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

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo-react",
-  "version": "0.0.0",
+  "version": "0.8.4-main.03d5cd7b56",
   "description": "React integration for ECHO.",
   "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,27 @@
     ".": {
       "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-react": "^0.4.4",
-    "@dxos/echo": "0.8.3",
-    "@dxos/echo-atom": "0.0.0"
+    "@effect-atom/atom": "^0.5.1",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@dxos/echo": "0.8.4-main.03d5cd7b56",
+    "@dxos/echo-atom": "0.8.4-main.03d5cd7b56"
   },
   "devDependencies": {
-    "@effect-atom/atom": "^0.4.10",
     "@testing-library/react": "^16.3.0",
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/echo-db": "0.8.3"
+    "@dxos/echo-db": "0.8.4-main.03d5cd7b56"
   },
   "peerDependencies": {
     "react": "~19.2.3"

package/src/useObject.test.tsx

@@ -2,15 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Registry from '@effect-atom/atom/Registry';
 import { RegistryContext } from '@effect-atom/atom-react';
+import * as Registry from '@effect-atom/atom/Registry';
 import { renderHook, waitFor } from '@testing-library/react';
 import React, { type PropsWithChildren } from 'react';
 import { 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 { TestSchema } from '@dxos/echo/testing';
 
 import { useObject } from './useObject';
 
@@ -46,7 +46,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     const [value] = result.current;
     expect(value).toBe('Test');
   });
@@ -59,12 +58,11 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     expect(result.current[0]).toBe('Test');
 
-    // Update the property via Obj.change
-    Obj.change(obj, (o) => {
-      o.name = 'Updated';
+    // Update the property via Obj.update
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated';
     });
 
     // Wait for reactivity to update
@@ -81,12 +79,11 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj), { wrapper });
-
     expect(result.current[0].name).toBe('Test');
 
-    // Update a property via Obj.change
-    Obj.change(obj, (o) => {
-      o.name = 'Updated';
+    // Update a property via Obj.update
+    Obj.update(obj, (obj) => {
+      obj.name = 'Updated';
     });
 
     // Wait for reactivity to update
@@ -103,12 +100,11 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     expect(result.current[0]).toBe('Test');
 
-    // Update a different property via Obj.change
-    Obj.change(obj, (o) => {
-      o.email = 'newemail@example.com';
+    // Update a different property via Obj.update
+    Obj.update(obj, (obj) => {
+      obj.email = 'newemail@example.com';
     });
 
     // Wait a bit to ensure no update happens
@@ -142,7 +138,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj), { wrapper });
-
     const [value, updateCallback] = result.current;
     expect(value.name).toBe('Test');
 
@@ -165,7 +160,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     const [value, updateCallback] = result.current;
     expect(value).toBe('Test');
 
@@ -186,7 +180,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     const [value, updateCallback] = result.current;
     expect(value).toBe('Test');
 
@@ -207,7 +200,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result, rerender } = renderHook(() => useObject(obj, 'name'), { wrapper });
-
     const [, firstUpdateCallback] = result.current;
 
     rerender();
@@ -233,7 +225,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(undefined as TestSchema.Person | undefined, 'name'), { wrapper });
-
     const [value] = result.current;
     expect(value).toBeUndefined();
   });
@@ -243,7 +234,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result } = renderHook(() => useObject(undefined as TestSchema.Person | undefined), { wrapper });
-
     const [, updateCallback] = result.current;
 
     // Should not throw when calling update on undefined object.
@@ -254,6 +244,46 @@ describe('useObject', () => {
     }).not.toThrow();
   });
 
+  test('snapshot is referentially stable across re-renders for object', ({ expect }) => {
+    const obj: TestSchema.Person = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const wrapper = createWrapper(registry);
+
+    const { result, rerender } = renderHook(() => useObject(obj), { wrapper });
+    const [firstSnapshot] = result.current;
+    expect(firstSnapshot).toBeDefined();
+
+    rerender();
+
+    const [secondSnapshot] = result.current;
+    expect(secondSnapshot).toBe(firstSnapshot);
+  });
+
+  test('snapshot is referentially stable across re-renders for ref', ({ expect }) => {
+    const org: TestSchema.Organization = createObject(Obj.make(TestSchema.Organization, { name: 'DXOS' }));
+    const person: TestSchema.Person = createObject(
+      Obj.make(TestSchema.Person, {
+        name: 'Test',
+        username: 'test',
+        email: 'test@example.com',
+        employer: Ref.make(org),
+      }),
+    );
+    const registry = Registry.make();
+    const wrapper = createWrapper(registry);
+
+    const { result, rerender } = renderHook(() => useObject(person.employer!), { wrapper });
+    const [firstSnapshot] = result.current;
+    expect(firstSnapshot).toBeDefined();
+
+    rerender();
+
+    const [secondSnapshot] = result.current;
+    expect(secondSnapshot).toBe(firstSnapshot);
+  });
+
   test('transitions from undefined to defined object', async () => {
     const registry = Registry.make();
     const wrapper = createWrapper(registry);

package/src/useObject.ts

@@ -3,17 +3,20 @@
 //
 
 import { useAtomValue } from '@effect-atom/atom-react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import * as Atom from '@effect-atom/atom/Atom';
+import { useCallback, useMemo } from 'react';
 
-import { type Entity, Obj, Ref } from '@dxos/echo';
+import { Obj, Ref } from '@dxos/echo';
 import { AtomObj } from '@dxos/echo-atom';
 
 export interface ObjectUpdateCallback<T> {
-  (update: (obj: T) => void): void;
-  (update: (obj: T) => T): void;
+  (update: (obj: Obj.Mutable<T>) => void): void;
+  (update: (obj: Obj.Mutable<T>) => Obj.Mutable<T>): void;
 }
 
-export interface ObjectPropUpdateCallback<T> extends ObjectUpdateCallback<T> {
+export interface ObjectPropUpdateCallback<T> {
+  (update: (value: Obj.Mutable<T>) => void): void;
+  (update: (value: Obj.Mutable<T>) => Obj.Mutable<T>): void;
   (newValue: T): void;
 }
 
@@ -21,63 +24,94 @@ export const useObject: {
   /**
    * Hook to subscribe to a Ref's target object.
    * Automatically dereferences the ref and handles async loading.
-   * Returns undefined if the ref hasn't loaded yet.
+   * Returns a snapshot (undefined if the ref hasn't loaded yet).
    *
    * @param ref - The Ref to dereference and subscribe to
-   * @returns The current target value (or undefined if not loaded) and update callback
+   * @returns The current target snapshot (or undefined if not loaded) and update callback
    */
-  <T>(ref: Ref.Ref<T>): [Readonly<T> | undefined, ObjectUpdateCallback<T>];
+  <T extends Obj.Unknown>(ref: Ref.Ref<T>): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
   /**
    * Hook to subscribe to a Ref's target object that may be undefined.
-   * Returns undefined if the ref is undefined or hasn't loaded yet.
+   * Returns a snapshot (undefined if the ref is undefined or hasn't loaded yet).
    *
    * @param ref - The Ref to dereference and subscribe to (can be undefined)
-   * @returns The current target value (or undefined) and update callback
+   * @returns The current target snapshot (or undefined) and update callback
    */
-  <T>(ref: Ref.Ref<T> | undefined): [Readonly<T> | undefined, ObjectUpdateCallback<T>];
+  <T extends Obj.Unknown>(ref: Ref.Ref<T> | undefined): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
   /**
    * Hook to subscribe to an entire Echo object.
-   * Returns the current object value and automatically re-renders when the object changes.
+   * Returns a snapshot of the current object value and automatically re-renders when the object changes.
    *
-   * @param obj - The Echo object to subscribe to
-   * @returns The current object value and update callback
+   * @param obj - The Echo object to subscribe to (objects only, not relations)
+   * @returns The current object snapshot and update callback
    */
-  <T extends Entity.Unknown>(obj: T): [Readonly<T>, ObjectUpdateCallback<T>];
+  <T extends Obj.Unknown>(obj: T): [Obj.Snapshot<T>, ObjectUpdateCallback<T>];
 
   /**
    * Hook to subscribe to an entire Echo object that may be undefined.
-   * Returns undefined if the object is undefined.
+   * Returns a snapshot (undefined if the object is undefined).
+   *
+   * @param obj - The Echo object to subscribe to (can be undefined, objects only)
+   * @returns The current object snapshot (or undefined) and update callback
+   */
+  <T extends Obj.Unknown>(obj: T | undefined): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
+
+  /**
+   * Hook to subscribe to an Echo object or Ref.
+   * Handles both cases - if passed a Ref, dereferences it and subscribes to the target.
+   * Returns a snapshot (undefined if ref hasn't loaded).
    *
-   * @param obj - The Echo object to subscribe to (can be undefined)
-   * @returns The current object value (or undefined) and update callback
+   * @param objOrRef - The Echo object or Ref to subscribe to
+   * @returns The current object snapshot (or undefined) and update callback
    */
-  <T extends Entity.Unknown>(obj: T | undefined): [Readonly<T> | undefined, ObjectUpdateCallback<T>];
+  <T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T>): [Obj.Snapshot<T> | undefined, ObjectUpdateCallback<T>];
 
   /**
    * Hook to subscribe to a specific property of an Echo object.
    * Returns the current property value and automatically re-renders when the property changes.
    *
-   * @param obj - The Echo object to subscribe to
+   * @param obj - The Echo object to subscribe to (objects only, not relations)
    * @param property - Property key to subscribe to
    * @returns The current property value and update callback
    */
-  <T extends Entity.Unknown, K extends keyof T>(obj: T, property: K): [Readonly<T[K]>, ObjectPropUpdateCallback<T[K]>];
+  <T extends Obj.Unknown, K extends keyof T>(obj: T, property: K): [T[K], ObjectPropUpdateCallback<T[K]>];
 
   /**
    * Hook to subscribe to a specific property of an Echo object that may be undefined.
    * Returns undefined if the object is undefined.
    *
-   * @param obj - The Echo object to subscribe to (can be undefined)
+   * @param obj - The Echo object to subscribe to (can be undefined, objects only)
    * @param property - Property key to subscribe to
    * @returns The current property value (or undefined) and update callback
    */
-  <T extends Entity.Unknown, K extends keyof T>(
+  <T extends Obj.Unknown, K extends keyof T>(
     obj: T | undefined,
     property: K,
-  ): [Readonly<T[K]> | undefined, ObjectPropUpdateCallback<T[K]>];
-} = (<T extends Entity.Unknown, K extends keyof T>(objOrRef: T | Ref.Ref<T> | undefined, property?: K): any => {
+  ): [T[K] | undefined, ObjectPropUpdateCallback<T[K]>];
+
+  /**
+   * Hook to subscribe to a specific property of a Ref's target object.
+   * Automatically dereferences the ref and handles async loading.
+   * Returns undefined if the ref hasn't loaded yet.
+   *
+   * @param ref - The Ref to dereference and subscribe to
+   * @param property - Property key to subscribe to
+   * @returns The current property value (or undefined if not loaded) and update callback
+   */
+  <T, K extends keyof T>(ref: Ref.Ref<T>, property: K): [T[K] | undefined, ObjectPropUpdateCallback<T[K]>];
+
+  /**
+   * Hook to subscribe to a specific property of a Ref's target object that may be undefined.
+   * Returns undefined if the ref is undefined or hasn't loaded yet.
+   *
+   * @param ref - The Ref to dereference and subscribe to (can be undefined)
+   * @param property - Property key to subscribe to
+   * @returns The current property value (or undefined) and update callback
+   */
+  <T, K extends keyof T>(ref: Ref.Ref<T> | undefined, property: K): [T[K] | undefined, ObjectPropUpdateCallback<T[K]>];
+} = (<T extends Obj.Unknown, K extends keyof T>(objOrRef: T | Ref.Ref<T> | undefined, property?: K): any => {
   // Get the live object for the callback (refs need to dereference).
   const isRef = Ref.isRef(objOrRef);
   const liveObj = isRef ? (objOrRef as Ref.Ref<T>)?.target : (objOrRef as T | undefined);
@@ -89,20 +123,20 @@ export const useObject: {
       if (obj === undefined) {
         return;
       }
-      Obj.change(obj as Entity.Unknown, (o: any) => {
+      Obj.update(obj, (obj: any) => {
         if (typeof updateOrValue === 'function') {
-          const returnValue = updateOrValue(property !== undefined ? o[property] : o);
+          const returnValue = updateOrValue(property !== undefined ? obj[property] : obj);
           if (returnValue !== undefined) {
             if (property === undefined) {
               throw new Error('Cannot re-assign the entire object');
             }
-            o[property] = returnValue;
+            obj[property] = returnValue;
           }
         } else {
           if (property === undefined) {
             throw new Error('Cannot re-assign the entire object');
           }
-          o[property] = updateOrValue;
+          obj[property] = updateOrValue;
         }
       });
     },
@@ -113,25 +147,26 @@ export const useObject: {
     // For property subscriptions on refs, we subscribe to trigger re-render on load.
     // TODO(dxos): Property subscriptions on refs may not update correctly until the ref loads.
     useObjectValue(objOrRef);
-    return [useObjectProperty(liveObj as Entity.Unknown | undefined, property as any), callback];
+    return [useObjectProperty(liveObj, property as any), callback];
+  } else {
+    return [useObjectValue(objOrRef), callback];
   }
-  return [useObjectValue(objOrRef), callback];
 }) as any;
 
 /**
  * Internal hook for subscribing to an Echo object or Ref.
  * AtomObj.make handles both objects and refs, returning snapshots.
  */
-const useObjectValue = <T extends Entity.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): T | undefined => {
+const useObjectValue = <T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): Obj.Snapshot<T> | undefined => {
   const atom = useMemo(() => AtomObj.make(objOrRef), [objOrRef]);
-  return useAtomValue(atom);
+  return useAtomValue(atom) as Obj.Snapshot<T> | undefined;
 };
 
 /**
  * Internal hook for subscribing to a specific property of an Echo object.
  * Uses useAtomValue directly since makeProperty returns the value directly.
  */
-const useObjectProperty = <T extends Entity.Unknown, K extends keyof T>(
+const useObjectProperty = <T extends Obj.Unknown, K extends keyof T>(
   obj: T | undefined,
   property: K,
 ): T[K] | undefined => {
@@ -150,66 +185,20 @@ const useObjectProperty = <T extends Entity.Unknown, K extends keyof T>(
  * @param refs - Array of Refs to dereference and subscribe to
  * @returns Array of loaded target snapshots (excludes unloaded refs)
  */
-export const useObjects = <T extends Entity.Unknown>(refs: Ref.Ref<T>[]): Readonly<T>[] => {
-  // Track version to trigger re-renders when any ref or target changes.
-  const [, setVersion] = useState(0);
-
-  // Subscribe to all refs and their targets.
-  useEffect(() => {
-    let isMounted = true;
-    const targetUnsubscribes = new Map<string, () => void>();
-
-    // Function to trigger re-render.
-    const triggerUpdate = () => {
-      if (isMounted) {
-        setVersion((v) => v + 1);
-      }
-    };
-
-    // Function to set up subscription for a target.
-    const subscribeToTarget = (ref: Ref.Ref<T>) => {
-      if (!isMounted) return;
-      const target = ref.target;
-      if (target) {
-        const key = ref.dxn.toString();
-        if (!targetUnsubscribes.has(key)) {
-          targetUnsubscribes.set(key, Obj.subscribe(target, triggerUpdate));
+export const useObjects = <T extends Obj.Unknown>(refs: readonly Ref.Ref<T>[]): Obj.Snapshot<T>[] => {
+  const atom = useMemo(
+    () =>
+      Atom.make((get) => {
+        const results: Obj.Snapshot<T>[] = [];
+        for (const ref of refs) {
+          const value = get(AtomObj.make(ref));
+          if (value !== undefined) {
+            results.push(value as Obj.Snapshot<T>);
+          }
         }
-      }
-    };
-
-    // Try to load all refs and subscribe to targets.
-    for (const ref of refs) {
-      // Subscribe to existing target if available.
-      subscribeToTarget(ref);
-
-      // Trigger async load if not already loaded.
-      if (!ref.target) {
-        void ref
-          .load()
-          .then(() => {
-            subscribeToTarget(ref);
-            triggerUpdate();
-          })
-          .catch(() => {
-            // Ignore load errors.
-          });
-      }
-    }
-
-    return () => {
-      isMounted = false;
-      targetUnsubscribes.forEach((u) => u());
-    };
-  }, [refs]);
-
-  // Compute current snapshots by reading each ref's target.
-  const snapshots: Readonly<T>[] = [];
-  for (const ref of refs) {
-    const target = ref.target;
-    if (target !== undefined) {
-      snapshots.push(target as Readonly<T>);
-    }
-  }
-  return snapshots;
+        return results;
+      }),
+    [refs],
+  );
+  return useAtomValue(atom);
 };

package/src/useQuery.__test.tsx

@@ -10,6 +10,7 @@ import { describe, expect, test } from 'vitest';
 
 import { Filter } from '@dxos/client/echo';
 import { Obj, Type } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
 
 import { createClient, createClientContextProvider } from '../testing/util';
 
@@ -23,9 +24,9 @@ describe('useQuery', () => {
     const wrapper = await createClientContextProvider(client);
 
     // Create 3 test objects: Alice, Bob, Charlie.
-    const alice = Obj.make(Type.Expando, { name: 'Alice' });
-    const bob = Obj.make(Type.Expando, { name: 'Bob' });
-    const charlie = Obj.make(Type.Expando, { name: 'Charlie' });
+    const alice = Obj.make(TestSchema.Expando, { name: 'Alice' });
+    const bob = Obj.make(TestSchema.Expando, { name: 'Bob' });
+    const charlie = Obj.make(TestSchema.Expando, { name: 'Charlie' });
 
     space!.db.add(alice);
     space!.db.add(bob);
@@ -38,7 +39,7 @@ describe('useQuery', () => {
     // Setup useQuery hook that captures every render.
     renderHook(
       () => {
-        const objects = useQuery(space?.db, Filter.type(Type.Expando));
+        const objects = useQuery(space?.db, Filter.type(TestSchema.Expando));
 
         // Capture the names in this render.
         const namesInThisRender = objects.map((obj) => obj.name);
@@ -85,7 +86,7 @@ describe('useQuery', () => {
     const wrapper = await createClientContextProvider(client);
 
     // Create 10 test objects: 1, 2, 3, ..., 10.
-    const objects = Array.from({ length: 10 }, (_, i) => Obj.make(Type.Expando, { value: i + 1 }));
+    const objects = Array.from({ length: 10 }, (_, i) => Obj.make(TestSchema.Expando, { value: i + 1 }));
 
     objects.forEach((obj) => space!.db.add(obj));
     await space!.db.flush();
@@ -96,7 +97,7 @@ describe('useQuery', () => {
     // Setup useQuery hook that captures every render.
     renderHook(
       () => {
-        const queryObjects = useQuery(space?.db, Filter.type(Type.Expando));
+        const queryObjects = useQuery(space?.db, Filter.type(TestSchema.Expando));
 
         // Capture the values in this render.
         const valuesInThisRender = queryObjects.map((obj) => obj.value);

package/src/useQuery.ts

@@ -24,6 +24,8 @@ interface UseQueryFn {
 
 /**
  * Create subscription.
+ *
+ * @param queryOrFilter - The query or filter to apply. Query is memoized based on the AST. No need to call useMemo.
  */
 export const useQuery: UseQueryFn = (
   resource: Database.Queryable | undefined,

package/src/useSchema.ts

@@ -9,7 +9,7 @@ import { type Database, type Type } from '@dxos/echo';
 /**
  * Subscribe to and retrieve schema changes from a space's schema registry.
  */
-export const useSchema = <T extends Type.Entity.Any = Type.Entity.Any>(
+export const useSchema = <T extends Type.AnyEntity = Type.AnyEntity>(
   db?: Database.Database,
   typename?: string,
 ): T | undefined => {