statewire 0.0.0-0 → 0.0.2

package/src/host/host.ts

@@ -0,0 +1,482 @@
+import { useEffect, useState } from "react";
+import { applyOps, sanitizeValue } from "../wire/ops";
+import type { StatewirePath } from "../wire/ops";
+import { StatewireReject } from "./engine";
+import { createStateDraft } from "./draft";
+import { createMethodProxy } from "../util/methodProxy";
+import type { ServerOp, StateDraft } from "./draft";
+import { StatewireSendError } from "../types";
+import type { Statewire } from "../types";
+import type { StatewireHost } from "../host";
+
+const isDev = () =>
+  typeof process === "undefined" || process.env["NODE_ENV"] !== "production";
+
+// ─── state ──────────────────────────────────────────────
+
+const stateHosts = new WeakMap<object, StatewireHost.StateHost>();
+
+/** Host-side accessor for a `useStatewireState` state object's source (`snapshot()` reads the committed state). */
+export const getStateHost = (
+  state: object,
+): StatewireHost.StateHost | undefined => stateHosts.get(state);
+
+type StateCell = {
+  current: unknown;
+  draft: StateDraft<object> | null;
+  changed: StatewirePath[];
+  onOp: ((op: ServerOp) => void) | null;
+  onChange: (() => void) | null;
+  ctl: StatewireHost.StateCtl;
+  host: StatewireHost.StateHost;
+  bump: () => void;
+};
+
+export const useStatewireState = <TState>(
+  init: () => TState,
+): readonly [TState, StatewireHost.StateCtl<TState>] => {
+  const [, setVersion] = useState(0);
+  const [cell] = useState((): StateCell => {
+    const commit = () => {
+      if (c.draft) c.current = c.draft.flush();
+      return c.current;
+    };
+    const c: StateCell = {
+      current: sanitizeValue(init()),
+      draft: null,
+      changed: [[]],
+      onOp: null,
+      onChange: null,
+      bump: () => setVersion((v) => v + 1),
+      ctl: {
+        apply: (ops) => {
+          const result = applyOps(commit(), ops);
+          if (result.events.length > 0) {
+            throw new Error(
+              "statewire: event ops do not apply to state — route them to emit",
+            );
+          }
+          c.current = result.state;
+          c.draft?.invalidate();
+          c.changed.push(...result.changedPaths);
+          if (c.onOp) for (const op of ops) c.onOp(op as ServerOp);
+          c.bump();
+          c.onChange?.();
+        },
+        snapshot: commit,
+      },
+      host: {
+        snapshot: commit,
+        setOnOp: (listener) => {
+          c.onOp = listener;
+        },
+        setOnChange: (listener) => {
+          c.onChange = listener;
+        },
+        takeChanged: () => {
+          const changed = c.changed;
+          c.changed = [];
+          return changed;
+        },
+      },
+    };
+    return c;
+  });
+
+  let value = cell.ctl.snapshot();
+  if (typeof value === "object" && value !== null) {
+    cell.draft ??= createStateDraft<object>({
+      snapshot: () => cell.current,
+      record: (op, changedPath) => {
+        cell.changed.push(changedPath);
+        cell.onOp?.(op);
+        cell.bump();
+        cell.onChange?.();
+      },
+    });
+    stateHosts.set(cell.draft.proxy, cell.host);
+    value = cell.draft.proxy;
+  }
+  return [value as TState, cell.ctl as StatewireHost.StateCtl<TState>] as const;
+};
+
+// ─── commands ───────────────────────────────────────────
+
+type ExecutionSettled =
+  | { type: "resolved"; value: unknown }
+  | { type: "rejected"; error: unknown };
+
+type ExecutionBind = {
+  onAck: () => void;
+  onSettle: (settled: ExecutionSettled) => void;
+};
+
+type ExecutionState = {
+  acked: boolean;
+  settled: ExecutionSettled | null;
+  bind: ExecutionBind | null;
+};
+
+const executionStates = new WeakMap<object, ExecutionState>();
+
+/**
+ * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`
+ * immediately: its return value resolves the execution, a throw/rejection
+ * rejects it; `ack()` releases the client's ack watermark before the executor
+ * finishes. `CommandExecution.withResolvers()` returns `[execution,
+ * { ack, resolve, reject }]` instead — settle them from your own spawned work.
+ */
+export const CommandExecution = Object.assign(
+  <T = void>(
+    executor: (resolvers: {
+      ack: () => void;
+    }) => T | void | PromiseLike<T | void>,
+  ): StatewireHost.Execution<T> => {
+    const state: ExecutionState = { acked: false, settled: null, bind: null };
+    const execution = Object.freeze(
+      {},
+    ) as unknown as StatewireHost.Execution<T>;
+    executionStates.set(execution, state);
+    const settle = (settled: ExecutionSettled) => {
+      if (state.settled) return;
+      state.settled = settled;
+      state.acked = true;
+      state.bind?.onSettle(settled);
+    };
+    const ack = () => {
+      if (state.acked) return;
+      state.acked = true;
+      state.bind?.onAck();
+    };
+    void (async () => {
+      try {
+        settle({ type: "resolved", value: await executor({ ack }) });
+      } catch (error) {
+        settle({ type: "rejected", error });
+      }
+    })();
+    return execution;
+  },
+  {
+    withResolvers: <T = void>(): [
+      StatewireHost.Execution<T>,
+      StatewireHost.ExecutionResolvers<T>,
+    ] => {
+      let resolve!: (value: T) => void;
+      let reject!: (error: unknown) => void;
+      const promise = new Promise<T>((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      let ack!: () => void;
+      const execution = CommandExecution<T>(({ ack: a }) => {
+        ack = a;
+        return promise;
+      });
+      return [execution, { ack: () => ack(), resolve, reject }];
+    },
+  },
+);
+
+export type CommandsInvocation = {
+  readonly method: string;
+  readonly params: readonly unknown[];
+  readonly ts: number;
+  readonly seq: number;
+  readonly clientId?: string;
+};
+
+export type CommandsOutcome =
+  | { type: "accepted"; payload?: unknown }
+  | { type: "rejected"; error: unknown };
+
+export type CommandsListener = {
+  onStart: (inv: CommandsInvocation) => void;
+  onPosted?: (inv: CommandsInvocation) => void;
+  onAck: (inv: CommandsInvocation) => void;
+  /** Canonical state now covers the invocation's effect — drop any overlay. */
+  onCovered?: (inv: CommandsInvocation) => void;
+  onSettle: (inv: CommandsInvocation, outcome: CommandsOutcome) => void;
+};
+
+export type CommandsSubmission = {
+  method: string;
+  params: readonly unknown[];
+  clientId?: string;
+  onAck?: () => void;
+  onSettle?: (outcome: CommandsOutcome) => void;
+};
+
+export type CommandsHost = {
+  setListener: (listener: CommandsListener | null) => void;
+  submit?: (call: CommandsSubmission) => Promise<unknown>;
+};
+
+const commandsHosts = new WeakMap<object, CommandsHost>();
+
+export const getCommandsHost = (commands: object): CommandsHost | undefined =>
+  commandsHosts.get(commands);
+
+export const bindCommandsHost = (commands: object, host: CommandsHost) => {
+  commandsHosts.set(commands, host);
+};
+
+type QueuedCall = {
+  method: string;
+  params: readonly unknown[];
+  ts: number;
+  resolve: (value: unknown) => void;
+  reject: (error: unknown) => void;
+  origin?: CommandsSubmission;
+};
+
+type ActiveInvocation = CommandsInvocation & {
+  acked: boolean;
+  origin?: CommandsSubmission;
+};
+
+type CommandsCell = {
+  handlers: Record<string, (...args: never[]) => unknown> | null;
+  queue: QueuedCall[];
+  running: boolean;
+  listener: CommandsListener | null;
+  seq: number;
+  unmounted: boolean;
+  stallTimer: ReturnType<typeof setTimeout> | null;
+};
+
+const STALL_WARN_MS = 5000;
+
+const toSendError = (error: unknown): StatewireSendError =>
+  error instanceof StatewireSendError
+    ? error
+    : new StatewireSendError({
+        fate: "rejected",
+        cause: "server",
+        message: error instanceof Error ? error.message : String(error),
+        ...(error instanceof StatewireReject &&
+          error.payload !== undefined && { payload: error.payload }),
+      });
+
+const ackInvocation = (cell: CommandsCell, inv: ActiveInvocation) => {
+  if (inv.acked) return;
+  inv.acked = true;
+  cell.listener?.onAck(inv);
+  inv.origin?.onAck?.();
+};
+
+const settleInvocation = (
+  cell: CommandsCell,
+  inv: ActiveInvocation,
+  call: QueuedCall,
+  settled: ExecutionSettled,
+) => {
+  ackInvocation(cell, inv);
+  if (settled.type === "resolved") {
+    const outcome: CommandsOutcome =
+      settled.value === undefined
+        ? { type: "accepted" }
+        : { type: "accepted", payload: sanitizeValue(settled.value) };
+    cell.listener?.onSettle(inv, outcome);
+    inv.origin?.onSettle?.(outcome);
+    call.resolve(outcome.payload);
+  } else {
+    const error = toSendError(settled.error);
+    const outcome: CommandsOutcome = { type: "rejected", error };
+    cell.listener?.onSettle(inv, outcome);
+    inv.origin?.onSettle?.(outcome);
+    call.reject(error);
+  }
+};
+
+const pump = (cell: CommandsCell) => {
+  if (cell.running || !cell.handlers) {
+    watchStall(cell);
+    return;
+  }
+  const call = cell.queue.shift();
+  if (!call) return;
+  const handler = cell.handlers[call.method];
+  if (handler === undefined) {
+    const error = new StatewireSendError({
+      fate: "unknown-command",
+      cause: "server",
+    });
+    call.origin?.onSettle?.({ type: "rejected", error });
+    call.reject(error);
+    pump(cell);
+    return;
+  }
+  const inv: ActiveInvocation = {
+    method: call.method,
+    params: call.params,
+    ts: call.ts,
+    seq: ++cell.seq,
+    acked: false,
+    ...(call.origin !== undefined && { origin: call.origin }),
+    ...(call.origin?.clientId !== undefined && {
+      clientId: call.origin.clientId,
+    }),
+  };
+  cell.running = true;
+  cell.listener?.onStart(inv);
+  cell.listener?.onPosted?.(inv);
+  cell.listener?.onCovered?.(inv);
+  void (async () => {
+    try {
+      const value = await (handler as (...args: readonly unknown[]) => unknown)(
+        ...call.params,
+      );
+      const execution =
+        typeof value === "object" && value !== null
+          ? executionStates.get(value)
+          : undefined;
+      if (execution) {
+        if (execution.acked) ackInvocation(cell, inv);
+        if (execution.settled) {
+          settleInvocation(cell, inv, call, execution.settled);
+        } else {
+          execution.bind = {
+            onAck: () => ackInvocation(cell, inv),
+            onSettle: (settled) => settleInvocation(cell, inv, call, settled),
+          };
+        }
+      } else {
+        settleInvocation(cell, inv, call, { type: "resolved", value });
+      }
+    } catch (error) {
+      settleInvocation(cell, inv, call, { type: "rejected", error });
+    } finally {
+      cell.running = false;
+      pump(cell);
+    }
+  })();
+};
+
+const watchStall = (cell: CommandsCell) => {
+  if (!isDev() || cell.stallTimer !== null || cell.queue.length === 0) return;
+  if (cell.handlers) return;
+  cell.stallTimer = setTimeout(() => {
+    cell.stallTimer = null;
+    if (cell.handlers === null && cell.queue.length > 0 && !cell.unmounted) {
+      console.warn(
+        `statewire: ${cell.queue.length} buffered command(s) waiting over ${STALL_WARN_MS}ms — did the host forget to arm useStatewireCommands?`,
+      );
+    }
+  }, STALL_WARN_MS);
+};
+
+export const useStatewireCommands = <THandlers extends Statewire.Commands>(
+  commands: THandlers | undefined | null | false,
+): Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>> => {
+  const [built] = useState(() => {
+    const cell: CommandsCell = {
+      handlers: null,
+      queue: [],
+      running: false,
+      listener: null,
+      seq: 0,
+      unmounted: false,
+      stallTimer: null,
+    };
+    const proxy = createMethodProxy<
+      Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>>
+    >(
+      (method, params) =>
+        new Promise((resolve, reject) => {
+          if (cell.unmounted) {
+            reject(new Error("statewire: commands called after unmount"));
+            return;
+          }
+          cell.queue.push({
+            method,
+            params,
+            ts: Date.now(),
+            resolve,
+            reject,
+          });
+          pump(cell);
+        }),
+    );
+    commandsHosts.set(proxy, {
+      setListener: (listener) => {
+        cell.listener = listener;
+      },
+      submit: (origin) =>
+        new Promise((resolve, reject) => {
+          if (cell.unmounted) {
+            reject(new Error("statewire: commands called after unmount"));
+            return;
+          }
+          cell.queue.push({
+            method: origin.method,
+            params: origin.params,
+            ts: Date.now(),
+            resolve,
+            reject,
+            origin,
+          });
+          pump(cell);
+        }),
+    });
+    return { cell, proxy };
+  });
+
+  useEffect(() => {
+    const { cell } = built;
+    cell.unmounted = false;
+    return () => {
+      cell.unmounted = true;
+      cell.handlers = null;
+      if (cell.stallTimer !== null) {
+        clearTimeout(cell.stallTimer);
+        cell.stallTimer = null;
+      }
+      queueMicrotask(() => {
+        if (!cell.unmounted) return;
+        const queued = cell.queue;
+        cell.queue = [];
+        for (const call of queued) {
+          call.reject(new Error("statewire: unmounted"));
+        }
+      });
+    };
+  }, [built]);
+
+  useEffect(() => {
+    built.cell.handlers = commands || null;
+    pump(built.cell);
+  });
+
+  return built.proxy;
+};
+
+// ─── emit ───────────────────────────────────────────────
+
+export type EmitHost = {
+  setSink: (sink: ((event: unknown) => void) | null) => void;
+};
+
+const emitHosts = new WeakMap<object, EmitHost>();
+
+export const getEmitHost = (emit: object | undefined): EmitHost | undefined =>
+  emit && emitHosts.get(emit);
+
+export const useStatewireEmit = <TEvent>(): ((event: TEvent) => void) => {
+  const [built] = useState(() => {
+    const cell = { sink: null as ((event: unknown) => void) | null };
+    const emit = (event: TEvent) => {
+      if (!cell.sink) {
+        throw new Error("statewire: emit before a host bound the event sink");
+      }
+      cell.sink(sanitizeValue(event));
+    };
+    emitHosts.set(emit, {
+      setSink: (sink) => {
+        cell.sink = sink;
+      },
+    });
+    return emit;
+  });
+  return built;
+};