@dxos/echo-react 0.0.0 → 0.8.4-main.69d29f4

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo-react",
-  "version": "0.0.0",
+  "version": "0.8.4-main.69d29f4",
   "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,
@@ -25,18 +29,18 @@
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom-react": "^0.4.4",
-    "@dxos/echo": "0.8.3",
-    "@dxos/echo-atom": "0.0.0"
+    "@effect-atom/atom": "^0.4.13",
+    "@effect-atom/atom-react": "^0.4.6",
+    "@dxos/echo-atom": "0.8.4-main.69d29f4",
+    "@dxos/echo": "0.8.4-main.69d29f4"
   },
   "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.69d29f4"
   },
   "peerDependencies": {
     "react": "~19.2.3"

package/src/useObject.ts

@@ -2,18 +2,21 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Atom from '@effect-atom/atom/Atom';
 import { useAtomValue } from '@effect-atom/atom-react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+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,7 +123,7 @@ export const useObject: {
       if (obj === undefined) {
         return;
       }
-      Obj.change(obj as Entity.Unknown, (o: any) => {
+      Obj.change(obj, (o: any) => {
         if (typeof updateOrValue === 'function') {
           const returnValue = updateOrValue(property !== undefined ? o[property] : o);
           if (returnValue !== undefined) {
@@ -113,7 +147,7 @@ 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];
   }
   return [useObjectValue(objOrRef), callback];
 }) as any;
@@ -122,16 +156,16 @@ export const useObject: {
  * 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 +184,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);