@playfast/reform 0.0.7 → 0.0.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "type": "module",
   "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
   "keywords": [
@@ -28,7 +28,7 @@
     "./*": "./src/*.ts"
   },
   "files": [
-    "dist",
+    "src",
     "README.md"
   ],
   "scripts": {

package/src/boundary/boundary.test.ts

@@ -0,0 +1,301 @@
+import { expect, it } from '@effect/vitest'
+import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
+import { AsyncCalc, Boundary, Calc, Engine, Event, State, StateGroup } from '../index'
+
+// Boundary merges several async lifecycles into one Pending/Errored/Ready value
+// — the Suspense-boundary analog, value-level. The behaviours under test: the
+// arm mapping (Loading pends, Idle and SWR-refetching count Ready, Error
+// surfaces), the chained-gate settle-gap pin, the `once` latch, and the
+// notification economy (arm-stable churn wakes nobody).
+
+const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
+
+const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
+  Effect.suspend(() => {
+    const a = read()
+    return pred(a) || rounds <= 0
+      ? Effect.succeed(a)
+      : Effect.flatMap(tick(10), () => until(read, pred, rounds - 1))
+  })
+
+class Boom extends Data.TaggedError('Boom')<{ readonly message: string }> {}
+
+it.live('pending while ANY covered query is on its first load; one Ready when all settle', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Fast extends AsyncCalc.make('Fast', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Slow extends AsyncCalc.make('Slow', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Fast, Slow] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Fast, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('10 millis')) }),
+        AsyncCalc.live(Slow, { query: ({ seed }) => Effect.succeed(seed).pipe(Effect.delay('40 millis')) }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const observed: Array<string> = []
+    store.subscribe(() => {
+      observed.push(store.get()._tag)
+    })
+    expect(store.get()._tag).toBe('Pending')
+
+    // The fast query settles first — still Pending (the slow one holds it).
+    yield* tick(20)
+    expect(store.get()._tag).toBe('Pending')
+
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    // Exactly ONE notification fired across the whole boot: Pending→Pending
+    // churn (Fast settling) was absorbed by the stable arm reference.
+    expect(observed).toEqual(['Ready'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a gated query that is OFF counts Ready — the off arm must not hold the gate', () => {
+  class Flag extends State.make('flag', S.Boolean) {}
+  class Inputs extends StateGroup.make(Flag) {}
+  class Always extends AsyncCalc.make('Always', {
+    inputs: [StateGroup.select(Inputs, 'flag')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gated extends AsyncCalc.make('Gated', {
+    inputs: [StateGroup.select(Inputs, 'flag')],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Always, Gated] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Always, { query: () => Effect.succeed(1) }),
+        AsyncCalc.live(Gated, { query: () => Effect.succeed(2), disabled: ({ flag }) => !flag }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { flag: false })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    // The gated query is Idle (deliberately off): only the always-on first
+    // load pends, and Ready arrives without ever waiting on the Idle arm.
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('an SWR refetch never re-pends — Success with refetching: true is Ready', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Q] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(Q, {
+        query: ({ seed }) => Effect.succeed(seed * 2).pipe(Effect.delay('15 millis')),
+      }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const seed = yield* StateGroup.select(Inputs, 'seed').store
+    const qStore = yield* Q.store
+    const store = yield* Gate.store
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+
+    // Move the input: the query goes Success+refetching (SWR) — Ready holds.
+    seed.set(2)
+    yield* until(() => qStore.get(), (q) => q._tag === 'Success' && q.refetching)
+    expect(store.get()._tag).toBe('Ready')
+    yield* until(() => qStore.get(), (q) => q._tag === 'Success' && !q.refetching)
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('a first-load failure surfaces as Errored with the failure, and a retry recovers', () => {
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class Poke extends Event.make('Poke', S.Struct({})) {}
+  const healthy = { now: false }
+  class Q extends AsyncCalc.make('Q', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    error: S.instanceOf(Boom),
+    alwaysOn: true,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Q] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(Q, {
+        query: () =>
+          healthy.now ? Effect.succeed(1) : Effect.fail(new Boom({ message: 'server down' })),
+        invalidateOn: [Poke],
+      }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+    Layer.provideMerge(Engine),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const errored = yield* until(() => store.get(), (s) => s._tag === 'Errored')
+    if (errored._tag === 'Errored') {
+      expect(errored.errors).toHaveLength(1)
+      const failure = errored.errors[0]
+      expect(failure instanceof Boom && failure.message).toBe('server down')
+    }
+
+    // The retry path: the server heals, a listed fact refetches, Ready lands.
+    healthy.now = true
+    yield* Event.dispatch(Poke, {})
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('settle-gap pin: a chained gate never leaks Ready between hops', () => {
+  // B enables only when A has succeeded — the app's Session → Bootstrap shape.
+  // The dangerous instant: A flips Success while B is still Idle (Idle counts
+  // Ready), so a naive merge could notify Ready before B's driver flips it to
+  // Loading. Layer dependency order (B's driver subscribes to A's store before
+  // the boundary does) plus the one-microtask fixpoint flush close the gap;
+  // this records every notification to prove no intermediate Ready escapes.
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class A extends AsyncCalc.make('A', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class B extends AsyncCalc.make('B', {
+    inputs: [A],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [A, B] }) {}
+  const TestLayer = Boundary.live(Gate).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(B, {
+        query: () => Effect.succeed(2).pipe(Effect.delay('15 millis')),
+        disabled: ({ A: a }) => a._tag !== 'Success',
+      }),
+    ),
+    Layer.provideMerge(
+      AsyncCalc.live(A, { query: () => Effect.succeed(1).pipe(Effect.delay('15 millis')) }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const store = yield* Gate.store
+    const observed: Array<string> = []
+    store.subscribe(() => {
+      observed.push(store.get()._tag)
+    })
+    expect(store.get()._tag).toBe('Pending')
+
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    yield* tick(30) // let any straggler notification land before judging
+    // ONE Ready, at the end — never a Ready while B's hop was still pending.
+    expect(observed).toEqual(['Ready'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('once + a Calc hop in the chain: the latch never freezes a mid-flush Ready', () => {
+  // The app's boot shape: AsyncCalc A → plain Calc projecting it → AsyncCalc B
+  // gated on the projection. Propagation crosses TWO scheduler-flush rounds,
+  // so when A settles there is a mid-flush frame where B has not yet flipped
+  // to Loading — a recompute-time latch would freeze that intermediate Ready
+  // and the boundary would abandon B's whole first load (caught live by the
+  // boot-frames walk: nav in, boards card still spinning).
+  class Seed extends State.make('seed', S.Number) {}
+  class Inputs extends StateGroup.make(Seed) {}
+  class A extends AsyncCalc.make('A', {
+    inputs: [StateGroup.select(Inputs, 'seed')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Hop extends Calc.make('Hop', { inputs: [A], output: S.Number }) {}
+  class B extends AsyncCalc.make('B', {
+    inputs: [Hop],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [A, B] }) {}
+  const TestLayer = Boundary.live(Gate, { once: true }).pipe(
+    Layer.provideMerge(
+      AsyncCalc.live(B, {
+        query: () => Effect.succeed(2).pipe(Effect.delay('25 millis')),
+        disabled: ({ Hop: hop }) => hop < 0,
+      }),
+    ),
+    Layer.provideMerge(Calc.live(Hop, ({ A: a }) => (a._tag === 'Success' ? a.value : -1))),
+    Layer.provideMerge(
+      AsyncCalc.live(A, { query: () => Effect.succeed(1).pipe(Effect.delay('15 millis')) }),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+  )
+  return Effect.gen(function* () {
+    const bStore = yield* B.store
+    const store = yield* Gate.store
+    // While B's first load is in flight the boundary MUST still be Pending —
+    // a poisoned latch would already report Ready here.
+    yield* until(() => bStore.get()._tag, (t) => t === 'Loading')
+    expect(store.get()._tag).toBe('Pending')
+    yield* until(() => bStore.get()._tag, (t) => t === 'Success')
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('once: a covered gate enabling AFTER the latch never re-pends the boundary', () => {
+  // The boot-boundary semantics: a route-gated query (the board) first loads
+  // on a later navigation — its own screen owns that loading state, the shell
+  // splash must not come back.
+  class Route extends State.make('routeFlag', S.Boolean) {}
+  class Inputs extends StateGroup.make(Route) {}
+  class Always extends AsyncCalc.make('Always', {
+    inputs: [StateGroup.select(Inputs, 'routeFlag')],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  class Routed extends AsyncCalc.make('Routed', {
+    inputs: [StateGroup.select(Inputs, 'routeFlag')],
+    output: S.Number,
+  }) {}
+  class Gate extends Boundary.make('Gate', { over: [Always, Routed] }) {}
+  const TestLayer = Boundary.live(Gate, { once: true }).pipe(
+    Layer.provideMerge(
+      Layer.merge(
+        AsyncCalc.live(Always, { query: () => Effect.succeed(1) }),
+        AsyncCalc.live(Routed, {
+          query: () => Effect.succeed(2).pipe(Effect.delay('20 millis')),
+          disabled: ({ routeFlag }) => !routeFlag,
+        }),
+      ),
+    ),
+    Layer.provideMerge(StateGroup.live(Inputs, { routeFlag: false })),
+  )
+  return Effect.gen(function* () {
+    const route = yield* StateGroup.select(Inputs, 'routeFlag').store
+    const routedStore = yield* Routed.store
+    const store = yield* Gate.store
+    yield* until(() => store.get()._tag, (t) => t === 'Ready')
+
+    // "Navigate": the routed query enables and goes Loading — latched Ready holds.
+    route.set(true)
+    yield* until(() => routedStore.get()._tag, (t) => t === 'Loading')
+    expect(store.get()._tag).toBe('Ready')
+    yield* until(() => routedStore.get()._tag, (t) => t === 'Success')
+    expect(store.get()._tag).toBe('Ready')
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/boundary/boundary.ts

@@ -0,0 +1,192 @@
+import { Context, Data, Effect, Layer, MutableRef, Predicate } from 'effect'
+import { type Manifest, yieldableClass } from '../definition/definition'
+import { resolveScheduler } from '../internal/scheduler'
+import { type InputStores, sameKey, wireSources } from '../internal/sources'
+import { makeDerivedStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+import { type Source } from '../state/token'
+
+// Boundary: the Suspense-boundary analog, value-level. One derived store that
+// merges the lifecycles of several async sources into a single
+// Pending/Errored/Ready value, so ONE surface (a splash, a skeleton) covers a
+// whole subtree's first load instead of every query consumer painting its own.
+//
+// Reform can do this without React's throw-a-promise machinery because
+// fetching is layer-driven, not render-driven: an `AsyncCalc` runs because its
+// layer is built, never because something rendered. A boundary therefore only
+// *aggregates* lifecycles — it cannot create render-waterfalls, and content it
+// reveals already has its data.
+//
+// The arm mapping IS the semantics, and most of it falls out of `AsyncData`:
+//   Loading            → Pending  (the arm only exists before the first value,
+//                                  so a boundary is first-load-only by construction)
+//   Success            → Ready    (even `refetching: true` — SWR refetches never
+//                                  re-show the fallback; no transition machinery)
+//   Idle               → Ready    (a gated query that is off is DELIBERATELY off —
+//                                  a signed-out viewer must not wait on a query
+//                                  that only runs signed-in)
+//   Error              → Errored  (the error-boundary half, also value-level)
+//
+// Chained gates (B enables when A succeeds) cannot leak a Ready between hops:
+// the boundary's layer requires every covered store, so each driver subscribes
+// upstream BEFORE the boundary does, the scheduler flush runs listeners in
+// subscription order to a fixpoint within one microtask, and reads are
+// pull-fresh — by the time any subscriber reads, the next hop is already
+// Loading. `boundary.test.ts` pins this with a recorded-notification proof.
+
+/** Some covered source is still on its FIRST load — show the fallback. */
+export interface BoundaryPending {
+  readonly _tag: 'Pending'
+}
+
+/** Some covered source failed before its first value. */
+export interface BoundaryErrored {
+  readonly _tag: 'Errored'
+  /** The failures, in `over` order (heterogeneous — display via `String`). */
+  readonly errors: ReadonlyArray<unknown>
+}
+
+/** Every covered source has settled (or is deliberately gated off). */
+export interface BoundaryReady {
+  readonly _tag: 'Ready'
+}
+
+export type BoundaryState = BoundaryPending | BoundaryErrored | BoundaryReady
+
+// Stable arm references: repeated recomputes return the same object, so the
+// derived store's Equal gate (and `useSyncExternalStore`'s stable-snapshot
+// contract) hold without a wrapper. `Errored` carries data, so it is a `Data`
+// struct — value-equal failures coalesce the same way.
+const pendingArm: BoundaryState = { _tag: 'Pending' }
+const readyArm: BoundaryState = { _tag: 'Ready' }
+const erroredArm = (errors: ReadonlyArray<unknown>): BoundaryState =>
+  Data.struct({ _tag: 'Errored' as const, errors: Data.array(errors) })
+
+/**
+ * Anything a boundary can cover: a `Source` whose value is an async lifecycle —
+ * an `AsyncCalc`, or anything lifecycle-valued built over one (e.g. a
+ * `RemoteState` overlay). The constraint is the same erased `Source` every calc
+ * input uses (store invariance rules out a fixed lifecycle value type — each
+ * definition's union carries its own `Gated`/`E` arms); the captured `const`
+ * tuple keeps each member's precise store requirement, and the runtime merge
+ * reads arms through structural guards, so a non-lifecycle source simply
+ * counts as settled.
+ */
+export type AnyLifecycleSource = Source<string, any>
+
+export interface BoundaryManifest<N extends string> extends Manifest {
+  readonly kind: 'Boundary'
+  readonly name: N
+}
+
+export interface BoundaryClass<out N extends string, out Over extends ReadonlyArray<AnyLifecycleSource>>
+  extends Effect.Effect<BoundaryState, never, Store<BoundaryState>> {
+  new (): {}
+  readonly manifest: BoundaryManifest<N>
+  readonly store: Context.Tag<Store<BoundaryState>, Store<BoundaryState>>
+  /** The boundary's name, so it doubles as a `Source` input to a calc. */
+  readonly name: N
+  /** The covered lifecycle sources — read by `live` and the editor's graph. */
+  readonly over: Over
+}
+
+export interface BoundaryConfig<Over extends ReadonlyArray<AnyLifecycleSource>> {
+  readonly over: Over
+}
+
+export interface BoundaryOptions {
+  /**
+   * Latch: once Ready, stay Ready. A BOOT boundary wants this — a covered
+   * route-gated query that first enables on a later navigation (Idle →
+   * Loading) must not re-splash the whole shell; its own screen owns that
+   * loading state. Without the latch the boundary re-pends on any covered
+   * first load, which is what a per-screen boundary wants.
+   */
+  readonly once?: boolean
+}
+
+/**
+ * Define a boundary over async sources. `yield* MyBoundary` reads the merged
+ * `Pending | Errored | Ready` lifecycle; the consuming view renders ONE
+ * fallback on Pending and its content slot on Ready — content reveals
+ * together, with data already present (fetching never waited on rendering).
+ */
+export const make = <const N extends string, const Over extends ReadonlyArray<AnyLifecycleSource>>(
+  name: N,
+  config: BoundaryConfig<Over>,
+): BoundaryClass<N, Over> => {
+  const store = Context.GenericTag<Store<BoundaryState>, Store<BoundaryState>>(
+    `reform/boundary/${name}`,
+  )
+  const manifest: BoundaryManifest<N> = { kind: 'Boundary', name }
+  const read = Effect.flatMap(store, readTracked)
+  return yieldableClass(read, { manifest, store, name, over: config.over })
+}
+
+// The snapshot values arrive through `wireSources`' erased key projection
+// (`ReadonlyArray<unknown>`), so read the two facts the merge needs through
+// honest structural guards — no cast back to `AnyAsyncData`.
+const tagOf = (arm: unknown): string =>
+  Predicate.hasProperty(arm, '_tag') && Predicate.isString(arm._tag) ? arm._tag : ''
+const errorOf = (arm: unknown): ReadonlyArray<unknown> =>
+  Predicate.hasProperty(arm, 'error') && tagOf(arm) === 'Error' ? [arm.error] : []
+
+/**
+ * Wire the merge. A derived store over the covered stores (sensed through the
+ * same `wireSources` plumbing every calc uses): recomputes are memoized on the
+ * input snapshots and the arms are stable references, so input churn that does
+ * not move the merged arm wakes nobody.
+ */
+export const live = <N extends string, Over extends ReadonlyArray<AnyLifecycleSource>>(
+  boundary: BoundaryClass<N, Over>,
+  options: BoundaryOptions = {},
+): Layer.Layer<Store<BoundaryState>, never, InputStores<Over>> =>
+  // Scoped so the source subscriptions are released with the layer's scope.
+  Layer.scoped(
+    boundary.store,
+    Effect.gen(function* () {
+      const scheduler = yield* resolveScheduler
+      const sources = yield* wireSources(boundary.over)
+
+      const latched = MutableRef.make(false)
+      const memo = MutableRef.make<
+        { readonly key: ReadonlyArray<unknown>; readonly value: BoundaryState } | undefined
+      >(undefined)
+      const recompute = (): BoundaryState => {
+        if (options.once === true && MutableRef.get(latched)) return readyArm
+        const arms = sources.keyOf(sources.snapshot())
+        const prev = MutableRef.get(memo)
+        if (prev !== undefined && sameKey(arms, prev.key)) return prev.value
+        const errors = arms.flatMap(errorOf)
+        const value =
+          errors.length > 0
+            ? erroredArm(errors)
+            : arms.some((arm) => tagOf(arm) === 'Loading')
+              ? pendingArm
+              : readyArm
+        MutableRef.set(memo, { key: arms, value })
+        return value
+      }
+
+      const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
+      yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
+
+      if (options.once === true) {
+        // Latch on CONVERGED values only — at build and on (coalesced,
+        // post-fixpoint) notifications — never inside `recompute`. A chained
+        // gate with a plain Calc hop between the async stores (bootstrap →
+        // current-workspace → boards) propagates over TWO flush rounds, so a
+        // mid-flush recompute can observe the frame where the downstream
+        // driver has not yet flipped its query to Loading. That intermediate
+        // Ready self-corrects within the flush for readers, but a latch taken
+        // there would freeze it; a subscriber runs only after the fixpoint,
+        // where the value is converged.
+        if (recompute()._tag === 'Ready') MutableRef.set(latched, true)
+        const offSelf = derived.store.subscribe(() => {
+          if (derived.store.get()._tag === 'Ready') MutableRef.set(latched, true)
+        })
+        yield* Effect.addFinalizer(() => Effect.sync(offSelf))
+      }
+      return derived.store
+    }),
+  )