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

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/echo-solid",
-  "version": "0.0.0",
+  "version": "0.8.4-main.1c7ec43d41",
   "description": "Solid.js 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,33 +16,30 @@
     ".": {
       "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.5.1",
     "@solid-primitives/utils": "^6.3.2",
-    "@dxos/effect-atom-solid": "0.0.0",
-    "@dxos/echo-atom": "0.0.0",
-    "@dxos/echo": "0.8.3"
+    "@dxos/echo": "0.8.4-main.1c7ec43d41",
+    "@dxos/echo-atom": "0.8.4-main.1c7ec43d41",
+    "@dxos/effect-atom-solid": "0.8.4-main.1c7ec43d41"
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.10",
-    "solid-js": "^1.9.9",
-    "vite-plugin-solid": "^2.11.10",
-    "vitest": "3.2.4",
-    "@dxos/echo-db": "0.8.3"
+    "solid-js": "^1.9.11",
+    "vite-plugin-solid": "^2.11.12",
+    "vitest": "4.1.5",
+    "@dxos/echo-db": "0.8.4-main.1c7ec43d41"
   },
   "peerDependencies": {
-    "solid-js": "^1.9.9"
+    "solid-js": "^1.9.11"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -4,5 +4,4 @@
 
 export * from './useObject';
 export * from './useQuery';
-export * from './useRef';
 export * from './useSchema';

package/src/useObject.test.tsx

@@ -8,12 +8,12 @@ import { describe, expect, test } from 'vitest';
 
 import type { Entity } from '@dxos/echo';
 import { Obj } from '@dxos/echo';
-import { TestSchema } from '@dxos/echo/testing';
 import { createObject } from '@dxos/echo-db';
+import { TestSchema } from '@dxos/echo/testing';
 import { Registry } from '@dxos/effect-atom-solid';
 import { RegistryProvider } from '@dxos/effect-atom-solid';
 
-import { useObject } from './useObject';
+import { type ObjectUpdateCallback, useObject } from './useObject';
 
 const createWrapper = (registry: Registry.Registry) => {
   return (props: { children: JSX.Element }) => (
@@ -86,9 +86,9 @@ describe('useObject', () => {
     expect(result).toBe('Test');
     expect(getByTestId('value').textContent).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.
@@ -118,9 +118,9 @@ describe('useObject', () => {
     expect(valueAccessor?.()?.name).toBe('Test');
     expect(getByTestId('name').textContent).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.
@@ -149,9 +149,9 @@ describe('useObject', () => {
 
     expect(result).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';
     });
 
     // Name should still be 'Test'.
@@ -334,7 +334,7 @@ describe('useObject', () => {
     const registry = Registry.make();
     const Wrapper = createWrapper(registry);
 
-    let updatePerson: ((updater: (p: Entity.Entity<TestSchema.Person>) => void) => void) | undefined;
+    let updatePerson: ObjectUpdateCallback<TestSchema.Person> | undefined;
     const { getByTestId } = render(
       () => {
         const [value, update] = useObject(obj);

package/src/useObject.ts

@@ -5,16 +5,18 @@
 import { type MaybeAccessor, access } from '@solid-primitives/utils';
 import { type Accessor, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
 
-import { type Entity, Obj } from '@dxos/echo';
+import { Obj, Ref } from '@dxos/echo';
 import { AtomObj } from '@dxos/echo-atom';
 import { type Registry, useRegistry } from '@dxos/effect-atom-solid';
 
 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;
 }
 
@@ -29,17 +31,25 @@ type ConditionalUndefined<T, R> = [T] extends [Exclude<T, undefined>]
     : R; // Both T and R include undefined, return R as-is (no double undefined)
 
 /**
- * Subscribe to a specific property of an Echo object.
- * Returns the current property value accessor and an update callback.
+ * Subscribe to a Ref's target object.
+ * Automatically dereferences the ref and handles async loading.
+ * Returns undefined if the ref hasn't loaded yet.
  *
- * @param obj - The Echo object to subscribe to (can be reactive)
- * @param property - Property key to subscribe to
+ * @param ref - The Ref to dereference and subscribe to (can be reactive)
  * @returns A tuple of [accessor, updateCallback]
  */
-export function useObject<T extends Entity.Unknown | undefined, K extends keyof Exclude<T, undefined>>(
-  obj: MaybeAccessor<T>,
-  property: K,
-): [Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>, ObjectPropUpdateCallback<Exclude<T, undefined>[K]>];
+export function useObject<T>(ref: MaybeAccessor<Ref.Ref<T>>): [Accessor<T | undefined>, ObjectUpdateCallback<T>];
+
+/**
+ * Subscribe to 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/reactive)
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T>(
+  ref: MaybeAccessor<Ref.Ref<T> | undefined>,
+): [Accessor<T | undefined>, ObjectUpdateCallback<T>];
 
 /**
  * Subscribe to an entire Echo object.
@@ -48,108 +58,168 @@ export function useObject<T extends Entity.Unknown | undefined, K extends keyof
  * @param obj - The Echo object to subscribe to (can be reactive)
  * @returns A tuple of [accessor, updateCallback]
  */
-export function useObject<T extends Entity.Unknown>(
+export function useObject<T extends Obj.Unknown>(
   obj: MaybeAccessor<T>,
 ): [Accessor<ConditionalUndefined<T, T>>, ObjectUpdateCallback<T>];
-export function useObject<T extends Entity.Unknown | undefined>(
+
+/**
+ * Subscribe to an entire Echo object that may be undefined.
+ * Returns undefined if the object is undefined.
+ *
+ * @param obj - The Echo object to subscribe to (can be undefined/reactive)
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T extends Obj.Unknown>(
+  obj: MaybeAccessor<T | undefined>,
+): [Accessor<ConditionalUndefined<T, T>>, ObjectUpdateCallback<T>];
+
+/**
+ * Subscribe to a specific property of an Echo object.
+ * Returns the current property value accessor and an update callback.
+ *
+ * @param obj - The Echo object to subscribe to (can be reactive)
+ * @param property - Property key to subscribe to
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T extends Obj.Unknown, K extends keyof T>(
   obj: MaybeAccessor<T>,
-): [Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>, ObjectUpdateCallback<Exclude<T, undefined>>];
+  property: K,
+): [Accessor<T[K]>, ObjectPropUpdateCallback<T[K]>];
+
+/**
+ * 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/reactive)
+ * @param property - Property key to subscribe to
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T extends Obj.Unknown, K extends keyof T>(
+  obj: MaybeAccessor<T | undefined>,
+  property: K,
+): [Accessor<T[K] | undefined>, ObjectPropUpdateCallback<T[K]>];
+
+/**
+ * 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 (can be reactive)
+ * @param property - Property key to subscribe to
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T, K extends keyof T>(
+  ref: MaybeAccessor<Ref.Ref<T>>,
+  property: K,
+): [Accessor<T[K] | undefined>, ObjectPropUpdateCallback<T[K]>];
+
+/**
+ * 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/reactive)
+ * @param property - Property key to subscribe to
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T, K extends keyof T>(
+  ref: MaybeAccessor<Ref.Ref<T> | undefined>,
+  property: K,
+): [Accessor<T[K] | undefined>, ObjectPropUpdateCallback<T[K]>];
 
 /**
- * Subscribe to an Echo object (entire object or specific property).
+ * Subscribe to an Echo object or Ref (entire object or specific property).
  * Returns the current value accessor and an update callback.
  *
- * @param obj - The Echo object to subscribe to (can be reactive)
+ * @param objOrRef - The Echo object or Ref to subscribe to (can be reactive)
  * @param property - Optional property key to subscribe to a specific property
  * @returns A tuple of [accessor, updateCallback]
  */
-export function useObject<T extends Entity.Unknown | undefined, K extends keyof Exclude<T, undefined>>(
-  obj: MaybeAccessor<T>,
-  property?: K,
-):
-  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>, ObjectUpdateCallback<Exclude<T, undefined>>]
-  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>, ObjectPropUpdateCallback<Exclude<T, undefined>[K]>];
-export function useObject<T extends Entity.Unknown, K extends keyof T>(
-  obj: MaybeAccessor<T>,
-  property?: K,
-):
-  | [Accessor<ConditionalUndefined<T, T>>, ObjectUpdateCallback<T>]
-  | [Accessor<ConditionalUndefined<T, T[K]>>, ObjectPropUpdateCallback<T[K]>];
-export function useObject<T extends Entity.Unknown | undefined, K extends keyof Exclude<T, undefined>>(
-  obj: MaybeAccessor<T>,
+export function useObject<T extends Obj.Unknown, K extends keyof T>(
+  objOrRef: MaybeAccessor<T | Ref.Ref<T> | undefined>,
   property?: K,
-):
-  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>, ObjectUpdateCallback<Exclude<T, undefined>>]
-  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>, ObjectPropUpdateCallback<Exclude<T, undefined>[K]>] {
+): [Accessor<any>, ObjectUpdateCallback<T> | ObjectPropUpdateCallback<T[K]>] {
   const registry = useRegistry();
 
-  // Memoize the resolved object to track changes.
-  const resolvedObj = createMemo(() => access(obj));
+  // Memoize the resolved input to track changes.
+  const resolvedInput = createMemo(() => access(objOrRef));
+
+  // Determine if input is a ref.
+  const isRef = createMemo(() => Ref.isRef(resolvedInput()));
+
+  // Get the live object for the callback (refs need to dereference).
+  const liveObj = createMemo(() => {
+    const input = resolvedInput();
+    return isRef() ? (input as Ref.Ref<T>)?.target : (input as T | undefined);
+  });
 
   // Create a stable callback that handles both object and property updates.
   const callback = (updateOrValue: unknown | ((obj: unknown) => unknown)) => {
-    const currentObj = resolvedObj();
-    if (!currentObj) {
+    // Get current target for refs (may have loaded since render).
+    const obj = isRef() ? (resolvedInput() as Ref.Ref<T>)?.target : liveObj();
+    if (!obj) {
       return;
     }
 
-    Obj.change(currentObj, (o: any) => {
+    Obj.update(obj, (obj: any) => {
       if (typeof updateOrValue === 'function') {
-        const returnValue = (updateOrValue as (obj: unknown) => unknown)(property !== undefined ? o[property] : o);
+        const returnValue = (updateOrValue as (obj: unknown) => unknown)(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;
       }
     });
   };
 
   if (property !== undefined) {
-    return [useObjectProperty(registry, obj, property), callback as ObjectPropUpdateCallback<Exclude<T, undefined>[K]>];
+    // For property subscriptions on refs, we subscribe to trigger re-render on load.
+    useObjectValue(registry, objOrRef);
+    return [useObjectProperty(registry, liveObj, property), callback as ObjectPropUpdateCallback<T[K]>];
+  } else {
+    return [useObjectValue(registry, objOrRef), callback as ObjectUpdateCallback<T>];
   }
-  return [useObjectValue(registry, obj), callback as ObjectUpdateCallback<Exclude<T, undefined>>];
 }
 
 /**
- * Internal function for subscribing to an entire Echo object.
- * Uses snapshots from AtomObj.make() which return new object references on each change.
+ * Internal function for subscribing to an Echo object or Ref.
+ * AtomObj.make handles both objects and refs, returning snapshots.
  */
-function useObjectValue<T extends Entity.Unknown | undefined>(
+function useObjectValue<T extends Obj.Unknown>(
   registry: Registry.Registry,
-  obj: MaybeAccessor<T>,
-): Accessor<ConditionalUndefined<T, Exclude<T, undefined>>> {
-  // Memoize the resolved object to track changes.
-  const resolvedObj = createMemo(() => access(obj));
+  objOrRef: MaybeAccessor<T | Ref.Ref<T> | undefined>,
+): Accessor<T | undefined> {
+  // Memoize the resolved input to track changes.
+  const resolvedInput = createMemo(() => access(objOrRef));
 
-  // Initialize with snapshot of the current object (if available).
-  const initialObj = resolvedObj();
-  const initialSnapshot = initialObj ? (Obj.getSnapshot(initialObj as Obj.Any) as T) : undefined;
-  const [value, setValue] = createSignal<T | undefined>(initialSnapshot);
+  // Initialize with the current value (if available).
+  const initialInput = resolvedInput();
+  const initialValue = initialInput ? registry.get(AtomObj.make(initialInput)) : undefined;
+  const [value, setValue] = createSignal<T | undefined>(initialValue as T | undefined);
 
   // Subscribe to atom updates.
   createEffect(() => {
-    const currentObj = resolvedObj();
+    const input = resolvedInput();
 
-    if (!currentObj) {
+    if (!input) {
       setValue(() => undefined);
       return;
     }
 
-    const atom = AtomObj.make(currentObj);
+    const atom = AtomObj.make(input);
     const currentValue = registry.get(atom);
-    setValue(() => currentValue as T);
+    setValue(() => currentValue as unknown as T);
 
     const unsubscribe = registry.subscribe(
       atom,
       () => {
-        setValue(() => registry.get(atom) as T);
+        setValue(() => registry.get(atom) as unknown as T);
       },
       { immediate: true },
     );
@@ -157,43 +227,39 @@ function useObjectValue<T extends Entity.Unknown | undefined>(
     onCleanup(unsubscribe);
   });
 
-  return value as Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>;
+  return value;
 }
 
 /**
  * Internal function for subscribing to a specific property of an Echo object.
  */
-function useObjectProperty<T extends Entity.Unknown | undefined, K extends keyof Exclude<T, undefined>>(
+function useObjectProperty<T extends Obj.Unknown, K extends keyof T>(
   registry: Registry.Registry,
-  obj: MaybeAccessor<T>,
+  obj: Accessor<T | undefined>,
   property: K,
-): Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>> {
-  // Memoize the resolved object to track changes.
-  const resolvedObj = createMemo(() => access(obj));
-
-  type NonUndefinedT = Exclude<T, undefined>;
-  const initialValue = resolvedObj() ? (resolvedObj() as NonUndefinedT)[property] : undefined;
-  const [value, setValue] = createSignal<NonUndefinedT[K] | undefined>(initialValue);
+): Accessor<T[K] | undefined> {
+  // Initialize with the current value (if available).
+  const initialObj = obj();
+  const initialValue = initialObj ? registry.get(AtomObj.makeProperty(initialObj, property)) : undefined;
+  const [value, setValue] = createSignal<T[K] | undefined>(initialValue);
 
   // Subscribe to atom updates.
   createEffect(() => {
-    const currentObj = resolvedObj();
+    const currentObj = obj();
 
     if (!currentObj) {
       setValue(() => undefined);
       return;
     }
 
-    type NonUndefinedT = Exclude<T, undefined>;
-    const echoObj = currentObj as NonUndefinedT;
-    const atom = AtomObj.makeProperty(echoObj, property);
+    const atom = AtomObj.makeProperty(currentObj, property);
     const currentValue = registry.get(atom);
     setValue(() => currentValue);
 
     const unsubscribe = registry.subscribe(
       atom,
       () => {
-        setValue(() => registry.get(atom) as NonUndefinedT[K]);
+        setValue(() => registry.get(atom) as T[K]);
       },
       { immediate: true },
     );
@@ -201,5 +267,85 @@ function useObjectProperty<T extends Entity.Unknown | undefined, K extends keyof
     onCleanup(unsubscribe);
   });
 
-  return value as Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>;
+  return value;
 }
+
+/**
+ * Subscribe to multiple Refs' target objects.
+ * Automatically dereferences each ref and handles async loading.
+ * Returns an accessor to an array of loaded snapshots (filtering out undefined values).
+ *
+ * This hook is useful for aggregate computations like counts or filtering
+ * across multiple refs without using .target directly.
+ *
+ * @param refs - Array of Refs to dereference and subscribe to (can be reactive)
+ * @returns Accessor to array of loaded target snapshots (excludes unloaded refs)
+ */
+export const useObjects = <T extends Obj.Unknown>(refs: MaybeAccessor<readonly Ref.Ref<T>[]>): Accessor<T[]> => {
+  // Track version to trigger re-renders when any ref or target changes.
+  const [version, setVersion] = createSignal(0);
+
+  // Memoize the refs array to track changes.
+  const resolvedRefs = createMemo(() => access(refs));
+
+  // Subscribe to all refs and their targets.
+  createEffect(() => {
+    const currentRefs = resolvedRefs();
+    const targetUnsubscribes = new Map<string, () => void>();
+
+    // Function to trigger re-render.
+    const triggerUpdate = () => {
+      setVersion((v) => v + 1);
+    };
+
+    // Function to set up subscription for a target.
+    const subscribeToTarget = (ref: Ref.Ref<T>) => {
+      const target = ref.target;
+      if (target) {
+        const key = ref.dxn.toString();
+        if (!targetUnsubscribes.has(key)) {
+          targetUnsubscribes.set(key, Obj.subscribe(target, triggerUpdate));
+        }
+      }
+    };
+
+    // Try to load all refs and subscribe to targets.
+    for (const ref of currentRefs) {
+      // 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.
+          });
+      }
+    }
+
+    onCleanup(() => {
+      targetUnsubscribes.forEach((u) => u());
+    });
+  });
+
+  // Compute current snapshots by reading each ref's target.
+  return createMemo(() => {
+    // Depend on version to re-compute when targets change.
+    version();
+
+    const currentRefs = resolvedRefs();
+    const snapshots: T[] = [];
+    for (const ref of currentRefs) {
+      const target = ref.target;
+      if (target !== undefined) {
+        snapshots.push(target as T);
+      }
+    }
+    return snapshots;
+  });
+};