statewire 0.17.0 → 0.17.2

package/src/document.ts

@@ -0,0 +1,185 @@
+import { isUnsafeKey, walkStatePath } from "./util/statePath";
+
+export namespace StatewireDocument {
+  export type Value =
+    | null
+    | boolean
+    | number
+    | string
+    | Value[]
+    | { [key: string]: Value };
+  export type MetaEntry = { path: (string | number)[]; type: "date" };
+  export type Encoded = { value: Value; meta?: MetaEntry[] };
+}
+
+const invalid = (message: string): never => {
+  throw new Error(`statewire: protocol error: invalid document: ${message}`);
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  (Object.getPrototypeOf(value) === Object.prototype ||
+    Object.getPrototypeOf(value) === null);
+
+const copyValue = (
+  value: unknown,
+  dates: boolean,
+  meta: StatewireDocument.MetaEntry[],
+  path: (string | number)[] = [],
+  ancestors = new Set<object>(),
+): StatewireDocument.Value => {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return value;
+  if (typeof value === "number") {
+    if (
+      !Number.isFinite(value) ||
+      (Number.isInteger(value) && !Number.isSafeInteger(value))
+    )
+      invalid(
+        `number at ${JSON.stringify(path)} must be finite and within the safe integer range`,
+      );
+    return value;
+  }
+  if (dates && value instanceof Date) {
+    if (
+      !Number.isFinite(value.getTime()) ||
+      value.getUTCFullYear() < 1 ||
+      value.getUTCFullYear() > 9999
+    )
+      invalid(
+        `date at ${JSON.stringify(path)} must have a year from 0001 to 9999`,
+      );
+    meta.push({ path, type: "date" });
+    return value.toISOString();
+  }
+  if (!Array.isArray(value) && !isObject(value))
+    return invalid(`unsupported value at ${JSON.stringify(path)}`);
+  if (ancestors.has(value)) invalid(`cycle at ${JSON.stringify(path)}`);
+  ancestors.add(value);
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  for (const key of Reflect.ownKeys(descriptors)) {
+    if (Array.isArray(value) && key === "length") continue;
+    if (typeof key !== "string")
+      invalid(`symbol key at ${JSON.stringify(path)}`);
+    const descriptor = descriptors[key as string]!;
+    if (!("value" in descriptor) || !descriptor.enumerable)
+      invalid(
+        `property at ${JSON.stringify([...path, key])} must be enumerable data`,
+      );
+    if (isUnsafeKey(key as string, path.at(-1)))
+      invalid(`unsafe key at ${JSON.stringify([...path, key])}`);
+    if (
+      Array.isArray(value) &&
+      (!/^(0|[1-9]\d*)$/.test(key as string) || Number(key) >= value.length)
+    )
+      invalid(
+        `unsupported array property at ${JSON.stringify([...path, key])}`,
+      );
+  }
+  let result: StatewireDocument.Value;
+  if (Array.isArray(value)) {
+    result = Array.from({ length: value.length }, (_, index) => {
+      if (!Object.hasOwn(value, index))
+        invalid(`sparse array at ${JSON.stringify(path)}`);
+      return copyValue(
+        descriptors[index]!.value,
+        dates,
+        meta,
+        [...path, index],
+        ancestors,
+      );
+    });
+  } else {
+    result = Object.fromEntries(
+      Object.keys(descriptors).map((key) => [
+        key,
+        copyValue(
+          descriptors[key]!.value,
+          dates,
+          meta,
+          [...path, key],
+          ancestors,
+        ),
+      ]),
+    );
+  }
+  ancestors.delete(value);
+  return result;
+};
+
+/** Encode a document value as detached JSON data with date metadata. */
+export const encodeDocument = (value: unknown): StatewireDocument.Encoded => {
+  const meta: StatewireDocument.MetaEntry[] = [];
+  const encoded = copyValue(value, true, meta);
+  return meta.length ? { value: encoded, meta } : { value: encoded };
+};
+
+/** Validate and decode a document into detached values with native dates. */
+export const decodeDocument = (encoded: unknown): unknown => {
+  const document = copyValue(encoded, false, []);
+  if (
+    !isObject(document) ||
+    !Object.hasOwn(document, "value") ||
+    Object.keys(document).some((key) => key !== "value" && key !== "meta")
+  )
+    return invalid("expected an object with value and optional meta");
+  const value: unknown = document.value;
+  if (!Object.hasOwn(document, "meta")) return value;
+  if (!Array.isArray(document.meta)) return invalid("meta must be an array");
+  return reviveDocumentValue(value, document.meta, {
+    rejectUnknown: true,
+    canonical: true,
+  });
+};
+
+export const reviveDocumentValue = (
+  value: unknown,
+  meta: unknown,
+  { rejectUnknown = false, canonical = false } = {},
+): unknown => {
+  if (!Array.isArray(meta)) return invalid("meta must be an array");
+  const seen = new Set<string>();
+  for (const entry of meta) {
+    if (
+      !isObject(entry) ||
+      !Array.isArray(entry.path) ||
+      (canonical &&
+        Object.keys(entry).some((key) => key !== "path" && key !== "type")) ||
+      !entry.path.every(
+        (segment) =>
+          typeof segment === "string" ||
+          (typeof segment === "number" &&
+            Number.isSafeInteger(segment) &&
+            segment >= 0),
+      )
+    )
+      return invalid("meta entry requires a path array and type date");
+    if (entry.type !== "date") {
+      if (rejectUnknown) invalid(`unknown meta type: ${String(entry.type)}`);
+      continue;
+    }
+    const path = entry.path as (string | number)[];
+    const identity = JSON.stringify(path);
+    if (seen.has(identity)) invalid(`duplicate meta path ${identity}`);
+    seen.add(identity);
+    const walked = walkStatePath(value, path, "resolve");
+    if (!walked || typeof walked.leaf !== "string")
+      return invalid(`meta path ${identity} must resolve to a string`);
+    const date = new Date(walked.leaf);
+    if (
+      canonical
+        ? !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(walked.leaf) ||
+          !Number.isFinite(date.getTime()) ||
+          date.getUTCFullYear() < 1 ||
+          date.toISOString() !== walked.leaf
+        : !/(?:T| )\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i.test(
+            walked.leaf,
+          ) || !Number.isFinite(date.getTime())
+    )
+      return invalid(`invalid date at meta path ${identity}`);
+    if (walked.parent === undefined) value = date;
+    else (walked.parent as Record<string | number, unknown>)[walked.key] = date;
+  }
+  return value;
+};

package/src/host/socket.ts

@@ -1,3 +1,4 @@
+import { encodeDocument } from "../document";
 import {
   DEFAULT_PROTOCOL,
   WIRE_VERSION,
@@ -15,7 +16,7 @@ import { StatewireSendError } from "../types";
 import type { Statewire } from "../types";
 import type { StatewireHost } from "../host";
 import type { StatewireHostInternal } from "../host-internal";
-import { encodeValue, reviveValue } from "../wire/meta";
+import { reviveValue } from "../wire/meta";
 import {
   COMMAND_CAPACITY_RETRY_MS,
   MAX_COMMANDS_PER_FRAME,
@@ -25,7 +26,7 @@ import {
   MAX_INFLIGHT_COMMANDS_PER_HOST,
 } from "../wire/limits";
 import { createMacrotaskPoster } from "../util/macrotask";
-import type { StatewireMetaEntry } from "../wire/meta";
+import type { StatewireDocument } from "../document";
 import type { StatewirePath } from "../wire/ops";
 import type { StatewireCmd, StatewireEnvelope } from "../client/connection";
 import { frames as serveFrames, stream as serveStream } from "./http";
@@ -79,7 +80,7 @@ type WireOp = {
   op: string;
   path?: StatewirePath;
   value?: unknown;
-  meta?: StatewireMetaEntry[];
+  meta?: StatewireDocument.MetaEntry[];
 };
 
 type Admission = {
@@ -242,9 +243,9 @@ const frameIsOversized = (raw: string): boolean =>
 
 const encodePayload = (
   payload: unknown,
-): { payload?: unknown; meta?: StatewireMetaEntry[] } => {
+): { payload?: unknown; meta?: StatewireDocument.MetaEntry[] } => {
   if (payload === undefined) return {};
-  const { value, meta } = encodeValue(payload);
+  const { value, meta } = encodeDocument(payload);
   return { payload: value, ...(meta !== undefined && { meta }) };
 };
 
@@ -374,7 +375,7 @@ const recordOp = (
   },
 ) => {
   if (op.op === "replace" || op.op === "add") {
-    const { value, meta } = encodeValue(op.value);
+    const { value, meta } = encodeDocument(op.value);
     h.pendingOps.push({ ...op, value, ...(meta !== undefined && { meta }) });
   } else {
     h.pendingOps.push(op);
@@ -1290,7 +1291,7 @@ export const register = (
   gcClients(h);
   notifyClientRecords(h);
   ensureHeartbeat(h);
-  const { value, meta } = encodeValue(h.stateHost!.snapshot());
+  const { value, meta } = encodeDocument(h.stateHost!.snapshot());
   const hello: StatewireEnvelope = {
     ops: [
       {

package/src/index.ts

@@ -1,4 +1,6 @@
 export type { Statewire } from "./types";
+export { encodeDocument, decodeDocument } from "./document";
+export type { StatewireDocument } from "./document";
 export { StatewireClient, useStatewire, StatewireResource } from "./statewire";
 export { StatewireHttp } from "./transports/sse";
 export { StatewireWebsocket } from "./transports/ws";

package/src/statewire.ts

@@ -436,7 +436,12 @@ export namespace StatewireClient {
     clientId: string;
     nextSeq: number;
     ctxNextSeq: number;
-    context?: { ops: unknown[]; pending: { seq: number; ops: unknown[] }[] };
+    context?: {
+      ops: unknown[];
+      pending: { seq: number; ops: unknown[] }[];
+      /** Recover the original wire's unpersisted single-document context after the next hello. */
+      recover?: "version-1";
+    };
     commands: readonly SessionCommand[];
     /** Terminal verdicts parked for the sharer that minted the seq (shared storage only). */
     verdicts?: readonly SessionVerdict[];

package/src/wire/meta.ts

@@ -1,60 +1,10 @@
-import { walkStatePath } from "../util/statePath";
+import {
+  encodeDocument,
+  reviveDocumentValue as reviveValue,
+} from "../document";
+import type { StatewireDocument } from "../document";
 
-export type StatewireMetaEntry = {
-  path: (string | number)[];
-  type: string;
-};
-
-const fault = (message: string): never => {
-  throw new Error(`statewire: protocol error: ${message}`);
-};
-
-const isPath = (path: unknown): path is (string | number)[] =>
-  Array.isArray(path) &&
-  path.every(
-    (seg) =>
-      typeof seg === "string" ||
-      (typeof seg === "number" && Number.isInteger(seg)),
-  );
-
-/** Revive meta-typed locations inside a wire value (in place). Clients skip
- * unknown types; hosts pass `rejectUnknown` to fault on them instead. */
-export const reviveValue = (
-  value: unknown,
-  meta: unknown,
-  { rejectUnknown = false } = {},
-): unknown => {
-  if (!Array.isArray(meta)) return fault("meta must be an array");
-  for (const entry of meta as { path?: unknown; type?: unknown }[]) {
-    const path =
-      typeof entry === "object" && entry !== null ? entry.path : null;
-    if (!isPath(path)) return fault("meta entry must carry a path array");
-    if (entry.type !== "date") {
-      if (rejectUnknown)
-        return fault(`unknown meta type: ${String(entry.type)}`);
-      continue;
-    }
-    const walked = walkStatePath(value, path, "resolve");
-    if (walked === undefined) {
-      return fault(`meta path ${path.join(".")} does not resolve`);
-    }
-    if (typeof walked.leaf !== "string") {
-      return fault(`meta path ${path.join(".")} must name a string`);
-    }
-    const date = new Date(walked.leaf);
-    if (
-      !/(?:T| )\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})$/i.test(
-        walked.leaf,
-      ) ||
-      Number.isNaN(date.getTime())
-    ) {
-      return fault(`invalid date at meta path ${path.join(".")}`);
-    }
-    if (walked.parent === undefined) return date;
-    (walked.parent as Record<string | number, unknown>)[walked.key] = date;
-  }
-  return value;
-};
+export { reviveDocumentValue as reviveValue } from "../document";
 
 export const reviveOps = (ops: unknown[]): unknown[] =>
   ops.map((op) => {
@@ -71,44 +21,11 @@ export const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(
   return { ...rest, payload: reviveValue(rest.payload, meta) } as T;
 };
 
-const walkDates = (
-  node: unknown,
-  path: (string | number)[],
-  meta: StatewireMetaEntry[],
-): unknown => {
-  if (node instanceof Date) {
-    meta.push({ path, type: "date" });
-    return node.toISOString();
-  }
-  if (Array.isArray(node)) {
-    return node.map((item, i) => walkDates(item, [...path, i], meta));
-  }
-  if (typeof node === "object" && node !== null) {
-    return Object.fromEntries(
-      Object.keys(node).map((key) => [
-        key,
-        walkDates((node as Record<string, unknown>)[key], [...path, key], meta),
-      ]),
-    );
-  }
-  return node;
-};
-
-/** Encode Date instances inside command params as canonical ISO strings,
- * recording their paths (starting at the param index) in meta. */
 export const encodeParams = (
   params: readonly unknown[],
-): { params: unknown[]; meta?: StatewireMetaEntry[] } => {
-  const meta: StatewireMetaEntry[] = [];
-  const encoded = params.map((param, i) => walkDates(param, [i], meta));
-  return meta.length > 0 ? { params: encoded, meta } : { params: encoded };
-};
-
-/** Encode Date instances inside a wire value, recording their paths in meta. */
-export const encodeValue = (
-  value: unknown,
-): { value: unknown; meta?: StatewireMetaEntry[] } => {
-  const meta: StatewireMetaEntry[] = [];
-  const encoded = walkDates(value, [], meta);
-  return meta.length > 0 ? { value: encoded, meta } : { value: encoded };
+): { params: unknown[]; meta?: StatewireDocument.MetaEntry[] } => {
+  const { value, meta } = encodeDocument(params);
+  return meta
+    ? { params: value as unknown[], meta }
+    : { params: value as unknown[] };
 };