@dxos/echo 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/Migration.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Schema from 'effect/Schema';
+
+import { type DXN } from '@dxos/keys';
+
+import type * as Database from './Database';
+import type * as Entity from './Entity';
+import { getSchemaDXN } from './internal';
+
+type DefineObjectMigrationOptions<From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext> = {
+  from: From;
+  to: To;
+  /**
+   * Pure function that converts the old object data to the new object data.
+   */
+  // TODO(dmaretskyi): `id` should not be a part of the schema.
+  transform: (
+    from: Schema.Schema.Type<From>,
+    context: ObjectMigrationContext,
+  ) => Promise<Omit<Schema.Schema.Type<To>, 'id' | Entity.KindId>>;
+
+  /**
+   * Callback that is called after the object is migrated. Called for every object that is migrated.
+   *
+   * NOTE: Database mutations performed in this callback are not guaranteed to be idempotent.
+   *       If multiple peers run the migration separately, the effects may be applied multiple times.
+   */
+  onMigration: (params: OnMigrateProps<From, To>) => Promise<void>;
+};
+
+/**
+ * Context passed to object migration callbacks.
+ */
+export type ObjectMigrationContext = {
+  db: Database.Database;
+};
+
+type OnMigrateProps<From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext> = {
+  before: Schema.Schema.Type<From>;
+  object: Schema.Schema.Type<To>;
+  db: Database.Database;
+};
+
+/**
+ * Definition of a migration from one object schema version to another.
+ */
+export type ObjectMigration = {
+  fromType: DXN;
+  toType: DXN;
+  fromSchema: Schema.Schema.AnyNoContext;
+  toSchema: Schema.Schema.AnyNoContext;
+  transform: (from: unknown, context: ObjectMigrationContext) => Promise<unknown>;
+  onMigration: (params: OnMigrateProps<any, any>) => Promise<void>;
+};
+
+/**
+ * Define a migration between two object schemas.
+ *
+ * @example
+ * ```ts
+ * const migration = Migration.define({
+ *   from: ContactV1,
+ *   to: ContactV2,
+ *   transform: async (from) => ({ name: `${from.firstName} ${from.lastName}` }),
+ *   onMigration: async () => {},
+ * });
+ * ```
+ */
+export const define = <From extends Schema.Schema.AnyNoContext, To extends Schema.Schema.AnyNoContext>(
+  options: DefineObjectMigrationOptions<From, To>,
+): ObjectMigration => {
+  const fromType = getSchemaDXN(options.from);
+  if (!fromType) {
+    throw new Error('Invalid from schema');
+  }
+  const toType = getSchemaDXN(options.to);
+  if (!toType) {
+    throw new Error('Invalid to schema');
+  }
+
+  return {
+    fromType,
+    toType,
+    fromSchema: options.from,
+    toSchema: options.to,
+    transform: options.transform as any,
+    onMigration: options.onMigration as any,
+  };
+};

package/src/Obj.test.ts

@@ -117,7 +117,7 @@ describe('Obj', () => {
 
     test('returns keys from reactive object and snapshot', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-      Obj.change(obj, (obj) => {
+      Obj.update(obj, (obj) => {
         const meta = Obj.getMeta(obj);
         meta.keys.push({ source: SOURCE, id: 'key-1' });
         meta.keys.push({ source: SOURCE, id: 'key-2' });
@@ -166,7 +166,7 @@ describe('Obj', () => {
 
       const cloned = Obj.clone(original);
 
-      Obj.change(original, (original) => {
+      Obj.update(original, (original) => {
         original.name = 'Bob';
       });
 
@@ -206,7 +206,7 @@ describe('Obj', () => {
       expect(cloned.employer?.target).toBe(person.employer?.target);
 
       // Modifying the referenced object affects both
-      Obj.change(employer, (employer) => {
+      Obj.update(employer, (employer) => {
         employer.name = 'Updated DXOS';
       });
 
@@ -234,7 +234,7 @@ describe('Obj', () => {
       expect(cloned.employer?.target?.name).toBe(employer.name);
 
       // Modifying the original referenced object does not affect the clone
-      Obj.change(employer, (employer) => {
+      Obj.update(employer, (employer) => {
         employer.name = 'Updated DXOS';
       });
 
@@ -333,7 +333,7 @@ describe('Obj', () => {
       expect(cloned.address?.coordinates.lng).toBe(-122.4194);
 
       // Modifying nested properties should be independent
-      Obj.change(person, (person) => {
+      Obj.update(person, (person) => {
         person.address!.city = 'New York';
       });
 
@@ -366,7 +366,7 @@ describe('Obj', () => {
       expect(cloned.tasks?.[2]?.target).not.toBe(task3);
 
       // Modifying original tasks should not affect cloned ones
-      Obj.change(task1, (task1) => {
+      Obj.update(task1, (task1) => {
         task1.title = 'Updated Task 1';
       });
 
@@ -449,7 +449,7 @@ describe('Obj', () => {
     test('returns false when values already match', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Acme', properties: { region: 'EU' } });
       const source = Obj.make(TestSchema.Organization, { name: 'Acme', properties: { region: 'EU' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(false);
       });
     });
@@ -463,7 +463,7 @@ describe('Obj', () => {
         name: 'New',
         properties: { a: '2', b: '3' },
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.name).toBe('New');
@@ -487,7 +487,7 @@ describe('Obj', () => {
         employer: Ref.make(orgB),
         address: { city: 'Portland', state: 'OR', zip: '97201', coordinates: { lat: 45.5, lng: -122.6 } },
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.employer?.dxn.toString()).toBe(Ref.make(orgB).dxn.toString());
@@ -510,7 +510,7 @@ describe('Obj', () => {
         email: 'bob@x.test',
         tasks: [Ref.make(t1), Ref.make(t3)],
       });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source)).toBe(true);
       });
       expect(target.tasks?.map((r) => r.dxn.toString())).toEqual(source.tasks?.map((r) => r.dxn.toString()));
@@ -519,7 +519,7 @@ describe('Obj', () => {
     test('respects include option', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Keep', properties: { x: '1' } });
       const source = Obj.make(TestSchema.Organization, { name: 'Drop', properties: { x: '2' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source, { include: ['properties'] })).toBe(true);
       });
       expect(target.name).toBe('Keep');
@@ -529,7 +529,7 @@ describe('Obj', () => {
     test('respects exclude option', () => {
       const target = Obj.make(TestSchema.Organization, { name: 'Old', properties: { x: '1' } });
       const source = Obj.make(TestSchema.Organization, { name: 'New', properties: { x: '2' } });
-      Obj.change(target, (target) => {
+      Obj.update(target, (target) => {
         expect(Obj.updateFrom(target, source, { exclude: ['name'] })).toBe(true);
       });
       expect(target.name).toBe('Old');

package/src/Obj.ts

@@ -13,7 +13,7 @@ import * as Utils from 'effect/Utils';
 
 import type { ForeignKey } from '@dxos/echo-protocol';
 import { createJsonPath } from '@dxos/effect';
-import { assertArgument } from '@dxos/invariant';
+import { assertArgument, invariant } from '@dxos/invariant';
 import { type DXN, ObjectId } from '@dxos/keys';
 import { assumeType, deepMapValues } from '@dxos/util';
 
@@ -304,7 +304,7 @@ export const clone: <T extends Unknown>(obj: T, opts?: CloneOptions) => T = objI
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of an object within `Obj.change`.
+ * Used to provide a mutable view of an object within `Obj.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -312,33 +312,33 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo object within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Obj.change` will throw
+ * when the callback completes. Direct mutations outside of `Obj.update` will throw
  * an error for echo objects.
  *
  * This function also works with nested objects within echo objects (e.g., Template structs)
  * that are reactive at runtime.
  *
- * @param obj - The echo object to mutate. Use `Relation.change` for relations.
+ * @param obj - The echo object to mutate. Use `Relation.update` for relations.
  * @param callback - The callback that performs mutations on the object.
  *
  * @example
  * ```ts
  * const person = Obj.make(Person, { name: 'John', age: 25 });
  *
- * // Mutate within Obj.change
- * Obj.change(person, (obj) => {
+ * // Mutate within Obj.update
+ * Obj.update(person, (obj) => {
  *   obj.name = 'Jane';
  *   obj.age = 30;
  * });
  * // ONE notification fires here
  *
  * // Direct mutation throws
- * person.name = 'Bob'; // Error: Cannot modify outside Obj.change()
+ * person.name = 'Bob'; // Error: Cannot modify outside Obj.update()
  * ```
  *
- * Note: Only accepts objects. Use `Relation.change` for relations.
+ * Note: Only accepts objects. Use `Relation.update` for relations.
  */
-export const change = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(obj: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(obj, callback);
 };
 
@@ -373,7 +373,7 @@ export const getValue = (obj: Unknown | Snapshot, path: readonly (string | numbe
  * whether to initialize nested data as an empty object or array.
  *
  * Similar to lodash.set and setDeep from @dxos/util, but schema-aware.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -387,7 +387,7 @@ export const getValue = (obj: Unknown | Snapshot, path: readonly (string | numbe
  * ```ts
  * const person = Obj.make(Person, { name: 'John' });
  * // Person schema has: addresses: Schema.Array(Address)
- * Obj.change(person, (obj) => {
+ * Obj.update(person, (obj) => {
  *   Obj.setValue(obj, ['addresses', 0, 'street'], '123 Main St');
  * });
  * // Creates: person.addresses = [{ street: '123 Main St' }]
@@ -470,16 +470,19 @@ export const getDXN = (entity: Unknown | Snapshot): DXN => {
 /**
  * @returns The DXN of the object's type.
  * @example dxn:com.example.type.person:1.0.0
+ * @throws If the object is missing its type (corrupted object).
  */
-// TODO(wittjosiah): Narrow types.
-export const getTypeDXN: (obj: unknown | undefined) => DXN | undefined = internal.getTypeDXN as any;
+export const getTypeDXN = (obj: Unknown | Snapshot): DXN => {
+  const type = internal.getTypeDXN(obj);
+  invariant(type != null, 'Corrupted object: missing type.');
+  return type;
+};
 
 /**
  * Get the schema of the object.
  * Returns the branded ECHO schema used to create the object.
  */
-// TODO(wittjosiah): Narrow types.
-export const getSchema: (obj: unknown | undefined) => Type.AnyEntity | undefined = internal.getSchema as any;
+export const getSchema: (obj: Unknown | Snapshot) => Type.AnyEntity | undefined = internal.getSchema as any;
 
 /**
  * @returns The typename of the object's type.
@@ -517,7 +520,7 @@ export const Meta = internal.MetaId;
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Obj.getMeta` inside an `Obj.change` callback.
+ * Mutable meta type returned by `Obj.getMeta` inside an `Obj.update` callback.
  */
 export type Meta = internal.Meta;
 
@@ -525,7 +528,7 @@ export type Meta = internal.Meta;
 // TODO(dmaretskyi): Allow returning undefined.
 /**
  * Get the metadata for an object.
- * Returns mutable meta when passed a mutable object (inside `Obj.change` callback).
+ * Returns mutable meta when passed a mutable object (inside `Obj.update` callback).
  * Returns read-only meta when passed a regular object or snapshot.
  *
  * @example
@@ -534,7 +537,7 @@ export type Meta = internal.Meta;
  * const meta = Obj.getMeta(person);  // ReadonlyMeta
  *
  * // Mutable access inside change callback
- * Obj.change(person, (obj) => {
+ * Obj.update(person, (obj) => {
  *   const meta = Obj.getMeta(obj);     // ObjectMeta (mutable)
  *   meta.tags ??= [];
  *   meta.tags.push('important');
@@ -559,7 +562,7 @@ export const getKeys: {
 
 /**
  * Delete all keys from the object for the specified source.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -568,7 +571,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -577,7 +580,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
 
 /**
  * Remove a tag from the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -603,7 +606,7 @@ export const getLabel = (entity: Unknown | Snapshot): string | undefined => inte
 
 /**
  * Set the label of the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -618,7 +621,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the object.
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -741,7 +744,7 @@ const prepareAssignValue = (value: unknown): unknown =>
  * References are compared by target DXN; other values use Effect `Equal.equals` inside a structural region,
  * with recursive comparison for arrays and plain object-shaped property bags (excluding `id`).
  *
- * Must be called within an `Obj.change` callback.
+ * Must be called within an `Obj.update` callback.
  *
  * @returns Whether any property was updated.
  */

package/src/Query.test.ts

@@ -617,6 +617,22 @@ describe('query api', () => {
       );
     });
 
+    test('Query.pretty surfaces debugLabel from options', () => {
+      const query = Query.select(Filter.type(TestSchema.Person)).debugLabel('my-label');
+      expect(Query.pretty(query)).toContain('debugLabel');
+      expect(Query.pretty(query)).toContain('"my-label"');
+    });
+
+    test('Query.debugLabel merges onto existing options clause', () => {
+      const query = Query.select(Filter.type(TestSchema.Person))
+        .options({ deleted: 'exclude' })
+        .debugLabel('timer-probe');
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('deleted');
+      expect(pretty).toContain('debugLabel');
+      expect(pretty).toContain('"timer-probe"');
+    });
+
     test('Query.pretty returns human-readable query string', () => {
       const query = Query.select(Filter.type(TestSchema.Person, { name: 'Fred' }));
       const pretty = Query.pretty(query);
@@ -669,9 +685,10 @@ describe('query api', () => {
   });
 
   describe('Filter.childOf', () => {
-    test('childOf with DXN', () => {
+    test('childOf with Ref', () => {
       const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const filter = Filter.childOf(parentDxn);
+      const parentRef = Ref.fromDXN(parentDxn);
+      const filter = Filter.childOf(parentRef);
 
       expect(filter.ast).toMatchObject({
         type: 'child-of',
@@ -693,10 +710,10 @@ describe('query api', () => {
       Schema.validateSync(QueryAST.Filter)(filter.ast);
     });
 
-    test('childOf with array of DXNs', () => {
+    test('childOf with array of Refs', () => {
       const dxn1 = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
       const dxn2 = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const filter = Filter.childOf([dxn1, dxn2]);
+      const filter = Filter.childOf([Ref.fromDXN(dxn1), Ref.fromDXN(dxn2)]);
 
       expect(filter.ast).toMatchObject({
         type: 'child-of',
@@ -707,12 +724,12 @@ describe('query api', () => {
     });
 
     test('childOf with transitive=false', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const filter = Filter.childOf(parentDxn, { transitive: false });
+      const parentRef = Ref.fromDXN(DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random()));
+      const filter = Filter.childOf(parentRef, { transitive: false });
 
       expect(filter.ast).toMatchObject({
         type: 'child-of',
-        parents: [parentDxn.toString()],
+        parents: [parentRef.dxn.toString()],
         transitive: false,
       });
       Schema.validateSync(QueryAST.Filter)(filter.ast);
@@ -720,7 +737,8 @@ describe('query api', () => {
 
     test('childOf in select query', () => {
       const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const query = Query.select(Filter.childOf(parentDxn));
+      const parentRef = Ref.fromDXN(parentDxn);
+      const query = Query.select(Filter.childOf(parentRef));
 
       expect(query.ast).toMatchObject({
         type: 'select',
@@ -735,7 +753,8 @@ describe('query api', () => {
 
     test('childOf combined with type filter', () => {
       const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.childOf(parentDxn)));
+      const parentRef = Ref.fromDXN(parentDxn);
+      const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.childOf(parentRef)));
 
       Schema.validateSync(QueryAST.Query)(query.ast);
       expect(query.ast).toMatchObject({
@@ -751,12 +770,26 @@ describe('query api', () => {
     });
 
     test('childOf pretty-prints correctly', () => {
-      const parentDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
-      const filter = Filter.childOf(parentDxn);
+      const parentRef = Ref.fromDXN(DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random()));
+      const filter = Filter.childOf(parentRef);
       const pretty = Filter.pretty(filter);
       expect(pretty).toContain('Filter.childOf');
       expect(pretty).toContain('transitive: true');
     });
+
+    test('childOf with mixed objects and Refs', () => {
+      const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
+      const refDxn = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(refDxn);
+      const filter = Filter.childOf([parent, parentRef]);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        transitive: true,
+      });
+      expect(filter.ast.type === 'child-of' && filter.ast.parents.length).toBe(2);
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
   });
 
   describe('Filter', () => {

package/src/Query.ts

@@ -207,6 +207,11 @@ export interface Query<T> {
    * Add options to a query.
    */
   'options'(options: QueryAST.QueryOptions): Query<T>;
+
+  /**
+   * Attach a diagnostic label for logs and tooling (execution semantics unchanged).
+   */
+  'debugLabel'(label: string): Query<T>;
 }
 
 export type Any = Query<any>;
@@ -429,6 +434,21 @@ class QueryClass implements Any {
       options,
     });
   }
+
+  debugLabel(label: string): Any {
+    if (this.ast.type === 'options') {
+      return new QueryClass({
+        type: 'options',
+        query: this.ast.query,
+        options: { ...this.ast.options, debugLabel: label },
+      });
+    }
+    return new QueryClass({
+      type: 'options',
+      query: this.ast,
+      options: { debugLabel: label },
+    });
+  }
 }
 
 export const is = (value: unknown): value is Any => {

package/src/Relation.ts

@@ -237,7 +237,9 @@ export const getSource = <T extends Unknown | Snapshot>(relation: T): SourceOf<T
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(relation);
   const obj = (relation as internal.InternalObjectProps)[internal.RelationSourceId];
-  invariant(obj !== undefined, `Invalid source: ${relation.id}`);
+  if (obj === undefined) {
+    throw new Error(`Relation source could not be resolved.`);
+  }
   return obj as SourceOf<T>;
 };
 
@@ -250,7 +252,9 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
   assertArgument(isRelation(relation), 'Expected a relation');
   assumeType<internal.InternalObjectProps>(relation);
   const obj = (relation as internal.InternalObjectProps)[internal.RelationTargetId];
-  invariant(obj !== undefined, `Invalid target: ${relation.id}`);
+  if (obj === undefined) {
+    throw new Error(`Relation target could not be resolved.`);
+  }
   return obj as TargetOf<T>;
 };
 
@@ -260,7 +264,7 @@ export const getTarget = <T extends Unknown | Snapshot>(relation: T): TargetOf<T
 
 /**
  * Makes all properties mutable recursively.
- * Used to provide a mutable view of a relation within `Relation.change`.
+ * Used to provide a mutable view of a relation within `Relation.update`.
  */
 export type Mutable<T> = internal.Mutable<T>;
 
@@ -268,10 +272,10 @@ export type Mutable<T> = internal.Mutable<T>;
  * Perform mutations on an echo relation within a controlled context.
  *
  * All mutations within the callback are batched and trigger a single notification
- * when the callback completes. Direct mutations outside of `Relation.change` will throw
+ * when the callback completes. Direct mutations outside of `Relation.update` will throw
  * an error for echo relations.
  *
- * @param relation - The echo relation to mutate. Use `Obj.change` for objects.
+ * @param relation - The echo relation to mutate. Use `Obj.update` for objects.
  * @param callback - The callback that performs mutations on the relation.
  *
  * @example
@@ -282,15 +286,15 @@ export type Mutable<T> = internal.Mutable<T>;
  *   role: 'Engineer',
  * });
  *
- * // Mutate within Relation.change
- * Relation.change(worksFor, (obj) => {
+ * // Mutate within Relation.update
+ * Relation.update(worksFor, (obj) => {
  *   obj.role = 'Senior Engineer';
  * });
  * ```
  *
- * Note: Only accepts relations. Use `Obj.change` for objects.
+ * Note: Only accepts relations. Use `Obj.update` for objects.
  */
-export const change = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
+export const update = <T extends Unknown>(relation: T, callback: internal.ChangeCallback<T>): void => {
   internal.change(relation, callback);
 };
 
@@ -333,7 +337,7 @@ export const getValue = (rel: Unknown | Snapshot, path: readonly (string | numbe
 
 /**
  * Set a deeply nested property on a relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -395,13 +399,13 @@ export const Meta = internal.MetaId;
 export type ReadonlyMeta = internal.ReadonlyMeta;
 
 /**
- * Mutable meta type returned by `Relation.getMeta` inside a `Relation.change` callback.
+ * Mutable meta type returned by `Relation.getMeta` inside a `Relation.update` callback.
  */
 export type Meta = internal.Meta;
 
 /**
  * Get the metadata for a relation.
- * Returns mutable meta when passed a mutable relation (inside `Relation.change` callback).
+ * Returns mutable meta when passed a mutable relation (inside `Relation.update` callback).
  * Returns read-only meta when passed a regular relation or snapshot.
  */
 // TODO(wittjosiah): When passed a Snapshot, should return a snapshot of meta, not the live meta proxy.
@@ -419,7 +423,7 @@ export const getKeys = (entity: Unknown | Snapshot, source: string): ForeignKey[
 
 /**
  * Delete all keys from the relation for the specified source.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -428,7 +432,7 @@ export const deleteKeys = (entity: Mutable<Unknown>, source: string): void => in
 
 /**
  * Add a tag to the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -437,7 +441,7 @@ export const addTag = (entity: Mutable<Unknown>, tag: string): void => internal.
 
 /**
  * Remove a tag from the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -462,7 +466,7 @@ export const getLabel = (entity: Unknown | Snapshot): string | undefined => inte
 
 /**
  * Set the label of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.
@@ -477,7 +481,7 @@ export const getDescription = (entity: Unknown | Snapshot): string | undefined =
 
 /**
  * Set the description of the relation.
- * Must be called within a `Relation.change` callback.
+ * Must be called within a `Relation.update` callback.
  *
  * NOTE: TypeScript's structural typing allows readonly objects to be passed to `Mutable<T>`
  * parameters, so there is no compile-time error. Enforcement is runtime-only.

package/src/index.ts

@@ -9,13 +9,16 @@ export { DXN } from '@dxos/keys';
 export * as Annotation from './Annotation';
 export * as Database from './Database';
 export * as Entity from './Entity';
+// TODO(burdon): Rename to Error (less problematic than Obj/Object).
 export * as Err from './Err';
 export * as Feed from './Feed';
 export * as Filter from './Filter';
 export * as Format from './Format';
 export * as Hypergraph from './Hypergraph';
+export * as Json from './Json';
 export * as JsonSchema from './JsonSchema';
 export * as Key from './Key';
+export * as Migration from './Migration';
 export * as Obj from './Obj';
 export * as Order from './Order';
 export * as Query from './Query';