@playfast/reform 1.0.1 → 1.2.0

package/src/calc/calc.test.ts

@@ -2,15 +2,11 @@ import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, Schema as S } from 'effect'
 import { Calc, State, StateGroup } from '../index'
 
-// The calc store memoizes on input identity and — the behaviour under test —
-// only wakes its subscribers when a source change actually moves the output.
-
 const tick = Effect.sleep(Duration.millis(1))
 
 it.live('a source change that does not move the output notifies no subscriber', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  // `isPositive` is stable across 1 -> 2 (still true) but flips on 2 -> -1.
   class IsPositive extends Calc.make('IsPositive', {
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Boolean,
@@ -33,13 +29,11 @@ it.live('a source change that does not move the output notifies no subscriber',
 
     expect(derived.get()).toBe(true)
 
-    // 1 -> 2: inputs changed, recompute runs, but the output (true) is unchanged.
     source.set(2)
     yield* tick
     expect(notifications.n).toBe(0)
     expect(derived.get()).toBe(true)
 
-    // 2 -> -1: output flips to false — exactly one notification.
     source.set(-1)
     yield* tick
     expect(notifications.n).toBe(1)
@@ -65,7 +59,6 @@ it.live('reading does not recompute while inputs are unchanged (memoized)', () =
   return Effect.gen(function* () {
     const derived = yield* Doubled.store
     const before = runs.n
-    // Repeated reads with no input change hit the memo — no extra compute.
     expect(derived.get()).toBe(10)
     expect(derived.get()).toBe(10)
     expect(runs.n).toBe(before)
@@ -80,7 +73,6 @@ it.live('a calc can depend on another calc as an input source', () => {
     output: S.Number,
   }) {}
   const DoubledLive = Calc.live(Doubled, ({ count }) => count * 2)
-  // `Doubled` (a Calc) is used directly as an input source; its name is the key.
   class PlusDoubled extends Calc.make('PlusDoubled', {
     inputs: [StateGroup.select(Inputs, 'count'), Doubled],
     output: S.Number,
@@ -95,17 +87,14 @@ it.live('a calc can depend on another calc as an input source', () => {
   return Effect.gen(function* () {
     const source = yield* StateGroup.select(Inputs, 'count').store
     const derived = yield* PlusDoubled.store
-    expect(derived.get()).toBe(15) // 5 + (5*2)
+    expect(derived.get()).toBe(15)
     source.set(3)
     yield* tick
-    expect(derived.get()).toBe(9) // 3 + (3*2)
+    expect(derived.get()).toBe(9)
   }).pipe(Effect.provide(TestLayer))
 })
 
 it.live('a diamond dependency resolves in one flush with a single leaf notification', () => {
-  // count ─┬─► A (count+1) ─┐
-  //        └─► B (count+10)─┴─► C (A+B).  A change to `count` moves both A and B;
-  // C must converge to the new value and wake its subscriber exactly once.
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
   class A extends Calc.make('A', {
@@ -133,11 +122,11 @@ it.live('a diamond dependency resolves in one flush with a single leaf notificat
     c.subscribe(() => {
       wakes.n += 1
     })
-    expect(c.get()).toBe(11) // (0+1) + (0+10)
+    expect(c.get()).toBe(11)
 
     source.set(5)
     yield* tick
-    expect(c.get()).toBe(21) // (5+1) + (5+10)
+    expect(c.get()).toBe(21)
     expect(wakes.n).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -168,13 +157,11 @@ it.live('invalidateBy: a calc recomputes only when the projected key moves', ()
     const base = runs.n
     expect(sum.get()).toBe(2)
 
-    // `b` moves but the key (just `a`) is unchanged — no recompute, value retained.
     sb.set(100)
     yield* tick
     expect(runs.n).toBe(base)
     expect(sum.get()).toBe(2)
 
-    // `a` moves — recompute, now seeing the current `b`.
     sa.set(5)
     yield* tick
     expect(sum.get()).toBe(105)
@@ -184,11 +171,6 @@ it.live('invalidateBy: a calc recomputes only when the projected key moves', ()
 it.live('inputs are keyed by the make() name even when the subclass binding differs', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
-  // The binding name ('Renamed…') deliberately differs from the make() name
-  // ('feed') — a class declaration defines its OWN static `name` from the
-  // binding, shadowing the explicit one. Minifiers rename bindings, so keying
-  // the snapshot off the static would make this input undefined in production
-  // builds; the inputs object must key by the manifest's make() name.
   class RenamedByTheMinifier extends Calc.make('feed', {
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Number,
@@ -210,9 +192,7 @@ it.live('inputs are keyed by the make() name even when the subclass binding diff
   )
 
   return Effect.gen(function* () {
-    // The subclass's own static name is the (would-be-minified) binding name…
     expect(RenamedByTheMinifier.name).toBe('RenamedByTheMinifier')
-    // …but the snapshot keys by the make() name, so `feed` is defined.
     const downstream = yield* Downstream.store
     expect(downstream.get()).toBe(7)
     expect(seen.every((v) => v !== undefined)).toBe(true)
@@ -231,11 +211,9 @@ it.live('reuse: an unchanged subtree keeps its identity across recompute', () =>
     inputs: [StateGroup.select(Inputs, 'a'), StateGroup.select(Inputs, 'b')],
     output: Pair,
   }) {}
-  const SplitLive = Calc.live(
-    Split,
-    ({ a, b }) => ({ left: { value: a }, right: { value: b } }),
-    { reuse: true },
-  )
+  const SplitLive = Calc.live(Split, ({ a, b }) => ({ left: { value: a }, right: { value: b } }), {
+    reuse: true,
+  })
   const TestLayer = SplitLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { a: 1, b: 1 })))
 
   return Effect.gen(function* () {
@@ -243,7 +221,6 @@ it.live('reuse: an unchanged subtree keeps its identity across recompute', () =>
     const derived = yield* Split.store
     const before = derived.get()
 
-    // Only `b` moves: the root and `right` are fresh, `left` keeps its identity.
     b.set(2)
     yield* tick
     const after = derived.get()
@@ -262,9 +239,6 @@ it.live('reuse: a value-equal recompute keeps the previous reference and wakes n
     inputs: [StateGroup.select(Inputs, 'count')],
     output: Box,
   }) {}
-  // A plain-object output: WITHOUT reuse every recompute is a fresh identity
-  // (and would notify); with it, a value-equal recompute returns the previous
-  // reference and the Equal gate stays silent.
   const IsPositiveLive = Calc.live(IsPositive, ({ count }) => ({ positive: count > 0 }), {
     reuse: true,
   })

package/src/calc/calc.ts

@@ -1,4 +1,5 @@
 import { Context, Effect, Layer, MutableRef, type Schema } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import {
   type InputsObject,
@@ -12,84 +13,77 @@ import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentat
 import { reuse } from '../internal/reuse'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
-import { type AnySource } from '../state/token'
+import { type AnySource, type Source, type SourceCapture } from '../state/token'
 
-// Re-exported so `Calc.InputsObject` / `Calc.InvalidateBy` keep their home here
-// even though the reactive plumbing now lives in `internal/sources`.
 export { type InputsObject, type InputStores, type InvalidateBy } from '../internal/sources'
 
-// Boundary config object: optional fields are the framework's public, JSON-like
-// definition surface (`ExternalApi` postfix exempts them from `no-optional-fields`).
 export interface CalcOptionsExternalApi<Inputs extends ReadonlyArray<AnySource>> {
-  /**
-   * Custom invalidation: recompute only when the projected key changes by value
-   * equality (React-Query's `queryKey`). Omitted ⇒ recompute when any input
-   * value changes. Shared with `AsyncCalc`.
-   */
   readonly invalidateBy?: InvalidateBy<Inputs>
-  /**
-   * Structural sharing: reconcile each recomputed output against the previous
-   * one, substituting previous nodes wherever value equality holds — so
-   * identities only move where values moved and downstream memo boundaries
-   * (React subtrees) skip unchanged regions. Referentially transparent (the
-   * result is value-equal to the fresh output); costs one O(output) walk per
-   * recompute, so opt in for large projections.
-   */
   readonly reuse?: boolean
 }
 
-export interface CalcManifest<N extends string, Out> extends Manifest {
+export interface CalcSchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
+
+export interface CalcManifest<N extends string> extends Manifest {
   readonly kind: 'Calc'
   readonly name: N
-  readonly output: Schema.Schema<Out, any>
+  readonly output: CalcSchemaReflection
+}
+
+export const CalcStoreTypeId: unique symbol = Symbol.for('reform/CalcStore')
+export type CalcStoreTypeId = typeof CalcStoreTypeId
+
+export interface CalcStore<N extends string, in out Out> extends Store<Out> {
+  readonly [CalcStoreTypeId]: N
 }
 
-export interface CalcClass<out N extends string, out Inputs extends ReadonlyArray<AnySource>, in out Out>
-  extends Effect.Effect<Out, never, Store<Out>> {
+export interface CalcClass<N extends string, Inputs extends ReadonlyArray<AnySource>, Out>
+  extends EffectType<Out, never, CalcStore<N, Out>>, Source<N, Out, CalcStore<N, Out>> {
   new (): {}
-  readonly manifest: CalcManifest<N, Out>
-  readonly store: Context.Tag<Store<Out>, Store<Out>>
-  /** The calc's name, so it doubles as a `Source` input to another calc. */
+  readonly manifest: CalcManifest<N>
+  readonly store: Context.Tag<CalcStore<N, Out>, Store<Out>>
   readonly name: N
-  /** Marker data read by `Calc.live`. */
   readonly inputs: Inputs
+  readonly capture: <Result>(visit: SourceCapture<Result>) => Result
 }
 
-export interface CalcConfig<Inputs extends ReadonlyArray<AnySource>, Out> {
+export interface CalcConfig<
+  Inputs extends ReadonlyArray<AnySource>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+> {
   readonly inputs: Inputs
-  readonly output: Schema.Schema<Out, any>
+  readonly output: OutputSchema
 }
 
-/**
- * A derived, memoized value over explicit inputs (state members, other calcs, or
- * async calcs). The *definition* fixes the inputs and the output schema; the
- * *implementation* is the pure projection. Recomputes only when an input changes;
- * `yield* Calc` reads the memoized value.
- */
-export const make = <const N extends string, const Inputs extends ReadonlyArray<AnySource>, Out>(
+export const make = <
+  const N extends string,
+  const Inputs extends ReadonlyArray<AnySource>,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+>(
   name: N,
-  config: CalcConfig<Inputs, Out>,
-): CalcClass<N, Inputs, Out> => {
-  const store = Context.GenericTag<Store<Out>, Store<Out>>(`reform/calc/${name}`)
-  const manifest: CalcManifest<N, Out> = { kind: 'Calc', name, output: config.output }
+  config: CalcConfig<Inputs, OutputSchema>,
+): CalcClass<N, Inputs, Schema.Schema.Type<OutputSchema>> => {
+  type Out = Schema.Schema.Type<OutputSchema>
+  const store = Context.GenericTag<CalcStore<N, Out>, Store<Out>>(`reform/calc/${name}`)
+  const manifest: CalcManifest<N> = { kind: 'Calc', name, output: config.output }
   const read = Effect.flatMap(store, readTracked)
-  return yieldableClass(read, { manifest, store, name, inputs: config.inputs })
+  const calc: CalcClass<N, Inputs, Out> = yieldableClass(read, {
+    manifest,
+    store,
+    name,
+    inputs: config.inputs,
+    capture: <Result>(visit: SourceCapture<Result>): Result => visit(calc),
+  })
+  return calc
 }
 
-/**
- * Wire the pure projection for a calc. Recomputes only when its invalidation key
- * changes (by default every input value; override with `invalidateBy`), memoized
- * on that key; `yield* Calc` reads the memoized value. The derived store reuses
- * the shared coalescing scheduler, so a recompute that yields an equal value
- * wakes no subscriber.
- */
 export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, Out>(
   calc: CalcClass<N, Inputs, Out>,
   compute: (inputs: InputsObject<Inputs>) => Out,
   options: CalcOptionsExternalApi<Inputs> = {},
-): Layer.Layer<Store<Out>, never, InputStores<Inputs>> =>
-  // Scoped so the source subscriptions are released when the layer's scope
-  // closes (each proof/test builds and disposes its own runtime).
+): Layer.Layer<CalcStore<N, Out>, never, InputStores<Inputs>> =>
   Layer.scoped(
     calc.store,
     Effect.gen(function* () {
@@ -97,8 +91,6 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
       const instrumentation = yield* resolveInstrumentation
       const sources = yield* wireSources(calc.inputs, options.invalidateBy)
 
-      // Memo cell: key and output captured together so reads are always
-      // consistent (no separate output that could lag the key it was computed for).
       const memo = MutableRef.make<
         { readonly key: ReadonlyArray<unknown>; readonly output: Out } | undefined
       >(undefined)
@@ -109,14 +101,8 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         if (prev !== undefined && sameKey(key, prev.key)) {
           return prev.output
         }
-        // Span covers the projection AND the optional reuse walk — both are the
-        // calc's real per-recompute cost. Memo hits return above, uncounted.
-        // (`manifest.name`, not `.name` — a user subclass shadows the static.)
         const end = instrumentation.calcRecomputed(calc.manifest.name)
         const fresh = compute(args)
-        // With `reuse`, a recompute that lands value-equal to the previous
-        // output returns the previous reference — the derived store's Equal
-        // gate then wakes no subscriber at all.
         const output =
           options.reuse === true && prev !== undefined ? reuse(prev.output, fresh) : fresh
         end()

package/src/calc/calcFamily.test.ts

@@ -2,14 +2,8 @@ import { expect, it } from '@effect/vitest'
 import { Context, Duration, Effect, Exit, Layer, Schema as S, Scope } from 'effect'
 import { CalcFamily, State, StateGroup } from '../index'
 
-// CalcFamily: per-key derived stores over shared inputs. The behaviours under
-// test: members derive + memoize independently, a member only notifies when ITS
-// output moves, and every removal path releases the member's upstream
-// subscription (a derived member holds one; a StateFamily entry doesn't).
-
 const tick = Effect.sleep(Duration.millis(1))
 
-// Shared fixture shape: a record of named counters; each member projects one.
 const Board = S.Record({ key: S.String, value: S.Number })
 
 const fixture = () => {
@@ -60,7 +54,6 @@ it.live('a member only notifies when its own slice of the projection moves', ()
       wakes.b += 1
     })
 
-    // Only `a` moves: b's member recomputes but its output is Equal — silent.
     feed.set({ a: 2, b: 10 })
     yield* tick
     expect(wakes).toEqual({ a: 1, b: 0 })
@@ -71,19 +64,79 @@ it.live('a member only notifies when its own slice of the projection moves', ()
   }).pipe(Effect.provide(TestLayer))
 })
 
-it.live('reading does not recompute while the shared inputs are unchanged (memoized per member)', () => {
-  const { Inputs, Slice, SliceLive, runs } = fixture()
-  const TestLayer = SliceLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
+const reuseFixture = () => {
+  class Feed extends State.make('reuse-feed', Board) {}
+  class Revision extends State.make('reuse-revision', S.Number) {}
+  class Inputs extends StateGroup.make(Feed, Revision) {}
+  class Presentation extends CalcFamily.make('ReusePresentation', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'reuse-feed'), StateGroup.select(Inputs, 'reuse-revision')],
+    output: S.Struct({ nested: S.Array(S.Struct({ value: S.Number })) }),
+  }) {}
+  const PresentationLive = CalcFamily.live(
+    Presentation,
+    (key) =>
+      ({ 'reuse-feed': feed }) => ({
+        nested: [{ value: feed[key] ?? 0 }],
+      }),
+    { reuse: true },
+  )
+  return { Inputs, Presentation, PresentationLive }
+}
+
+it.live('reuse preserves each member output when equal and replaces it when changed', () => {
+  const { Inputs, Presentation, PresentationLive } = reuseFixture()
+  const TestLayer = PresentationLive.pipe(
+    Layer.provideMerge(
+      StateGroup.live(Inputs, { 'reuse-feed': { a: 1, b: 1 }, 'reuse-revision': 0 }),
+    ),
   )
   return Effect.gen(function* () {
-    yield* CalcFamily.read(Slice, 'a')
-    yield* CalcFamily.read(Slice, 'a')
-    yield* CalcFamily.read(Slice, 'a')
-    expect(runs.get('a')).toBe(1)
+    const feed = yield* StateGroup.select(Inputs, 'reuse-feed').store
+    const revision = yield* StateGroup.select(Inputs, 'reuse-revision').store
+    const family = yield* Presentation.store
+    const initialA = family.at('a').get()
+    const initialB = family.at('b').get()
+    const wakes = { a: 0, b: 0 }
+    family.at('a').subscribe(() => {
+      wakes.a += 1
+    })
+    family.at('b').subscribe(() => {
+      wakes.b += 1
+    })
+
+    expect(Object.is(initialA.nested, initialB.nested)).toBe(false)
+    revision.set(1)
+    yield* tick
+    expect(Object.is(family.at('a').get().nested, initialA.nested)).toBe(true)
+    expect(Object.is(family.at('b').get().nested, initialB.nested)).toBe(true)
+    expect(wakes).toEqual({ a: 0, b: 0 })
+
+    feed.set({ a: 2, b: 1 })
+    yield* tick
+    expect(family.at('a').get().nested).toEqual([{ value: 2 }])
+    expect(Object.is(family.at('a').get().nested, initialA.nested)).toBe(false)
+    expect(Object.is(family.at('b').get().nested, initialB.nested)).toBe(true)
+    expect(wakes).toEqual({ a: 1, b: 0 })
   }).pipe(Effect.provide(TestLayer))
 })
 
+it.live(
+  'reading does not recompute while the shared inputs are unchanged (memoized per member)',
+  () => {
+    const { Inputs, Slice, SliceLive, runs } = fixture()
+    const TestLayer = SliceLive.pipe(
+      Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
+    )
+    return Effect.gen(function* () {
+      yield* CalcFamily.read(Slice, 'a')
+      yield* CalcFamily.read(Slice, 'a')
+      yield* CalcFamily.read(Slice, 'a')
+      expect(runs.get('a')).toBe(1)
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
+
 it.live('invalidateBy: shared-input churn outside the key recomputes no member', () => {
   class Feed extends State.make('feed', Board) {}
   class Noise extends State.make('noise', S.Number) {}
@@ -96,10 +149,11 @@ it.live('invalidateBy: shared-input churn outside the key recomputes no member',
   }) {}
   const SliceLive = CalcFamily.live(
     Slice,
-    (key) => ({ feed }) => {
-      runs.set(key, (runs.get(key) ?? 0) + 1)
-      return feed[key] ?? 0
-    },
+    (key) =>
+      ({ feed }) => {
+        runs.set(key, (runs.get(key) ?? 0) + 1)
+        return feed[key] ?? 0
+      },
     { invalidateBy: ({ feed }) => [feed] },
   )
   const TestLayer = SliceLive.pipe(
@@ -119,9 +173,7 @@ it.live('invalidateBy: shared-input churn outside the key recomputes no member',
 
 it.live('forget releases the member and its upstream subscription', () => {
   const { Inputs, Slice, SliceLive, runs } = fixture()
-  const TestLayer = SliceLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
-  )
+  const TestLayer = SliceLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })))
   return Effect.gen(function* () {
     const feed = yield* StateGroup.select(Inputs, 'feed').store
     const family = yield* Slice.store
@@ -130,13 +182,11 @@ it.live('forget releases the member and its upstream subscription', () => {
 
     family.forget('a')
     expect(family.size()).toBe(0)
-    // The dropped member no longer recomputes on upstream churn.
     const before = runs.get('a') ?? 0
     feed.set({ a: 2 })
     yield* tick
     expect(runs.get('a') ?? 0).toBe(before)
 
-    // Re-`at`-ing allocates a fresh member over the current snapshot.
     expect(family.at('a').get()).toBe(2)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -152,15 +202,14 @@ it.live('evictWhenUnused: an idle member is dropped on the next microtask and un
   }) {}
   const SliceLive = CalcFamily.live(
     Slice,
-    (key) => ({ feed }) => {
-      runs.set(key, (runs.get(key) ?? 0) + 1)
-      return feed[key] ?? 0
-    },
+    (key) =>
+      ({ feed }) => {
+        runs.set(key, (runs.get(key) ?? 0) + 1)
+        return feed[key] ?? 0
+      },
     { evictWhenUnused: true },
   )
-  const TestLayer = SliceLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })),
-  )
+  const TestLayer = SliceLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { feed: { a: 1 } })))
   return Effect.gen(function* () {
     const feed = yield* StateGroup.select(Inputs, 'feed').store
     const family = yield* Slice.store
@@ -181,9 +230,6 @@ it.live('the layer finalizer clears every member (no live subscriptions leak)',
   const { Inputs, Slice, SliceLive, runs } = fixture()
   return Effect.scoped(
     Effect.gen(function* () {
-      // Build the input stores once, then the family in its OWN scope over that
-      // exact context — so the stores outlive the family and we can prove the
-      // members' upstream subscriptions died with it.
       const storesCtx = yield* Layer.build(StateGroup.live(Inputs, { feed: { a: 1, b: 2 } }))
       const feed = Context.get(storesCtx, StateGroup.select(Inputs, 'feed').store)
       const scope = yield* Scope.make()