@playfast/reform-remote 1.1.0 → 1.3.0

package/src/client.ts

@@ -1,5 +1,5 @@
 import { createElement, Fragment, type ReactNode, useRef } from 'react'
-import { Effect, Record as Rec, Schema } from 'effect'
+import { Effect, Option, Record as Rec, Schema } from 'effect'
 import { type MadeView, Ui, type UiContract, UiViewContract, type ViewImpl } from '@playfast/reform'
 import {
   type AnyMadeView,
@@ -71,14 +71,26 @@ const registerView = (view: AnyMadeView): RegisteredRemoteView =>
         )
       }
       const propsSchema = Schema.make<C['props'], unknown>(propsReflection.ast)
+      const decodeProps = Schema.decodeUnknownOption(propsSchema)
       return {
         name: contract.manifest.name,
+        // Props off the wire are untrusted — the envelope types a data prop as
+        // `Schema.Unknown`, so version skew against a differently-shaped server first
+        // shows up here, inside React's render phase. A throw would take the whole tree
+        // down; this node costs itself, which is what an unregistered node name already
+        // does one level up.
         view: (encoded, slots, events) =>
-          exact(
-            Schema.decodeUnknownSync(propsSchema)(encoded),
-            bindSlots<C>(slots),
-            bindEvents<C>(events),
-          ),
+          Option.match(decodeProps(encoded), {
+            onNone: () => {
+              Effect.runSync(
+                Effect.logWarning(
+                  `reform-remote: dropped node '${contract.manifest.name}' — props do not match its wire schema`,
+                ),
+              )
+              return null
+            },
+            onSome: (props) => exact(props, bindSlots<C>(slots), bindEvents<C>(events)),
+          }),
       }
     },
   )
@@ -123,9 +135,8 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
   }
 
   const encoded: Record<string, unknown> = Rec.fromEntries(
-    node.props.flatMap(
-      (prop): ReadonlyArray<readonly [string, unknown]> =>
-        prop._tag === 'Data' ? [[prop.name, prop.value]] : [],
+    node.props.flatMap((prop): ReadonlyArray<readonly [string, unknown]> =>
+      prop._tag === 'Data' ? [[prop.name, prop.value]] : [],
     ),
   )
   const eventEntries = node.props.flatMap(
@@ -155,6 +166,11 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
           .filter((child) => requestedKey === undefined || child.key === requestedKey)
           .map((child) =>
             createElement(WireNodeView, {
+              // Reconcile on the semantic key when the server sent one: node ids are
+              // positional, so a reorder would otherwise slide item state between rows.
+              // Matches the local host, which keys by `placement.key`.
+              // The node id, not the app's key: ids are derived from the key and so are
+              // stable across a reorder, but unlike a key they are unique by construction.
               key: child.id,
               node: child,
               tree: currentTree,

package/src/clientBinding.ts

@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react'
+import { Match, MutableRef, Option, Predicate } from 'effect'
+import { Wire, type WireTree } from '@playfast/reform/internal'
+import {
+  type ClientConfig,
+  type RemoteContract,
+  type RemoteViewSet,
+  renderWireTree,
+} from './client'
+import type { InvokeMessage, RemoteTransport, ServerMessage } from './transport'
+
+export interface ClientBinding {
+  readonly node: () => ReactNode
+  readonly subscribe: (listener: () => void) => () => void
+  readonly snapshot: () => WireTree
+  // Stop notifying React. The wire stays in sync — see `connect`.
+  readonly dispose: () => void
+  // Done with the connection: drop the transport subscription too. A binding that
+  // has been closed never updates again.
+  readonly close: () => void
+}
+
+export interface ConnectOptions<C extends RemoteContract> {
+  readonly transport: RemoteTransport<InvokeMessage, ServerMessage>
+  readonly views: RemoteViewSet<C>
+  // How long the transport subscription outlives a `dispose()`. See `dispose` below.
+  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional public config; absent falls back to the built-in default
+  readonly releaseWindowMs?: number
+}
+
+// oxlint-disable-next-line reform-rules/no-magic-numbers -- the window's length is the value being named
+const defaultReleaseWindowMs = 10_000
+
+// Browsers hand back a number, which has no `unref`.
+const detachTimer = (handle: unknown): void => {
+  if (Predicate.hasProperty(handle, 'unref') && Predicate.isFunction(handle.unref)) {
+    handle.unref()
+  }
+}
+
+export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): ClientBinding => {
+  const { transport, views } = options
+  const state: { tree: WireTree } = { tree: [] }
+  const listeners = new Set<() => void>()
+  const config: ClientConfig<C> = {
+    views,
+    invoke: (handle, payload) => transport.send({ _tag: 'Invoke', handle, payload }),
+  }
+  const receive = (message: ServerMessage): void => {
+    state.tree = Match.value(message).pipe(
+      Match.tag('Snapshot', ({ tree }) => tree),
+      Match.tag('Patches', ({ patches }) => Wire.apply(state.tree, patches)),
+      Match.exhaustive,
+    )
+    listeners.forEach((listener) => listener())
+  }
+  // Subscribed for the binding's whole life, not for the span React happens to be
+  // listening. Patches are deltas against the server's own baseline and a delete is
+  // never re-sent, so a frame missed while detached is a permanent phantom node —
+  // and an effect cleanup is not an unmount (StrictMode, <Suspense>, <Activity> all
+  // tear effects down and put them back). `dispose` therefore only goes quiet; the
+  // transport subscription is released by `close`, which the connection's owner calls.
+  const off = transport.onMessage(receive)
+  const pending = MutableRef.make(Option.none<ReturnType<typeof setTimeout>>())
+  const close = (): void => {
+    listeners.clear()
+    MutableRef.set(pending, Option.none())
+    off()
+  }
+  // `dispose()` cannot know whether React is unmounting the host or merely hiding it,
+  // so it goes quiet and starts a clock. A `subscribe` inside the window is the host
+  // coming back and stops it; nothing inside the window means the host is gone, and
+  // the transport subscription is released rather than left to accumulate one dead
+  // handler per mount/unmount cycle.
+  const cancelClose = (): void =>
+    Option.match(MutableRef.get(pending), {
+      onNone: () => undefined,
+      onSome: (handle) => {
+        MutableRef.set(pending, Option.none())
+        clearTimeout(handle)
+      },
+    })
+  return {
+    node: () => renderWireTree(state.tree, config),
+    subscribe: (listener) => {
+      cancelClose()
+      listeners.add(listener)
+      return () => void listeners.delete(listener)
+    },
+    snapshot: () => state.tree,
+    dispose: () => {
+      listeners.clear()
+      if (Option.isSome(MutableRef.get(pending))) {
+        return
+      }
+      // oxlint-disable-next-line reform-rules/no-set-timeout-interval -- must be unref-able; a binding waiting to be collected must not hold the host process open
+      const handle = setTimeout(close, options.releaseWindowMs ?? defaultReleaseWindowMs)
+      detachTimer(handle)
+      MutableRef.set(pending, Option.some(handle))
+    },
+    close,
+  }
+}

package/src/counterFixtures.ts

@@ -0,0 +1,142 @@
+import { Duration, Effect, Layer, Schema as S } from 'effect'
+import {
+  Channel,
+  Composition,
+  Engine,
+  Event,
+  Procedure,
+  Reducer,
+  State,
+  StateGroup,
+  Ui,
+  mount,
+  provide,
+  scene,
+  type CapturedScene,
+  type DerivedContract,
+  type EventOf,
+  ui,
+} from '@playfast/reform'
+import { type EngineServices, type WiredUi } from '@playfast/reform/internal'
+
+const CountBase: State.StateDefinition<'count', number, typeof S.Number> = State.make(
+  'count',
+  S.Number,
+)
+class Count extends CountBase {}
+class Counters extends StateGroup.make(Count) {}
+class Bumped extends Event.make('Bumped', S.Struct({ by: S.Number })) {}
+class Bump extends Reducer.make('Bump', {
+  states: [Count],
+  events: [Bumped],
+}) {}
+const CounterUiBase: WiredUi<
+  DerivedContract<{
+    props: S.Struct<{ count: typeof S.Number }>
+    events: { bump: S.Struct<{ by: typeof S.Number }> }
+  }>,
+  'Counter'
+> = ui('Counter', {
+  props: S.Struct({ count: S.Number }),
+  events: { bump: S.Struct({ by: S.Number }) },
+})
+export class CounterUi extends CounterUiBase {}
+
+class Counter extends Composition.make('Counter', {
+  title: 'Counter',
+  ui: CounterUi,
+  states: [Count],
+})<Counter>() {}
+
+type CounterScene = CapturedScene<
+  typeof CounterUi.Contract,
+  readonly [typeof Count],
+  | EngineServices
+  | State.StateStore<'count', number>
+  | Ui.UiService<'Counter'>
+  | Composition.CompositionId<'Counter', Counter, never>,
+  unknown,
+  'Counter',
+  Counter
+>
+
+export const bumpedBy = (amount: number): EventOf<'Bumped', { by: number }> =>
+  Event.construct(Bumped, { by: amount })
+
+const makeCounterScene = (
+  boot?: ReadonlyArray<EventOf<'Bumped', { by: number }>>,
+): CounterScene => {
+  const presentation = Layer.mergeAll(
+    provide(
+      CounterUi,
+      Ui.make(CounterUi, ({ count }) => `count:${count}`),
+    ),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return mount({ props: { count }, slots: {}, events: { bump } })
+    }),
+    Reducer.live(Bump, (count, event) => count + event.by),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  return scene(Counter, boot === undefined ? { provide: [app] } : { provide: [app], boot })
+}
+export const counterScene: typeof makeCounterScene = makeCounterScene
+
+const makeStructureCounterScene = (): CounterScene => {
+  const presentation = Layer.mergeAll(
+    provide(
+      CounterUi,
+      Ui.make(CounterUi, ({ count }) => `count:${count}`),
+    ),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return mount({ props: { count }, slots: {}, events: { bump } })
+    }),
+    Reducer.live(Bump, (count, event) => count + event.by),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  return scene(Counter, { provide: [app] })
+}
+export const structureCounterScene: typeof makeStructureCounterScene = makeStructureCounterScene
+
+class Kick extends Event.make('Kick', S.Struct({ to: S.Number })) {}
+class Loader extends Channel.make('Loader', { policy: { _tag: 'latest' } }) {}
+class DelayedBump extends Procedure.make('DelayedBump', {
+  channel: Loader,
+  events: [Kick],
+}) {}
+
+const makeAsyncCounterScene = (delay: Duration.DurationInput = '40 millis'): CounterScene => {
+  const presentation = Layer.mergeAll(
+    provide(
+      CounterUi,
+      Ui.make(CounterUi, ({ count }) => `count:${count}`),
+    ),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return mount({ props: { count }, slots: {}, events: { bump } })
+    }),
+    Reducer.live(Bump, (count, event) => count + event.by),
+    Procedure.live(DelayedBump, function* (event) {
+      yield* Effect.sleep(delay)
+      yield* Event.dispatch(Bumped, { by: event.to })
+    }),
+    // Without Channel.live the boot Kick is dropped.
+    Channel.live(Loader),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  return scene(Counter, {
+    provide: [app],
+    boot: [Event.construct(Kick, { to: 7 })],
+  })
+}
+export const asyncCounterScene: typeof makeAsyncCounterScene = makeAsyncCounterScene