@dxos/echo-atom 0.0.0 → 0.8.4-main.1068cf700f

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();
+  });
 });

package/src/ref-atom.test.ts

@@ -0,0 +1,209 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Obj, Ref } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { type EchoDatabase } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+
+import * as AtomRef from './ref-atom';
+
+describe('AtomRef - Basic Functionality', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const { db: database } = await testBuilder.createDatabase();
+    db = database;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('AtomRef.make returns target when ref is loaded', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const atom = AtomRef.make(ref);
+
+    // Should return the target object (as a snapshot).
+    const result = registry.get(atom);
+    expect(result?.name).toBe('Target');
+  });
+
+  test('AtomRef.make does not subscribe to target changes (use AtomObj for reactive snapshots)', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const atom = AtomRef.make(ref);
+
+    // Subscribe to updates.
+    let updateCount = 0;
+    registry.subscribe(atom, () => updateCount++, { immediate: true });
+
+    expect(updateCount).toBe(1);
+
+    // Mutate target - ref atom does NOT react to this.
+    Obj.change(targetObj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // Update count should still be 1 - ref atom doesn't subscribe to target changes.
+    expect(updateCount).toBe(1);
+  });
+});
+
+describe('AtomRef - Referential Equality', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const { db: database } = await testBuilder.createDatabase();
+    db = database;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('AtomRef.make returns same atom instance for same ref', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+
+    const atom1 = AtomRef.make(ref);
+    const atom2 = AtomRef.make(ref);
+
+    // Same ref should return the exact same atom instance.
+    expect(atom1).toBe(atom2);
+  });
+
+  test('AtomRef.make returns different atom instances for different refs', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj1 = Obj.make(TestSchema.Person, {
+      name: 'Target1',
+      username: 'target1',
+      email: 'target1@example.com',
+    });
+    const targetObj2 = Obj.make(TestSchema.Person, {
+      name: 'Target2',
+      username: 'target2',
+      email: 'target2@example.com',
+    });
+    db.add(targetObj1);
+    db.add(targetObj2);
+    await db.flush({ indexes: true });
+
+    const ref1 = Ref.make(targetObj1);
+    const ref2 = Ref.make(targetObj2);
+
+    const atom1 = AtomRef.make(ref1);
+    const atom2 = AtomRef.make(ref2);
+
+    // Different refs should return different atom instances.
+    expect(atom1).not.toBe(atom2);
+  });
+
+  test('AtomRef.make returns same atom for refs created separately to same target', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    // Create two separate refs to the same target.
+    const ref1 = Ref.make(targetObj);
+    const ref2 = Ref.make(targetObj);
+
+    // Refs are different objects (not referentially equal).
+    expect(ref1).not.toBe(ref2);
+
+    const atom1 = AtomRef.make(ref1);
+    const atom2 = AtomRef.make(ref2);
+
+    // Refs with the same DXN resolve to the same atom via Hash/Equal traits.
+    expect(atom1).toBe(atom2);
+
+    // Both atoms should return the same target data.
+    expect(registry.get(atom1)?.name).toBe('Target');
+    expect(registry.get(atom2)?.name).toBe('Target');
+  });
+
+  test('cached ref atoms return same instance after multiple retrievals', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+
+    // Get the same atom multiple times.
+    const atom1 = AtomRef.make(ref);
+    const atom2 = AtomRef.make(ref);
+    const atom3 = AtomRef.make(ref);
+
+    // All should be the same instance.
+    expect(atom1).toBe(atom2);
+    expect(atom2).toBe(atom3);
+
+    // All should return the same target value.
+    expect(registry.get(atom1)?.name).toBe('Target');
+    expect(registry.get(atom2)?.name).toBe('Target');
+    expect(registry.get(atom3)?.name).toBe('Target');
+  });
+});
+
+describe('AtomRef - Expando Objects', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const { db: database } = await testBuilder.createDatabase();
+    db = database;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('works with Expando objects', async () => {
+    const targetObj = Obj.make(TestSchema.Expando, { name: 'Expando Target', value: 42 });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const atom = AtomRef.make(ref);
+
+    const result = registry.get(atom);
+    expect(result?.name).toBe('Expando Target');
+    expect(result?.value).toBe(42);
+  });
+});

package/src/ref-atom.ts

@@ -4,21 +4,29 @@
 
 import * as Atom from '@effect-atom/atom/Atom';
 
-import { type Entity, type Ref } from '@dxos/echo';
+import { type Ref } from '@dxos/echo';
 
 import { loadRefTarget } from './ref-utils';
 
 /**
- * Create an atom for a reference target that returns the live object when loaded.
+ * Atom family for ECHO refs.
+ * Uses ref reference as key - same ref returns same atom.
  * This atom only updates once when the ref loads - it does not subscribe to object changes.
- * Use AtomObj.make with a ref if you need reactive snapshots.
+ * Use AtomObj.make with a ref if you need reactive snapshots of ECHO objects.
  */
-export function make<T extends Entity.Unknown>(ref: Ref.Ref<T> | undefined): Atom.Atom<T | undefined> {
-  if (!ref) {
-    return Atom.make<T | undefined>(() => undefined);
-  }
-
+const refFamily = Atom.family(<T>(ref: Ref.Ref<T>): Atom.Atom<T | undefined> => {
   return Atom.make<T | undefined>((get) => {
     return loadRefTarget(ref, get, (target) => target);
   });
-}
+});
+
+/**
+ * Create a read-only atom for a reference target.
+ * Returns undefined if the target hasn't loaded yet.
+ * Updates when the ref loads but does NOT subscribe to target object changes.
+ * Use AtomObj.make with a ref if you need reactive snapshots of ECHO objects.
+ * Uses Atom.family internally - same ref reference returns same atom instance.
+ *
+ * Supports refs to any target type including ECHO objects and Queues.
+ */
+export const make = refFamily;