@playfast/reform 0.1.0 → 1.1.1

package/src/remote/remoteState.test.ts

@@ -1,11 +1,13 @@
 import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, Match, Option, Schema as S } from 'effect'
 import {
+  Channel,
   Channels,
   Engine,
   Event,
   Procedures,
   QueryStore,
+  Procedure,
   Reducer,
   Reducers,
   RemoteState,
@@ -13,17 +15,9 @@ import {
   StateGroup,
 } from '../index'
 
-// RemoteState is server-owned state with optimistic mutations as one primitive:
-// visible = pending.reduce(apply, serverTruth). Dispatching an intent event is
-// the only write surface; a settled or failed intent leaves the queue and the
-// derivation converges. The headline guarantee is the GENERATION RULE: an
-// intent acked at query-run generation g settles only on a Success run with a
-// later generation — the optimistic change never flickers out mid-convergence.
-
 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.
+// Bounded poll — fixed tick budgets flake under parallel-suite host load
 const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.Effect<A> =>
   Effect.suspend(() => {
     const a = read()
@@ -32,8 +26,6 @@ const until = <A>(read: () => A, pred: (a: A) => boolean, rounds = 200): Effect.
       : Effect.flatMap(tick(10), () => until(read, pred, rounds - 1))
   })
 
-// ── Shared fixture: a tiny mutable item server. ─────────────────────────────
-
 const Item = S.Struct({ id: S.String, name: S.String })
 type Item = typeof Item.Type
 
@@ -41,8 +33,7 @@ class Added extends Event.make('Added', S.Struct({ id: S.String, name: S.String
 class Renamed extends Event.make('Renamed', S.Struct({ id: S.String, name: S.String })) {}
 type Intent = Event.EventType<typeof Added> | Event.EventType<typeof Renamed>
 
-// The per-intent fold — idempotent against truth that already carries the
-// intent (an add whose id landed is skipped; a rename converges naturally).
+// apply must be idempotent against truth that already carries the intent
 const applyIntent = (items: ReadonlyArray<Item>, intent: Intent): ReadonlyArray<Item> =>
   Match.value(intent).pipe(
     Match.tag('Added', ({ id, name }) =>
@@ -54,8 +45,7 @@ const applyIntent = (items: ReadonlyArray<Item>, intent: Intent): ReadonlyArray<
     Match.exhaustive,
   )
 
-// A server double whose query SNAPSHOTS state at request arrival (like a real
-// DB read) and whose send applies the mutation right before acking.
+// Query snapshots at request arrival; send mutates then acks
 const makeServer = (initial: ReadonlyArray<Item>) => {
   const state = { items: initial, fetches: 0 }
   return {
@@ -75,8 +65,6 @@ const makeServer = (initial: ReadonlyArray<Item>) => {
   }
 }
 
-// An in-memory QueryStore (the reform-side double — stores the encoded value
-// directly, no envelope), so RemoteState persistence is exercised with no DOM.
 const fakeQueryStore = (seed: Record<string, unknown> = {}) => {
   const map = new Map<string, unknown>(Object.entries(seed))
   const layer = Layer.succeed(QueryStore, {
@@ -88,6 +76,85 @@ const fakeQueryStore = (seed: Record<string, unknown> = {}) => {
   return { map, layer }
 }
 
+it.live('settled dispatches after Success is committed to truth', () => {
+  class Page extends State.make('settled-success-page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  class QuerySettled extends Event.make('SettledSuccessQuerySettled', S.Struct({})) {}
+  class Items extends RemoteState.make('SettledSuccessItems', {
+    inputs: [StateGroup.select(Inputs, 'settled-success-page')],
+    output: S.Array(Item),
+    intents: [],
+    alwaysOn: true,
+  }) {}
+  class Lane extends Channel.make('SettledSuccessLane', { policy: { _tag: 'merge' } }) {}
+  class Observe extends Procedure.make('SettledSuccessObserve', {
+    events: [QuerySettled],
+    channel: Lane,
+  }) {}
+
+  const observed: Array<string> = []
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => Effect.as(tick(5), [{ id: 'a', name: 'alpha' }]),
+    send: () => Effect.void,
+    apply: (items) => items,
+    settled: { event: QuerySettled, payload: () => ({}) },
+  })
+  const ObserveLive = Procedure.live(Observe, function* () {
+    const truth = yield* Items.truth
+    observed.push(truth._tag)
+  })
+  const TestLayer = Layer.merge(ObserveLive, Channel.live(Lane)).pipe(
+    Layer.provideMerge(ItemsLive),
+    Layer.provideMerge(StateGroup.live(Inputs, { 'settled-success-page': 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* until(() => observed, (values) => values.length === 1)
+    expect(observed).toEqual(['Success'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('settled dispatches after Error is committed to truth', () => {
+  class Page extends State.make('settled-error-page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  class QuerySettled extends Event.make('SettledErrorQuerySettled', S.Struct({})) {}
+  class Items extends RemoteState.make('SettledErrorItems', {
+    inputs: [StateGroup.select(Inputs, 'settled-error-page')],
+    output: S.Array(Item),
+    error: S.String,
+    intents: [],
+    alwaysOn: true,
+  }) {}
+  class Lane extends Channel.make('SettledErrorLane', { policy: { _tag: 'merge' } }) {}
+  class Observe extends Procedure.make('SettledErrorObserve', {
+    events: [QuerySettled],
+    channel: Lane,
+  }) {}
+
+  const observed: Array<string> = []
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => Effect.zipRight(tick(5), Effect.fail('offline')),
+    send: () => Effect.void,
+    apply: (items) => items,
+    settled: { event: QuerySettled, payload: () => ({}) },
+  })
+  const ObserveLive = Procedure.live(Observe, function* () {
+    const truth = yield* Items.truth
+    observed.push(truth._tag)
+  })
+  const TestLayer = Layer.merge(ObserveLive, Channel.live(Lane)).pipe(
+    Layer.provideMerge(ItemsLive),
+    Layer.provideMerge(StateGroup.live(Inputs, { 'settled-error-page': 1 })),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    yield* until(() => observed, (values) => values.length === 1)
+    expect(observed).toEqual(['Error'])
+  }).pipe(Effect.provide(TestLayer))
+})
+
 it.live('an intent overlays instantly — no fetch fired, truth untouched', () => {
   class Page extends State.make('page', S.Number) {}
   class Inputs extends StateGroup.make(Page) {}
@@ -100,7 +167,6 @@ it.live('an intent overlays instantly — no fetch fired, truth untouched', () =
   }) {}
   const ItemsLive = RemoteState.live(Items, {
     query: () => server.fetch(5),
-    // Slow send: the pure-optimistic window stays open for the assertions.
     send: (intent) => server.receive(intent, 80),
     apply: applyIntent,
   })
@@ -116,7 +182,6 @@ it.live('an intent overlays instantly — no fetch fired, truth untouched', () =
     yield* until(() => store.get(), (v) => v._tag === 'Success')
     expect(server.state.fetches).toBe(1)
 
-    // Dispatch the intent: the overlay shows it before the RPC or any refetch.
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     const optimistic = yield* until(
       () => store.get(),
@@ -126,7 +191,6 @@ it.live('an intent overlays instantly — no fetch fired, truth untouched', () =
       expect(optimistic.value[1]).toEqual({ id: 'b', name: 'beta' })
     }
     expect(queue.get()).toMatchObject([{ status: 'sending' }])
-    // Nothing remote happened yet: one fetch ever, truth still one row.
     expect(server.state.fetches).toBe(1)
     expect(truth.get()).toMatchObject({ _tag: 'Success' })
     const t = truth.get()
@@ -159,17 +223,14 @@ it.live('convergence: the send acks, the refetch lands, the queue drains — and
     const queue = yield* Items.pending.store
     yield* until(() => store.get(), (v) => v._tag === 'Success')
 
-    // FLICKER GUARD: log every Success frame from dispatch to convergence; the
-    // row must be present in all of them (the old settle-on-ack idiom fails
-    // this — the row vanished between the RPC response and the refetch landing).
+    // Flicker guard: once optimistic row appears, no later Success frame may lack it
     const frames: Array<number> = []
     const off = store.subscribe(() => {
       const v = store.get()
       if (v._tag === 'Success') frames.push(v.value.length)
     })
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
-    // Dispatch routes through the bus: wait for the entry to LAND before
-    // waiting for it to leave (an empty read here would be vacuous).
+    // Wait for queue entry to land before waiting for settle (empty would be vacuous)
     yield* until(() => queue.get(), (q) => q.length === 1)
     yield* until(() => queue.get(), (q) => q.length === 0)
     off()
@@ -202,14 +263,11 @@ it.live('THE GENERATION RULE: a refetch that started before the ack can never se
     alwaysOn: true,
   }) {}
   const ItemsLive = RemoteState.live(Items, {
-    // Slow query: its snapshot is taken at request arrival, so a run started
-    // before the send acks carries truth WITHOUT the mutation.
     query: () => server.fetch(60),
     send: (intent) => server.receive(intent, 15),
     apply: applyIntent,
     invalidateOn: [Poke],
-    // Trailing: the pre-ack run completes and LANDS (switch would cancel it),
-    // which is exactly the stale-Success the rule must refuse to settle on.
+    // Trailing lets pre-ack run land — stale Success must not settle
     coalesce: 'trailing',
   })
   const TestLayer = ItemsLive.pipe(
@@ -229,15 +287,11 @@ it.live('THE GENERATION RULE: a refetch that started before the ack can never se
       if (v._tag === 'Success') frames.push(v.value.length)
     })
 
-    // A refetch starts (generation 2, snapshot WITHOUT the row)…
     yield* Event.dispatch(Poke, {})
     yield* tick(5)
-    // …and the intent is dispatched + acked while it is still in flight. The
-    // ack registers a waiter for generation 3 and queues the trailing refetch.
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
 
-    // The stale run (gen 2) lands its Success. The rule: it settles NOBODY —
-    // the entry stays pending and the overlay keeps the row over stale truth.
+    // Gen-2 Success settles nobody (generation rule)
     yield* until(() => server.state.fetches, (n) => n === 2)
     yield* tick(25)
     expect(queue.get()).toHaveLength(1)
@@ -246,13 +300,9 @@ it.live('THE GENERATION RULE: a refetch that started before the ack can never se
     expect(midflight).toMatchObject({ _tag: 'Success' })
     if (midflight._tag === 'Success') expect(midflight.value).toHaveLength(2)
 
-    // The post-ack run (gen 3) lands with the mutation: NOW the entry settles.
     yield* until(() => queue.get(), (q) => q.length === 0)
     off()
     expect(server.state.fetches).toBe(3)
-    // The frames before the intent legitimately show one row (the Poke refetch
-    // flips `refetching` and notifies). The flicker property is: once the
-    // optimistic row APPEARS, no later frame may lack it.
     const firstOptimistic = frames.indexOf(2)
     expect(firstOptimistic).toBeGreaterThanOrEqual(0)
     expect(frames.slice(firstOptimistic).every((n) => n === 2)).toBe(true)
@@ -282,7 +332,6 @@ it.live('a failed send settles the intent, reverts the overlay, and Failed reach
     send: () => Effect.fail('rejected' as const).pipe(Effect.delay(Duration.millis(15))),
     apply: applyIntent,
   })
-  // The toast/retry seam: an ordinary reducer on the public Failed event.
   const LogReducer = Reducer.make('failLog', { states: [FailLog], events: [Items.Failed] })
   const TestLayer = Layer.mergeAll(
     ItemsLive,
@@ -303,8 +352,6 @@ it.live('a failed send settles the intent, reverts the overlay, and Failed reach
     yield* until(() => store.get(), (v) => v._tag === 'Success' && v.value.length === 2)
     expect(queue.get()).toHaveLength(1)
 
-    // The send fails: entry leaves the queue, the view reverts by construction,
-    // and the Failed payload carried the intent + the error.
     yield* until(() => queue.get(), (q) => q.length === 0)
     const reverted = yield* until(
       () => store.get(),
@@ -315,7 +362,6 @@ it.live('a failed send settles the intent, reverts the overlay, and Failed reach
     }
     yield* until(() => log.get(), (l) => l.length === 1)
     expect(log.get()).toEqual(['Added|rejected'])
-    // No invalidation on failure: the one boot fetch is still the only one.
     expect(server.state.fetches).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -345,8 +391,7 @@ it.live('two intents apply in dispatch order and settle together on the post-ack
     const queue = yield* Items.pending.store
     yield* until(() => store.get(), (v) => v._tag === 'Success')
 
-    // Order matters: the rename targets the row the add creates. Reversed
-    // application would rename nothing and show 'beta'.
+    // Apply order = dispatch order
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* Event.dispatch(Renamed, { id: 'b', name: 'BETA' })
     yield* until(() => queue.get(), (q) => q.length === 2)
@@ -382,8 +427,6 @@ it.live('one intent failing leaves the other pending and converging', () => {
   }) {}
   const ItemsLive = RemoteState.live(Items, {
     query: () => server.fetch(10),
-    // The rename is rejected; the add is much slower and succeeds — so the
-    // partial state (one failed, one in flight) is observable.
     send: (intent) =>
       intent._tag === 'Renamed'
         ? Effect.fail('rejected' as const).pipe(Effect.delay(Duration.millis(50)))
@@ -402,14 +445,12 @@ it.live('one intent failing leaves the other pending and converging', () => {
 
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* Event.dispatch(Renamed, { id: 'a', name: 'ALPHA' })
-    // Both folded: the overlay shows the rename optimistically.
     yield* until(
       () => store.get(),
       (v) => v._tag === 'Success' && v.value[0]?.name === 'ALPHA',
     )
     expect(queue.get()).toHaveLength(2)
 
-    // The rename fails and leaves; the add stays optimistic and intact.
     yield* until(
       () => store.get(),
       (v) => v._tag === 'Success' && v.value[0]?.name === 'alpha',
@@ -424,7 +465,6 @@ it.live('one intent failing leaves the other pending and converging', () => {
       ])
     }
 
-    // The add converges independently.
     yield* until(() => queue.get(), (q) => q.length === 0)
     const settled = yield* until(
       () => store.get(),
@@ -450,7 +490,6 @@ it.live("pending exposes the lifecycle: 'sending' -> 'confirmed' -> gone", () =>
     alwaysOn: true,
   }) {}
   const ItemsLive = RemoteState.live(Items, {
-    // A slow refetch keeps the 'confirmed' window wide enough to observe.
     query: () => server.fetch(40),
     send: (intent) => server.receive(intent, 40),
     apply: applyIntent,
@@ -507,8 +546,7 @@ it.live('gated: intents queue and send while Idle; re-enabling converges and set
     yield* tick()
     expect(store.get()._tag).toBe('Idle')
 
-    // The intent still sends while the query is gated off: the server takes
-    // the mutation, but the view stays Idle and the entry waits for a run.
+    // Intents still send while gated Idle; settle waits for re-enable
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* until(() => server.state.items, (items) => items.length === 2)
     yield* tick(20)
@@ -516,7 +554,6 @@ it.live('gated: intents queue and send while Idle; re-enabling converges and set
     expect(queue.get()).toHaveLength(1)
     expect(server.state.fetches).toBe(0)
 
-    // Re-enable: the run lands with the mutation and settles the waiter.
     source.set(1)
     yield* until(() => queue.get(), (q) => q.length === 0)
     const settled = yield* until(
@@ -546,7 +583,6 @@ it.live('reuse: untouched element identities survive the whole optimistic round-
     alwaysOn: true,
   }) {}
   const ItemsLive = RemoteState.live(Items, {
-    // Fresh objects every fetch — only `reuse` can preserve identities.
     query: () => Effect.map(server.fetch(10), (items) => items.map((item) => ({ ...item }))),
     send: (intent) => server.receive(intent, 10),
     apply: applyIntent,
@@ -572,8 +608,6 @@ it.live('reuse: untouched element identities survive the whole optimistic round-
       (v) => v._tag === 'Success' && v.refetching === false,
     )
     if (settled._tag !== 'Success') return
-    // Row a was never touched: same identity through the overlay recompute AND
-    // the convergence refetch. Row b moved: fresh.
     expect(settled.value[0]).toBe(untouched)
     expect(settled.value[1]).not.toBe(first.value[1])
     expect(settled.value[1]).toEqual({ id: 'b', name: 'BETA' })
@@ -609,11 +643,9 @@ it.live('invalidateOn + coalesce trailing compose with the mutation lifecycle',
     yield* until(() => store.get(), (v) => v._tag === 'Success')
     expect(server.state.fetches).toBe(1)
 
-    // A realtime push refetches like any invalidateOn event.
     yield* Event.dispatch(BoardChanged, {})
     yield* until(() => server.state.fetches, (n) => n === 2)
 
-    // The mutation lifecycle still converges under trailing conciliation.
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* until(() => queue.get(), (q) => q.length === 1)
     yield* until(() => queue.get(), (q) => q.length === 0)
@@ -657,9 +689,7 @@ it.live('a query Error passes through by reference with intents still pending',
     const queue = yield* Items.pending.store
     yield* until(() => store.get(), (v) => v._tag === 'Error')
 
-    // The send succeeds and invalidates, but every run lands Error: an Error
-    // run settles NOBODY, so the entry stays pending (confirmed) — and the
-    // overlay passes the Error arm through by reference, never applying.
+    // Error runs settle nobody; overlay passes Error through without apply
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* until(() => queue.get(), (q) => q.length === 1 && q[0]?.status === 'confirmed')
     yield* until(() => store.get(), (v) => v._tag === 'Error' && v.refetching === false)
@@ -700,7 +730,6 @@ it.live('teardown: closing the scope unregisters the reducers, the procedure, an
       }),
     )
 
-    // Scope closed: every registration is gone (a lazy feature unmounting).
     expect(reducers.entries.some((entry) => entry.name === 'Items/pending')).toBe(false)
     expect(reducers.entries.some((entry) => entry.name === 'Items/revision')).toBe(false)
     expect(procedures.entries.some((entry) => entry.name === 'Items/send')).toBe(false)
@@ -708,7 +737,6 @@ it.live('teardown: closing the scope unregisters the reducers, the procedure, an
   }).pipe(Effect.provide(Engine))
 })
 
-// ── persist (00b/00c): the converged truth round-trips a QueryStore. ─────────
 
 it.live('persist: hydrates the seeded truth (stale) then writes the fresh truth through', () => {
   class Page extends State.make('page', S.Number) {}
@@ -735,12 +763,10 @@ it.live('persist: hydrates the seeded truth (stale) then writes the fresh truth
 
   return Effect.gen(function* () {
     const view = yield* Items.store
-    // The persisted truth shows instantly, marked refetching (stale-while-revalidate).
     const hydrated = view.get()
     expect(hydrated).toMatchObject({ _tag: 'Success', refetching: true })
     if (hydrated._tag === 'Success') expect(hydrated.value).toEqual([{ id: 'seed', name: 'seeded' }])
 
-    // The fresh fetch lands and the converged truth is written through under the name key.
     const settled = yield* until(
       () => view.get(),
       (v) => v._tag === 'Success' && v.refetching === false,
@@ -767,7 +793,6 @@ it.live('persist: the optimistic overlay is NEVER written — only the converged
   }) {}
   const ItemsLive = RemoteState.live(Items, {
     query: () => server.fetch(10),
-    // Slow send so the pure-optimistic window stays open for the store assertion.
     send: (intent) => server.receive(intent, 60),
     apply: applyIntent,
     persist: true,
@@ -782,17 +807,14 @@ it.live('persist: the optimistic overlay is NEVER written — only the converged
     const view = yield* Items.store
     const queue = yield* Items.pending.store
     yield* until(() => view.get(), (v) => v._tag === 'Success')
-    // First truth is persisted.
     yield* until(() => store.map.get('Items'), (v) => Array.isArray(v) && v.length === 1)
 
-    // Dispatch the optimistic intent: the overlay shows two rows...
     yield* Event.dispatch(Added, { id: 'b', name: 'beta' })
     yield* until(() => view.get(), (v) => v._tag === 'Success' && v.value.length === 2)
     yield* until(() => queue.get(), (q) => q.length === 1)
-    // ...but the store still holds the PRE-mutation truth (no overlay write).
+    // Persist never captures overlay — only settled server truth
     expect(store.map.get('Items')).toEqual([{ id: 'a', name: 'alpha' }])
 
-    // Once the send acks and the refetch lands, the converged truth is written.
     yield* until(() => queue.get(), (q) => q.length === 0)
     yield* until(
       () => store.map.get('Items'),
@@ -837,7 +859,6 @@ it.live('persist: `true` keys by name; `{ key }` overrides — two definitions k
     yield* until(() => store.map.get('custom-B'), (v) => Array.isArray(v))
     expect(store.map.get('ItemsA')).toEqual([{ id: 'a', name: 'alpha' }])
     expect(store.map.get('custom-B')).toEqual([{ id: 'b', name: 'beta' }])
-    // No collision: neither wrote the other's key, and the name key for B is empty.
     expect(store.map.has('ItemsB')).toBe(false)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -847,8 +868,6 @@ it.live('persist (00c): a function key keys a family per-input — two input key
   class Inputs extends StateGroup.make(Page) {}
   const inputs = StateGroup.live(Inputs, { page: 1 })
   const store = fakeQueryStore()
-  // The server returns a distinct row per requested page, so a collision (one
-  // slot for both pages) would overwrite — the assertion catches it.
   const fetchPage = (page: number) =>
     Effect.as(tick(10), [{ id: `p${page}`, name: `page-${page}` }])
   class Fam extends RemoteState.make('Fam', {
@@ -871,12 +890,10 @@ it.live('persist (00c): a function key keys a family per-input — two input key
     yield* until(() => store.map.get('fam:1'), (v) => Array.isArray(v))
     expect(store.map.get('fam:1')).toEqual([{ id: 'p1', name: 'page-1' }])
 
-    // Move the input to page 2: a new fetch writes to a DISTINCT slot.
     page.set(2)
     yield* until(() => view.get(), (v) => v._tag === 'Success' && v.value[0]?.id === 'p2')
     yield* until(() => store.map.get('fam:2'), (v) => Array.isArray(v))
     expect(store.map.get('fam:2')).toEqual([{ id: 'p2', name: 'page-2' }])
-    // Page 1's slot is intact — no collision.
     expect(store.map.get('fam:1')).toEqual([{ id: 'p1', name: 'page-1' }])
   }).pipe(Effect.provide(TestLayer))
 })