@dxos/echo-react 0.8.4-main.fcfe5033a5 → 0.8.4-staging.60fe92afc8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/echo-react",
-  "version": "0.8.4-main.fcfe5033a5",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "React integration for ECHO.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": false,
   "type": "module",
@@ -20,18 +20,14 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom": "^0.5.1",
+    "@effect-atom/atom": "^0.5.3",
     "@effect-atom/atom-react": "^0.5.0",
-    "@dxos/echo": "0.8.4-main.fcfe5033a5",
-    "@dxos/echo-atom": "0.8.4-main.fcfe5033a5"
+    "@dxos/echo": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",
@@ -39,7 +35,7 @@
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/echo-db": "0.8.4-main.fcfe5033a5"
+    "@dxos/echo-client": "0.8.4-staging.60fe92afc8"
   },
   "peerDependencies": {
     "react": "~19.2.3"

package/src/index.ts

@@ -3,5 +3,5 @@
 //
 
 export * from './useQuery';
-export * from './useSchema';
+export * from './useType';
 export * from './useObject';

package/src/useObject.test.tsx

@@ -9,7 +9,7 @@ import React, { type PropsWithChildren } from 'react';
 import { describe, expect, test } from 'vitest';
 
 import { Obj, Ref } from '@dxos/echo';
-import { createObject } from '@dxos/echo-db';
+import { createObject } from '@dxos/echo-client';
 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,11 +58,10 @@ 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, (obj) => {
+    // Update the property via Obj.update
+    Obj.update(obj, (obj) => {
       obj.name = 'Updated';
     });
 
@@ -81,11 +79,10 @@ 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, (obj) => {
+    // Update a property via Obj.update
+    Obj.update(obj, (obj) => {
       obj.name = 'Updated';
     });
 
@@ -103,11 +100,10 @@ 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, (obj) => {
+    // Update a different property via Obj.update
+    Obj.update(obj, (obj) => {
       obj.email = 'newemail@example.com';
     });
 
@@ -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.
@@ -262,7 +252,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result, rerender } = renderHook(() => useObject(obj), { wrapper });
-
     const [firstSnapshot] = result.current;
     expect(firstSnapshot).toBeDefined();
 
@@ -286,7 +275,6 @@ describe('useObject', () => {
     const wrapper = createWrapper(registry);
 
     const { result, rerender } = renderHook(() => useObject(person.employer!), { wrapper });
-
     const [firstSnapshot] = result.current;
     expect(firstSnapshot).toBeDefined();
 

package/src/useObject.ts

@@ -7,7 +7,6 @@ import * as Atom from '@effect-atom/atom/Atom';
 import { useCallback, useMemo } from 'react';
 
 import { Obj, Ref } from '@dxos/echo';
-import { AtomObj } from '@dxos/echo-atom';
 
 export interface ObjectUpdateCallback<T> {
   (update: (obj: Obj.Mutable<T>) => void): void;
@@ -123,7 +122,7 @@ export const useObject: {
       if (obj === undefined) {
         return;
       }
-      Obj.change(obj, (obj: any) => {
+      Obj.update(obj, (obj: any) => {
         if (typeof updateOrValue === 'function') {
           const returnValue = updateOrValue(property !== undefined ? obj[property] : obj);
           if (returnValue !== undefined) {
@@ -144,32 +143,60 @@ export const useObject: {
   );
 
   if (property !== undefined) {
-    // 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);
+    // For refs, subscribe to load event only (not full mutation tracking).
+    // Property-level updates are handled by useObjectProperty once the ref loads.
+    useRefLoad(objOrRef);
     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 Obj.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): Obj.Snapshot<T> | undefined => {
-  const atom = useMemo(() => AtomObj.make(objOrRef), [objOrRef]);
+  const atom = useMemo(() => {
+    if (objOrRef == null) {
+      return Atom.make<Obj.Snapshot<T> | undefined>(() => undefined);
+    }
+    if (Ref.isRef(objOrRef)) {
+      return Obj.atom(objOrRef);
+    }
+    return Obj.atom(objOrRef);
+  }, [objOrRef]);
   return useAtomValue(atom) as Obj.Snapshot<T> | undefined;
 };
 
+/**
+ * Internal hook for subscribing to ref resolution only (load-once).
+ * Triggers a re-render when the ref target first becomes available,
+ * without subscribing to subsequent target mutations.
+ * For non-refs, this is a no-op.
+ */
+const useRefLoad = <T extends Obj.Unknown>(objOrRef: T | Ref.Ref<T> | undefined): void => {
+  const atom = useMemo(() => {
+    if (objOrRef == null || !Ref.isRef(objOrRef)) {
+      return Atom.make<T | undefined>(() => undefined);
+    }
+    return objOrRef.atom;
+  }, [objOrRef]);
+  useAtomValue(atom);
+};
+
 /**
  * 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 Obj.Unknown, K extends keyof T>(
   obj: T | undefined,
   property: K,
 ): T[K] | undefined => {
-  const atom = useMemo(() => AtomObj.makeProperty(obj, property), [obj, property]);
+  const atom = useMemo(() => {
+    if (obj == null) {
+      return Atom.make<T[K] | undefined>(() => undefined);
+    }
+    return Obj.atomProperty(obj, property);
+  }, [obj, property]);
   return useAtomValue(atom);
 };
 
@@ -190,7 +217,7 @@ export const useObjects = <T extends Obj.Unknown>(refs: readonly Ref.Ref<T>[]):
       Atom.make((get) => {
         const results: Obj.Snapshot<T>[] = [];
         for (const ref of refs) {
-          const value = get(AtomObj.make(ref));
+          const value = get(Obj.atom(ref));
           if (value !== undefined) {
             results.push(value as Obj.Snapshot<T>);
           }

package/src/useQuery.__test.tsx

@@ -8,8 +8,7 @@
 import { renderHook } from '@testing-library/react';
 import { describe, expect, test } from 'vitest';
 
-import { Filter } from '@dxos/client/echo';
-import { Obj, Type } from '@dxos/echo';
+import { Filter, Obj, Type } from '@dxos/echo';
 import { TestSchema } from '@dxos/echo/testing';
 
 import { createClient, createClientContextProvider } from '../testing/util';

package/src/useType.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo, useSyncExternalStore } from 'react';
+
+import { DXN, EID, URI, type Database, Filter, Query, Scope, Type } from '@dxos/echo';
+
+/**
+ * Subscribe to and retrieve a type by its URI from a space: a static schema's typename DXN, or a
+ * persisted (database) schema's `echo:` EID (what `Type.getURI` / `getTypeURIFromQuery` produce).
+ *
+ * Fans across the owning space db (persisted custom types) and the shared
+ * registry (static/runtime plugin types). Persisted types live only in the db,
+ * so a registry-only lookup misses them.
+ *
+ * DXN matching is version-agnostic: `dxn:com.example/Foo` matches `dxn:com.example/Foo:0.1.0`.
+ * This lets callers pass a bare typename DXN (no version) from e.g. a `ReferenceAnnotation`.
+ */
+export const useType = <T extends Type.AnyEntity = Type.AnyEntity>(
+  db?: Database.Database,
+  typeUri?: URI.URI,
+): T | undefined => {
+  const { subscribe, getType } = useMemo(() => {
+    if (!typeUri || !db) {
+      return {
+        subscribe: () => () => {},
+        getType: (): T | undefined => undefined,
+      };
+    }
+
+    const searchEid = EID.isEID(typeUri) ? EID.tryParse(typeUri) : undefined;
+    const searchDxn = DXN.isDXN(typeUri) ? DXN.tryMake(typeUri) : undefined;
+
+    const queryResult = db.query(Query.select(Filter.type(Type.Type)).from(Scope.space(), Scope.registry()));
+    let subscribed = false;
+    const find = (): T | undefined => {
+      if (!subscribed) {
+        return undefined;
+      }
+      return queryResult.results.find((type) => {
+        const uri = Type.getURI(type);
+        if (uri === typeUri) {
+          return true;
+        }
+        // EID matching is space-agnostic: echo:/<id> matches echo://<space>/<id>.
+        if (searchEid && EID.isEID(uri)) {
+          const typeEid = EID.tryParse(uri);
+          return typeEid != null && EID.getEntityId(typeEid) === EID.getEntityId(searchEid);
+        }
+        // DXN matching is version-agnostic so callers may pass an unversioned DXN.
+        if (searchDxn && DXN.isDXN(uri)) {
+          const typeDxn = DXN.tryMake(uri);
+          return typeDxn != null && DXN.getName(typeDxn) === DXN.getName(searchDxn);
+        }
+        return false;
+      }) as T | undefined;
+    };
+
+    return {
+      subscribe: (onStoreChange: () => void) => {
+        subscribed = true;
+        const unsubscribe = queryResult.subscribe(onStoreChange);
+        return () => {
+          unsubscribe();
+          subscribed = false;
+        };
+      },
+      getType: find,
+    };
+  }, [typeUri, db]);
+
+  return useSyncExternalStore(subscribe, getType);
+};

package/dist/types/src/useSchema.d.ts

@@ -1,6 +0,0 @@
-import { type Database, type Type } from '@dxos/echo';
-/**
- * Subscribe to and retrieve schema changes from a space's schema registry.
- */
-export declare const useSchema: <T extends Type.AnyEntity = Type.AnyEntity>(db?: Database.Database, typename?: string) => T | undefined;
-//# sourceMappingURL=useSchema.d.ts.map

package/dist/types/src/useSchema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useSchema.d.ts","sourceRoot":"","sources":["../../../src/useSchema.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,SAAS,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,EACjE,KAAK,QAAQ,CAAC,QAAQ,EACtB,WAAW,MAAM,KAChB,CAAC,GAAG,SA2BN,CAAC"}

package/src/useSchema.ts

@@ -1,42 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useMemo, useSyncExternalStore } from 'react';
-
-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.AnyEntity = Type.AnyEntity>(
-  db?: Database.Database,
-  typename?: string,
-): T | undefined => {
-  const { subscribe, getSchema } = useMemo(() => {
-    if (!typename || !db) {
-      return {
-        subscribe: () => () => {},
-        getSchema: () => undefined,
-      };
-    }
-
-    const query = db.schemaRegistry.query({ typename, location: ['database', 'runtime'] });
-    const initialResult = query.runSync()[0];
-    let currentSchema = initialResult;
-
-    return {
-      subscribe: (onStoreChange: () => void) => {
-        const unsubscribe = query.subscribe(() => {
-          currentSchema = query.results[0];
-          onStoreChange();
-        });
-
-        return unsubscribe;
-      },
-      getSchema: () => currentSchema,
-    };
-  }, [typename, db]);
-
-  return useSyncExternalStore(subscribe, getSchema) as T;
-};