@playfast/reform 0.0.5 → 0.0.8

package/src/wire/triggers.ts

@@ -0,0 +1,98 @@
+import { type Cause, Context, Data, Effect, Layer, type ParseResult, Ref, Schema } from 'effect'
+import type { Trigger } from '../ui/trigger'
+
+/**
+ * The server-side bridge for trigger handles (REMOTE_UI.md §4). A rendered
+ * `WireProp` of `_tag: 'Event'` carries a `handle`; the client invokes it by
+ * sending `(handle, encodedPayload)`. Here we hold the live `Trigger` and its
+ * payload schema, decode the wire payload, and fire — so the UI never ships a
+ * function, only a handle, and the payload is validated at the seam.
+ *
+ * Handles are caller-provided keys, by convention `${nodeId}:${eventName}`: a
+ * re-render re-`register`s the same handle with that frame's fresh trigger, so the
+ * handle is stable across frames (the client's in-flight handle stays valid) and
+ * the handle space never grows. The schema is the contract's own per-event wire
+ * schema (`WiredUiManifest.events`, Phase 1) — the single source of truth for the
+ * UI boundary, decoupled from which `Event` the composition binds behind it.
+ */
+
+export type TriggerHandle = string
+
+// `any` in the schema/trigger slots is the documented Schema-variance escape
+// (same reason as `CompositionConfig.props`); only the registrar's call site,
+// where the trigger and its schema agree, sees the precise type.
+interface TriggerEntry {
+  readonly trigger: Trigger<any>
+  readonly schema: Schema.Schema<any, any>
+}
+
+const UnknownTriggerBase: new (args: { readonly handle: TriggerHandle }) => Cause.YieldableError & {
+  readonly _tag: 'reform/UnknownTrigger'
+} & Readonly<{ readonly handle: TriggerHandle }> = Data.TaggedError('reform/UnknownTrigger')<{
+  readonly handle: TriggerHandle
+}>
+
+/** A wire message named a trigger handle the server no longer holds (a stale client). */
+export class UnknownTrigger extends UnknownTriggerBase {
+  override get message(): string {
+    return `reform: no trigger registered under handle '${this.handle}'`
+  }
+}
+
+export interface TriggerRegistryApi {
+  /** Register (or overwrite) a trigger + its payload schema under a handle key. */
+  readonly register: <P>(
+    handle: TriggerHandle,
+    trigger: Trigger<P>,
+    schema: Schema.Schema<P, any>,
+  ) => Effect.Effect<void>
+  /** Decode an encoded payload via the handle's schema and fire the trigger. */
+  readonly invoke: (
+    handle: TriggerHandle,
+    encodedPayload: unknown,
+  ) => Effect.Effect<void, UnknownTrigger | ParseResult.ParseError>
+  /** Drop a handle once its node unmounts (the Phase 2 tree diff signals it). */
+  readonly revoke: (handle: TriggerHandle) => Effect.Effect<void>
+}
+
+const TriggerRegistryBase: Context.TagClass<
+  TriggerRegistry,
+  'reform/wire/TriggerRegistry',
+  TriggerRegistryApi
+> = Context.Tag('reform/wire/TriggerRegistry')<TriggerRegistry, TriggerRegistryApi>()
+
+export class TriggerRegistry extends TriggerRegistryBase {}
+
+export const make: Effect.Effect<TriggerRegistryApi> = Effect.gen(function* () {
+  const entries = yield* Ref.make(new Map<TriggerHandle, TriggerEntry>())
+
+  const register = <P>(
+    handle: TriggerHandle,
+    trigger: Trigger<P>,
+    schema: Schema.Schema<P, any>,
+  ): Effect.Effect<void> =>
+    Ref.update(entries, (map) => new Map(map).set(handle, { trigger, schema }))
+
+  const invoke = (
+    handle: TriggerHandle,
+    encodedPayload: unknown,
+  ): Effect.Effect<void, UnknownTrigger | ParseResult.ParseError> =>
+    Effect.gen(function* () {
+      const entry = (yield* Ref.get(entries)).get(handle)
+      if (entry === undefined) return yield* Effect.fail(new UnknownTrigger({ handle }))
+      const payload = yield* Schema.decodeUnknown(entry.schema)(encodedPayload)
+      entry.trigger(payload)
+    })
+
+  const revoke = (handle: TriggerHandle): Effect.Effect<void> =>
+    Ref.update(entries, (map) => {
+      const next = new Map(map)
+      next.delete(handle)
+      return next
+    })
+
+  return { register, invoke, revoke }
+})
+
+/** Provide a fresh registry — one per remote connection (each client gets its own handle space). */
+export const layer: Layer.Layer<TriggerRegistry> = Layer.effect(TriggerRegistry, make)