statewire 0.0.1 → 0.0.3

package/src/host/host.ts

@@ -1,54 +1,48 @@
 import { useEffect, useState } from "react";
-import { applyOp, applyOps } from "../wire/ops";
-import type { StatewireOp, StatewirePath } from "../wire/ops";
+import { applyOps, sanitizeValue } from "../wire/ops";
+import type { StatewirePath } from "../wire/ops";
 import { StatewireReject } from "./engine";
-import { createStateDraft, frozen } from "./draft";
-import type { ServerOp } from "./draft";
+import { createStateDraft } from "./draft";
+import { createMethodProxy } from "../util/methodProxy";
+import type { ServerOp, StateDraft } from "./draft";
 import { StatewireSendError } from "../types";
-import type {
-  StatewireCommands,
-  StatewireCommandsProxy,
-  StatewireStateSource,
-} from "../types";
+import type { Statewire } from "../types";
+import type { StatewireHost } from "../host";
 
 const isDev = () =>
   typeof process === "undefined" || process.env["NODE_ENV"] !== "production";
 
 // ─── state ──────────────────────────────────────────────
 
-export type StatewireStateCtl = {
-  /** Apply server-vocabulary ops (root replace = whole-state swap). */
-  apply: (ops: readonly StatewireOp[]) => void;
-};
-
-export type StateHost = StatewireStateSource & {
-  /** Synchronous, per locally-recorded op; the host owns batching. */
-  setOnOp: (listener: ((op: ServerOp) => void) | null) => void;
-};
-
-const stateHosts = new WeakMap<object, StateHost>();
+const stateHosts = new WeakMap<object, StatewireHost.StateHost>();
 
-export const getStateHost = (state: object): StateHost | undefined =>
-  stateHosts.get(state);
+/** 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: object | null;
+  draft: StateDraft<object> | null;
   changed: StatewirePath[];
   onOp: ((op: ServerOp) => void) | null;
   onChange: (() => void) | null;
-  ctl: StatewireStateCtl;
-  host: StateHost;
+  ctl: StatewireHost.StateCtl;
+  host: StatewireHost.StateHost;
   bump: () => void;
 };
 
 export const useStatewireState = <TState>(
   init: () => TState,
-): readonly [TState, StatewireStateCtl] => {
+): 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: frozen(init()),
+      current: sanitizeValue(init()),
       draft: null,
       changed: [[]],
       onOp: null,
@@ -56,20 +50,23 @@ export const useStatewireState = <TState>(
       bump: () => setVersion((v) => v + 1),
       ctl: {
         apply: (ops) => {
-          const result = applyOps(c.current, 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: {
-        root: () => c.current,
+        snapshot: commit,
         setOnOp: (listener) => {
           c.onOp = listener;
         },
@@ -86,23 +83,21 @@ export const useStatewireState = <TState>(
     return c;
   });
 
-  let value = cell.current;
+  let value = cell.ctl.snapshot();
   if (typeof value === "object" && value !== null) {
     cell.draft ??= createStateDraft<object>({
-      root: () => cell.current,
-      record: (op) => {
-        const applied = applyOp(cell.current, op);
-        cell.current = applied.state;
-        cell.changed.push(...applied.changedPaths);
+      snapshot: () => cell.current,
+      record: (op, changedPath) => {
+        cell.changed.push(changedPath);
         cell.onOp?.(op);
         cell.bump();
         cell.onChange?.();
       },
     });
-    stateHosts.set(cell.draft, cell.host);
-    value = cell.draft;
+    stateHosts.set(cell.draft.proxy, cell.host);
+    value = cell.draft.proxy;
   }
-  return [value as TState, cell.ctl] as const;
+  return [value as TState, cell.ctl as StatewireHost.StateCtl<TState>] as const;
 };
 
 // ─── commands ───────────────────────────────────────────
@@ -124,24 +119,6 @@ type ExecutionState = {
 
 const executionStates = new WeakMap<object, ExecutionState>();
 
-declare const executionResult: unique symbol;
-
-/**
- * Handle a command handler returns to keep the command open past its own
- * return: `ack()` releases the client's optimistic overlay / ack watermark,
- * `resolve`/`reject` settle the command (and imply ack). `ack` is idempotent
- * and a no-op after settle.
- */
-export type CommandExecution<T = void> = {
-  readonly [executionResult]: (value: T) => void;
-};
-
-export type CommandExecutionResolvers<T = void> = {
-  ack: () => void;
-  resolve: (value: T) => void;
-  reject: (error: unknown) => void;
-};
-
 /**
  * `CommandExecution(executor)` runs the (possibly async) `executor({ ack })`
  * immediately: its return value resolves the execution, a throw/rejection
@@ -154,9 +131,11 @@ export const CommandExecution = Object.assign(
     executor: (resolvers: {
       ack: () => void;
     }) => T | void | PromiseLike<T | void>,
-  ): CommandExecution<T> => {
+  ): StatewireHost.Execution<T> => {
     const state: ExecutionState = { acked: false, settled: null, bind: null };
-    const execution = Object.freeze({}) as unknown as CommandExecution<T>;
+    const execution = Object.freeze(
+      {},
+    ) as unknown as StatewireHost.Execution<T>;
     executionStates.set(execution, state);
     const settle = (settled: ExecutionSettled) => {
       if (state.settled) return;
@@ -180,8 +159,8 @@ export const CommandExecution = Object.assign(
   },
   {
     withResolvers: <T = void>(): [
-      CommandExecution<T>,
-      CommandExecutionResolvers<T>,
+      StatewireHost.Execution<T>,
+      StatewireHost.ExecutionResolvers<T>,
     ] => {
       let resolve!: (value: T) => void;
       let reject!: (error: unknown) => void;
@@ -220,8 +199,18 @@ export type CommandsListener = {
   onSettle: (inv: CommandsInvocation, outcome: CommandsOutcome) => void;
 };
 
+export type CommandsSubmission = {
+  method: string;
+  params: readonly unknown[];
+  clientId?: string;
+  caller?: StatewireHost.Caller;
+  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>();
@@ -239,9 +228,13 @@ type QueuedCall = {
   ts: number;
   resolve: (value: unknown) => void;
   reject: (error: unknown) => void;
+  origin?: CommandsSubmission;
 };
 
-type ActiveInvocation = CommandsInvocation & { acked: boolean };
+type ActiveInvocation = CommandsInvocation & {
+  acked: boolean;
+  origin?: CommandsSubmission;
+};
 
 type CommandsCell = {
   handlers: Record<string, (...args: never[]) => unknown> | null;
@@ -255,6 +248,12 @@ type CommandsCell = {
 
 const STALL_WARN_MS = 5000;
 
+// In-process dispatch has no wire client: never any ambient context, trivially attached.
+const LOCAL_CALLER: StatewireHost.Caller = Object.freeze({
+  context: null,
+  isConnected: true,
+});
+
 const toSendError = (error: unknown): StatewireSendError =>
   error instanceof StatewireSendError
     ? error
@@ -270,6 +269,7 @@ const ackInvocation = (cell: CommandsCell, inv: ActiveInvocation) => {
   if (inv.acked) return;
   inv.acked = true;
   cell.listener?.onAck(inv);
+  inv.origin?.onAck?.();
 };
 
 const settleInvocation = (
@@ -283,12 +283,15 @@ const settleInvocation = (
     const outcome: CommandsOutcome =
       settled.value === undefined
         ? { type: "accepted" }
-        : { type: "accepted", payload: frozen(settled.value) };
+        : { 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);
-    cell.listener?.onSettle(inv, { type: "rejected", error });
+    const outcome: CommandsOutcome = { type: "rejected", error };
+    cell.listener?.onSettle(inv, outcome);
+    inv.origin?.onSettle?.(outcome);
     call.reject(error);
   }
 };
@@ -302,9 +305,12 @@ const pump = (cell: CommandsCell) => {
   if (!call) return;
   const handler = cell.handlers[call.method];
   if (handler === undefined) {
-    call.reject(
-      new StatewireSendError({ fate: "unknown-command", cause: "server" }),
-    );
+    const error = new StatewireSendError({
+      fate: "unknown-command",
+      cause: "server",
+    });
+    call.origin?.onSettle?.({ type: "rejected", error });
+    call.reject(error);
     pump(cell);
     return;
   }
@@ -314,6 +320,10 @@ const pump = (cell: CommandsCell) => {
     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);
@@ -321,9 +331,9 @@ const pump = (cell: CommandsCell) => {
   cell.listener?.onCovered?.(inv);
   void (async () => {
     try {
-      const value = await (handler as (...args: readonly unknown[]) => unknown)(
-        ...call.params,
-      );
+      const value = await (
+        handler as (...args: readonly unknown[]) => unknown
+      ).call(call.origin?.caller ?? LOCAL_CALLER, ...call.params);
       const execution =
         typeof value === "object" && value !== null
           ? executionStates.get(value)
@@ -363,17 +373,13 @@ const watchStall = (cell: CommandsCell) => {
   }, STALL_WARN_MS);
 };
 
-type UnwrapExecution<V> = V extends CommandExecution<infer T> ? T : V;
-
-export type StatewireHandledCommands<THandlers extends StatewireCommands> = {
-  [K in keyof THandlers]: (
-    ...args: Parameters<THandlers[K]>
-  ) => UnwrapExecution<Awaited<ReturnType<THandlers[K]>>>;
-};
-
-export const useStatewireCommands = <THandlers extends StatewireCommands>(
-  commands: THandlers | undefined | null | false,
-): StatewireCommandsProxy<StatewireHandledCommands<THandlers>> => {
+export const useStatewireCommands = <THandlers extends Statewire.Commands>(
+  commands:
+    | (THandlers & ThisType<StatewireHost.Caller>)
+    | undefined
+    | null
+    | false,
+): Statewire.CommandsProxy<StatewireHost.HandledCommands<THandlers>> => {
   const [built] = useState(() => {
     const cell: CommandsCell = {
       handlers: null,
@@ -384,39 +390,45 @@ export const useStatewireCommands = <THandlers extends StatewireCommands>(
       unmounted: false,
       stallTimer: null,
     };
-    const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
-    const proxy = new Proxy(
-      {} as StatewireCommandsProxy<StatewireHandledCommands<THandlers>>,
-      {
-        get: (_target, method) => {
-          if (typeof method !== "string") return undefined;
-          let fn = memo.get(method);
-          if (fn === undefined) {
-            fn = (...params: unknown[]) =>
-              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);
-              });
-            memo.set(method, fn);
+    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;
           }
-          return fn;
-        },
-      },
+          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 };
   });
@@ -458,8 +470,8 @@ export type EmitHost = {
 
 const emitHosts = new WeakMap<object, EmitHost>();
 
-export const getEmitHost = (emit: object): EmitHost | undefined =>
-  emitHosts.get(emit);
+export const getEmitHost = (emit: object | undefined): EmitHost | undefined =>
+  emit && emitHosts.get(emit);
 
 export const useStatewireEmit = <TEvent>(): ((event: TEvent) => void) => {
   const [built] = useState(() => {
@@ -468,7 +480,7 @@ export const useStatewireEmit = <TEvent>(): ((event: TEvent) => void) => {
       if (!cell.sink) {
         throw new Error("statewire: emit before a host bound the event sink");
       }
-      cell.sink(frozen(event));
+      cell.sink(sanitizeValue(event));
     };
     emitHosts.set(emit, {
       setSink: (sink) => {