@playfast/reform 1.0.1 → 1.2.0

package/src/boundary/boundary.ts

@@ -1,191 +1,222 @@
-import { Context, Data, Effect, Layer, MutableRef, Predicate } from 'effect'
+import { Context, Data, Effect, Equal, Layer, MutableRef, Option, Predicate } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
-import { type InputStores, sameKey, wireSources } from '../internal/sources'
+import { type InputStores, 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. */
+import { type AnySource, type SourceCapture, type SourceValue } from '../state/token'
+
 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.
+export const BoundaryStoreTypeId: unique symbol = Symbol.for('reform/BoundaryStore')
+export type BoundaryStoreTypeId = typeof BoundaryStoreTypeId
+
+export interface BoundaryStore<N extends string> {
+  readonly [BoundaryStoreTypeId]: N
+}
+
 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 type AnyLifecycleSource = AnySource
+
+declare const BoundaryLifecycleMismatchTypeId: unique symbol
+
+interface BoundaryLifecycleMismatch<Value> {
+  readonly [BoundaryLifecycleMismatchTypeId]: Value
+}
+
+type CheckedLifecycleValue<Value> = Value extends { readonly _tag: 'Idle' | 'Loading' }
+  ? Value
+  : Value extends {
+        readonly _tag: 'Success'
+        readonly value: infer _Success
+        readonly refetching: boolean
+      }
+    ? Value
+    : Value extends {
+          readonly _tag: 'Error'
+          readonly error: infer _Failure
+          readonly refetching: boolean
+        }
+      ? Value
+      : BoundaryLifecycleMismatch<Value>
+
+type CheckedLifecycleSource<Source extends AnySource> = [SourceValue<Source>] extends [never]
+  ? BoundaryLifecycleMismatch<Source>
+  : SourceValue<Source> extends CheckedLifecycleValue<SourceValue<Source>>
+    ? Source
+    : BoundaryLifecycleMismatch<SourceValue<Source>>
+
+type CheckedLifecycleSources<Over extends ReadonlyArray<AnyLifecycleSource>> = {
+  readonly [Index in keyof Over]: Over[Index] extends AnySource
+    ? CheckedLifecycleSource<Over[Index]>
+    : BoundaryLifecycleMismatch<Over[Index]>
+}
 
 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>> {
+export interface BoundaryClass<
+  N extends string,
+  out Over extends ReadonlyArray<AnyLifecycleSource>,
+> extends EffectType<BoundaryState, never, BoundaryStore<N>> {
   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 store: Context.Tag<BoundaryStore<N>, Store<BoundaryState>>
   readonly name: N
-  /** The covered lifecycle sources — read by `live` and the editor's graph. */
   readonly over: Over
+  readonly capture: <Result>(visit: SourceCapture<Result>) => Result
 }
 
 export interface BoundaryConfig<Over extends ReadonlyArray<AnyLifecycleSource>> {
-  readonly over: Over
+  readonly over: Over & CheckedLifecycleSources<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.
-   */
   // oxlint-disable-next-line reform-rules/no-optional-fields -- public options-bag input; omission is the documented default (no latch) and external callers pass a plain `{ once: true }` literal
   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>>(
+  const store = Context.GenericTag<BoundaryStore<N>, 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 })
+  const boundary: BoundaryClass<N, Over> = yieldableClass(read, {
+    manifest,
+    store,
+    name,
+    over: config.over,
+    capture: <Result>(visit: SourceCapture<Result>): Result => visit(boundary),
+  })
+  return boundary
 }
 
-// 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.
- */
+const errorOf = (arm: unknown): Option.Option<unknown> =>
+  Predicate.hasProperty(arm, 'error') && tagOf(arm) === 'Error'
+    ? Option.some(arm.error)
+    : Option.none()
+
+interface SlotUpdate {
+  readonly slot: number
+  readonly arm: unknown
+}
+
 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.Layer<BoundaryStore<N>, never, InputStores<Over>> =>
   Layer.scoped(
     boundary.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
-      const sources = yield* wireSources(boundary.over)
+      const sourceWires = yield* Effect.forEach(boundary.over, (source) => wireSources([source]))
+      const readSource = (source: (typeof sourceWires)[number]): unknown =>
+        source.keyOf(source.snapshot())[0]
+      const arms = sourceWires.map((source) => MutableRef.make(readSource(source)))
+      const loadingCount = MutableRef.make(
+        arms.reduce((count, arm) => count + (tagOf(MutableRef.get(arm)) === 'Loading' ? 1 : 0), 0),
+      )
+      const errorCount = MutableRef.make(
+        arms.reduce(
+          (count, arm) => count + (Option.isSome(errorOf(MutableRef.get(arm))) ? 1 : 0),
+          0,
+        ),
+      )
+      const collectErrors = (): ReadonlyArray<unknown> =>
+        arms.flatMap((arm) => Option.toArray(errorOf(MutableRef.get(arm))))
+      const errorArm = MutableRef.make(erroredArm(collectErrors()))
+      const updateSlot = (update: SlotUpdate): void => {
+        const armRef = arms[update.slot]
+        if (armRef === undefined) {
+          return
+        }
+        const previous = MutableRef.get(armRef)
+        if (Equal.equals(previous, update.arm)) {
+          return
+        }
+        MutableRef.set(armRef, update.arm)
+        MutableRef.update(
+          loadingCount,
+          (count) =>
+            count +
+            (tagOf(update.arm) === 'Loading' ? 1 : 0) -
+            (tagOf(previous) === 'Loading' ? 1 : 0),
+        )
+        const previousError = errorOf(previous)
+        const nextError = errorOf(update.arm)
+        if (!Equal.equals(previousError, nextError)) {
+          MutableRef.update(
+            errorCount,
+            (count) =>
+              count + (Option.isSome(nextError) ? 1 : 0) - (Option.isSome(previousError) ? 1 : 0),
+          )
+          MutableRef.set(errorArm, erroredArm(collectErrors()))
+        }
+      }
+      const synchronize = (): void =>
+        sourceWires.forEach((source, slot) => updateSlot({ slot, arm: readSource(source) }))
 
       const latched = MutableRef.make(false)
-      const memo = MutableRef.make<
-        { readonly key: ReadonlyArray<unknown>; readonly value: BoundaryState } | undefined
-      >(undefined)
+      const incremental = MutableRef.make(false)
       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
+        if (!MutableRef.get(incremental)) {
+          synchronize()
         }
-        const errors = arms.flatMap(errorOf)
-        const mergedArm =
-          errors.length > 0
-            ? erroredArm(errors)
-            : arms.some((arm) => tagOf(arm) === 'Loading')
-              ? pendingArm
-              : readyArm
-        MutableRef.set(memo, { key: arms, value: mergedArm })
-        return mergedArm
+        return MutableRef.get(errorCount) > 0
+          ? MutableRef.get(errorArm)
+          : MutableRef.get(loadingCount) > 0
+            ? pendingArm
+            : readyArm
       }
 
-      const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
+      const subscribe = (onChange: () => void): (() => void) => {
+        const publish = (): void => {
+          MutableRef.set(incremental, true)
+          onChange()
+          MutableRef.set(incremental, false)
+        }
+        const settle = (): void => scheduler.schedule([publish])
+        const unsubscribes = sourceWires.map((source, sourceIndex) =>
+          source.subscribe(() => {
+            updateSlot({ slot: sourceIndex, arm: readSource(source) })
+            scheduler.schedule([settle])
+          }),
+        )
+        return () => unsubscribes.forEach((unsubscribe) => unsubscribe())
+      }
+      const derived = makeDerivedStore(recompute, 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)
         }