@playfast/reform 0.0.7 → 0.0.8

package/src/reducer/reducer.ts

@@ -0,0 +1,137 @@
+import { Effect, Layer } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { AsyncReducer } from '../internal/errors'
+import { type AnyEvent, type EventType } from '../event/event'
+import type { Store } from '../internal/store'
+import { type AnyState, type StateValue } from '../state/state'
+import {
+  type AnyFamily,
+  type FamilyKey,
+  type FamilyStore,
+  type FamilyValue,
+  Tombstone,
+} from '../state/stateFamily'
+import { narrowHandled, type Tagged } from '../runtime/bus'
+import { type ReducerEntry, Reducers } from '../runtime/loop'
+
+/** The reflectable descriptor a reducer carries, like every other primitive's `*Manifest`. */
+export interface ReducerManifest extends Manifest {
+  readonly kind: 'Reducer'
+}
+
+export interface StateReducerConfig<S extends AnyState, Events extends ReadonlyArray<AnyEvent>> {
+  readonly states: readonly [S]
+  readonly events: Events
+}
+
+export interface FamilyReducerConfig<F extends AnyFamily, Events extends ReadonlyArray<AnyEvent>> {
+  readonly family: F
+  readonly keyOf: (event: EventType<Events[number]>) => FamilyKey<F>
+  readonly events: Events
+}
+
+export interface StateReducerClass<S extends AnyState, Events extends ReadonlyArray<AnyEvent>> {
+  new (): {}
+  readonly manifest: ReducerManifest
+  /** Marker data read by `Reducer.live`. */
+  readonly config: StateReducerConfig<S, Events>
+  readonly handles: ReadonlySet<string>
+}
+
+export interface FamilyReducerClass<F extends AnyFamily, Events extends ReadonlyArray<AnyEvent>> {
+  new (): {}
+  readonly manifest: ReducerManifest
+  readonly config: FamilyReducerConfig<F, Events>
+  readonly handles: ReadonlySet<string>
+}
+
+/**
+ * Reducers are the only writers of state. The *definition* (`Reducer.make`)
+ * declares which state and events it touches; the *implementation*
+ * (`Reducer.live`) is the pure fold. An unhandled event is a no-op because
+ * it is never in `handles`.
+ */
+export function make<S extends AnyState, const Events extends ReadonlyArray<AnyEvent>>(
+  name: string,
+  config: StateReducerConfig<S, Events>,
+): StateReducerClass<S, Events>
+export function make<F extends AnyFamily, const Events extends ReadonlyArray<AnyEvent>>(
+  name: string,
+  config: FamilyReducerConfig<F, Events>,
+): FamilyReducerClass<F, Events>
+export function make(
+  name: string,
+  config:
+    | StateReducerConfig<AnyState, ReadonlyArray<AnyEvent>>
+    | FamilyReducerConfig<AnyFamily, ReadonlyArray<AnyEvent>>,
+): unknown {
+  return definitionClass<unknown>({
+    manifest: { kind: 'Reducer' as const, name } satisfies ReducerManifest,
+    config,
+    handles: new Set(config.events.map((e) => e.tag)),
+  })
+}
+
+/** 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') {
+    throw new AsyncReducer()
+  }
+  return value
+}
+
+export function live<S extends AnyState, Events extends ReadonlyArray<AnyEvent>>(
+  reducer: StateReducerClass<S, Events>,
+  fold: (value: StateValue<S>, event: EventType<Events[number]>) => StateValue<S>,
+): Layer.Layer<never, never, Reducers | Store<StateValue<S>>>
+export function live<F extends AnyFamily, Events extends ReadonlyArray<AnyEvent>>(
+  reducer: FamilyReducerClass<F, Events>,
+  fold: (entry: FamilyValue<F>, event: EventType<Events[number]>) => FamilyValue<F> | Tombstone,
+): Layer.Layer<never, never, Reducers | FamilyStore<FamilyKey<F>, FamilyValue<F>>>
+export function live(
+  reducer:
+    | StateReducerClass<AnyState, ReadonlyArray<AnyEvent>>
+    | FamilyReducerClass<AnyFamily, ReadonlyArray<AnyEvent>>,
+  fold: (acc: any, event: any) => any,
+): Layer.Layer<never, never, any> {
+  const { config, handles } = reducer
+  const name = reducer.manifest.name
+  // Scoped registration: register on build, unregister on scope close. For an eager
+  // app the scope is the root runtime's (closes only at dispose), so behavior is
+  // unchanged; for a lazy feature the scope is the feature's, so unmount removes the
+  // entry — it stops folding and is reclaimed instead of leaking onto a dead store.
+  return Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const reducers = yield* Reducers
+      if (reducers.entries.some((e) => e.name === name)) {
+        yield* Effect.logWarning(`reform: duplicate reducer name '${name}' registered`)
+      }
+      const entry: ReducerEntry = yield* Effect.gen(function* () {
+        if ('family' in config) {
+          const family = yield* config.family.store
+          return {
+            name,
+            handles,
+            apply: (event: Tagged) => {
+              // The loop only invokes `apply` for events in `handles`, so `event`
+              // is one of this reducer's declared events; `narrowHandled` restores
+              // that typed view from the erased `Tagged` envelope `keyOf` is fed.
+              const key = config.keyOf(narrowHandled(event))
+              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))
+            },
+          }
+        }
+        const store = yield* config.states[0].store
+        return { name, handles, apply: (event: Tagged) => store.set(sync(fold(store.get(), event))) }
+      })
+      yield* Effect.acquireRelease(Effect.sync(() => reducers.register(entry)), () =>
+        Effect.sync(() => reducers.unregister(entry)),
+      )
+    }),
+  )
+}