Mutating objects

By the end of this page the app will add, edit and remove records, and you will watch a record change.

Before you start

An object you make with Obj.make exists only in memory until you add it to a database. db.add starts tracking it: from then on the database stores every change and sends it to the space’s other peers.

A tracked object is read like any other, but it is changed only inside Obj.update. The callback gets a mutable view of the object. Each update is one change, which peers apply whole, and which notifies subscribers once.

Writes are local. db.add and Obj.update return once the change is in the local database, and replication runs after. Two peers that change the same object concurrently both keep their edits: ECHO merges them field by field.

1. Write the app’s add functions. Each takes the database and the props of one type, and returns the tracked object.

   export const addOrganization = (db: Database.Database, props: { name: string; website?: string }) =>
     db.add(Obj.make(Organization, props));
   
   export const addPerson = (
     db: Database.Database,
     { employer, ...props }: { name: string; email?: string; employer?: Organization },
   ) => db.add(Obj.make(Person, { ...props, ...(employer && { employer: Ref.make(employer) }) }));
   
   export const addEvent = (
     db: Database.Database,
     { attendees = [], ...props }: { title: string; description?: string; attendees?: Person[] },
   ) => db.add(Obj.make(Event, { ...props, attendees: attendees.map((person) => Ref.make(person)) }));
   
   

   A person’s employer is passed as an object and stored as a reference to it.

2. Add records.

   const northwind = addOrganization(db, { name: 'Northwind Labs' });
   const ada = addPerson(db, { name: 'Ada Lovelace', employer: northwind });
   
   

3. Watch a record. Obj.subscribe calls back after each change to the object, and returns a function that stops the subscription.

   const employers: (string | undefined)[] = [];
   const unsubscribe = Obj.subscribe(ada, () => {
     employers.push(ada.employer?.peek()?.name);
   });
   
   

4. Change a record. The app moves a person to another organization in one update, and its form writes whatever fields the reader changed.

   /** Moves a person to another organization. */
   export const changeEmployer = (person: Person, employer: Organization) =>
     Obj.update(person, (person) => {
       person.employer = Ref.make(employer);
     });
   
   /** Writes the values a form returns onto a record, one field at a time. */
   export const updateRecord = (record: Obj.Unknown, values: Record<string, unknown>) =>
     Obj.update(record, (record) => {
       for (const [key, value] of Object.entries(values)) {
         Obj.setValue(record, [key], value);
       }
     });
   
   

   const halcyon = addOrganization(db, { name: 'Halcyon Robotics' });
   changeEmployer(ada, halcyon);
   
   

   The subscriber from step 3 has run, so employers holds 'Halcyon Robotics'.

5. Remove a record.

   export const removeRecord = (db: Database.Database, record: Obj.Unknown) => db.remove(record);
   
   

   removeRecord(db, ada);
   
   

   Note

   ECHO does not delete a removed object at once. It marks the object as removed and keeps it in the change history until the next epoch, so a peer that wrote while offline can still reconcile its changes when it reconnects.

Try it

Select a record and change it in the form, or press New to add one of the chosen type. The × on a row removes it. A person’s employer is a picker of the organizations in the space.

What you can do now

You can add records to a database, change them inside Obj.update, watch them change, and remove them.

Next

Querying: list the records, sorted and searched.