@dxos/echo-atom 0.0.0

package/LICENSE

@@ -0,0 +1,8 @@
+MIT License
+Copyright (c) 2025 DXOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @dxos/echo-atom
+
+Effect Atom wrappers for ECHO objects with automatic subscriptions. Provides object reactivity without signals by integrating ECHO objects with the Effect Atom system.
+
+## Overview
+
+`echo-atom` bridges ECHO objects and Effect Atoms, enabling reactive programming patterns without relying on signals. It provides:
+
+- **Object-level reactivity**: Subscribe to entire Echo objects or specific properties
+- **Automatic subscriptions**: Direct integration with Echo's `Obj.subscribe` system
+- **Type-safe APIs**: Full TypeScript support with proper inference
+- **React integration**: See `@dxos/echo-react` for React hooks
+- **SolidJS integration**: See `@dxos/echo-solid` for SolidJS hooks
+
+## Design Goals
+
+1. **No Signals Dependency**: Provides reactivity without requiring signal-based reactivity systems
+2. **Automatic Subscriptions**: Atoms automatically subscribe to Echo object changes via `Obj.subscribe`
+3. **Granular Updates**: Subscribe to entire objects or specific properties for efficient re-renders
+4. **Type Safety**: Full TypeScript support with proper generic constraints
+5. **Framework Agnostic**: Core functionality works with any framework; React and SolidJS hooks provided separately
+
+## Core Concepts
+
+### Atoms
+
+Atoms wrap Echo objects and their properties, storing metadata about the object and path being watched:
+
+```typescript
+interface AtomValue<T> {
+  readonly obj: Entity.Unknown;  // The Echo object being watched
+  readonly path: KeyPath;        // Property path (empty for entire object)
+  readonly value: T;             // Current value
+}
+```
+
+### Registry
+
+The Effect Atom Registry manages atom lifecycle and subscriptions. Each registry instance maintains its own subscription state.
+
+### Reactive Updates
+
+When you mutate an Echo object directly, the changes automatically flow through `Obj.subscribe` to update the atom and notify all subscribers.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import * as Registry from '@effect-atom/atom/Registry';
+import { AtomObj } from '@dxos/echo-atom';
+import { Obj } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+
+// Create a registry
+const registry = Registry.make();
+
+// Create an Echo object
+const person = Obj.make(TestSchema.Person, {
+  name: 'Alice',
+  email: 'alice@example.com'
+});
+
+// Create an atom for the entire object
+const personAtom = AtomObj.make(person);
+
+// Create an atom for a specific property
+const nameAtom = AtomObj.makeProperty(person, 'name');
+
+// Get current values from the registry
+const currentPerson = registry.get(personAtom).value;
+const currentName = registry.get(nameAtom).value;
+
+// Subscribe to updates using the registry
+const unsubscribe = registry.subscribe(nameAtom, () => {
+  const newName = registry.get(nameAtom).value;
+  console.log('Name changed:', newName);
+}, { immediate: true });
+
+// Update the object directly - the atom will automatically update
+person.name = 'Bob';
+person.email = 'bob@example.com';
+
+// Clean up
+unsubscribe();
+```
+
+### React Integration
+
+For React applications, use the hooks from `@dxos/echo-react`:
+
+```tsx
+import { useObject } from '@dxos/echo-react';
+import { RegistryContext } from '@effect-atom/atom-react';
+import * as Registry from '@effect-atom/atom/Registry';
+
+// Wrap your app with RegistryContext
+function App() {
+  const registry = useMemo(() => Registry.make(), []);
+
+  return (
+    <RegistryContext.Provider value={registry}>
+      <YourComponents />
+    </RegistryContext.Provider>
+  );
+}
+
+// In your components
+function PersonView({ person }: { person: Person }) {
+  // Subscribe to entire object (returns [value, updateCallback])
+  const [currentPerson, updatePerson] = useObject(person);
+
+  // Subscribe to specific property (returns [value, updateCallback])
+  const [name, updateName] = useObject(person, 'name');
+
+  return (
+    <div>
+      <input
+        value={name}
+        onChange={(e) => updateName(e.target.value)}
+      />
+      <button onClick={() => updatePerson(p => { p.email = 'new@example.com'; })}>
+        Update Email
+      </button>
+    </div>
+  );
+}
+```
+
+### SolidJS Integration
+
+For SolidJS applications, use the hooks from `@dxos/echo-solid`:
+
+```tsx
+import { useObject } from '@dxos/echo-solid';
+import { RegistryContext } from '@dxos/effect-atom-solid';
+import * as Registry from '@effect-atom/atom/Registry';
+
+// Wrap your app with RegistryContext
+function App() {
+  const registry = Registry.make();
+
+  return (
+    <RegistryContext.Provider value={registry}>
+      <YourComponents />
+    </RegistryContext.Provider>
+  );
+}
+
+// In your components
+function PersonView(props: { person: Person }) {
+  // Subscribe to entire object (returns [accessor, updateCallback])
+  const [currentPerson, updatePerson] = useObject(() => props.person);
+
+  // Subscribe to specific property (returns [accessor, updateCallback])
+  const [name, updateName] = useObject(() => props.person, 'name');
+
+  return (
+    <div>
+      <input
+        value={name()}
+        onInput={(e) => updateName(e.target.value)}
+      />
+      <button onClick={() => updatePerson(p => { p.email = 'new@example.com'; })}>
+        Update Email
+      </button>
+    </div>
+  );
+}
+```

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@dxos/echo-atom",
+  "version": "0.0.0",
+  "description": "Effect Atom wrappers for ECHO objects with explicit subscriptions.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "browser": "./dist/lib/browser/index.mjs",
+      "node": "./dist/lib/node-esm/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"
+  },
+  "devDependencies": {
+    "@types/lodash.isequal": "^4.5.0",
+    "@dxos/test-utils": "0.8.3",
+    "@dxos/random": "0.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/atom.test.ts

@@ -0,0 +1,152 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { describe, expect, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { createObject } from '@dxos/echo-db';
+
+import * as AtomObj from './atom';
+
+describe('Echo Atom - Basic Functionality', () => {
+  test('AtomObj.make creates atom for entire object', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.make(obj);
+
+    // Returns a snapshot (plain object), not the Echo object itself.
+    const snapshot = registry.get(atom);
+    expect(snapshot).not.toBe(obj);
+    expect(snapshot.name).toBe('Test');
+    expect(snapshot.username).toBe('test');
+    expect(snapshot.email).toBe('test@example.com');
+  });
+
+  test('AtomObj.makeProperty creates atom for specific property', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeProperty(obj, 'name');
+
+    const atomValue = registry.get(atom);
+    expect(atomValue).toBe('Test');
+  });
+
+  test('AtomObj.makeProperty is type-safe', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    // This should compile and work.
+    const nameAtom = AtomObj.makeProperty(obj, 'name');
+    const emailAtom = AtomObj.makeProperty(obj, 'email');
+
+    expect(registry.get(nameAtom)).toBe('Test');
+    expect(registry.get(emailAtom)).toBe('test@example.com');
+  });
+
+  test('atom updates when object is mutated via Obj.change', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeProperty(obj, 'name');
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Mutate object via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // Subscription should have fired: immediate + update.
+    expect(updateCount).toBe(2);
+
+    // Atom should reflect the change.
+    expect(registry.get(atom)).toBe('Updated');
+    expect(obj.name).toBe('Updated');
+  });
+
+  test('property atom supports updater pattern via Obj.change', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Task, {
+        title: 'Task',
+      }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeProperty(obj, 'title');
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Update through Obj.change.
+    Obj.change(obj, (o) => {
+      o.title = (o.title ?? '') + ' Updated';
+    });
+
+    // Subscription should have fired: immediate + update.
+    expect(updateCount).toBe(2);
+
+    // Atom should reflect the change.
+    expect(registry.get(atom)).toBe('Task Updated');
+    expect(obj.title).toBe('Task Updated');
+  });
+
+  test('atoms work for plain live objects (Obj.make without createObject)', () => {
+    // This test explicitly verifies that reactivity works for plain live objects
+    // created with just Obj.make() - no createObject() or database required.
+    // This is the simplest form of reactive object.
+    const obj = Obj.make(TestSchema.Person, { name: 'Standalone', username: 'test', email: 'test@example.com' });
+
+    // Verify object has an id (Obj.make generates one).
+    expect(obj.id).toBeDefined();
+
+    const registry = Registry.make();
+    const objectAtom = AtomObj.make(obj);
+    const propertyAtom = AtomObj.makeProperty(obj, 'name');
+
+    let objectUpdateCount = 0;
+    let propertyUpdateCount = 0;
+
+    registry.subscribe(objectAtom, () => objectUpdateCount++, { immediate: true });
+    registry.subscribe(propertyAtom, () => propertyUpdateCount++, { immediate: true });
+
+    expect(objectUpdateCount).toBe(1);
+    expect(propertyUpdateCount).toBe(1);
+
+    // Mutate the standalone object.
+    obj.name = 'Updated Standalone';
+
+    // Both atoms should have received updates.
+    expect(objectUpdateCount).toBe(2);
+    expect(propertyUpdateCount).toBe(2);
+
+    // Verify values are correct.
+    expect(registry.get(objectAtom)!.name).toBe('Updated Standalone');
+    expect(registry.get(propertyAtom)).toBe('Updated Standalone');
+  });
+});

package/src/atom.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import isEqual from 'lodash.isequal';
+
+import { type Entity, 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.
+ */
+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 unsubscribe = Obj.subscribe(obj, () => {
+      get.setSelf(getSnapshot(obj) as T);
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return getSnapshot(obj) as T;
+  });
+}
+
+/**
+ * Internal helper to create an atom from a Ref.
+ * Handles async loading and subscribes to the target for reactive updates.
+ */
+const makeFromRef = <T extends Entity.Unknown>(ref: Ref.Ref<T>): Atom.Atom<T | undefined> => {
+  return Atom.make<T | undefined>((get) => {
+    let unsubscribeTarget: (() => void) | undefined;
+
+    const setupTargetSubscription = (target: T): T => {
+      unsubscribeTarget?.();
+      unsubscribeTarget = Obj.subscribe(target, () => {
+        get.setSelf(getSnapshot(target) as T);
+      });
+      return getSnapshot(target) as T;
+    };
+
+    get.addFinalizer(() => unsubscribeTarget?.());
+
+    return loadRefTarget(ref, get, setupTargetSubscription);
+  });
+};
+
+/**
+ * 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.
+ *
+ * @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>(
+  obj: T | undefined,
+  key: K,
+): Atom.Atom<T[K] | undefined>;
+export function makeProperty<T extends Entity.Unknown, K extends keyof T>(
+  obj: T | undefined,
+  key: K,
+): Atom.Atom<T[K] | undefined> {
+  if (obj === undefined) {
+    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];
+
+    const unsubscribe = Obj.subscribe(obj, () => {
+      const newValue = obj[key];
+      if (!isEqual(previousValue, newValue)) {
+        previousValue = newValue;
+        get.setSelf(newValue);
+      }
+    });
+
+    get.addFinalizer(() => unsubscribe());
+
+    return obj[key];
+  });
+}

package/src/batching.test.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { describe, expect, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { createObject } from '@dxos/echo-db';
+
+import * as AtomObj from './atom';
+
+describe('Echo Atom - Batch Updates', () => {
+  test('multiple updates to same object atom in single Obj.change fire single update', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.make(obj);
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Get initial count (immediate: true causes initial update).
+    const initialCount = updateCount;
+    expect(initialCount).toBe(1); // Verify immediate update fired.
+
+    // Make multiple updates to the same object in a single Obj.change call.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated1';
+      o.email = 'updated@example.com';
+      o.username = 'updated';
+    });
+
+    // Should have fired once for initial + once for the Obj.change (not once per property update).
+    expect(updateCount).toBe(2);
+
+    // Verify final state.
+    const finalValue = registry.get(atom);
+    expect(finalValue.name).toBe('Updated1');
+    expect(finalValue.email).toBe('updated@example.com');
+    expect(finalValue.username).toBe('updated');
+  });
+
+  test('multiple separate Obj.change calls fire separate updates', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.make(obj);
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Get initial count (immediate: true causes initial update).
+    const initialCount = updateCount;
+    expect(initialCount).toBe(1);
+
+    // Make multiple separate Obj.change calls.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated1';
+    });
+    Obj.change(obj, (o) => {
+      o.email = 'updated@example.com';
+    });
+    Obj.change(obj, (o) => {
+      o.username = 'updated';
+    });
+
+    // Should have fired once for initial + once per Obj.change call.
+    expect(updateCount).toBe(4);
+
+    // Verify final state.
+    const finalValue = registry.get(atom);
+    expect(finalValue.name).toBe('Updated1');
+    expect(finalValue.email).toBe('updated@example.com');
+    expect(finalValue.username).toBe('updated');
+  });
+
+  test('multiple updates to same property atom in single Obj.change fire single update', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeProperty(obj, 'name');
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Get initial count (immediate: true causes initial update).
+    const initialCount = updateCount;
+    expect(initialCount).toBe(1);
+
+    // Make multiple updates to the same property in a single Obj.change call.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated1';
+      o.name = 'Updated2';
+      o.name = 'Updated3';
+    });
+
+    // Should have fired once for initial + once for the Obj.change (not once per assignment).
+    expect(updateCount).toBe(2);
+
+    // Verify final state.
+    expect(registry.get(atom)).toBe('Updated3');
+  });
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as AtomObj from './atom';
+export * as AtomQuery from './query-atom';
+export * as AtomRef from './ref-atom';

package/src/query-atom.test.ts

@@ -0,0 +1,200 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import * as Schema from 'effect/Schema';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Obj, type QueryResult, Type } from '@dxos/echo';
+import { type EchoDatabase, Filter, Query } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+
+import * as AtomQuery from './query-atom';
+
+/**
+ * Test schema for query-atom tests.
+ */
+const TestItem = Schema.Struct({
+  name: Schema.String,
+  value: Schema.Number,
+}).pipe(
+  Type.Obj({
+    typename: 'example.com/type/TestItem',
+    version: '0.1.0',
+  }),
+);
+type TestItem = Schema.Schema.Type<typeof TestItem>;
+
+describe('AtomQuery', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: EchoDatabase;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const { db: database } = await testBuilder.createDatabase({ types: [TestItem] });
+    db = database;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('creates atom with initial results', async () => {
+    db.add(Obj.make(TestItem, { name: 'Object 1', value: 100 }));
+    db.add(Obj.make(TestItem, { name: 'Object 2', value: 100 }));
+    await db.flush({ indexes: true });
+
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 100 })),
+    );
+    await queryResult.run();
+
+    const atom = AtomQuery.fromQuery(queryResult);
+    const results = registry.get(atom);
+
+    expect(results).toHaveLength(2);
+    expect(results.map((r) => r.name).sort()).toEqual(['Object 1', 'Object 2']);
+  });
+
+  test('registry.subscribe fires on QueryResult changes', async () => {
+    db.add(Obj.make(TestItem, { name: 'Initial', value: 200 }));
+    await db.flush({ indexes: true });
+
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 200 })),
+    );
+    await queryResult.run();
+
+    const atom = AtomQuery.fromQuery(queryResult);
+
+    // Get initial results.
+    const initialResults = registry.get(atom);
+    expect(initialResults).toHaveLength(1);
+
+    // Subscribe to atom updates.
+    let updateCount = 0;
+    let latestResults: TestItem[] = [];
+    registry.subscribe(atom, () => {
+      updateCount++;
+      latestResults = registry.get(atom);
+    });
+
+    // Add a new object that matches the query.
+    db.add(Obj.make(TestItem, { name: 'New Object', value: 200 }));
+    await db.flush({ indexes: true, updates: true });
+
+    // Subscription should have fired.
+    expect(updateCount).toBeGreaterThan(0);
+    expect(latestResults).toHaveLength(2);
+  });
+
+  test('registry.subscribe fires when objects are removed', async () => {
+    const obj1 = db.add(Obj.make(TestItem, { name: 'Object 1', value: 300 }));
+    db.add(Obj.make(TestItem, { name: 'Object 2', value: 300 }));
+    await db.flush({ indexes: true });
+
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 300 })),
+    );
+    await queryResult.run();
+
+    const atom = AtomQuery.fromQuery(queryResult);
+
+    // Get initial results.
+    const initialResults = registry.get(atom);
+    expect(initialResults).toHaveLength(2);
+
+    // Subscribe to atom updates.
+    let updateCount = 0;
+    let latestResults: TestItem[] = [];
+    registry.subscribe(atom, () => {
+      updateCount++;
+      latestResults = registry.get(atom);
+    });
+
+    // Remove an object.
+    db.remove(obj1);
+    await db.flush({ indexes: true, updates: true });
+
+    // Subscription should have fired.
+    expect(updateCount).toBeGreaterThan(0);
+    expect(latestResults).toHaveLength(1);
+    expect(latestResults[0].name).toBe('Object 2');
+  });
+
+  test('unsubscribing from registry stops receiving updates', async () => {
+    db.add(Obj.make(TestItem, { name: 'Initial', value: 400 }));
+    await db.flush({ indexes: true });
+
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 400 })),
+    );
+    await queryResult.run();
+
+    const atom = AtomQuery.fromQuery(queryResult);
+
+    // Initialize the atom by getting its value first.
+    const initialResults = registry.get(atom);
+    expect(initialResults).toHaveLength(1);
+
+    // Subscribe to atom updates.
+    let updateCount = 0;
+    const unsubscribe = registry.subscribe(atom, () => {
+      updateCount++;
+    });
+
+    // Add object and verify subscription fires.
+    db.add(Obj.make(TestItem, { name: 'Object 2', value: 400 }));
+    await db.flush({ indexes: true, updates: true });
+    const countAfterFirstAdd = updateCount;
+    expect(countAfterFirstAdd).toBeGreaterThan(0);
+
+    // Unsubscribe.
+    unsubscribe();
+
+    // Add another object.
+    db.add(Obj.make(TestItem, { name: 'Object 3', value: 400 }));
+    await db.flush({ indexes: true, updates: true });
+
+    // Update count should not have changed after unsubscribe.
+    expect(updateCount).toBe(countAfterFirstAdd);
+  });
+
+  test('works with empty query results', async () => {
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 999 })),
+    );
+    await queryResult.run();
+
+    const atom = AtomQuery.fromQuery(queryResult);
+    const results = registry.get(atom);
+
+    expect(results).toHaveLength(0);
+  });
+
+  test('multiple atoms from same query share underlying subscription', async () => {
+    db.add(Obj.make(TestItem, { name: 'Object', value: 500 }));
+    await db.flush({ indexes: true });
+
+    const queryResult: QueryResult.QueryResult<TestItem> = db.query(
+      Query.select(Filter.type(TestItem, { value: 500 })),
+    );
+    await queryResult.run();
+
+    // Create two atoms from the same query result.
+    const atom1 = AtomQuery.fromQuery(queryResult);
+    const atom2 = AtomQuery.fromQuery(queryResult);
+
+    // Both should return the same results.
+    const results1 = registry.get(atom1);
+    const results2 = registry.get(atom2);
+
+    expect(results1).toHaveLength(1);
+    expect(results2).toHaveLength(1);
+    expect(results1[0].name).toBe('Object');
+    expect(results2[0].name).toBe('Object');
+  });
+});

package/src/query-atom.ts

@@ -0,0 +1,121 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom';
+
+import { DXN, Database, type Entity, type Filter, Query, type QueryResult } from '@dxos/echo';
+import { WeakDictionary } from '@dxos/util';
+
+/**
+ * Create a self-updating atom from an existing QueryResult.
+ * Internally subscribes to queryResult and uses get.setSelf to update.
+ * Cleanup is handled via get.addFinalizer.
+ *
+ * Note: This creates a new atom each time. For memoization, use `make` instead.
+ *
+ * @param queryResult - The QueryResult to wrap.
+ * @returns An atom that automatically updates when query results change.
+ */
+export const fromQuery = <T extends Entity.Unknown>(queryResult: QueryResult.QueryResult<T>): Atom.Atom<T[]> =>
+  Atom.make((get) => {
+    // TODO(wittjosiah): Consider subscribing to individual objects here as well, and grabbing their snapshots.
+    // Subscribe to QueryResult changes.
+    const unsubscribe = queryResult.subscribe(() => {
+      get.setSelf(queryResult.results);
+    });
+
+    // Register cleanup for when atom is no longer used.
+    get.addFinalizer(unsubscribe);
+
+    return queryResult.results;
+  });
+
+// Registry: key → Queryable (WeakRef with auto-cleanup when GC'd).
+const queryableRegistry = new WeakDictionary<string, Database.Queryable>();
+
+// Atom.family keyed by "identifier:serializedAST".
+const queryFamily = Atom.family((key: string) => {
+  // Parse key outside Atom.make - runs once per key.
+  const separatorIndex = key.indexOf(':');
+  const identifier = key.slice(0, separatorIndex);
+  const serializedAst = key.slice(separatorIndex + 1);
+
+  // Get queryable outside Atom.make - keeps Queryable alive via closure.
+  const queryable = queryableRegistry.get(identifier);
+  if (!queryable) {
+    return Atom.make(() => [] as Entity.Unknown[]);
+  }
+
+  // Create query outside Atom.make - runs once, not on every recompute.
+  const ast = JSON.parse(serializedAst);
+  const queryResult = queryable.query(Query.fromAst(ast)) as QueryResult.QueryResult<Entity.Unknown>;
+
+  return Atom.make((get) => {
+    const unsubscribe = queryResult.subscribe(() => {
+      get.setSelf(queryResult.results);
+    });
+    get.addFinalizer(unsubscribe);
+
+    return queryResult.results;
+  });
+});
+
+/**
+ * Derive a stable identifier from a Queryable.
+ * Supports Database (spaceId), Queue (dxn), and objects with id.
+ */
+const getQueryableIdentifier = (queryable: Database.Queryable): string => {
+  // Database: use spaceId.
+  if (Database.isDatabase(queryable)) {
+    return queryable.spaceId;
+  }
+  // Queue or similar: use dxn if it's a DXN instance.
+  if ('dxn' in queryable && queryable.dxn instanceof DXN) {
+    return queryable.dxn.toString();
+  }
+  // Fallback: use id if it's a string.
+  if ('id' in queryable && typeof queryable.id === 'string') {
+    return queryable.id;
+  }
+  throw new Error('Unable to derive identifier from queryable.');
+};
+
+/**
+ * Get a memoized query atom for any Queryable (Database, Queue, etc.).
+ * Uses a single Atom.family keyed by queryable identifier + serialized query AST.
+ * Same queryable + query/filter = same atom instance (proper memoization).
+ *
+ * @param queryable - The queryable to query (Database, Queue, etc.).
+ * @param queryOrFilter - A Query or Filter to execute.
+ * @returns A memoized atom that updates when query results change.
+ */
+export const make = <T extends Entity.Unknown>(
+  queryable: Database.Queryable,
+  queryOrFilter: Query.Query<T> | Filter.Filter<T>,
+): Atom.Atom<T[]> => {
+  const identifier = getQueryableIdentifier(queryable);
+  return fromQueryable(queryable, identifier, queryOrFilter);
+};
+
+/**
+ * Internal: Get a memoized query atom for any Queryable with a custom identifier.
+ */
+const fromQueryable = <T extends Entity.Unknown>(
+  queryable: Database.Queryable,
+  identifier: string,
+  queryOrFilter: Query.Query<T> | Filter.Filter<T>,
+): Atom.Atom<T[]> => {
+  // Register queryable in registry (WeakDictionary handles cleanup automatically).
+  queryableRegistry.set(identifier, queryable);
+
+  // Normalize to Query.
+  const normalizedQuery: Query.Any = Query.is(queryOrFilter)
+    ? queryOrFilter
+    : Query.select(queryOrFilter as Filter.Filter<T>);
+
+  // Build key: identifier:serializedAST.
+  const key = `${identifier}:${JSON.stringify(normalizedQuery.ast)}`;
+
+  return queryFamily(key) as Atom.Atom<T[]>;
+};

package/src/reactivity.test.ts

@@ -0,0 +1,158 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { describe, expect, test } from 'vitest';
+
+import { Obj } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { createObject } from '@dxos/echo-db';
+
+import * as AtomObj from './atom';
+
+describe('Echo Atom - Reactivity', () => {
+  test('atom updates when Echo object is mutated', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.make(obj);
+
+    // Returns a snapshot (plain object), not the Echo object itself.
+    const initialSnapshot = registry.get(atom);
+    expect(initialSnapshot.name).toBe('Test');
+
+    // Subscribe to enable reactivity.
+    registry.subscribe(atom, () => {});
+
+    // Update the object via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    const updatedSnapshot = registry.get(atom);
+    expect(updatedSnapshot.name).toBe('Updated');
+  });
+
+  test('property atom updates when its property is mutated', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.makeProperty(obj, 'name');
+
+    expect(registry.get(atom)).toBe('Test');
+
+    // Subscribe to enable reactivity.
+    registry.subscribe(atom, () => {});
+
+    // Update the property via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    expect(registry.get(atom)).toBe('Updated');
+  });
+
+  test('property atom does NOT update when other properties change', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const nameAtom = AtomObj.makeProperty(obj, 'name');
+    const emailAtom = AtomObj.makeProperty(obj, 'email');
+
+    const initialName = registry.get(nameAtom);
+    const initialEmail = registry.get(emailAtom);
+    expect(initialName).toBe('Test');
+    expect(initialEmail).toBe('test@example.com');
+
+    // Subscribe to enable reactivity.
+    let nameUpdateCount = 0;
+    let emailUpdateCount = 0;
+    registry.subscribe(nameAtom, () => {
+      nameUpdateCount++;
+    });
+    registry.subscribe(emailAtom, () => {
+      emailUpdateCount++;
+    });
+
+    // Update only email property via Obj.change.
+    Obj.change(obj, (o) => {
+      o.email = 'updated@example.com';
+    });
+
+    // Name atom should NOT have changed.
+    expect(registry.get(nameAtom)).toBe('Test');
+    expect(nameUpdateCount).toBe(0);
+
+    // Email atom should have changed.
+    expect(registry.get(emailAtom)).toBe('updated@example.com');
+    expect(emailUpdateCount).toBe(1);
+  });
+
+  test('multiple property updates on same object update respective atoms', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const nameAtom = AtomObj.makeProperty(obj, 'name');
+    const emailAtom = AtomObj.makeProperty(obj, 'email');
+
+    // Subscribe to enable reactivity.
+    registry.subscribe(nameAtom, () => {});
+    registry.subscribe(emailAtom, () => {});
+
+    // Update multiple properties via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+      o.email = 'updated@example.com';
+    });
+
+    expect(registry.get(nameAtom)).toBe('Updated');
+    expect(registry.get(emailAtom)).toBe('updated@example.com');
+  });
+
+  test('direct object mutations flow through to atoms', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+
+    const registry = Registry.make();
+    const atom = AtomObj.make(obj);
+
+    let updateCount = 0;
+    registry.subscribe(
+      atom,
+      () => {
+        updateCount++;
+      },
+      { immediate: true },
+    );
+
+    // Get initial count (immediate: true causes initial update).
+    const initialCount = updateCount;
+    expect(initialCount).toBe(1);
+
+    // Update object via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+    Obj.change(obj, (o) => {
+      o.email = 'updated@example.com';
+    });
+
+    // Updates fire through Obj.subscribe (one per Obj.change call).
+    expect(updateCount).toBe(initialCount + 2);
+
+    // Verify final state - returns snapshot (plain object).
+    const finalSnapshot = registry.get(atom);
+    expect(finalSnapshot.name).toBe('Updated');
+    expect(finalSnapshot.email).toBe('updated@example.com');
+  });
+});

package/src/ref-atom.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+
+import { type Entity, type Ref } from '@dxos/echo';
+
+import { loadRefTarget } from './ref-utils';
+
+/**
+ * Create an atom for a reference target that returns the live object when loaded.
+ * 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.
+ */
+export function make<T extends Entity.Unknown>(ref: Ref.Ref<T> | undefined): Atom.Atom<T | undefined> {
+  if (!ref) {
+    return Atom.make<T | undefined>(() => undefined);
+  }
+
+  return Atom.make<T | undefined>((get) => {
+    return loadRefTarget(ref, get, (target) => target);
+  });
+}

package/src/ref-utils.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+
+import type { Ref } from '@dxos/echo';
+
+/**
+ * Internal helper for loading ref targets in atoms.
+ * Handles the common pattern of checking for loaded target and triggering async load.
+ *
+ * @param ref - The ref to load.
+ * @param get - The atom context for setSelf.
+ * @param onTargetAvailable - Callback invoked when target is available (sync or async).
+ *   Should return the value to use for the atom.
+ * @returns The result of onTargetAvailable if target is already loaded, undefined otherwise.
+ */
+export const loadRefTarget = <T, R>(
+  ref: Ref.Ref<T>,
+  get: Atom.Context,
+  onTargetAvailable: (target: T) => R,
+): R | undefined => {
+  const currentTarget = ref.target;
+  if (currentTarget) {
+    return onTargetAvailable(currentTarget);
+  }
+
+  // Target not loaded yet - trigger async load.
+  void ref
+    .load()
+    .then((loadedTarget) => {
+      get.setSelf(onTargetAvailable(loadedTarget));
+    })
+    .catch(() => {
+      // Loading failed, keep target as undefined.
+    });
+
+  return undefined;
+};