Defining types

By the end of this page the app will have its three types: organizations, the people who work at them, and the events they attend.

Before you start

A type is a schema with a name. ECHO uses the schema three ways:

• The compiler uses it to check the fields of every object you create.
• ECHO uses it to check what it stores, and to send the type to peers that have not seen it.
• Code can read it at run time. The app’s forms, table and graph are built from the schemas rather than written per type.

The schema is an Effect Schema. The name is a DXN: a reverse-domain name and a version, such as com.example.type.person at 0.1.0. Use a domain you control, since the name is global.

A field can hold a reference to another object, with Ref.Ref(Type). A reference stores the target’s identity, not a copy, so the graph stays consistent when the target changes.

1. Declare an organization. Type.makeObject takes the name and the schema, and returns a class that is both the schema and the TypeScript type of its instances.

   export class Organization extends Type.makeObject<Organization>(DXN.make('com.example.type.organization', '0.1.0'))(
     Schema.Struct({
       name: Schema.String,
       website: Schema.optional(Format.URL),
     }).pipe(Annotation.IconAnnotation.set({ icon: 'ph--buildings--regular', hue: 'amber' })),
   ) {}
   
   

   Format.URL marks the website as a URL, so a form offers a URL field for it. IconAnnotation gives the type an icon and a hue, which the app’s list and graph use.

2. Point a person at an organization. employer is a reference to an Organization.

   export class Person extends Type.makeObject<Person>(DXN.make('com.example.type.person', '0.1.0'))(
     Schema.Struct({
       name: Schema.String,
       email: Schema.optional(Format.Email),
       employer: Schema.optional(Ref.Ref(Organization)),
     }).pipe(Annotation.IconAnnotation.set({ icon: 'ph--user--regular', hue: 'cyan' })),
   ) {}
   
   

3. Point an event at many people. A list of references gives an event its attendees. LabelAnnotation says which field names an event, since it has a title rather than a name.

   export class Event extends Type.makeObject<Event>(DXN.make('com.example.type.event', '0.1.0'))(
     Schema.Struct({
       title: Schema.String,
       description: Schema.optional(Schema.String),
       attendees: Schema.optional(Schema.Array(Ref.Ref(Person))),
     }).pipe(
       Annotation.IconAnnotation.set({ icon: 'ph--calendar-dots--regular', hue: 'green' }),
       Annotation.LabelAnnotation.set(['title']),
     ),
   ) {}
   
   

4. List the types. The client is given this list when the app starts, in Installation.

   export const types = [Organization, Person, Event];
   
   

5. Create instances. Obj.make takes the props the schema allows, and Ref.make makes a reference to an object.

   const northwind = Obj.make(Organization, { name: 'Northwind Labs', website: 'https://northwind.example' });
   const ada = Obj.make(Person, { name: 'Ada Lovelace', employer: Ref.make(northwind) });
   const review = Obj.make(Event, { title: 'Quarterly review', attendees: [Ref.make(ada)] });
   
   

   Leave out a person’s name and the compiler rejects the call.

6. Follow a reference. peek reads the target, if it is loaded, without waiting.

   // The reference holds the organization's identity, not a copy of it.
   const employer = ada.employer?.peek();
   console.log(employer?.name);
   
   

Try it

The form beside the list is built from the selected type’s schema: a URL field for a website, a picker of organizations for an employer, and a list of people for an event’s attendees. Choose a type to see its form, or a record to see its values. Editing comes on the next page.

What you can do now

You can declare object types with references between them, give a type an icon and a label, and create objects that the compiler checks against their schema.

Next

Mutating objects: add, change and remove the app’s records.