@playfast/reform 0.0.4 → 0.0.7

package/src/internal/scheduler.ts

@@ -1,91 +0,0 @@
-import { Context, Effect, Layer, MutableRef, Option } from 'effect'
-
-/**
- * Coalesces store notifications into a single microtask flush so a batch of
- * writes wakes each subscriber at most once (RESEARCH #3). React owns frame
- * timing; we only collapse the notifications.
- *
- * One scheduler is shared by every store in a runtime, so writes across
- * different stores in the same tick batch into one flush. The instance is
- * resolved per store at creation: `Notifications` when a runtime provides it
- * (per-runtime isolation — see `resolveScheduler`), else the process-wide
- * `defaultScheduler`.
- */
-export interface Scheduler {
-  readonly schedule: (listeners: Iterable<() => void>) => void
-}
-
-export const makeScheduler = (): Scheduler => {
-  const pending = new Set<() => void>()
-  const armed = MutableRef.make(false)
-
-  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
-          })
-        }
-      }
-    }
-  }
-
-  const schedule = (listeners: Iterable<() => void>) => {
-    for (const listener of listeners) pending.add(listener)
-    if (pending.size > 0 && !MutableRef.get(armed)) {
-      MutableRef.set(armed, true)
-      queueMicrotask(flush)
-    }
-  }
-
-  return { schedule }
-}
-
-/**
- * The process-wide scheduler, used by any store created outside a runtime that
- * provides its own `Notifications`. Fine for a single client app (microtask
- * ordering is global anyway); a runtime that needs isolation — concurrent SSR,
- * multiple mounted roots — provides `Notifications` upstream of its stores.
- */
-export const defaultScheduler: Scheduler = makeScheduler()
-
-/**
- * Optional per-runtime scheduler. When a runtime provides it upstream of its
- * state/calc layers, those stores coalesce on it instead of the global default,
- * isolating their notification timing from other runtimes in the same process.
- */
-export class Notifications extends Context.Tag('reform/Notifications')<Notifications, Scheduler>() {}
-
-/**
- * A fresh per-runtime scheduler. Merged into `Engine`, so a runtime that wires
- * its state/calc layers *downstream* of `Engine` gets isolated notification
- * timing; the common sibling wiring falls back to `defaultScheduler` (still
- * correct, just process-shared).
- */
-export const notificationsLayer: Layer.Layer<Notifications> = Layer.sync(Notifications, makeScheduler)
-
-/**
- * Resolve the scheduler a store should use: the runtime's `Notifications` if one
- * is in context, else the global default. Uses `serviceOption` so it imposes no
- * hard requirement — a store layer wired as a sibling of the runtime (the common
- * pattern) simply falls back to the default.
- */
-export const resolveScheduler: Effect.Effect<Scheduler> = Effect.map(
-  Effect.serviceOption(Notifications),
-  Option.getOrElse(() => defaultScheduler),
-)

package/src/internal/sources.ts

@@ -1,104 +0,0 @@
-import { type Context, Effect, Equal, Predicate } from 'effect'
-import { type AnySource, type SourceName, type SourceValue } from '../state/token'
-import { type Store } from './store'
-
-// The reactive plumbing shared by `Calc` and `AsyncCalc`: read a list of input
-// `Source`s, snapshot them by name, project a comparable invalidation key, and
-// subscribe to changes. Both derived primitives sense their inputs the same way
-// and differ only in what they do with a change (recompute vs. re-run a query).
-
-/** The decoded inputs handed to a calc body, keyed by each source's name. */
-export type InputsObject<Inputs extends ReadonlyArray<AnySource>> = {
-  readonly [S in Inputs[number] as SourceName<S>]: SourceValue<S>
-}
-
-/**
- * The store services a list of store-carriers requires, as a *union of distinct*
- * stores (each carrier has its own backing tag), not a single store of a union.
- * Structural over the `store` tag, so it serves both calc inputs (`Source`s) and
- * state-group members (`StateClass`es) — anything carrying a `store` tag.
- */
-export type StoresOf<Items extends ReadonlyArray<unknown>> = {
-  [I in keyof Items]: Items[I] extends { readonly store: Context.Tag<infer Svc, any> } ? Svc : never
-}[number]
-
-/** The store requirement a calc's inputs impose. */
-export type InputStores<Inputs extends ReadonlyArray<AnySource>> = StoresOf<Inputs>
-
-/** Project inputs into a comparable key; the calc reacts only when it moves. */
-export type InvalidateBy<Inputs extends ReadonlyArray<AnySource>> = (
-  inputs: InputsObject<Inputs>,
-) => ReadonlyArray<unknown>
-
-/**
- * The runtime key an input contributes to the inputs object. Prefer the
- * explicit `manifest.name` — the string handed to `make` — over the structural
- * `name`: a `Calc`/`AsyncCalc` *class* satisfies `Source` through its static
- * `name`, and a user subclass declaration (`class Feed extends Calc.make(…)`)
- * defines its OWN `name` from the class binding, shadowing the explicit one.
- * That binding is what minifiers rename, so keying the snapshot by `input.name`
- * made every subclassed calc input `undefined` in production builds (and would
- * silently mis-key in dev whenever the binding differs from the `make` name —
- * the type-level key, `SourceName<S>`, is always the `make` string). The
- * manifest is inherited through the static prototype chain and never shadowed.
- * `StateToken`s carry no manifest; their `name` is an instance field holding
- * the explicit member key, so the fallback is always the declared string.
- */
-const inputKey = (input: AnySource): string =>
-  Predicate.hasProperty(input, 'manifest') &&
-  Predicate.isRecord(input.manifest) &&
-  Predicate.isString(input.manifest.name)
-    ? input.manifest.name
-    : 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]))
-
-/** The sensing surface both `Calc.live` and `AsyncCalc.live` build on. */
-export interface WiredSources<Inputs extends ReadonlyArray<AnySource>> {
-  /** Snapshot every input by name — the decoded inputs object a calc body sees. */
-  readonly snapshot: () => InputsObject<Inputs>
-  /** The invalidation key for an inputs object: the projection, or all input values. */
-  readonly keyOf: (inputs: InputsObject<Inputs>) => ReadonlyArray<unknown>
-  /** Subscribe to every source at once; the returned thunk unsubscribes from all. */
-  readonly subscribe: (listener: () => void) => () => void
-}
-
-/**
- * Read each input's backing store and return the shared sensing surface. The
- * caller owns lifecycle: register the `subscribe` result's unsubscribe as a
- * scope finalizer (both live bodies run under `Layer.scoped`).
- */
-export const wireSources = <Inputs extends ReadonlyArray<AnySource>>(
-  inputs: Inputs,
-  invalidateBy?: InvalidateBy<Inputs>,
-): Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>> =>
-  Effect.gen(function* () {
-    const sources: Array<Store<unknown>> = []
-    for (const input of inputs) sources.push(yield* input.store)
-
-    const snapshot = (): InputsObject<Inputs> => {
-      const args: Record<string, unknown> = {}
-      inputs.forEach((input, i) => {
-        // `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()
-      })
-      return args as InputsObject<Inputs>
-    }
-    const keyOf = (args: InputsObject<Inputs>): ReadonlyArray<unknown> =>
-      invalidateBy ? invalidateBy(args) : Object.values(args)
-    const subscribe = (listener: () => void): (() => void) => {
-      const unsubscribes = sources.map((source) => source.subscribe(listener))
-      return () => {
-        for (const unsubscribe of unsubscribes) unsubscribe()
-      }
-    }
-    return { snapshot, keyOf, subscribe }
-    // Yielding each `input.store` (a `Context.Tag<Store<unknown>>`) widens the
-    // inferred requirement to `Store<unknown>`; restate the precise per-input
-    // `InputStores<Inputs>` union the signature promises. This is the single
-    // place that cast lives — `Calc.live`/`AsyncCalc.live` inherit it.
-  }) as Effect.Effect<WiredSources<Inputs>, never, InputStores<Inputs>>

package/src/internal/store.ts

@@ -1,105 +0,0 @@
-import { Equal, MutableRef } from 'effect'
-import { type Inspectable, inspectable } from './inspect'
-import { defaultScheduler, type Scheduler } from './scheduler'
-
-/**
- * A reactive cell living outside Effect. The single source of truth for one
- * slice of state. `set` is internal: only the reduce loop ever holds a Store
- * (reducers return values, the loop writes them), which is how "state changes
- * only in the reduce loop" is enforced structurally — there is no public writer.
- *
- * This is the synchronous, React-facing analog of Effect's `SubscriptionRef`
- * (a `Ref` + `PubSub` + a `changes` `Stream`). We don't use `SubscriptionRef`
- * directly because `useSyncExternalStore` requires a *synchronous* `getSnapshot`
- * and a *synchronous* `subscribe` returning an unsubscribe thunk, whereas
- * `SubscriptionRef.get` is an `Effect` and its `changes` is a `Stream` (a fiber
- * per subscription). Mutable state is held in a `MutableRef` (Effect's mutable
- * cell), so there is no reassigned binding.
- *
- * `getSnapshot` + `subscribe` are the stable pair the React bridge binds to;
- * `getSnapshot` returns the same reference until the value actually changes.
- * `getVersion` returns a monotonic counter bumped on every real change — the
- * host sums it across a render's tracked stores for a `useSyncExternalStore`
- * snapshot, which closes the tear/dropped-update window a value snapshot can't.
- */
-export interface Store<in out A> extends Inspectable {
-  get(): A
-  set(value: A): void
-  getSnapshot(): A
-  getVersion(): number
-  subscribe(listener: () => void): () => void
-}
-
-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 version = MutableRef.make(0)
-  const listeners = new Set<() => void>()
-  return {
-    get: () => MutableRef.get(value),
-    getSnapshot: () => MutableRef.get(value),
-    getVersion: () => MutableRef.get(version),
-    set: (next) => {
-      if (Equal.equals(MutableRef.get(value), next)) return
-      MutableRef.set(value, next)
-      MutableRef.update(version, (n) => n + 1)
-      scheduler.schedule(listeners)
-    },
-    subscribe: (listener) => {
-      listeners.add(listener)
-      return () => {
-        listeners.delete(listener)
-      }
-    },
-    ...inspectable(() => ({ _id: 'reform/Store', value: MutableRef.get(value) })),
-  }
-}
-
-/**
- * A read-only `Store` whose value is computed from upstream sources.
- *
- * Reads are pull-fresh: `get`/`getSnapshot` call `compute` directly, so a
- * headless snapshot always reflects the current source state without waiting for
- * a notification (`compute` must memoize so an unchanged read returns a stable
- * reference — `useSyncExternalStore` requires it). *Notifications*, by contrast,
- * run through the same coalescing scheduler as `makeStore`: an upstream change
- * recomputes once and wakes subscribers only when the output actually moves (by
- * `Equal.equals`), so every store kind shares one notification timing. `set` is
- * a no-op — the only writer is the upstream subscription.
- */
-export const makeDerivedStore = <A>(
-  compute: () => A,
-  subscribeUpstream: (onChange: () => void) => () => void,
-  scheduler: Scheduler = defaultScheduler,
-): { readonly store: Store<A>; readonly unsubscribe: () => void } => {
-  const listeners = new Set<() => void>()
-  const version = MutableRef.make(0)
-  // The last output we notified against — tracked only here, never touched by
-  // reads, so a `get` racing ahead of `onChange` can't suppress a notification.
-  const seen = MutableRef.make<{ readonly value: A } | undefined>({ value: compute() })
-  const onChange = () => {
-    const previous = MutableRef.get(seen)
-    const next = compute()
-    MutableRef.set(seen, { value: next })
-    if (previous === undefined || !Equal.equals(previous.value, next)) {
-      MutableRef.update(version, (n) => n + 1)
-      scheduler.schedule(listeners)
-    }
-  }
-  const unsubscribe = subscribeUpstream(onChange)
-  const store: Store<A> = {
-    get: compute,
-    getSnapshot: compute,
-    getVersion: () => MutableRef.get(version),
-    set: () => {},
-    subscribe: (listener) => {
-      listeners.add(listener)
-      return () => {
-        listeners.delete(listener)
-      }
-    },
-    ...inspectable(() => ({ _id: 'reform/Store', value: compute() })),
-  }
-  return { store, unsubscribe }
-}

package/src/procedure/procedure.ts

@@ -1,89 +0,0 @@
-import { Effect, Layer } from 'effect'
-import type { YieldWrap } from 'effect/Utils'
-import { type ChannelClass, type ProcedureEntry, Procedures } from '../channel/channel'
-import { type Manifest, definitionClass } from '../definition/definition'
-import { type AnyEvent, type EventType } from '../event/event'
-import { type Ctx } from '../internal/ctx'
-import { Bus, narrowHandled } from '../runtime/bus'
-
-/** The reflectable descriptor a procedure carries. */
-export interface ProcedureManifest extends Manifest {
-  readonly kind: 'Procedure'
-}
-
-export interface ProcedureClass<Events extends ReadonlyArray<AnyEvent>> {
-  new (): {}
-  readonly manifest: ProcedureManifest
-  /** The trigger events (marker data; read by `Procedure.live`). */
-  readonly events: Events
-  /** The channel this procedure's runs are scheduled on (marker data). */
-  readonly channel: ChannelClass
-}
-
-export interface ProcedureConfig<Events extends ReadonlyArray<AnyEvent>> {
-  readonly events: Events
-  /** The scheduling lane. Replaces the old `concurrency` option. */
-  readonly channel: ChannelClass
-}
-
-export type AnyProcedure = ProcedureClass<ReadonlyArray<AnyEvent>>
-
-/**
- * A cross-event-loop flow. The *definition* declares its trigger events and the
- * channel it runs on; the *implementation* is the effectful body. Procedures no
- * longer subscribe to the bus themselves — the single drain loop routes events
- * to the channel, which runs the registered bodies under its policy.
- */
-export const make = <const Events extends ReadonlyArray<AnyEvent>>(
-  name: string,
-  config: ProcedureConfig<Events>,
-): ProcedureClass<Events> =>
-  definitionClass<ProcedureClass<Events>>({
-    manifest: { kind: 'Procedure' as const, name } satisfies ProcedureManifest,
-    events: config.events,
-    channel: config.channel,
-  })
-
-/**
- * Register the flow body into its channel. The body may read state and dispatch
- * events, but never writes state (the core invariant); its context requirements
- * (RPC clients, etc.) are captured here so the channel fiber can run it with no
- * outstanding R.
- */
-export const live = <
-  Events extends ReadonlyArray<AnyEvent>,
-  Eff extends YieldWrap<Effect.Effect<any, any, any>>,
-  Done,
->(
-  procedure: ProcedureClass<Events>,
-  body: (event: EventType<Events[number]>) => Generator<Eff, Done, never>,
-): 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))
-  // 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)) {
-        yield* Effect.logWarning(`reform: duplicate procedure name '${name}' registered`)
-      }
-      // Snapshot the body's full context (Bus + RPC clients) so `run` is total.
-      const runtime = yield* Effect.runtime<Bus | Ctx<Eff>>()
-      const entry: ProcedureEntry = {
-        name,
-        channelName,
-        // The channel only routes events whose tag is in `handles`, so at runtime
-        // `event` is always one of `Events`; `narrowHandled` restores the body's
-        // declared event union from the erased `Tagged` envelope.
-        handles,
-        run: (event) => Effect.provide(Effect.gen(() => body(narrowHandled(event))), runtime),
-      }
-      yield* Effect.acquireRelease(Effect.sync(() => procedures.register(entry)), () =>
-        Effect.sync(() => procedures.unregister(entry)),
-      )
-    }),
-  )
-}

package/src/reducer/reducer.ts

@@ -1,137 +0,0 @@
-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 StateClass, 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)),
-      )
-    }),
-  )
-}