statewire 0.0.1 → 0.0.2

package/src/transports/ws.ts

@@ -1,127 +1,85 @@
+import { useState } from "react";
 import { flushTapSync, resource } from "@assistant-ui/tap";
 import type { ResourceElement } from "@assistant-ui/tap";
 import { encodeParams } from "../wire/meta";
 import { timing } from "../client/timing";
 import {
-  createGate,
   handleEnvelope,
   overloadedError,
-  reconnectConn,
+  useStatewireConn,
 } from "../client/connection";
-import type { ConnBase, StatewireEnvelope } from "../client/connection";
-import type { StatewireTransport } from "../types";
+import type { Conn, StatewireEnvelope } from "../client/connection";
+import type { Statewire } from "../types";
+import type { StatewireClient } from "../statewire";
 import { useStatewireRemote } from "./remote";
-import type { StatewireSessionStore } from "../client/sessionStore";
-import type { StatewireCommands } from "../types";
+import { CLIENT_QUERY_PARAM } from "../host/adapter";
 import type {
   RemoteLink,
   StatewireSubmitResult,
-  StatewireConnection,
-  StatewireTransportProps,
+  StatewireRemoteProps,
   StatewireWireCommand,
 } from "./sse";
 
-export type StatewireWSOptions = {
-  url: string;
-  protocols?: string | string[];
-  query?:
-    | Record<string, string>
-    | (() => Record<string, string> | Promise<Record<string, string>>);
-  webSocket?: new (url: string, protocols?: string | string[]) => WebSocket;
-  onChange?: (connection: StatewireConnection) => void;
-  sessionStore?: StatewireSessionStore;
-};
-
-type Latest = {
-  options: StatewireWSOptions;
-  ctx: StatewireTransportProps;
-};
-
 type PendingCommand = {
   seq: number;
   resolve: (result: StatewireSubmitResult) => void;
   reject: (error: Error) => void;
 };
 
-type Conn = ConnBase & {
+type WsChannel = {
   socket: WebSocket | null;
   pending: PendingCommand[];
-  latest: { readonly current: Latest };
-  send: RemoteLink["send"];
 };
 
 const OPEN = 1;
 
 export const WS_SUBPROTOCOL = "statewire.v1";
 
-const createConn = (
-  latest: { readonly current: Latest },
-  notify: (connection: StatewireConnection) => void,
-): Conn => {
-  const c: Conn = {
-    hasSnapshot: false,
-    lease: null,
-    attempt: 0,
-    episode: null,
-    abort: null,
-    socket: null,
-    pending: [],
-    gate: createGate(),
-    lifetime: null,
-    latest,
-    notify,
-    reconnect: () => reconnectConn(c),
-    attemptOnce: (abort) => attemptSocket(c, abort),
-    send: (args) => sendCommand(c, args),
-    connection: { status: "connecting", reconnect: () => c.reconnect() },
-  };
-  return c;
-};
-
-const socketUrl = async (c: Conn) => {
-  const { url, query } = c.latest.current.options;
+const socketUrl = async (
+  options: StatewireClient.WSOptions,
+  clientId: string,
+) => {
+  const { url, query } = options;
   const params = new URLSearchParams(
     typeof query === "function" ? await query() : query,
   );
-  params.set("client", c.latest.current.ctx.clientId);
+  params.set(CLIENT_QUERY_PARAM, clientId);
   const base = url.replace(/\/$/, "").replace(/^http/, "ws");
   return `${base}/ws?${params.toString()}`;
 };
 
 const settleOverloaded = (
-  c: Conn,
+  w: WsChannel,
   { seq, retryAfterMs }: { seq?: number; retryAfterMs?: number },
 ) => {
   if (seq === undefined) throw overloadedError(retryAfterMs);
-  const entry = c.pending.find((p) => p.seq === seq);
+  const entry = w.pending.find((p) => p.seq === seq);
   if (!entry) return;
-  c.pending = c.pending.filter((p) => p !== entry);
+  w.pending = w.pending.filter((p) => p !== entry);
   entry.reject(overloadedError(retryAfterMs));
 };
 
-const resolveReceipts = (c: Conn, ack: number) => {
-  while (c.pending[0] && c.pending[0].seq <= ack) {
-    c.pending.shift()!.resolve({ type: "receipt" });
-  }
-};
-
-const resolveResponded = (c: Conn, seqs: Set<number>) => {
+const resolvePending = (
+  w: WsChannel,
+  matches: (entry: PendingCommand) => boolean,
+) => {
   const remaining: PendingCommand[] = [];
-  for (const entry of c.pending) {
-    if (seqs.has(entry.seq)) entry.resolve({ type: "receipt" });
+  for (const entry of w.pending) {
+    if (matches(entry)) entry.resolve({ type: "receipt" });
     else remaining.push(entry);
   }
-  c.pending = remaining;
+  w.pending = remaining;
 };
 
-const failPending = (c: Conn, error: Error) => {
-  const pending = c.pending;
-  c.pending = [];
+const failPending = (w: WsChannel, error: Error) => {
+  const pending = w.pending;
+  w.pending = [];
   for (const entry of pending) entry.reject(error);
 };
 
 const runSocket = (
   c: Conn,
+  w: WsChannel,
   ws: WebSocket,
   abort: AbortController,
 ): Promise<"stop" | "reattach"> =>
@@ -130,7 +88,6 @@ const runSocket = (
     let timedOut = false;
     let outcome: "stop" | "reattach" | null = null;
     let closed = false;
-    let attached = false;
     const arm = () => {
       clearTimeout(timer);
       timer = setTimeout(() => {
@@ -148,11 +105,14 @@ const runSocket = (
       ws.close();
     };
     const processEnv = (env: StatewireEnvelope) => {
-      const done = flushTapSync(() => handleEnvelope(c, env, attached));
-      attached = true;
-      if (env.ack !== undefined) resolveReceipts(c, env.ack);
+      const done = flushTapSync(() => handleEnvelope(c, env));
+      if (env.ack !== undefined) {
+        const ack = env.ack;
+        resolvePending(w, (entry) => entry.seq <= ack);
+      }
       if (env.res !== undefined) {
-        resolveResponded(c, new Set(env.res.map((r) => r.seq)));
+        const seqs = new Set(env.res.map((r) => r.seq));
+        resolvePending(w, (entry) => seqs.has(entry.seq));
       }
       if (done) {
         outcome = done;
@@ -173,7 +133,7 @@ const runSocket = (
       }
       try {
         if (frame.overloaded !== undefined) {
-          settleOverloaded(c, frame.overloaded);
+          settleOverloaded(w, frame.overloaded);
         } else {
           processEnv(frame);
         }
@@ -184,7 +144,7 @@ const runSocket = (
     ws.onclose = () => {
       closed = true;
       clearTimeout(timer);
-      if (c.socket === ws) failPending(c, new Error("network"));
+      if (w.socket === ws) failPending(w, new Error("network"));
       if (outcome) resolve(outcome);
       else reject(new Error(timedOut ? "timeout" : "network"));
     };
@@ -192,13 +152,15 @@ const runSocket = (
 
 const attemptSocket = async (
   c: Conn,
+  w: WsChannel,
+  options: StatewireClient.WSOptions,
   abort: AbortController,
 ): Promise<"stop" | "reattach"> => {
   let ws: WebSocket | null = null;
   try {
-    const url = await socketUrl(c);
+    const url = await socketUrl(options, c.ctx.clientId);
     abort.signal.throwIfAborted();
-    const { protocols, webSocket } = c.latest.current.options;
+    const { protocols, webSocket } = options;
     const WS = webSocket ?? globalThis.WebSocket;
     if (!WS) throw new Error("no WebSocket implementation");
     const extra =
@@ -208,18 +170,18 @@ const attemptSocket = async (
           ? [protocols]
           : protocols;
     ws = new WS(url, [WS_SUBPROTOCOL, ...extra]);
-    c.socket = ws;
-    return await runSocket(c, ws, abort);
+    w.socket = ws;
+    return await runSocket(c, w, ws, abort);
   } finally {
-    if (c.socket === ws) c.socket = null;
+    if (w.socket === ws) w.socket = null;
   }
 };
 
 const sendCommand = (
-  c: Conn,
+  w: WsChannel,
   { seq, command }: { seq: number; command: StatewireWireCommand },
 ): Promise<StatewireSubmitResult> => {
-  const ws = c.socket;
+  const ws = w.socket;
   if (!ws || ws.readyState !== OPEN) {
     return Promise.reject(new Error("network"));
   }
@@ -238,11 +200,11 @@ const sendCommand = (
     // A timed-out command fails the socket: the retry then rides reconnect +
     // attach-seq arbitration.
     const timer = setTimeout(() => {
-      c.pending = c.pending.filter((p) => p !== entry);
+      w.pending = w.pending.filter((p) => p !== entry);
       reject(new Error("timeout"));
       ws.close();
     }, timing.heartbeatTimeoutMs);
-    c.pending.push(entry);
+    w.pending.push(entry);
     try {
       ws.send(
         JSON.stringify({
@@ -253,20 +215,42 @@ const sendCommand = (
       );
     } catch {
       clearTimeout(timer);
-      c.pending = c.pending.filter((p) => p !== entry);
+      w.pending = w.pending.filter((p) => p !== entry);
       reject(new Error("network"));
     }
   });
 };
 
+const useWsLink = (
+  options: StatewireClient.WSOptions,
+  ctx: StatewireRemoteProps,
+): RemoteLink => {
+  const [w] = useState((): WsChannel => ({ socket: null, pending: [] }));
+  const c = useStatewireConn({
+    url: options.url,
+    onChange: options.onChange,
+    ctx,
+    attemptOnce: (c, abort) => attemptSocket(c, w, options, abort),
+  });
+  const [link] = useState(
+    (): RemoteLink => ({
+      get connection() {
+        return c.connection;
+      },
+      send: (args) => sendCommand(w, args),
+    }),
+  );
+  return link;
+};
+
 const useStatewireWS = (
-  options: StatewireWSOptions,
-): StatewireTransport<any, any, any> => useStatewireRemote(options, createConn);
+  options: StatewireClient.WSOptions,
+): Statewire<any, any, any> => useStatewireRemote(options, useWsLink);
 
 export const StatewireWS = resource(useStatewireWS) as <
   TState = any,
-  TCommands extends StatewireCommands = StatewireCommands,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
 >(
-  options: StatewireWSOptions,
-) => ResourceElement<StatewireTransport<TState | undefined, TCommands, TEvent>>;
+  options: StatewireClient.WSOptions,
+) => ResourceElement<Statewire<TState | undefined, TCommands, TEvent>>;

package/src/types.ts

@@ -1,145 +1,64 @@
-import type { ResourceElement } from "@assistant-ui/tap";
-import type { StatewireConnection } from "./transports/sse";
+import type { StatewireClient } from "./statewire";
 import type { StatewirePath } from "./wire/ops";
 
-export type StatewireCommands = Record<string, (...args: never[]) => unknown>;
+export namespace Statewire {
+  export type Commands = Record<string, (...args: never[]) => unknown>;
 
-/** Push-based canonical state feed a transport hands to the client core. */
-export type StatewireStateSource = {
-  root: () => unknown;
-  /** Drain the paths changed since the last take (`[]` entry = whole state). */
-  takeChanged: () => StatewirePath[];
-  /** Synchronous, per change; the consumer owns coalescing. */
-  setOnChange: (listener: (() => void) | null) => void;
-};
-
-export type StatewireTransport<
-  TState,
-  TCommands extends StatewireCommands = StatewireCommands,
-  TEvent = any,
-> = {
-  state: TState;
-  commands: StatewireCommandsProxy<TCommands>;
-  emit: (event: TEvent) => void;
-  connection?: StatewireConnection;
-  source?: StatewireStateSource;
-};
+  export type Command<TCommands extends Commands = Commands> = {
+    [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };
+  }[keyof TCommands];
 
-export type StatewireCommand<
-  TCommands extends StatewireCommands = StatewireCommands,
-> = {
-  [K in keyof TCommands]: { method: K; params: Parameters<TCommands[K]> };
-}[keyof TCommands];
+  export type CommandsProxy<TCommands extends Commands> = {
+    [K in keyof TCommands]: (
+      ...args: Parameters<TCommands[K]>
+    ) => Promise<Awaited<ReturnType<TCommands[K]>>>;
+  };
 
-export type StatewireCommandsProxy<TCommands extends StatewireCommands> = {
-  [K in keyof TCommands]: (
-    ...args: Parameters<TCommands[K]>
-  ) => Promise<Awaited<ReturnType<TCommands[K]>>>;
-};
+  export type CommandUpdate<TCommands extends Commands = Commands> = {
+    [K in keyof TCommands]: {
+      method: K;
+      params: Parameters<TCommands[K]>;
+      seq: number;
+      status: "queued" | "posted" | "acked" | "settled";
+      result?: unknown;
+      failure?: StatewireClient.SendFailure;
+    };
+  }[keyof TCommands];
 
-export type StatewireCommandUpdate<
-  TCommands extends StatewireCommands = StatewireCommands,
-> = {
-  [K in keyof TCommands]: {
-    method: K;
-    params: Parameters<TCommands[K]>;
-    seq: number;
-    status: "queued" | "posted" | "acked" | "settled";
-    result?: unknown;
-    failure?: SendFailure;
+  /** Push-based canonical state feed a statewire hands to the client core. */
+  export type StateSource = {
+    snapshot: () => unknown;
+    /** Drain the paths changed since the last take (`[]` entry = whole state). */
+    takeChanged: () => StatewirePath[];
+    /** Synchronous, per change; the consumer owns coalescing. */
+    setOnChange: (listener: (() => void) | null) => void;
   };
-}[keyof TCommands];
-
-export type StatewireOptimisticContext = {
-  ts: number;
-  seq: number;
-  clientId?: string;
-};
 
-/**
- * Mutate the draft in place; the client records the next state plus the exact
- * changed paths. Re-run against the new base on every rebase.
- */
-export type StatewireOptimistic<
-  TState,
-  TCommands extends StatewireCommands = StatewireCommands,
-> = (
-  draft: TState,
-  command: StatewireCommand<TCommands>,
-  ctx: StatewireOptimisticContext,
-) => void;
+  export type Op =
+    | { op: "replace"; path: StatewirePath; value: unknown }
+    | { op: "add"; path: StatewirePath; value: unknown }
+    | { op: "remove"; path: StatewirePath }
+    | { op: "event"; value: object };
 
-export type StatewireChanges = {
-  isChangedAt(path: readonly (string | number)[]): boolean;
-  getChangedKeys(path: readonly (string | number)[]): string[];
-};
+  export type Changes = {
+    isChangedAt(path: readonly (string | number)[]): boolean;
+    getChangedKeys(path: readonly (string | number)[]): string[];
+  };
+}
 
-export type StatewireOptions<
-  TState,
-  TCommands extends StatewireCommands = StatewireCommands,
+export interface Statewire<
+  TState = any,
+  TCommands extends Statewire.Commands = Statewire.Commands,
   TEvent = any,
-> = {
-  transport: ResourceElement<StatewireTransport<TState, TCommands, TEvent>>;
-  optimistic?: StatewireOptimistic<NonNullable<TState>, TCommands>;
-  onEvent?: (event: TEvent, ctx: { state: NonNullable<TState> }) => void;
-  onStateChange?: (
-    state: NonNullable<TState>,
-    ctx: { changes: StatewireChanges },
-  ) => void;
-  onCommandChange?: (
-    update: StatewireCommandUpdate<TCommands>,
-    ctx: { state: NonNullable<TState> },
-  ) => void;
-};
-
-export type StatewireHelpers<
-  TState,
-  TCommands extends StatewireCommands = StatewireCommands,
-> = {
-  /** The transport's state type — remote transports include `undefined` until the first attach snapshot applies. */
+> {
   state: TState;
-  connection: StatewireConnection;
-  commands: StatewireCommandsProxy<TCommands>;
-};
-
-/**
- * fate: "aborted" = never sent, "rejected" = the handler refused,
- * "unknown-command" = no such command, "invalid-params" = the args did not
- * match the command's schema, "lost" = sent but never covered by an ack,
- * "crashed" = acked but the processing died, "result-unavailable" = acked
- * but the result is gone.
- * cause is which channel settled it: "server" = the server's answer;
- * the rest are channel deaths the client settled locally.
- */
-export type SendFailure =
-  | { fate: "rejected"; cause: "server"; message: string; payload?: unknown }
-  | { fate: "unknown-command"; cause: "server" }
-  | { fate: "invalid-params"; cause: "server"; message: string }
-  | { fate: "crashed"; cause: "server" }
-  | {
-      fate: "result-unavailable";
-      cause:
-        | "server"
-        | "unmount"
-        | "stream-gone"
-        | "session-lost"
-        | "superseded";
-    }
-  | {
-      fate: "aborted";
-      cause:
-        | "cascade"
-        | "unmount"
-        | "stream-gone"
-        | "session-lost"
-        | "superseded";
-    }
-  | {
-      fate: "lost";
-      cause: "unmount" | "stream-gone" | "session-lost" | "superseded";
-    };
+  commands: Statewire.CommandsProxy<TCommands>;
+  emit?: (event: TEvent) => void;
+  connection?: StatewireClient.Connection;
+  source?: Statewire.StateSource;
+}
 
-const describe = (failure: SendFailure): string => {
+const describe = (failure: StatewireClient.SendFailure): string => {
   switch (failure.fate) {
     case "rejected":
       return `statewire: command rejected: ${failure.message}`;
@@ -159,9 +78,9 @@ const describe = (failure: SendFailure): string => {
 };
 
 export class StatewireSendError extends Error {
-  readonly failure: SendFailure;
+  readonly failure: StatewireClient.SendFailure;
 
-  constructor(failure: SendFailure) {
+  constructor(failure: StatewireClient.SendFailure) {
     super(describe(failure));
     this.name = "StatewireSendError";
     this.failure = failure;

package/src/util/draftTraps.ts

@@ -0,0 +1,32 @@
+type SharedTraps = Pick<
+  ProxyHandler<object>,
+  | "defineProperty"
+  | "setPrototypeOf"
+  | "preventExtensions"
+  | "ownKeys"
+  | "getOwnPropertyDescriptor"
+>;
+
+export const sharedDraftTraps = (
+  current: () => object,
+  context: string,
+): SharedTraps => {
+  const unsupported = (op: string): never => {
+    throw new Error(`statewire: ${op} is not supported ${context}`);
+  };
+  return {
+    defineProperty: () => unsupported("defineProperty"),
+    setPrototypeOf: () => unsupported("setPrototypeOf"),
+    preventExtensions: () => unsupported("preventExtensions"),
+    ownKeys: () => Reflect.ownKeys(current()),
+    getOwnPropertyDescriptor: (_target, prop) => {
+      const node = current();
+      const desc = Reflect.getOwnPropertyDescriptor(node, prop);
+      if (!desc) return undefined;
+      return {
+        ...desc,
+        configurable: !Array.isArray(node) || prop !== "length",
+      };
+    },
+  };
+};

package/src/util/macrotask.ts

@@ -0,0 +1,25 @@
+// MessageChannel schedules the flush as a macrotask (tap's pattern): it runs
+// after the whole microtask drain, so every producer in the current turn
+// coalesces. The port is ref'd only while a flush is pending — an active
+// MessagePort holds the Node event loop open. ref/unref are Node-only.
+export const createMacrotaskPoster = (callback: () => void): (() => void) => {
+  if (typeof MessageChannel !== "undefined") {
+    let port1: (MessagePort & { ref?: () => void; unref?: () => void }) | null =
+      null;
+    let port2: MessagePort;
+    return () => {
+      if (!port1) {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+          port1?.unref?.();
+          callback();
+        };
+        port1 = channel.port1;
+        port2 = channel.port2;
+      }
+      port1.ref?.();
+      port2!.postMessage(null);
+    };
+  }
+  return () => setTimeout(callback, 0);
+};

package/src/util/methodProxy.ts

@@ -0,0 +1,16 @@
+export const createMethodProxy = <T extends object>(
+  dispatch: (method: string, params: unknown[]) => Promise<unknown>,
+): T => {
+  const memo = new Map<string, (...params: unknown[]) => Promise<unknown>>();
+  return new Proxy({} as T, {
+    get: (_target, method) => {
+      if (typeof method !== "string") return undefined;
+      let fn = memo.get(method);
+      if (fn === undefined) {
+        fn = (...params: unknown[]) => dispatch(method, params);
+        memo.set(method, fn);
+      }
+      return fn;
+    },
+  });
+};

package/src/util/randomId.ts

@@ -0,0 +1,4 @@
+export const randomId = (): string =>
+  typeof crypto !== "undefined" && "randomUUID" in crypto
+    ? crypto.randomUUID()
+    : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;

package/src/util/statePath.ts

@@ -0,0 +1,61 @@
+export type StatePath = readonly (string | number)[];
+
+export const isUnsafeKey = (
+  key: string | number,
+  parent: string | number | undefined,
+) => key === "__proto__" || (key === "prototype" && parent === "constructor");
+
+export type WalkedPath = {
+  /** Container of the final key; undefined when the path is empty. */
+  parent: unknown;
+  key: string | number;
+  leaf: unknown;
+};
+
+// "read": lenient, never fails — missing steps yield an undefined leaf.
+// "parent": every step before the last must resolve; the leaf may not exist.
+// "resolve": every step including the last must resolve.
+// Strict modes require array+integer for number keys, plain object for string
+// keys, and reject unsafe (prototype-polluting) segments.
+export const walkStatePath = (
+  root: unknown,
+  path: StatePath,
+  mode: "read" | "parent" | "resolve",
+): WalkedPath | undefined => {
+  let parent: unknown = undefined;
+  let key: string | number = "";
+  let node: unknown = root;
+  for (let depth = 0; depth < path.length; depth++) {
+    const k = path[depth]!;
+    const mustResolve =
+      mode === "resolve" || (mode === "parent" && depth < path.length - 1);
+    if (mode !== "read") {
+      if (typeof k === "number") {
+        if (!Array.isArray(node) || !Number.isInteger(k) || k < 0) {
+          return undefined;
+        }
+        if (mustResolve && k >= node.length) return undefined;
+      } else {
+        if (
+          isUnsafeKey(k, path[depth - 1]) ||
+          typeof node !== "object" ||
+          node === null ||
+          Array.isArray(node)
+        ) {
+          return undefined;
+        }
+        if (mustResolve && !Object.hasOwn(node, k)) return undefined;
+      }
+    }
+    parent = node;
+    key = k;
+    node =
+      typeof node === "object" && node !== null && Object.hasOwn(node, k)
+        ? (node as Record<string | number, unknown>)[k]
+        : undefined;
+  }
+  return { parent, key, leaf: node };
+};
+
+export const readAtPath = (root: unknown, path: StatePath): unknown =>
+  walkStatePath(root, path, "read")!.leaf;