@playfast/reform 0.0.10 → 0.1.0

package/src/internal/scheduler.ts

@@ -19,34 +19,46 @@ export const makeScheduler = (): Scheduler => {
   const pending = new Set<() => void>()
   const armed = MutableRef.make(false)
 
+  // One listener's throw (a defect in a user calc body) must not abandon the
+  // rest of the flush; surface it to the host's global handler on a fresh
+  // microtask instead of unwinding the drain.
+  const runListener = (listener: () => void): void =>
+    Effect.runSync(
+      Effect.try({ try: listener, catch: (error) => error }).pipe(
+        Effect.catchAll((error) =>
+          Effect.sync(() =>
+            queueMicrotask(() => {
+              // oxlint-disable-next-line reform-rules/no-throw -- only way to surface a listener defect to the host's global error handler
+              throw error
+            }),
+          ),
+        ),
+      ),
+    )
+
+  // Drain to a fixpoint within ONE microtask. A derived store's `onChange`
+  // re-schedules during the pass (it is itself a listener of its upstream), so
+  // resolving the whole dependency graph here — instead of re-arming a fresh
+  // microtask per layer — collapses a depth-N propagation into a single flush
+  // and wakes each leaf subscriber once at its final value. Converges because
+  // a derived store schedules only when its output actually moves (Equal).
+  const drain = (): void => {
+    if (pending.size === 0) {
+      return
+    }
+    const due = [...pending]
+    pending.clear()
+    due.forEach(runListener)
+    drain()
+  }
+
   const flush = () => {
     MutableRef.set(armed, false)
-    // Drain to a fixpoint within ONE microtask. A derived store's `onChange`
-    // re-schedules during the pass (it is itself a listener of its upstream), so
-    // resolving the whole dependency graph here — instead of re-arming a fresh
-    // microtask per layer — collapses a depth-N propagation into a single flush
-    // and wakes each leaf subscriber once at its final value. Converges because
-    // a derived store schedules only when its output actually moves (Equal).
-    while (pending.size > 0) {
-      const due = [...pending]
-      pending.clear()
-      for (const listener of due) {
-        // One listener's throw (a defect in a user calc body) must not abandon
-        // the rest of the flush; surface it to the host's global handler on a
-        // fresh microtask instead of unwinding this loop.
-        try {
-          listener()
-        } catch (error) {
-          queueMicrotask(() => {
-            throw error
-          })
-        }
-      }
-    }
+    drain()
   }
 
   const schedule = (listeners: Iterable<() => void>) => {
-    for (const listener of listeners) pending.add(listener)
+    ;[...listeners].forEach((listener) => pending.add(listener))
     if (pending.size > 0 && !MutableRef.get(armed)) {
       MutableRef.set(armed, true)
       queueMicrotask(flush)

package/src/internal/sources.ts

@@ -52,8 +52,8 @@ const inputKey = (input: AnySource): string =>
     : input.name
 
 /** Element-wise value equality of two invalidation keys. */
-export const sameKey = (a: ReadonlyArray<unknown>, b: ReadonlyArray<unknown>): boolean =>
-  a.length === b.length && a.every((value, i) => Equal.equals(value, b[i]))
+export const sameKey = (left: ReadonlyArray<unknown>, right: ReadonlyArray<unknown>): boolean =>
+  left.length === right.length && left.every((element, index) => Equal.equals(element, right[index]))
 
 /** The sensing surface both `Calc.live` and `AsyncCalc.live` build on. */
 export interface WiredSources<Inputs extends ReadonlyArray<AnySource>> {
@@ -74,18 +74,24 @@ export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
   inputs: Inputs,
   invalidateBy?: InvalidateBy<Inputs>,
 ): Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>> =>
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- restate the precise InputStores<Inputs> union the signature promises; Effect.forEach over a heterogeneous tuple widens R (the single seam this cast lives at)
   Effect.gen(function* () {
-    const sources: Array<Store<unknown>> = []
-    for (const input of inputs) sources.push(yield* input.store)
+    const sources: ReadonlyArray<Store<unknown>> = yield* Effect.forEach(
+      inputs,
+      (input) => input.store,
+    )
 
     const snapshot = (): InputsObject<Inputs> => {
       const args: Record<string, unknown> = {}
-      inputs.forEach((input, i) => {
+      inputs.forEach((input, index) => {
         // `noUncheckedIndexedAccess`: `sources` is built 1:1 with `inputs`, but
         // guard the index so the read is honestly total.
-        const source = sources[i]
-        if (source !== undefined) args[inputKey(input)] = source.getSnapshot()
+        const source = sources[index]
+        if (source !== undefined) {
+          args[inputKey(input)] = source.getSnapshot()
+        }
       })
+      // oxlint-disable-next-line reform-rules/no-type-assertion -- `args` is built by reflection over input names; this restates the InputsObject mapped-type shape
       return args as InputsObject<Inputs>
     }
     const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
@@ -93,7 +99,7 @@ export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
     const subscribe = (listener: () => void): (() => void) => {
       const unsubscribes = sources.map((source) => source.subscribe(listener))
       return () => {
-        for (const unsubscribe of unsubscribes) unsubscribe()
+        unsubscribes.forEach((unsubscribe) => unsubscribe())
       }
     }
     return { snapshot, keyOf, subscribe }

package/src/internal/stateRegistry.ts

@@ -22,7 +22,9 @@ export const claimStateTag = (identifier: string): void => {
     claimed.add(identifier)
     return
   }
-  if (warned.has(identifier)) return
+  if (warned.has(identifier)) {
+    return
+  }
   warned.add(identifier)
   Effect.runSync(
     Effect.logWarning(

package/src/internal/store.ts

@@ -33,17 +33,19 @@ export interface Store<in out A> extends Inspectable {
 export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler): Store<A> => {
   // The store is a mutable reactive slot by design, so its value lives in a
   // `MutableRef` we update in place (no reassigned binding).
-  const value = MutableRef.make(initial)
+  const current = MutableRef.make(initial)
   const version = MutableRef.make(0)
   const listeners = new Set<() => void>()
   return {
-    get: () => MutableRef.get(value),
-    getSnapshot: () => MutableRef.get(value),
+    get: () => MutableRef.get(current),
+    getSnapshot: () => MutableRef.get(current),
     getVersion: () => MutableRef.get(version),
     set: (next) => {
-      if (Equal.equals(MutableRef.get(value), next)) return
-      MutableRef.set(value, next)
-      MutableRef.update(version, (n) => n + 1)
+      if (Equal.equals(MutableRef.get(current), next)) {
+        return
+      }
+      MutableRef.set(current, next)
+      MutableRef.update(version, (count) => count + 1)
       scheduler.schedule(listeners)
     },
     subscribe: (listener) => {
@@ -52,7 +54,7 @@ export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler
         listeners.delete(listener)
       }
     },
-    ...inspectable(() => ({ _id: 'reform/Store', value: MutableRef.get(value) })),
+    ...inspectable(() => ({ _id: 'reform/Store', value: MutableRef.get(current) })),
   }
 }
 
@@ -83,7 +85,7 @@ export const makeDerivedStore = <A>(
     const next = compute()
     MutableRef.set(seen, { value: next })
     if (previous === undefined || !Equal.equals(previous.value, next)) {
-      MutableRef.update(version, (n) => n + 1)
+      MutableRef.update(version, (count) => count + 1)
       scheduler.schedule(listeners)
     }
   }

package/src/internal/track.ts

@@ -34,6 +34,8 @@ export class CurrentTracker extends CurrentTrackerBase {}
  */
 export const readTracked = <A>(store: Store<A>): Effect.Effect<A> =>
   Effect.map(Effect.serviceOption(CurrentTracker), (tracker) => {
-    if (Option.isSome(tracker)) tracker.value.add(store)
+    if (Option.isSome(tracker)) {
+      tracker.value.add(store)
+    }
     return store.getSnapshot()
   })

package/src/procedure/procedure.ts

@@ -60,14 +60,14 @@ export const live = <
 ): Layer.Layer<never, never, Procedures | Bus | Ctx<Eff>> => {
   const name = procedure.manifest.name
   const channelName = procedure.channel.manifest.name
-  const handles = new Set(procedure.events.map((e) => e.tag))
+  const handles = new Set(procedure.events.map((event) => event.tag))
   // Scoped registration (see `Reducer.live`): an eager procedure's scope is the
   // root runtime's, so behavior is unchanged; a lazy feature's procedure registers
   // on mount and unregisters on unmount, so it stops running and is reclaimed.
   return Layer.scopedDiscard(
     Effect.gen(function* () {
       const procedures = yield* Procedures
-      if (procedures.entries.some((e) => e.name === name)) {
+      if (procedures.entries.some((entry) => entry.name === name)) {
         yield* Effect.logWarning(`reform: duplicate procedure name '${name}' registered`)
       }
       // Snapshot the body's full context (Bus + RPC clients) so `run` is total.

package/src/reducer/reducer.ts

@@ -1,4 +1,4 @@
-import { Effect, Layer } from 'effect'
+import { Effect, Layer, Predicate } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { AsyncReducer } from '../internal/errors'
 import { type AnyEvent, type EventType } from '../event/event'
@@ -68,17 +68,21 @@ export function make(
   return definitionClass<unknown>({
     manifest: { kind: 'Reducer' as const, name } satisfies ReducerManifest,
     config,
-    handles: new Set(config.events.map((e) => e.tag)),
+    handles: new Set(config.events.map((event) => event.tag)),
   })
 }
 
+/** A thenable check that excludes null/undefined without an assertion. */
+const isThenable = (candidate: unknown): candidate is PromiseLike<unknown> =>
+  Predicate.isRecord(candidate) && typeof candidate['then'] === 'function'
+
 /** Reject an accidentally-async fold up front: a reducer must be a pure sync write. */
-const sync = <A>(value: A): A => {
-  // Loose `!= null` so a reducer returning `undefined` doesn't crash the guard.
-  if (value != null && typeof (value as { then?: unknown }).then === 'function') {
+const sync = <A>(candidate: A): A => {
+  if (isThenable(candidate)) {
+    // oxlint-disable-next-line reform-rules/no-throw -- sync reducer-write boundary can't yield an Effect; an async fold is a programmer defect
     throw new AsyncReducer()
   }
-  return value
+  return candidate
 }
 
 export function live<S extends AnyState, Events extends ReadonlyArray<AnyEvent>>(
@@ -93,6 +97,7 @@ export function live(
   reducer:
     | StateReducerClass<AnyState, ReadonlyArray<AnyEvent>>
     | FamilyReducerClass<AnyFamily, ReadonlyArray<AnyEvent>>,
+  // oxlint-disable-next-line reform-rules/no-explicit-any-value -- overload-impl signature: `unknown` params fail contravariance against the State/Family folds (TS2394); only `any` subsumes both
   fold: (acc: any, event: any) => any,
 ): Layer.Layer<never, never, any> {
   const { config, handles } = reducer
@@ -104,7 +109,7 @@ export function live(
   return Layer.scopedDiscard(
     Effect.gen(function* () {
       const reducers = yield* Reducers
-      if (reducers.entries.some((e) => e.name === name)) {
+      if (reducers.entries.some((existing) => existing.name === name)) {
         yield* Effect.logWarning(`reform: duplicate reducer name '${name}' registered`)
       }
       const entry: ReducerEntry = yield* Effect.gen(function* () {
@@ -121,8 +126,11 @@ export function live(
               const next = fold(family.at(key).get(), event)
               // A fold may return the eviction sentinel to drop the key's store
               // (bounding an otherwise-unbounded family) instead of a new value.
-              if (next === Tombstone) family.forget(key)
-              else family.at(key).set(sync(next))
+              if (next === Tombstone) {
+                family.forget(key)
+              } else {
+                family.at(key).set(sync(next))
+              }
             },
           }
         }

package/src/remote/remoteState.test.ts

@@ -1,10 +1,11 @@
 import { expect, it } from '@effect/vitest'
-import { Duration, Effect, Layer, Match, Schema as S } from 'effect'
+import { Duration, Effect, Layer, Match, Option, Schema as S } from 'effect'
 import {
   Channels,
   Engine,
   Event,
   Procedures,
+  QueryStore,
   Reducer,
   Reducers,
   RemoteState,
@@ -74,6 +75,19 @@ 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, {
+    get: (key: string) =>
+      Effect.sync(() => Option.fromNullable(map.has(key) ? map.get(key) : undefined)),
+    set: (key: string, value: unknown) => Effect.sync(() => void map.set(key, value)),
+    remove: (key: string) => Effect.sync(() => void map.delete(key)),
+  })
+  return { map, layer }
+}
+
 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) {}
@@ -693,3 +707,176 @@ it.live('teardown: closing the scope unregisters the reducers, the procedure, an
     expect(channels.byName.has('Items/sends')).toBe(false)
   }).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) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  const store = fakeQueryStore({ Items: [{ id: 'seed', name: 'seeded' }] })
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const ItemsLive = RemoteState.live(Items, {
+    query: () => server.fetch(15),
+    send: (intent) => server.receive(intent, 15),
+    apply: applyIntent,
+    persist: true,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(store.layer),
+    Layer.provideMerge(Engine),
+  )
+
+  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,
+    )
+    if (settled._tag === 'Success') expect(settled.value).toEqual([{ id: 'a', name: 'alpha' }])
+    yield* until(
+      () => store.map.get('Items'),
+      (v) => Array.isArray(v) && v.length === 1 && v[0].id === 'a',
+    )
+    expect(store.map.get('Items')).toEqual([{ id: 'a', name: 'alpha' }])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('persist: the optimistic overlay is NEVER written — only the converged server truth is', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const server = makeServer([{ id: 'a', name: 'alpha' }])
+  const store = fakeQueryStore()
+  class Items extends RemoteState.make('Items', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  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,
+  })
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })),
+    Layer.provideMerge(store.layer),
+    Layer.provideMerge(Engine),
+  )
+
+  return Effect.gen(function* () {
+    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).
+    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'),
+      (v) => Array.isArray(v) && v.length === 2,
+    )
+    expect(store.map.get('Items')).toEqual([
+      { id: 'a', name: 'alpha' },
+      { id: 'b', name: 'beta' },
+    ])
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('persist: `true` keys by name; `{ key }` overrides — two definitions keep separate slots', () => {
+  class Page extends State.make('page', S.Number) {}
+  class Inputs extends StateGroup.make(Page) {}
+  const serverA = makeServer([{ id: 'a', name: 'alpha' }])
+  const serverB = makeServer([{ id: 'b', name: 'beta' }])
+  const store = fakeQueryStore()
+  class ItemsA extends RemoteState.make('ItemsA', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  class ItemsB extends RemoteState.make('ItemsB', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const TestLayer = Layer.mergeAll(
+    RemoteState.live(ItemsA, { query: () => serverA.fetch(10), send: (i) => serverA.receive(i, 10), apply: applyIntent, persist: true }),
+    RemoteState.live(ItemsB, { query: () => serverB.fetch(10), send: (i) => serverB.receive(i, 10), apply: applyIntent, persist: { key: 'custom-B' } }),
+  ).pipe(Layer.provideMerge(StateGroup.live(Inputs, { page: 1 })), Layer.provideMerge(store.layer), Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    const a = yield* ItemsA.store
+    const b = yield* ItemsB.store
+    yield* until(() => a.get(), (v) => v._tag === 'Success')
+    yield* until(() => b.get(), (v) => v._tag === 'Success')
+    yield* until(() => store.map.get('ItemsA'), (v) => Array.isArray(v))
+    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))
+})
+
+it.live('persist (00c): a function key keys a family per-input — two input keys, two slots, no collision', () => {
+  class Page extends State.make('page', S.Number) {}
+  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', {
+    inputs: [StateGroup.select(Inputs, 'page')],
+    output: S.Array(Item),
+    intents: [Added, Renamed],
+    alwaysOn: true,
+  }) {}
+  const FamLive = RemoteState.live(Fam, {
+    query: ({ page }) => fetchPage(page),
+    send: (i) => Effect.sync(() => void i),
+    apply: applyIntent,
+    persist: { key: ({ page }) => `fam:${page}` },
+  })
+  const TestLayer = FamLive.pipe(Layer.provideMerge(inputs), Layer.provideMerge(store.layer), Layer.provideMerge(Engine))
+
+  return Effect.gen(function* () {
+    const view = yield* Fam.store
+    const page = yield* Page.store
+    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))
+})