@playfast/reform-proof 1.1.1 → 1.2.1

package/src/facade.ts

@@ -1,258 +1,78 @@
-import { Array as Arr, Effect, ManagedRuntime, Option, Schema as S } from 'effect'
-import {
-  Composition,
-  type CompositionClass,
-  type CompositionService,
-  isStructure,
-  type RenderEnv,
-  type SlotChild,
-  type SlotClass,
-  type Trigger,
-  type UiCapture,
-  type UiContract,
+import type { Duration, Effect } from 'effect'
+import type {
+  SlotContract as ReformSlotContract,
+  Trigger,
+  UiContract,
 } from '@playfast/reform'
-import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
-import { matchProps } from './assertions'
-import type { Action, Facade, SlotFacade } from './index'
-import {
-  keyed,
-  SETTLE_MAX_RENDERS,
-  SETTLE_STEP,
-  settleDrain,
-  type RuntimeServices,
-  type Sink,
-  uiNameOf,
-} from './sink'
-import {
-  collectBindings,
-  driveStructure,
-  type Mounted,
-  type NodeRef,
-  type SettleProgress,
-  slotsOf,
-} from './treeBindings'
 
-type AnyFacade = Facade<UiContract>
-type AnySlotFacade = SlotFacade<UiContract>
-const encodeUnknown = S.encodeSync(S.parseJson(S.Unknown))
+export type EventsOf<C extends UiContract> = C extends {
+  readonly events: infer E extends NonNullable<UiContract['events']>
+}
+  ? E
+  : Readonly<Record<PropertyKey, never>>
+export type EventNamesOf<C extends UiContract> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? keyof EventsOf<C>
+  : never
+export type SlotsOf<C extends UiContract> = C extends {
+  readonly slots: infer S extends NonNullable<UiContract['slots']>
+}
+  ? S
+  : Readonly<Record<PropertyKey, never>>
+export type PayloadOf<T> = T extends Trigger<infer P> ? P : never
+export type ContractOf<Comp> = Comp extends {
+  readonly Contract: infer C extends UiContract
+}
+  ? C
+  : never
+export type ContractOfSlot<S> = ReformSlotContract<S>
 
-const renderMounted = Effect.fn('renderMounted')(function* (
-  mounted: Mounted,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<ReadonlyArray<Mounted>, never, CompositionService> {
-  const service = yield* mounted.comp.tag
-  const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
-  const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(mounted.comp))
-  const frame = yield* Composition.render(service, env)
-  endRenderSpan()
-  if (!isStructure(frame)) {
-    return yield* Effect.dieMessage(
-      `reform-proof: composition ${uiNameOf(mounted.comp)} did not return a Structure`,
-    )
-  }
-  return driveStructure(mounted.comp, frame, mounted.key, sink, bindings)
-})
-
-const renderLevel: (
-  frontier: ReadonlyArray<Mounted>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-) => Effect.Effect<void, never, CompositionService> = Effect.fn('renderLevel')(function* (
-  frontier: ReadonlyArray<Mounted>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  if (frontier.length === 0) {
-    return
-  }
-  const levels = yield* Effect.forEach(frontier, (mounted) =>
-    renderMounted(mounted, bindings, sink),
-  )
-  yield* renderLevel(levels.flat(), bindings, sink)
-})
-
-const renderTree = Effect.fn('renderTree')(function* (
-  root: CompositionClass<unknown>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  sink.reset()
-  yield* renderLevel([{ comp: root, props: {}, key: Option.none() }], bindings, sink)
-})
-
-export const capturesFor = (sink: Sink, name: string): ReadonlyArray<UiCapture> =>
-  sink.captures.filter((capture) => capture.name === name)
-
-export const fingerprint = (sink: Sink): string =>
-  encodeUnknown(sink.captures.map((capture) => [capture.name, capture.props]))
-
-const settleTree = Effect.fn('settleTree')(function* (
-  root: CompositionClass<unknown>,
-  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  sink: Sink,
-): Effect.fn.Return<void, never, CompositionService> {
-  yield* settleDrain
-  yield* renderTree(root, bindings, sink)
-  yield* Effect.iterate(
-    {
-      previous: fingerprint(sink),
-      remaining: SETTLE_MAX_RENDERS,
-      stable: false,
-    },
-    {
-      while: (progress: SettleProgress) => !progress.stable && progress.remaining > 0,
-      body: (progress) =>
-        Effect.gen(function* () {
-          yield* settleDrain
-          yield* Effect.sleep(SETTLE_STEP)
-          yield* renderTree(root, bindings, sink)
-          const current = fingerprint(sink)
-          return {
-            previous: current,
-            remaining: progress.remaining - 1,
-            stable: current === progress.previous,
-          }
-        }),
-    },
-  )
-})
-
-export const makeFacadeEffect: (
-  root: CompositionClass<unknown>,
-  sink: Sink,
-  dispatched: Set<string>,
-) => Effect.Effect<
-  {
-    readonly facade: AnyFacade
-    readonly settle: Effect.Effect<void, never, CompositionService>
-  },
-  never,
-  SlotChild
-> = Effect.fn('makeFacadeEffect')(function* (
-  root: CompositionClass<unknown>,
-  sink: Sink,
-  dispatched: Set<string>,
-): Effect.fn.Return<
-  {
-    readonly facade: AnyFacade
-    readonly settle: Effect.Effect<void, never, CompositionService>
-  },
-  never,
-  SlotChild
-> {
-  const bindings = yield* collectBindings(root)
-  const settle = settleTree(root, bindings, sink)
-  const rerender = renderTree(root, bindings, sink)
-
-  const triggerOf = (ref: NodeRef, event: string): Effect.Effect<Trigger<unknown>> =>
-    Option.match(Option.fromNullable(capturesFor(sink, ref.name)[ref.index]?.events[event]), {
-      onNone: () =>
-        Effect.dieMessage(
-          new UnknownAction({
-            composition: ref.name,
-            action: event,
-            rendered: capturesFor(sink, ref.name).length,
-          }).message,
-        ),
-      onSome: Effect.succeed,
-    })
-
-  const propsFor = (ref: NodeRef): Effect.Effect<unknown, never, CompositionService> =>
-    Effect.map(rerender, () => capturesFor(sink, ref.name)[ref.index]?.props)
-
-  const nodeFacade = (ref: NodeRef, comp: CompositionClass<unknown>): AnyFacade => ({
-    props: propsFor(ref),
-    expectProps: (partial) =>
-      propsFor(ref).pipe(
-        Effect.flatMap((props) => {
-          const mismatch = matchProps({ actual: props, expected: partial })
-          return mismatch === undefined
-            ? Effect.void
-            : Effect.dieMessage(new AssertionFailed({ detail: mismatch }).message)
-        }),
-      ),
-    actions: keyed(
-      (event): Action =>
-        (payload) =>
-          rerender.pipe(
-            Effect.flatMap(() => triggerOf(ref, event)),
-            Effect.flatMap((trigger) =>
-              Effect.sync(() => {
-                dispatched.add(event)
-                trigger(payload)
-              }),
-            ),
-            Effect.flatMap(() => settle),
-            Effect.flatMap(() => propsFor(ref)),
-          ),
-    ),
-    slots: keyed((slotName) => slotFacade(comp, slotName)),
-    frame: settle,
-  })
-
-  const slotFacade = (parent: CompositionClass<unknown>, slotName: string): AnySlotFacade => {
-    const slotClass = slotsOf(parent)[slotName]
-    const child = slotClass && bindings.get(slotClass)
-    if (child === undefined) {
-      return Effect.runSync(
-        Effect.dieMessage(new UnknownSlot({ parent: uiNameOf(parent), slot: slotName }).message),
-      )
+export type ActionsOf<C extends UiContract, R = never> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? {
+      readonly [K in keyof EventsOf<C>]: (
+        payload: PayloadOf<EventsOf<C>[K]>,
+      ) => Effect.Effect<C['props'], never, R>
     }
-    const childName = uiNameOf(child)
-    const atIndex = (index: number): Effect.Effect<AnyFacade, never, CompositionService> =>
-      Effect.as(rerender, nodeFacade({ name: childName, index }, child))
-    const first = nodeFacade({ name: childName, index: 0 }, child)
-    const indexOfKey = (key: string): Option.Option<number> =>
-      Arr.findFirstIndex(capturesFor(sink, childName), (capture) => capture.key === key)
-    return {
-      first: atIndex(0),
-      at: atIndex,
-      all: Effect.map(rerender, () =>
-        capturesFor(sink, childName).map((_capture, index) =>
-          nodeFacade({ name: childName, index }, child),
-        ),
-      ),
-      byKey: (key) =>
-        Effect.flatMap(rerender, () =>
-          Option.match(indexOfKey(key), {
-            onNone: () =>
-              Effect.dieMessage(
-                new UnknownSlot({
-                  parent: uiNameOf(parent),
-                  slot: `${slotName}[key=${key}]`,
-                }).message,
-              ),
-            onSome: (index) => Effect.succeed(nodeFacade({ name: childName, index }, child)),
-          }),
-        ),
-      where: (predicate) =>
-        Effect.map(rerender, () =>
-          capturesFor(sink, childName).flatMap((capture, index) =>
-            predicate(capture.props) ? [nodeFacade({ name: childName, index }, child)] : [],
-          ),
-        ),
-      count: Effect.map(rerender, () => capturesFor(sink, childName).length),
-      props: first.props,
-      expectProps: first.expectProps,
-      actions: first.actions,
-      slots: first.slots,
-      frame: first.frame,
+  : Readonly<Record<PropertyKey, never>>
+export type SlotFacadesOf<C extends UiContract, R = never> = C extends {
+  readonly slots: NonNullable<UiContract['slots']>
+}
+  ? {
+      readonly [K in keyof SlotsOf<C>]: SlotFacade<ContractOfSlot<SlotsOf<C>[K]>, R>
     }
-  }
+  : Readonly<Record<PropertyKey, never>>
+
+export type Action<R = never> = (payload: unknown) => Effect.Effect<unknown, never, R>
 
-  return {
-    facade: nodeFacade({ name: uiNameOf(root), index: 0 }, root),
-    settle,
-  }
-})
+export interface Facade<C extends UiContract, R = never> {
+  readonly props: Effect.Effect<C['props'], never, R>
+  readonly expectProps: (partial: Partial<C['props']>) => Effect.Effect<void, never, R>
+  readonly actions: ActionsOf<C, R>
+  readonly slots: SlotFacadesOf<C, R>
+  readonly frame: Effect.Effect<void, never, R>
+  /**
+   * Elapse `duration` of the scene's product time, then settle. Every timer the
+   * scene's procedures hold — `Effect.sleep`, `Schedule`, `Clock` reads — moves by
+   * exactly this much and no real time passes, so a 1500ms poll interval is observed
+   * in microseconds and never races the runner.
+   *
+   * Requires the scene's layers to be wrapped in `Proof.withTestClock(...)`. Against
+   * the real clock there is no virtual time to move, so the proof dies with
+   * `NoTestClock` instead of silently doing nothing.
+   */
+  readonly advance: (duration: Duration.DurationInput) => Effect.Effect<void, never, R>
+}
 
-export const makeFacade = (
-  runtime: ManagedRuntime.ManagedRuntime<RuntimeServices, never>,
-  root: CompositionClass<unknown>,
-  sink: Sink,
-  dispatched: Set<string>,
-): {
-  readonly facade: AnyFacade
-  readonly settle: Effect.Effect<void, never, CompositionService>
-} => runtime.runSync(makeFacadeEffect(root, sink, dispatched))
+export interface SlotFacade<C extends UiContract, R = never> extends Facade<C, R> {
+  readonly first: Effect.Effect<Facade<C, R>, never, R>
+  readonly at: (index: number) => Effect.Effect<Facade<C, R>, never, R>
+  readonly all: Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly byKey: (key: string) => Effect.Effect<Facade<C, R>, never, R>
+  readonly where: (
+    predicate: (props: C['props']) => boolean,
+  ) => Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly count: Effect.Effect<number, never, R>
+}

package/src/fingerprint.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { formatFingerprint } from './fingerprint'
+
+describe('proof render fingerprints', () => {
+  it('distinguishes bigint props from strings without throwing', () => {
+    expect(formatFingerprint({ sequence: 1n })).not.toBe(formatFingerprint({ sequence: '1' }))
+  })
+
+  it('stabilizes equivalent cyclic render props', () => {
+    const left: Array<unknown> = []
+    left.push(left)
+    const right: Array<unknown> = []
+    right.push(right)
+
+    expect(formatFingerprint(left)).toBe(formatFingerprint(right))
+  })
+
+  it('tracks Map and Set contents', () => {
+    expect(formatFingerprint(new Map([['feature', 'home']]))).not.toBe(
+      formatFingerprint(new Map([['feature', 'tasks']])),
+    )
+    expect(formatFingerprint(new Set(['home']))).not.toBe(formatFingerprint(new Set(['tasks'])))
+  })
+})

package/src/fingerprint.ts

@@ -0,0 +1,73 @@
+import * as Option from 'effect/Option'
+
+const readPropertyOption = Option.liftThrowable((target: object, key: PropertyKey): unknown =>
+  Reflect.get(target, key),
+)
+
+const readProperty = (target: object, key: PropertyKey): unknown =>
+  Option.getOrElse(readPropertyOption(target, key), () => '[Property read threw]')
+
+const propertyKeyFingerprint = (key: PropertyKey): string =>
+  typeof key === 'symbol'
+    ? `symbol:${String(key.description)}`
+    : typeof key === 'number'
+      ? `number-key:${String(key)}`
+      : `key:${key.length}:${key}`
+
+const valueFingerprint = (candidate: unknown, seen: WeakSet<object>): string => {
+  if (typeof candidate === 'bigint') {
+    return `bigint:${String(candidate)}`
+  }
+  if (typeof candidate === 'boolean') {
+    return candidate ? 'boolean:true' : 'boolean:false'
+  }
+  if (typeof candidate === 'function') {
+    return `function:${String(candidate)}`
+  }
+  if (typeof candidate === 'number') {
+    return `number:${String(candidate)}`
+  }
+  if (typeof candidate === 'string') {
+    return `string:${candidate.length}:${candidate}`
+  }
+  if (typeof candidate === 'symbol') {
+    return `symbol:${String(candidate.description)}`
+  }
+  if (typeof candidate === 'undefined') {
+    return 'undefined'
+  }
+  if (candidate === null) {
+    return 'null'
+  }
+  if (seen.has(candidate)) {
+    return '[Circular]'
+  }
+  seen.add(candidate)
+  if (Array.isArray(candidate)) {
+    return `[${candidate.map((arrayEntry) => valueFingerprint(arrayEntry, seen)).join(',')}]`
+  }
+  if (candidate instanceof Date) {
+    return `date:${String(candidate.getTime())}`
+  }
+  if (candidate instanceof Map) {
+    return `map:[${Array.from(
+      candidate,
+      ([mapKey, mapEntry]) =>
+        `${valueFingerprint(mapKey, seen)}=>${valueFingerprint(mapEntry, seen)}`,
+    ).join(',')}]`
+  }
+  if (candidate instanceof Set) {
+    return `set:[${Array.from(candidate, (setEntry) => valueFingerprint(setEntry, seen)).join(
+      ',',
+    )}]`
+  }
+  return `{${Reflect.ownKeys(candidate)
+    .map(
+      (key) =>
+        `${propertyKeyFingerprint(key)}:${valueFingerprint(readProperty(candidate, key), seen)}`,
+    )
+    .join(',')}}`
+}
+
+export const formatFingerprint = (fingerprintInput: unknown): string =>
+  valueFingerprint(fingerprintInput, new WeakSet())