@playfast/reform 1.0.1 → 1.2.0

package/src/channel/channel.ts

@@ -1,19 +1,21 @@
-import { Chunk, Context, type Duration, Effect, Layer, Match, Option, Queue, Stream } from 'effect'
+import {
+  Chunk,
+  Context,
+  Duration,
+  Effect,
+  Exit,
+  Layer,
+  Match,
+  Option,
+  Queue,
+  Scope,
+  Stream,
+} from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
+import { makeBucketCache } from '../internal/bucketCache'
 import type { Tagged } from '../runtime/bus'
 import { resolveInstrumentation } from '../runtime/instrumentation'
 
-/**
- * How a channel schedules the procedure work routed to it. Channels generalize
- * the old per-procedure `concurrency`: a named lane with one policy, shared by
- * every procedure that declares it.
- *
- * - `merge`     run every routed event concurrently (the default).
- * - `latest`    a new event cancels the in-flight run (switch).
- * - `debounce`  collapse a burst, run only after `duration` of quiet.
- * - `throttle`  rate-limit to `units` per `duration` (shape or enforce).
- * - `exclusive` one run at a time across the whole channel (mutual exclusion).
- */
 export type ChannelPolicy =
   | { readonly _tag: 'merge' }
   | { readonly _tag: 'latest' }
@@ -28,7 +30,6 @@ export type ChannelPolicy =
     }
   | { readonly _tag: 'exclusive' }
 
-/** The reflectable descriptor a channel carries. */
 export interface ChannelManifest extends Manifest {
   readonly kind: 'Channel'
 }
@@ -43,44 +44,21 @@ export interface ChannelConfig {
   readonly policy: ChannelPolicy
 }
 
-/**
- * A registered procedure body, with its trigger events and the channel it runs
- * on. `run`'s context (RPC clients, etc.) is already provided at registration
- * (see `Procedure.live`), so the channel fiber can run it with no R.
- */
 export interface ProcedureEntry {
-  /** The procedure's name — used only to warn on duplicate registration. */
   readonly name: string
   readonly channelName: string
   readonly handles: ReadonlySet<string>
   readonly run: (event: Tagged) => Effect.Effect<unknown, unknown, never>
 }
 
-/**
- * Mutable collector procedures register into; channels read it to find their
- * bodies. `byTag` indexes entries by trigger tag, so a channel routes an event
- * to O(procedures handling it) rather than scanning every registered procedure.
- */
 export interface ProcedureRegistry {
   readonly entries: Array<ProcedureEntry>
-  readonly byTag: Map<string, Array<ProcedureEntry>>
-  /**
-   * Distinct channel names per event tag. The drain loop routes through this so
-   * it offers each event to each channel exactly once — not once per matching
-   * procedure, which would re-run every procedure on a shared channel per offer.
-   */
-  readonly channelsByTag: Map<string, Array<string>>
-  /**
-   * Procedures keyed by (channel, tag), so a channel's `runMatching` is a direct
-   * lookup instead of scanning `byTag` and re-filtering by channel per event.
-   */
-  readonly byChannelTag: Map<string, Map<string, Array<ProcedureEntry>>>
+  readonly byName: Map<string, Set<ProcedureEntry>>
+  readonly byTag: Map<string, Set<ProcedureEntry>>
+  readonly channelsByTag: Map<string, Set<string>>
+  readonly channelsFor: (tag: string) => ReadonlyArray<string>
+  readonly byChannelTag: Map<string, Map<string, Set<ProcedureEntry>>>
   readonly register: (entry: ProcedureEntry) => void
-  /**
-   * Remove a previously-registered entry — the inverse of `register`, used when a
-   * lazy feature unmounts (scope close) so its procedures stop running and their
-   * index entries are reclaimed. Eager procedures (root scope) never call it.
-   */
   readonly unregister: (entry: ProcedureEntry) => void
 }
 
@@ -88,7 +66,6 @@ const ProceduresBase: Context.TagClass<Procedures, 'reform/Procedures', Procedur
   Context.Tag('reform/Procedures')<Procedures, ProcedureRegistry>()
 export class Procedures extends ProceduresBase {}
 
-/** Get a map entry, creating and inserting it on first access (avoids `let`). */
 const getOrCreate = <K, V>(map: Map<K, V>, key: K, make: () => V): V => {
   const existing = map.get(key)
   if (existing !== undefined) {
@@ -99,57 +76,64 @@ const getOrCreate = <K, V>(map: Map<K, V>, key: K, make: () => V): V => {
   return created
 }
 
-/** Drop an item from a `Map<K, Array>` bucket, pruning the key when it empties. */
-const dropFrom = <K, T>(map: Map<K, Array<T>>, key: K, target: T): void => {
+const dropFrom = <K, T>(map: Map<K, Set<T>>, key: K, target: T): void => {
   const bucket = map.get(key)
   if (bucket === undefined) {
     return
   }
-  const next = bucket.filter((candidate) => candidate !== target)
-  if (next.length === 0) {
+  bucket.delete(target)
+  if (bucket.size === 0) {
     map.delete(key)
-  } else {
-    map.set(key, next)
   }
 }
 
 const makeProcedureRegistry = (): ProcedureRegistry => {
-  // `entries` is reassigned immutably (new array per change) rather than mutated
-  // in place, so the holder keeps a stable reference the getter reads through.
-  const state: { entries: Array<ProcedureEntry> } = { entries: [] }
-  const byTag = new Map<string, Array<ProcedureEntry>>()
-  const channelsByTag = new Map<string, Array<string>>()
-  const byChannelTag = new Map<string, Map<string, Array<ProcedureEntry>>>()
+  const entries = new Set<ProcedureEntry>()
+  const byName = new Map<string, Set<ProcedureEntry>>()
+  const byTag = new Map<string, Set<ProcedureEntry>>()
+  const channelsByTag = new Map<string, Set<string>>()
+  const channelsFor = makeBucketCache(channelsByTag)
+  const byChannelTag = new Map<string, Map<string, Set<ProcedureEntry>>>()
+  const snapshot: { value: Option.Option<Array<ProcedureEntry>> } = {
+    value: Option.some([]),
+  }
   return {
     get entries() {
-      return state.entries
+      return Option.getOrElse(snapshot.value, () => {
+        const current = Array.from(entries)
+        snapshot.value = Option.some(current)
+        return current
+      })
     },
+    byName,
     byTag,
     channelsByTag,
+    channelsFor: channelsFor.read,
     byChannelTag,
     register: (entry) => {
-      state.entries = [...state.entries, entry]
+      entries.add(entry)
+      snapshot.value = Option.none()
+      getOrCreate(byName, entry.name, () => new Set()).add(entry)
       entry.handles.forEach((tag) => {
-        byTag.set(tag, [...getOrCreate(byTag, tag, () => []), entry])
-        const channels = getOrCreate(channelsByTag, tag, () => [])
-        if (!channels.includes(entry.channelName)) {
-          channelsByTag.set(tag, [...channels, entry.channelName])
-        }
+        getOrCreate(byTag, tag, () => new Set()).add(entry)
+        getOrCreate(channelsByTag, tag, () => new Set()).add(entry.channelName)
+        channelsFor.invalidate(tag)
         const channelMap = getOrCreate(byChannelTag, entry.channelName, () => new Map())
-        channelMap.set(tag, [...getOrCreate(channelMap, tag, () => []), entry])
+        getOrCreate(channelMap, tag, () => new Set()).add(entry)
       })
     },
     unregister: (entry) => {
-      state.entries = state.entries.filter((existing) => existing !== entry)
+      entries.delete(entry)
+      snapshot.value = Option.none()
+      dropFrom(byName, entry.name, entry)
       entry.handles.forEach((tag) => {
         dropFrom(byTag, tag, entry)
         const channelMap = byChannelTag.get(entry.channelName)
         if (channelMap !== undefined) {
           dropFrom(channelMap, tag, entry)
-          // If no procedure on this channel still handles the tag, drop the
-          // channel from `channelsByTag[tag]` so the loop stops offering to it.
           if (channelMap.get(tag) === undefined) {
             dropFrom(channelsByTag, tag, entry.channelName)
+            channelsFor.invalidate(tag)
           }
           if (channelMap.size === 0) {
             byChannelTag.delete(entry.channelName)
@@ -160,17 +144,19 @@ const makeProcedureRegistry = (): ProcedureRegistry => {
   }
 }
 
-export const proceduresLayer: Layer.Layer<Procedures> = Layer.sync(Procedures, makeProcedureRegistry)
+export const proceduresLayer: Layer.Layer<Procedures> = Layer.sync(
+  Procedures,
+  makeProcedureRegistry,
+)
 
-/** A live channel: the single loop offers events here; the channel drives them. */
 export interface ChannelRuntime {
   readonly name: string
-  /** The policy this channel was built with — used to reject a name clash. */
   readonly policy: ChannelPolicy
   readonly offer: (event: Tagged) => void
+  readonly leases: { count: number }
+  readonly close: Effect.Effect<void>
 }
 
-/** Registry of live channels, keyed by name. The single loop routes through it. */
 const ChannelsBase: Context.TagClass<
   Channels,
   'reform/Channels',
@@ -178,25 +164,66 @@ const ChannelsBase: Context.TagClass<
 > = Context.Tag('reform/Channels')<Channels, { readonly byName: Map<string, ChannelRuntime> }>()
 export class Channels extends ChannelsBase {}
 
-export const channelsLayer: Layer.Layer<Channels> = Layer.sync(Channels, () => ({ byName: new Map() }))
+export const channelsLayer: Layer.Layer<Channels> = Layer.sync(Channels, () => ({
+  byName: new Map(),
+}))
 
-/**
- * A scheduling lane for procedures. The *definition* (`Channel.make`) is a
- * reflectable name + policy; the *implementation* (`Channel.live`) builds the
- * queue + fiber that applies the policy. Procedures reference a channel by value
- * and register into it; `Channel.live` is merged into the app once per channel.
- */
 export const make = (name: string, config: ChannelConfig): ChannelClass =>
   definitionClass<ChannelClass>({
     manifest: { kind: 'Channel' as const, name } satisfies ChannelManifest,
     policy: config.policy,
   })
 
-/**
- * Build and register the live machinery for a channel. Idempotent by name, so
- * procedures sharing an `exclusive`/`latest` channel share one queue + fiber +
- * semaphore (and therefore truly serialize / cancel across each other).
- */
+const durationMillis = (duration: Duration.DurationInput): number =>
+  Duration.toMillis(Duration.decode(duration))
+
+const sameOptionValue = <A>(left: Option.Option<A>, right: Option.Option<A>): boolean =>
+  Option.match(left, {
+    onNone: () => Option.isNone(right),
+    onSome: (leftValue) =>
+      Option.match(right, {
+        onNone: () => false,
+        onSome: (rightValue) => Object.is(leftValue, rightValue),
+      }),
+  })
+
+const samePolicy = (left: ChannelPolicy, right: ChannelPolicy): boolean =>
+  Match.value(left).pipe(
+    Match.tag('merge', () => right._tag === 'merge'),
+    Match.tag('latest', () => right._tag === 'latest'),
+    Match.tag(
+      'debounce',
+      (policy) =>
+        right._tag === 'debounce' &&
+        durationMillis(policy.duration) === durationMillis(right.duration),
+    ),
+    Match.tag(
+      'throttle',
+      (policy) =>
+        right._tag === 'throttle' &&
+        policy.units === right.units &&
+        durationMillis(policy.duration) === durationMillis(right.duration) &&
+        sameOptionValue(policy.cost, right.cost) &&
+        sameOptionValue(policy.burst, right.burst) &&
+        sameOptionValue(policy.strategy, right.strategy),
+    ),
+    Match.tag('exclusive', () => right._tag === 'exclusive'),
+    Match.exhaustive,
+  )
+
+const release = Effect.fn('release')(function* (
+  byName: Map<string, ChannelRuntime>,
+  registration: ChannelRuntime,
+): Effect.fn.Return<void> {
+  registration.leases.count -= 1
+  if (registration.leases.count === 0) {
+    if (byName.get(registration.name) === registration) {
+      byName.delete(registration.name)
+    }
+    yield* registration.close
+  }
+})
+
 export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels | Procedures> =>
   Layer.scopedDiscard(
     Effect.gen(function* () {
@@ -204,28 +231,20 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
       const channels = yield* Channels
       const existing = channels.byName.get(name)
       if (existing !== undefined) {
-        // Idempotent for the *same* channel `.live`'d through several sub-layers
-        // (shared `exclusive`/`latest` lane). A *different* channel reusing the
-        // name is a silent footgun — the second policy would be dropped — so
-        // reject it loudly instead.
-        if (existing.policy !== channel.policy) {
-          // A different channel reusing a live name is a programmer footgun, not a
-          // recoverable failure — surface it as a defect to keep the layer E = never.
+        if (!samePolicy(existing.policy, channel.policy)) {
           yield* Effect.dieMessage(
-            `reform: channel '${name}' is already live with a different policy`,
+            `reform: channel '${name}' is already live with a different policy (existing: ${existing.policy._tag}, incoming: ${channel.policy._tag})`,
           )
         }
+        existing.leases.count += 1
+        yield* Effect.addFinalizer(() => release(channels.byName, existing))
         return
       }
       const procedures = yield* Procedures
       const instrumentation = yield* resolveInstrumentation
+      const machineryScope = yield* Scope.make()
       const queue = yield* Queue.unbounded<Tagged>()
 
-      // Run every procedure on THIS channel that handles the event. Read the live
-      // index each time so procedures registered later are still seen.
-      // A procedure is expected to model expected failures as events; a leaked
-      // defect (a bug in the body) is logged before being isolated, so one
-      // procedure's crash never tears down the channel fiber — but is observable.
       const runMatching = (event: Tagged): Effect.Effect<void> => {
         const matching = Option.fromNullable(procedures.byChannelTag.get(name)).pipe(
           Option.flatMapNullable((byTag) => byTag.get(event._tag)),
@@ -234,8 +253,6 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         return Effect.forEach(
           matching,
           (procedure) =>
-            // The `procedureRun` span covers the whole body, success/failure/cancel
-            // alike (`ensuring` fires on all three).
             Effect.sync(() => instrumentation.procedureRun(procedure.name, name, event._tag)).pipe(
               Effect.flatMap((endSpan) =>
                 procedure.run(event).pipe(Effect.ensuring(Effect.sync(endSpan))),
@@ -249,13 +266,15 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
         )
       }
 
-      // Map the policy to its scheduling stream. `Match.exhaustive` makes a new
-      // policy variant a compile error, and each arm is a self-contained const.
       const events = Stream.fromQueue(queue)
       const driven: Stream.Stream<unknown> = Match.value(channel.policy).pipe(
-        Match.tag('merge', () => Stream.mapEffect(events, runMatching, { concurrency: 'unbounded' })),
+        Match.tag('merge', () =>
+          Stream.mapEffect(events, runMatching, { concurrency: 'unbounded' }),
+        ),
         Match.tag('latest', () =>
-          Stream.flatMap(events, (event) => Stream.fromEffect(runMatching(event)), { switch: true }),
+          Stream.flatMap(events, (event) => Stream.fromEffect(runMatching(event)), {
+            switch: true,
+          }),
         ),
         Match.tag('debounce', (policy) =>
           events.pipe(
@@ -278,25 +297,21 @@ export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels
             Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
           ),
         ),
-        // `concurrency: 1` runs one event at a time AND in offer order — a true
-        // serialized lane. (An unbounded fork racing for a single semaphore permit
-        // would serialize but could reorder under contention.)
         Match.tag('exclusive', () => Stream.mapEffect(events, runMatching, { concurrency: 1 })),
         Match.exhaustive,
       )
 
-      yield* Effect.forkScoped(Stream.runDrain(driven))
-      channels.byName.set(name, {
+      yield* Stream.runDrain(driven).pipe(Effect.forkIn(machineryScope))
+      const registration: ChannelRuntime = {
         name,
         policy: channel.policy,
         offer: (event) => {
           Queue.unsafeOffer(queue, event)
         },
-      })
-      // On scope close (a lazy feature unmounting) remove the live channel so the
-      // loop stops routing to it; the drain fiber is already torn down by
-      // `forkScoped`. Eager channels live on the root scope, so this is a no-op
-      // until app dispose.
-      yield* Effect.addFinalizer(() => Effect.sync(() => channels.byName.delete(name)))
+        leases: { count: 1 },
+        close: Scope.close(machineryScope, Exit.void),
+      }
+      channels.byName.set(name, registration)
+      yield* Effect.addFinalizer(() => release(channels.byName, registration))
     }),
   )

package/src/compose/composition.test.ts

@@ -0,0 +1,19 @@
+import { Option, Schema } from 'effect'
+import { expect, it } from '@effect/vitest'
+import { make } from './composition'
+import { ui } from './ui'
+
+class ItemUi extends ui('composition.parser.ItemUi')<{
+  props: { readonly label: string }
+}>() {}
+
+class Item extends make('composition.parser.Item', {
+  title: 'Item',
+  props: Schema.Struct({ label: Schema.String }),
+  ui: ItemUi,
+})<Item>() {}
+
+it('validates reflected props against the composition schema', () => {
+  expect(Item.parseProps({ label: 'ready' })).toEqual(Option.some({ label: 'ready' }))
+  expect(Option.isNone(Item.parseProps({ label: 1 }))).toBe(true)
+})