@playfast/reform 1.2.1 → 1.4.0

package/src/calc/asyncCalc-registry-name.test.ts

@@ -0,0 +1,82 @@
+import { expect, it } from '@effect/vitest'
+import { Effect, Layer, Schema as S } from 'effect'
+import { AsyncCalc, Engine, State, StateGroup } from '../index'
+import { Queries } from '../runtime/queries'
+import { until } from '../testkit/flight.testkit'
+
+// `AsyncCalc.invalidate`/`refetch` look the query up by `calc.name`. A class
+// declaration defines its own `name` own-property, so `class ChatHistory extends
+// AsyncCalc.make('chat/history', …)` reports 'ChatHistory' and shadows the
+// registered 'chat/history'. The registry lookup misses and the call is silently
+// swallowed by `?.` — the very naming the framework asks for (namespace the name
+// per feature) is what breaks it.
+
+class Seed extends State.make('seed', S.Number) {}
+class Inputs extends StateGroup.make(Seed) {}
+const seed = StateGroup.select(Inputs, 'seed')
+
+const isStale = (name: string): Effect.Effect<boolean, never, Queries> =>
+  Effect.map(Queries, (queries) => queries.byName.get(name)?.snapshot().isStale ?? false)
+
+it.live('refetch reaches a calc whose class binding differs from its registered name', () => {
+  const runs = { n: 0 }
+  class ChatHistory extends AsyncCalc.make('chat/history', {
+    inputs: [seed],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const Live = AsyncCalc.live(ChatHistory, {
+    query: ({ seed: value }) =>
+      Effect.sync(() => {
+        runs.n += 1
+        return value
+      }),
+  })
+  const TestLayer = Live.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* ChatHistory.store
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success',
+    )
+    expect(runs.n).toBe(1)
+
+    yield* AsyncCalc.refetch(ChatHistory)
+    yield* until(
+      () => runs.n,
+      (n) => n > 1,
+      20,
+    )
+    expect(runs.n).toBe(2)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('invalidate reaches a calc whose class binding differs from its registered name', () => {
+  class ChatBranches extends AsyncCalc.make('chat/branches', {
+    inputs: [seed],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const Live = AsyncCalc.live(ChatBranches, {
+    query: ({ seed: value }) => Effect.succeed(value),
+  })
+  const TestLayer = Live.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { seed: 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    const store = yield* ChatBranches.store
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+
+    yield* AsyncCalc.invalidate(ChatBranches)
+    expect(yield* isStale('chat/branches')).toBe(true)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/asyncCalc.superseded-commit.test.ts

@@ -0,0 +1,162 @@
+import { expect, it } from '@effect/vitest'
+import { Data, Effect, Layer, Schema as S } from 'effect'
+import { AsyncCalc, Engine, State, StateGroup } from '../index'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
+
+// Class bindings match their registered names on purpose: `AsyncCalc.invalidate` /
+// `refetch` resolve a query by `calc.name`, and a class declaration installs its
+// own `name` own-property that shadows the static the framework wrote. That
+// divergence is a separate finding — these tests keep the two aligned so they
+// isolate the driver, not the lookup.
+
+class Torn extends Data.TaggedError('Torn')<{ readonly reason: string }> {}
+
+// A negative wait: long enough that the missing transition would have landed,
+// short enough that the assertion — not the timeout — reports the failure.
+const settleRounds = 40
+
+// `commitSuccess` asks only `disabledNow()` — is the query enabled *now* — before
+// writing. It never asks whether the request it is committing survived the gate.
+// A run that was in flight when `disabled` flipped is dropped from the queue's
+// point of view and its state wiped to Idle, yet it still lands as the answer once
+// the query is re-enabled under a different key. `coalesce: 'trailing'` makes this
+// deterministic: that consumer never cancels the run it is holding.
+it.live('a flight disabled away commits over the query the gate reset', () => {
+  class Count extends State.make('supersedeDisableCount', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class SupersedeDisableResurrect extends AsyncCalc.make('SupersedeDisableResurrect', {
+    inputs: [StateGroup.select(Inputs, 'supersedeDisableCount')],
+    output: S.Number,
+  }) {}
+  const firstGate = makeFlightGate()
+  const laterGate = makeFlightGate()
+  // Armed before the layer builds, so the very first flight parks at the gate.
+  Effect.runSync(firstGate.hold)
+  Effect.runSync(laterGate.hold)
+  const TestLayer = AsyncCalc.live(SupersedeDisableResurrect, {
+    query: ({ supersedeDisableCount: count }) =>
+      count === 1
+        ? firstGate.through(Effect.succeed(count * 2))
+        : laterGate.through(Effect.succeed(count * 2)),
+    disabled: ({ supersedeDisableCount: count }) => count < 0,
+    coalesce: 'trailing',
+  }).pipe(Layer.provideMerge(StateGroup.live(Inputs, { supersedeDisableCount: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'supersedeDisableCount').store
+    const store = yield* SupersedeDisableResurrect.store
+    yield* firstGate.awaitEntry(1)
+
+    // count=1's answer is held at the gate; the disable then wipes the query back
+    // to Idle and drops the key it was asked with.
+    source.set(-1)
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Idle',
+    )
+    expect(store.get()._tag).toBe('Idle')
+
+    // Re-enabled at a different key. The trailing consumer runs count=1 to
+    // completion first, then parks count=5's flight, so what the store reports in
+    // between is a stable state rather than a window to catch.
+    source.set(5)
+    yield* firstGate.release
+    yield* laterGate.awaitEntry(1)
+
+    // count=1's answer belongs to a key the gate already discarded: it is not an
+    // answer about count=5, and it is not permission to leave Idle behind.
+    expect(store.get()).toMatchObject({ _tag: 'Loading' })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// The same hole on the failure side: `settleError` sits behind the identical
+// `!disabledNow()` guard, so a disabled-away run's failure is published as the
+// current key's error.
+it.live('a failure disabled away commits over the query the gate reset', () => {
+  class Count extends State.make('supersedeDisableErrCount', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class SupersedeDisableResurrectError extends AsyncCalc.make('SupersedeDisableResurrectError', {
+    inputs: [StateGroup.select(Inputs, 'supersedeDisableErrCount')],
+    output: S.Number,
+    error: S.String,
+  }) {}
+  const firstGate = makeFlightGate()
+  const laterGate = makeFlightGate()
+  Effect.runSync(firstGate.hold)
+  Effect.runSync(laterGate.hold)
+  const TestLayer = AsyncCalc.live(SupersedeDisableResurrectError, {
+    query: ({ supersedeDisableErrCount: count }): Effect.Effect<number, string> =>
+      count === 1
+        ? // Park first, then fail: the gate only wraps a success.
+          firstGate.through(Effect.void).pipe(Effect.zipRight(Effect.fail('boom-for-1')))
+        : laterGate.through(Effect.succeed(count * 2)),
+    disabled: ({ supersedeDisableErrCount: count }) => count < 0,
+    coalesce: 'trailing',
+  }).pipe(Layer.provideMerge(StateGroup.live(Inputs, { supersedeDisableErrCount: 1 })))
+
+  return Effect.gen(function* () {
+    const source = yield* StateGroup.select(Inputs, 'supersedeDisableErrCount').store
+    const store = yield* SupersedeDisableResurrectError.store
+    yield* firstGate.awaitEntry(1)
+
+    source.set(-1)
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Idle',
+    )
+    expect(store.get()._tag).toBe('Idle')
+
+    source.set(5)
+    yield* firstGate.release
+    yield* laterGate.awaitEntry(1)
+
+    // count=1's failure is not a failure of count=5.
+    expect(store.get()).toMatchObject({ _tag: 'Loading' })
+  }).pipe(Effect.provide(TestLayer))
+})
+
+// `runQuery` folds the whole cause: a typed failure reaches `settleError`, but a
+// defect is only logged and then swallowed as `Option.none()`. Nothing ever clears
+// the `isFetching` flag `enqueue` raised, so the run that died stays advertised as
+// in flight for the rest of the query's life.
+it.live('a query that dies leaves the view refetching forever', () => {
+  const runs = { n: 0 }
+  class RegressDefectQ extends AsyncCalc.make('RegressDefectQ', {
+    inputs: [],
+    output: S.Number,
+    alwaysOn: true,
+  }) {}
+  const TestLayer = AsyncCalc.live(RegressDefectQ, {
+    query: (): Effect.Effect<number> =>
+      Effect.suspend(() => {
+        runs.n += 1
+        // A defect, not a typed failure: an exception escaping the query body.
+        return runs.n === 1 ? Effect.succeed(1) : Effect.die(new Torn({ reason: 'kaboom' }))
+      }),
+  }).pipe(Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    const store = yield* RegressDefectQ.store
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+    )
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 1, refetching: false })
+
+    yield* AsyncCalc.refetch(RegressDefectQ)
+    yield* until(
+      () => runs.n,
+      (n) => n > 1,
+    )
+    expect(runs.n).toBe(2)
+
+    // The run is over — it died. Nothing is in flight and nothing is queued, so
+    // the view must stop advertising a refetch.
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success' && v.refetching === false,
+      settleRounds,
+    )
+    expect(store.get()).toMatchObject({ _tag: 'Success', value: 1, refetching: false })
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/calc/asyncCalc.test.ts

@@ -104,6 +104,10 @@ it.live('a dependency change re-fetches, keeping the last value with refetching:
   const gate = makeFlightGate()
   const DoubledLive = AsyncCalc.live(Doubled, {
     query: ({ count }) => gate.through(Effect.succeed(count * 2)),
+    // Opt-in: across an input-key change the previous key's payload is retained
+    // only under `keepPreviousData`. The default reads as Loading — see
+    // asyncCalc-key-attribution.test.ts.
+    keepPreviousData: true,
   })
   const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 5 })))
 
@@ -245,7 +249,10 @@ it.live('invalidateBy: an input change outside the key does not re-fetch', () =>
     // Holding the gate means any flight the status churn triggered would still
     // be marked fetching here, and could not have settled back out of view.
     yield* gate.hold
-    yield* afterNotify(status, Effect.sync(() => status.set('b')))
+    yield* afterNotify(
+      status,
+      Effect.sync(() => status.set('b')),
+    )
     expect(store.get()).toMatchObject({ _tag: 'Success', refetching: false })
     expect(runs.n).toBe(1)
     yield* gate.release
@@ -338,8 +345,14 @@ it.live(
       yield* gate.hold
       source.set(2)
       yield* gate.awaitEntry(2)
-      yield* afterNotify(source, Effect.sync(() => source.set(3)))
-      yield* afterNotify(source, Effect.sync(() => source.set(4)))
+      yield* afterNotify(
+        source,
+        Effect.sync(() => source.set(3)),
+      )
+      yield* afterNotify(
+        source,
+        Effect.sync(() => source.set(4)),
+      )
       yield* gate.release
       const settled = yield* until(
         () => store.get(),
@@ -371,6 +384,9 @@ it.live(
           ? trailingGate.through(Effect.succeed(count * 2))
           : firstGate.through(Effect.succeed(count * 2)),
       coalesce: 'trailing',
+      // The stale settle belongs to a superseded key, so it is visible only under
+      // `keepPreviousData`; by default it reads as Loading.
+      keepPreviousData: true,
     })
     const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
 
@@ -386,7 +402,10 @@ it.live(
       yield* trailingGate.hold
       source.set(2)
       yield* firstGate.awaitEntry(2)
-      yield* afterNotify(source, Effect.sync(() => source.set(3)))
+      yield* afterNotify(
+        source,
+        Effect.sync(() => source.set(3)),
+      )
 
       yield* firstGate.release
       yield* trailingGate.awaitEntry(1)
@@ -437,8 +456,14 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
     yield* gate.hold
     source.set(2)
     yield* gate.awaitEntry(2)
-    yield* afterNotify(source, Effect.sync(() => source.set(3)))
-    yield* afterNotify(source, Effect.sync(() => source.set(-1)))
+    yield* afterNotify(
+      source,
+      Effect.sync(() => source.set(3)),
+    )
+    yield* afterNotify(
+      source,
+      Effect.sync(() => source.set(-1)),
+    )
     yield* gate.release
     expect(store.get()._tag).toBe('Idle')
     expect(completed).toEqual([1, 2])
@@ -545,7 +570,10 @@ it.live(
       expect(runs.n).toBe(1)
 
       yield* gate.hold
-      yield* afterNotify(status, Effect.sync(() => status.set('b')))
+      yield* afterNotify(
+        status,
+        Effect.sync(() => status.set('b')),
+      )
       expect(store.get()).toMatchObject({ _tag: 'Success', refetching: false })
       expect(runs.n).toBe(1)
       yield* gate.release

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.test.ts

@@ -0,0 +1,64 @@
+import { expect, it } from '@effect/vitest'
+import type { Effect } from 'effect'
+import { Schema as S } from 'effect'
+import { AsyncCalc, Namespace, State, StateGroup } from '../index'
+import type { AsyncData } from './asyncData'
+
+// Pins the config -> value-type contract: a named schema in `output`/`error` must survive
+// inference. The package publishes source, so consumers compile these signatures under their
+// own tsconfig — keep `output`/`error` bare inference sites rather than wrapped in anything
+// deferred. `Namespace.make` is the exposed path here because `AsyncCalc.make` can fall back
+// to its second overload, which would mask a regression in `AsyncCalcConfig` itself.
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true
+  : false
+const expectTypeEquality = <_Proof extends true>(): void => {}
+
+const ns = Namespace.make('apps')
+
+it('infers output and error schema types from named schemas', () => {
+  const Result = S.Struct({ id: S.String, count: S.Number })
+
+  class Count extends State.make('count', S.Number) {}
+  class Inputs extends StateGroup.make(Count) {}
+  class MyApps extends ns.AsyncCalc('MyApps', {
+    inputs: [StateGroup.select(Inputs, 'count')],
+    output: Result,
+    error: S.String,
+    alwaysOn: true,
+  }) {}
+
+  type Data = Effect.Effect.Success<typeof MyApps>
+  expectTypeEquality<
+    Equals<Data, AsyncData<{ readonly id: string; readonly count: number }, string, false>>
+  >()
+
+  // `MyApps.name` is the JS class binding's own name, which shadows the prefixed one.
+  expect(MyApps.manifest.name).toBe('apps.MyApps')
+  expect(MyApps.gated).toBe(false)
+})
+
+it('defaults the error type to never when `error` is omitted', () => {
+  class Loaded extends ns.AsyncCalc('Loaded', {
+    inputs: [],
+    output: S.Number,
+  }) {}
+
+  type Data = Effect.Effect.Success<typeof Loaded>
+  expectTypeEquality<Equals<Data, AsyncData<number, never, true>>>()
+
+  expect(Loaded.gated).toBe(true)
+})
+
+it('keeps `AsyncCalc.make` inference intact through its overloads', () => {
+  class Doubled extends AsyncCalc.make('Doubled', {
+    inputs: [],
+    output: S.Number,
+    error: S.String,
+    alwaysOn: true,
+  }) {}
+
+  type Data = Effect.Effect.Success<typeof Doubled>
+  expectTypeEquality<Equals<Data, AsyncData<number, string, false>>>()
+
+  expect(Doubled.gated).toBe(false)
+})

package/src/calc/asyncCalcTypes.ts

@@ -70,14 +70,6 @@ export interface DefinedAsyncCalcClass<
   readonly capture: <Result>(visit: SourceCapture<Result>) => Result
 }
 
-type ConfigSchema<ValueOrSchema> = [ValueOrSchema] extends [Schema.Schema.AnyNoContext]
-  ? ValueOrSchema
-  : AnySchema<ValueOrSchema>
-
-type ConfigErrorSchema<ValueOrSchema> = [ValueOrSchema] extends [undefined]
-  ? ValueOrSchema
-  : ConfigSchema<ValueOrSchema>
-
 export interface AsyncCalcConfig<
   Inputs extends ReadonlyArray<AnySource>,
   OutputSchema,
@@ -85,9 +77,9 @@ export interface AsyncCalcConfig<
   AlwaysOn extends boolean,
 > {
   readonly inputs: Inputs
-  readonly output: ConfigSchema<OutputSchema>
+  readonly output: OutputSchema
   // 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 error?: ConfigErrorSchema<ErrorSchema>
+  readonly error?: ErrorSchema
   // 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 alwaysOn?: AlwaysOn
 }
@@ -117,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
@@ -141,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) }