@dxos/echo-solid 0.0.0

package/src/useQuery.test.tsx

@@ -0,0 +1,277 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { render, waitFor } from '@solidjs/testing-library';
+import { type JSX, createSignal } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Filter, Obj, Query, Type } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+
+import { useQuery } from './useQuery';
+
+describe('useQuery', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: any;
+
+  beforeEach(async () => {
+    testBuilder = new EchoTestBuilder();
+    const result = await testBuilder.createDatabase();
+    db = result.db;
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('returns empty array when database is undefined', () => {
+    let result: any[] | undefined;
+
+    render(() => {
+      const objects = useQuery(undefined, Filter.type(Type.Expando));
+      result = objects();
+      return (<div>test</div>) as JSX.Element;
+    });
+
+    expect(result).toEqual([]);
+  });
+
+  test('returns empty array when query matches no objects', async () => {
+    let result: any[] | undefined;
+
+    render(() => {
+      const objects = useQuery(db, Filter.type(Type.Expando));
+      result = objects();
+      return (<div>test</div>) as JSX.Element;
+    });
+
+    await waitFor(() => {
+      expect(result).toEqual([]);
+    });
+  });
+
+  test('returns matching objects', async () => {
+    // Add some objects to the database
+    const obj1 = Obj.make(Type.Expando, { name: 'Alice' });
+    const obj2 = Obj.make(Type.Expando, { name: 'Bob' });
+    db.add(obj1);
+    db.add(obj2);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+
+    function TestComponent() {
+      const objects = useQuery(db, Filter.type(Type.Expando));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('2');
+    });
+
+    // Get the actual results from the accessor
+    const result = objectsAccessor?.() ?? [];
+    const names = result.map((obj) => obj.name).sort();
+    expect(names).toEqual(['Alice', 'Bob']);
+  });
+
+  test('updates when objects are added', async () => {
+    let objectsAccessor: (() => any[]) | undefined;
+
+    function TestComponent() {
+      const objects = useQuery(db, Filter.type(Type.Expando));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('0');
+    });
+
+    // Add an object
+    const obj = Obj.make(Type.Expando, { name: 'Charlie' });
+    db.add(obj);
+    await db.flush({ indexes: true });
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    const result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe('Charlie');
+  });
+
+  test('updates when objects are removed', async () => {
+    // Add objects first
+    const obj1 = Obj.make(Type.Expando, { name: 'Alice' });
+    const obj2 = Obj.make(Type.Expando, { name: 'Bob' });
+    db.add(obj1);
+    db.add(obj2);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+
+    function TestComponent() {
+      const objects = useQuery(db, Filter.type(Type.Expando));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('2');
+    });
+
+    // Remove an object
+    db.remove(obj1);
+    await db.flush({ indexes: true });
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    const result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe('Bob');
+  });
+
+  test('accepts Filter directly', async () => {
+    // Register schema first
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const obj = Obj.make(TestSchema.Person, { name: 'Test', username: 'test', email: 'test@example.com' });
+    db.add(obj);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+
+    function TestComponent() {
+      const objects = useQuery(db, Filter.type(TestSchema.Person));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    const result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe('Test');
+  });
+
+  test('accepts Query directly', async () => {
+    const obj = Obj.make(Type.Expando, { name: 'Test' });
+    db.add(obj);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+
+    function TestComponent() {
+      const objects = useQuery(db, Query.select(Filter.type(Type.Expando)));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    const result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe('Test');
+  });
+
+  test('accepts reactive database accessor', async () => {
+    const obj = Obj.make(Type.Expando, { name: 'Test' });
+    db.add(obj);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+    let dbAccessor: any = db;
+
+    function TestComponent() {
+      const objects = useQuery(() => dbAccessor, Filter.type(Type.Expando));
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    let result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+
+    // Change database to undefined
+    dbAccessor = undefined;
+
+    // Should keep previous value (no flickering)
+    result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+  });
+
+  test('accepts reactive query accessor', async () => {
+    // Register schema first
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const obj1 = Obj.make(Type.Expando, { name: 'Test1' });
+    const obj2 = Obj.make(TestSchema.Person, { name: 'Test2', username: 'test', email: 'test@example.com' });
+    db.add(obj1);
+    db.add(obj2);
+    await db.flush({ indexes: true });
+
+    let objectsAccessor: (() => any[]) | undefined;
+    const [usePersonFilter, setUsePersonFilter] = createSignal(false);
+
+    function TestComponent() {
+      const objects = useQuery(db, () =>
+        usePersonFilter() ? Filter.type(TestSchema.Person) : Filter.type(Type.Expando),
+      );
+      objectsAccessor = objects;
+      return (<div data-testid='count'>{objects().length}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    let result = objectsAccessor?.() ?? [];
+    expect(result[0]?.name).toBe('Test1');
+
+    // Switch to person filter
+    setUsePersonFilter(true);
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    // Get the actual results from the accessor
+    result = objectsAccessor?.() ?? [];
+    expect(result.length).toBe(1);
+    expect(result[0]?.name).toBe('Test2');
+  });
+});

package/src/useQuery.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Accessor, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
+
+import { type Database, type Entity, Filter, Query } from '@dxos/echo';
+
+const EMPTY_ARRAY: never[] = [];
+
+type MaybeAccessor<T> = T | Accessor<T>;
+
+/**
+ * Create a reactive query subscription.
+ * Accepts either values or accessors for resource and query/filter.
+ *
+ * @param resource - The database or queryable resource (can be reactive)
+ * @param queryOrFilter - The query or filter to apply (can be reactive)
+ * @returns An accessor that returns the current query results
+ */
+export const useQuery = <T extends Entity.Any = Entity.Any>(
+  resource: MaybeAccessor<Database.Queryable | undefined>,
+  queryOrFilter: MaybeAccessor<Query.Any | Filter.Any>,
+): Accessor<T[]> => {
+  // Derive the normalized query from the input
+  const query = createMemo(() => {
+    const resolved = typeof queryOrFilter === 'function' ? queryOrFilter() : queryOrFilter;
+    return Filter.is(resolved) ? Query.select(resolved) : resolved;
+  });
+
+  // Derive the query result object reactively
+  const queryResult = createMemo(() => {
+    const q = query();
+    const resolvedResource = typeof resource === 'function' ? resource() : resource;
+    return resolvedResource?.query(q);
+  });
+
+  // Store the current results in a signal
+  const [objects, setObjects] = createSignal<T[]>(EMPTY_ARRAY as T[]);
+
+  // Subscribe to query result changes
+  createEffect(() => {
+    const result = queryResult();
+    if (!result) {
+      // Keep previous value during transitions to prevent flickering
+      return;
+    }
+
+    // Subscribe with immediate fire to get initial results
+    const unsubscribe = result.subscribe(
+      () => {
+        setObjects(() => result.results as T[]);
+      },
+      { fire: true },
+    );
+
+    onCleanup(unsubscribe);
+  });
+
+  return objects;
+};

package/src/useRef.test.tsx

@@ -0,0 +1,247 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { render, waitFor } from '@solidjs/testing-library';
+import { type JSX, createSignal } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Obj, Ref, Type } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { Registry, RegistryProvider } from '@dxos/effect-atom-solid';
+
+import { useRef } from './useRef';
+
+const createWrapper = (registry: Registry.Registry) => {
+  return (props: { children: JSX.Element }) => {
+    return <RegistryProvider registry={registry}>{props.children}</RegistryProvider>;
+  };
+};
+
+describe('useRef', () => {
+  let testBuilder: EchoTestBuilder;
+  let db: any;
+  let registry: Registry.Registry;
+
+  beforeEach(async () => {
+    testBuilder = await new EchoTestBuilder().open();
+    const { db: database } = await testBuilder.createDatabase();
+    db = database;
+    registry = Registry.make();
+  });
+
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('returns undefined when ref is undefined', () => {
+    const Wrapper = createWrapper(registry);
+
+    let result: any;
+
+    render(
+      () => {
+        const target = useRef(undefined);
+        result = target();
+        return (<div>test</div>) as JSX.Element;
+      },
+      { wrapper: Wrapper },
+    );
+
+    expect(result).toBeUndefined();
+  });
+
+  test('returns undefined when ref target is not loaded and loads it', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    // Create objects with a ref
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    // Create a ref - target should be available since object is in memory
+    const ref = Ref.make(targetObj);
+
+    // Initially target should be available since object is in memory
+    expect(ref.target).toBeDefined();
+
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(ref);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    // Should load since target is available
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Target');
+    });
+
+    // Get the actual result from the accessor
+    const result = targetAccessor?.();
+    expect(result?.name).toBe('Target');
+  });
+
+  test('returns target when ref is loaded', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(ref);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Target');
+    });
+
+    // Get the actual result from the accessor
+    const result = targetAccessor?.();
+    expect(result?.name).toBe('Target');
+    expect(result?.username).toBe('target');
+  });
+
+  test('handles ref to Expando object', async () => {
+    const targetObj = Obj.make(Type.Expando, { name: 'Expando Target', value: 42 });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(ref);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Expando Target');
+    });
+
+    // Get the actual result from the accessor
+    const result = targetAccessor?.();
+    expect(result?.name).toBe('Expando Target');
+    expect(result?.value).toBe(42);
+  });
+
+  test('works with accessor function', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj = Obj.make(TestSchema.Person, { name: 'Target', username: 'target', email: 'target@example.com' });
+    db.add(targetObj);
+    await db.flush({ indexes: true });
+
+    const ref = Ref.make(targetObj);
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(() => ref);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Target');
+    });
+
+    // Get the actual result from the accessor
+    const result = targetAccessor?.();
+    expect(result?.name).toBe('Target');
+  });
+
+  test('reactively tracks changes when accessor returns different ref', async () => {
+    await db.graph.schemaRegistry.register([TestSchema.Person]);
+
+    const targetObj1 = Obj.make(TestSchema.Person, {
+      name: 'Target1',
+      username: 'target1',
+      email: 'target1@example.com',
+    });
+    const targetObj2 = Obj.make(TestSchema.Person, {
+      name: 'Target2',
+      username: 'target2',
+      email: 'target2@example.com',
+    });
+    db.add(targetObj1);
+    db.add(targetObj2);
+    await db.flush({ indexes: true });
+
+    const ref1 = Ref.make(targetObj1);
+    const ref2 = Ref.make(targetObj2);
+    const [refSignal, setRefSignal] = createSignal<Ref.Ref<any> | undefined>(ref1);
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(refSignal);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Target1');
+    });
+
+    // Get the actual result from the accessor
+    let result = targetAccessor?.();
+    expect(result?.name).toBe('Target1');
+
+    // Change the ref via signal
+    setRefSignal(() => ref2);
+
+    await waitFor(() => {
+      expect(getByTestId('name').textContent).toBe('Target2');
+    });
+
+    // Get the actual result from the accessor
+    result = targetAccessor?.();
+    expect(result?.name).toBe('Target2');
+  });
+
+  test('handles undefined when accessor returns undefined', () => {
+    const [refSignal] = createSignal<Ref.Ref<any> | undefined>(undefined);
+    const Wrapper = createWrapper(registry);
+
+    let targetAccessor: (() => any) | undefined;
+
+    function TestComponent() {
+      const target = useRef(refSignal);
+      targetAccessor = target;
+      return (<div data-testid='name'>{target()?.name || 'undefined'}</div>) as JSX.Element;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />, { wrapper: Wrapper });
+
+    expect(getByTestId('name').textContent).toBe('undefined');
+    expect(targetAccessor?.()).toBeUndefined();
+  });
+});

package/src/useRef.ts

@@ -0,0 +1,48 @@
+//
+// 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, type Ref } from '@dxos/echo';
+import { AtomRef } from '@dxos/echo-atom';
+import { useRegistry } from '@dxos/effect-atom-solid';
+
+/**
+ * Subscribe to a reference target object.
+ * Returns undefined if the reference hasn't loaded yet, and automatically updates when the target loads or changes.
+ *
+ * @param ref - The reference to subscribe to (can be reactive).
+ * @returns An accessor that returns the current target object or undefined if not loaded.
+ */
+export function useRef<T extends Entity.Unknown>(ref: MaybeAccessor<Ref.Ref<T> | undefined>): Accessor<T | undefined> {
+  const registry = useRegistry();
+
+  // Memoize the ref to track changes.
+  const memoizedRef = createMemo(() => access(ref));
+
+  // Store the current target in a signal.
+  const [target, setTarget] = createSignal<T | undefined>(undefined);
+
+  // Subscribe to ref target changes.
+  createEffect(() => {
+    const currentRef = memoizedRef();
+
+    const atom = AtomRef.make(currentRef);
+    const currentValue = registry.get(atom);
+    setTarget(() => currentValue);
+
+    const unsubscribe = registry.subscribe(
+      atom,
+      () => {
+        setTarget(() => registry.get(atom));
+      },
+      { immediate: true },
+    );
+
+    onCleanup(unsubscribe);
+  });
+
+  return target;
+}