Module: devtools¶

Development tools library.

Purpose¶

The devtools library provides APIs to help support common use-cases when building applications on top of Ceramic, notably as a complement to the runtime Glaze libraries. It is meant to be used by developers in scripts or other tools such as the CLI, not as a runtime library.

The ModelManager class notably allows developers to create, update and deploy data models to be used with the DataModel runtime.

Installation¶

npm install --dev @glazed/devtools

Common use-cases¶

Add an existing schema to a model¶

An existing schema can be added using the useDeployedSchema method, as shown below.

import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'

const ceramic = new CeramicClient()
const manager = new ModelManager({ ceramic })

// Set the alias (human-readable name) and stream reference (stream or commit ID or URL) of the
// schema to add to the model. The schema must be already present on the Ceramic node.
await manager.useDeployedSchema('MySchema', 'ceramic://k2...ab')

The useDeployedDefinition and useDeployedTile methods can be used similarly to add definitions and tiles to the model.

Create and add a schema to a model¶

Using the createSchema method allows to create the schema on the Ceramic node and add it to the model. Note that using this method creates a new schema every time it is called, therefore generating different stream IDs.

import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'

const ceramic = new CeramicClient()
const manager = new ModelManager({ ceramic })

// Set the alias (human-readable name) and JSON schema contents
await manager.createSchema('MySchema', {
  $schema: 'http://json-schema.org/draft-07/schema#',
  title: 'MySchema',
  type: 'object',
  properties: {
    ...
  },
})

The createDefinition and createTile methods can be used similarly to add definitions and tiles to the model.

Export a model to JSON¶

A managed model can be serialized to JSON, making it portable and reusable, with the toJSON method.

import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'

const ceramic = new CeramicClient()
const manager = new ModelManager({ ceramic })

await manager.useDeployedSchema('MySchema', 'ceramic://k2...ab')
const encodedModel = await manager.toJSON()

Import a model from JSON¶

A managed model serialized using the toJSON method can be deserialized with the fromJSON static method.

import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'

const ceramic = new CeramicClient()
const manager = new ModelManager({ ceramic })

await manager.useDeployedSchema('MySchema', 'ceramic://k2...ab')
const encodedModel = await manager.toJSON()

// The `clonedManager` instance will contain the same model as the `manager` instance
const clonedManager = ModelManager.fromJSON({ ceramic, model: encodedModel })

Deploy a model to Ceramic¶

In order to use a model at runtime in an application, it is important to ensure all the streams used by the model are present in the Ceramic network. This can be achieved by calling the deploy method, which returns the aliases of the model that can be used at runtime by a DataModel instance.

import { readFile, writeFile } from 'node:fs/promises'
import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'

// The encoded model could be imported from the file system for example
const bytes = await readFile(new URL('encoded-model.json', import.meta.url))
const encodedModel = JSON.parse(bytes.toString())

const ceramic = new CeramicClient()
const manager = ModelManager.fromJSON({ ceramic, model: encodedModel })

// The deployed model aliases could then be exported to be used at runtime
const aliases = await manager.deploy()
await writeFile(new URL('model-aliases.json', import.meta.url), JSON.stringify(aliases))

Use existing models¶

A model can be created by combining other models. For example, using the models for the CIP-19 "Basic Profile", CIP-21 "Crypto Accounts" and CIP-23 "Also Known As" specifications provided by the following packages:

npm install --dev @datamodels/identity-profile-basic @datamodels/identity-accounts-crypto @datamodels/identity-accounts-web

import { CeramicClient } from '@ceramicnetwork/http-client'
import { ModelManager } from '@glazed/devtools'
import { model as basicProfileModel } from '@datamodels/identity-profile-basic'
import { model as cryptoAccountsModel } from '@datamodels/identity-accounts-crypto'
import { model as webAccountsModel } from '@datamodels/identity-accounts-web'

const ceramic = new CeramicClient()
const manager = new ModelManager({ ceramic })

// Add the imported models to the manager
manager.addJSONModel(basicProfileModel)
manager.addJSONModel(cryptoAccountsModel)
manager.addJSONModel(webAccountsModel)

// Once deployed, the streams are available on the Ceramic node
await manager.deploy()

Classes¶

ModelManager

Type aliases¶

FromJSONParams¶

Ƭ FromJSONParams: Object

Type declaration¶

Name	Type	Description
`ceramic`	`CeramicApi`	Ceramic client instance
`model`	`EncodedManagedModel`	`JSON-encoded managed model` to use

ModelManagerConfig¶

Ƭ ModelManagerConfig: Object

Type declaration¶

Name	Type	Description
`ceramic`	`CeramicApi`	Ceramic client instance
`model?`	`ManagedModel`	Optional `managed model` to use

Functions¶

deployEncodedModel¶

▸ deployEncodedModel(ceramic, model): Promise<ModelAliases>

Deploy a JSON-encoded managed model to the given Ceramic node.

Parameters¶

Name	Type
`ceramic`	`CeramicApi`
`model`	`EncodedManagedModel`

Returns¶

Promise<ModelAliases>

deployModel¶

▸ deployModel(ceramic, model, createOpts?, commitOpts?): Promise<ModelAliases>

Deploy a managed model to the given Ceramic node.

Parameters¶

Name	Type
`ceramic`	`CeramicApi`
`model`	`ManagedModel`<`DagJWSResult`>
`createOpts?`	`CreateOpts`
`commitOpts?`	`UpdateOpts`

Returns¶

Promise<ModelAliases>

isSecureSchema¶

▸ isSecureSchema<T>(schema): boolean

Type parameters¶

Name	Type
`T`	`Record`<`string`, `any`>

Parameters¶

Name	Type
`schema`	`UncheckedJSONSchemaType`<`T`, `false`>

Returns¶

boolean