@dxos/echo 0.8.4-main.ef1bc66f44 → 0.8.4-main.effb148878

package/src/Migration.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Schema from 'effect/Schema';
+
+import { type URI } from '@dxos/keys';
+
+import type * as Database from './Database';
+import type * as Entity from './Entity';
+import { MetaId, type ObjectMeta, getSchemaURI } from './internal';
+import * as Type from './Type';
+
+/**
+ * Result returned by a migration's `transform` callback.
+ * The data shape matches the target schema; the optional `[Obj.Meta]` symbol key lets the
+ * transform update the object's meta (e.g. `key` / `version`) atomically with the data swap.
+ */
+type MigrationSchemaInput = Type.AnyEntity;
+
+type MigrationInstanceType<S> = S extends Type.AnyEntity
+  ? Type.InstanceType<S>
+  : S extends Schema.Schema.AnyNoContext
+    ? Schema.Schema.Type<S>
+    : never;
+
+export type TransformResult<To> = Omit<MigrationInstanceType<To>, 'id' | Entity.KindId> & {
+  [MetaId]?: Partial<ObjectMeta>;
+};
+
+type DefineObjectMigrationOptions<From extends MigrationSchemaInput, To extends MigrationSchemaInput> = {
+  from: From;
+  to: To;
+  /**
+   * Pure function that converts the old object data to the new object data.
+   *
+   * The returned object may include an optional `[Obj.Meta]` entry to update the object's meta
+   * (e.g. registry `key` / `version`) atomically with the data swap.
+   */
+  // TODO(dmaretskyi): `id` should not be a part of the schema.
+  transform: (from: MigrationInstanceType<From>, context: ObjectMigrationContext) => Promise<TransformResult<To>>;
+
+  /**
+   * 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, To> = {
+  before: MigrationInstanceType<From>;
+  object: MigrationInstanceType<To>;
+  db: Database.Database;
+};
+
+/**
+ * Definition of a migration from one object schema version to another.
+ */
+export type ObjectMigration = {
+  fromType: URI.URI;
+  toType: URI.URI;
+  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 MigrationSchemaInput, To extends MigrationSchemaInput>(
+  options: DefineObjectMigrationOptions<From, To>,
+): ObjectMigration => {
+  const fromSchema = Type.getSchema(options.from);
+  const toSchema = Type.getSchema(options.to);
+  const fromType = getSchemaURI(fromSchema);
+  if (!fromType) {
+    throw new Error('Invalid from schema');
+  }
+  const toType = getSchemaURI(toSchema);
+  if (!toType) {
+    throw new Error('Invalid to schema');
+  }
+
+  return {
+    fromType,
+    toType,
+    fromSchema,
+    toSchema,
+    transform: options.transform as any,
+    onMigration: options.onMigration as any,
+  };
+};

package/src/Obj.test.ts

@@ -2,12 +2,13 @@
 // Copyright 2026 DXOS.org
 //
 
-import { describe, expectTypeOf, test } from 'vitest';
+import { describe, expectTypeOf, test, expect } from 'vitest';
 
 import * as Entity from './Entity';
 import { SnapshotKindId } from './internal';
 import * as Obj from './Obj';
 import * as Ref from './Ref';
+import * as Relation from './Relation';
 import { TestSchema } from './testing';
 
 describe('Obj', () => {
@@ -19,6 +20,10 @@ describe('Obj', () => {
       // Snapshot has SnapshotKindId, not KindId.
       expect(snapshot[SnapshotKindId]).toBe(Entity.Kind.Object);
       expect((snapshot as any)[Entity.KindId]).toBeUndefined();
+      expect(Obj.isSnapshot(snapshot)).toBe(true);
+      expect(Relation.isSnapshot(snapshot)).toBe(false);
+      expect(Entity.isEntity(snapshot)).toBe(false);
+      expect(Entity.isSnapshot(snapshot)).toBe(true);
 
       // Snapshot has same id and properties.
       expect(snapshot.id).toBe(obj.id);
@@ -37,12 +42,12 @@ describe('Obj', () => {
       const snapshot = Obj.getSnapshot(obj);
 
       // getDXN - works with both.
-      expect(Obj.getDXN(obj)).toBeDefined();
-      expect(Obj.getDXN(snapshot)).toBeDefined();
+      expect(Obj.getURI(obj)).toBeDefined();
+      expect(Obj.getURI(snapshot)).toBeDefined();
 
       // getTypename - works with both.
-      expect(Obj.getTypename(obj)).toBe('example.com/type/Person');
-      expect(Obj.getTypename(snapshot)).toBe('example.com/type/Person');
+      expect(Obj.getTypename(obj)).toBe('com.example.type.person');
+      expect(Obj.getTypename(snapshot)).toBe('com.example.type.person');
 
       // getMeta - works with both.
       expect(Obj.getMeta(obj)).toBeDefined();
@@ -75,6 +80,47 @@ describe('Obj', () => {
       expect(SnapshotKindId in snapshot).toBe(true);
       expect(Entity.KindId in snapshot).toBe(false);
     });
+
+    test('getSnapshot preserves parent', ({ expect }) => {
+      const parent = Obj.make(TestSchema.Organization, { name: 'parent' });
+      const child = Obj.make(TestSchema.Person, { name: 'child' });
+      Obj.setParent(child, parent);
+
+      const snapshot = Obj.getSnapshot(child);
+
+      expect(Obj.getParent(child)).toBe(parent);
+      expect(Obj.getParent(snapshot)).toBe(parent);
+    });
+  });
+
+  describe('snapshotOf', () => {
+    test('returns true for snapshot of matching schema', ({ expect }) => {
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+      const snapshot = Obj.getSnapshot(obj);
+
+      expect(Obj.snapshotOf(TestSchema.Person, snapshot)).toBe(true);
+      expect(Obj.snapshotOf(TestSchema.Organization, snapshot)).toBe(false);
+    });
+
+    test('returns false for reactive object', ({ expect }) => {
+      const obj = Obj.make(TestSchema.Person, { name: 'Test' });
+
+      expect(Obj.snapshotOf(TestSchema.Person, obj)).toBe(false);
+    });
+
+    test('returns false for plain object with matching shape', ({ expect }) => {
+      const plain = { id: 'test', name: 'Test' };
+
+      expect(Obj.snapshotOf(TestSchema.Person, plain)).toBe(false);
+    });
+
+    test('curried form works', ({ expect }) => {
+      const snapshot = Obj.getSnapshot(Obj.make(TestSchema.Person, { name: 'Test' }));
+      const isPersonSnapshot = Obj.snapshotOf(TestSchema.Person);
+
+      expect(isPersonSnapshot(snapshot)).toBe(true);
+      expect(isPersonSnapshot({})).toBe(false);
+    });
   });
 
   describe('getKeys', () => {
@@ -82,8 +128,8 @@ describe('Obj', () => {
 
     test('returns keys from reactive object and snapshot', ({ expect }) => {
       const obj = Obj.make(TestSchema.Person, { name: 'Test' });
-      Obj.change(obj, (o) => {
-        const meta = Obj.getMeta(o);
+      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' });
         meta.keys.push({ source: 'other', id: 'key-3' });
@@ -131,8 +177,8 @@ describe('Obj', () => {
 
       const cloned = Obj.clone(original);
 
-      Obj.change(original, (p) => {
-        p.name = 'Bob';
+      Obj.update(original, (original) => {
+        original.name = 'Bob';
       });
 
       expect(original.name).toBe('Bob');
@@ -171,8 +217,8 @@ describe('Obj', () => {
       expect(cloned.employer?.target).toBe(person.employer?.target);
 
       // Modifying the referenced object affects both
-      Obj.change(employer, (org) => {
-        org.name = 'Updated DXOS';
+      Obj.update(employer, (employer) => {
+        employer.name = 'Updated DXOS';
       });
 
       expect(cloned.employer?.target?.name).toBe('Updated DXOS');
@@ -199,8 +245,8 @@ describe('Obj', () => {
       expect(cloned.employer?.target?.name).toBe(employer.name);
 
       // Modifying the original referenced object does not affect the clone
-      Obj.change(employer, (org) => {
-        org.name = 'Updated DXOS';
+      Obj.update(employer, (employer) => {
+        employer.name = 'Updated DXOS';
       });
 
       expect(cloned.employer?.target?.name).toBe('DXOS');
@@ -294,12 +340,12 @@ describe('Obj', () => {
       expect(cloned.address?.city).toBe('San Francisco');
       expect(cloned.address?.state).toBe('CA');
       expect(cloned.address?.zip).toBe('94102');
-      expect(cloned.address?.coordinates.lat).toBe(37.7749);
-      expect(cloned.address?.coordinates.lng).toBe(-122.4194);
+      expect(cloned.address?.coordinates?.lat).toBe(37.7749);
+      expect(cloned.address?.coordinates?.lng).toBe(-122.4194);
 
       // Modifying nested properties should be independent
-      Obj.change(person, (p) => {
-        p.address!.city = 'New York';
+      Obj.update(person, (person) => {
+        person.address!.city = 'New York';
       });
 
       expect(cloned.address?.city).toBe('San Francisco');
@@ -331,8 +377,8 @@ describe('Obj', () => {
       expect(cloned.tasks?.[2]?.target).not.toBe(task3);
 
       // Modifying original tasks should not affect cloned ones
-      Obj.change(task1, (t) => {
-        t.title = 'Updated Task 1';
+      Obj.update(task1, (task1) => {
+        task1.title = 'Updated Task 1';
       });
 
       expect(cloned.tasks?.[0]?.target?.title).toBe('Task 1');
@@ -370,7 +416,7 @@ describe('Obj', () => {
       const cloned = Obj.clone(person);
 
       expect(Obj.instanceOf(TestSchema.Person, cloned)).toBe(true);
-      expect(Obj.getSchema(cloned)).toBe(Obj.getSchema(person));
+      expect(Obj.getType(cloned)).toBe(Obj.getType(person));
     });
   });
 
@@ -409,4 +455,96 @@ describe('Obj', () => {
       expectTypeOf<Obj.Any>().toMatchTypeOf<Obj.Unknown>();
     });
   });
+
+  describe('Obj.updateFrom', () => {
+    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.update(target, (target) => {
+        expect(Obj.updateFrom(target, source)).toBe(false);
+      });
+    });
+
+    test('updates scalar and nested record fields on Organization', () => {
+      const target = Obj.make(TestSchema.Organization, {
+        name: 'Old',
+        properties: { a: '1' },
+      });
+      const source = Obj.make(TestSchema.Organization, {
+        name: 'New',
+        properties: { a: '2', b: '3' },
+      });
+      Obj.update(target, (target) => {
+        expect(Obj.updateFrom(target, source)).toBe(true);
+      });
+      expect(target.name).toBe('New');
+      expect(target.properties).toEqual({ a: '2', b: '3' });
+    });
+
+    test('compares employer refs by DXN and updates Person fields', () => {
+      const orgA = Obj.make(TestSchema.Organization, { name: 'A' });
+      const orgB = Obj.make(TestSchema.Organization, { name: 'B' });
+      const target = Obj.make(TestSchema.Person, {
+        name: 'Ann',
+        username: 'ann',
+        email: 'ann@x.test',
+        employer: Ref.make(orgA),
+        address: { city: 'X', state: 'Y', zip: '1', coordinates: { lat: 0, lng: 0 } },
+      });
+      const source = Obj.make(TestSchema.Person, {
+        name: 'Ann',
+        username: 'ann',
+        email: 'ann@x.test',
+        employer: Ref.make(orgB),
+        address: { city: 'Portland', state: 'OR', zip: '97201', coordinates: { lat: 45.5, lng: -122.6 } },
+      });
+      Obj.update(target, (target) => {
+        expect(Obj.updateFrom(target, source)).toBe(true);
+      });
+      expect(target.employer?.uri.toString()).toBe(Ref.make(orgB).uri.toString());
+      expect(target.address?.city).toBe('Portland');
+    });
+
+    test('updates array of task refs when DXNs differ', () => {
+      const t1 = Obj.make(TestSchema.Task, { title: 'One' });
+      const t2 = Obj.make(TestSchema.Task, { title: 'Two' });
+      const t3 = Obj.make(TestSchema.Task, { title: 'Three' });
+      const target = Obj.make(TestSchema.Person, {
+        name: 'Bob',
+        username: 'bob',
+        email: 'bob@x.test',
+        tasks: [Ref.make(t1), Ref.make(t2)],
+      });
+      const source = Obj.make(TestSchema.Person, {
+        name: 'Bob',
+        username: 'bob',
+        email: 'bob@x.test',
+        tasks: [Ref.make(t1), Ref.make(t3)],
+      });
+      Obj.update(target, (target) => {
+        expect(Obj.updateFrom(target, source)).toBe(true);
+      });
+      expect(target.tasks?.map((r) => r.uri)).toEqual(source.tasks?.map((r) => r.uri));
+    });
+
+    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.update(target, (target) => {
+        expect(Obj.updateFrom(target, source, { include: ['properties'] })).toBe(true);
+      });
+      expect(target.name).toBe('Keep');
+      expect(target.properties).toEqual({ x: '2' });
+    });
+
+    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.update(target, (target) => {
+        expect(Obj.updateFrom(target, source, { exclude: ['name'] })).toBe(true);
+      });
+      expect(target.name).toBe('Old');
+      expect(target.properties).toEqual({ x: '2' });
+    });
+  });
 });