@dxos/echo 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

package/src/internal/Obj/set-value.test.ts

@@ -17,7 +17,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address).toBeDefined();
     expect(person.address?.city).toBe('NYC');
@@ -30,7 +30,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['fields', 0, 'label'], 'Phone'));
+    Obj.update(person, (person) => Obj.setValue(person, ['fields', 0, 'label'], 'Phone'));
 
     expect(Array.isArray(person.fields)).toBe(true);
     expect(person.fields?.[0].label).toBe('Phone');
@@ -45,7 +45,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['address', 'coordinates', 'lat'], 40.7128));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'coordinates', 'lat'], 40.7128));
 
     expect(person.address).toBeDefined();
     expect(person.address?.coordinates).toBeDefined();
@@ -69,10 +69,10 @@ describe('Obj.setValue', () => {
 
     const container = Obj.make(Container, { name: 'box' });
 
-    Obj.change(container, (obj) => {
-      Obj.setValue(obj, ['items', 0, 'value'], 10);
-      Obj.setValue(obj, ['items', 1, 'value'], 20);
-      Obj.setValue(obj, ['items', 2, 'value'], 30);
+    Obj.update(container, (container) => {
+      Obj.setValue(container, ['items', 0, 'value'], 10);
+      Obj.setValue(container, ['items', 1, 'value'], 20);
+      Obj.setValue(container, ['items', 2, 'value'], 30);
     });
 
     expect(container.items).toHaveLength(3);
@@ -88,7 +88,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['age'], 25));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 25));
 
     expect(person.age).toBe(25);
   });
@@ -100,7 +100,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address).toBeDefined();
     expect(person.address?.city).toBe('NYC');
@@ -114,8 +114,8 @@ describe('Obj.setValue', () => {
     });
 
     let result: any;
-    Obj.change(person, (obj) => {
-      result = Obj.setValue(obj, ['age'], 30);
+    Obj.update(person, (person) => {
+      result = Obj.setValue(person, ['age'], 30);
     });
 
     expect(result).toBe(30);
@@ -129,7 +129,7 @@ describe('Obj.setValue', () => {
       age: 25,
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['age'], 30));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 30));
 
     expect(person.age).toBe(30);
   });
@@ -142,7 +142,7 @@ describe('Obj.setValue', () => {
       address: { city: 'Boston', state: 'MA', coordinates: {} },
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['address', 'city'], 'NYC'));
+    Obj.update(person, (person) => Obj.setValue(person, ['address', 'city'], 'NYC'));
 
     expect(person.address?.city).toBe('NYC');
     expect(person.address?.state).toBe('MA');
@@ -160,11 +160,11 @@ describe('Obj.setValue', () => {
 
     const matrix = Obj.make(Matrix, {});
 
-    Obj.change(matrix, (obj) => {
-      Obj.setValue(obj, ['values', 0, 0], 1);
-      Obj.setValue(obj, ['values', 0, 1], 2);
-      Obj.setValue(obj, ['values', 1, 0], 3);
-      Obj.setValue(obj, ['values', 1, 1], 4);
+    Obj.update(matrix, (matrix) => {
+      Obj.setValue(matrix, ['values', 0, 0], 1);
+      Obj.setValue(matrix, ['values', 0, 1], 2);
+      Obj.setValue(matrix, ['values', 1, 0], 3);
+      Obj.setValue(matrix, ['values', 1, 1], 4);
     });
 
     expect(matrix.values?.[0][0]).toBe(1);
@@ -180,8 +180,8 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => {
-      expect(() => Obj.setValue(obj, [], 'value')).toThrow('Path must not be empty');
+    Obj.update(person, (person) => {
+      expect(() => Obj.setValue(person, [], 'value')).toThrow('Path must not be empty');
     });
   });
 
@@ -192,7 +192,7 @@ describe('Obj.setValue', () => {
       email: 'john@example.com',
     });
 
-    Obj.change(person, (obj) => Obj.setValue(obj, ['age'], 30));
+    Obj.update(person, (person) => Obj.setValue(person, ['age'], 30));
 
     expect(person.age).toBe(30);
   });
@@ -215,7 +215,7 @@ describe('Obj.setValue', () => {
     const container = Obj.make(Container, { name: 'box' });
 
     // Using string '0' for array index.
-    Obj.change(container, (obj) => Obj.setValue(obj, ['items', '0', 'value'], 42));
+    Obj.update(container, (container) => Obj.setValue(container, ['items', '0', 'value'], 42));
 
     expect(container.items?.[0].value).toBe(42);
   });
@@ -243,7 +243,7 @@ describe('Obj.setValue', () => {
 
     // This should work: setting a nested property on an array element.
     // The required 'id' field should be initialized with a default value.
-    Obj.change(todoList, (obj) => Obj.setValue(obj, ['tasks', 0, 'title'], 'Buy groceries'));
+    Obj.update(todoList, (todoList) => Obj.setValue(todoList, ['tasks', 0, 'title'], 'Buy groceries'));
 
     expect(todoList.tasks?.[0].id).toBe(''); // Default value for required String
     expect(todoList.tasks?.[0].title).toBe('Buy groceries');
@@ -270,7 +270,7 @@ describe('Obj.setValue', () => {
 
     const container = Obj.make(Container, { name: 'box' });
 
-    Obj.change(container, (obj) => Obj.setValue(obj, ['items', 0, 'label'], 'First Item'));
+    Obj.update(container, (container) => Obj.setValue(container, ['items', 0, 'label'], 'First Item'));
 
     // All required primitive fields should have default values.
     expect(container.items?.[0].id).toBe('');

package/src/internal/Obj/set-value.ts

@@ -21,7 +21,7 @@ import { getSchema } from '../common/types';
 
 /**
  * Set a deeply nested property on an object.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const setValue = (obj: Mutable<any>, path: readonly (string | number)[], value: any): void => {
   invariant(path.length > 0, 'Path must not be empty');

package/src/internal/Query.ts

@@ -10,6 +10,18 @@ import { type QueryAST } from '@dxos/echo-protocol';
 export const prettyFilter = (filter: QueryAST.Filter): string => {
   switch (filter.type) {
     case 'object': {
+      // A type-less object filter with only a meta-key constraint is `Filter.key(...)`.
+      if (
+        filter.typename === null &&
+        (filter.id === undefined || filter.id.length === 0) &&
+        Object.keys(filter.props).length === 0 &&
+        (filter.foreignKeys === undefined || filter.foreignKeys.length === 0) &&
+        filter.metaKey !== undefined
+      ) {
+        return filter.metaVersion !== undefined
+          ? `Filter.key(${JSON.stringify(filter.metaKey)}, { version: ${JSON.stringify(filter.metaVersion)} })`
+          : `Filter.key(${JSON.stringify(filter.metaKey)})`;
+      }
       const parts: string[] = [];
       if (filter.typename !== null) {
         parts.push(String(filter.typename));
@@ -25,6 +37,13 @@ export const prettyFilter = (filter: QueryAST.Filter): string => {
       if (filter.foreignKeys !== undefined && filter.foreignKeys.length > 0) {
         parts.push(`foreignKeys: [${filter.foreignKeys.map((fk) => JSON.stringify(fk)).join(', ')}]`);
       }
+      if (filter.metaKey !== undefined) {
+        parts.push(
+          filter.metaVersion !== undefined
+            ? `metaKey: ${JSON.stringify(filter.metaKey)} (${filter.metaVersion})`
+            : `metaKey: ${JSON.stringify(filter.metaKey)}`,
+        );
+      }
       return parts.length > 0 ? `Filter.type(${parts.join(', ')})` : 'Filter.everything()';
     }
     case 'compare':
@@ -43,6 +62,8 @@ export const prettyFilter = (filter: QueryAST.Filter): string => {
         : `Filter.textSearch(${JSON.stringify(filter.text)})`;
     case 'timestamp':
       return `Filter.${filter.field}.${filter.operator}(${filter.value})`;
+    case 'child-of':
+      return `Filter.childOf([${filter.parents.map((p) => JSON.stringify(p)).join(', ')}], { transitive: ${filter.transitive} })`;
     case 'not':
       return `Filter.not(${prettyFilter(filter.filter)})`;
     case 'and':
@@ -107,6 +128,9 @@ export const prettyQuery = (query: QueryAST.Query): string => {
       if (opts.deleted !== undefined) {
         parts.push(`deleted: ${JSON.stringify(opts.deleted)}`);
       }
+      if (opts.debugLabel !== undefined) {
+        parts.push(`debugLabel: ${JSON.stringify(opts.debugLabel)}`);
+      }
       return `${prettyQuery(query.query)}.options({ ${parts.join(', ')} })`;
     }
     case 'from': {
@@ -116,11 +140,11 @@ export const prettyQuery = (query: QueryAST.Query): string => {
         if (scope.spaceIds !== undefined) {
           parts.push(`spaceIds: [${scope.spaceIds.map((s) => JSON.stringify(s)).join(', ')}]`);
         }
-        if (scope.queues !== undefined) {
-          parts.push(`queues: [${scope.queues.map(String).join(', ')}]`);
+        if (scope.feeds !== undefined) {
+          parts.push(`feeds: [${scope.feeds.map(String).join(', ')}]`);
         }
-        if (scope.allQueuesFromSpaces !== undefined) {
-          parts.push(`allQueuesFromSpaces: ${scope.allQueuesFromSpaces}`);
+        if (scope.allFeedsFromSpaces !== undefined) {
+          parts.push(`allFeedsFromSpaces: ${scope.allFeedsFromSpaces}`);
         }
         return `${prettyQuery(query.query)}.from({ ${parts.join(', ')} })`;
       }

package/src/internal/Ref/ref.ts

@@ -164,6 +164,16 @@ export interface Ref<T> extends Pipeable.Pipeable {
 
   tryLoad(): Promise<T | undefined>;
 
+  /**
+   * Subscribe to the ref's resolution event.
+   * The callback fires when the target object becomes available in the working set
+   * (e.g. when its document is loaded after sibling-client mutation).
+   * Note: the resolver only schedules a notification when the target is requested
+   * via {@link target} while it is not yet loaded.
+   * @returns Function that unsubscribes the callback.
+   */
+  onResolved(callback: () => void): () => void;
+
   /**
    * Do not inline the target object in the reference.
    * Makes .target unavailable unless the reference is connected to a database context.
@@ -420,6 +430,13 @@ export class RefImpl<T> implements Ref<T> {
     return (await this.#resolver.resolve(this.#dxn)) as T | undefined;
   }
 
+  /**
+   * @inheritdoc
+   */
+  onResolved(callback: () => void): () => void {
+    return this.#resolved.on(callback);
+  }
+
   /**
    * Do not inline the target object in the reference.
    * Makes .target unavailable unless the reference is connected to a database context.

package/src/internal/Type/echo-schema.ts

@@ -372,7 +372,7 @@ export class EchoSchema<A = any, I = any> extends EchoSchemaConstructor() implem
   }
 
   /**
-   * Wrapper for Obj.change that handles the change context for the persistent schema.
+   * Wrapper for Obj.update that handles the change context for the persistent schema.
    */
   private _change(callback: (schema: PersistentSchema) => void): void {
     const changeFn = (this._persistentSchema as any)[ChangeId];

package/src/internal/common/README.md

@@ -99,4 +99,4 @@
 - [ ] ReactiveObject should specify id property? Reconcile AnyProperties, ReactiveObject, HasId, WithId, etc.
 - [ ] Can we us S.is(MyType) to detect objects with our types system? (Branding?)
 - [ ] Type.Expando doesn't work with AtomQuery result type (have to use Obj.Any instead).
-- [ ] Obj.Any doesn't work with Obj.change callback types (have to use `any` for the mutable parameter).
+- [ ] Obj.Any doesn't work with Obj.update callback types (have to use `any` for the mutable parameter).

package/src/internal/common/api/meta.ts

@@ -48,7 +48,7 @@ export const getKeys = (entity: AnyProperties, source: string): ForeignKey[] =>
 
 /**
  * Delete all keys from the entity for the specified source.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
   const meta = getMetaChecked(entity);
@@ -62,7 +62,7 @@ export const deleteKeys = (entity: Mutable<AnyProperties>, source: string) => {
 
 /**
  * Add a tag to the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);
@@ -72,7 +72,7 @@ export const addTag = (entity: Mutable<AnyProperties>, tag: string) => {
 
 /**
  * Remove a tag from the entity.
- * Must be called within an Obj.change or Relation.change callback.
+ * Must be called within an Obj.update or Relation.update callback.
  */
 export const removeTag = (entity: Mutable<AnyProperties>, tag: string) => {
   const meta = getMetaChecked(entity);

package/src/internal/common/proxy/change-context.ts

@@ -35,7 +35,7 @@ const pendingOwnerNotifications = new Set<object>();
 /**
  * Enter a change context for the given key.
  * While in a change context, mutations are allowed on the associated object.
- * Nested Obj.change calls are not supported.
+ * Nested Obj.update calls are not supported.
  *
  * @param key - The key to enter the change context for (target object or ObjectCore).
  * @returns A cleanup function that exits the change context.