@playfast/reform 1.1.1 → 1.2.0

package/src/event/event.ts

@@ -1,33 +1,57 @@
-import { Effect, PubSub, Runtime } from 'effect'
+import { Effect, Layer, MutableRef, Option, PubSub, Runtime, Schema } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
+import { resolveScheduler } from '../internal/scheduler'
 import { Bus, publish, type Tagged } from '../runtime/bus'
+import type { Source } from '../state/token'
 import type { Trigger } from '../ui/trigger'
-import type { AnySchema, AnyValue } from '../internal/variance'
 
 export type EventOf<N extends string, P> = Tagged & { readonly _tag: N } & P
 
-export interface EventManifest<N extends string, P> extends Manifest {
+export interface EventSchemaReflection {
+  readonly ast: Schema.Schema<unknown, unknown, unknown>['ast']
+}
+
+export interface EventManifest<N extends string> extends Manifest {
   readonly kind: 'Event'
   readonly name: N
-  readonly schema: AnySchema<P>
+  readonly schema: EventSchemaReflection
 }
 
-export interface EventClass<out N extends string, in out P> {
+export interface EventReflection<out N extends string = string, out P = unknown> {
   new (): {}
-  readonly manifest: EventManifest<N, P>
+  readonly manifest: EventManifest<N>
   readonly tag: N
+  readonly Payload: P
+}
+
+export type EventCapture<Result> = <N extends string, P>(event: EventClass<N, P>) => Result
+
+export interface AnyEvent extends EventReflection {
+  readonly buildUnknown: (payload: unknown) => Tagged
+  readonly capture: <Result>(visit: EventCapture<Result>) => Result
+}
+
+export interface EventClass<out N extends string, in out P> extends EventReflection<N, P> {
   readonly build: (payload: P) => EventOf<N, P>
   readonly trigger: Effect.Effect<Trigger<P>, never, Bus>
+  readonly buildUnknown: (payload: unknown) => Tagged
+  readonly capture: <Result>(visit: EventCapture<Result>) => Result
 }
 
-export type AnyEvent = EventClass<string, AnyValue>
-export type EventType<E> = E extends EventClass<infer N, infer P> ? EventOf<N, P> : never
+export type EventName<E> = E extends EventReflection<infer N, infer _P> ? N : never
+export type EventPayload<E> = E extends EventReflection<string, infer P> ? P : never
+export type EventType<E> = E extends EventReflection<infer N, infer P> ? EventOf<N, P> : never
 
-export const make = <const N extends string, P>(
+export const make = <const N extends string, P, Encoded>(
   name: N,
-  schema: AnySchema<P>,
+  schema: Schema.Schema<P, Encoded, never>,
 ): EventClass<N, P> => {
-  const build = (payload: P): EventOf<N, P> => ({ _tag: name, ...payload })
+  const build = (payload: P): EventOf<N, P> => ({ ...payload, _tag: name })
+  // Payloads at existential boundaries are already-decoded domain values, so
+  // check the Type side — decodeUnknownSync would reject transforming schemas
+  // (e.g. a real Option, whose _tag lives on the prototype).
+  const validatePayload = Schema.validateSync(schema)
+  const buildUnknown = (payload: unknown): Tagged => build(validatePayload(payload))
   const trigger = Effect.gen(function* () {
     const bus = yield* Bus
     const runtime = yield* Effect.runtime<never>()
@@ -35,22 +59,82 @@ export const make = <const N extends string, P>(
       Runtime.runSync(runtime)(PubSub.publish(bus, { priority: 'High', event: build(payload) }))
     }
   })
-  return definitionClass<EventClass<N, P>>({
+  const event: EventClass<N, P> = definitionClass<EventClass<N, P>>({
     manifest: { kind: 'Event' as const, name, schema },
     tag: name,
     build,
+    buildUnknown,
     trigger,
+    capture: <Result>(visit: EventCapture<Result>): Result => visit(event),
   })
+  return event
 }
 
-export const construct = <N extends string, P>(event: EventClass<N, P>, payload: P): EventOf<N, P> =>
-  event.build(payload)
+export function construct<N extends string, P>(event: EventClass<N, P>, payload: P): EventOf<N, P>
+export function construct<E extends AnyEvent>(event: E, payload: EventPayload<E>): EventType<E>
+export function construct(event: AnyEvent, payload: unknown): Tagged {
+  return event.buildUnknown(payload)
+}
 
-export const dispatch = <N extends string, P>(
-  event: EventClass<N, P>,
-  payload: P,
-): Effect.Effect<void, never, Bus> => publish('Normal', event.build(payload))
+export const dispatch = <E extends AnyEvent>(
+  event: E,
+  payload: EventPayload<E>,
+): Effect.Effect<void, never, Bus> => publish('Normal', event.buildUnknown(payload))
 
 export const trigger = <N extends string, P>(
   event: EventClass<N, P>,
 ): Effect.Effect<Trigger<P>, never, Bus> => event.trigger
+
+export interface SourceChange<A> {
+  readonly previous: Option.Option<A>
+  readonly current: A
+}
+
+export interface SourceEventConfigExternalApi<A, P> {
+  readonly emitInitial?: boolean
+  readonly payload: (change: SourceChange<A>) => Option.Option<P>
+}
+export type SourceEventConfig<A, P> = SourceEventConfigExternalApi<A, P>
+
+export const liveFromSource = <N extends string, P, SourceName extends string, A, Identifier>(
+  event: EventClass<N, P>,
+  source: Source<SourceName, A, Identifier>,
+  config: SourceEventConfigExternalApi<A, P>,
+): Layer.Layer<never, never, Identifier | Bus> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const store = yield* source.store
+      const scheduler = yield* resolveScheduler
+      const runtime = yield* Effect.runtime<Bus>()
+      const initial = store.getSnapshot()
+      // The scheduler coalesces bursts, so track the last value this adapter observed.
+      const seen = MutableRef.make(initial)
+      // A queued notification may outlive unsubscribe within the same tick.
+      const active = MutableRef.make(true)
+      const emit = (change: SourceChange<A>): void => {
+        if (!MutableRef.get(active)) {
+          return
+        }
+        const payload = config.payload(change)
+        if (Option.isSome(payload)) {
+          Runtime.runSync(runtime)(publish('Normal', event.build(payload.value)))
+        }
+      }
+      const unsubscribe = store.subscribe(() => {
+        const current = store.getSnapshot()
+        const previous = MutableRef.get(seen)
+        MutableRef.set(seen, current)
+        emit({ previous: Option.some(previous), current })
+      })
+      yield* Effect.addFinalizer(() =>
+        Effect.sync(() => {
+          MutableRef.set(active, false)
+          unsubscribe()
+        }),
+      )
+      if (config.emitInitial === true) {
+        // Defer until reducers and procedures from the same layer build have registered.
+        scheduler.schedule([() => emit({ previous: Option.none(), current: initial })])
+      }
+    }),
+  )

package/src/feature/feature.mount.test.ts

@@ -1,46 +1,105 @@
-import { type Cause, Duration, Effect, Exit, Layer, Scope } from "effect";
-import { Schema as S } from "effect";
-import { expect, it } from "@effect/vitest";
-import * as Composition from "../compose/composition";
-import { ui } from "../compose/ui";
-import * as Event from "../event/event";
-import * as Reducer from "../reducer/reducer";
-import * as State from "../state/state";
-import { publish } from "../runtime/bus";
-import { Engine, Reducers } from "../runtime/loop";
-import * as Feature from "./feature";
-import { type EngineServices, featureModule, mountFeature } from "./feature";
+import { type Cause, Context, Duration, Effect, Exit, Layer, Scope } from 'effect'
+import { Schema as S } from 'effect'
+import { expect, it } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { mount } from '../compose/structure'
+import { ui } from '../compose/ui'
+import * as Event from '../event/event'
+import * as Reducer from '../reducer/reducer'
+import * as State from '../state/state'
+import { publish } from '../runtime/bus'
+import { Engine, Reducers } from '../runtime/loop'
+import * as Feature from './feature'
+import { type EngineServices, featureModule, mountFeature } from './feature'
 
 // A self-contained feature: a Count state + a reducer that folds Tick. The base
 // seeds Count; the logic provides the reducer over it and leaves the engine
 // (Reducers registry) OPEN, so `mountFeature` builds it against the live engine.
-class Tick extends Event.make("Tick", S.Struct({})) {}
-class Count extends State.make("count", S.Number) {}
-class CountReducer extends Reducer.make("CountReducer", {
+class Tick extends Event.make('Tick', S.Struct({})) {}
+class Count extends State.make('count', S.Number) {}
+class CountReducer extends Reducer.make('CountReducer', {
   states: [Count],
   events: [Tick],
 }) {}
 
-const mod = featureModule(
-  [],
-  Reducer.live(CountReducer, (n) => n + 1).pipe(
-    Layer.provideMerge(State.live(Count, 0)),
-  ),
-);
+class MountedCounterProbe extends Context.Tag('test/MountedCounterProbe')<
+  MountedCounterProbe,
+  { readonly value: number }
+>() {}
+
+class LazyMountedProbe extends Context.Tag('test/LazyMountedProbe')<
+  LazyMountedProbe,
+  { readonly value: string }
+>() {}
+
+class UnmountedProbe extends Context.Tag('test/UnmountedProbe')<
+  UnmountedProbe,
+  { readonly value: boolean }
+>() {}
 
 // A trivial composition to hang the feature off (definitions only).
-class CtrUi extends ui("CtrUi")<{ props: {}; events: {} }>() {}
-class CtrComp extends Composition.make("CtrComp", {
-  title: "Counter",
+class CtrUi extends ui('CtrUi')<{ props: {}; events: {} }>() {}
+class CtrComp extends Composition.make('CtrComp', {
+  title: 'Counter',
   ui: CtrUi,
-}) {}
+})<CtrComp>() {}
 
-class CounterFeature extends Feature.make("counter", {
+const CtrLive = Composition.live(CtrComp, function* () {
+  return mount({ props: {}, slots: {} })
+})
+
+const mod = featureModule(
+  [],
+  Layer.mergeAll(
+    CtrLive,
+    Reducer.live(CountReducer, (n) => n + 1).pipe(Layer.provideMerge(State.live(Count, 0))),
+    Layer.succeed(MountedCounterProbe, { value: 42 }),
+  ),
+)
+
+class CounterFeature extends Feature.make('counter', {
   composition: CtrComp,
   module: mod,
   boot: [Event.construct(Tick, {})],
 }) {}
 
+const lazyMod = featureModule(
+  [],
+  Layer.merge(CtrLive, Layer.succeed(LazyMountedProbe, { value: 'lazy' })),
+)
+
+class LazyCounterFeature extends Feature.make('lazy-counter', {
+  composition: CtrComp,
+  loadingStrategy: 'lazy',
+  load: Effect.succeed(lazyMod),
+  placeholder: { loading: CtrComp, failed: CtrComp },
+}) {}
+
+const CounterNative = Feature.tree<typeof CounterFeature>(CounterFeature.token)
+const LazyCounterNative = Feature.tree<typeof LazyCounterFeature>(LazyCounterFeature.token)
+
+const mountCounterFeature = (engineContext: Context.Context<EngineServices>) =>
+  mountFeature(CounterNative.binding, engineContext)
+
+const mountLazyCounterFeature = (engineContext: Context.Context<EngineServices>) =>
+  mountFeature(LazyCounterNative.binding, engineContext)
+
+type ContextServices<C> = C extends Context.Context<infer Services> ? Services : never
+type EagerMountedServices = ContextServices<
+  Effect.Effect.Success<ReturnType<typeof mountCounterFeature>>
+>
+type LazyMountedServices = ContextServices<
+  Effect.Effect.Success<ReturnType<typeof mountLazyCounterFeature>>
+>
+type Includes<Services, Candidate> = Candidate extends Services ? true : false
+
+const mountedServiceTypeProof: readonly [
+  Includes<EagerMountedServices, MountedCounterProbe>,
+  Includes<EagerMountedServices, UnmountedProbe>,
+  Includes<LazyMountedServices, LazyMountedProbe>,
+  Includes<LazyMountedServices, UnmountedProbe>,
+] = [true, false, true, false]
+
 // Poll a read until it satisfies a predicate (the loop drains on a forked fiber).
 const waitUntil = <A, R>(
   read: Effect.Effect<A, never, R>,
@@ -49,46 +108,54 @@ const waitUntil = <A, R>(
   Effect.flatMap(read, (a) =>
     pred(a)
       ? Effect.succeed(a)
-      : Effect.flatMap(Effect.sleep(Duration.millis(1)), () =>
-          waitUntil(read, pred),
-        ),
-  ).pipe(Effect.timeout(Duration.seconds(2)));
+      : Effect.flatMap(Effect.sleep(Duration.millis(1)), () => waitUntil(read, pred)),
+  ).pipe(Effect.timeout(Duration.seconds(2)))
 
 it.scopedLive(
-  "a mounted feature registers on the shared loop, boots, and folds dispatched events",
+  'a mounted feature registers on the shared loop, boots, and folds dispatched events',
   () =>
     Effect.gen(function* () {
-      const engineContext = yield* Effect.context<EngineServices>();
-      const reducers = yield* Reducers;
-      const baseline = reducers.entries.length;
-
-      const scope = yield* Scope.make();
-      const ctx = yield* mountFeature(
-        CounterFeature.binding,
-        engineContext,
-      ).pipe(Effect.provideService(Scope.Scope, scope));
+      const engineContext = yield* Effect.context<EngineServices>()
+      const reducers = yield* Reducers
+      const baseline = reducers.entries.length
+
+      const scope = yield* Scope.make()
+      const ctx = yield* mountCounterFeature(engineContext).pipe(
+        Effect.provideService(Scope.Scope, scope),
+      )
+      expect(mountedServiceTypeProof).toEqual([true, false, true, false])
+      expect(Context.get(ctx, MountedCounterProbe).value).toBe(42)
+      expect(Context.getOption(ctx, UnmountedProbe)._tag).toBe('None')
       // Registered into the SHARED registry.
-      expect(reducers.entries.length).toBe(baseline + 1);
+      expect(reducers.entries.length).toBe(baseline + 1)
 
       // boot dispatched Tick → Count folds to 1 on the shared loop.
-      const booted = yield* waitUntil(
-        Count.pipe(Effect.provide(ctx)),
-        (n) => n === 1,
-      );
-      expect(booted).toBe(1);
+      const booted = yield* waitUntil(Count.pipe(Effect.provide(ctx)), (n) => n === 1)
+      expect(booted).toBe(1)
 
       // A further dispatch on the shared bus folds again → 2.
-      yield* publish("High", Event.construct(Tick, {}));
-      const folded = yield* waitUntil(
-        Count.pipe(Effect.provide(ctx)),
-        (n) => n === 2,
-      );
-      expect(folded).toBe(2);
+      yield* publish('High', Event.construct(Tick, {}))
+      const folded = yield* waitUntil(Count.pipe(Effect.provide(ctx)), (n) => n === 2)
+      expect(folded).toBe(2)
 
       // Unmount: closing the feature scope unregisters its reducer — the entry is
       // reclaimed, not left folding onto an orphaned store.
-      yield* Scope.close(scope, Exit.succeed(undefined));
-      expect(reducers.entries.length).toBe(baseline);
-      expect(reducers.byTag.get("Tick")).toBeUndefined();
+      yield* Scope.close(scope, Exit.succeed(undefined))
+      expect(reducers.entries.length).toBe(baseline)
+      expect(reducers.byTag.get('Tick')).toBeUndefined()
     }).pipe(Effect.provide(Engine)),
-);
+)
+
+it.scopedLive('a lazy feature retains its mounted service type', () =>
+  Effect.gen(function* () {
+    const engineContext = yield* Effect.context<EngineServices>()
+    const scope = yield* Scope.make()
+    const ctx = yield* mountLazyCounterFeature(engineContext).pipe(
+      Effect.provideService(Scope.Scope, scope),
+    )
+
+    expect(Context.get(ctx, LazyMountedProbe).value).toBe('lazy')
+    expect(Context.getOption(ctx, UnmountedProbe)._tag).toBe('None')
+    yield* Scope.close(scope, Exit.succeed(undefined))
+  }).pipe(Effect.provide(Engine)),
+)

package/src/feature/feature.test.ts

@@ -1,81 +1,85 @@
-import { Effect, Layer, Option } from "effect";
-import { expect, it } from "@effect/vitest";
-import * as Composition from "../compose/composition";
-import { ui } from "../compose/ui";
-import * as Feature from "./feature";
-import {
-  featureModule,
-  isFeature,
-  isFeatureBinding,
-  lazyImport,
-} from "./feature";
+import { Effect, Option } from 'effect'
+import { expect, it } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { mount } from '../compose/structure'
+import { ui } from '../compose/ui'
+import * as Feature from './feature'
+import { featureModule, isFeature, isFeatureBinding, lazyImport } from './feature'
 
 // Minimal composition surface to hang features off — definitions only, no logic.
-class TestUi extends ui("TestUi")<{ props: {}; events: {} }>() {}
-class TestComp extends Composition.make("TestComp", {
-  title: "Test",
+class TestUi extends ui('TestUi')<{ props: {}; events: {} }>() {}
+class TestComp extends Composition.make('TestComp', {
+  title: 'Test',
   ui: TestUi,
-}) {}
-class FailComp extends Composition.make("FailComp", {
-  title: "Fail",
+})<TestComp>() {}
+class FailComp extends Composition.make('FailComp', {
+  title: 'Fail',
   ui: TestUi,
-}) {}
+})<FailComp>() {}
+
+const TestLive = Composition.live(TestComp, function* () {
+  return mount({ props: {}, slots: {} })
+})
 
-// A trivial loaded module: empty layer, no shared requirements.
-const mod = featureModule([], Layer.empty);
+// A valid Feature module owns its declared root Composition service.
+const mod = featureModule([], TestLive)
 
-class LazyFeature extends Feature.make("lazyFeature", {
-  loadingStrategy: "lazy",
+class LazyFeature extends Feature.make('lazyFeature', {
+  loadingStrategy: 'lazy',
   composition: TestComp,
   load: lazyImport(() => Promise.resolve({ default: mod })),
   placeholder: { loading: TestComp, failed: FailComp },
 }) {}
 
-class EagerFeature extends Feature.make("eagerFeature", {
+class SameShapeFeature extends Feature.make('lazyFeature', {
+  loadingStrategy: 'lazy',
+  composition: TestComp,
+  load: lazyImport(() => Promise.resolve({ default: mod })),
+  placeholder: { loading: TestComp, failed: FailComp },
+}) {}
+
+class EagerFeature extends Feature.make('eagerFeature', {
   composition: TestComp,
   module: mod,
 }) {}
 
-it("a lazy feature reflects as a Feature manifest with placeholders, no chunk loaded", () => {
-  expect(LazyFeature.manifest.kind).toBe("Feature");
-  expect(LazyFeature.manifest.name).toBe("lazyFeature");
-  expect(LazyFeature.manifest.strategy).toBe("lazy");
-  expect(LazyFeature.manifest.composition.name).toBe("TestComp");
-  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).loading.name).toBe(
-    "TestComp",
-  );
-  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).failed.name).toBe(
-    "FailComp",
-  );
-  expect(LazyFeature.eagerModule).toBeUndefined();
-});
+const LazyNative = Feature.tree<typeof LazyFeature>(LazyFeature.token)
+const EagerNative = Feature.tree<typeof EagerFeature>(EagerFeature.token)
+
+it('a lazy feature reflects as a Feature manifest with placeholders, no chunk loaded', () => {
+  expect(LazyFeature.manifest.kind).toBe('Feature')
+  expect(LazyFeature.manifest.name).toBe('lazyFeature')
+  expect(LazyFeature.manifest.strategy).toBe('lazy')
+  expect(LazyFeature.manifest.composition.name).toBe('TestComp')
+  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).loading.name).toBe('TestComp')
+  expect(Option.getOrThrow(LazyFeature.manifest.placeholder).failed.name).toBe('FailComp')
+  expect(LazyNative.eagerModule).toBeUndefined()
+})
 
-it("an eager feature reflects as default strategy with its module available", () => {
-  expect(EagerFeature.manifest.strategy).toBe("default");
-  expect(Option.isNone(EagerFeature.manifest.placeholder)).toBe(true);
-  expect(EagerFeature.eagerModule).toBe(mod);
-});
+it('an eager feature reflects as default strategy with its module available', () => {
+  expect(EagerFeature.manifest.strategy).toBe('default')
+  expect(Option.isNone(EagerFeature.manifest.placeholder)).toBe(true)
+  expect(EagerNative.eagerModule).toBe(mod)
+})
 
-it("isFeature / isFeatureBinding discriminate", () => {
-  expect(isFeature(LazyFeature)).toBe(true);
-  expect(isFeature(TestComp)).toBe(false);
-  expect(isFeature(null)).toBe(false);
-  expect(isFeatureBinding(LazyFeature.binding)).toBe(true);
-  expect(isFeatureBinding(TestComp)).toBe(false);
-});
+it('isFeature / isFeatureBinding discriminate', () => {
+  expect(isFeature(LazyFeature)).toBe(true)
+  expect(isFeature(TestComp)).toBe(false)
+  expect(isFeature(null)).toBe(false)
+  expect(isFeatureBinding(LazyNative.binding)).toBe(true)
+  expect(isFeatureBinding(TestComp)).toBe(false)
+  expect(LazyFeature.token).not.toBe(SameShapeFeature.token)
+  expect(LazyFeature.token.identity).not.toBe(SameShapeFeature.token.identity)
+})
 
-it.live(
-  "load is an Effect (not a thenable) that yields the module and its requires",
-  () =>
-    Effect.gen(function* () {
-      // No `.then` on `load` — it is an Effect, run on the Effect runtime.
-      expect(typeof (LazyFeature.load as { then?: unknown }).then).toBe(
-        "undefined",
-      );
-      const loaded = yield* LazyFeature.load;
-      expect(loaded.requires).toEqual([]);
-      expect(loaded).toBe(mod);
-      // default strategy resolves immediately to its module.
-      expect(yield* EagerFeature.load).toBe(mod);
-    }),
-);
+it.live('load is an Effect (not a thenable) that yields the module and its requires', () =>
+  Effect.gen(function* () {
+    // No `.then` on `load` — it is an Effect, run on the Effect runtime.
+    expect('then' in LazyNative.load).toBe(false)
+    const loaded = yield* LazyNative.load
+    expect(loaded.requires).toEqual([])
+    expect(loaded).toBe(mod)
+    // default strategy resolves immediately to its module.
+    expect(yield* EagerNative.load).toBe(mod)
+  }),
+)