statewire 0.0.0-0 → 0.0.1

package/src/host/draft.ts

@@ -0,0 +1,155 @@
+import type { StatewireOp, StatewirePath } from "../wire/ops";
+
+export type ServerOp = Exclude<StatewireOp, { op: "event" }>;
+
+export type DraftHost = {
+  root: () => unknown;
+  record: (op: ServerOp) => void;
+};
+
+export const frozen = (value: unknown): unknown => {
+  if (value instanceof Date) return new Date(value.getTime());
+  if (Array.isArray(value)) {
+    return value.map((item) => frozen(item) ?? null);
+  }
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) {
+      const item = frozen((value as Record<string, unknown>)[key]);
+      if (item !== undefined) out[key] = item;
+    }
+    return out;
+  }
+  return typeof value === "function" ? undefined : value;
+};
+
+const lookup = (root: unknown, path: StatewirePath): unknown => {
+  let node = root;
+  for (const key of path) {
+    node = (node as Record<string | number, unknown>)[key];
+  }
+  return node;
+};
+
+const isIndex = (key: string) => /^(0|[1-9]\d*)$/.test(key);
+
+const invalid = (path: StatewirePath, message: string) =>
+  new Error(`statewire: ${message} at path: ${path.join(".")}`);
+
+export const createStateDraft = <T>(
+  host: DraftHost,
+  path: StatewirePath = [],
+): T => {
+  const node = () => lookup(host.root(), path);
+
+  const assign = (
+    container: Record<string | number, unknown>,
+    key: string | number,
+    value: unknown,
+  ) => {
+    const old = Object.hasOwn(container, key) ? container[key] : undefined;
+    if (old === value) return;
+    if (
+      typeof old === "string" &&
+      typeof value === "string" &&
+      value.startsWith(old)
+    ) {
+      host.record({
+        op: "append",
+        path: [...path, key],
+        value: value.slice(old.length),
+      });
+      return;
+    }
+    host.record({ op: "replace", path: [...path, key], value });
+  };
+
+  return new Proxy(node() as object, {
+    get: (_target, prop) => {
+      const current = node() as Record<string | number, unknown>;
+      if (typeof prop === "symbol") {
+        return (current as unknown as Record<symbol, unknown>)[prop];
+      }
+      const key = Array.isArray(current) && isIndex(prop) ? Number(prop) : prop;
+      const value = current[key];
+      if (typeof value === "object" && value !== null) {
+        return createStateDraft(host, [...path, key]);
+      }
+      return value;
+    },
+    set: (_target, prop, rawValue) => {
+      if (typeof prop === "symbol") return false;
+      const current = node();
+      const value = frozen(rawValue);
+      if (Array.isArray(current)) {
+        if (prop === "length") {
+          const next = Number(value);
+          if (!Number.isInteger(next) || next < 0 || next > current.length) {
+            throw invalid(path, `cannot set list length to ${String(value)}`);
+          }
+          for (let i = current.length - 1; i >= next; i--) {
+            host.record({ op: "remove", path: [...path, i] });
+          }
+          return true;
+        }
+        if (!isIndex(prop)) {
+          throw invalid(path, `cannot set key "${prop}" on a list`);
+        }
+        const index = Number(prop);
+        if (index > current.length) {
+          throw invalid(path, `list index ${index} out of range`);
+        }
+        if (index === current.length) {
+          host.record({ op: "add", path: [...path, index], value });
+          return true;
+        }
+        assign(
+          current as unknown as Record<string | number, unknown>,
+          index,
+          value,
+        );
+        return true;
+      }
+      assign(current as Record<string, unknown>, prop, value);
+      return true;
+    },
+    deleteProperty: (_target, prop) => {
+      if (typeof prop === "symbol") return false;
+      const current = node();
+      if (Array.isArray(current)) {
+        if (!isIndex(prop) || Number(prop) >= current.length) return true;
+        host.record({ op: "remove", path: [...path, Number(prop)] });
+        return true;
+      }
+      if (!Object.hasOwn(current as object, prop)) return true;
+      host.record({ op: "remove", path: [...path, prop] });
+      return true;
+    },
+    defineProperty: () => {
+      throw new Error(
+        "statewire: defineProperty is not supported on a state draft",
+      );
+    },
+    setPrototypeOf: () => {
+      throw new Error(
+        "statewire: setPrototypeOf is not supported on a state draft",
+      );
+    },
+    preventExtensions: () => {
+      throw new Error(
+        "statewire: preventExtensions is not supported on a state draft",
+      );
+    },
+    has: (_target, prop) => Reflect.has(node() as object, prop),
+    ownKeys: () => Reflect.ownKeys(node() as object),
+    getOwnPropertyDescriptor: (_target, prop) => {
+      const current = node() as object;
+      const desc = Reflect.getOwnPropertyDescriptor(current, prop);
+      if (!desc) return undefined;
+      return {
+        ...desc,
+        configurable: !Array.isArray(current) || prop !== "length",
+      };
+    },
+  }) as T;
+};

package/src/host/engine.ts

@@ -0,0 +1,13 @@
+/**
+ * Definitive handler rejection: the command settles rejected and
+ * message/payload travel to the client's rejected promise.
+ */
+export class StatewireReject extends Error {
+  readonly payload?: unknown;
+
+  constructor(message: string, options?: { payload?: unknown }) {
+    super(message);
+    this.name = "StatewireReject";
+    if (options?.payload !== undefined) this.payload = options.payload;
+  }
+}

package/src/host/host.ts

@@ -0,0 +1,481 @@
+import { useEffect, useState } from "react";
+import { applyOp, applyOps } from "../wire/ops";
+import type { StatewireOp, StatewirePath } from "../wire/ops";
+import { StatewireReject } from "./engine";
+import { createStateDraft, frozen } from "./draft";
+import type { ServerOp } from "./draft";
+import { StatewireSendError } from "../types";
+import type {
+  StatewireCommands,
+  StatewireCommandsProxy,
+  StatewireStateSource,
+} from "../types";
+
+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>();
+
+export const getStateHost = (state: object): StateHost | undefined =>
+  stateHosts.get(state);
+
+type StateCell = {
+  current: unknown;
+  draft: object | null;
+  changed: StatewirePath[];
+  onOp: ((op: ServerOp) => void) | null;
+  onChange: (() => void) | null;
+  ctl: StatewireStateCtl;
+  host: StateHost;
+  bump: () => void;
+};
+
+export const useStatewireState = <TState>(
+  init: () => TState,
+): readonly [TState, StatewireStateCtl] => {
+  const [, setVersion] = useState(0);
+  const [cell] = useState((): StateCell => {
+    const c: StateCell = {
+      current: frozen(init()),
+      draft: null,
+      changed: [[]],
+      onOp: null,
+      onChange: null,
+      bump: () => setVersion((v) => v + 1),
+      ctl: {
+        apply: (ops) => {
+          const result = applyOps(c.current, 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.changed.push(...result.changedPaths);
+          c.bump();
+          c.onChange?.();
+        },
+      },
+      host: {
+        root: () => c.current,
+        setOnOp: (listener) => {
+          c.onOp = listener;
+        },
+        setOnChange: (listener) => {
+          c.onChange = listener;
+        },
+        takeChanged: () => {
+          const changed = c.changed;
+          c.changed = [];
+          return changed;
+        },
+      },
+    };
+    return c;
+  });
+
+  let value = cell.current;
+  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);
+        cell.onOp?.(op);
+        cell.bump();
+        cell.onChange?.();
+      },
+    });
+    stateHosts.set(cell.draft, cell.host);
+    value = cell.draft;
+  }
+  return [value as TState, cell.ctl] 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>();
+
+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
+ * 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>,
+  ): CommandExecution<T> => {
+    const state: ExecutionState = { acked: false, settled: null, bind: null };
+    const execution = Object.freeze({}) as unknown as CommandExecution<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>(): [
+      CommandExecution<T>,
+      CommandExecutionResolvers<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 CommandsHost = {
+  setListener: (listener: CommandsListener | null) => void;
+};
+
+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;
+};
+
+type ActiveInvocation = CommandsInvocation & { acked: boolean };
+
+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);
+};
+
+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: frozen(settled.value) };
+    cell.listener?.onSettle(inv, outcome);
+    call.resolve(outcome.payload);
+  } else {
+    const error = toSendError(settled.error);
+    cell.listener?.onSettle(inv, { type: "rejected", error });
+    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) {
+    call.reject(
+      new StatewireSendError({ fate: "unknown-command", cause: "server" }),
+    );
+    pump(cell);
+    return;
+  }
+  const inv: ActiveInvocation = {
+    method: call.method,
+    params: call.params,
+    ts: call.ts,
+    seq: ++cell.seq,
+    acked: false,
+  };
+  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);
+};
+
+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>> => {
+  const [built] = useState(() => {
+    const cell: CommandsCell = {
+      handlers: null,
+      queue: [],
+      running: false,
+      listener: null,
+      seq: 0,
+      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);
+          }
+          return fn;
+        },
+      },
+    );
+    commandsHosts.set(proxy, {
+      setListener: (listener) => {
+        cell.listener = listener;
+      },
+    });
+    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): EmitHost | undefined =>
+  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(frozen(event));
+    };
+    emitHosts.set(emit, {
+      setSink: (sink) => {
+        cell.sink = sink;
+      },
+    });
+    return emit;
+  });
+  return built;
+};

package/src/index.ts

@@ -0,0 +1,65 @@
+import type { StatewireStateSource, StatewireTransport } from "./types";
+import type { StatewireOp } from "./wire/ops";
+import type {
+  SendFailure as StatewireSendFailure,
+  StatewireChanges,
+  StatewireCommand,
+  StatewireCommands,
+  StatewireCommandsProxy,
+  StatewireCommandUpdate,
+  StatewireHelpers,
+  StatewireOptimistic,
+  StatewireOptimisticContext,
+  StatewireOptions,
+} from "./types";
+import type {
+  StatewireSSEOptions,
+  StatewireConnection,
+} from "./transports/sse";
+import type { StatewireWSOptions } from "./transports/ws";
+import { Statewire } from "./statewire";
+
+export { Statewire };
+export { useStatewire, StatewireResource } from "./statewire";
+export { applyOps } from "./wire/ops";
+export { StatewireSSE } from "./transports/sse";
+export { StatewireWS } from "./transports/ws";
+export { StatewireSendError } from "./types";
+
+export namespace Statewire {
+  export type Connection = StatewireConnection;
+  export type ConnectionStatus = StatewireConnection["status"];
+  export type Transport<
+    TState = any,
+    TCommands extends StatewireCommands = StatewireCommands,
+    TEvent = any,
+  > = StatewireTransport<TState, TCommands, TEvent>;
+  export type StateSource = StatewireStateSource;
+  export type SSEOptions = StatewireSSEOptions;
+  export type WSOptions = StatewireWSOptions;
+  export type Options<
+    TState,
+    TCommands extends StatewireCommands = StatewireCommands,
+    TEvent = any,
+  > = StatewireOptions<TState, TCommands, TEvent>;
+  export type Helpers<
+    TState,
+    TCommands extends StatewireCommands = StatewireCommands,
+  > = StatewireHelpers<TState, TCommands>;
+  export type Commands = StatewireCommands;
+  export type Command<TCommands extends StatewireCommands = StatewireCommands> =
+    StatewireCommand<TCommands>;
+  export type CommandsProxy<TCommands extends StatewireCommands> =
+    StatewireCommandsProxy<TCommands>;
+  export type CommandUpdate<
+    TCommands extends StatewireCommands = StatewireCommands,
+  > = StatewireCommandUpdate<TCommands>;
+  export type Optimistic<
+    TState,
+    TCommands extends StatewireCommands = StatewireCommands,
+  > = StatewireOptimistic<TState, TCommands>;
+  export type OptimisticContext = StatewireOptimisticContext;
+  export type SendFailure = StatewireSendFailure;
+  export type Changes = StatewireChanges;
+  export type Op = StatewireOp;
+}