Model

A Model is one content type in a schema, such as Post. You usually get one with Model.find and use it to create items. You can also define new models in code with Model.create.

import { Model, AmbiguousModelError } from '@seedprotocol/sdk'

Call client.init() (or render SeedClientGate) before using Model. The examples use the blog schema from Your first schema.

Model.find

Finds a model by name or ID, loading it from the local database if it isn't loaded yet, and waits for it to be ready.

static find(options: {
  modelName?: string
  schemaName?: string
  modelFileId?: string
  waitForReady?: boolean
  readyTimeout?: number
  hold?: boolean
}): Promise<Model | undefined>

Parameters

Returns

The Model, or undefined if no model matches (or you passed neither modelName nor modelFileId).

If you pass modelName without schemaName and two loaded schemas both define that model, find throws an AmbiguousModelError.

Example

const Post = await Model.find({ modelName: 'Post', schemaName: 'blog' })
if (!Post) throw new Error('Post model is not loaded')

const post = await Post.create({ title: 'Hello, world!' })

model.create (new items)

Creates an item of this model. This is the instance method; for defining a new model, see Model.create.

create(values: Partial<ItemData> & Record<string, any>): Promise<Item<any>>

Parameters

The model's name, schema name and the model itself are passed along for you, so the item is created in the right schema even when another schema has a model with the same name.

Returns

A Promise that resolves to the new Item once it's written to the local database and ready (up to 15 seconds). Throws Cannot create item: model name is not set on this Model instance if the model has no name, and EntityUnloadedError if the model was destroyed or evicted (see unload()).

Example

const Author = await Model.find({ modelName: 'Author', schemaName: 'blog' })
const Post = await Model.find({ modelName: 'Post', schemaName: 'blog' })
if (!Author || !Post) throw new Error('blog schema is not loaded')

const author = await Author.create({ name: 'Jane Doe' })
const post = await Post.create({
  title: 'Hello, world!',
  published: false,
  author: author.seedLocalId,
})

Values passed to create() are validated first, as in Item.create: an unknown key or an invalid value rejects with ItemCreateValidationError, and nothing is written. Unlike Item.create, there's no option to skip the check. Values read back as strings; see What you get back.

Instance properties

for (const property of Post.properties) {
  console.log(property.name, property.dataType) // 'title' 'Text', …
}

waitForReady({ timeout }) resolves once status is 'ready'. It rejects with the load's error, or after timeout milliseconds (default 15000). While status is 'error', entityLoadError(model) returns that error.

properties and description can't be assigned: both throw. A model's description from the schema file isn't loaded onto the instance.

Model.all

Lists models as Model instances.

static all(
  schemaName?: string,
  options?: { waitForReady?: boolean; readyTimeout?: number; hold?: boolean },
): Promise<Model[]>

const models = await Model.all('blog')
console.log(models.map((model) => model.name)) // ['Post', 'Author']

Without schemaName, the result includes the SDK's internal models (Seed, Version, Metadata, Image, File, Html) along with yours.

Model.create (new models)

Defines a new model in a schema. It never returns an existing model: if the schema already has a model with this name, the new one gets a numbered name such as Post 1, then Post 2. To get a model from your schema file, use Model.find.

static create(
  modelName: string,
  schemaNameOrSchema: string | Schema,
  options?: {
    properties?: { [propertyName: string]: PropertyDefinition }
    modelFileId?: string
    registerWithSchema?: boolean
    waitForReady?: true
    readyTimeout?: number
    hold?: boolean
  },
): Promise<Model>

The real options type is wider: properties values are typed any, there's a deprecated id alias for modelFileId, and passing { waitForReady: false } returns a Model instead of a Promise.

Parameters

Example

import { Schema, Model } from '@seedprotocol/sdk'

const blog = await Schema.create('blog')

const Tag = await Model.create('Tag', blog, {
  properties: {
    label: { dataType: 'Text', required: true },
    color: { dataType: 'Text' },
  },
})

const news = await Tag.create({ label: 'news' })

The model and its properties are written to the local database as a draft of the schema. They aren't added to your seed.schema.json. A model created in code but missing from config.schema stays in the local database across restarts, with the validation rules of its properties; see Validation.

When it waits for ready (the default), Model.create resolves only once the properties you passed exist, so model.properties is filled straight after the await. It rejects if they can't be created, or aren't created within readyTimeout.

Model.create refuses a name that publishes as a reserved Solidity word before it makes a model: the model's name, or a property name in options.properties. Model.create('Event', blog) rejects with Model "Event" publishes as "event", …, and a property view with Property "view" publishes as "view", …. With waitForReady: false the call throws instead. Nothing stays in schema.models or Model.getByName.

Model.getByName and AmbiguousModelError

Model.getByName is a synchronous lookup in the loaded models, with no waiting.

static getByName(
  modelName: string,
  schemaName?: string,
  options?: { hold?: boolean },
): Model | undefined

It takes no hold unless options.hold is true. With schemaName, it returns that schema's model or undefined. Without it, it returns the only loaded model with that name, or throws AmbiguousModelError when models in several schemas share the name. Model.find, Item.create and other name-only lookups throw the same error.

AmbiguousModelError extends Error and adds:

try {
  Model.getByName('Post')
} catch (error) {
  if (error instanceof AmbiguousModelError) {
    console.log(error.schemaNames) // ['blog', 'shop']
  }
}

The fix is always to pass the schema name: Model.find({ modelName: 'Post', schemaName: 'blog' }).

Other static methods

hold defaults to false on each of them.

The class also exposes cache and bookkeeping helpers used by the SDK and @seedprotocol/react (getByNameAsync, resolveAsync, findByModelType, getCachedInstancesForSchema, cachedModelNames, findUniqueModelName, evictForSchema, refreshPropertiesForDbId). You don't need them in app code.

Instance methods

A model stays cached and running until it, or its schema, is destroyed or evicted, whether or not anything holds it; client.stop() evicts every cached model. A hold only counts your use of the instance. Once a model is destroyed or evicted, create(), reload() and assigning modelName throw EntityUnloadedError, whose message names the model and says to look it up again with Model.find. EntityUnloadedError is exported from the main entry.

Editing a model

Assigning model.modelName = 'Article' renames the model. The SDK updates its lookup tables at once and renames the model in the local database in the background. A failure isn't thrown: it's logged with console.warn and kept on model.lastSaveError. The schema is marked as edited.

To add or change properties, use ModelProperty.

Conflicts

Model saves don't detect conflicts. The model's conflict check always passes, because the models table has no updatedAt column to compare. The ConflictError you may see comes from the schema: see Saving and conflicts.

Related

• Creating items: create items and set relations
• Modeling relations
• Schema, ModelProperty and Item
• React model hooks: useModel, useModels, useCreateModel