@playfast/reform 1.0.1 → 1.2.0

package/src/calc/calcFamily.ts

@@ -9,60 +9,70 @@ import {
 } 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 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.
+export interface CalcFamilySchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
 
-export interface CalcFamilyManifest<N extends string, K, Out> extends Manifest {
+export interface CalcFamilyManifest<N extends string> extends Manifest {
   readonly kind: 'CalcFamily'
   readonly name: N
-  readonly key: Schema.Schema<K, any>
-  readonly output: Schema.Schema<Out, any>
+  readonly key: CalcFamilySchemaReflection
+  readonly output: CalcFamilySchemaReflection
+}
+
+export const CalcFamilyStoreTypeId: unique symbol = Symbol.for('reform/CalcFamilyStore')
+export type CalcFamilyStoreTypeId = typeof CalcFamilyStoreTypeId
+
+export interface CalcFamilyStore<N extends string, in out K, in out Out> extends FamilyStore<
+  K,
+  Out
+> {
+  readonly [CalcFamilyStoreTypeId]: N
 }
 
 export interface CalcFamilyClass<
-  out N extends string,
-  out Inputs extends ReadonlyArray<AnySource>,
-  in out K,
-  in out Out,
+  N extends string,
+  Inputs extends ReadonlyArray<AnySource>,
+  K,
+  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 manifest: CalcFamilyManifest<N>
+  readonly store: Context.Tag<CalcFamilyStore<N, K, Out>, FamilyStore<K, Out>>
   readonly inputs: Inputs
 }
 
-export interface CalcFamilyConfig<Inputs extends ReadonlyArray<AnySource>, K, Out> {
-  readonly key: Schema.Schema<K, any>
+export interface CalcFamilyConfig<
+  Inputs extends ReadonlyArray<AnySource>,
+  KeySchema extends Schema.Schema.AnyNoContext,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+> {
+  readonly key: KeySchema
   readonly inputs: Inputs
-  readonly output: Schema.Schema<Out, any>
+  readonly output: OutputSchema
 }
 
-/**
- * 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>(
+export const make = <
+  const N extends string,
+  const Inputs extends ReadonlyArray<AnySource>,
+  KeySchema extends Schema.Schema.AnyNoContext,
+  OutputSchema extends Schema.Schema.AnyNoContext,
+>(
   name: N,
-  config: CalcFamilyConfig<Inputs, K, Out>,
-): CalcFamilyClass<N, Inputs, K, Out> => {
-  const store = Context.GenericTag<FamilyStore<K, Out>, FamilyStore<K, Out>>(
+  config: CalcFamilyConfig<Inputs, KeySchema, OutputSchema>,
+): CalcFamilyClass<N, Inputs, Schema.Schema.Type<KeySchema>, Schema.Schema.Type<OutputSchema>> => {
+  type K = Schema.Schema.Type<KeySchema>
+  type Out = Schema.Schema.Type<OutputSchema>
+  const store = Context.GenericTag<CalcFamilyStore<N, K, Out>, FamilyStore<K, Out>>(
     `reform/calcFamily/${name}`,
   )
-  const manifest: CalcFamilyManifest<N, K, Out> = {
+  const manifest: CalcFamilyManifest<N> = {
     kind: 'CalcFamily',
     name,
     key: config.key,
@@ -75,54 +85,33 @@ 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.Effect<Out, never, CalcFamilyStore<N, 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.
-   */
+export interface CalcFamilyLiveOptionsExternalApi<
+  Inputs extends ReadonlyArray<AnySource>,
+> extends FamilyOptions {
   readonly invalidateBy?: InvalidateBy<Inputs>
+  readonly reuse?: boolean
 }
 
-/**
- * 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,
   options: CalcFamilyLiveOptionsExternalApi<Inputs> = {},
-): Layer.Layer<FamilyStore<K, Out>, never, InputStores<Inputs>> =>
+): Layer.Layer<CalcFamilyStore<N, K, Out>, never, InputStores<Inputs>> =>
   Layer.scoped(
     family.store,
     Effect.gen(function* () {
       const scheduler = yield* resolveScheduler
       const instrumentation = yield* resolveInstrumentation
       const onOutputChange = stateUpdateHook(instrumentation, family.manifest.name)
-      // Wired ONCE for the whole family — members share the sensing surface.
       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 => {
@@ -134,8 +123,9 @@ 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 createMember = (
+        key: K,
+      ): { readonly store: Store<Out>; readonly unsubscribe: () => void } => {
         const body = compute(key)
         const memo = MutableRef.make<
           { readonly key: ReadonlyArray<unknown>; readonly output: Out } | undefined
@@ -148,7 +138,9 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
             return prev.output
           }
           const end = instrumentation.calcRecomputed(family.manifest.name)
-          const output = body(args)
+          const fresh = body(args)
+          const output =
+            options.reuse === true && prev !== undefined ? reuse(prev.output, fresh) : fresh
           end()
           MutableRef.set(memo, { key: memoKey, output })
           return output
@@ -156,9 +148,6 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         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>,
@@ -33,20 +13,7 @@ export function composeCalcs<LOut, LErr, LIn, AOut, AErr, AIn, BOut, BErr, BIn>(
   LErr | AErr | BErr,
   BIn | Exclude<AIn | Exclude<LIn, AOut>, BOut>
 >
-export function composeCalcs<
-  LOut,
-  LErr,
-  LIn,
-  AOut,
-  AErr,
-  AIn,
-  BOut,
-  BErr,
-  BIn,
-  COut,
-  CErr,
-  CIn,
->(
+export function composeCalcs<LOut, LErr, LIn, AOut, AErr, AIn, BOut, BErr, BIn, COut, CErr, CIn>(
   leaf: Layer.Layer<LOut, LErr, LIn>,
   upstream1: Layer.Layer<AOut, AErr, AIn>,
   upstream2: Layer.Layer<BOut, BErr, BIn>,
@@ -60,8 +27,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)