@dxos/echo-atom 0.0.0 → 0.8.4-main.69d29f4

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo-atom",
-  "version": "0.0.0",
+  "version": "0.8.4-main.69d29f4",
   "description": "Effect Atom wrappers for ECHO objects with explicit subscriptions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": false,
@@ -25,18 +29,17 @@
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom": "^0.4.10",
+    "@effect-atom/atom": "^0.4.13",
     "lodash.isequal": "^4.5.0",
-    "@dxos/echo-db": "0.8.3",
-    "@dxos/live-object": "0.8.3",
-    "@dxos/echo": "0.8.3",
-    "@dxos/invariant": "0.8.3",
-    "@dxos/util": "0.8.3"
+    "@dxos/echo-db": "0.8.4-main.69d29f4",
+    "@dxos/invariant": "0.8.4-main.69d29f4",
+    "@dxos/util": "0.8.4-main.69d29f4",
+    "@dxos/echo": "0.8.4-main.69d29f4"
   },
   "devDependencies": {
     "@types/lodash.isequal": "^4.5.0",
-    "@dxos/test-utils": "0.8.3",
-    "@dxos/random": "0.8.3"
+    "@dxos/test-utils": "0.8.4-main.69d29f4",
+    "@dxos/random": "0.8.4-main.69d29f4"
   },
   "publishConfig": {
     "access": "public"

package/src/atom.test.ts

@@ -139,7 +139,9 @@ describe('Echo Atom - Basic Functionality', () => {
     expect(propertyUpdateCount).toBe(1);
 
     // Mutate the standalone object.
-    obj.name = 'Updated Standalone';
+    Obj.change(obj, (o) => {
+      o.name = 'Updated Standalone';
+    });
 
     // Both atoms should have received updates.
     expect(objectUpdateCount).toBe(2);
@@ -150,3 +152,135 @@ describe('Echo Atom - Basic Functionality', () => {
     expect(registry.get(propertyAtom)).toBe('Updated Standalone');
   });
 });
+
+describe('Echo Atom - Referential Equality', () => {
+  test('AtomObj.make returns same atom instance for same object', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const atom1 = AtomObj.make(obj);
+    const atom2 = AtomObj.make(obj);
+
+    // Same object should return the exact same atom instance.
+    expect(atom1).toBe(atom2);
+  });
+
+  test('AtomObj.make returns different atom instances for different objects', () => {
+    const obj1 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test1', username: 'test1', email: 'test1@example.com' }),
+    );
+    const obj2 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test2', username: 'test2', email: 'test2@example.com' }),
+    );
+
+    const atom1 = AtomObj.make(obj1);
+    const atom2 = AtomObj.make(obj2);
+
+    // Different objects should return different atom instances.
+    expect(atom1).not.toBe(atom2);
+  });
+
+  test('AtomObj.makeProperty returns same atom instance for same object and key', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const atom1 = AtomObj.makeProperty(obj, 'name');
+    const atom2 = AtomObj.makeProperty(obj, 'name');
+
+    // Same object and key should return the exact same atom instance.
+    expect(atom1).toBe(atom2);
+  });
+
+  test('AtomObj.makeProperty returns different atom instances for same object but different keys', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const nameAtom = AtomObj.makeProperty(obj, 'name');
+    const emailAtom = AtomObj.makeProperty(obj, 'email');
+
+    // Same object but different keys should return different atom instances.
+    expect(nameAtom).not.toBe(emailAtom);
+  });
+
+  test('AtomObj.makeProperty returns different atom instances for different objects with same key', () => {
+    const obj1 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test1', username: 'test1', email: 'test1@example.com' }),
+    );
+    const obj2 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test2', username: 'test2', email: 'test2@example.com' }),
+    );
+
+    const atom1 = AtomObj.makeProperty(obj1, 'name');
+    const atom2 = AtomObj.makeProperty(obj2, 'name');
+
+    // Different objects should return different atom instances even for same key.
+    expect(atom1).not.toBe(atom2);
+  });
+
+  test('cached atoms remain reactive after multiple retrievals', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+
+    // Get the same atom multiple times.
+    const atom1 = AtomObj.make(obj);
+    const atom2 = AtomObj.make(obj);
+    const atom3 = AtomObj.make(obj);
+
+    // All should be the same instance.
+    expect(atom1).toBe(atom2);
+    expect(atom2).toBe(atom3);
+
+    // Subscribe to the atom.
+    let updateCount = 0;
+    registry.subscribe(atom1, () => updateCount++, { immediate: true });
+
+    expect(updateCount).toBe(1);
+
+    // Mutate the object.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // The subscription should still work.
+    expect(updateCount).toBe(2);
+    expect(registry.get(atom1).name).toBe('Updated');
+  });
+
+  test('cached property atoms remain reactive after multiple retrievals', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+
+    // Get the same property atom multiple times.
+    const atom1 = AtomObj.makeProperty(obj, 'name');
+    const atom2 = AtomObj.makeProperty(obj, 'name');
+    const atom3 = AtomObj.makeProperty(obj, 'name');
+
+    // All should be the same instance.
+    expect(atom1).toBe(atom2);
+    expect(atom2).toBe(atom3);
+
+    // Subscribe to the atom.
+    let updateCount = 0;
+    registry.subscribe(atom1, () => updateCount++, { immediate: true });
+
+    expect(updateCount).toBe(1);
+
+    // Mutate the specific property.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // The subscription should still work.
+    expect(updateCount).toBe(2);
+    expect(registry.get(atom1)).toBe('Updated');
+  });
+});

package/src/atom.ts

@@ -5,87 +5,146 @@
 import * as Atom from '@effect-atom/atom/Atom';
 import isEqual from 'lodash.isequal';
 
-import { type Entity, Obj, Ref } from '@dxos/echo';
+import { Obj, Ref } from '@dxos/echo';
 import { assertArgument } from '@dxos/invariant';
-import { getSnapshot, isLiveObject } from '@dxos/live-object';
 
 import { loadRefTarget } from './ref-utils';
 
 /**
- * Create a read-only atom for a reactive object or ref.
- * Works with Echo objects, plain live objects (from Obj.make), and Refs.
- * Returns immutable snapshots of the object data.
- * The atom updates automatically when the object is mutated.
- * For refs, automatically handles async loading.
- *
- * @param objOrRef - The reactive object or ref to create an atom for, or undefined.
- * @returns An atom that returns the object snapshot, or undefined if not loaded/undefined.
+ * Atom family for ECHO objects.
+ * Uses object reference as key - same object returns same atom.
  */
-export function make<T extends Entity.Unknown>(objOrRef: T | Ref.Ref<T>): Atom.Atom<T | undefined>;
-export function make<T extends Entity.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): Atom.Atom<T | undefined>;
-export function make<T extends Entity.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): Atom.Atom<T | undefined> {
-  if (objOrRef === undefined) {
-    return Atom.make<T | undefined>(() => undefined);
-  }
-
-  // Handle Ref inputs.
-  if (Ref.isRef(objOrRef)) {
-    return makeFromRef(objOrRef as Ref.Ref<T>);
-  }
-
-  // At this point, objOrRef is definitely T (not a Ref).
-  const obj = objOrRef as T;
-  assertArgument(isLiveObject(obj), 'obj', 'Object must be a reactive object');
-
-  return Atom.make<T | undefined>((get) => {
+const objectFamily = Atom.family(<T extends Obj.Unknown>(obj: T): Atom.Atom<Obj.Snapshot<T>> => {
+  return Atom.make<Obj.Snapshot<T>>((get) => {
     const unsubscribe = Obj.subscribe(obj, () => {
-      get.setSelf(getSnapshot(obj) as T);
+      get.setSelf(Obj.getSnapshot(obj));
     });
 
     get.addFinalizer(() => unsubscribe());
 
-    return getSnapshot(obj) as T;
+    return Obj.getSnapshot(obj);
   });
-}
+});
 
 /**
  * Internal helper to create an atom from a Ref.
  * Handles async loading and subscribes to the target for reactive updates.
+ * Uses Atom.family internally - same ref reference returns same atom instance.
  */
-const makeFromRef = <T extends Entity.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined> => {
-  return Atom.make<T | undefined>((get) => {
+const refFamily = Atom.family(<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<Obj.Snapshot<T> | undefined> => {
+  return Atom.make<Obj.Snapshot<T> | undefined>((get) => {
     let unsubscribeTarget: (() => void) | undefined;
 
-    const setupTargetSubscription = (target: T): T => {
+    const setupTargetSubscription = (target: T): Obj.Snapshot<T> => {
       unsubscribeTarget?.();
       unsubscribeTarget = Obj.subscribe(target, () => {
-        get.setSelf(getSnapshot(target) as T);
+        get.setSelf(Obj.getSnapshot(target));
       });
-      return getSnapshot(target) as T;
+      return Obj.getSnapshot(target);
     };
 
     get.addFinalizer(() => unsubscribeTarget?.());
 
     return loadRefTarget(ref, get, setupTargetSubscription);
   });
+});
+
+/**
+ * Snapshot a value to create a new reference for comparison and React dependency tracking.
+ * Arrays and plain objects are shallow-copied so that:
+ * 1. The snapshot is isolated from mutations to the original value.
+ * 2. React's shallow comparison (Object.is) detects changes via new reference identity.
+ */
+const snapshotForComparison = <V>(value: V): V => {
+  if (Array.isArray(value)) {
+    return [...value] as V;
+  }
+  if (value !== null && typeof value === 'object') {
+    return { ...value } as V;
+  }
+  return value;
 };
 
+/**
+ * Atom family for ECHO object properties.
+ * Uses nested families: outer keyed by object, inner keyed by property key.
+ * Same object+key combination returns same atom instance.
+ */
+const propertyFamily = Atom.family(<T extends Obj.Unknown>(obj: T) =>
+  Atom.family(<K extends keyof T>(key: K): Atom.Atom<T[K]> => {
+    return Atom.make<T[K]>((get) => {
+      // Snapshot the initial value for comparison (arrays/objects need copying).
+      let previousSnapshot = snapshotForComparison(obj[key]);
+
+      const unsubscribe = Obj.subscribe(obj, () => {
+        const newValue = obj[key];
+        if (!isEqual(previousSnapshot, newValue)) {
+          previousSnapshot = snapshotForComparison(newValue);
+          // Return a snapshot copy so React sees a new reference.
+          get.setSelf(snapshotForComparison(newValue));
+        }
+      });
+
+      get.addFinalizer(() => unsubscribe());
+
+      // Return a snapshot copy so React sees a new reference.
+      return snapshotForComparison(obj[key]);
+    });
+  }),
+);
+
+/**
+ * Create a read-only atom for a reactive object or ref.
+ * Works with Echo objects, plain reactive objects (from Obj.make), and Refs.
+ * Returns immutable snapshots of the object data (branded with SnapshotKindId).
+ * The atom updates automatically when the object is mutated.
+ * For refs, automatically handles async loading.
+ * Uses Atom.family internally - same object/ref reference returns same atom instance.
+ *
+ * @param objOrRef - The reactive object or ref to create an atom for, or undefined.
+ * @returns An atom that returns the object snapshot. Returns undefined only for refs (async loading) or undefined input.
+ */
+export function make<T extends Obj.Unknown>(obj: T): Atom.Atom<Obj.Snapshot<T>>;
+export function make<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<Obj.Snapshot<T> | undefined>;
+export function make<T extends Obj.Unknown>(
+  objOrRef: T | Ref.Ref<T> | undefined,
+): Atom.Atom<Obj.Snapshot<T> | undefined>;
+export function make<T extends Obj.Unknown>(
+  objOrRef: T | Ref.Ref<T> | undefined,
+): Atom.Atom<Obj.Snapshot<T> | undefined> {
+  if (objOrRef === undefined) {
+    return Atom.make<Obj.Snapshot<T> | undefined>(() => undefined);
+  }
+
+  // Handle Ref inputs.
+  if (Ref.isRef(objOrRef)) {
+    return refFamily(objOrRef as Ref.Ref<T>);
+  }
+
+  // At this point, objOrRef is definitely T (not a Ref).
+  const obj = objOrRef as T;
+  assertArgument(Obj.isObject(obj), 'obj', 'Object must be a reactive object');
+
+  return objectFamily(obj);
+}
+
 /**
  * Create a read-only atom for a specific property of a reactive object.
  * Works with both Echo objects (from createObject) and plain live objects (from Obj.make).
  * The atom updates automatically when the property is mutated.
  * Only fires updates when the property value actually changes.
+ * Uses Atom.family internally - same object+key combination returns same atom instance.
  *
  * @param obj - The reactive object to create an atom for, or undefined.
  * @param key - The property key to subscribe to.
  * @returns An atom that returns the property value, or undefined if obj is undefined.
  */
-export function makeProperty<T extends Entity.Unknown, K extends keyof T>(obj: T, key: K): Atom.Atom<T[K]>;
-export function makeProperty<T extends Entity.Unknown, K extends keyof T>(
+export function makeProperty<T extends Obj.Unknown, K extends keyof T>(obj: T, key: K): Atom.Atom<T[K]>;
+export function makeProperty<T extends Obj.Unknown, K extends keyof T>(
   obj: T | undefined,
   key: K,
 ): Atom.Atom<T[K] | undefined>;
-export function makeProperty<T extends Entity.Unknown, K extends keyof T>(
+export function makeProperty<T extends Obj.Unknown, K extends keyof T>(
   obj: T | undefined,
   key: K,
 ): Atom.Atom<T[K] | undefined> {
@@ -93,22 +152,7 @@ export function makeProperty<T extends Entity.Unknown, K extends keyof T>(
     return Atom.make<T[K] | undefined>(() => undefined);
   }
 
-  assertArgument(isLiveObject(obj), 'obj', 'Object must be a reactive object');
+  assertArgument(Obj.isObject(obj), 'obj', 'Object must be a reactive object');
   assertArgument(key in obj, 'key', 'Property must exist on object');
-
-  return Atom.make<T[K] | undefined>((get) => {
-    let previousValue = obj[key];
-
-    const unsubscribe = Obj.subscribe(obj, () => {
-      const newValue = obj[key];
-      if (!isEqual(previousValue, newValue)) {
-        previousValue = newValue;
-        get.setSelf(newValue);
-      }
-    });
-
-    get.addFinalizer(() => unsubscribe());
-
-    return obj[key];
-  });
+  return propertyFamily(obj)(key);
 }

package/src/query-atom.test.ts

@@ -7,8 +7,10 @@ import * as Schema from 'effect/Schema';
 import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
 import { Obj, type QueryResult, Type } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
 import { type EchoDatabase, Filter, Query } from '@dxos/echo-db';
 import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { SpaceId } from '@dxos/keys';
 
 import * as AtomQuery from './query-atom';
 
@@ -19,7 +21,7 @@ const TestItem = Schema.Struct({
   name: Schema.String,
   value: Schema.Number,
 }).pipe(
-  Type.Obj({
+  Type.object({
     typename: 'example.com/type/TestItem',
     version: '0.1.0',
   }),
@@ -198,3 +200,63 @@ describe('AtomQuery', () => {
     expect(results2[0].name).toBe('Object');
   });
 });
+
+describe('AtomQuery with queues', () => {
+  let testBuilder: EchoTestBuilder;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('AtomQuery.make with Filter.type on queue', async () => {
+    const peer = await testBuilder.createPeer({ types: [TestSchema.Person] });
+    const spaceId = SpaceId.random();
+    const queues = peer.client.constructQueueFactory(spaceId);
+    const queue = queues.create();
+
+    const john = Obj.make(TestSchema.Person, { name: 'john' });
+    const jane = Obj.make(TestSchema.Person, { name: 'jane' });
+    await queue.append([john, jane]);
+
+    // Verify queue.query works directly (sanity check).
+    const directResult = await queue.query(Query.select(Filter.type(TestSchema.Person))).run();
+    expect(directResult).toHaveLength(2);
+
+    // Now test AtomQuery.make.
+    const atom = AtomQuery.make<TestSchema.Person>(queue, Filter.type(TestSchema.Person));
+    const results = registry.get(atom);
+
+    expect(results).toHaveLength(2);
+    expect(results.map((r) => r.name).sort()).toEqual(['jane', 'john']);
+  });
+
+  test('AtomQuery.make with Filter.id on queue', async () => {
+    const peer = await testBuilder.createPeer({ types: [TestSchema.Person] });
+    const spaceId = SpaceId.random();
+    const queues = peer.client.constructQueueFactory(spaceId);
+    const queue = queues.create();
+
+    const john = Obj.make(TestSchema.Person, { name: 'john' });
+    const jane = Obj.make(TestSchema.Person, { name: 'jane' });
+    const alice = Obj.make(TestSchema.Person, { name: 'alice' });
+    await queue.append([john, jane, alice]);
+
+    // Verify queue.query works directly (sanity check).
+    const directResult = await queue.query(Query.select(Filter.id(jane.id))).run();
+    expect(directResult).toHaveLength(1);
+
+    // Use AtomQuery.make with Filter.id - this is what app-graph-builder uses.
+    const atom = AtomQuery.make<TestSchema.Person>(queue, Filter.id(jane.id));
+    const results = registry.get(atom);
+
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toEqual(jane.id);
+    expect(results[0].name).toEqual('jane');
+  });
+});

package/src/query-atom.ts

@@ -34,10 +34,13 @@ export const fromQuery = <T extends Entity.Unknown>(queryResult: QueryResult.Que
 // Registry: key → Queryable (WeakRef with auto-cleanup when GC'd).
 const queryableRegistry = new WeakDictionary<string, Database.Queryable>();
 
-// Atom.family keyed by "identifier:serializedAST".
+// Key separator that won't appear in identifiers (DXN strings use colons).
+const KEY_SEPARATOR = '~';
+
+// Atom.family keyed by "identifier\0serializedAST".
 const queryFamily = Atom.family((key: string) => {
   // Parse key outside Atom.make - runs once per key.
-  const separatorIndex = key.indexOf(':');
+  const separatorIndex = key.indexOf(KEY_SEPARATOR);
   const identifier = key.slice(0, separatorIndex);
   const serializedAst = key.slice(separatorIndex + 1);
 
@@ -114,8 +117,8 @@ const fromQueryable = <T extends Entity.Unknown>(
     ? queryOrFilter
     : Query.select(queryOrFilter as Filter.Filter<T>);
 
-  // Build key: identifier:serializedAST.
-  const key = `${identifier}:${JSON.stringify(normalizedQuery.ast)}`;
+  // Build key: identifier\0serializedAST (using null char as separator to avoid DXN colon conflicts).
+  const key = `${identifier}${KEY_SEPARATOR}${JSON.stringify(normalizedQuery.ast)}`;
 
   return queryFamily(key) as Atom.Atom<T[]>;
 };

package/src/reactivity.test.ts

@@ -155,4 +155,52 @@ describe('Echo Atom - Reactivity', () => {
     expect(finalSnapshot.name).toBe('Updated');
     expect(finalSnapshot.email).toBe('updated@example.com');
   });
+
+  test('property mutation on standalone Obj.make object is synchronous', () => {
+    // Test objects created with just Obj.make() - no createObject/database.
+    const obj = Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' });
+
+    const actions: string[] = [];
+    const unsubscribe = Obj.subscribe(obj, () => {
+      actions.push('update');
+    });
+
+    actions.push('before');
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+    actions.push('after');
+
+    // Updates must be synchronous: before -> update -> after.
+    expect(actions).toEqual(['before', 'update', 'after']);
+
+    // Verify the property was modified.
+    expect(obj.name).toBe('Updated');
+
+    unsubscribe();
+  });
+
+  test('array splice on standalone Obj.make object is synchronous', () => {
+    // Test objects created with just Obj.make() - no createObject/database.
+    const obj = Obj.make(TestSchema.Example, { stringArray: ['a', 'b', 'c', 'd'] });
+
+    const actions: string[] = [];
+    const unsubscribe = Obj.subscribe(obj, () => {
+      actions.push('update');
+    });
+
+    actions.push('before');
+    Obj.change(obj, (o) => {
+      o.stringArray!.splice(1, 1);
+    });
+    actions.push('after');
+
+    // Updates must be synchronous: before -> update -> after.
+    expect(actions).toEqual(['before', 'update', 'after']);
+
+    // Verify the array was modified.
+    expect(obj.stringArray).toEqual(['a', 'c', 'd']);
+
+    unsubscribe();
+  });
 });