@tmonier/effract 0.1.0

package/src/application/interpreter.test.ts

@@ -0,0 +1,140 @@
+/**
+ * The interpreter, exercised with no React at all. This is the payoff of
+ * keeping it in the application layer: the entire fiber-bridging logic — hook
+ * unwrapping, synchronous service resolution, async suspension, error
+ * propagation — is testable against plain fakes.
+ */
+import { describe, expect, it } from 'vitest';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import { hook } from '#domain/protocol.ts';
+import { driveRec } from '#application/interpreter.ts';
+import type { Executor, InterpreterDeps, RenderCache, Suspender } from '#application/ports.ts';
+
+class Stats extends Context.Service<Stats, { readonly total: number }>()('test/Stats') {}
+
+const executorWith = (layer: Layer.Layer<never, never, never>): Executor => {
+  const runtime = ManagedRuntime.make(layer) as unknown as ManagedRuntime.ManagedRuntime<
+    unknown,
+    unknown
+  >;
+  return {
+    runSyncExit: (effect) => runtime.runSyncExit(effect),
+    runPromise: (effect) => runtime.runPromise(effect),
+  };
+};
+
+const neverSuspend: Suspender = {
+  use: () => {
+    throw new Error('did not expect to suspend');
+  },
+};
+
+const makeDeps = (
+  layer: Layer.Layer<never, never, never>,
+  suspender: Suspender = neverSuspend,
+): InterpreterDeps => ({
+  executor: executorWith(layer),
+  suspender,
+  cache: new Map(),
+});
+
+describe('driveRec', () => {
+  it('unwraps lifted hooks without touching the runtime', () => {
+    const result = driveRec(
+      (function* () {
+        const a = yield* hook(10);
+        const b = yield* hook(20);
+        return a + b;
+      })(),
+      makeDeps(Layer.empty),
+    );
+    expect(result).toBe(30);
+  });
+
+  it('resolves a service Tag synchronously from the runtime', () => {
+    const result = driveRec(
+      (function* () {
+        const stats = yield* Stats;
+        return stats.total;
+      })(),
+      makeDeps(Layer.succeed(Stats)({ total: 42 })),
+    );
+    expect(result).toBe(42);
+  });
+
+  it('interleaves services and hooks in one render pass — the fiber bridge', () => {
+    const result = driveRec(
+      (function* () {
+        const stats = yield* Stats;
+        const label = yield* hook('overview');
+        const suffix = yield* hook('!');
+        return `${label}:${stats.total}${suffix}`;
+      })(),
+      makeDeps(Layer.succeed(Stats)({ total: 7 })),
+    );
+    expect(result).toBe('overview:7!');
+  });
+
+  it('suspends on an async effect, caching a stable promise, then returns on retry', async () => {
+    const deps = makeDeps(Layer.empty, {
+      use: (promise) => {
+        throw promise;
+      },
+    });
+    const body = function* () {
+      const value = yield* Effect.promise(() => Promise.resolve(99));
+      return value;
+    };
+
+    // First pass: the async effect cannot finish synchronously, so it suspends.
+    let suspended: unknown;
+    try {
+      driveRec(body(), deps);
+      expect.unreachable('should have suspended');
+    } catch (thrown) {
+      suspended = thrown;
+    }
+    expect(suspended).toBeInstanceOf(Promise);
+    expect(deps.cache.size).toBe(1);
+
+    // The cached promise settles to the effect's value.
+    await expect(deps.cache.get(0)?.promise).resolves.toBe(99);
+
+    // Retry with a suspender that returns settled values: now it resolves inline.
+    const retryDeps: InterpreterDeps = {
+      executor: deps.executor,
+      cache: deps.cache,
+      suspender: { use: () => 99 as never },
+    };
+    expect(driveRec(body(), retryDeps)).toBe(99);
+  });
+
+  it('throws a genuine Effect failure to the error boundary', () => {
+    expect.assertions(1);
+    try {
+      driveRec(
+        (function* () {
+          const value = yield* Effect.fail('boom');
+          return value;
+        })(),
+        makeDeps(Layer.empty),
+      );
+    } catch (thrown) {
+      expect(thrown).toBe('boom');
+    }
+  });
+
+  it('rejects a yield that is neither an Effect nor a hook', () => {
+    const cache: RenderCache = new Map();
+    const body = function* () {
+      yield 5 as never; // a bare yield of a non-instruction: the interpreter must reject it
+      return null;
+    };
+    expect(() =>
+      driveRec(body(), { executor: executorWith(Layer.empty), suspender: neverSuspend, cache }),
+    ).toThrow(TypeError);
+  });
+});

package/src/application/interpreter.ts

@@ -0,0 +1,84 @@
+/**
+ * The interpreter — the bridge between React's fiber and Effect's fiber.
+ *
+ * React drives a component by calling its function during a render pass.
+ * `driveRec` runs *inside* that pass: it walks the component's generator
+ * synchronously, and for every `yield*` it decides who answers.
+ *
+ *   - a lifted hook  → the React hook already ran inline; unwrap its value
+ *   - a service Tag  → resolve it synchronously from the runtime's context
+ *   - a sync Effect  → run it synchronously, return its value
+ *   - an async Effect → suspend through React's `use`, resuming on the retry
+ *
+ * Because the walk is synchronous and deterministic, the user's hook calls keep
+ * a stable order across renders — they are, and remain, ordinary React hooks.
+ * Nothing here forks React's reconciler; it cooperates with it.
+ */
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import { isHook, type AnyEffect, type RecGenerator } from '#domain/protocol.ts';
+import type { InterpreterDeps } from '#application/ports.ts';
+
+interface DriveState {
+  index: number;
+}
+
+/**
+ * Resolve a single yielded Effect against the runtime. Synchronous effects
+ * (services, pure computation, ref reads) return immediately. An effect that
+ * cannot finish synchronously surfaces as an `AsyncFiberError`; we route it
+ * through React Suspense with a promise cached by encounter order, so the
+ * retry after the promise settles returns the value inline. Any other failure
+ * is a real error and is thrown to the nearest React error boundary.
+ */
+export const resolveEffect = (
+  effect: AnyEffect,
+  deps: InterpreterDeps,
+  state: DriveState,
+): unknown => {
+  if (!Effect.isEffect(effect)) {
+    throw new TypeError(
+      'effract: a component body yielded a value that is neither an Effect nor a hook(...). ' +
+        'Wrap React hooks with `hook(...)`, e.g. `yield* hook(useState(0))`.',
+    );
+  }
+
+  const exit = deps.executor.runSyncExit(effect);
+  if (Exit.isSuccess(exit)) {
+    return exit.value;
+  }
+
+  const squashed = Cause.squash(exit.cause);
+  if (Cause.isAsyncFiberError(squashed)) {
+    const index = state.index++;
+    let slot = deps.cache.get(index);
+    if (slot === undefined) {
+      slot = { promise: deps.executor.runPromise(effect) };
+      deps.cache.set(index, slot);
+    }
+    // Suspends the render until the cached promise settles, then returns inline.
+    return deps.suspender.use(slot.promise);
+  }
+
+  throw squashed;
+};
+
+/**
+ * Run a React Effect Component body to its rendered result. Creates a fresh
+ * generator per render (generators are single-use); a Suspense retry simply
+ * runs this again from the top, replaying hooks in order and hitting the async
+ * cache for already-started work.
+ */
+export const driveRec = <A>(gen: RecGenerator<A>, deps: InterpreterDeps): A => {
+  const state: DriveState = { index: 0 };
+  let step = gen.next();
+  while (!step.done) {
+    const instruction = step.value;
+    const result = isHook(instruction)
+      ? instruction.value
+      : resolveEffect(instruction, deps, state);
+    step = gen.next(result);
+  }
+  return step.value;
+};

package/src/application/ports.ts

@@ -0,0 +1,47 @@
+/**
+ * Ports the interpreter depends on. Both are capabilities the *infrastructure*
+ * supplies — an Effect runtime and React's `use` — so the reconciler itself
+ * stays free of any concrete runtime or renderer and can be unit-tested with
+ * plain fakes.
+ */
+import type * as Exit from 'effect/Exit';
+import type { AnyEffect } from '#domain/protocol.ts';
+
+/**
+ * Something that can run an Effect. Backed in production by a `ManagedRuntime`
+ * built once at the `<Runtime>` boundary, which already carries the resolved
+ * service environment — so `runSyncExit` resolves services synchronously and
+ * only genuinely asynchronous work falls through to `runPromise`.
+ */
+export interface Executor {
+  readonly runSyncExit: (effect: AnyEffect) => Exit.Exit<unknown, unknown>;
+  readonly runPromise: (effect: AnyEffect) => Promise<unknown>;
+}
+
+/**
+ * React's `use`, injected. Given a stable promise it suspends the render until
+ * the promise settles, then returns the value (or throws to the nearest error
+ * boundary). The interpreter never imports React — it asks for this instead.
+ */
+export interface Suspender {
+  readonly use: <A>(promise: Promise<A>) => A;
+}
+
+/** One suspended async slot: the stable promise React's `use` will track. */
+interface AsyncSlot {
+  readonly promise: Promise<unknown>;
+}
+
+/**
+ * Per-component-instance cache of suspended async effects, keyed by the order
+ * in which they are encountered during a render. Persisted across renders (and
+ * across a Suspense retry) by a `useRef` in the React adapter, which gives
+ * async effects load-once semantics for the lifetime of the component.
+ */
+export type RenderCache = Map<number, AsyncSlot>;
+
+export interface InterpreterDeps {
+  readonly executor: Executor;
+  readonly suspender: Suspender;
+  readonly cache: RenderCache;
+}

package/src/domain/protocol.ts

@@ -0,0 +1,110 @@
+/**
+ * The yield protocol that lets a single generator body speak two languages at
+ * once: Effect (services, effects) and React (hooks). This module is the pure
+ * heart of the framework — it knows nothing about React or about how effects
+ * are executed. It only defines *what* can flow through `yield*` and how the
+ * interpreter recognises each kind.
+ *
+ * Two kinds of value travel through `yield*`:
+ *
+ *   yield* SomeService          // an Effect (a service Tag is itself an Effect)
+ *   yield* hook(useState(0))    // a Hook: a real React hook call, lifted in
+ *
+ * Both implement the single-shot iterator protocol that `yield*` delegates to,
+ * so the interpreter receives the instruction, resolves it, and feeds the
+ * result back into the generator — exactly how `Effect.gen` drives Tags.
+ */
+import type * as Effect from 'effect/Effect';
+
+/**
+ * The one unavoidable `any` in the framework. The heterogeneous yield protocol
+ * must accept an Effect of *any* error and requirement variance — there is no
+ * other way to express "some Effect" as a generic constraint, which is why
+ * Effect's own `Effect.gen` is typed exactly this way. Precise `E` and `R` are
+ * recovered below through conditional inference, so this never leaks to users.
+ */
+// oxlint-disable-next-line typescript/no-explicit-any
+export type AnyEffect = Effect.Effect<any, any, any>;
+
+/** Brand identifying a lifted React hook instruction. */
+export const HookTypeId = Symbol.for('@tmonier/effract/Hook');
+export type HookTypeId = typeof HookTypeId;
+
+/**
+ * A React hook result lifted into the `yield*` channel. The hook itself has
+ * already executed (synchronously, during render) by the time the value is
+ * wrapped — `hook(useState(0))` calls `useState` inline. Wrapping it only makes
+ * the result yieldable, so a component body reads as one uniform stream of
+ * `yield*`s whether the value comes from Effect or from React.
+ */
+export interface Hook<out A> {
+  readonly [HookTypeId]: true;
+  readonly value: A;
+  [Symbol.iterator](): Iterator<Hook<A>, A>;
+}
+
+/**
+ * Lift an already-evaluated React hook result into the effract yield channel.
+ *
+ * ```ts
+ * const [tab, setTab] = yield* hook(useState('overview'));
+ * const ref = yield* hook(useRef<HTMLDivElement>(null));
+ * ```
+ *
+ * Because the component body runs synchronously inside React's render pass, the
+ * wrapped hook call obeys the Rules of Hooks: same order on every render.
+ */
+export const hook = <A>(value: A): Hook<A> => {
+  const self: Hook<A> = {
+    [HookTypeId]: true,
+    value,
+    [Symbol.iterator]() {
+      let yielded = false;
+      return {
+        next(sent?: unknown): IteratorResult<Hook<A>, A> {
+          if (yielded) {
+            return { done: true, value: sent as A };
+          }
+          yielded = true;
+          return { done: false, value: self };
+        },
+      };
+    },
+  };
+  return self;
+};
+
+/** Type guard: is this yielded instruction a lifted hook? */
+export const isHook = (u: unknown): u is Hook<unknown> =>
+  typeof u === 'object' && u !== null && HookTypeId in u;
+
+/** Everything a component body may `yield*`: an Effect, or a lifted hook. */
+export type Yieldable<A> = Effect.Effect<A, unknown, unknown> | Hook<A>;
+
+/** The generator a React Effect Component body produces. */
+export type RecGenerator<A> = Generator<AnyEffect | Hook<unknown>, A, unknown>;
+
+/** A component body: props in, a generator of yields ending in a rendered `A`. */
+export type RecBody<Props, A> = (props: Props) => RecGenerator<A>;
+
+/**
+ * Distribute over the yield union and keep only its Effect members. Hooks are
+ * not Effects, so they drop away — leaving just what carries `E` and `R`.
+ */
+type EffectsOnly<Eff> = Eff extends AnyEffect ? Eff : never;
+
+/**
+ * Recover the Effect requirement channel `R` from everything a body yields.
+ * A body that needs both `A` and `B` requires `A & B`, which is exactly the
+ * intersection TypeScript infers from the contravariant requirement slot.
+ */
+export type RequirementsOf<Eff> = [EffectsOnly<Eff>] extends [
+  Effect.Effect<unknown, unknown, infer R>,
+]
+  ? R
+  : never;
+
+/** Recover the Effect error channel `E` (a union — any yielded effect may fail). */
+export type ErrorsOf<Eff> = [EffectsOnly<Eff>] extends [Effect.Effect<unknown, infer E, unknown>]
+  ? E
+  : never;

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * effract — write React components as Effect programs.
+ *
+ * The same component runs in a SPA, on a Bun/Node server, in a Web Worker, or
+ * as a React Server Component. "Server vs client" is an Effect runtime detail,
+ * supplied by a `<Runtime>` boundary — not an architectural fork.
+ *
+ * @packageDocumentation
+ */
+
+export const VERSION = '0.1.0';
+
+// --- the yield protocol ---
+export { hook, isHook, HookTypeId } from '#domain/protocol.ts';
+export type {
+  AnyEffect,
+  Hook,
+  Yieldable,
+  RecBody,
+  RecGenerator,
+  RequirementsOf,
+  ErrorsOf,
+} from '#domain/protocol.ts';
+
+// --- components ---
+export { component, view } from '#infrastructure/react/component.tsx';
+export type { Component } from '#infrastructure/react/component.tsx';
+
+// --- the runtime boundary ---
+export { Runtime, useEffractRuntime } from '#infrastructure/react/runtime.tsx';
+export type { RuntimeProps } from '#infrastructure/react/runtime.tsx';
+
+// --- reactivity ---
+export {
+  observe,
+  Observe,
+  atom,
+  useAtom,
+  useAtomValue,
+  useAtomSet,
+} from '#infrastructure/react/reactivity.tsx';
+export type { Read, ObserveProps } from '#infrastructure/react/reactivity.tsx';

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

@@ -0,0 +1,140 @@
+/**
+ * The proof that effract is 100% real React: a React Effect Component is an
+ * ordinary component that React renders, holds hook state for, suspends, and
+ * re-renders — with Effect services resolved in the same pass.
+ */
+import { Suspense, act, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { Runtime, component, hook } from '../../index.ts';
+
+Reflect.set(globalThis, 'IS_REACT_ACT_ENVIRONMENT', true);
+
+class Stats extends Context.Service<Stats, { readonly total: number }>()('test/Stats') {}
+const statsLayer = (total: number): Layer.Layer<never, never, never> =>
+  Layer.succeed(Stats)({ total });
+
+let container: HTMLDivElement;
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+afterEach(() => {
+  container.remove();
+});
+
+describe('component (React Effect Component)', () => {
+  it('renders a service + hook REC to static markup in one pass', () => {
+    const Dashboard = component(function* () {
+      const stats = yield* Stats;
+      const [tab] = yield* hook(useState('overview'));
+      return (
+        <div>
+          {tab}:{stats.total}
+        </div>
+      );
+    });
+
+    const html = renderToStaticMarkup(
+      <Runtime layer={statsLayer(42)}>
+        <Dashboard />
+      </Runtime>,
+    );
+    expect(html).toContain('overview');
+    expect(html).toContain('42');
+  });
+
+  it('holds genuine hook state across re-renders while re-resolving services', async () => {
+    const Counter = component(function* () {
+      const stats = yield* Stats;
+      const [n, setN] = yield* hook(useState(0));
+      return (
+        <button type="button" onClick={() => setN(n + 1)}>
+          {n}/{stats.total}
+        </button>
+      );
+    });
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <Runtime layer={statsLayer(42)}>
+          <Counter />
+        </Runtime>,
+      );
+    });
+    expect(container.textContent).toBe('0/42');
+
+    // Clicking drives a real useState update: the generator re-runs, the hook
+    // remembers its state, and the Stats service resolves again in the new pass.
+    const button = container.querySelector('button');
+    await act(async () => {
+      button?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(container.textContent).toBe('1/42');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('suspends an async effect through React Suspense, then resolves it', async () => {
+    let release: (value: number) => void = () => {};
+    const gate = new Promise<number>((resolve) => {
+      release = resolve;
+    });
+
+    const AsyncPanel = component(function* () {
+      const value = yield* Effect.promise(() => gate);
+      return <span>val:{value}</span>;
+    });
+
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(
+        <Runtime layer={Layer.empty}>
+          <Suspense fallback={<i>loading</i>}>
+            <AsyncPanel />
+          </Suspense>
+        </Runtime>,
+      );
+    });
+    expect(container.textContent).toContain('loading');
+
+    await act(async () => {
+      release(7);
+      await gate;
+    });
+    expect(container.textContent).toContain('val:7');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('runs the SAME component under two runtimes — server vs client is a runtime detail', () => {
+    const Total = component(function* () {
+      const stats = yield* Stats;
+      return <output>{stats.total}</output>;
+    });
+
+    const onServer = renderToStaticMarkup(
+      <Runtime layer={statsLayer(100)}>
+        <Total />
+      </Runtime>,
+    );
+    const onClient = renderToStaticMarkup(
+      <Runtime layer={statsLayer(1)}>
+        <Total />
+      </Runtime>,
+    );
+
+    expect(onServer).toContain('100');
+    expect(onClient).toContain('1');
+    expect(onServer).not.toBe(onClient);
+  });
+});

package/src/infrastructure/react/component.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+/**
+ * The two ways to write a component as an Effect program.
+ *
+ *   component(function* () { ... })   the headline: a *React Effect Component*
+ *                                     whose body yields both Effect services
+ *                                     and React hooks, interpreted inside the
+ *                                     render pass.
+ *
+ *   view(Effect | (props) => Effect)  the simpler resolve-up-front mode: a pure
+ *                                     Effect with no hooks, ideal for server /
+ *                                     RSC rendering.
+ *
+ * Both produce a genuine React function component. There is no custom
+ * reconciler — `<Dashboard />` is a real element React renders, suspends, and
+ * reconciles like any other.
+ */
+import { use, useRef, type ReactNode } from 'react';
+import type * as Effect from 'effect/Effect';
+import { driveRec, resolveEffect } from '#application/interpreter.ts';
+import type { RenderCache, Suspender } from '#application/ports.ts';
+import type { AnyEffect, Hook, RequirementsOf } from '#domain/protocol.ts';
+import { useExecutor } from '#infrastructure/react/runtime.tsx';
+
+declare const RequirementsId: unique symbol;
+
+/**
+ * A React component produced by effract. It renders like any other component;
+ * the phantom `R` records which Effect services it needs from its `<Runtime>`,
+ * available for type-level introspection and runtime-binding helpers.
+ */
+export interface Component<in Props, out R> {
+  (props: Props): ReactNode;
+  readonly [RequirementsId]?: R;
+}
+
+const useSuspender = (): Suspender => ({ use });
+
+const useRenderCache = (): RenderCache => {
+  const ref = useRef<RenderCache>(undefined as unknown as RenderCache);
+  if (ref.current === undefined) {
+    ref.current = new Map();
+  }
+  return ref.current;
+};
+
+/**
+ * Define a React Effect Component. The body is a generator that may `yield*`
+ * Effect services and effects, and `yield* hook(...)` for React hooks.
+ *
+ * ```tsx
+ * const Dashboard = component(function* () {
+ *   const stats = yield* Stats;                         // Effect service
+ *   const [tab, setTab] = yield* hook(useState('overview')); // real React hook
+ *   return <Panel tab={tab} total={stats.total} onTab={setTab} />;
+ * });
+ * ```
+ */
+export function component<Eff extends AnyEffect | Hook<unknown>, A extends ReactNode>(
+  body: () => Generator<Eff, A, never>,
+): Component<Record<never, never>, RequirementsOf<Eff>>;
+export function component<Eff extends AnyEffect | Hook<unknown>, A extends ReactNode, Props>(
+  body: (props: Props) => Generator<Eff, A, never>,
+): Component<Props, RequirementsOf<Eff>>;
+export function component<Eff extends AnyEffect | Hook<unknown>, A extends ReactNode, Props>(
+  body: (props: Props) => Generator<Eff, A, never>,
+): Component<Props, RequirementsOf<Eff>> {
+  const Rec = (props: Props): ReactNode => {
+    const executor = useExecutor();
+    const suspender = useSuspender();
+    const cache = useRenderCache();
+    return driveRec(body(props), { executor, suspender, cache });
+  };
+  Rec.displayName = body.name || 'EffractComponent';
+  return Rec as Component<Props, RequirementsOf<Eff>>;
+}
+
+/**
+ * Define a resolve-up-front component: a pure Effect (no hooks) rendered to a
+ * `ReactNode`. Services resolve synchronously from the runtime; async work
+ * suspends through React Suspense. This is the RSC-friendly mode.
+ *
+ * ```tsx
+ * const Header = view(Effect.gen(function* () {
+ *   const user = yield* CurrentUser;
+ *   return <h1>Welcome, {user.name}</h1>;
+ * }));
+ * ```
+ */
+export function view<A extends ReactNode, E, R>(
+  render: Effect.Effect<A, E, R>,
+): Component<Record<never, never>, R>;
+export function view<A extends ReactNode, E, R, Props>(
+  render: (props: Props) => Effect.Effect<A, E, R>,
+): Component<Props, R>;
+export function view<A extends ReactNode, E, R, Props>(
+  render: Effect.Effect<A, E, R> | ((props: Props) => Effect.Effect<A, E, R>),
+): Component<Props, R> {
+  const View = (props: Props): ReactNode => {
+    const executor = useExecutor();
+    const suspender = useSuspender();
+    const cache = useRenderCache();
+    const effect = (typeof render === 'function' ? render(props) : render) as AnyEffect;
+    return resolveEffect(effect, { executor, suspender, cache }, { index: 0 }) as ReactNode;
+  };
+  View.displayName = 'EffractView';
+  return View as Component<Props, R>;
+}