statewire 0.0.0-0 → 0.0.2

package/src/client/timing.ts

@@ -0,0 +1,14 @@
+export const timing = {
+  backoffBaseMs: 250,
+  backoffMaxMs: 30_000,
+  heartbeatTimeoutMs: 30_000,
+};
+
+export const backoff = (attempt: number) =>
+  Math.min(timing.backoffBaseMs * 2 ** (attempt - 1), timing.backoffMaxMs);
+
+export const retryDelay = (error: unknown, attempt: number): number => {
+  const retryAfterMs = (error as { retryAfterMs?: unknown } | undefined)
+    ?.retryAfterMs;
+  return typeof retryAfterMs === "number" ? retryAfterMs : backoff(attempt);
+};

package/src/host/adapter.ts

@@ -0,0 +1,33 @@
+import type { StatewireHostInternal } from "../host-internal";
+
+export const CLIENT_QUERY_PARAM = "client";
+
+export const clientIdFromUrl = (url: string | null | undefined): string => {
+  if (!url) {
+    throw new Error("statewire: cannot resolve client id: missing url");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url, "http://statewire");
+  } catch {
+    throw new Error(
+      `statewire: cannot resolve client id: unparseable url "${url}"`,
+    );
+  }
+  const clientId = parsed.searchParams.get(CLIENT_QUERY_PARAM);
+  if (!clientId) {
+    throw new Error(
+      `statewire: url is missing the "${CLIENT_QUERY_PARAM}" query parameter`,
+    );
+  }
+  return clientId;
+};
+
+export const textFrameOrClose = (
+  socket: Pick<StatewireHostInternal.Socket, "close">,
+  data: unknown,
+): string | null => {
+  if (typeof data === "string") return data;
+  socket.close(1008, "text frames only");
+  return null;
+};

package/src/host/draft.ts

@@ -0,0 +1,323 @@
+import type { Statewire } from "../types";
+import type { StatewirePath } from "../wire/ops";
+import { sanitizeValue } from "../wire/ops";
+import { isUnsafeKey } from "../util/statePath";
+import { sharedDraftTraps } from "../util/draftTraps";
+
+export type ServerOp = Exclude<Statewire.Op, { op: "event" }>;
+
+export type DraftHost = {
+  snapshot: () => unknown;
+  record: (op: ServerOp, changedPath: StatewirePath) => void;
+};
+
+export type StateDraft<T> = {
+  proxy: T;
+  /** Seal pending writes and return the committed state. */
+  flush: () => unknown;
+  /** Committed state was replaced externally; cached nodes re-resolve. */
+  invalidate: () => void;
+};
+
+const NODE = Symbol("statewire.draftNode");
+
+type NodeHandle = {
+  append: (key: string | number, suffix: string) => void;
+};
+
+const isIndex = (key: string) => /^(0|[1-9]\d*)$/.test(key);
+
+const invalid = (path: StatewirePath, message: string) =>
+  new Error(`statewire: ${message} at path: ${path.join(".")}`);
+
+type Container = Record<string | number, unknown>;
+
+type Node = {
+  parent: Node | null;
+  key: string | number;
+  path: StatewirePath;
+  gen: number;
+  base: unknown;
+  copy: Container | null;
+  children: Map<string, Node>;
+  isArray: boolean;
+  proxy: object;
+  handle: NodeHandle;
+};
+
+export const createStateDraft = <T>(host: DraftHost): StateDraft<T> => {
+  let gen = 0;
+  const dirty: Node[] = [];
+
+  const latest = (node: Node): unknown => node.copy ?? node.base;
+
+  const resolve = (node: Node): Node => {
+    if (node.gen === gen) return node;
+    node.gen = gen;
+    if (node.parent === null) {
+      if (node.copy === null) node.base = host.snapshot();
+      return node;
+    }
+    const value = (latest(resolve(node.parent)) as Container)[node.key];
+    if (value !== latest(node)) {
+      node.base = value;
+      node.copy = null;
+    }
+    return node;
+  };
+
+  const prepareForWrite = (node: Node): Container => {
+    resolve(node);
+    if (node.copy !== null) return node.copy;
+    const base = node.base;
+    node.copy = Array.isArray(base)
+      ? (base.slice() as unknown as Container)
+      : { ...(base as Container) };
+    dirty.push(node);
+    if (node.parent !== null) {
+      prepareForWrite(node.parent)[node.key] = node.copy;
+    }
+    return node.copy;
+  };
+
+  const changedPathFor = (node: Node, key: string | number): StatewirePath =>
+    Array.isArray(latest(node)) ? node.path : [...node.path, key];
+
+  const applyAppend = (node: Node, rawKey: string | number, suffix: string) => {
+    const container = latest(resolve(node)) as Container;
+    const key =
+      Array.isArray(container) && typeof rawKey === "string" && isIndex(rawKey)
+        ? Number(rawKey)
+        : rawKey;
+    const existing = Object.hasOwn(container as object, key)
+      ? container[key]
+      : undefined;
+    if (typeof existing !== "string") {
+      throw invalid([...node.path, key], "cannot append to a non-string");
+    }
+    if (suffix === "") return;
+    prepareForWrite(node)[key] = existing + suffix;
+    host.record(
+      { op: "add", path: [...node.path, key, existing.length], value: suffix },
+      changedPathFor(node, key),
+    );
+  };
+
+  const createNode = (parent: Node | null, key: string | number): Node => {
+    const seed =
+      parent === null ? host.snapshot() : (latest(parent) as Container)[key];
+    const node: Node = {
+      parent,
+      key,
+      path: parent === null ? [] : [...parent.path, key],
+      gen,
+      base: seed,
+      copy: null,
+      children: new Map(),
+      isArray: Array.isArray(seed),
+      proxy: null!,
+      handle: null!,
+    };
+    node.handle = {
+      append: (childKey, suffix) => applyAppend(node, childKey, suffix),
+    };
+
+    const current = () => latest(resolve(node));
+
+    const childProxy = (
+      prop: string,
+      childKey: string | number,
+      value: object,
+    ) => {
+      let child = node.children.get(prop);
+      if (child === undefined || child.isArray !== Array.isArray(value)) {
+        child = createNode(node, childKey);
+        node.children.set(prop, child);
+      }
+      return child.proxy;
+    };
+
+    const assign = (
+      container: Container,
+      key: string | number,
+      value: unknown,
+    ) => {
+      const old = Object.hasOwn(container as object, key)
+        ? container[key]
+        : undefined;
+      if (old === value) return;
+      const isObjectContainer = !Array.isArray(container);
+      if (
+        isObjectContainer &&
+        isUnsafeKey(key, node.path[node.path.length - 1])
+      ) {
+        throw invalid([...node.path, key], `cannot set unsafe key "${key}"`);
+      }
+      if (value === undefined) {
+        if (!isObjectContainer) {
+          throw invalid([...node.path, key], "cannot serialize undefined");
+        }
+        delete prepareForWrite(node)[key];
+        host.record({ op: "remove", path: [...node.path, key] }, [
+          ...node.path,
+          key,
+        ]);
+        gen++;
+        return;
+      }
+      prepareForWrite(node)[key] = isObjectContainer
+        ? sanitizeValue(value, key as string)
+        : sanitizeValue(value);
+      host.record(
+        { op: "replace", path: [...node.path, key], value },
+        changedPathFor(node, key),
+      );
+      if (
+        (typeof old === "object" && old !== null) ||
+        (typeof value === "object" && value !== null)
+      ) {
+        gen++;
+      }
+    };
+
+    node.proxy = new Proxy(seed as object, {
+      get: (_target, prop) => {
+        if (prop === NODE) return node.handle;
+        const container = current();
+        if (typeof prop === "symbol") {
+          return (container as Record<symbol, unknown>)[prop];
+        }
+        const c = container as Container;
+        const key = Array.isArray(c) && isIndex(prop) ? Number(prop) : prop;
+        const value = c[key];
+        if (typeof value === "object" && value !== null) {
+          return childProxy(prop, key, value);
+        }
+        return value;
+      },
+      set: (_target, prop, value) => {
+        if (typeof prop === "symbol") return false;
+        const container = current();
+        if (Array.isArray(container)) {
+          if (prop === "length") {
+            const next = Number(value);
+            if (
+              !Number.isInteger(next) ||
+              next < 0 ||
+              next > container.length
+            ) {
+              throw invalid(
+                node.path,
+                `cannot set list length to ${String(value)}`,
+              );
+            }
+            if (next === container.length) return true;
+            const copy = prepareForWrite(node) as unknown as unknown[];
+            for (let i = container.length - 1; i >= next; i--) {
+              copy.splice(i, 1);
+              host.record({ op: "remove", path: [...node.path, i] }, node.path);
+            }
+            gen++;
+            return true;
+          }
+          if (!isIndex(prop)) {
+            throw invalid(node.path, `cannot set key "${prop}" on a list`);
+          }
+          const index = Number(prop);
+          if (index > container.length) {
+            throw invalid(node.path, `list index ${index} out of range`);
+          }
+          if (index === container.length) {
+            if (value === undefined) {
+              throw invalid(
+                [...node.path, index],
+                "cannot serialize undefined",
+              );
+            }
+            prepareForWrite(node)[index] = sanitizeValue(value);
+            host.record(
+              { op: "add", path: [...node.path, index], value },
+              node.path,
+            );
+            gen++;
+            return true;
+          }
+          assign(container as unknown as Container, index, value);
+          return true;
+        }
+        assign(container as Container, prop, value);
+        return true;
+      },
+      deleteProperty: (_target, prop) => {
+        if (typeof prop === "symbol") return false;
+        const container = current();
+        if (Array.isArray(container)) {
+          if (!isIndex(prop) || Number(prop) >= container.length) return true;
+          const index = Number(prop);
+          (prepareForWrite(node) as unknown as unknown[]).splice(index, 1);
+          host.record({ op: "remove", path: [...node.path, index] }, node.path);
+          gen++;
+          return true;
+        }
+        if (!Object.hasOwn(container as object, prop)) return true;
+        if (isUnsafeKey(prop, node.path[node.path.length - 1])) {
+          throw invalid(
+            [...node.path, prop],
+            `cannot remove unsafe key "${prop}"`,
+          );
+        }
+        delete prepareForWrite(node)[prop];
+        host.record({ op: "remove", path: [...node.path, prop] }, [
+          ...node.path,
+          prop,
+        ]);
+        gen++;
+        return true;
+      },
+      has: (_target, prop) => Reflect.has(current() as object, prop),
+      ...sharedDraftTraps(() => current() as object, "on a state draft"),
+    });
+    return node;
+  };
+
+  const root = createNode(null, "");
+
+  return {
+    proxy: root.proxy as T,
+    flush: () => {
+      if (dirty.length === 0) return host.snapshot();
+      for (const node of dirty) {
+        if (node.copy !== null) {
+          node.base = node.copy;
+          node.copy = null;
+        }
+      }
+      dirty.length = 0;
+      return root.base;
+    },
+    invalidate: () => {
+      gen++;
+    },
+  };
+};
+
+/**
+ * Append `suffix` to the string at `parent[key]` on a statewire state draft,
+ * recording a single end-offset text-insert `add` op instead of a full
+ * `replace` — use it on token-streaming hot paths. Throws when the current
+ * value is not a string.
+ */
+export const append = <TKey extends string | number>(
+  parent: { readonly [P in TKey]: string },
+  key: TKey,
+  suffix: string,
+): void => {
+  const handle = (parent as { [NODE]?: NodeHandle })[NODE];
+  if (handle === undefined) {
+    throw new Error("statewire: append expects a state draft object");
+  }
+  if (typeof suffix !== "string") {
+    throw new Error("statewire: append suffix must be a string");
+  }
+  handle.append(key, suffix);
+};

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;
+  }
+}