@dxos/echo-atom 0.0.0 → 0.8.4-main.03d5cd7b56

package/src/ref-atom.test.ts

@@ -0,0 +1,243 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { type EchoDatabase } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { TestSchema } from '@dxos/echo/testing';
+import { PublicKey } from '@dxos/keys';
+
+import * as AtomObj from './atom';
+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();
+
+    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();
+
+    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.update(targetObj, (targetObj) => {
+      targetObj.name = 'Updated';
+    });
+
+    // Update count should still be 1 - ref atom doesn't subscribe to target changes.
+    expect(updateCount).toBe(1);
+  });
+
+  // Sibling client (sharing services) creates a brand-new ref target. The atom
+  // must update once the target's document propagates and resolves.
+  test('atom resolves target created by sibling client', async () => {
+    const [spaceKey] = PublicKey.randomSequence();
+    await using peer = await testBuilder.createPeer({
+      types: [TestSchema.Person, TestSchema.Container],
+    });
+    await using db1 = await peer.createDatabase(spaceKey);
+    const parent1 = db1.add(Obj.make(TestSchema.Container, { objects: [] }));
+    await db1.flush();
+
+    await using client2 = await peer.createClient();
+    await using db2 = await peer.openDatabase(spaceKey, db1.rootUrl!, { client: client2 });
+    const [parent2] = await db2.query(Filter.id(parent1.id)).run();
+
+    const newPerson = db2.add(
+      Obj.make(TestSchema.Person, { name: 'Alice', username: 'alice', email: 'alice@example.com' }),
+    );
+    Obj.update(parent2, (parent2) => {
+      parent2.objects = [...(parent2.objects ?? []), Ref.make(newPerson)];
+    });
+    await db2.flush();
+
+    await expect.poll(() => (parent1.objects ?? []).length).toBeGreaterThan(0);
+    const atom = AtomObj.make(parent1.objects![0]);
+
+    let lastValue: any;
+    registry.subscribe(atom, (value) => (lastValue = value), { immediate: true });
+
+    await expect.poll(() => lastValue?.name).toBe('Alice');
+  });
+});
+
+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();
+
+    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();
+
+    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();
+
+    // 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();
+
+    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();
+
+    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;

package/src/ref-utils.ts

@@ -21,19 +21,34 @@ export const loadRefTarget = <T, R>(
   get: Atom.Context,
   onTargetAvailable: (target: T) => R,
 ): R | undefined => {
+  // Accessing `ref.target` registers a resolution callback when the target is
+  // not yet loaded, so resolution can be observed via `ref.onResolved` below.
   const currentTarget = ref.target;
   if (currentTarget) {
     return onTargetAvailable(currentTarget);
   }
 
-  // Target not loaded yet - trigger async load.
+  // Subscribe to the ref's resolution event in case the target loads later
+  // (e.g. when a sibling client creates the linked object). Without this,
+  // a one-shot async load that fails because the document hasn't propagated
+  // would leave the atom permanently undefined.
+  const unsubscribe = ref.onResolved(() => {
+    const target = ref.target;
+    if (target) {
+      get.setSelf(onTargetAvailable(target));
+    }
+  });
+  get.addFinalizer(unsubscribe);
+
+  // Also try async load (e.g. for objects that need disk loading).
   void ref
     .load()
     .then((loadedTarget) => {
       get.setSelf(onTargetAvailable(loadedTarget));
     })
     .catch(() => {
-      // Loading failed, keep target as undefined.
+      // Loading failed; the resolution subscription above will pick up
+      // cross-client updates when they arrive.
     });
 
   return undefined;