@tmonier/effract 0.1.0

package/src/infrastructure/react/reactivity.test.tsx

@@ -0,0 +1,103 @@
+/**
+ * The signals bridge: a change to an atom re-renders precisely the components
+ * that read it — and leaves the rest untouched.
+ */
+import { act, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Observe, atom, observe, useAtom } from '../../index.ts';
+
+Reflect.set(globalThis, 'IS_REACT_ACT_ENVIRONMENT', true);
+
+let container: HTMLDivElement;
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+afterEach(() => {
+  container.remove();
+});
+
+describe('reactivity', () => {
+  it('observe re-renders when a read atom changes', async () => {
+    const count = atom(1);
+    const Doubled = (): ReactNode => {
+      const doubled = observe(($) => $(count) * 2);
+      return <span>{doubled}</span>;
+    };
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<Doubled />);
+    });
+    expect(container.textContent).toBe('2');
+
+    await act(async () => {
+      count.set(5);
+    });
+    expect(container.textContent).toBe('10');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('useAtom reads and writes like useState, backed by Effect', async () => {
+    const name = atom('ada');
+    const Field = (): ReactNode => {
+      const [value, setValue] = useAtom(name);
+      return (
+        <button type="button" onClick={() => setValue((prev) => `${prev}!`)}>
+          {value}
+        </button>
+      );
+    };
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<Field />);
+    });
+    expect(container.textContent).toBe('ada');
+
+    await act(async () => {
+      container.querySelector('button')?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(container.textContent).toBe('ada!');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('<Observe> tracks only the atoms it actually reads', async () => {
+    const a = atom(1);
+    const b = atom(100);
+    let renders = 0;
+    const View = (): ReactNode => {
+      renders += 1;
+      return <Observe>{($) => <em>{$(a)}</em>}</Observe>;
+    };
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<View />);
+    });
+    const baseline = renders;
+    expect(container.textContent).toBe('1');
+
+    // b is never read by the selector, so changing it must not re-render.
+    await act(async () => {
+      b.set(200);
+    });
+    expect(renders).toBe(baseline);
+
+    await act(async () => {
+      a.set(2);
+    });
+    expect(container.textContent).toBe('2');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+});

package/src/infrastructure/react/reactivity.tsx

@@ -0,0 +1,148 @@
+'use client';
+
+/**
+ * The signals bridge. Effect's reactive cell is `AtomRef`; this binds it to
+ * React so a component re-renders precisely when — and only when — an atom it
+ * actually read changes.
+ *
+ *   observe($ => $(count) * 2)          // a hook: read + auto-subscribe
+ *   <Observe>{$ => <b>{$(count)}</b>}</Observe>   // the same, as an element
+ *   const [n, setN] = useAtom(count)    // read + write a single atom
+ *
+ * `observe` tracks exactly the atoms touched during its selector and subscribes
+ * to that set, re-tracking on every change so dynamic dependencies stay
+ * correct. No `Effect.runSync` at the call site, no manual dependency arrays.
+ */
+import { useCallback, useRef, useSyncExternalStore, type ReactNode } from 'react';
+import * as Equal from 'effect/Equal';
+import { AtomRef } from 'effect/unstable/reactivity';
+
+type Ref<A> = AtomRef.AtomRef<A>;
+
+/** Read an atom inside `observe`, subscribing the component to it. */
+export type Read = <A>(ref: Ref<A>) => A;
+
+/** Create a reactive cell. Sugar for `AtomRef.make`. */
+export const atom = <A,>(initial: A): Ref<A> => AtomRef.make(initial);
+
+interface ObserveState<A> {
+  selector: (read: Read) => A;
+  deps: Map<Ref<unknown>, unknown>;
+  value: A;
+  initialized: boolean;
+}
+
+const depsEqual = (a: Map<Ref<unknown>, unknown>, b: Map<Ref<unknown>, unknown>): boolean => {
+  if (a.size !== b.size) {
+    return false;
+  }
+  for (const [ref, value] of a) {
+    if (!b.has(ref) || !Equal.equals(value, b.get(ref))) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Run the selector, tracking which atoms it reads. Returns a *stable* reference
+ * when the tracked atoms and their values are unchanged, so it is safe to call
+ * from `getSnapshot` without provoking a render loop.
+ */
+const compute = <A,>(state: ObserveState<A>): A => {
+  const nextDeps = new Map<Ref<unknown>, unknown>();
+  const read: Read = (ref) => {
+    const value = ref.value;
+    nextDeps.set(ref as Ref<unknown>, value);
+    return value;
+  };
+  const next = state.selector(read);
+  if (state.initialized && depsEqual(state.deps, nextDeps)) {
+    state.deps = nextDeps;
+    return state.value;
+  }
+  state.deps = nextDeps;
+  state.value = next;
+  state.initialized = true;
+  return next;
+};
+
+/**
+ * Subscribe to a derived view over one or more atoms. Re-renders precisely when
+ * a read atom changes.
+ *
+ * ```tsx
+ * const doubled = observe(($) => $(count) * 2);
+ * ```
+ */
+export const observe = <A,>(selector: (read: Read) => A): A => {
+  const stateRef = useRef<ObserveState<A> | null>(null);
+  if (stateRef.current === null) {
+    stateRef.current = { selector, deps: new Map(), value: undefined as A, initialized: false };
+  }
+  stateRef.current.selector = selector;
+
+  const subscribe = useCallback((onStoreChange: () => void) => {
+    const state = stateRef.current;
+    if (state === null) {
+      return () => {};
+    }
+    let unsubscribes: Array<() => void> = [];
+    const resubscribe = (): void => {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+      unsubscribes = [...state.deps.keys()].map((ref) => ref.subscribe(handleChange));
+    };
+    function handleChange(): void {
+      compute(state as ObserveState<A>);
+      resubscribe();
+      onStoreChange();
+    }
+    compute(state);
+    resubscribe();
+    return () => {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+    };
+  }, []);
+
+  const getSnapshot = useCallback(() => compute(stateRef.current as ObserveState<A>), []);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+
+/** Read a single atom's value, subscribing the component to it. */
+export const useAtomValue = <A,>(ref: Ref<A>): A => {
+  const subscribe = useCallback((onStoreChange: () => void) => ref.subscribe(onStoreChange), [ref]);
+  const getSnapshot = useCallback(() => ref.value, [ref]);
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+
+/** A stable setter for an atom, supporting both values and updater functions. */
+export const useAtomSet = <A,>(ref: Ref<A>): ((value: A | ((prev: A) => A)) => void) =>
+  useCallback(
+    (value) => {
+      if (typeof value === 'function') {
+        ref.update(value as (prev: A) => A);
+      } else {
+        ref.set(value);
+      }
+    },
+    [ref],
+  );
+
+/** Read and write a single atom — the `useState` shape, backed by Effect. */
+export const useAtom = <A,>(ref: Ref<A>): readonly [A, (value: A | ((prev: A) => A)) => void] => [
+  useAtomValue(ref),
+  useAtomSet(ref),
+];
+
+export interface ObserveProps<A extends ReactNode> {
+  readonly children: (read: Read) => A;
+}
+
+/** The render-prop form of {@link observe}. */
+export const Observe = <A extends ReactNode>({ children }: ObserveProps<A>): ReactNode =>
+  observe(children);

package/src/infrastructure/react/runtime.tsx

@@ -0,0 +1,81 @@
+'use client';
+
+/**
+ * The `<Runtime>` boundary. It builds an Effect `ManagedRuntime` once from a
+ * `Layer` and hands it down through React context, where every effract
+ * component reads it. This is the seam where "server vs client" lives: provide
+ * a browser layer and the same components run in a SPA; provide a server layer
+ * and they run under Node, Bun, or a Web Worker — the components never change.
+ *
+ * Services are resolved up-front into the runtime's context (the RSC-style
+ * "resolve near the root" mode), so reading a service inside a component is a
+ * synchronous context lookup, not an async round-trip.
+ */
+import { createContext, useContext, useEffect, useMemo, useRef, type ReactNode } from 'react';
+import type * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import type { Executor } from '#application/ports.ts';
+
+type AnyManagedRuntime = ManagedRuntime.ManagedRuntime<unknown, unknown>;
+
+interface RuntimeContextValue {
+  readonly executor: Executor;
+  readonly runtime: AnyManagedRuntime;
+}
+
+const RuntimeContext = createContext<RuntimeContextValue | null>(null);
+
+const executorFromRuntime = (runtime: AnyManagedRuntime): Executor => ({
+  runSyncExit: (effect) => runtime.runSyncExit(effect),
+  runPromise: (effect) => runtime.runPromise(effect),
+});
+
+export interface RuntimeProps<ROut, E> {
+  /** A self-contained layer (no open requirements) providing the subtree's services. */
+  readonly layer: Layer.Layer<ROut, E, never>;
+  readonly children: ReactNode;
+}
+
+/**
+ * Provide an Effect runtime to a React subtree.
+ *
+ * ```tsx
+ * <Runtime layer={AppLive}>
+ *   <Dashboard />
+ * </Runtime>
+ * ```
+ */
+export function Runtime<ROut, E>({ layer, children }: RuntimeProps<ROut, E>): ReactNode {
+  // Build the runtime exactly once for this boundary instance.
+  const runtimeRef = useRef<AnyManagedRuntime | null>(null);
+  if (runtimeRef.current === null) {
+    runtimeRef.current = ManagedRuntime.make(layer) as AnyManagedRuntime;
+  }
+  const runtime = runtimeRef.current;
+
+  const value = useMemo<RuntimeContextValue>(
+    () => ({ executor: executorFromRuntime(runtime), runtime }),
+    [runtime],
+  );
+
+  // Tear the runtime down (close scopes, finalize layers) when the boundary unmounts.
+  useEffect(() => () => void runtime.dispose(), [runtime]);
+
+  return <RuntimeContext.Provider value={value}>{children}</RuntimeContext.Provider>;
+}
+
+const useRuntimeContext = (): RuntimeContextValue => {
+  const value = useContext(RuntimeContext);
+  if (value === null) {
+    throw new Error(
+      'effract: no <Runtime> found above this component. Wrap your tree in <Runtime layer={...}>.',
+    );
+  }
+  return value;
+};
+
+/** Internal: the executor the interpreter runs effects through. */
+export const useExecutor = (): Executor => useRuntimeContext().executor;
+
+/** Escape hatch: the underlying `ManagedRuntime`, for imperative `runPromise`/`runFork`. */
+export const useEffractRuntime = (): AnyManagedRuntime => useRuntimeContext().runtime;