@playfast/reform-proof 0.1.0 → 1.1.1

package/src/runtimeFacade.ts

@@ -0,0 +1,269 @@
+import { Array as Arr, Effect, Option, Record as Rec } from 'effect'
+import {
+  Composition,
+  type CompositionClass,
+  isStructure,
+  type RenderEnv,
+  type RuntimeHandle,
+  type SlotClass,
+  type Trigger,
+} from '@playfast/reform'
+import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
+import { matchProps } from './assertions'
+import { capturesFor, fingerprint } from './facade'
+import {
+  keyed,
+  SETTLE_MAX_RENDERS,
+  SETTLE_STEP,
+  settleDrain,
+  type Sink,
+  uiNameOf,
+} from './sink'
+import {
+  childComposition,
+  driveStructure,
+  type Mounted,
+  type NodeRef,
+  type SettleProgress,
+  slotsOf,
+} from './treeBindings'
+
+export interface MountedFacade {
+  readonly props: Effect.Effect<unknown, never, never>
+  readonly expectProps: (partial: unknown) => Effect.Effect<void, never, never>
+  readonly actions: Record<string, (payload: unknown) => Effect.Effect<unknown, never, never>>
+  readonly slots: Record<string, MountedSlotFacade>
+  readonly frame: Effect.Effect<void, never, never>
+}
+
+export interface MountedSlotFacade extends MountedFacade {
+  readonly first: Effect.Effect<MountedFacade, never, never>
+  readonly at: (index: number) => Effect.Effect<MountedFacade, never, never>
+  readonly all: Effect.Effect<ReadonlyArray<MountedFacade>, never, never>
+  readonly byKey: (key: string) => Effect.Effect<MountedFacade, never, never>
+  readonly where: (
+    predicate: (props: unknown) => boolean,
+  ) => Effect.Effect<ReadonlyArray<MountedFacade>, never, never>
+  readonly count: Effect.Effect<number, never, never>
+}
+
+const collectRuntimeBindings = (
+  root: CompositionClass<unknown>,
+  runtime: RuntimeHandle,
+): Map<SlotClass, CompositionClass<unknown>> => {
+  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+  const walk = (comp: CompositionClass<unknown>): void => {
+    Rec.values(slotsOf(comp)).forEach((slotClass) => {
+      if (bindings.has(slotClass)) {
+        return
+      }
+      const child = childComposition(runtime.read(slotClass.tag))
+      bindings.set(slotClass, child)
+      walk(child)
+    })
+  }
+  walk(root)
+  return bindings
+}
+
+const renderMountedRuntime = (
+  runtime: RuntimeHandle,
+  mounted: Mounted,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  sink: Sink,
+): ReadonlyArray<Mounted> => {
+  const service = runtime.read(mounted.comp.tag)
+  const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
+  const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(mounted.comp))
+  const frame = Effect.runSync(Composition.render(service, env))
+  endRenderSpan()
+  if (!isStructure(frame)) {
+    return Effect.runSync(
+      Effect.dieMessage(
+        `reform-proof: composition ${uiNameOf(mounted.comp)} did not return a Structure`,
+      ),
+    )
+  }
+  return driveStructure(mounted.comp, frame, mounted.key, sink, bindings)
+}
+
+const renderLevelRuntime = (
+  runtime: RuntimeHandle,
+  frontier: ReadonlyArray<Mounted>,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  sink: Sink,
+): void => {
+  if (frontier.length === 0) {
+    return
+  }
+  const levels = frontier.map((mounted) => renderMountedRuntime(runtime, mounted, bindings, sink))
+  renderLevelRuntime(runtime, levels.flat(), bindings, sink)
+}
+
+const renderTreeRuntime = (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  sink: Sink,
+): Effect.Effect<void, never, never> =>
+  Effect.sync(() => {
+    sink.reset()
+    renderLevelRuntime(runtime, [{ comp: root, props: {}, key: Option.none() }], bindings, sink)
+  })
+
+const settleTreeRuntime = Effect.fn('settleTreeRuntime')(function* (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  sink: Sink,
+): Effect.fn.Return<void, never, never> {
+  yield* settleDrain
+  yield* renderTreeRuntime(runtime, 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* renderTreeRuntime(runtime, root, bindings, sink)
+          const current = fingerprint(sink)
+          return {
+            previous: current,
+            remaining: progress.remaining - 1,
+            stable: current === progress.previous,
+          }
+        }),
+    },
+  )
+})
+
+const makeMountedFacade = (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+  dispatched: Set<string>,
+): {
+  readonly facade: MountedFacade
+  readonly settle: Effect.Effect<void, never, never>
+} => {
+  const bindings = collectRuntimeBindings(root, runtime)
+  const settle = settleTreeRuntime(runtime, root, bindings, sink)
+  const rerender = renderTreeRuntime(runtime, root, bindings, sink)
+
+  const triggerOf = (ref: NodeRef, event: string): Effect.Effect<Trigger<unknown>, never, never> =>
+    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, never> =>
+    Effect.map(rerender, () => capturesFor(sink, ref.name)[ref.index]?.props)
+
+  const nodeFacade = (ref: NodeRef, comp: CompositionClass<unknown>): MountedFacade => ({
+    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) => (payload: unknown) =>
+        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): MountedSlotFacade => {
+    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),
+      )
+    }
+    const childName = uiNameOf(child)
+    const atIndex = (index: number): Effect.Effect<MountedFacade, never, never> =>
+      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,
+    }
+  }
+
+  return {
+    facade: nodeFacade({ name: uiNameOf(root), index: 0 }, root),
+    settle,
+  }
+}
+
+export const makeRuntimeHandleFacade = (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+  dispatched: Set<string>,
+): {
+  readonly facade: MountedFacade
+  readonly settle: Effect.Effect<void, never, never>
+} => makeMountedFacade(runtime, root, sink, dispatched)
+

package/src/runtimeTreeDispose.ts

@@ -0,0 +1,21 @@
+import { Array as Arr, Order } from 'effect'
+import type { TreeFeatureMount } from './runtimeTreeTypes'
+
+interface DisposeTreeMountsOptions {
+  readonly status: { disposed: boolean }
+  readonly mounts: Map<string, TreeFeatureMount>
+}
+
+export const disposeTreeMounts = ({ status, mounts }: DisposeTreeMountsOptions): void => {
+  if (status.disposed) {
+    return
+  }
+  status.disposed = true
+  Arr.sortWith(Array.from(mounts.values()), (record) => -record.depth, Order.number).forEach(
+    (record) => {
+      record.attempt += 1
+      record.dispose()
+    },
+  )
+  mounts.clear()
+}

package/src/runtimeTreeDriver.ts

@@ -0,0 +1,285 @@
+import { Array as Arr, Effect, Match, Option, Order, Record as Rec, Schema as S } from 'effect'
+import {
+  Composition,
+  type CompositionClass,
+  isFeatureBinding,
+  isStructure,
+  type RenderEnv,
+  type RuntimeHandle,
+} from '@playfast/reform'
+import { eventsOf, type Sink, uiNameOf } from './sink'
+import { slotsOf, structureFills } from './treeBindings'
+import { disposeTreeMounts } from './runtimeTreeDispose'
+import { makeTreeSettle } from './runtimeTreeSettle'
+import {
+  encodeIdentityPart,
+  type FeatureRecordInput,
+  fillEntries,
+  type MountIdentityInput,
+  type RenderCompositionInput,
+  type TreeDriver,
+  type TreeFeatureMount,
+  type TreeNode,
+  type TreeRenderState,
+  treeFingerprint,
+} from './runtimeTreeTypes'
+
+const encodeUnknown = S.encodeSync(S.parseJson(S.Unknown))
+
+export const makeTreeDriver = (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+): TreeDriver => {
+  const mounts = new Map<string, TreeFeatureMount>()
+  const runtimeIds = new WeakMap<RuntimeHandle, number>()
+  const bindingIds = new WeakMap<object, number>()
+  const sequence = { runtime: 0, binding: 0 }
+  const status = { disposed: false }
+
+  const identity = (
+    identities: WeakMap<object, number>,
+    subject: object,
+    next: () => number,
+  ): number => {
+    const current = identities.get(subject)
+    if (current !== undefined) {
+      return current
+    }
+    const created = next()
+    identities.set(subject, created)
+    return created
+  }
+
+  const mountId = ({ parent, parentPath, slotName, key, binding }: MountIdentityInput): string => {
+    const runtimeId = identity(runtimeIds, parent, () => ++sequence.runtime)
+    const bindingId = identity(bindingIds, binding, () => ++sequence.binding)
+    return [String(runtimeId), parentPath, slotName, String(bindingId), key]
+      .map(encodeIdentityPart)
+      .join('')
+  }
+
+  const startMount = (record: TreeFeatureMount): void => {
+    record.attempt += 1
+    const attempt = record.attempt
+    if (record.binding.strategy === 'default') {
+      record.state = { _tag: 'Live', runtime: record.parent }
+      record.binding.boot.forEach((event) => record.parent.dispatch('High', event))
+      record.dispose = () => {}
+      return
+    }
+    record.state = { _tag: 'Loading' }
+    record.dispose = record.parent.mountFeature(record.binding, {
+      props: record.props,
+      onLive: (childRuntime) => {
+        if (status.disposed || record.attempt !== attempt || mounts.get(record.id) !== record) {
+          return
+        }
+        record.state = { _tag: 'Live', runtime: childRuntime }
+      },
+      onFailed: (error) => {
+        if (status.disposed || record.attempt !== attempt || mounts.get(record.id) !== record) {
+          return
+        }
+        record.state = { _tag: 'Failed', error }
+      },
+    })
+  }
+
+  const retryMount = (record: TreeFeatureMount): void => {
+    if (status.disposed || mounts.get(record.id) !== record || record.state._tag !== 'Failed') {
+      return
+    }
+    record.dispose()
+    startMount(record)
+  }
+
+  const featureRecord = ({
+    id,
+    parent,
+    binding,
+    depth,
+    props,
+  }: FeatureRecordInput): TreeFeatureMount => {
+    const current = mounts.get(id)
+    if (current !== undefined && current.binding === binding && current.parent === parent) {
+      return current
+    }
+    if (current !== undefined) {
+      current.attempt += 1
+      current.dispose()
+    }
+    const created: TreeFeatureMount = {
+      id,
+      binding,
+      parent,
+      depth,
+      props,
+      attempt: 0,
+      state: { _tag: 'Loading' },
+      dispose: () => {},
+    }
+    mounts.set(id, created)
+    startMount(created)
+    return created
+  }
+
+  const renderComposition = ({
+    runtime: currentRuntime,
+    comp,
+    props,
+    key,
+    path,
+    depth,
+    seen,
+  }: RenderCompositionInput): TreeNode => {
+    const service = currentRuntime.read(comp.tag)
+    const env: RenderEnv = { props, tracker: { add: () => {} } }
+    const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(comp))
+    const frame = Effect.runSync(Composition.render(service, env))
+    endRenderSpan()
+    if (!isStructure(frame)) {
+      return Effect.runSync(
+        Effect.dieMessage(`reform-proof: composition ${uiNameOf(comp)} did not return a Structure`),
+      )
+    }
+    sink.api.record({
+      name: uiNameOf(comp),
+      props: frame.props,
+      events: eventsOf(frame),
+      ...(Option.isSome(key) ? { key: key.value } : {}),
+    })
+
+    const fills = structureFills(frame)
+    const renderedSlots = Rec.map(slotsOf(comp), (slotClass, slotName) => {
+      const fill = fills[slotName]
+      if (fill === undefined) {
+        return []
+      }
+      const child = currentRuntime.read(slotClass.tag)
+      return fillEntries(slotName, fill).flatMap((entry) => {
+        const childPath = `${path}${encodeIdentityPart(slotName)}${encodeIdentityPart(entry.key)}`
+        if (!isFeatureBinding(child)) {
+          return [
+            renderComposition({
+              runtime: currentRuntime,
+              comp: child,
+              props: entry.props,
+              key: Option.some(entry.key),
+              path: childPath,
+              depth: depth + 1,
+              seen,
+            }),
+          ]
+        }
+        const id = mountId({
+          parent: currentRuntime,
+          parentPath: path,
+          slotName,
+          key: entry.key,
+          binding: child,
+        })
+        seen.add(id)
+        const record = featureRecord({
+          id,
+          parent: currentRuntime,
+          binding: child,
+          depth: depth + 1,
+          props: entry.props,
+        })
+        return Match.value(record.state).pipe(
+          Match.when({ _tag: 'Live' }, (live) => [
+            renderComposition({
+              runtime: live.runtime,
+              comp: child.composition,
+              props: entry.props,
+              key: Option.some(entry.key),
+              path: childPath,
+              depth: depth + 1,
+              seen,
+            }),
+          ]),
+          Match.when({ _tag: 'Failed' }, (failed) => {
+            if (child.placeholder === undefined) {
+              return []
+            }
+            return [
+              renderComposition({
+                runtime: currentRuntime,
+                comp: child.placeholder.failed,
+                props: { error: failed.error, retry: () => retryMount(record) },
+                key: Option.some(entry.key),
+                path: `${childPath}/failed`,
+                depth: depth + 1,
+                seen,
+              }),
+            ]
+          }),
+          Match.when({ _tag: 'Loading' }, () => {
+            if (child.placeholder === undefined) {
+              return []
+            }
+            return [
+              renderComposition({
+                runtime: currentRuntime,
+                comp: child.placeholder.loading,
+                props: entry.props,
+                key: Option.some(entry.key),
+                path: `${childPath}/loading`,
+                depth: depth + 1,
+                seen,
+              }),
+            ]
+          }),
+          Match.exhaustive,
+        )
+      })
+    })
+
+    return {
+      path,
+      depth,
+      key,
+      comp,
+      props: frame.props,
+      events: eventsOf(frame),
+      slots: renderedSlots,
+    }
+  }
+
+  const disposeStale = (seen: ReadonlySet<string>): void => {
+    Arr.sortWith(
+      Array.from(mounts.values()).filter((record) => !seen.has(record.id)),
+      (record) => -record.depth,
+      Order.number,
+    ).forEach((record) => {
+      mounts.delete(record.id)
+      record.attempt += 1
+      record.dispose()
+    })
+  }
+
+  const render = (): TreeRenderState => {
+    sink.reset()
+    const seen = new Set<string>()
+    const rootNode = renderComposition({
+      runtime,
+      comp: root,
+      props: {},
+      key: Option.none(),
+      path: 'root',
+      depth: 0,
+      seen,
+    })
+    disposeStale(seen)
+    return {
+      root: rootNode,
+      fingerprint: encodeUnknown(treeFingerprint(rootNode)),
+    }
+  }
+
+  const settle = makeTreeSettle(render)
+  const dispose = (): void => disposeTreeMounts({ status, mounts })
+
+  return { render, settle, dispose }
+}

package/src/runtimeTreeFacade.ts

@@ -0,0 +1,134 @@
+import { Array as Arr, Effect, Option } from 'effect'
+import type { CompositionClass, RuntimeHandle } from '@playfast/reform'
+import { AssertionFailed, UnknownAction, UnknownSlot } from './errors'
+import { matchProps } from './assertions'
+import { makeTreeDriver } from './runtimeTreeDriver'
+import type { RuntimeTreeFacade, TreeNode } from './runtimeTreeTypes'
+import { keyed, type Sink, uiNameOf } from './sink'
+import type { MountedFacade, MountedSlotFacade } from './runtimeFacade'
+
+export type { RuntimeTreeFacade } from './runtimeTreeTypes'
+
+export const makeRuntimeTreeFacade = (
+  runtime: RuntimeHandle,
+  root: CompositionClass<unknown>,
+  sink: Sink,
+  dispatched: Set<string>,
+): RuntimeTreeFacade => {
+  const driver = makeTreeDriver(runtime, root, sink)
+  const currentRoot = (): TreeNode => driver.render().root
+
+  const nodeFacade = (resolve: () => TreeNode): MountedFacade => ({
+    props: Effect.sync(() => resolve().props),
+    expectProps: (partial) =>
+      Effect.sync(() => {
+        const mismatch = matchProps({
+          actual: resolve().props,
+          expected: partial,
+        })
+        if (mismatch !== undefined) {
+          return Effect.runSync(
+            Effect.dieMessage(new AssertionFailed({ detail: mismatch }).message),
+          )
+        }
+      }),
+    actions: keyed(
+      (event) => (payload: unknown) =>
+        Effect.gen(function* () {
+          const node = resolve()
+          const trigger = node.events[event]
+          if (trigger === undefined) {
+            return yield* Effect.dieMessage(
+              new UnknownAction({
+                composition: uiNameOf(node.comp),
+                action: event,
+                rendered: 1,
+              }).message,
+            )
+          }
+          dispatched.add(event)
+          trigger(payload)
+          yield* driver.settle
+          return resolve().props
+        }),
+    ),
+    slots: keyed((slotName) => slotFacade(resolve, slotName)),
+    frame: driver.settle,
+  })
+
+  const slotFacade = (resolveParent: () => TreeNode, slotName: string): MountedSlotFacade => {
+    const children = (): ReadonlyArray<TreeNode> => {
+      const parent = resolveParent()
+      const resolved = parent.slots[slotName]
+      if (resolved === undefined) {
+        return Effect.runSync(
+          Effect.dieMessage(
+            new UnknownSlot({ parent: uiNameOf(parent.comp), slot: slotName }).message,
+          ),
+        )
+      }
+      return resolved
+    }
+    const childAt = (index: number): MountedFacade =>
+      nodeFacade(() => children()[index] ?? missingChild(index))
+    const childByKey = (key: string): MountedFacade =>
+      nodeFacade(() => {
+        return Option.getOrElse(
+          Arr.findFirst(children(), (candidate) => Option.contains(candidate.key, key)),
+          () => missingKey(key),
+        )
+      })
+    const missingChild = (index: number): never => {
+      const parent = resolveParent()
+      return Effect.runSync(
+        Effect.dieMessage(
+          new UnknownSlot({
+            parent: uiNameOf(parent.comp),
+            slot: `${slotName}[${index}]`,
+          }).message,
+        ),
+      )
+    }
+    const missingKey = (key: string): never => {
+      const parent = resolveParent()
+      return Effect.runSync(
+        Effect.dieMessage(
+          new UnknownSlot({
+            parent: uiNameOf(parent.comp),
+            slot: `${slotName}[key=${key}]`,
+          }).message,
+        ),
+      )
+    }
+    const first = childAt(0)
+    return {
+      first: Effect.sync(() => childAt(0)),
+      at: (index) => Effect.sync(() => childAt(index)),
+      all: Effect.sync(() => children().map((_child, index) => childAt(index))),
+      byKey: (key) =>
+        Effect.sync(() => {
+          const child = Arr.findFirst(children(), (candidate) =>
+            Option.contains(candidate.key, key),
+          )
+          return Option.isNone(child) ? missingKey(key) : childByKey(key)
+        }),
+      where: (predicate) =>
+        Effect.sync(() =>
+          children().flatMap((child, index) => (predicate(child.props) ? [childAt(index)] : [])),
+        ),
+      count: Effect.sync(() => children().length),
+      props: first.props,
+      expectProps: first.expectProps,
+      actions: first.actions,
+      slots: first.slots,
+      frame: driver.settle,
+    }
+  }
+
+  return {
+    facade: nodeFacade(currentRoot),
+    settle: driver.settle,
+    dispose: driver.dispose,
+  }
+}
+