@playfast/reform 0.1.0 → 1.1.1

package/src/internal/store.ts

@@ -2,26 +2,6 @@ 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
@@ -30,9 +10,13 @@ export interface Store<in out A> extends Inspectable {
   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 noChange = (): void => {}
+
+export const makeStore = <A>(
+  initial: A,
+  scheduler: Scheduler = defaultScheduler,
+  onChange: () => void = noChange,
+): Store<A> => {
   const current = MutableRef.make(initial)
   const version = MutableRef.make(0)
   const listeners = new Set<() => void>()
@@ -46,6 +30,7 @@ export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler
       }
       MutableRef.set(current, next)
       MutableRef.update(version, (count) => count + 1)
+      onChange()
       scheduler.schedule(listeners)
     },
     subscribe: (listener) => {
@@ -58,27 +43,14 @@ export const makeStore = <A>(initial: A, scheduler: Scheduler = defaultScheduler
   }
 }
 
-/**
- * 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,
+  onOutputChange: () => void = noChange,
 ): { 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)
@@ -86,6 +58,7 @@ export const makeDerivedStore = <A>(
     MutableRef.set(seen, { value: next })
     if (previous === undefined || !Equal.equals(previous.value, next)) {
       MutableRef.update(version, (count) => count + 1)
+      onOutputChange()
       scheduler.schedule(listeners)
     }
   }

package/src/internal/track.ts

@@ -1,37 +1,19 @@
 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)
- * structurally satisfy this. The host sums `getVersion()` across a render's
- * tracked sources for its `useSyncExternalStore` snapshot — a value that moves
- * whenever any dependency changes, which is what closes the tear/dropped-update
- * window a per-store value snapshot cannot.
- */
 export interface Subscribable {
   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
 }
 
-/**
- * The active render's dependency tracker (D5). Present only while a composition
- * is rendering under `@reform/react`; absent in procedures and headless reads.
- */
 const CurrentTrackerBase: Context.TagClass<CurrentTracker, 'reform/Tracker', Tracker> =
   Context.Tag('reform/Tracker')<CurrentTracker, Tracker>()
 export class CurrentTracker extends CurrentTrackerBase {}
 
-/**
- * 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 const readTracked = <A>(store: Store<A>): Effect.Effect<A> =>
   Effect.map(Effect.serviceOption(CurrentTracker), (tracker) => {
     if (Option.isSome(tracker)) {

package/src/internal/variance.ts

@@ -0,0 +1,5 @@
+import type { Schema } from 'effect'
+
+export type AnyValue = Schema.Schema.Type<Schema.Schema.AnyNoContext>
+
+export type AnySchema<A> = Schema.Schema<A, Schema.Schema.Encoded<Schema.Schema.AnyNoContext>>

package/src/namespace/namespace.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { Match, Schema as S } from 'effect'
+import * as Event from '../event/event'
+import * as Namespace from './namespace'
+
+describe('Namespace.make', () => {
+  const ns = Namespace.make('demoFeature')
+
+  it('prefixes every definition kind', () => {
+    class Saved extends ns.Event('Saved', S.Struct({})) {}
+    class Lane extends ns.Channel('Lane', { policy: { _tag: 'latest' } }) {}
+    class Count extends ns.State('count', S.Number) {}
+    class Doubled extends ns.Calc('Doubled', { inputs: [Count], output: S.Number }) {}
+    class Feed extends ns.AsyncCalc('Feed', { inputs: [Count], output: S.Number }) {}
+    class Rows extends ns.RemoteState('Rows', {
+      inputs: [Count],
+      output: S.Number,
+      intents: [],
+    }) {}
+
+    expect(Saved.tag).toBe('demoFeature.Saved')
+    expect(Lane.manifest.name).toBe('demoFeature.Lane')
+    expect(Count.manifest.name).toBe('demoFeature.count')
+    expect(Doubled.manifest.name).toBe('demoFeature.Doubled')
+    expect(Feed.manifest.name).toBe('demoFeature.Feed')
+    expect(Rows.manifest.name).toBe('demoFeature.Rows')
+  })
+
+  it('keeps the tag literal type for Match.tags folds', () => {
+    class Opened extends ns.Event('Opened', S.Struct({})) {}
+    class Closed extends ns.Event('Closed', S.Struct({ reason: S.String })) {}
+    type Folded = Event.EventType<typeof Opened> | Event.EventType<typeof Closed>
+
+    const fold = (event: Folded): string =>
+      Match.value(event).pipe(
+        Match.tags({
+          'demoFeature.Opened': () => 'open',
+          'demoFeature.Closed': ({ reason }) => reason,
+        }),
+        Match.exhaustive,
+      )
+
+    expect(fold(Event.construct(Opened, {}))).toBe('open')
+    expect(fold(Event.construct(Closed, { reason: 'done' }))).toBe('done')
+  })
+})

package/src/namespace/namespace.ts

@@ -0,0 +1,85 @@
+import * as AsyncCalc from '../calc/asyncCalc'
+import * as Calc from '../calc/calc'
+import * as CalcFamily from '../calc/calcFamily'
+import * as Channel from '../channel/channel'
+import * as Event from '../event/event'
+import type { GatedOf } from '../internal/queryDriver'
+import * as RemoteState from '../remote/remoteState'
+import * as State from '../state/state'
+import * as StateFamily from '../state/stateFamily'
+import type { AnySource } from '../state/token'
+import type { AnySchema } from '../internal/variance'
+
+export interface FeatureNamespace<Prefix extends string> {
+  readonly prefix: Prefix
+  readonly Event: <const N extends string, P>(
+    name: N,
+    schema: AnySchema<P>,
+  ) => Event.EventClass<`${Prefix}.${N}`, P>
+  readonly Channel: (name: string, config: Channel.ChannelConfig) => Channel.ChannelClass
+  readonly State: <const N extends string, A>(
+    name: N,
+    schema: AnySchema<A>,
+    options?: State.StateOptions,
+  ) => State.StateClass<`${Prefix}.${N}`, A>
+  readonly StateFamily: <const N extends string, K, V>(
+    name: N,
+    key: AnySchema<K>,
+    valueSchema: AnySchema<V>,
+    options?: StateFamily.StateFamilyMakeOptionsExternalApi,
+  ) => StateFamily.StateFamilyClass<`${Prefix}.${N}`, K, V>
+  readonly Calc: <const N extends string, const Inputs extends ReadonlyArray<AnySource>, Out>(
+    name: N,
+    config: Calc.CalcConfig<Inputs, Out>,
+  ) => Calc.CalcClass<`${Prefix}.${N}`, Inputs, Out>
+  readonly CalcFamily: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    K,
+    Out,
+  >(
+    name: N,
+    config: CalcFamily.CalcFamilyConfig<Inputs, K, Out>,
+  ) => CalcFamily.CalcFamilyClass<`${Prefix}.${N}`, Inputs, K, Out>
+  readonly AsyncCalc: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    A,
+    E = never,
+    const AlwaysOn extends boolean = false,
+  >(
+    name: N,
+    config: AsyncCalc.AsyncCalcConfig<Inputs, A, E, AlwaysOn>,
+  ) => AsyncCalc.AsyncCalcClass<`${Prefix}.${N}`, Inputs, A, E, GatedOf<AlwaysOn>>
+  readonly RemoteState: <
+    const N extends string,
+    const Inputs extends ReadonlyArray<AnySource>,
+    const Intents extends ReadonlyArray<Event.AnyEvent>,
+    A,
+    E = never,
+    const AlwaysOn extends boolean = false,
+  >(
+    name: N,
+    config: RemoteState.RemoteStateConfigExternalApi<Inputs, Intents, A, E, AlwaysOn>,
+  ) => RemoteState.RemoteStateClass<
+    `${Prefix}.${N}`,
+    Inputs,
+    Intents,
+    A,
+    E,
+    GatedOf<AlwaysOn>
+  >
+}
+
+export const make = <const Prefix extends string>(prefix: Prefix): FeatureNamespace<Prefix> => ({
+  prefix,
+  Event: (name, schema) => Event.make(`${prefix}.${name}`, schema),
+  Channel: (name, config) => Channel.make(`${prefix}.${name}`, config),
+  State: (name, schema, options) => State.make(`${prefix}.${name}`, schema, options),
+  StateFamily: (name, key, valueSchema, options) =>
+    StateFamily.make(`${prefix}.${name}`, key, valueSchema, options),
+  Calc: (name, config) => Calc.make(`${prefix}.${name}`, config),
+  CalcFamily: (name, config) => CalcFamily.make(`${prefix}.${name}`, config),
+  AsyncCalc: (name, config) => AsyncCalc.make(`${prefix}.${name}`, config),
+  RemoteState: (name, config) => RemoteState.make(`${prefix}.${name}`, config),
+})

package/src/procedure/procedure.ts

@@ -5,8 +5,8 @@ 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'
+import type { AnyValue } from '../internal/variance'
 
-/** The reflectable descriptor a procedure carries. */
 export interface ProcedureManifest extends Manifest {
   readonly kind: 'Procedure'
 }
@@ -14,26 +14,17 @@ export interface ProcedureManifest extends Manifest {
 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>,
@@ -44,15 +35,9 @@ export const make = <const Events extends ReadonlyArray<AnyEvent>>(
     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>>,
+  Eff extends YieldWrap<Effect.Effect<AnyValue, AnyValue, AnyValue>>,
   Done,
 >(
   procedure: ProcedureClass<Events>,
@@ -61,23 +46,16 @@ export const live = <
   const name = procedure.manifest.name
   const channelName = procedure.channel.manifest.name
   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((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.
       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),
       }

package/src/reducer/reducer.ts

@@ -13,8 +13,8 @@ import {
 } from '../state/stateFamily'
 import { narrowHandled, type Tagged } from '../runtime/bus'
 import { type ReducerEntry, Reducers } from '../runtime/loop'
+import type { AnyValue } from '../internal/variance'
 
-/** The reflectable descriptor a reducer carries, like every other primitive's `*Manifest`. */
 export interface ReducerManifest extends Manifest {
   readonly kind: 'Reducer'
 }
@@ -33,7 +33,6 @@ export interface FamilyReducerConfig<F extends AnyFamily, Events extends Readonl
 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>
 }
@@ -45,12 +44,6 @@ export interface FamilyReducerClass<F extends AnyFamily, Events extends Readonly
   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>,
@@ -72,11 +65,9 @@ export function make(
   })
 }
 
-/** 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>(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
@@ -98,14 +89,10 @@ export function live(
     | 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> {
+  fold: (acc: AnyValue, event: AnyValue) => AnyValue,
+): Layer.Layer<never, never, AnyValue> {
   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
@@ -119,13 +106,8 @@ export function live(
             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 {