@playfast/reform 1.2.0 → 1.3.0

package/src/runtime/loop.test.ts

@@ -1,6 +1,7 @@
 import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, Schema as S, TestClock } from 'effect'
 import { Channel, Engine, Event, Procedure, publish, Reducer, State } from '../index'
+import { makeFlightGate, until } from '../testkit/flight.testkit'
 
 it.live('a frame of events drains in one pass with a single notification flush', () => {
   class Counter extends State.make('counter', S.Number) {}
@@ -22,7 +23,11 @@ it.live('a frame of events drains in one pass with a single notification flush',
     yield* publish('Normal', Event.construct(Bumped, { to: 1 }))
     yield* publish('Normal', Event.construct(Bumped, { to: 2 }))
     yield* publish('Normal', Event.construct(Bumped, { to: 3 }))
-    yield* Effect.sleep(Duration.millis(20))
+    // The flush is the frame's last act, so one notification means the fold is done.
+    yield* until(
+      () => notifications.n,
+      (n) => n >= 1,
+    )
 
     expect(store.get()).toBe(3)
     expect(notifications.n).toBe(1)
@@ -34,11 +39,12 @@ it.live('an exclusive channel serializes procedures that share it', () => {
   class StartB extends Event.make('StartB', S.Struct({})) {}
   class Exclusive extends Channel.make('Exclusive', { policy: { _tag: 'exclusive' } }) {}
 
+  const gate = makeFlightGate()
   const concurrency = { active: 0, max: 0 }
   const guarded = function* () {
     concurrency.active += 1
     concurrency.max = Math.max(concurrency.max, concurrency.active)
-    yield* Effect.sleep(Duration.millis(15))
+    yield* gate.through(Effect.void)
     concurrency.active -= 1
   }
 
@@ -52,9 +58,20 @@ it.live('an exclusive channel serializes procedures that share it', () => {
   )
 
   return Effect.gen(function* () {
+    // Parking the first run IS the overlap: a shared lane that is not exclusive
+    // would start the second procedure while the first sits at the gate.
+    yield* gate.hold
     yield* publish('Normal', Event.construct(StartA, {}))
     yield* publish('Normal', Event.construct(StartB, {}))
-    yield* Effect.sleep(Duration.millis(60))
+    yield* gate.awaitEntry(1)
+    expect(gate.entered()).toBe(1)
+
+    yield* gate.release
+    yield* gate.awaitEntry(2)
+    yield* until(
+      () => concurrency.active,
+      (active) => active === 0,
+    )
     expect(concurrency.max).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -79,7 +96,11 @@ it.live('two procedures sharing a channel each run once for one shared event', (
 
   return Effect.gen(function* () {
     yield* publish('High', Event.construct(Shared, {}))
-    yield* Effect.sleep(Duration.millis(20))
+    yield* until(
+      () => runs.a + runs.b,
+      (total) => total >= 2,
+    )
+    // A duplicated offer would land in the same frame and double one of them.
     expect(runs.a).toBe(1)
     expect(runs.b).toBe(1)
   }).pipe(Effect.provide(TestLayer))
@@ -126,10 +147,12 @@ it.live('a reducer ignores events outside its declared set (no-op)', () => {
   return Effect.gen(function* () {
     const store = yield* Counter.store
     yield* publish('Normal', Event.construct(Unrelated, {}))
-    yield* Effect.sleep(Duration.millis(10))
-    expect(store.get()).toBe(0)
     yield* publish('Normal', Event.construct(Bump, {}))
-    yield* Effect.sleep(Duration.millis(10))
+    yield* until(
+      () => store.get(),
+      (n) => n > 0,
+    )
+    // Both events fold in one frame: a reducer that also took Unrelated reads 2.
     expect(store.get()).toBe(1)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -166,6 +189,7 @@ it.live('a fold returning the previous reference keeps the exact store value', (
     S.TaggedStruct('Open', { revision: S.Number }),
   )
   class ViewerState extends State.make('viewer', Viewer) {}
+  class Marker extends State.make('marker', S.Number) {}
   class Poked extends Event.make('Poked', S.Struct({})) {}
   class PokeReducer extends Reducer.make('PokeReducer', {
     states: [ViewerState],
@@ -175,20 +199,37 @@ it.live('a fold returning the previous reference keeps the exact store value', (
   const PokeReducerLive = Reducer.live(PokeReducer, (viewer) =>
     viewer._tag === 'Open' ? { ...viewer, revision: viewer.revision + 1 } : viewer,
   )
+  class MarkReducer extends Reducer.make('MarkReducer', {
+    states: [Marker],
+    events: [Poked],
+  }) {}
+  const MarkReducerLive = Reducer.live(MarkReducer, (n) => n + 1)
 
-  const TestLayer = PokeReducerLive.pipe(
-    Layer.provideMerge(Layer.mergeAll(State.live(ViewerState, { _tag: 'Closed' }), Engine)),
+  const TestLayer = Layer.mergeAll(PokeReducerLive, MarkReducerLive).pipe(
+    Layer.provideMerge(
+      Layer.mergeAll(State.live(ViewerState, { _tag: 'Closed' }), State.live(Marker, 0), Engine),
+    ),
   )
 
   return Effect.gen(function* () {
     const store = yield* ViewerState.store
+    const marker = yield* Marker.store
     const before = store.get()
     const notifications = { n: 0 }
+    const flushed = { n: 0 }
     store.subscribe(() => {
       notifications.n += 1
     })
+    marker.subscribe(() => {
+      flushed.n += 1
+    })
     yield* publish('Normal', Event.construct(Poked, {}))
-    yield* Effect.sleep(Duration.millis(20))
+    // The marker folds on the same event and shares the scheduler's flush: once
+    // its listener fires, a viewer notification would have run in that batch too.
+    yield* until(
+      () => flushed.n,
+      (n) => n >= 1,
+    )
     // Reference identity is the repaint signal: an unchanged fold must not be
     // re-decoded into a fresh, structurally-equal value that wakes subscribers.
     expect(store.get()).toBe(before)

package/src/runtime/runtimeHandle.ts

@@ -0,0 +1,124 @@
+import type { Context, Effect, Option } from 'effect'
+import type {
+  CompositionActivation,
+  CompositionId,
+  RequiredSlotIdentities,
+} from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type {
+  AnyFeatureBinding,
+  CapturedFeatureBinding,
+  FeatureBinding,
+  FeatureRequirement,
+} from '../feature/feature'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryContract,
+  FeatureSummaryInput,
+  FeatureSummaryMountProps,
+  FeatureSummaryName,
+  FeatureSummaryOpenServices,
+  FeatureSummaryUsesInput,
+} from '../graph/closure'
+import type { FeatureLoadFailed } from '../internal/errors'
+import type { Node } from '../ui/node'
+import type { Priority, Tagged } from './bus'
+import type { Instrumentation } from './instrumentation'
+import type { EngineServices } from './loop'
+
+export const UnspecifiedRuntimeServicesTypeId: unique symbol = Symbol.for(
+  'reform/UnspecifiedRuntimeServices',
+)
+export type UnspecifiedRuntimeServicesTypeId = typeof UnspecifiedRuntimeServicesTypeId
+export interface UnspecifiedRuntimeServices {
+  readonly [UnspecifiedRuntimeServicesTypeId]: UnspecifiedRuntimeServicesTypeId
+}
+
+export type FeatureMountHandlersExternalApi<UsesInput extends boolean, Input, Services> = {
+  readonly onLive: (runtime: RuntimeHandle<Services>) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+} & (UsesInput extends true ? { readonly props: Input } : { readonly props?: never })
+
+export type FeatureMountHandlers<
+  UsesInput extends boolean,
+  Input,
+  Services,
+> = FeatureMountHandlersExternalApi<UsesInput, Input, Services>
+
+export type RuntimeFeatureAvailability<Services, OpenServices> = [
+  EngineServices | OpenServices,
+] extends [Services]
+  ? object
+  : {
+      readonly missingFeatureServices: Exclude<EngineServices | OpenServices, Services>
+    }
+
+export interface AnyFeatureMountHandlers {
+  readonly props: unknown
+  readonly onLive: <Services>(runtime: RuntimeHandle<Services>) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+export interface CapturedFeatureMountHandlers<
+  Props,
+  HostServices,
+  FeatureServices,
+  C extends UiContract,
+  N extends string,
+  Identity,
+> {
+  readonly props: Props
+  readonly onLive: (
+    runtime: RuntimeHandle<
+      HostServices | FeatureServices | CompositionId<N, Identity, RequiredSlotIdentities<C>>
+    >,
+  ) => void
+  readonly onFailed: (error: FeatureLoadFailed) => void
+}
+
+export interface RuntimeHandle<Services = UnspecifiedRuntimeServices> {
+  read<Identifier extends Services, Service>(tag: Context.Tag<Identifier, Service>): Service
+  readOption<Identifier, Service>(tag: Context.Tag<Identifier, Service>): Option.Option<Service>
+  runRender(effect: Effect.Effect<Node, never, never>): Node
+  dispatch(priority: Priority, event: Tagged): void
+  mountScoped(activation: CompositionActivation): () => void
+  mountFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: [EngineServices | FeatureSummaryOpenServices<Summary>] extends [Services]
+      ? FeatureBinding<Summary, ROut, DirectRequires>
+      : never,
+    handlers: FeatureMountHandlers<
+      FeatureSummaryUsesInput<Summary>,
+      FeatureSummaryInput<Summary>,
+      Services | ROut
+    >,
+  ): () => void
+  mountCapturedFeature<
+    Summary extends AnyFeatureGraphSummary,
+    ROut,
+    const DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  >(
+    binding: CapturedFeatureBinding<Summary, ROut, DirectRequires> &
+      RuntimeFeatureAvailability<Services, FeatureSummaryOpenServices<Summary>>,
+    handlers: CapturedFeatureMountHandlers<
+      FeatureSummaryMountProps<Summary>,
+      Services,
+      ROut,
+      FeatureSummaryContract<Summary>,
+      FeatureSummaryName<Summary>,
+      FeatureSummaryCompositionIdentity<Summary>
+    >,
+  ): () => void
+  mountAnyFeature(binding: AnyFeatureBinding, handlers: AnyFeatureMountHandlers): () => void
+  readonly instrumentation: Instrumentation
+}
+
+export interface AppRuntime<Services = UnspecifiedRuntimeServices> extends RuntimeHandle<Services> {
+  boot(): void
+  dispose(): void
+  isDisposed(): boolean
+}

package/src/state/stateFamily.test.ts

@@ -1,8 +1,12 @@
 import { expect, it } from '@effect/vitest'
-import { Duration, Effect, Layer, Schema as S } from 'effect'
+import { Effect, Layer, Schema as S } from 'effect'
 import { Engine, Event, publish, Reducer, StateFamily } from '../index'
+import { until } from '../testkit/flight.testkit'
 
-const tick = Effect.sleep(Duration.millis(1))
+// Eviction is queued with queueMicrotask; one turn of the queue provably drains it.
+const drainMicrotasks = Effect.promise(
+  () => new Promise<void>((resolve) => queueMicrotask(resolve)),
+)
 
 it.live('same-shaped families resolve their own stores', () => {
   class First extends StateFamily.make('family.nominal.first', S.String, S.Number) {}
@@ -36,7 +40,10 @@ it.live("writing one key does not notify another key's subscribers", () => {
     })
 
     a.set(1)
-    yield* tick
+    yield* until(
+      () => aWakes.n,
+      (n) => n > 0,
+    )
     expect(aWakes.n).toBe(1)
     expect(bWakes.n).toBe(0)
     expect(b.get()).toBe(0)
@@ -81,12 +88,16 @@ it.live('evictWhenUnused drops a key once its last subscriber leaves', () => {
     const offB = store.subscribe(() => {})
     expect(family.size()).toBe(1)
 
+    // Releasing one of two subscribers queues no eviction at all — assert with no window.
     offA()
-    yield* tick
+    yield* drainMicrotasks
     expect(family.size()).toBe(1)
 
     offB()
-    yield* tick
+    yield* until(
+      () => family.size(),
+      (size) => size === 0,
+    )
     expect(family.size()).toBe(0)
     expect(family.at('k').get()).toBe(0)
   }).pipe(Effect.provide(TestLayer))
@@ -103,7 +114,7 @@ it.live('evictWhenUnused: a same-tick re-subscribe cancels eviction', () => {
     const off = store.subscribe(() => {})
     off()
     store.subscribe(() => {})
-    yield* tick
+    yield* drainMicrotasks
     expect(family.size()).toBe(1)
     expect(family.at('k').get()).toBe(7)
   }).pipe(Effect.provide(TestLayer))
@@ -130,12 +141,18 @@ it.live('a family reducer fold returning Tombstone evicts the key', () => {
     const family = yield* Items.store
 
     yield* publish('High', Event.construct(Bumped, { id: 'a' }))
-    yield* Effect.sleep(Duration.millis(5))
+    yield* until(
+      () => family.at('a').get(),
+      (value) => value === 1,
+    )
     const before = family.at('a')
     expect(before.get()).toBe(1)
 
     yield* publish('High', Event.construct(Removed, { id: 'a' }))
-    yield* Effect.sleep(Duration.millis(5))
+    yield* until(
+      () => family.at('a'),
+      (store) => store !== before,
+    )
     const after = family.at('a')
     expect(after).not.toBe(before)
     expect(after.get()).toBe(0)

package/src/testkit/flight.testkit.ts

@@ -10,6 +10,15 @@ import { Deferred, Duration, Effect, MutableRef, Option } from 'effect'
 
 export const tick = (ms = 10): Effect.Effect<void> => Effect.sleep(Duration.millis(ms))
 
+// The runtime notifies on the microtask queue (scheduler, stateFamily, calcFamily),
+// so draining turns is exact where a duration is a guess: a microtask cannot be
+// starved by host load the way a 10ms budget can. Use this to let the graph
+// quiesce before asserting that something did NOT happen.
+export const flush = (turns = 3): Effect.Effect<void> =>
+  Effect.promise(() => new Promise<void>((resolve) => queueMicrotask(resolve))).pipe(
+    Effect.repeatN(Math.max(turns - 1, 0)),
+  )
+
 export const until = <A>(
   read: () => A,
   predicate: (value: A) => boolean,