@playfast/reform 1.3.0 → 1.4.1

package/src/calc/asyncCalc.ts

@@ -1,6 +1,7 @@
 import { Context, Effect, Layer, Match, Option, Schema } from 'effect'
 import { yieldableClass } from '../definition/definition'
 import { type AnyEvent } from '../event/event'
+import { resolvePersistSlot } from '../internal/queryDriverPersistWarn'
 import { type InputStores } from '../internal/sources'
 import {
   bumpRevision,
@@ -15,7 +16,7 @@ import { type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import * as Reducer from '../reducer/reducer'
 import { Reducers } from '../runtime/loop'
-import { Queries } from '../runtime/queries'
+import { Queries, type QueryHandle } from '../runtime/queries'
 import * as State from '../state/state'
 import { type AnySource, type SourceCapture } from '../state/token'
 import { type AsyncData, narrowStore } from './asyncData'
@@ -44,7 +45,6 @@ export type {
   DefinedAsyncCalcClass,
 } from './asyncCalcTypes'
 
-
 export function make<
   const N extends string,
   const Inputs extends ReadonlyArray<AnySource>,
@@ -154,10 +154,12 @@ export function live<
       const cfg: AsyncCalcLiveView<Inputs, A, E, R> = config
 
       const persistOption = cfg.persist
-      const persistKey =
-        persistOption === true || persistOption === undefined || persistOption === false
-          ? calc.manifest.name
-          : (persistOption.key ?? calc.manifest.name)
+      const persistKey = yield* resolvePersistSlot({
+        label: 'AsyncCalc',
+        name: calc.manifest.name,
+        inputs: calc.inputs.length,
+        option: persistOption,
+      })
       const persistCodec: QueryCodec<A> = {
         encode: Schema.encode(calc.manifest.output),
         decode: Schema.decodeUnknown(calc.manifest.output),
@@ -188,6 +190,7 @@ export function live<
         disabled: cfg.disabled,
         coalesce: cfg.coalesce,
         reuse: cfg.reuse,
+        keepPreviousData: cfg.keepPreviousData,
         persist,
         extraKey,
       })
@@ -208,14 +211,34 @@ export function live<
   )
 }
 
+// Resolved through `manifest`, never through `calc.name`: a `class X extends
+// AsyncCalc.make('some/name')` declaration defines its own `name` own-property,
+// which shadows the registered one — so a name-keyed lookup silently misses for
+// exactly the namespaced names the framework asks authors to use.
 export interface NamedCalc {
-  readonly name: string
+  readonly manifest: { readonly name: string }
 }
 
-export const invalidate = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
+const onHandle = (
+  calc: NamedCalc,
+  verb: string,
+  act: (handle: QueryHandle) => void,
+): Effect.Effect<void, never, Queries> =>
   Effect.flatMap(Queries, (queries) =>
-    Effect.sync(() => queries.byName.get(calc.name)?.invalidate()),
+    Effect.suspend(() =>
+      Option.match(Option.fromNullable(queries.byName.get(calc.manifest.name)), {
+        // Swallowing this is how a dead invalidation goes unnoticed for a release.
+        onNone: () =>
+          Effect.logWarning(
+            `reform: ${verb} skipped — no live query named '${calc.manifest.name}'`,
+          ),
+        onSome: (handle) => Effect.sync(() => act(handle)),
+      }),
+    ),
   )
 
+export const invalidate = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
+  onHandle(calc, 'invalidate', (handle) => handle.invalidate())
+
 export const refetch = (calc: NamedCalc): Effect.Effect<void, never, Queries> =>
-  Effect.flatMap(Queries, (queries) => Effect.sync(() => queries.byName.get(calc.name)?.refetch()))
+  onHandle(calc, 'refetch', (handle) => handle.refetch())

package/src/calc/asyncCalcTypes.ts

@@ -109,6 +109,11 @@ export type AsyncCalcLive<
   readonly coalesce?: 'switch' | 'trailing'
   // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly reuse?: boolean
+  // Keep showing the previous key's result while the new key loads. Off by default:
+  // a retained payload is not an answer to the key being asked. Turn it on only when
+  // the payload is displayed, never when fields are read off it.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
+  readonly keepPreviousData?: boolean
   // oxlint-disable-next-line reform-rules/no-optional-fields -- caller-omitted option built at the asyncCalc/remoteState construction site; Option<T> would change that call shape
   readonly persist?:
     | boolean
@@ -133,6 +138,7 @@ export interface AsyncCalcLiveView<Inputs extends ReadonlyArray<AnySource>, A, E
   readonly disabled?: (inputs: InputsObject<Inputs>) => boolean
   readonly coalesce?: 'switch' | 'trailing'
   readonly reuse?: boolean
+  readonly keepPreviousData?: boolean
   readonly persist?:
     | boolean
     | { readonly key?: string | ((inputs: InputsObject<Inputs>) => string) }

package/src/calc/calcFamily.ts

@@ -7,6 +7,7 @@ import {
   sameKey,
   wireSources,
 } from '../internal/sources'
+import { makeKeyCanonicalizer } from '../internal/familyKeys'
 import { resolveScheduler } from '../internal/scheduler'
 import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { reuse } from '../internal/reuse'
@@ -14,6 +15,7 @@ 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'
+import { microtask } from '../internal/platform'
 
 export interface CalcFamilySchemaReflection {
   readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
@@ -111,8 +113,39 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
       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 keys = makeKeyCanonicalizer<K>()
       const evictWhenUnused = options.evictWhenUnused === true
-      const subscribers = new Map<K, number>()
+      // Stamps identify a member *instance*, not a key: `forget` lets one key hold a
+      // succession of members, and a stale unsubscribe from an earlier one must not
+      // decrement — or evict — the one that replaced it.
+      const stamps = new Map<K, number>()
+      const nextStamp = MutableRef.make(0)
+
+      // A forgotten key's member is orphaned — `at(key)` mints a fresh one — so its
+      // subscribers must be woken to re-read, or they hold a store nothing recomputes
+      // again and never hear about the key another way.
+      const wakers = new Map<K, Set<() => void>>()
+      const wakersFor = (key: K): Set<() => void> => {
+        const existing = wakers.get(key)
+        if (existing !== undefined) {
+          return existing
+        }
+        const created = new Set<() => void>()
+        wakers.set(key, created)
+        return created
+      }
+      const wakeable = (key: K, store: Store<Out>): Store<Out> => ({
+        ...store,
+        subscribe: (listener) => {
+          const registered = wakersFor(key)
+          registered.add(listener)
+          const off = store.subscribe(listener)
+          return () => {
+            registered.delete(listener)
+            off()
+          }
+        },
+      })
 
       const dropEntry = (key: K): void => {
         const entry = entries.get(key)
@@ -120,7 +153,13 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
           entry.unsubscribe()
         }
         entries.delete(key)
-        subscribers.delete(key)
+        stamps.delete(key)
+        keys.release(key)
+        const woken = wakers.get(key)
+        wakers.delete(key)
+        if (woken !== undefined && woken.size > 0) {
+          scheduler.schedule(woken)
+        }
       }
 
       const createMember = (
@@ -148,51 +187,59 @@ export const live = <N extends string, Inputs extends ReadonlyArray<AnySource>,
         return makeDerivedStore(recompute, sources.subscribe, scheduler, onOutputChange)
       }
 
-      const refCounted = (key: K, store: Store<Out>): Store<Out> => ({
-        ...store,
-        subscribe: (listener) => {
-          const priorCount = subscribers.get(key)
-          subscribers.set(key, (priorCount === undefined ? 0 : priorCount) + 1)
-          const off = store.subscribe(listener)
-          const released = { done: false }
-          return () => {
-            if (released.done) {
-              return
-            }
-            released.done = true
-            off()
-            const remaining = (subscribers.get(key) ?? 1) - 1
-            if (remaining > 0) {
-              subscribers.set(key, remaining)
-              return
-            }
-            subscribers.delete(key)
-            queueMicrotask(() => {
-              const liveCount = subscribers.get(key)
-              if (liveCount === undefined || liveCount === 0) {
-                dropEntry(key)
+      const refCounted = (key: K, store: Store<Out>, stamp: number): Store<Out> => {
+        const count = MutableRef.make(0)
+        return {
+          ...store,
+          subscribe: (listener) => {
+            MutableRef.update(count, (current) => current + 1)
+            const off = store.subscribe(listener)
+            const released = { done: false }
+            return () => {
+              if (released.done) {
+                return
               }
-            })
-          }
-        },
-      })
+              released.done = true
+              off()
+              MutableRef.update(count, (current) => Math.max(0, current - 1))
+              if (MutableRef.get(count) > 0) {
+                return
+              }
+              microtask(() => {
+                // Still unused, and still the member this key holds.
+                if (MutableRef.get(count) === 0 && stamps.get(key) === stamp) {
+                  dropEntry(key)
+                }
+              })
+            }
+          },
+        }
+      }
 
       const familyStore: FamilyStore<K, Out> = {
-        at: (key) => {
+        at: (rawKey) => {
+          const key = keys.canonical(rawKey)
           const existing = entries.get(key)
           if (existing !== undefined) {
             return existing.store
           }
           const member = createMember(key)
-          const created = evictWhenUnused
-            ? { store: refCounted(key, member.store), unsubscribe: member.unsubscribe }
-            : member
+          const stamp = MutableRef.updateAndGet(nextStamp, (current) => current + 1)
+          const created = {
+            store: wakeable(
+              key,
+              evictWhenUnused ? refCounted(key, member.store, stamp) : member.store,
+            ),
+            unsubscribe: member.unsubscribe,
+          }
           entries.set(key, created)
+          stamps.set(key, stamp)
           return created.store
         },
-        forget: dropEntry,
+        forget: (key) => dropEntry(keys.canonical(key)),
         clear: () => {
           ;[...entries.keys()].forEach((key) => dropEntry(key))
+          keys.reset()
         },
         size: () => entries.size,
       }

package/src/calc/family-identity.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Bug hunt — `CalcFamily.live`'s per-member lifecycle (`calc/calcFamily.ts`).
+ *
+ * `StateFamily` treats a family key as holding a *succession* of store
+ * instances. `state/stateFamily.ts` stamps each instance so "a stale
+ * unsubscribe from an earlier one must not decrement — or evict — the one that
+ * replaced it", and wakes a forgotten key's subscribers so they do not "hold a
+ * store nothing writes to again and never hear about the key another way".
+ *
+ * `CalcFamily.live` re-implements that same lifecycle — its `subscribers:
+ * Map<K, number>` / `remaining` / `queueMicrotask` block is line-for-line what
+ * `stateFamily.ts` looked like before those two guards were added — and it got
+ * neither. The ref-count is credited to the KEY, not to the instance that
+ * earned it, and `dropEntry` severs a member's upstream subscription without
+ * telling the listeners still attached to it.
+ *
+ * Both tests run the *working* half of the same scenario first, in the same
+ * body, so a failure cannot be blamed on the harness. Every listener is
+ * attached before anything is awaited. Neither test waits a duration: `flush`
+ * drains microtask turns, which is the exact lane the scheduler and the
+ * eviction `queueMicrotask` both run on.
+ */
+import { expect, it } from '@effect/vitest'
+import { Data, Effect, Equal, Layer, Schema as S } from 'effect'
+import {
+  CalcFamily,
+  Engine,
+  Event,
+  publish,
+  Reducer,
+  State,
+  StateFamily,
+  StateGroup,
+} from '../index'
+import { flush, until } from '../testkit/flight.testkit'
+
+const Board = S.Record({ key: S.String, value: S.Number })
+
+// ---------------------------------------------------------------------------
+// FINDING 1 — `calc/calcFamily.ts:115` + `:151-178`: the eviction ref-count is credited
+// to the KEY, not to the store instance that earned it.
+//
+// `subscribers: Map<K, number>` is shared by every store a key ever holds, and
+// `dropEntry` deletes the key's slot outright. So once `forget(key)` has minted
+// a replacement, the *forgotten* member's release decrements — and then evicts —
+// the live replacement, tearing down its upstream subscription. That is exactly
+// the hazard `stateFamily.ts` closes with per-instance counts + `stamps`.
+// ---------------------------------------------------------------------------
+it.live('calcFamily: a forgotten member stale release evicts its live replacement', () => {
+  class Feed extends State.make('hunt-evict-feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  class Slice extends CalcFamily.make('HuntEvictSlice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'hunt-evict-feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) =>
+      ({ 'hunt-evict-feed': feed }) =>
+        feed[key] ?? 0,
+    { evictWhenUnused: true },
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { 'hunt-evict-feed': { control: 1, victim: 1 } })),
+  )
+
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'hunt-evict-feed').store
+    const family = yield* Slice.store
+    const wakes = { control: 0, victim: 0 }
+
+    // CONTROL — key `control`: subscribe, forget, subscribe the replacement.
+    // The forgotten subscription's release is simply never called, so nothing
+    // stale is in play.
+    family.at('control').subscribe(() => {})
+    family.forget('control')
+    family.at('control').subscribe(() => {
+      wakes.control += 1
+    })
+
+    // DEFECT — key `victim`: the identical sequence, except the forgotten
+    // member's release runs after the replacement is already live.
+    const staleRelease = family.at('victim').subscribe(() => {})
+    family.forget('victim')
+    family.at('victim').subscribe(() => {
+      wakes.victim += 1
+    })
+    staleRelease()
+
+    yield* flush()
+    const membersAfterStaleRelease = family.size()
+
+    feed.set({ control: 2, victim: 2 })
+    yield* flush()
+
+    // The control proves the harness: forget + re-subscribe keeps a live member.
+    expect(wakes.control).toBe(1)
+    // Observed 1: only `control` survived — the stale release dropped `victim`.
+    expect(membersAfterStaleRelease).toBe(2)
+    // Observed 0: `victim`'s live subscriber is never woken again.
+    expect(wakes.victim).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+// FINDING 2 — `calc/calcFamily.ts:117-124`: `dropEntry` orphans a member's
+// subscribers silently.
+//
+// `forget(key)` severs the member's upstream subscription and drops it from
+// `entries`, but never wakes the listeners still attached to that store. They
+// keep a handle whose `getVersion()` can never move again — and that version is
+// exactly what `@playfast/reform-react`'s `Compose` compares to decide whether
+// to repaint — so the view shows a value that is no longer true, permanently.
+// `stateFamily.ts` wakes a forgotten key's subscribers for precisely this reason.
+// ---------------------------------------------------------------------------
+it.live('calcFamily: forget silently orphans a member subscribers', () => {
+  class Feed extends State.make('hunt-orphan-feed', Board) {}
+  class Inputs extends StateGroup.make(Feed) {}
+  class Slice extends CalcFamily.make('HuntOrphanSlice', {
+    key: S.String,
+    inputs: [StateGroup.select(Inputs, 'hunt-orphan-feed')],
+    output: S.Number,
+  }) {}
+  const SliceLive = CalcFamily.live(
+    Slice,
+    (key) =>
+      ({ 'hunt-orphan-feed': feed }) =>
+        feed[key] ?? 0,
+  )
+  const TestLayer = SliceLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { 'hunt-orphan-feed': { control: 1, orphan: 1 } })),
+  )
+
+  return Effect.gen(function* () {
+    const feed = yield* StateGroup.select(Inputs, 'hunt-orphan-feed').store
+    const family = yield* Slice.store
+    const wakes = { control: 0, orphan: 0 }
+
+    family.at('control').subscribe(() => {
+      wakes.control += 1
+    })
+    family.at('orphan').subscribe(() => {
+      wakes.orphan += 1
+    })
+
+    // CONTROL — both members are live, and both wake on a shared-input move.
+    feed.set({ control: 2, orphan: 2 })
+    yield* flush()
+    expect(wakes.control).toBe(1)
+    expect(wakes.orphan).toBe(1)
+
+    // DEFECT — only `orphan` is forgotten. Its subscriber is neither woken by
+    // the forget itself nor reached by any later input move.
+    family.forget('orphan')
+    feed.set({ control: 3, orphan: 3 })
+    yield* flush()
+
+    // The control proves the harness: the untouched member still wakes.
+    expect(wakes.control).toBe(2)
+    // Observed 1: the forgotten member's subscriber went permanently silent.
+    expect(wakes.orphan).toBeGreaterThan(1)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// ---------------------------------------------------------------------------
+// FINDING 3 — `state/stateFamily.ts:30` (and `calc/calcFamily.ts:113`): a family
+// indexes its members in a plain `Map<K, …>`, i.e. by SameValueZero reference
+// identity, while every other equality in reform is `Equal.equals`
+// (`internal/store.ts:28`, `internal/sources.ts:45`).
+//
+// So a composite key that is `Equal.equals`-equal — the Effect-canonical way to
+// have a value-typed key, `Schema.Data` / `Data.struct` — resolves to a DIFFERENT
+// store on every lookup. Through the family reducer path that is unconditional,
+// not a caller mistake: `reducer/reducer.ts:131-141` re-decodes the key with
+// `family.validateKeySync(...)`, which mints a fresh object for a struct schema,
+// so `family.at(key)` can never hit the entry the previous event wrote. The fold
+// reads the seed forever, each event strands a new store, and nothing warns.
+// ---------------------------------------------------------------------------
+it.live('stateFamily: an Equal-equal composite key resolves to a different member', () => {
+  const RowKey = S.Data(S.Struct({ board: S.String, row: S.Number }))
+  class Flat extends StateFamily.make('hunt-flat-tally', S.String, S.Number) {}
+  class Keyed extends StateFamily.make('hunt-keyed-tally', RowKey, S.Number) {}
+  class Bumped extends Event.make('HuntBumped', S.Struct({ board: S.String, row: S.Number })) {}
+  class FlatReducer extends Reducer.make('HuntFlatReducer', {
+    family: Flat,
+    keyOf: (event) => `${event.board}:${event.row}`,
+    events: [Bumped],
+  }) {}
+  class KeyedReducer extends Reducer.make('HuntKeyedReducer', {
+    family: Keyed,
+    keyOf: (event) => Data.struct({ board: event.board, row: event.row }),
+    events: [Bumped],
+  }) {}
+  const TestLayer = Layer.mergeAll(
+    Reducer.live(FlatReducer, (count) => count + 1),
+    Reducer.live(KeyedReducer, (count) => count + 1),
+  ).pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(StateFamily.live(Flat, 0), StateFamily.live(Keyed, 0), Engine),
+    ),
+  )
+
+  return Effect.gen(function* () {
+    const flat = yield* Flat.store
+    const keyed = yield* Keyed.store
+    const lookup = Data.struct({ board: 'b', row: 1 })
+    const twin = Data.struct({ board: 'b', row: 1 })
+
+    // Both keys are `Equal.equals`-equal — the premise the family violates.
+    expect(Equal.equals(lookup, twin)).toBe(true)
+
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+    yield* publish('High', Event.construct(Bumped, { board: 'b', row: 1 }))
+
+    // CONTROL — the string-keyed twin of the same reducer, same events, same
+    // fold. Gating on it also proves all three events were folded.
+    yield* until(
+      () => flat.at('b:1').get(),
+      (count) => count === 3,
+    )
+    expect(flat.at('b:1').get()).toBe(3)
+    expect(flat.size()).toBe(1)
+
+    // Observed 0: every fold read the seed and wrote into a brand-new store.
+    expect(keyed.at(lookup).get()).toBe(3)
+    // Observed 4: three stranded members plus the one this lookup just minted.
+    expect(keyed.size()).toBe(1)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/queryState.ts

@@ -6,24 +6,55 @@ export interface QueryState<A, E> {
   readonly error: Option.Option<E>
   readonly isFetching: boolean
   readonly isStale: boolean
+  // The settled result answers an input key the sources have since moved past.
+  // Without it a retained payload is indistinguishable from an answer to the key
+  // the consumer actually asked with.
+  readonly isPreviousKey: boolean
+  // Whether a previous key's payload is presentable. Carried on the state rather
+  // than passed per-reader so every reading of one query agrees about what is
+  // showing — `toAsyncData` and `isLoading` used to be able to contradict.
+  readonly keepPreviousData: boolean
 }
 
-export const empty = (fetching: boolean): QueryState<never, never> => ({
+export const empty = (fetching: boolean, keepPreviousData = false): QueryState<never, never> => ({
   data: Option.none(),
   error: Option.none(),
   isFetching: fetching,
   isStale: false,
+  isPreviousKey: false,
+  keepPreviousData,
 })
 
-export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
-  Option.match(state.error, {
+const unsettled = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> =>
+  state.isFetching || !gated ? AsyncData.loading : AsyncData.idle
+
+// A result belonging to a superseded key is not an answer to the question being
+// asked, so it reads as unsettled. `keepPreviousData` opts back into showing it —
+// safe when the payload is only displayed, unsafe when fields are read off it.
+export const toAsyncData = <A, E>(state: QueryState<A, E>, gated: boolean): AnyAsyncData<A, E> => {
+  // `keepPreviousData` keeps a *payload*, and only a payload. A previous key's error
+  // is a verdict on a question nobody is asking any more — republishing it gates the
+  // key now in flight behind a failure that is not its own — and a key that produced
+  // only an error has nothing to keep at all.
+  if (state.isPreviousKey) {
+    const kept = state.keepPreviousData ? state.data : Option.none()
+    return Option.match(kept, {
+      onNone: () => unsettled(state, gated),
+      onSome: (payload) => AsyncData.success(payload, state.isFetching),
+    })
+  }
+  return Option.match(state.error, {
     onSome: (error) => AsyncData.error(error, state.isFetching),
     onNone: () =>
       Option.match(state.data, {
         onSome: (payload) => AsyncData.success(payload, state.isFetching),
-        onNone: () => (state.isFetching || !gated ? AsyncData.loading : AsyncData.idle),
+        onNone: () => unsettled(state, gated),
       }),
   })
+}
 
+// True while there is nothing to show for the key being asked. A previous key's
+// payload counts as something to show exactly when the query keeps it.
 export const isLoading = <A, E>(state: QueryState<A, E>): boolean =>
-  state.isFetching && Option.isNone(state.data)
+  state.isFetching &&
+  (Option.isNone(state.data) || (state.isPreviousKey && !state.keepPreviousData))