@dxos/effect-atom-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/effect-atom-solid

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dxos/effect-atom-solid",
+  "version": "0.0.0",
+  "description": "Solid.js bindings for Effect Atom",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "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"
+  ],
+  "devDependencies": {
+    "@effect-atom/atom": "^0.4.10",
+    "@solidjs/testing-library": "^0.8.10",
+    "effect": "3.19.11",
+    "solid-js": "^1.9.9",
+    "vite-plugin-solid": "^2.11.10"
+  },
+  "peerDependencies": {
+    "@effect-atom/atom": "^0.4.10",
+    "effect": "3.19.11",
+    "solid-js": "^1.9.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useAtomValue';
+export * from './useAtomSet';
+export * from './useAtom';
+export * from './useAtomMount';
+export * from './useAtomRefresh';
+export * from './useAtomSubscribe';
+export * from './useAtomRef';
+export * from './useAtomResource';
+export * from './useAtomSuspense';
+export * from './useAtomInitialValues';

package/src/hooks/useAtom.test.tsx

@@ -0,0 +1,49 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { fireEvent, render, waitFor } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtom } from './useAtom';
+
+describe('useAtom', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('returns both value and setter', async () => {
+    const countAtom = Atom.make(0);
+
+    function TestComponent() {
+      const [count, setCount] = useAtom(countAtom);
+      return (
+        <div>
+          <span data-testid='count'>{count()}</span>
+          <button data-testid='increment' onClick={() => setCount((c) => c + 1)}>
+            +
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('count').textContent).toBe('0');
+
+    fireEvent.click(getByTestId('increment'));
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+
+    fireEvent.click(getByTestId('increment'));
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('2');
+    });
+  });
+});

package/src/hooks/useAtom.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import type * as Result from '@effect-atom/atom/Result';
+import { type Accessor, createSignal, onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+import { type SetAtomFn, createSetAtom } from './useAtomSet';
+
+/**
+ * Hook to both read and write an atom
+ * Returns a tuple of [value accessor, setter function]
+ */
+export function useAtom<R, W, Mode extends 'value' | 'promise' | 'promiseExit' = never>(
+  atom: Atom.Writable<R, W>,
+  options?: {
+    readonly mode?: ([R] extends [Result.Result<any, any>] ? Mode : 'value') | undefined;
+  },
+): readonly [Accessor<R>, SetAtomFn<R, W, Mode>] {
+  const registry = useRegistry();
+
+  const [value, setValue] = createSignal<R>(registry.get(atom));
+
+  // Subscribe to atom changes
+  const unsubscribe = registry.subscribe(
+    atom,
+    (nextValue) => {
+      setValue(() => nextValue);
+    },
+    { immediate: true },
+  );
+
+  onCleanup(unsubscribe);
+
+  return [value, createSetAtom(registry, atom, options)] as const;
+}

package/src/hooks/useAtomInitialValues.test.tsx

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { render } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomInitialValues } from './useAtomInitialValues';
+import { useAtomValue } from './useAtomValue';
+
+describe('useAtomInitialValues', () => {
+  beforeEach(() => {
+    defaultRegistry.reset();
+  });
+
+  test('initializes atoms', () => {
+    const atom = Atom.make(0);
+
+    function TestComponent() {
+      useAtomInitialValues([[atom, 42]]);
+      const value = useAtomValue(atom);
+      return <span data-testid='val'>{value()}</span>;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('val').textContent).toBe('42');
+  });
+});

package/src/hooks/useAtomInitialValues.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Hook to initialize atoms with values
+ */
+export function useAtomInitialValues(initialValues: Iterable<readonly [Atom.Writable<any, any>, any]>): void {
+  const registry = useRegistry();
+
+  for (const [atom, value] of initialValues) {
+    registry.set(atom, value);
+  }
+}

package/src/hooks/useAtomMount.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import { onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Hook to mount an atom without reading its value
+ */
+export function useAtomMount<A>(atom: Atom.Atom<A>): void {
+  const registry = useRegistry();
+  const unmount = registry.mount(atom);
+  onCleanup(unmount);
+}

package/src/hooks/useAtomRef.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as AtomRef from '@effect-atom/atom/AtomRef';
+import { type Accessor, createMemo, createSignal, onCleanup } from 'solid-js';
+
+/**
+ * Hook to read an AtomRef value
+ */
+export function useAtomRef<A>(ref: AtomRef.ReadonlyRef<A>): Accessor<A> {
+  const [value, setValue] = createSignal<A>(ref.value);
+
+  const unsubscribe = ref.subscribe((next) => {
+    setValue(() => next);
+  });
+
+  onCleanup(unsubscribe);
+
+  return value;
+}
+
+/**
+ * Hook to get a prop accessor from an AtomRef
+ */
+export function useAtomRefProp<A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): AtomRef.AtomRef<A[K]> {
+  return createMemo(() => ref.prop(prop))();
+}
+
+/**
+ * Hook to read a prop value from an AtomRef
+ */
+export function useAtomRefPropValue<A, K extends keyof A>(ref: AtomRef.AtomRef<A>, prop: K): Accessor<A[K]> {
+  return useAtomRef(useAtomRefProp(ref, prop));
+}

package/src/hooks/useAtomRefresh.test.tsx

@@ -0,0 +1,49 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { fireEvent, render, waitFor } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomRefresh } from './useAtomRefresh';
+import { useAtomValue } from './useAtomValue';
+
+describe('useAtomRefresh', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('returns a refresh function', async () => {
+    let callCount = 0;
+    const computedAtom = Atom.make(() => {
+      callCount++;
+      return callCount;
+    });
+
+    function TestComponent() {
+      const value = useAtomValue(computedAtom);
+      const refresh = useAtomRefresh(computedAtom);
+      return (
+        <div>
+          <span data-testid='value'>{value()}</span>
+          <button data-testid='refresh' onClick={refresh}>
+            Refresh
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('value').textContent).toBe('1');
+
+    fireEvent.click(getByTestId('refresh'));
+
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('2');
+    });
+  });
+});

package/src/hooks/useAtomRefresh.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import { onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Hook to get a refresh function for an atom
+ */
+export function useAtomRefresh<A>(atom: Atom.Atom<A>): () => void {
+  const registry = useRegistry();
+
+  const unmount = registry.mount(atom);
+  onCleanup(unmount);
+
+  return () => registry.refresh(atom);
+}

package/src/hooks/useAtomResource.test.tsx

@@ -0,0 +1,43 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { render, waitFor } from '@solidjs/testing-library';
+import * as Effect from 'effect/Effect';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomResource } from './useAtomResource';
+
+describe('useAtomResource', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('handles loading, success states for Result atoms', async () => {
+    const dataAtom = Atom.make(Effect.succeed(42));
+
+    function TestComponent() {
+      const { value, loading, error } = useAtomResource(dataAtom);
+      return (
+        <div>
+          <span data-testid='loading'>{loading() ? 'true' : 'false'}</span>
+          <span data-testid='value'>{value() ?? 'none'}</span>
+          <span data-testid='error'>{error() ? 'has error' : 'no error'}</span>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    // Wait for the effect to resolve
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('42');
+    });
+
+    expect(getByTestId('error').textContent).toBe('no error');
+  });
+});

package/src/hooks/useAtomResource.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import type * as Result from '@effect-atom/atom/Result';
+import * as Cause from 'effect/Cause';
+import { type Accessor, createMemo, createSignal, onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Resource-like hook for atoms that contain Result values
+ * Automatically handles loading and error states
+ */
+export function useAtomResource<A, E>(
+  atom: Atom.Atom<Result.Result<A, E>>,
+): {
+  value: Accessor<A | undefined>;
+  error: Accessor<E | undefined>;
+  loading: Accessor<boolean>;
+  result: Accessor<Result.Result<A, E>>;
+} {
+  const registry = useRegistry();
+  const [result, setResult] = createSignal<Result.Result<A, E>>(registry.get(atom));
+
+  const unsubscribe = registry.subscribe(
+    atom,
+    (nextValue) => {
+      setResult(() => nextValue);
+    },
+    { immediate: true },
+  );
+
+  onCleanup(unsubscribe);
+
+  const value = createMemo(() => {
+    const r = result();
+    return r._tag === 'Success' ? r.value : undefined;
+  });
+
+  const error = createMemo(() => {
+    const r = result();
+    return r._tag === 'Failure' ? (Cause.squash(r.cause) as E) : undefined;
+  });
+
+  const loading = createMemo(() => {
+    const r = result();
+    return r._tag === 'Initial' || r.waiting;
+  });
+
+  return {
+    value,
+    error,
+    loading,
+    result,
+  };
+}

package/src/hooks/useAtomSet.test.tsx

@@ -0,0 +1,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { fireEvent, render, waitFor } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomSet } from './useAtomSet';
+import { useAtomValue } from './useAtomValue';
+
+describe('useAtomSet', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('returns a setter function', async () => {
+    const countAtom = Atom.make(0);
+
+    function TestComponent() {
+      const setCount = useAtomSet(countAtom);
+      const count = useAtomValue(countAtom);
+      return (
+        <div>
+          <span data-testid='count'>{count()}</span>
+          <button data-testid='set' onClick={() => setCount(10)}>
+            Set to 10
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('count').textContent).toBe('0');
+
+    fireEvent.click(getByTestId('set'));
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('10');
+    });
+  });
+
+  test('supports updater function', async () => {
+    const countAtom = Atom.make(5);
+
+    function TestComponent() {
+      const setCount = useAtomSet(countAtom);
+      const count = useAtomValue(countAtom);
+      return (
+        <div>
+          <span data-testid='count'>{count()}</span>
+          <button data-testid='double' onClick={() => setCount((c) => c * 2)}>
+            Double
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('count').textContent).toBe('5');
+
+    fireEvent.click(getByTestId('double'));
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('10');
+    });
+  });
+});

package/src/hooks/useAtomSet.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import * as Registry from '@effect-atom/atom/Registry';
+import type * as Result from '@effect-atom/atom/Result';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+const flattenExit = <A, E>(exit: Exit.Exit<A, E>): A => {
+  if (Exit.isSuccess(exit)) return exit.value;
+  throw Cause.squash(exit.cause);
+};
+
+export type SetAtomFn<R, W, Mode extends 'value' | 'promise' | 'promiseExit'> = 'promise' extends Mode
+  ? (value: W) => Promise<Result.Result.Success<R>>
+  : 'promiseExit' extends Mode
+    ? (value: W) => Promise<Exit.Exit<Result.Result.Success<R>, Result.Result.Failure<R>>>
+    : (value: W | ((value: R) => W)) => void;
+
+export function createSetAtom<R, W, Mode extends 'value' | 'promise' | 'promiseExit' = never>(
+  registry: Registry.Registry,
+  atom: Atom.Writable<R, W>,
+  options?: {
+    readonly mode?: ([R] extends [Result.Result<any, any>] ? Mode : 'value') | undefined;
+  },
+): SetAtomFn<R, W, Mode> {
+  if (options?.mode === 'promise' || options?.mode === 'promiseExit') {
+    return ((value: W) => {
+      registry.set(atom, value);
+      const promise = Effect.runPromiseExit(
+        Registry.getResult(registry, atom as Atom.Atom<Result.Result<any, any>>, { suspendOnWaiting: true }),
+      );
+      return options!.mode === 'promise' ? promise.then(flattenExit) : promise;
+    }) as SetAtomFn<R, W, Mode>;
+  }
+  return ((value: W | ((value: R) => W)) => {
+    registry.set(atom, typeof value === 'function' ? (value as any)(registry.get(atom)) : value);
+  }) as SetAtomFn<R, W, Mode>;
+}
+
+/**
+ * Hook to get a setter function for an atom
+ * Also mounts the atom in the registry
+ */
+export function useAtomSet<R, W, Mode extends 'value' | 'promise' | 'promiseExit' = never>(
+  atom: Atom.Writable<R, W>,
+  options?: {
+    readonly mode?: ([R] extends [Result.Result<any, any>] ? Mode : 'value') | undefined;
+  },
+): SetAtomFn<R, W, Mode> {
+  const registry = useRegistry();
+
+  // Mount the atom
+  const unmount = registry.mount(atom);
+  onCleanup(unmount);
+
+  return createSetAtom(registry, atom, options);
+}

package/src/hooks/useAtomSubscribe.test.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { fireEvent, render, waitFor } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomSet } from './useAtomSet';
+import { useAtomSubscribe } from './useAtomSubscribe';
+
+describe('useAtomSubscribe', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('calls callback on value changes', async () => {
+    const countAtom = Atom.make(0);
+    const values: number[] = [];
+
+    function TestComponent() {
+      useAtomSubscribe(
+        countAtom,
+        (value) => {
+          values.push(value);
+        },
+        { immediate: true },
+      );
+
+      const setCount = useAtomSet(countAtom);
+      return (
+        <button data-testid='increment' onClick={() => setCount((c) => c + 1)}>
+          +
+        </button>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+
+    // Should have received the initial value
+    expect(values).toContain(0);
+
+    fireEvent.click(getByTestId('increment'));
+
+    await waitFor(() => {
+      expect(values).toContain(1);
+    });
+  });
+});

package/src/hooks/useAtomSubscribe.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import { onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Hook to subscribe to atom changes with a callback
+ */
+export function useAtomSubscribe<A>(
+  atom: Atom.Atom<A>,
+  f: (value: A) => void,
+  options?: { readonly immediate?: boolean },
+): void {
+  const registry = useRegistry();
+
+  const unsubscribe = registry.subscribe(atom, f, options);
+  onCleanup(unsubscribe);
+}

package/src/hooks/useAtomSuspense.test.tsx

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import * as Result from '@effect-atom/atom/Result';
+import { render, waitFor } from '@solidjs/testing-library';
+import { Suspense } from 'solid-js';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomSuspense } from './useAtomSuspense';
+
+describe('useAtomSuspense', () => {
+  beforeEach(() => {
+    defaultRegistry.reset();
+  });
+
+  test('suspends while waiting for value', async () => {
+    const atom = Atom.make<Result.Result<string, never>>(Result.initial());
+
+    function Child() {
+      const value = useAtomSuspense(atom);
+      return <span data-testid='value'>{value()}</span>;
+    }
+
+    function TestComponent() {
+      return (
+        <Suspense fallback={<span data-testid='loading'>Loading</span>}>
+          <Child />
+        </Suspense>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('loading')).toBeTruthy();
+
+    // Update atom
+    defaultRegistry.set(atom, Result.success('ready'));
+
+    await waitFor(() => {
+      expect(getByTestId('value').textContent).toBe('ready');
+    });
+  });
+});

package/src/hooks/useAtomSuspense.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import type * as Result from '@effect-atom/atom/Result';
+import { createResource, onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * Hook to read an atom value with Suspense support
+ */
+export function useAtomSuspense<A, E>(atom: Atom.Atom<Result.Result<A, E>>): () => A {
+  const registry = useRegistry();
+
+  const [data, { mutate, refetch }] = createResource(async () => {
+    // Check if we already have a value
+    const current = registry.get(atom);
+    if (current._tag === 'Success') {
+      return current.value;
+    }
+    if (current._tag === 'Failure') {
+      throw current.cause;
+    }
+
+    // Wait for the next success or failure
+    return new Promise<A>((resolve, reject) => {
+      const unsubscribe = registry.subscribe(atom, (next) => {
+        if (next._tag === 'Success') {
+          unsubscribe();
+          resolve(next.value);
+        } else if (next._tag === 'Failure') {
+          unsubscribe();
+          reject(next.cause);
+        }
+      });
+      // Note: We might want to handle cancellation if the resource is disposed?
+      // But creating a promise that leaks isn't great.
+      // Ideally we tie this to the component, but the promise itself is localized.
+    });
+  });
+
+  // Subscribe to updates to keep the resource fresh
+  const unsubscribe = registry.subscribe(atom, (next) => {
+    if (next._tag === 'Success') {
+      mutate(() => next.value);
+    } else if (next._tag === 'Failure') {
+      // If we encounter a failure, we trigger a refetch which will hit the fetcher
+      // and throw the error (reject the promise)
+      // Or we could try to mutate error state?
+      // createResource doesn't have a direct 'setError'.
+      // Refetching is the safe bet to re-enter the promise/error flow.
+      void refetch();
+    } else if (next._tag === 'Initial' || (next as any).waiting) {
+      // If we go back to loading, refetch to suspend
+      void refetch();
+    }
+  });
+
+  onCleanup(unsubscribe);
+
+  return () => {
+    const value = data();
+    if (value === undefined) {
+      // This case handles when the resource is loading initially
+      // createResource reads undefined (or initial value) when loading if strict mode isn't on for types,
+      // but wrapping it ensures we signal "read" to Suspense.
+      // However, data() itself should trigger Suspense if loading.
+      // We assume standard Suspense behavior.
+    }
+    return value as A;
+  };
+}

package/src/hooks/useAtomValue.test.tsx

@@ -0,0 +1,67 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Atom from '@effect-atom/atom/Atom';
+import { fireEvent, render, waitFor } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { defaultRegistry } from '../registry';
+
+import { useAtomValue } from './useAtomValue';
+
+describe('useAtomValue', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  test('reads initial atom value', () => {
+    const countAtom = Atom.make(42);
+
+    function TestComponent() {
+      const count = useAtomValue(countAtom);
+      return <div data-testid='count'>{count()}</div>;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('count').textContent).toBe('42');
+  });
+
+  test('updates when atom value changes', async () => {
+    const countAtom = Atom.make(0);
+
+    function TestComponent() {
+      const count = useAtomValue(countAtom);
+      return (
+        <div>
+          <span data-testid='count'>{count()}</span>
+          <button data-testid='increment' onClick={() => defaultRegistry.set(countAtom, count() + 1)}>
+            +
+          </button>
+        </div>
+      );
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('count').textContent).toBe('0');
+
+    fireEvent.click(getByTestId('increment'));
+
+    await waitFor(() => {
+      expect(getByTestId('count').textContent).toBe('1');
+    });
+  });
+
+  test('supports mapping function', () => {
+    const countAtom = Atom.make(5);
+
+    function TestComponent() {
+      const doubled = useAtomValue(countAtom, (n) => n * 2);
+      return <div data-testid='doubled'>{doubled()}</div>;
+    }
+
+    const { getByTestId } = render(() => <TestComponent />);
+    expect(getByTestId('doubled').textContent).toBe('10');
+  });
+});

package/src/hooks/useAtomValue.ts

@@ -0,0 +1,57 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import * as AtomModule from '@effect-atom/atom/Atom';
+import { type Accessor, createEffect, createMemo, createSignal, onCleanup } from 'solid-js';
+
+import { useRegistry } from '../registry';
+
+/**
+ * A value that may be a static value or a reactive accessor.
+ */
+type MaybeAccessor<T> = T | Accessor<T>;
+
+/**
+ * Resolves a MaybeAccessor to its value.
+ */
+const access = <T>(value: MaybeAccessor<T>): T => (typeof value === 'function' ? (value as Accessor<T>)() : value);
+
+/**
+ * Hook to read the value of an atom.
+ * The returned accessor will update whenever the atom's value changes.
+ * The atom parameter can be reactive (MaybeAccessor) - if the atom changes,
+ * the hook will automatically unsubscribe from the old atom and subscribe to the new one.
+ */
+export function useAtomValue<A>(atom: MaybeAccessor<Atom.Atom<A>>): Accessor<A>;
+export function useAtomValue<A, B>(atom: MaybeAccessor<Atom.Atom<A>>, f: (a: A) => B): Accessor<B>;
+export function useAtomValue<A>(atom: MaybeAccessor<Atom.Atom<A>>, f?: (a: A) => A): Accessor<A> {
+  const registry = useRegistry();
+
+  // Resolve the atom reactively and apply mapping if provided.
+  const resolvedAtom = createMemo(() => {
+    const a = access(atom);
+    return f ? AtomModule.map(a, f) : a;
+  });
+
+  const [value, setValue] = createSignal<A>(registry.get(resolvedAtom()));
+
+  // Subscribe to atom changes reactively - re-subscribes when atom changes.
+  createEffect(() => {
+    const currentAtom = resolvedAtom();
+    setValue(() => registry.get(currentAtom));
+
+    const unsubscribe = registry.subscribe(
+      currentAtom,
+      (nextValue) => {
+        setValue(() => nextValue);
+      },
+      { immediate: true },
+    );
+
+    onCleanup(unsubscribe);
+  });
+
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as Atom from '@effect-atom/atom/Atom';
+export * as Registry from '@effect-atom/atom/Registry';
+export * as Result from '@effect-atom/atom/Result';
+export * as AtomRef from '@effect-atom/atom/AtomRef';
+export * as AtomHttpApi from '@effect-atom/atom/AtomHttpApi';
+export * as AtomRpc from '@effect-atom/atom/AtomRpc';
+
+export * from './hooks';
+export * from './registry';

package/src/registry.test.tsx

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Registry from '@effect-atom/atom/Registry';
+import { render } from '@solidjs/testing-library';
+import { beforeEach, describe, expect, test } from 'vitest';
+
+import { RegistryProvider, defaultRegistry, useRegistry } from './registry';
+
+describe('registry', () => {
+  beforeEach(() => {
+    // Reset the default registry between tests
+    defaultRegistry.reset();
+  });
+
+  describe('useRegistry', () => {
+    test('returns the default registry', () => {
+      let capturedRegistry: Registry.Registry | null = null;
+
+      function TestComponent() {
+        capturedRegistry = useRegistry();
+        return <div>test</div>;
+      }
+
+      render(() => <TestComponent />);
+      expect(capturedRegistry).toBe(defaultRegistry);
+    });
+  });
+
+  describe('RegistryProvider', () => {
+    test('provides a custom registry to children', () => {
+      const customRegistry = Registry.make();
+      let capturedRegistry: Registry.Registry | null = null;
+
+      function Child() {
+        capturedRegistry = useRegistry();
+        return <div>child</div>;
+      }
+
+      render(() => (
+        <RegistryProvider registry={customRegistry}>
+          <Child />
+        </RegistryProvider>
+      ));
+
+      expect(capturedRegistry).toBe(customRegistry);
+
+      // Clean up
+      customRegistry.dispose();
+    });
+  });
+});

package/src/registry.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Atom from '@effect-atom/atom/Atom';
+import * as Registry from '@effect-atom/atom/Registry';
+import * as GlobalValue from 'effect/GlobalValue';
+import { type Context, createContext, onCleanup, useContext } from 'solid-js';
+
+/**
+ * Default registry instance
+ */
+export const defaultRegistry: Registry.Registry = GlobalValue.globalValue(
+  '@effect-atom/atom-solid/defaultRegistry',
+  () => Registry.make(),
+);
+
+/**
+ * Solid context for the atom registry
+ */
+export const RegistryContext: Context<Registry.Registry> = createContext<Registry.Registry>(defaultRegistry);
+
+/**
+ * Get the current registry from context
+ */
+export const useRegistry = (): Registry.Registry => {
+  return useContext(RegistryContext);
+};
+
+/**
+ * Provider component for custom registry
+ */
+export interface RegistryProviderProps {
+  children: any;
+  registry?: Registry.Registry;
+  initialValues?: Iterable<readonly [Atom.Atom<any>, any]>;
+  scheduleTask?: (f: () => void) => void;
+  timeoutResolution?: number;
+  defaultIdleTTL?: number;
+}
+
+export function RegistryProvider(props: RegistryProviderProps) {
+  const registry =
+    props.registry ??
+    Registry.make({
+      scheduleTask: props.scheduleTask,
+      initialValues: props.initialValues,
+      timeoutResolution: props.timeoutResolution,
+      defaultIdleTTL: props.defaultIdleTTL ?? 400,
+    });
+
+  onCleanup(() => {
+    // Delay disposal to allow for component re-mounting
+    const timeout = setTimeout(() => {
+      registry.dispose();
+    }, 500);
+    return () => clearTimeout(timeout);
+  });
+
+  return RegistryContext.Provider({
+    value: registry,
+    get children() {
+      return props.children;
+    },
+  });
+}