@dxos/echo-solid 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 @@
+# @dxos/echo-solid

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dxos/echo-solid",
+  "version": "0.0.0",
+  "description": "Solid.js integration for ECHO.",
+  "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": {
+    "@solid-primitives/utils": "^6.3.2",
+    "@dxos/effect-atom-solid": "0.0.0",
+    "@dxos/echo-atom": "0.0.0",
+    "@dxos/echo": "0.8.3"
+  },
+  "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"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.9.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useObject';
+export * from './useQuery';
+export * from './useRef';
+export * from './useSchema';

package/src/useObject.test.tsx

@@ -0,0 +1,362 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { render, waitFor } from '@solidjs/testing-library';
+import { type JSX, createSignal } from 'solid-js';
+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 { Registry } from '@dxos/effect-atom-solid';
+import { RegistryProvider } from '@dxos/effect-atom-solid';
+
+import { useObject } from './useObject';
+
+const createWrapper = (registry: Registry.Registry) => {
+  return (props: { children: JSX.Element }) => (
+    <RegistryProvider registry={registry}>{props.children}</RegistryProvider>
+  );
+};
+
+describe('useObject', () => {
+  test('returns entire object when property is not provided', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: Entity.Entity<TestSchema.Person> | undefined;
+    render(
+      () => {
+        const [value] = useObject(obj);
+        result = value();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    // Returns a snapshot (plain object), not the Echo object itself.
+    expect(result).not.toBe(obj);
+    expect(result?.name).toBe('Test');
+    expect(result?.username).toBe('test');
+    expect(result?.email).toBe('test@example.com');
+  });
+
+  test('returns property value when property is provided', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: string | undefined;
+    render(
+      () => {
+        const [value] = useObject(obj, 'name');
+        result = value();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(result).toBe('Test');
+  });
+
+  test('updates when object property changes', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: string | undefined;
+    const { getByTestId } = render(
+      () => {
+        const [value] = useObject(obj, 'name');
+        result = value();
+        return (<div data-testid='value'>{value()}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(result).toBe('Test');
+    expect(getByTestId('value').textContent).toBe('Test');
+
+    // Update the property via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('Updated');
+    });
+  });
+
+  test('updates when entire object changes', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    // Capture the accessor to get the latest snapshot value.
+    let valueAccessor: (() => Entity.Entity<TestSchema.Person> | undefined) | undefined;
+    const { getByTestId } = render(
+      () => {
+        const [value] = useObject(obj);
+        valueAccessor = value;
+        return (<div data-testid='name'>{value()?.name}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(valueAccessor?.()?.name).toBe('Test');
+    expect(getByTestId('name').textContent).toBe('Test');
+
+    // Update a property via Obj.change.
+    Obj.change(obj, (o) => {
+      o.name = 'Updated';
+    });
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Updated');
+    });
+    expect(valueAccessor?.()?.name).toBe('Updated');
+  });
+
+  test('property atom does not update when other properties change', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: string | undefined;
+    render(
+      () => {
+        const [value] = useObject(obj, 'name');
+        result = value();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(result).toBe('Test');
+
+    // Update a different property via Obj.change.
+    Obj.change(obj, (o) => {
+      o.email = 'newemail@example.com';
+    });
+
+    // Name should still be 'Test'.
+    expect(result).toBe('Test');
+  });
+
+  test('works with accessor function for entire object', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: Entity.Entity<TestSchema.Person> | undefined;
+    render(
+      () => {
+        const [value] = useObject(() => obj);
+        result = value();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    // Returns a snapshot (plain object), not the Echo object itself.
+    expect(result).not.toBe(obj);
+    expect(result?.name).toBe('Test');
+  });
+
+  test('works with accessor function for property', () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let result: string | undefined;
+
+    render(
+      () => {
+        const [value] = useObject(() => obj, 'name');
+        result = value();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(result).toBe('Test');
+  });
+
+  test('reactively tracks changes when accessor returns different object', async () => {
+    const obj1 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test1', username: 'test1', email: 'test1@example.com' }),
+    );
+    const obj2 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test2', username: 'test2', email: 'test2@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    const [objSignal, setObjSignal] = createSignal(obj1);
+    let valueAccessor: (() => string | undefined) | undefined;
+
+    const { getByTestId } = render(
+      () => {
+        const [value] = useObject(objSignal, 'name');
+        valueAccessor = value;
+        return (<div data-testid='value'>{value()}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(valueAccessor?.()).toBe('Test1');
+    expect(getByTestId('value').textContent).toBe('Test1');
+
+    // Change the object via signal.
+    setObjSignal(() => obj2);
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('Test2');
+    });
+    expect(valueAccessor?.()).toBe('Test2');
+  });
+
+  test('reactively tracks entire object when accessor returns different object', async () => {
+    const obj1 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test1', username: 'test1', email: 'test1@example.com' }),
+    );
+    const obj2 = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test2', username: 'test2', email: 'test2@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    const [objSignal, setObjSignal] = createSignal(obj1);
+    let valueAccessor: (() => Entity.Entity<TestSchema.Person> | undefined) | undefined;
+    render(
+      () => {
+        const [value] = useObject(objSignal);
+        valueAccessor = value;
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(valueAccessor?.()?.name).toBe('Test1');
+
+    // Change the object via signal.
+    setObjSignal(() => obj2);
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(valueAccessor?.()?.name).toBe('Test2');
+    });
+    expect(valueAccessor?.()?.username).toBe('test2');
+  });
+
+  test('update callback can update property value directly', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let updateName: ((value: string | undefined) => void) | undefined;
+    const { getByTestId } = render(
+      () => {
+        const [value, update] = useObject(obj, 'name');
+        updateName = update;
+        return (<div data-testid='value'>{value()}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(getByTestId('value').textContent).toBe('Test');
+
+    // Update using the callback.
+    updateName?.('Updated');
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('Updated');
+    });
+    expect(obj.name).toBe('Updated');
+  });
+
+  test('update callback can update property with updater function', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let updateName: ((updater: (current: string | undefined) => string | undefined) => void) | undefined;
+    const { getByTestId } = render(
+      () => {
+        const [value, update] = useObject(obj, 'name');
+        updateName = update;
+        return (<div data-testid='value'>{value()}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(getByTestId('value').textContent).toBe('Test');
+
+    // Update using an updater function.
+    updateName?.((current) => (current ?? '') + ' Updated');
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('Test Updated');
+    });
+    expect(obj.name).toBe('Test Updated');
+  });
+
+  test('update callback can mutate entire object', async () => {
+    const obj = createObject(
+      Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' }),
+    );
+    const registry = Registry.make();
+    const Wrapper = createWrapper(registry);
+
+    let updatePerson: ((updater: (p: Entity.Entity<TestSchema.Person>) => void) => void) | undefined;
+    const { getByTestId } = render(
+      () => {
+        const [value, update] = useObject(obj);
+        updatePerson = update;
+        return (<div data-testid='value'>{value()?.name}</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(getByTestId('value').textContent).toBe('Test');
+
+    // Update using the callback to mutate the object.
+    updatePerson?.((p) => {
+      p.name = 'Updated';
+      p.email = 'updated@example.com';
+    });
+
+    // Wait for reactivity to update.
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('Updated');
+    });
+    expect(obj.name).toBe('Updated');
+    expect(obj.email).toBe('updated@example.com');
+  });
+});

package/src/useObject.ts

@@ -0,0 +1,205 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 { 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;
+}
+
+export interface ObjectPropUpdateCallback<T> extends ObjectUpdateCallback<T> {
+  (newValue: T): void;
+}
+
+/**
+ * Helper type to conditionally include undefined in return type only if input includes undefined.
+ * Only adds undefined if T includes undefined AND R doesn't already include undefined.
+ */
+type ConditionalUndefined<T, R> = [T] extends [Exclude<T, undefined>]
+  ? R // T doesn't include undefined, return R as-is
+  : [R] extends [Exclude<R, undefined>]
+    ? R | undefined // T includes undefined but R doesn't, add 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.
+ *
+ * @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 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]>];
+
+/**
+ * Subscribe to an entire Echo object.
+ * Returns the current object value accessor and an update callback.
+ *
+ * @param obj - The Echo object to subscribe to (can be reactive)
+ * @returns A tuple of [accessor, updateCallback]
+ */
+export function useObject<T extends Entity.Unknown>(
+  obj: MaybeAccessor<T>,
+): [Accessor<ConditionalUndefined<T, T>>, ObjectUpdateCallback<T>];
+export function useObject<T extends Entity.Unknown | undefined>(
+  obj: MaybeAccessor<T>,
+): [Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>, ObjectUpdateCallback<Exclude<T, undefined>>];
+
+/**
+ * Subscribe to an Echo object (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 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>,
+  property?: K,
+):
+  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>, ObjectUpdateCallback<Exclude<T, undefined>>]
+  | [Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>, ObjectPropUpdateCallback<Exclude<T, undefined>[K]>] {
+  const registry = useRegistry();
+
+  // Memoize the resolved object to track changes.
+  const resolvedObj = createMemo(() => access(obj));
+
+  // Create a stable callback that handles both object and property updates.
+  const callback = (updateOrValue: unknown | ((obj: unknown) => unknown)) => {
+    const currentObj = resolvedObj();
+    if (!currentObj) {
+      return;
+    }
+
+    Obj.change(currentObj, (o: any) => {
+      if (typeof updateOrValue === 'function') {
+        const returnValue = (updateOrValue as (obj: unknown) => unknown)(property !== undefined ? o[property] : o);
+        if (returnValue !== undefined) {
+          if (property === undefined) {
+            throw new Error('Cannot re-assign the entire object');
+          }
+          o[property] = returnValue;
+        }
+      } else {
+        if (property === undefined) {
+          throw new Error('Cannot re-assign the entire object');
+        }
+        o[property] = updateOrValue;
+      }
+    });
+  };
+
+  if (property !== undefined) {
+    return [useObjectProperty(registry, obj, property), callback as ObjectPropUpdateCallback<Exclude<T, undefined>[K]>];
+  }
+  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.
+ */
+function useObjectValue<T extends Entity.Unknown | undefined>(
+  registry: Registry.Registry,
+  obj: MaybeAccessor<T>,
+): Accessor<ConditionalUndefined<T, Exclude<T, undefined>>> {
+  // Memoize the resolved object to track changes.
+  const resolvedObj = createMemo(() => access(obj));
+
+  // 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);
+
+  // Subscribe to atom updates.
+  createEffect(() => {
+    const currentObj = resolvedObj();
+
+    if (!currentObj) {
+      setValue(() => undefined);
+      return;
+    }
+
+    const atom = AtomObj.make(currentObj);
+    const currentValue = registry.get(atom);
+    setValue(() => currentValue as T);
+
+    const unsubscribe = registry.subscribe(
+      atom,
+      () => {
+        setValue(() => registry.get(atom) as T);
+      },
+      { immediate: true },
+    );
+
+    onCleanup(unsubscribe);
+  });
+
+  return value as Accessor<ConditionalUndefined<T, Exclude<T, undefined>>>;
+}
+
+/**
+ * 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>>(
+  registry: Registry.Registry,
+  obj: MaybeAccessor<T>,
+  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);
+
+  // Subscribe to atom updates.
+  createEffect(() => {
+    const currentObj = resolvedObj();
+
+    if (!currentObj) {
+      setValue(() => undefined);
+      return;
+    }
+
+    type NonUndefinedT = Exclude<T, undefined>;
+    const echoObj = currentObj as NonUndefinedT;
+    const atom = AtomObj.makeProperty(echoObj, property);
+    const currentValue = registry.get(atom);
+    setValue(() => currentValue);
+
+    const unsubscribe = registry.subscribe(
+      atom,
+      () => {
+        setValue(() => registry.get(atom) as NonUndefinedT[K]);
+      },
+      { immediate: true },
+    );
+
+    onCleanup(unsubscribe);
+  });
+
+  return value as Accessor<ConditionalUndefined<T, Exclude<T, undefined>[K]>>;
+}