@playfast/reform 0.0.1 → 0.0.3

package/src/internal/store.ts

@@ -0,0 +1,105 @@
+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/{dist/dts/internal/track.d.ts → src/internal/track.ts}

@@ -1,5 +1,6 @@
-import { Context, Effect } from 'effect';
-import type { Store } from './store.js';
+import { Context, Effect, Option } from 'effect'
+import type { Store } from './store'
+
 /**
  * Anything a render can depend on: a source it can subscribe to for changes and
  * snapshot a monotonic version from. `Store` (and the calc/family stores)
@@ -9,25 +10,28 @@ import type { Store } from './store.js';
  * window a per-store value snapshot cannot.
  */
 export interface Subscribable {
-    subscribe(listener: () => void): () => void;
-    getVersion(): number;
+  subscribe(listener: () => void): () => void
+  getVersion(): number
 }
+
 /** A per-render dependency sink. The renderer provides one; reads record into it. */
 export interface Tracker {
-    add(source: Subscribable): void;
+  add(source: Subscribable): void
 }
-declare const CurrentTracker_base: Context.TagClass<CurrentTracker, "reform/Tracker", Tracker>;
+
 /**
  * The active render's dependency tracker (D5). Present only while a composition
  * is rendering under `@reform/react`; absent in procedures and headless reads.
  */
-export declare class CurrentTracker extends CurrentTracker_base {
-}
+export class CurrentTracker extends Context.Tag('reform/Tracker')<CurrentTracker, Tracker>() {}
+
 /**
  * Read a store's current snapshot and, if a tracker is active, record the store
  * as a dependency of the current render. One read API, two behaviors by context
  * (D5): inside a render it subscribes the slice; elsewhere it just snapshots.
  */
-export declare const readTracked: <A>(store: Store<A>) => Effect.Effect<A>;
-export {};
-//# sourceMappingURL=track.d.ts.map
+export const readTracked = <A>(store: Store<A>): Effect.Effect<A> =>
+  Effect.map(Effect.serviceOption(CurrentTracker), (tracker) => {
+    if (Option.isSome(tracker)) tracker.value.add(store)
+    return store.getSnapshot()
+  })

package/src/procedure/procedure.ts

@@ -0,0 +1,89 @@
+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

@@ -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 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)),
+      )
+    }),
+  )
+}