Type

import { Type } from '@dxos/echo';

A type names a kind of entity and fixes its fields. You declare one at module scope as a class, and that class is both the runtime schema and the TypeScript type of its instances. Every type carries a DXN with a typename and a version, so two peers agree on what an object is without sharing code.

Declare an object type

makeObject takes the DXN first, then the fields. The optional second argument pipes annotations onto the schema, here the field that labels an object in lists.

import * as Schema from 'effect/Schema';
import { Annotation, DXN, Type } from '@dxos/echo';

class Project extends Type.makeObject<Project>(
  DXN.make('com.example.type.project', '0.1.0'),
)(
  { name: Schema.String, summary: Schema.optional(Schema.String) },
  Annotation.LabelAnnotation.set(['name']),
) {}

The last segment of the typename must be camelCase. A typename such as com.example.type.works-at fails to compile.

Declare a relation type

A relation type also names the types of its two endpoints. Relation covers making instances.

import * as Schema from 'effect/Schema';
import { DXN, Type } from '@dxos/echo';
import { Organization, Person } from './schema.ts';

export class WorksAt extends Type.makeRelation<WorksAt>(
  DXN.make('com.example.type.worksAt', '0.1.0'),
)({
  source: Person,
  target: Organization,
})({ role: Schema.String }) {}

Convert to and from JSON Schema

The JsonSchema module converts a type’s schema to JSON Schema and back. Type.makeObjectFromJsonSchema builds a type from JSON Schema, for a type that comes from a form, an agent or another system.

import * as Schema from 'effect/Schema';
import { JsonSchema, Type } from '@dxos/echo';
import { Organization } from './schema.ts';

// Out: a JSON Schema document for a form, an agent or another system.
const jsonSchema = JsonSchema.toJsonSchema(Type.getSchema(Organization));

// In: a type built from JSON Schema at runtime.
const Note = Type.makeObjectFromJsonSchema({
  typename: 'com.example.type.note',
  version: '0.1.0',
  jsonSchema: { type: 'object', properties: { title: { type: 'string' } } },
});

Change fields at runtime

A type stored in a space with db.addType can gain and lose fields after it exists; the change replicates like any write. The functions throw for a type that is not stored. Objects already made from the type keep their data. Use a new version and a migration instead when old objects need converting.

import * as Schema from 'effect/Schema';
import { Type } from '@dxos/echo';

const note = await db.addType(Note);
Type.addFields(note, { pinned: Schema.optional(Schema.Boolean) });
Type.removeFields(note, ['pinned']);

Inspect a type

These read the identity and schema of a type, which is what an agent or a generic UI works from.

import { Type } from '@dxos/echo';
import { Person } from './schema.ts';

const typename = Type.getTypename(Person); // 'com.example.type.person'
const version = Type.getVersion(Person); // '0.1.0'
const uri = Type.getURI(Person); // 'dxn:com.example.type.person:0.1.0'
const schema = Type.getSchema(Person);

Check the kind of a value

Type.isObject and Type.isRelation test a type. To test an instance, use the predicates in Obj and Relation.

import { Obj, Type } from '@dxos/echo';
import { Person } from './schema.ts';
import { WorksAt } from './works-at.ts';

const ada = Obj.make(Person, { name: 'Ada' });

Type.isObject(Person); // true
Type.isRelation(WorksAt); // true
Obj.isObject(ada); // true
Obj.instanceOf(Person, ada); // true

Members at a glance

Member	Summary
makeObject	Declare an object type
makeRelation	Declare a relation type with typed endpoints
makeObjectFromJsonSchema	Build an object type from JSON Schema
addFields updateFields removeFields	Change the fields of a type at runtime
getTypename getVersion getURI getMeta	Read the identity and metadata of a type
getSchema	The Effect Schema of a type
JsonSchema.toJsonSchema JsonSchema.toEffectSchema	Convert to and from JSON Schema
isObject isRelation isType	Test what kind of type a value is

The full list is in the API reference.

Related

• Defining types declares the tutorial app’s types.
• Types and schema explains types, versions and migrations.
• Annotation lists what a type can carry beyond its fields.