@dxos/echo 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/Obj.ts

@@ -5,22 +5,25 @@
 // @import-as-namespace
 
 import * as Effect from 'effect/Effect';
+import * as Equal from 'effect/Equal';
 import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
+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 } from '@dxos/util';
+import { assumeType, deepMapValues } from '@dxos/util';
 
 import type * as Database from './Database';
 import * as Entity from './Entity';
 import * as Err from './Err';
-import * as objInternal from './internal/Obj';
 import * as internal from './internal';
-import type * as Ref from './Ref';
+import { getProxyTarget, isProxy } from './internal/common/proxy/proxy-utils';
+import * as objInternal from './internal/Obj';
+import * as Ref from './Ref';
 import type * as Type from './Type';
 
 /**
@@ -81,8 +84,6 @@ export const Unknown: Type.Obj<Unknown> = Schema.Struct({
     }) as unknown as Type.Obj<Unknown>,
 );
 
-/**
-
 /**
  * Object with arbitrary properties.
  *
@@ -303,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>;
 
@@ -311,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, (p) => {
- *   p.name = 'Jane';
- *   p.age = 30;
+ * // 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);
 };
 
@@ -372,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.
@@ -386,8 +387,8 @@ 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, (p) => {
- *   Obj.setValue(p, ['addresses', 0, 'street'], '123 Main St');
+ * Obj.update(person, (obj) => {
+ *   Obj.setValue(obj, ['addresses', 0, 'street'], '123 Main St');
  * });
  * // Creates: person.addresses = [{ street: '123 Main St' }]
  * ```
@@ -469,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.
@@ -516,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;
 
@@ -524,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
@@ -533,8 +537,8 @@ export type Meta = internal.Meta;
  * const meta = Obj.getMeta(person);  // ReadonlyMeta
  *
  * // Mutable access inside change callback
- * Obj.change(person, (p) => {
- *   const meta = Obj.getMeta(p);     // ObjectMeta (mutable)
+ * Obj.update(person, (obj) => {
+ *   const meta = Obj.getMeta(obj);     // ObjectMeta (mutable)
  *   meta.tags ??= [];
  *   meta.tags.push('important');
  * });
@@ -558,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.
@@ -567,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.
@@ -576,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.
@@ -602,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.
@@ -617,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.
@@ -660,6 +664,123 @@ export const setParent = (entity: Unknown, parent: Any | undefined) => {
   assumeType<internal.InternalObjectProps>(entity);
   assumeType<internal.InternalObjectProps | undefined>(parent);
   entity[internal.ParentId] = parent;
+  return entity;
+};
+
+interface UpdateFromOptions<T> {
+  exclude?: (keyof T)[];
+  include?: (keyof T)[];
+}
+
+const valuesEqual = (left: unknown, right: unknown): boolean => {
+  if (left === right) {
+    return true;
+  }
+  if (left === null || right === null) {
+    return left === right;
+  }
+  if (typeof left !== 'object' || typeof right !== 'object') {
+    return Utils.structuralRegion(() => Equal.equals(left, right));
+  }
+  if (Ref.isRef(left) && Ref.isRef(right)) {
+    return left.dxn.toString() === right.dxn.toString();
+  }
+  if (Ref.isRef(left) || Ref.isRef(right)) {
+    return false;
+  }
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
+      return false;
+    }
+    for (let index = 0; index < left.length; index++) {
+      if (!valuesEqual(left[index], right[index])) {
+        return false;
+      }
+    }
+    return true;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    return false;
+  }
+  const leftRecord = left as Record<string, unknown>;
+  const rightRecord = right as Record<string, unknown>;
+  const keys = new Set([
+    ...Object.keys(leftRecord).filter((key) => key !== 'id'),
+    ...Object.keys(rightRecord).filter((key) => key !== 'id'),
+  ]);
+  for (const key of keys) {
+    const leftHas = Object.hasOwn(leftRecord, key);
+    const rightHas = Object.hasOwn(rightRecord, key);
+    const leftValue = leftHas ? leftRecord[key] : undefined;
+    const rightValue = rightHas ? rightRecord[key] : undefined;
+    if (!valuesEqual(leftValue, rightValue)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Breaks reactive proxies on assigned values so echo-db assignment accepts nested structs (same idea as link assignment).
+ */
+const prepareAssignValue = (value: unknown): unknown =>
+  deepMapValues(value, (nested, recurse) => {
+    if (nested === null || typeof nested !== 'object') {
+      return nested;
+    }
+    if (Ref.isRef(nested)) {
+      return nested;
+    }
+    if (Array.isArray(nested)) {
+      return recurse(nested);
+    }
+    if (isProxy(nested)) {
+      return recurse({ ...getProxyTarget(nested) });
+    }
+    return recurse(nested);
+  });
+
+/**
+ * For each key present on `source` (except `id`), assigns `target[key]` when the current value differs.
+ * 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.update` callback.
+ *
+ * @returns Whether any property was updated.
+ */
+export const updateFrom = <T extends Unknown>(
+  target: Mutable<T>,
+  source: T,
+  options?: UpdateFromOptions<T>,
+): boolean => {
+  assertArgument(isObject(target), 'Expected an echo object target.');
+  assertArgument(isObject(source), 'Expected an echo object source.');
+  let keys = Object.keys(source as Record<string, unknown>).filter((key) => key !== 'id');
+  if (options?.include !== undefined) {
+    const include = new Set(options.include.map((key) => String(key)));
+    keys = keys.filter((key) => include.has(key));
+  }
+  if (options?.exclude !== undefined) {
+    const exclude = new Set(options.exclude.map((key) => String(key)));
+    keys = keys.filter((key) => !exclude.has(key));
+  }
+  let updated = false;
+  const sourceRecord = source as Record<string, unknown>;
+  const targetRecord = target as Record<string, unknown>;
+  for (const key of keys) {
+    if (!Object.hasOwn(sourceRecord, key)) {
+      continue;
+    }
+    const nextValue = sourceRecord[key];
+    const prevValue = Object.hasOwn(targetRecord, key) ? targetRecord[key] : undefined;
+    if (valuesEqual(prevValue, nextValue)) {
+      continue;
+    }
+    targetRecord[key] = prepareAssignValue(nextValue) as never;
+    updated = true;
+  }
+  return updated;
 };
 
 //
@@ -691,7 +812,7 @@ export const toJSON = (entity: Unknown | Snapshot): JSON => objInternal.objectTo
  */
 export const fromJSON: (
   json: unknown,
-  options?: { refResolver?: Ref.Resolver; dxn?: DXN; database?: Database.Database },
+  options?: { refResolver?: Ref.Resolver; dxn?: DXN; database?: Database.Database; parent?: Unknown },
 ) => Promise<Unknown> = objInternal.objectFromJSON as any;
 
 /**

package/src/Query.test.ts

@@ -6,7 +6,7 @@ import * as Schema from 'effect/Schema';
 import { describe, expect, test } from 'vitest';
 
 import { QueryAST } from '@dxos/echo-protocol';
-import { DXN } from '@dxos/keys';
+import { DXN, ObjectId, SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 
 import * as Dataset from './Dataset';
@@ -523,7 +523,7 @@ describe('query api', () => {
           "from": {
             "_tag": "scope",
             "scope": {
-              "allQueuesFromSpaces": true,
+              "allFeedsFromSpaces": true,
             },
           },
           "query": {
@@ -560,12 +560,20 @@ describe('query api', () => {
       });
     });
 
-    test('Query.type(...).from(feed) sets queue scope', () => {
-      const feed = Feed.make({ name: 'test-feed' });
-      const queueDxn = DXN.parse('dxn:echo:test-space:test-queue');
-      Obj.change(feed, (mutable) => {
-        Obj.getMeta(mutable).keys.push({ source: Feed.DXN_KEY, id: queueDxn.toString() });
-      });
+    test('Query.type(...).from(feed) sets queue scope', async () => {
+      const spaceId = SpaceId.random();
+      const feedId = ObjectId.random();
+      const feedDXN = DXN.parse(`dxn:echo:${spaceId}:${feedId}`);
+      const feed = (await Obj.fromJSON(
+        {
+          '@type': 'dxn:type:org.dxos.type.feed:0.1.0',
+          id: feedId,
+          name: 'test-feed',
+        },
+        { dxn: feedDXN },
+      )) as Feed.Feed;
+
+      const expectedQueueDXN = new DXN(DXN.kind.QUEUE, ['data', spaceId, feedId]);
 
       const query = Query.type(TestSchema.Person).from(feed);
       Schema.validateSync(QueryAST.Query)(query.ast);
@@ -574,7 +582,7 @@ describe('query api', () => {
         from: {
           _tag: 'scope',
           scope: {
-            queues: [queueDxn.toString()],
+            feeds: [expectedQueueDXN.toString()],
           },
         },
         query: {
@@ -587,6 +595,60 @@ describe('query api', () => {
       });
     });
 
+    test('Query.from(non-feed) throws TypeError', () => {
+      const person = Obj.make(TestSchema.Person, { name: 'Fred' });
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(person as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(person as any)).toThrow(
+        /Query\.from\(\) expects Feed objects/,
+      );
+    });
+
+    test('Query.from(undefined) throws TypeError', () => {
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(undefined as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(undefined as any)).toThrow(
+        /Query\.from\(\) requires a valid data source argument/,
+      );
+    });
+
+    test('Query.from(null) throws TypeError', () => {
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(null as any)).toThrow(TypeError);
+      expect(() => Query.select(Filter.type(TestSchema.Person)).from(null as any)).toThrow(
+        /Query\.from\(\) requires a valid data source argument/,
+      );
+    });
+
+    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);
+      expect(pretty).toContain('Query.select');
+      expect(pretty).toContain('Filter.type');
+      expect(pretty).toContain('com.example.type.person');
+    });
+
+    test('Query.pretty handles complex queries', () => {
+      const query = Query.select(Filter.and(Filter.type(TestSchema.Person), Filter.id(ObjectId.random()))).limit(10);
+      const pretty = Query.pretty(query);
+      expect(pretty).toContain('Query.select');
+      expect(pretty).toContain('Filter.and');
+      expect(pretty).toContain('limit(10)');
+    });
+
     test.skip('chain', () => {
       // NOTE: Can't support props without type since they can't be inferred.
       // const f1: Filter<Person> = Filter.props({ name: 'Fred' });
@@ -622,11 +684,139 @@ describe('query api', () => {
     });
   });
 
+  describe('Filter.childOf', () => {
+    test('childOf with Ref', () => {
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
+      const filter = Filter.childOf(parentRef);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        parents: [parentDXN.toString()],
+        transitive: true,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf with object', () => {
+      const parent = Obj.make(TestSchema.Person, { name: 'Parent' });
+      const filter = Filter.childOf(parent);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        transitive: true,
+      });
+      expect(filter.ast.type === 'child-of' && filter.ast.parents.length).toBe(1);
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    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([Ref.fromDXN(dxn1), Ref.fromDXN(dxn2)]);
+
+      expect(filter.ast).toMatchObject({
+        type: 'child-of',
+        parents: [dxn1.toString(), dxn2.toString()],
+        transitive: true,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf with 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: [parentRef.dxn.toString()],
+        transitive: false,
+      });
+      Schema.validateSync(QueryAST.Filter)(filter.ast);
+    });
+
+    test('childOf in select query', () => {
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      const parentRef = Ref.fromDXN(parentDXN);
+      const query = Query.select(Filter.childOf(parentRef));
+
+      expect(query.ast).toMatchObject({
+        type: 'select',
+        filter: {
+          type: 'child-of',
+          parents: [parentDXN.toString()],
+          transitive: true,
+        },
+      });
+      Schema.validateSync(QueryAST.Query)(query.ast);
+    });
+
+    test('childOf combined with type filter', () => {
+      const parentDXN = DXN.fromSpaceAndObjectId(SpaceId.random(), ObjectId.random());
+      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({
+        type: 'select',
+        filter: {
+          type: 'and',
+          filters: [
+            { type: 'object', typename: 'dxn:type:com.example.type.person:0.1.0' },
+            { type: 'child-of', parents: [parentDXN.toString()], transitive: true },
+          ],
+        },
+      });
+    });
+
+    test('childOf pretty-prints correctly', () => {
+      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', () => {
     test('Filter.or(Filter.typename(...))', () => {
       const filter = Filter.or(Filter.typename('com.example.type.person'));
       // TODO(dmaretskyi): Give vitest type-tests a try.
       const _isAssignable: Obj.Unknown = null as any as Filter.Type<typeof filter>;
     });
+
+    test('Filter.pretty returns human-readable filter string', () => {
+      const filter = Filter.type(TestSchema.Person, { name: 'Fred' });
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.type');
+      expect(pretty).toContain('com.example.type.person');
+    });
+
+    test('Filter.pretty handles complex filters', () => {
+      const filter = Filter.and(Filter.type(TestSchema.Person), Filter.id(ObjectId.random()));
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.and');
+      expect(pretty).toContain('Filter.type');
+    });
+
+    test('Filter.pretty handles or filters', () => {
+      const filter = Filter.or(Filter.type(TestSchema.Person), Filter.type(TestSchema.Organization));
+      const pretty = Filter.pretty(filter);
+      expect(pretty).toContain('Filter.or');
+    });
   });
 });