@dxos/echo 0.8.4-main.c85a9c8dae → 0.8.4-main.cb12b3f963

package/src/Json.test.ts

@@ -0,0 +1,175 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { DXN, ObjectId } from '@dxos/keys';
+import { safeStringify } from '@dxos/util';
+
+import * as Database from './Database';
+import * as Json from './Json';
+
+/** Mint a random ECHO object id usable as both a stub-db key and a DXN payload. */
+const newId = (): string => ObjectId.random();
+
+/** Build a fake encoded ref for a local-space object id. */
+const encodeRef = (id: string): { '/': string } => ({ '/': DXN.fromLocalObjectId(id).toString() });
+
+/** Minimal stub: `createRefReplacer` only touches `db.getObjectById`. */
+const makeStubDb = (objects: Record<string, unknown>): Database.Database => {
+  return {
+    getObjectById: (id: string) => objects[id],
+  } as unknown as Database.Database;
+};
+
+/**
+ * Run a value through the replacer's public contract — `JSON.stringify(value, replacer)` —
+ * then re-parse the result so tests can assert on plain JS shapes. This mirrors the way
+ * the JSON highlighter invokes the replacer in production.
+ */
+const stringifyWith = (replacer: Json.JsonReplacer, value: unknown): unknown =>
+  JSON.parse(JSON.stringify(value, replacer));
+
+describe('createRefReplacer', () => {
+  test('passes plain values through unchanged', () => {
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    const subject = { a: 1, b: 'two', c: [3, { d: 4 }] };
+    expect(stringifyWith(replacer, subject)).toEqual(subject);
+  });
+
+  test('inlines refs at default depth (1)', () => {
+    const id = newId();
+    const target = { name: 'inlined' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [id]: target }) });
+    const subject = { ref: encodeRef(id) };
+    expect(stringifyWith(replacer, subject)).toEqual({ ref: target });
+  });
+
+  test('does not follow refs when depth is 0', () => {
+    const id = newId();
+    const target = { name: 'inlined' };
+    const ref = encodeRef(id);
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [id]: target }), depth: 0 });
+    expect(stringifyWith(replacer, { ref })).toEqual({ ref });
+  });
+
+  test('inlines refs across multiple levels up to depth', () => {
+    const innerId = newId();
+    const middleId = newId();
+    const inner = { name: 'inner' };
+    const middle = { ref: encodeRef(innerId) };
+    const outer = { ref: encodeRef(middleId) };
+    const db = makeStubDb({ [innerId]: inner, [middleId]: middle });
+
+    expect(stringifyWith(Json.createRefReplacer({ db, depth: 1 }), outer)).toEqual({
+      ref: { ref: encodeRef(innerId) },
+    });
+
+    expect(stringifyWith(Json.createRefReplacer({ db, depth: 2 }), outer)).toEqual({
+      ref: { ref: inner },
+    });
+  });
+
+  test('leaves refs encoded when the target is missing in the db', () => {
+    const ref = encodeRef(newId());
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref })).toEqual({ ref });
+  });
+
+  test('leaves non-DXN single-key { "/": string } objects untouched', () => {
+    // Same `{ '/': string }` shape is used by other IPLD-style refs (e.g. CIDs); those should
+    // not crash the replacer and should pass through verbatim.
+    const cidLike = { '/': 'bafybeibwzifw7izxykxz' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: cidLike })).toEqual({ ref: cidLike });
+  });
+
+  test('leaves malformed dxn strings untouched', () => {
+    const malformed = { '/': 'dxn:not-a-real-dxn' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: malformed })).toEqual({ ref: malformed });
+  });
+
+  test('leaves non-echo dxns untouched (e.g. type DXN)', () => {
+    // Type DXNs share the `dxn:` prefix but `asEchoDXN()` returns undefined.
+    const typeRef = { '/': DXN.fromTypename('com.example.Thing').toString() };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    expect(stringifyWith(replacer, { ref: typeRef })).toEqual({ ref: typeRef });
+  });
+
+  test('inlines refs inside arrays', () => {
+    const idA = newId();
+    const idB = newId();
+    const a = { name: 'a' };
+    const b = { name: 'b' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [idA]: a, [idB]: b }) });
+    expect(stringifyWith(replacer, { items: [encodeRef(idA), encodeRef(idB), { plain: true }] })).toEqual({
+      items: [a, b, { plain: true }],
+    });
+  });
+
+  test('walks nested objects recursively', () => {
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }) });
+    const subject = { outer: { mid: { ref: encodeRef(innerId) } } };
+    expect(stringifyWith(replacer, subject)).toEqual({ outer: { mid: { ref: inner } } });
+  });
+
+  test('a single replacer invocation does not recurse on its own', () => {
+    // The replacer is per-call; JSON.stringify drives the tree walk. Calling the replacer
+    // directly on a cyclic input must therefore return without touching the cycle.
+    const replacer = Json.createRefReplacer({ db: makeStubDb({}) });
+    const node: any = { name: 'self' };
+    node.self = node;
+
+    expect(() => replacer('', node)).not.toThrow();
+    expect(replacer('', node)).toBe(node);
+  });
+
+  test('invokes `toJSON` on resolved targets so refs in the target are re-walked', () => {
+    // Simulates the ECHO-object branch: `db.getObjectById` returns a live proxy, the replacer
+    // calls `.toJSON()` to get the encoded form, then continues walking that form. A ref nested
+    // inside the target should be inlined when there's depth budget remaining.
+    const outerId = newId();
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const target = {
+      toJSON: () => ({ nestedRef: encodeRef(innerId) }),
+    };
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [outerId]: target, [innerId]: inner }), depth: 2 });
+    expect(stringifyWith(replacer, { ref: encodeRef(outerId) })).toEqual({
+      ref: { nestedRef: inner },
+    });
+  });
+
+  test('depth budget counts ref hops, not tree depth — a ref deep in a plain tree still resolves', () => {
+    // A ref nested under arbitrarily many plain objects is one ref hop from the root, so
+    // `depth: 1` resolves it. `depth: 0` leaves it encoded.
+    const innerId = newId();
+    const inner = { name: 'inner' };
+    const subject = { a: { b: { c: { d: { ref: encodeRef(innerId) } } } } };
+
+    const inlining = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }), depth: 1 });
+    expect(stringifyWith(inlining, subject)).toEqual({ a: { b: { c: { d: { ref: inner } } } } });
+
+    const passthrough = Json.createRefReplacer({ db: makeStubDb({ [innerId]: inner }), depth: 0 });
+    expect(stringifyWith(passthrough, subject)).toEqual(subject);
+  });
+
+  test('inlines refs when invoked through safeStringify (production path)', () => {
+    // `JsonHighlighter` runs the replacer through `@dxos/util/safeStringify`, whose inner
+    // wrapper short-circuits the root call without forwarding it to the user's filter. The
+    // replacer must therefore work on a per-call basis — not as a one-shot root tree walk.
+    // This regression-tests that integration: the `content` ref must inline.
+    const targetId = newId();
+    const target = { toJSON: () => ({ name: 'README content' }) };
+    const document = { id: '01ABC', name: 'README', content: encodeRef(targetId) };
+
+    const replacer = Json.createRefReplacer({ db: makeStubDb({ [targetId]: target }) });
+    const out = JSON.parse(safeStringify(document, replacer, 0)!);
+
+    expect(out).toEqual({ id: '01ABC', name: 'README', content: { name: 'README content' } });
+  });
+});

package/src/Json.ts

@@ -0,0 +1,102 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { DXN } from '@dxos/keys';
+
+import * as Database from './Database';
+import * as Obj from './Obj';
+
+/**
+ * `JSON.stringify` replacer signature.
+ *
+ * Defined here (rather than re-imported from a UI package) so other ECHO-aware utilities can
+ * share a stable signature without creating a dependency edge into the UI tree.
+ */
+export type JsonReplacer = (key: string, value: any) => any;
+
+export type CreateRefReplacerOptions = {
+  db: Database.Database;
+  /** How many ref hops to follow. `0` leaves all refs as-is. Default: `1`. */
+  depth?: number;
+};
+
+const isEncodedRef = (value: unknown): value is { '/': string } =>
+  typeof value === 'object' &&
+  value !== null &&
+  Object.keys(value as object).length === 1 &&
+  typeof (value as { '/': unknown })['/'] === 'string';
+
+const toJson = (obj: Obj.Any): unknown => (typeof (obj as any).toJSON === 'function' ? (obj as any).toJSON() : obj);
+
+/**
+ * Returns a {@link JsonReplacer} that inlines ECHO ref objects (`{ "/": "dxn:echo:..." }`) up to
+ * `depth` ref hops. Beyond that depth refs are left in their encoded form.
+ *
+ * Implemented as a per-call `JSON.stringify` replacer (not a one-shot tree walk at root) so it
+ * composes with wrappers like `safeStringify` that intercept the root call. JSON.stringify
+ * already drives the recursion; we only need to (a) detect a ref at the current callback,
+ * (b) resolve and return the target if hop budget remains, and (c) tag the returned object
+ * with its hop count so children know how far in they are.
+ *
+ * The hop count is tracked per-object via a `WeakMap`: a ref-resolved target's children inherit
+ * `parentHops + 1`; a regular intermediate object's children inherit `parentHops`. This makes the
+ * budget count *ref hops*, not tree depth — a ref deep in a tree still resolves once when
+ * `depth >= 1`.
+ *
+ * Note: ECHO objects' `toJSON` runs before the replacer is invoked, so by the time we see a
+ * value refs are already encoded as `{ "/": "dxn:..." }`.
+ */
+export const createRefReplacer = ({ db, depth = 1 }: CreateRefReplacerOptions): JsonReplacer => {
+  // Per-object hop count. Set when we return an object (via ref resolution or pass-through) so
+  // the child callbacks (which carry that object as `this`) can read it.
+  const hops = new WeakMap<object, number>();
+
+  return function (this: any, key: string, value: any) {
+    // Hop count for this call: hops at the parent, or 0 for the root.
+    const parentHops = this && typeof this === 'object' ? (hops.get(this) ?? 0) : 0;
+    if (isEncodedRef(value)) {
+      if (parentHops >= depth) {
+        return value;
+      }
+
+      // The `{ '/': string }` shape is shared with non-DXN IPLD-style refs (e.g. CIDs);
+      // an unparseable string would otherwise crash the whole `JSON.stringify`.
+      // Treat any parse miss as "leave as-is" rather than propagating.
+      const dxnString = value['/'];
+      if (!dxnString.startsWith('dxn:')) {
+        return value;
+      }
+
+      let echoId: string | undefined;
+      try {
+        echoId = DXN.parse(dxnString).asEchoDXN()?.echoId;
+      } catch {
+        return value;
+      }
+
+      if (!echoId) {
+        return value;
+      }
+      const target = db.getObjectById(echoId);
+      if (!target) {
+        return value;
+      }
+
+      const encoded = toJson(target);
+      if (encoded != null && typeof encoded === 'object') {
+        // Children of the resolved target are one hop deeper.
+        hops.set(encoded as object, parentHops + 1);
+      }
+      return encoded;
+    }
+
+    // Pass-through object: children inherit the parent's hop count (this branch doesn't burn
+    // budget).
+    if (value != null && typeof value === 'object') {
+      hops.set(value, parentHops);
+    }
+
+    return value;
+  };
+};

package/src/JsonSchema.ts

@@ -2,23 +2,25 @@
 // Copyright 2025 DXOS.org
 //
 
+// @import-as-namespace
+
 import type * as Schema from 'effect/Schema';
 
-import * as internal from './internal';
+import * as jsonSchemaInternal from './internal/JsonSchema';
 
 /**
  * Decode JSON Schema to Effect Schema.
  */
-export const toEffectSchema = internal.toEffectSchema;
+export const toEffectSchema = jsonSchemaInternal.toEffectSchema;
 
 /**
  * Encode Effect Schema to JSON Schema.
  */
-export const toJsonSchema = internal.toJsonSchema;
+export const toJsonSchema = jsonSchemaInternal.toJsonSchema;
 
 /**
  * Serializable JsonSchema type definition.
  */
-export type JsonSchema = internal.JsonSchemaType;
+export type JsonSchema = jsonSchemaInternal.JsonSchemaType;
 
-export const JsonSchema: Schema.Schema<internal.JsonSchemaType> = internal.JsonSchemaType;
+export const JsonSchema: Schema.Schema<jsonSchemaInternal.JsonSchemaType> = jsonSchemaInternal.JsonSchemaType;

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

@@ -2,7 +2,7 @@
 // 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';
@@ -46,8 +46,8 @@ describe('Obj', () => {
       expect(Obj.getDXN(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();
@@ -117,8 +117,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' });
@@ -166,8 +166,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');
@@ -206,8 +206,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');
@@ -234,8 +234,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');
@@ -333,8 +333,8 @@ describe('Obj', () => {
       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');
@@ -366,8 +366,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');
@@ -444,4 +444,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?.dxn.toString()).toBe(Ref.make(orgB).dxn.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.dxn.toString())).toEqual(source.tasks?.map((r) => r.dxn.toString()));
+    });
+
+    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' });
+    });
+  });
 });