@dxos/echo-atom 0.0.0 → 0.8.4-main.1c7ec43d41

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo-atom",
-  "version": "0.0.0",
+  "version": "0.8.4-main.1c7ec43d41",
   "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,
@@ -12,31 +16,29 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom": "^0.4.10",
-    "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"
+    "@effect-atom/atom": "^0.5.1",
+    "@dxos/echo": "0.8.4-main.1c7ec43d41",
+    "@dxos/echo-db": "0.8.4-main.1c7ec43d41",
+    "@dxos/util": "0.8.4-main.1c7ec43d41",
+    "@dxos/invariant": "0.8.4-main.1c7ec43d41"
   },
   "devDependencies": {
-    "@types/lodash.isequal": "^4.5.0",
-    "@dxos/test-utils": "0.8.3",
-    "@dxos/random": "0.8.3"
+    "effect": "3.20.0",
+    "@dxos/context": "0.8.4-main.1c7ec43d41",
+    "@dxos/random": "0.8.4-main.1c7ec43d41",
+    "@dxos/test-utils": "0.8.4-main.1c7ec43d41"
+  },
+  "peerDependencies": {
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/atom.test.ts

@@ -3,11 +3,12 @@
 //
 
 import * as Registry from '@effect-atom/atom/Registry';
-import { describe, expect, test } from 'vitest';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
 
-import { Obj } from '@dxos/echo';
-import { TestSchema } from '@dxos/echo/testing';
+import { Obj, Ref } from '@dxos/echo';
 import { createObject } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { TestSchema } from '@dxos/echo/testing';
 
 import * as AtomObj from './atom';
 
@@ -54,7 +55,7 @@ describe('Echo Atom - Basic Functionality', () => {
     expect(registry.get(emailAtom)).toBe('test@example.com');
   });
 
-  test('atom updates when object is mutated via Obj.change', () => {
+  test('atom updates when object is mutated via Obj.update', () => {
     const obj = createObject(
       Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
     );
@@ -71,9 +72,9 @@ describe('Echo Atom - Basic Functionality', () => {
       { immediate: true },
     );
 
-    // Mutate object via Obj.change.
-    Obj.change(obj, (o) => {
-      o.name = 'Updated';
+    // Mutate object via Obj.update.
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated';
     });
 
     // Subscription should have fired: immediate + update.
@@ -84,7 +85,7 @@ describe('Echo Atom - Basic Functionality', () => {
     expect(obj.name).toBe('Updated');
   });
 
-  test('property atom supports updater pattern via Obj.change', () => {
+  test('property atom supports updater pattern via Obj.update', () => {
     const obj = createObject(
       Obj.make(TestSchema.Task, {
         title: 'Task',
@@ -103,9 +104,9 @@ describe('Echo Atom - Basic Functionality', () => {
       { immediate: true },
     );
 
-    // Update through Obj.change.
-    Obj.change(obj, (o) => {
-      o.title = (o.title ?? '') + ' Updated';
+    // Update through Obj.update.
+    Obj.update(obj, (obj) => {
+      obj.title = (obj.title ?? '') + ' Updated';
     });
 
     // Subscription should have fired: immediate + update.
@@ -139,7 +140,9 @@ describe('Echo Atom - Basic Functionality', () => {
     expect(propertyUpdateCount).toBe(1);
 
     // Mutate the standalone object.
-    obj.name = 'Updated Standalone';
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated Standalone';
+    });
 
     // Both atoms should have received updates.
     expect(objectUpdateCount).toBe(2);
@@ -150,3 +153,246 @@ 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.update(obj, (obj) => {
+      obj.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.update(obj, (obj) => {
+      obj.name = 'Updated';
+    });
+
+    // The subscription should still work.
+    expect(updateCount).toBe(2);
+    expect(registry.get(atom1)).toBe('Updated');
+  });
+
+  test('AtomObj.make returns same atom instance for different ref instances with same DXN', ({ expect }) => {
+    const org = createObject(Obj.make(TestSchema.Organization, { name: 'DXOS' }));
+    const person = createObject(
+      Obj.make(TestSchema.Person, {
+        name: 'Test',
+        username: 'test',
+        email: 'test@example.com',
+        employer: Ref.make(org),
+      }),
+    );
+
+    // Each property access returns a new Ref instance from the ECHO proxy.
+    const ref1 = person.employer!;
+    const ref2 = person.employer!;
+    expect(ref1).not.toBe(ref2);
+
+    // Despite being different Ref instances, they should resolve to the same atom.
+    const atom1 = AtomObj.make(ref1);
+    const atom2 = AtomObj.make(ref2);
+    expect(atom1).toBe(atom2);
+  });
+});
+
+describe('AtomObj.makeWithReactive', () => {
+  test('returns object for direct obj input', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeWithReactive(obj);
+    const result = registry.get(atom);
+
+    expect(result).toBe(obj);
+    expect(result?.name).toBe('Test');
+  });
+
+  test('returns same atom for same object', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const atom1 = AtomObj.makeWithReactive(obj);
+    const atom2 = AtomObj.makeWithReactive(obj);
+
+    expect(atom1).toBe(atom2);
+  });
+
+  describe('with ref input', () => {
+    let testBuilder: InstanceType<typeof EchoTestBuilder>;
+
+    beforeEach(async () => {
+      testBuilder = await new EchoTestBuilder().open();
+    });
+
+    afterEach(async () => {
+      await testBuilder.close();
+    });
+
+    test('returns resolved object for ref', async ({ expect }) => {
+      const { db } = await testBuilder.createDatabase({
+        types: [TestSchema.Person, TestSchema.Task],
+      });
+      const task = db.add(Obj.make(TestSchema.Task, { title: 'Task 1' }));
+      const person = db.add(
+        Obj.make(TestSchema.Person, {
+          name: 'Test',
+          username: 'test',
+          email: 'test@example.com',
+          tasks: [Ref.make(task)],
+        }),
+      );
+      await db.flush();
+
+      const ref = person.tasks![0];
+      const registry = Registry.make();
+      const atom = AtomObj.makeWithReactive(ref);
+      const result = registry.get(atom);
+
+      expect(result).toBe(task);
+      expect(result?.title).toBe('Task 1');
+    });
+
+    test('returns undefined when ref target was removed', async ({ expect }) => {
+      const { db } = await testBuilder.createDatabase({
+        types: [TestSchema.Person, TestSchema.Task],
+      });
+      const task = db.add(Obj.make(TestSchema.Task, { title: 'Task 1' }));
+      const person = db.add(
+        Obj.make(TestSchema.Person, {
+          name: 'Test',
+          username: 'test',
+          email: 'test@example.com',
+          tasks: [Ref.make(task)],
+        }),
+      );
+      await db.flush();
+
+      const ref = person.tasks![0];
+      const registry = Registry.make();
+      const atom = AtomObj.makeWithReactive(ref);
+
+      expect(registry.get(atom)).toBe(task);
+
+      db.remove(task);
+      await db.flush();
+
+      expect(registry.get(atom)).toBeUndefined();
+    });
+  });
+});

package/src/atom.ts

@@ -3,89 +3,156 @@
 //
 
 import * as Atom from '@effect-atom/atom/Atom';
-import isEqual from 'lodash.isequal';
+import * as Result from '@effect-atom/atom/Result';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
 
-import { type Entity, Obj, Ref } from '@dxos/echo';
+import { type Entity, Obj, Ref, Relation } 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);
+  }).pipe(Atom.keepAlive);
+});
 
 /**
- * Internal helper to create an atom from a Ref.
- * Handles async loading and subscribes to the target for reactive updates.
+ * Atom family for ECHO refs.
+ * RefImpl implements Effect's Hash/Equal traits using DXN, so different Ref instances
+ * pointing to the same object resolve to the same atom.
  */
-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?.());
+    get.addFinalizer(() => {
+      unsubscribeTarget?.();
+    });
 
     return loadRefTarget(ref, get, setupTargetSubscription);
-  });
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * 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 (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]);
+    }).pipe(Atom.keepAlive);
+  }),
+);
+
+/**
+ * Create a read-only atom for a single reactive object or ref.
+ * Returns {@link Obj.Snapshot} (immutable plain data), not the live reactive object.
+ * Use this when you need one object's data for display or React dependency tracking.
+ * The atom updates automatically when the object is mutated.
+ * For refs, automatically handles async loading.
+ * Uses Atom.family internally - same object/ref 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 (plain data). 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 Relation.Unknown>(relation: T): Atom.Atom<Relation.Snapshot<T>>;
+export function make<T extends Entity.Unknown>(entity: T): Atom.Atom<Entity.Snapshot>;
+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 Entity.Unknown>(
+  objOrRef: T | Ref.Ref<T> | undefined,
+): Atom.Atom<Entity.Snapshot | undefined> {
+  if (objOrRef === undefined) {
+    return Atom.make<Entity.Snapshot | undefined>(() => undefined);
+  }
+
+  // Handle Ref inputs.
+  if (Ref.isRef(objOrRef)) {
+    return refFamily(objOrRef as any);
+  }
+
+  // At this point, objOrRef is definitely T (not a Ref).
+  const obj = objOrRef as T;
+  assertArgument(Obj.isObject(obj) || Relation.isRelation(obj), 'obj', 'Object must be a reactive object');
+
+  // TODO(dmaretskyi): Fix echo types during review.
+  return objectFamily(obj as any);
+}
+
 /**
  * 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 +160,70 @@ 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(key in obj, 'key', 'Property must exist on object');
-
-  return Atom.make<T[K] | undefined>((get) => {
-    let previousValue = obj[key];
+  assertArgument(Obj.isObject(obj), 'obj', 'Object must be a reactive object');
+  return propertyFamily(obj)(key);
+}
 
+/**
+ * Atom family for ECHO objects - returns the live object, not a snapshot.
+ * Same as objectFamily but returns T instead of Obj.Snapshot<T>.
+ */
+const objectWithReactiveFamily = Atom.family(<T extends Obj.Unknown>(obj: T): Atom.Atom<T> => {
+  return Atom.make<T>((get) => {
     const unsubscribe = Obj.subscribe(obj, () => {
-      const newValue = obj[key];
-      if (!isEqual(previousValue, newValue)) {
-        previousValue = newValue;
-        get.setSelf(newValue);
-      }
+      get.setSelf(obj);
     });
 
     get.addFinalizer(() => unsubscribe());
 
-    return obj[key];
-  });
+    return obj;
+  }).pipe(Atom.keepAlive);
+});
+
+/**
+ * Atom family for ECHO refs - returns the live reactive object, not a snapshot.
+ * Resolves the ref via the database; returns undefined while loading or if unresolved.
+ */
+const refWithReactiveFamily = Atom.family(<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined> => {
+  const effect = (get: Atom.Context) =>
+    Effect.gen(function* () {
+      const snapshot = get(make(ref));
+      if (snapshot == null) {
+        return undefined;
+      }
+      const option = yield* Obj.getReactiveOption(snapshot);
+      return Option.getOrElse(option, () => undefined);
+    });
+
+  return Function.pipe(
+    Atom.make(effect),
+    Atom.map((result) => Result.getOrElse(result, () => undefined)),
+  );
+});
+
+/**
+ * Like {@link make} but returns the live reactive object instead of a snapshot.
+ * Same input: Obj or Ref.Ref. Same output shape: Atom that updates when the object mutates.
+ * Prefer {@link make} (snapshot) unless you need the live Obj.Obj for generic mutations (e.g. Obj.update).
+ *
+ * @param objOrRef - The reactive object or ref.
+ * @returns An atom that returns the live object. Returns undefined for refs (async loading) or undefined input.
+ */
+export function makeWithReactive<T extends Obj.Unknown>(obj: T): Atom.Atom<T>;
+export function makeWithReactive<T extends Obj.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined>;
+export function makeWithReactive<T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): Atom.Atom<T | undefined>;
+export function makeWithReactive<T extends Obj.Unknown>(
+  objOrRef: T | Ref.Ref<T> | undefined,
+): Atom.Atom<T | undefined> {
+  if (objOrRef === undefined) {
+    return Atom.make<T | undefined>(() => undefined);
+  }
+
+  if (Ref.isRef(objOrRef)) {
+    return refWithReactiveFamily(objOrRef as Ref.Ref<T>);
+  }
+
+  const obj = objOrRef as T;
+  assertArgument(Obj.isObject(obj), 'obj', 'Object must be a reactive object');
+  return objectWithReactiveFamily(obj);
 }