statewire 0.0.1 → 0.0.3

package/src/host/draft.ts

@@ -1,34 +1,28 @@
-import type { StatewireOp, StatewirePath } from "../wire/ops";
+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<StatewireOp, { op: "event" }>;
+export type ServerOp = Exclude<Statewire.Op, { op: "event" }>;
 
 export type DraftHost = {
-  root: () => unknown;
-  record: (op: ServerOp) => void;
+  snapshot: () => unknown;
+  record: (op: ServerOp, changedPath: StatewirePath) => 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;
+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 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 NODE = Symbol("statewire.draftNode");
+
+type NodeHandle = {
+  append: (key: string | number, suffix: string) => void;
 };
 
 const isIndex = (key: string) => /^(0|[1-9]\d*)$/.test(key);
@@ -36,120 +30,294 @@ 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;
+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;
     }
-    host.record({ op: "replace", path: [...path, key], value });
+    return node.copy;
   };
 
-  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 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);
       }
-      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 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}"`);
       }
-      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 (value === undefined) {
+        if (!isObjectContainer) {
+          throw invalid([...node.path, key], "cannot serialize undefined");
         }
-        if (!isIndex(prop)) {
-          throw invalid(path, `cannot set key "${prop}" on a list`);
+        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 index = Number(prop);
-        if (index > current.length) {
-          throw invalid(path, `list index ${index} out of range`);
+        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);
         }
-        if (index === current.length) {
-          host.record({ op: "add", path: [...path, index], 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(
-          current as unknown as Record<string | number, unknown>,
-          index,
-          value,
-        );
+        assign(container as Container, prop, 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)] });
+      },
+      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;
+        }
       }
-      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",
-      );
+      dirty.length = 0;
+      return root.base;
     },
-    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",
-      );
+    invalidate: () => {
+      gen++;
     },
-    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;
+  };
+};
+
+/**
+ * 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);
 };