@playfast/reform 0.1.0 → 1.1.1

package/src/calc/calc.ts

@@ -1,4 +1,5 @@
-import { Context, Effect, Layer, MutableRef, type Schema } from 'effect'
+import { Context, Effect, Layer, MutableRef } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import {
   type InputsObject,
@@ -8,63 +9,40 @@ import {
   wireSources,
 } from '../internal/sources'
 import { resolveScheduler } from '../internal/scheduler'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 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 { AnySchema } from '../internal/variance'
 
-// 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 {
   readonly kind: 'Calc'
   readonly name: N
-  readonly output: Schema.Schema<Out, any>
+  readonly output: AnySchema<Out>
 }
 
 export interface CalcClass<out N extends string, out Inputs extends ReadonlyArray<AnySource>, in out Out>
-  extends Effect.Effect<Out, never, Store<Out>> {
+  extends EffectType<Out, never, Store<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 name: N
-  /** Marker data read by `Calc.live`. */
   readonly inputs: Inputs
 }
 
 export interface CalcConfig<Inputs extends ReadonlyArray<AnySource>, Out> {
   readonly inputs: Inputs
-  readonly output: Schema.Schema<Out, any>
+  readonly output: AnySchema<Out>
 }
 
-/**
- * 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>(
   name: N,
   config: CalcConfig<Inputs, Out>,
@@ -75,28 +53,18 @@ export const make = <const N extends string, const Inputs extends ReadonlyArray<
   return yieldableClass(read, { manifest, store, name, inputs: config.inputs })
 }
 
-/**
- * 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.scoped(
     calc.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
+      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)
@@ -107,17 +75,21 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         if (prev !== undefined && sameKey(key, prev.key)) {
           return prev.output
         }
+        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()
         MutableRef.set(memo, { key, output })
         return output
       }
 
-      const derived = makeDerivedStore(recompute, sources.subscribe, scheduler)
+      const derived = makeDerivedStore(
+        recompute,
+        sources.subscribe,
+        scheduler,
+        stateUpdateHook(instrumentation, calc.manifest.name),
+      )
       yield* Effect.addFinalizer(() => Effect.sync(derived.unsubscribe))
       return derived.store
     }),

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 })
@@ -130,13 +123,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))
 })
@@ -181,9 +172,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()

package/src/calc/calcFamily.ts

@@ -1,4 +1,4 @@
-import { Context, Effect, Layer, MutableRef, type Schema } from 'effect'
+import { Context, Effect, Layer, MutableRef } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import {
   type InputsObject,
@@ -8,25 +8,18 @@ import {
   wireSources,
 } from '../internal/sources'
 import { resolveScheduler } from '../internal/scheduler'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import { type FamilyOptions, type FamilyStore } from '../state/stateFamily'
 import { type AnySource } from '../state/token'
-
-// `CalcFamily` is `Calc`'s keyed sibling, modeled on `StateFamily`: one derived,
-// memoized store per key over a SHARED set of inputs. Where a monolithic calc
-// rebuilds its whole output on any change (waking every consumer), a family
-// member recomputes lazily and notifies only when ITS slice of the projection
-// moves (the derived store's Equal gate) — per-row/per-group UI subscribes per
-// key and unrelated changes never wake it. Members are pure projections; a
-// Reducer cannot target a CalcFamily (its config requires a `StateFamily`
-// manifest), so calc purity holds structurally.
+import type { AnySchema } from '../internal/variance'
 
 export interface CalcFamilyManifest<N extends string, K, Out> extends Manifest {
   readonly kind: 'CalcFamily'
   readonly name: N
-  readonly key: Schema.Schema<K, any>
-  readonly output: Schema.Schema<Out, any>
+  readonly key: AnySchema<K>
+  readonly output: AnySchema<Out>
 }
 
 export interface CalcFamilyClass<
@@ -35,25 +28,18 @@ export interface CalcFamilyClass<
   in out K,
   in out Out,
 > {
-  /** Instance carries the key phantom so `Family['Key']` resolves in key types. */
   new (): { readonly Key: K }
   readonly manifest: CalcFamilyManifest<N, K, Out>
   readonly store: Context.Tag<FamilyStore<K, Out>, FamilyStore<K, Out>>
-  /** Marker data read by `CalcFamily.live` and the editor's graph builder. */
   readonly inputs: Inputs
 }
 
 export interface CalcFamilyConfig<Inputs extends ReadonlyArray<AnySource>, K, Out> {
-  readonly key: Schema.Schema<K, any>
+  readonly key: AnySchema<K>
   readonly inputs: Inputs
-  readonly output: Schema.Schema<Out, any>
+  readonly output: AnySchema<Out>
 }
 
-/**
- * Define a keyed derived value: per-key memoized projections over shared
- * inputs. The *definition* fixes the key/output schemas and the inputs; the
- * *implementation* (the per-key projection) is supplied by `CalcFamily.live`.
- */
 export const make = <const N extends string, const Inputs extends ReadonlyArray<AnySource>, K, Out>(
   name: N,
   config: CalcFamilyConfig<Inputs, K, Out>,
@@ -74,38 +60,17 @@ export const make = <const N extends string, const Inputs extends ReadonlyArray<
   })
 }
 
-/**
- * Read one member by key — `CalcFamily.read(GroupProjection, id)`. Inside a
- * render it subscribes exactly that member's store (unrelated members never
- * wake the subtree); elsewhere it just snapshots — the same one-read-API
- * contract as `StateFamily.read`.
- */
 export const read = <N extends string, Inputs extends ReadonlyArray<AnySource>, K, Out>(
   family: CalcFamilyClass<N, Inputs, K, Out>,
   key: K,
 ): Effect.Effect<Out, never, FamilyStore<K, Out>> =>
   Effect.flatMap(family.store, (familyStore) => readTracked(familyStore.at(key)))
 
-// Boundary config object: optional fields are the framework's public, JSON-like
-// definition surface (`ExternalApi` postfix exempts them from `no-optional-fields`).
 export interface CalcFamilyLiveOptionsExternalApi<Inputs extends ReadonlyArray<AnySource>>
   extends FamilyOptions {
-  /**
-   * Family-wide invalidation key over the SHARED inputs (the member key plays
-   * no part — it is fixed per member). Same contract as `Calc`'s.
-   */
   readonly invalidateBy?: InvalidateBy<Inputs>
 }
 
-/**
- * Wire the per-key projection. `compute` is curried — `(key) => (inputs) =>
- * Out` — so per-key construction (closing over key-derived constants) runs once
- * per member while the inner projection runs per recompute. Each member is a
- * lazy derived store over the shared wired sources: memoized on the family's
- * invalidation key, notifying only when its own output moves. Unlike a
- * `StateFamily` entry, a member holds an upstream subscription, so every
- * removal path (forget / clear / eviction / the layer finalizer) releases it.
- */
 export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>, K, Out>(
   family: CalcFamilyClass<N, Inputs, K, Out>,
   compute: (key: K) => (inputs: InputsObject<Inputs>) => Out,
@@ -115,11 +80,11 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
     family.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
-      // Wired ONCE for the whole family — members share the sensing surface.
+      const instrumentation = yield* resolveInstrumentation
+      const onOutputChange = stateUpdateHook(instrumentation, family.manifest.name)
       const sources = yield* wireSources(family.inputs, options.invalidateBy)
       const entries = new Map<K, { readonly store: Store<Out>; readonly unsubscribe: () => void }>()
       const evictWhenUnused = options.evictWhenUnused === true
-      // Live subscriber count per key — maintained only when eviction is on.
       const subscribers = new Map<K, number>()
 
       const dropEntry = (key: K): void => {
@@ -131,7 +96,6 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         subscribers.delete(key)
       }
 
-      // One member: the same memo block as `Calc.live`, with the key closed over.
       const createMember = (key: K): { readonly store: Store<Out>; readonly unsubscribe: () => void } => {
         const body = compute(key)
         const memo = MutableRef.make<
@@ -144,16 +108,15 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
           if (prev !== undefined && sameKey(memoKey, prev.key)) {
             return prev.output
           }
+          const end = instrumentation.calcRecomputed(family.manifest.name)
           const output = body(args)
+          end()
           MutableRef.set(memo, { key: memoKey, output })
           return output
         }
-        return makeDerivedStore(recompute, sources.subscribe, scheduler)
+        return makeDerivedStore(recompute, sources.subscribe, scheduler, onOutputChange)
       }
 
-      // The `StateFamily` ref-count idiom: evict on the next microtask once a
-      // key falls idle (a same-commit re-subscribe cancels it) — here eviction
-      // also releases the member's upstream subscription via `dropEntry`.
       const refCounted = (key: K, store: Store<Out>): Store<Out> => ({
         ...store,
         subscribe: (listener) => {

package/src/calc/compose.test.ts

@@ -2,10 +2,6 @@ import { expect, it } from '@effect/vitest'
 import { Effect, Layer, Schema as S } from 'effect'
 import { Calc, composeCalcs, State, StateGroup } from '../index'
 
-// `composeCalcs` wires a calc-on-calc chain in dependency order. The shape under
-// test is the one that defeats a flat `Layer.mergeAll`: a linear chain where each
-// calc's only input is the previous calc — count → Doubled → PlusOne → Tripled.
-
 it.live('composeCalcs wires a linear calc chain; the result needs only the base state', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
@@ -22,23 +18,16 @@ it.live('composeCalcs wires a linear calc chain; the result needs only the base
   class Tripled extends Calc.make('Tripled', { inputs: [PlusOne], output: S.Number }) {}
   const TripledLive = Calc.live(Tripled, ({ PlusOne }) => PlusOne * 3)
 
-  // Leaf-first, then upstreams in dependency order. The composed layer's only
-  // remaining requirement is the base `count` store — which the type system
-  // proves by letting us provide *only* the state group below.
-  // The chain's only remaining requirement is the base `count` store — provide
-  // (and expose, via provideMerge) just the state group and everything builds.
   const Chain = composeCalcs(TripledLive, PlusOneLive, DoubledLive)
   const TestLayer = Chain.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })))
 
   return Effect.gen(function* () {
     const source = yield* StateGroup.select(Inputs, 'count').store
     const tripled = yield* Tripled.store
-    // count 5 → Doubled 10 → PlusOne 11 → Tripled 33
     expect(tripled.get()).toBe(33)
 
     source.set(2)
     yield* Effect.yieldNow()
-    // count 2 → Doubled 4 → PlusOne 5 → Tripled 15
     expect(tripled.get()).toBe(15)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -63,6 +52,6 @@ it.live('composeCalcs(leaf, upstream) matches the hand-written provideMerge chai
 
   return Effect.gen(function* () {
     const derived = yield* PlusDoubled.store
-    expect(derived.get()).toBe(15) // 5 + (5*2), same as the manual-pipe test
+    expect(derived.get()).toBe(15)
   }).pipe(Effect.provide(TestLayer))
 })

package/src/calc/compose.ts

@@ -1,25 +1,5 @@
 import { Layer } from 'effect'
 
-// Wiring a calc-on-calc chain (`FilteredAgents` ← `AllAgents` ← `AgentsQuery`)
-// is the one calc-graph shape that trips people up: each upstream calc's store
-// must be *provided into* the downstream live, in dependency order. A flat
-// `Layer.mergeAll(FilteredLive, AllLive, QueryLive)` does NOT do this — `mergeAll`
-// merges outputs but never provides members to one another, so the upstream
-// calc stores stay as unmet `Store<…>` requirements (the TS2322 the migration
-// hit). The correct shape is `leaf.pipe(provideMerge(u1), provideMerge(u2), …)`;
-// `composeCalcs` is that fold under one name so the right thing is the easy thing.
-
-/**
- * Compose a calc-dependency chain: provide each upstream calc's `.live` layer
- * into the downstream one, nearest dependency first. The result exposes every
- * calc store in the chain and requires only the chain's *external* inputs (the
- * base state stores) — never the intermediate calc stores.
- *
- * Order is leaf-first, then its upstreams in dependency order:
- * `composeCalcs(FilteredLive, AllLive, QueryLive)` ≡
- * `FilteredLive.pipe(Layer.provideMerge(AllLive), Layer.provideMerge(QueryLive))`.
- * For chains deeper than three upstreams, nest `composeCalcs`.
- */
 export function composeCalcs<LOut, LErr, LIn, AOut, AErr, AIn>(
   leaf: Layer.Layer<LOut, LErr, LIn>,
   upstream: Layer.Layer<AOut, AErr, AIn>,
@@ -60,8 +40,6 @@ export function composeCalcs(
   leaf: Layer.Layer<unknown, unknown, unknown>,
   ...upstream: ReadonlyArray<Layer.Layer<unknown, unknown, unknown>>
 ): Layer.Layer<unknown, unknown, unknown> {
-  // Fold leaf-first: each upstream is provided into the accumulated downstream,
-  // so dependency order is exactly the argument order.
   return upstream.reduce<Layer.Layer<unknown, unknown, unknown>>(
     (downstream, upstreamLayer) => Layer.provideMerge(downstream, upstreamLayer),
     leaf,

package/src/calc/queryState.ts

@@ -1,26 +1,13 @@
 import { Option } from 'effect'
 import { type AnyAsyncData, AsyncData } from './asyncData'
 
-// `QueryState` is the data-oriented value an `AsyncCalc` is driven by: the four
-// axes of a query, stored *flat and independent* so each can move on its own.
-// `data`/`error` survive a refetch (stale-while-revalidate for free); `isFetching`
-// (activity) and `isStale` (freshness) are orthogonal to both — which is exactly
-// what lets `invalidate` (flip `isStale`) and `refetch` (drive `isFetching`) be
-// separate operations. The matchable `AsyncData` union is *derived* from this
-// (`toAsyncData`), so view code and `RemoteState` keep their arm dispatch.
-
 export interface QueryState<A, E> {
-  /** Last resolved value — kept across a refetch. */
   readonly data: Option.Option<A>
-  /** Last failure — kept across a refetch. */
   readonly error: Option.Option<E>
-  /** Activity axis: a run is in flight. */
   readonly isFetching: boolean
-  /** Freshness axis: the value has been marked invalid (drives auto-refetch). */
   readonly isStale: boolean
 }
 
-/** The empty cell. `fetching` seeds the first-kick `Loading` for an enabled query. */
 export const empty = (fetching: boolean): QueryState<never, never> => ({
   data: Option.none(),
   error: Option.none(),
@@ -28,15 +15,6 @@ export const empty = (fetching: boolean): QueryState<never, never> => ({
   isStale: false,
 })
 
-/**
- * Project the flat state onto the public `AsyncData` union (the view contract) —
- * the single `Match`-able view of a query, so call sites keep `Match.tag`-ing the
- * arms. `error` wins over `data` so a failed refetch surfaces the `Error` arm,
- * matching the pre-`QueryState` driver; `isFetching` becomes the arm's
- * `refetching` flag. The data-less case is `Loading` while fetching (or for a
- * non-gated query, which always fetches) and `Idle` only for a switched-off
- * gateable query.
- */
 export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
   Option.match(state.error, {
     onSome: (error) => AsyncData.error(error, state.isFetching),
@@ -47,6 +25,5 @@ export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyA
       }),
   })
 
-/** `Loading` in the React-Query sense: fetching with nothing to show yet. */
 export const isLoading = <A, E>(state: QueryState<A, E>): boolean =>
   state.isFetching && Option.isNone(state.data)