@playfast/reform 1.0.1 → 1.2.0

package/src/calc/asyncCalc.test.ts

@@ -1,22 +1,7 @@
 import { expect, it } from '@effect/vitest'
 import { Data, Duration, Effect, Layer, Schema as S } from 'effect'
 import { AsyncCalc, Engine, Event, State, StateGroup } from '../index'
-
-// AsyncCalc is a derived store whose value is the lifecycle of an Effect. It runs
-// the query reactively from its inputs (latest-wins), keeps the last value while
-// re-fetching (stale-while-revalidate), and goes Idle when a gated query disables.
-
-const tick = (ms = 10) => Effect.sleep(Duration.millis(ms))
-
-// Poll until the predicate holds (bounded) — for assertions that race real
-// timers under parallel-suite host load, where a fixed `tick` budget flakes.
-const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
-  Effect.suspend(() => {
-    const a = read()
-    return pred(a) || rounds <= 0
-      ? Effect.succeed(a)
-      : Effect.flatMap(tick(10), () => until(read, pred, rounds - 1))
-  })
+import { makeFlightGate, tick, until } from '../testkit/flight.testkit'
 
 class Boom extends Data.TaggedError('Boom')<{ readonly message: string }> {}
 
@@ -35,7 +20,6 @@ it.live('runs the query and resolves Loading -> Success', () => {
 
   return Effect.gen(function* () {
     const store = yield* Doubled.store
-    // Before the forked query resolves, the value is Loading.
     expect(store.get()._tag).toBe('Loading')
     yield* tick(40)
     const value = store.get()
@@ -92,7 +76,6 @@ it.live('a dependency change re-fetches, keeping the last value with refetching:
     yield* tick(40)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: false })
 
-    // Move the input: the prior value is kept while the new fetch is in flight.
     source.set(7)
     yield* tick(5)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 10, refetching: true })
@@ -126,9 +109,6 @@ it.live('latest-wins: a rapid second change cancels the in-flight run', () => {
     yield* tick(40)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 2 })
 
-    // Two changes in quick succession: the first run is switched out before it
-    // can write, so only the latest value lands (poll — fixed sleeps flake when
-    // a loaded host starves the 25ms query timer).
     source.set(3)
     yield* tick(5)
     source.set(4)
@@ -181,7 +161,6 @@ it.live('invalidateBy: an input change outside the key does not re-fetch', () =>
         runs.n += 1
         return page
       }),
-    // Only `page` is part of the key; `status` churn must not re-fetch.
     invalidateBy: ({ page }) => [page],
   })
   const TestLayer = QLive.pipe(
@@ -195,12 +174,10 @@ it.live('invalidateBy: an input change outside the key does not re-fetch', () =>
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // status moves, key unchanged -> no re-fetch.
     status.set('b')
     yield* tick()
     expect(runs.n).toBe(1)
 
-    // page moves, key changes -> one re-fetch.
     page.set(2)
     yield* tick()
     expect(runs.n).toBe(2)
@@ -218,7 +195,6 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
     alwaysOn: true,
   }) {}
   const RowsLive = AsyncCalc.live(Rows, {
-    // Fresh objects every run — only the row matching `page` differs.
     query: ({ page }) =>
       Effect.succeed([
         { id: 1, name: 'one' },
@@ -231,7 +207,10 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
   return Effect.gen(function* () {
     const source = yield* StateGroup.select(Inputs, 'page').store
     const store = yield* Rows.store
-    const first = yield* until(() => store.get(), (v) => v._tag === 'Success')
+    const first = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success',
+    )
     if (first._tag !== 'Success') return
 
     source.set(2)
@@ -240,94 +219,105 @@ it.live('reuse: a refetch returning mostly-equal data keeps unchanged element id
       (v) => v._tag === 'Success' && v.refetching === false && v.value !== first.value,
     )
     if (second._tag !== 'Success') return
-    // Row 1 didn't move: same identity. Row 2 did: fresh.
     expect(second.value[0]).toBe(first.value[0])
     expect(second.value[1]).not.toBe(first.value[1])
     expect(second.value[1]).toEqual({ id: 2, name: 'two@2' })
   }).pipe(Effect.provide(TestLayer))
 })
 
-it.live('coalesce trailing: a burst during one flight completes it and runs ONE trailing refetch', () => {
-  class Count extends State.make('count', S.Number) {}
-  class Inputs extends StateGroup.make(Count) {}
-  // Completion log: the sync body runs AFTER the delay, so the order proves
-  // which runs actually finished (and that the in-flight one was not cancelled).
-  const completed: number[] = []
-  class Doubled extends AsyncCalc.make('Doubled', {
-    inputs: [StateGroup.select(Inputs, 'count')],
-    output: S.Number,
-    alwaysOn: true,
-  }) {}
-  const DoubledLive = AsyncCalc.live(Doubled, {
-    query: ({ count }) =>
-      Effect.sync(() => {
-        completed.push(count)
-        return count * 2
-      }).pipe(Effect.delay(Duration.millis(25))),
-    coalesce: 'trailing',
-  })
-  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
-
-  return Effect.gen(function* () {
-    const source = yield* StateGroup.select(Inputs, 'count').store
-    const store = yield* Doubled.store
-    yield* until(() => store.get(), (v) => v._tag === 'Success')
-    expect(completed).toEqual([1])
-
-    // Three key changes during the first change's flight: the in-flight run (2)
-    // completes and lands, the middle change (3) is conflated away, and exactly
-    // one trailing run fetches the latest key (4).
-    source.set(2)
-    yield* tick(5)
-    source.set(3)
-    yield* tick(5)
-    source.set(4)
-    const settled = yield* until(
-      () => store.get(),
-      (v) => v._tag === 'Success' && v.refetching === false && v.value === 8,
-    )
-    expect(settled).toMatchObject({ _tag: 'Success', value: 8, refetching: false })
-    expect(completed).toEqual([1, 2, 4])
-  }).pipe(Effect.provide(TestLayer))
-})
-
-it.live('coalesce trailing: the stale settle re-flags refetching until the trailing run lands', () => {
-  class Count extends State.make('count', S.Number) {}
-  class Inputs extends StateGroup.make(Count) {}
-  class Doubled extends AsyncCalc.make('Doubled', {
-    inputs: [StateGroup.select(Inputs, 'count')],
-    output: S.Number,
-    alwaysOn: true,
-  }) {}
-  const DoubledLive = AsyncCalc.live(Doubled, {
-    query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(30))),
-    coalesce: 'trailing',
-  })
-  const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
-
-  return Effect.gen(function* () {
-    const source = yield* StateGroup.select(Inputs, 'count').store
-    const store = yield* Doubled.store
-    yield* until(() => store.get(), (v) => v._tag === 'Success')
-
-    // Two changes: when the in-flight result (4) lands, a trailing run is still
-    // pending — the value must read as syncing, not settled.
-    source.set(2)
-    yield* tick(5)
-    source.set(3)
-    const midflight = yield* until(
-      () => store.get(),
-      (v) => v._tag === 'Success' && v.value === 4,
-    )
-    expect(midflight).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
-
-    const settled = yield* until(
-      () => store.get(),
-      (v) => v._tag === 'Success' && v.refetching === false,
-    )
-    expect(settled).toMatchObject({ _tag: 'Success', value: 6 })
-  }).pipe(Effect.provide(TestLayer))
-})
+it.live(
+  'coalesce trailing: a burst during one flight completes it and runs ONE trailing refetch',
+  () => {
+    class Count extends State.make('count', S.Number) {}
+    class Inputs extends StateGroup.make(Count) {}
+    const completed: number[] = []
+    class Doubled extends AsyncCalc.make('Doubled', {
+      inputs: [StateGroup.select(Inputs, 'count')],
+      output: S.Number,
+      alwaysOn: true,
+    }) {}
+    const gate = makeFlightGate()
+    const DoubledLive = AsyncCalc.live(Doubled, {
+      query: ({ count }) =>
+        gate.through(
+          Effect.sync(() => {
+            completed.push(count)
+            return count * 2
+          }),
+        ),
+      coalesce: 'trailing',
+    })
+    const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+    return Effect.gen(function* () {
+      const source = yield* StateGroup.select(Inputs, 'count').store
+      const store = yield* Doubled.store
+      yield* until(
+        () => store.get(),
+        (v) => v._tag === 'Success',
+      )
+      expect(completed).toEqual([1])
+
+      // Hold the `2` flight at the gate so 3 and 4 land while it is in flight.
+      yield* gate.hold
+      source.set(2)
+      yield* gate.awaitEntry(2)
+      source.set(3)
+      yield* tick(5)
+      source.set(4)
+      yield* tick(5)
+      yield* gate.release
+      const settled = yield* until(
+        () => store.get(),
+        (v) => v._tag === 'Success' && v.refetching === false && v.value === 8,
+      )
+      expect(settled).toMatchObject({ _tag: 'Success', value: 8, refetching: false })
+      expect(completed).toEqual([1, 2, 4])
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
+
+it.live(
+  'coalesce trailing: the stale settle re-flags refetching until the trailing run lands',
+  () => {
+    class Count extends State.make('count', S.Number) {}
+    class Inputs extends StateGroup.make(Count) {}
+    class Doubled extends AsyncCalc.make('Doubled', {
+      inputs: [StateGroup.select(Inputs, 'count')],
+      output: S.Number,
+      alwaysOn: true,
+    }) {}
+    const DoubledLive = AsyncCalc.live(Doubled, {
+      query: ({ count }) => Effect.succeed(count * 2).pipe(Effect.delay(Duration.millis(30))),
+      coalesce: 'trailing',
+    })
+    const TestLayer = DoubledLive.pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })))
+
+    return Effect.gen(function* () {
+      const source = yield* StateGroup.select(Inputs, 'count').store
+      const store = yield* Doubled.store
+      yield* until(
+        () => store.get(),
+        (v) => v._tag === 'Success',
+      )
+
+      source.set(2)
+      yield* tick(5)
+      source.set(3)
+      const midflight = yield* until(
+        () => store.get(),
+        (v) => v._tag === 'Success' && v.value === 4,
+      )
+      expect(midflight).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
+
+      const settled = yield* until(
+        () => store.get(),
+        (v) => v._tag === 'Success' && v.refetching === false,
+      )
+      expect(settled).toMatchObject({ _tag: 'Success', value: 6 })
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
 
 it.live('coalesce trailing: a disable while a request waits in the slot skips the run', () => {
   class Count extends State.make('count', S.Number) {}
@@ -337,12 +327,15 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
     inputs: [StateGroup.select(Inputs, 'count')],
     output: S.Number,
   }) {}
+  const gate = makeFlightGate()
   const QLive = AsyncCalc.live(Q, {
     query: ({ count }) =>
-      Effect.sync(() => {
-        completed.push(count)
-        return count * 2
-      }).pipe(Effect.delay(Duration.millis(25))),
+      gate.through(
+        Effect.sync(() => {
+          completed.push(count)
+          return count * 2
+        }),
+      ),
     disabled: ({ count }) => count < 0,
     coalesce: 'trailing',
   })
@@ -351,30 +344,37 @@ it.live('coalesce trailing: a disable while a request waits in the slot skips th
   return Effect.gen(function* () {
     const source = yield* StateGroup.select(Inputs, 'count').store
     const store = yield* Q.store
-    yield* until(() => store.get(), (v) => v._tag === 'Success')
+    yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success',
+    )
 
-    // 2 starts a flight, 3 waits in the slot, then the gate closes: the flight's
-    // stale result must not land (Idle), and the queued request must not run.
+    // 3 queues behind the held `2` flight, then the disable overtakes it: the
+    // queued run must be dropped, not executed on release.
+    yield* gate.hold
     source.set(2)
-    yield* tick(5)
+    yield* gate.awaitEntry(2)
     source.set(3)
-    yield* tick(2)
+    yield* tick(5)
     source.set(-1)
+    yield* tick(5)
+    yield* gate.release
+    // Asserting an absence: give the consumer a real window to wake and (wrongly)
+    // run the queued key. A slow machine only widens the window, never narrows it.
     yield* tick(60)
     expect(store.get()._tag).toBe('Idle')
     expect(completed).toEqual([1, 2])
 
-    // Re-enabling re-runs (the driver forgot its key when switched off).
     source.set(5)
-    const settled = yield* until(() => store.get(), (v) => v._tag === 'Success')
+    const settled = yield* until(
+      () => store.get(),
+      (v) => v._tag === 'Success',
+    )
     expect(settled).toMatchObject({ _tag: 'Success', value: 10 })
     expect(completed).toEqual([1, 2, 5])
   }).pipe(Effect.provide(TestLayer))
 })
 
-// `invalidateOn` is sugar for a hidden revision state + reducer appended to the
-// key — these proofs need the Engine (the Reducers registry + bus + drain loop).
-
 it.live('invalidateOn: dispatching a listed event re-fetches with refetching: true', () => {
   class Count extends State.make('count', S.Number) {}
   class Inputs extends StateGroup.make(Count) {}
@@ -404,8 +404,6 @@ it.live('invalidateOn: dispatching a listed event re-fetches with refetching: tr
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: false })
     expect(runs.n).toBe(1)
 
-    // The fact lands: the hidden revision bumps, the key moves, the value is
-    // kept while the re-fetch is in flight (SWR), then settles.
     yield* Event.dispatch(Poke, {})
     yield* tick(5)
     expect(store.get()).toMatchObject({ _tag: 'Success', value: 4, refetching: true })
@@ -415,91 +413,92 @@ it.live('invalidateOn: dispatching a listed event re-fetches with refetching: tr
   }).pipe(Effect.provide(TestLayer))
 })
 
-it.live('invalidateOn: composes with invalidateBy — non-key churn stays inert, the event re-fetches', () => {
-  class Status extends State.make('status', S.String) {}
-  class Page extends State.make('page', S.Number) {}
-  class Inputs extends StateGroup.make(Status, Page) {}
-  class Poke extends Event.make('Poke', S.Struct({})) {}
-  const runs = { n: 0 }
-  class Q extends AsyncCalc.make('Q', {
-    inputs: [StateGroup.select(Inputs, 'status'), StateGroup.select(Inputs, 'page')],
-    output: S.Number,
-    alwaysOn: true,
-  }) {}
-  const QLive = AsyncCalc.live(Q, {
-    query: ({ page }) =>
-      Effect.sync(() => {
-        runs.n += 1
-        return page
-      }),
-    invalidateBy: ({ page }) => [page],
-    invalidateOn: [Poke],
-  })
-  const TestLayer = QLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { status: 'a', page: 1 })),
-    Layer.provideMerge(Engine),
-  )
-
-  return Effect.gen(function* () {
-    const status = yield* StateGroup.select(Inputs, 'status').store
-    yield* tick()
-    expect(runs.n).toBe(1)
-
-    // Outside the user key: still no re-fetch (the hidden revision rides along
-    // WITHOUT widening the key to every input).
-    status.set('b')
-    yield* tick()
-    expect(runs.n).toBe(1)
-
-    // The listed event always re-fetches.
-    yield* Event.dispatch(Poke, {})
-    yield* tick()
-    expect(runs.n).toBe(2)
-  }).pipe(Effect.provide(TestLayer))
-})
-
-it.live('invalidateOn: a listed event while disabled stays Idle, and enabling re-fetches once', () => {
-  class Count extends State.make('count', S.Number) {}
-  class Inputs extends StateGroup.make(Count) {}
-  class Poke extends Event.make('Poke', S.Struct({})) {}
-  const runs = { n: 0 }
-  class Q extends AsyncCalc.make('Q', {
-    inputs: [StateGroup.select(Inputs, 'count')],
-    output: S.Number,
-  }) {}
-  const QLive = AsyncCalc.live(Q, {
-    query: ({ count }) =>
-      Effect.sync(() => {
-        runs.n += 1
-        return count * 2
-      }),
-    disabled: ({ count }) => count < 0,
-    invalidateOn: [Poke],
-  })
-  const TestLayer = QLive.pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { count: -1 })),
-    Layer.provideMerge(Engine),
-  )
-
-  return Effect.gen(function* () {
-    const source = yield* StateGroup.select(Inputs, 'count').store
-    const store = yield* Q.store
-    yield* tick()
-    expect(store.get()._tag).toBe('Idle')
+it.live(
+  'invalidateOn: composes with invalidateBy — non-key churn stays inert, the event re-fetches',
+  () => {
+    class Status extends State.make('status', S.String) {}
+    class Page extends State.make('page', S.Number) {}
+    class Inputs extends StateGroup.make(Status, Page) {}
+    class Poke extends Event.make('Poke', S.Struct({})) {}
+    const runs = { n: 0 }
+    class Q extends AsyncCalc.make('Q', {
+      inputs: [StateGroup.select(Inputs, 'status'), StateGroup.select(Inputs, 'page')],
+      output: S.Number,
+      alwaysOn: true,
+    }) {}
+    const QLive = AsyncCalc.live(Q, {
+      query: ({ page }) =>
+        Effect.sync(() => {
+          runs.n += 1
+          return page
+        }),
+      invalidateBy: ({ page }) => [page],
+      invalidateOn: [Poke],
+    })
+    const TestLayer = QLive.pipe(
+      Layer.provideMerge(StateGroup.live(Inputs, { status: 'a', page: 1 })),
+      Layer.provideMerge(Engine),
+    )
 
-    // A bump while gated off runs nothing — the driver shows Idle and forgets
-    // its key, so the eventual enable always re-runs.
-    yield* Event.dispatch(Poke, {})
-    yield* tick()
-    expect(store.get()._tag).toBe('Idle')
-    expect(runs.n).toBe(0)
+    return Effect.gen(function* () {
+      const status = yield* StateGroup.select(Inputs, 'status').store
+      yield* tick()
+      expect(runs.n).toBe(1)
+
+      status.set('b')
+      yield* tick()
+      expect(runs.n).toBe(1)
+
+      yield* Event.dispatch(Poke, {})
+      yield* tick()
+      expect(runs.n).toBe(2)
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
+
+it.live(
+  'invalidateOn: a listed event while disabled stays Idle, and enabling re-fetches once',
+  () => {
+    class Count extends State.make('count', S.Number) {}
+    class Inputs extends StateGroup.make(Count) {}
+    class Poke extends Event.make('Poke', S.Struct({})) {}
+    const runs = { n: 0 }
+    class Q extends AsyncCalc.make('Q', {
+      inputs: [StateGroup.select(Inputs, 'count')],
+      output: S.Number,
+    }) {}
+    const QLive = AsyncCalc.live(Q, {
+      query: ({ count }) =>
+        Effect.sync(() => {
+          runs.n += 1
+          return count * 2
+        }),
+      disabled: ({ count }) => count < 0,
+      invalidateOn: [Poke],
+    })
+    const TestLayer = QLive.pipe(
+      Layer.provideMerge(StateGroup.live(Inputs, { count: -1 })),
+      Layer.provideMerge(Engine),
+    )
 
-    source.set(5)
-    yield* tick()
-    expect(store.get()).toMatchObject({ _tag: 'Success', value: 10 })
-    expect(runs.n).toBe(1)
-  }).pipe(Effect.provide(TestLayer))
-})
+    return Effect.gen(function* () {
+      const source = yield* StateGroup.select(Inputs, 'count').store
+      const store = yield* Q.store
+      yield* tick()
+      expect(store.get()._tag).toBe('Idle')
+
+      yield* Event.dispatch(Poke, {})
+      yield* tick()
+      expect(store.get()._tag).toBe('Idle')
+      expect(runs.n).toBe(0)
+
+      source.set(5)
+      yield* tick()
+      expect(store.get()).toMatchObject({ _tag: 'Success', value: 10 })
+      expect(runs.n).toBe(1)
+    }).pipe(Effect.provide(TestLayer))
+  },
+)
 
 it.live('invalidateOn: two async calcs keep independent hidden revisions', () => {
   class Count extends State.make('count', S.Number) {}
@@ -534,17 +533,12 @@ it.live('invalidateOn: two async calcs keep independent hidden revisions', () =>
         }),
       invalidateOn: [PokeB],
     }),
-  ).pipe(
-    Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })),
-    Layer.provideMerge(Engine),
-  )
+  ).pipe(Layer.provideMerge(StateGroup.live(Inputs, { count: 1 })), Layer.provideMerge(Engine))
 
   return Effect.gen(function* () {
     yield* tick()
     expect(runs).toEqual({ a: 1, b: 1 })
 
-    // Each calc's hidden revision is namespaced by its own name: A's fact moves
-    // only A.
     yield* Event.dispatch(PokeA, {})
     yield* tick()
     expect(runs).toEqual({ a: 2, b: 1 })