statewire 0.17.0 → 0.17.1

package/dist/wire/meta.js

@@ -1,36 +1,11 @@
-import { walkStatePath } from "../util/statePath.js";
+import { encodeDocument, reviveDocumentValue } from "../document.js";
 //#region src/wire/meta.ts
-const fault = (message) => {
-	throw new Error(`statewire: protocol error: ${message}`);
-};
-const isPath = (path) => 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. */
-const reviveValue = (value, meta, { rejectUnknown = false } = {}) => {
-	if (!Array.isArray(meta)) return fault("meta must be an array");
-	for (const entry of meta) {
-		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 === void 0) 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 === void 0) return date;
-		walked.parent[walked.key] = date;
-	}
-	return value;
-};
 const reviveOps = (ops) => ops.map((op) => {
 	if (typeof op !== "object" || op === null || !("meta" in op)) return op;
 	const { meta, ...rest } = op;
 	return {
 		...rest,
-		value: reviveValue(rest.value, meta)
+		value: reviveDocumentValue(rest.value, meta)
 	};
 });
 const reviveResponse = (response) => {
@@ -38,41 +13,17 @@ const reviveResponse = (response) => {
 	const { meta, ...rest } = response;
 	return {
 		...rest,
-		payload: reviveValue(rest.payload, meta)
+		payload: reviveDocumentValue(rest.payload, meta)
 	};
 };
-const walkDates = (node, path, meta) => {
-	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[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. */
 const encodeParams = (params) => {
-	const meta = [];
-	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. */
-const encodeValue = (value) => {
-	const meta = [];
-	const encoded = walkDates(value, [], meta);
-	return meta.length > 0 ? {
-		value: encoded,
+	const { value, meta } = encodeDocument(params);
+	return meta ? {
+		params: value,
 		meta
-	} : { value: encoded };
+	} : { params: value };
 };
 //#endregion
-export { encodeParams, encodeValue, reviveOps, reviveResponse, reviveValue };
+export { encodeParams, reviveOps, reviveResponse, reviveDocumentValue as reviveValue };
 
 //# sourceMappingURL=meta.js.map

package/dist/wire/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","names":["walkStatePath","StatewireMetaEntry","path","type","fault","message","Error","isPath","Array","isArray","every","seg","Number","isInteger","reviveValue","value","meta","rejectUnknown","entry","String","walked","undefined","join","leaf","date","Date","test","isNaN","getTime","parent","Record","key","reviveOps","ops","map","op","rest","reviveResponse","payload","response","T","walkDates","node","push","toISOString","item","i","Object","fromEntries","keys","encodeParams","params","encoded","param","length","encodeValue"],"sources":["../../src/wire/meta.ts"],"sourcesContent":["import { walkStatePath } from \"../util/statePath\";\n\nexport type StatewireMetaEntry = {\n  path: (string | number)[];\n  type: string;\n};\n\nconst fault = (message: string): never => {\n  throw new Error(`statewire: protocol error: ${message}`);\n};\n\nconst isPath = (path: unknown): path is (string | number)[] =>\n  Array.isArray(path) &&\n  path.every(\n    (seg) =>\n      typeof seg === \"string\" ||\n      (typeof seg === \"number\" && Number.isInteger(seg)),\n  );\n\n/** Revive meta-typed locations inside a wire value (in place). Clients skip\n * unknown types; hosts pass `rejectUnknown` to fault on them instead. */\nexport const reviveValue = (\n  value: unknown,\n  meta: unknown,\n  { rejectUnknown = false } = {},\n): unknown => {\n  if (!Array.isArray(meta)) return fault(\"meta must be an array\");\n  for (const entry of meta as { path?: unknown; type?: unknown }[]) {\n    const path =\n      typeof entry === \"object\" && entry !== null ? entry.path : null;\n    if (!isPath(path)) return fault(\"meta entry must carry a path array\");\n    if (entry.type !== \"date\") {\n      if (rejectUnknown)\n        return fault(`unknown meta type: ${String(entry.type)}`);\n      continue;\n    }\n    const walked = walkStatePath(value, path, \"resolve\");\n    if (walked === undefined) {\n      return fault(`meta path ${path.join(\".\")} does not resolve`);\n    }\n    if (typeof walked.leaf !== \"string\") {\n      return fault(`meta path ${path.join(\".\")} must name a string`);\n    }\n    const date = new Date(walked.leaf);\n    if (\n      !/(?:T| )\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:?\\d{2})$/i.test(\n        walked.leaf,\n      ) ||\n      Number.isNaN(date.getTime())\n    ) {\n      return fault(`invalid date at meta path ${path.join(\".\")}`);\n    }\n    if (walked.parent === undefined) return date;\n    (walked.parent as Record<string | number, unknown>)[walked.key] = date;\n  }\n  return value;\n};\n\nexport const reviveOps = (ops: unknown[]): unknown[] =>\n  ops.map((op) => {\n    if (typeof op !== \"object\" || op === null || !(\"meta\" in op)) return op;\n    const { meta, ...rest } = op as { meta: unknown; value?: unknown };\n    return { ...rest, value: reviveValue(rest.value, meta) };\n  });\n\nexport const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(\n  response: T,\n): T => {\n  if (response.meta === undefined) return response;\n  const { meta, ...rest } = response;\n  return { ...rest, payload: reviveValue(rest.payload, meta) } as T;\n};\n\nconst walkDates = (\n  node: unknown,\n  path: (string | number)[],\n  meta: StatewireMetaEntry[],\n): unknown => {\n  if (node instanceof Date) {\n    meta.push({ path, type: \"date\" });\n    return node.toISOString();\n  }\n  if (Array.isArray(node)) {\n    return node.map((item, i) => walkDates(item, [...path, i], meta));\n  }\n  if (typeof node === \"object\" && node !== null) {\n    return Object.fromEntries(\n      Object.keys(node).map((key) => [\n        key,\n        walkDates((node as Record<string, unknown>)[key], [...path, key], meta),\n      ]),\n    );\n  }\n  return node;\n};\n\n/** Encode Date instances inside command params as canonical ISO strings,\n * recording their paths (starting at the param index) in meta. */\nexport const encodeParams = (\n  params: readonly unknown[],\n): { params: unknown[]; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = params.map((param, i) => walkDates(param, [i], meta));\n  return meta.length > 0 ? { params: encoded, meta } : { params: encoded };\n};\n\n/** Encode Date instances inside a wire value, recording their paths in meta. */\nexport const encodeValue = (\n  value: unknown,\n): { value: unknown; meta?: StatewireMetaEntry[] } => {\n  const meta: StatewireMetaEntry[] = [];\n  const encoded = walkDates(value, [], meta);\n  return meta.length > 0 ? { value: encoded, meta } : { value: encoded };\n};\n"],"mappings":";;AAOA,MAAMI,SAASC,YAA2B;CACxC,MAAM,IAAIC,MAAM,8BAA8BD,SAAS;AACzD;AAEA,MAAME,UAAUL,SACdM,MAAMC,QAAQP,IAAI,KAClBA,KAAKQ,OACFC,QACC,OAAOA,QAAQ,YACd,OAAOA,QAAQ,YAAYC,OAAOC,UAAUF,GAAG,CACpD;;;AAIF,MAAaG,eACXC,OACAC,MACA,EAAEC,gBAAgB,UAAU,CAAC,MACjB;CACZ,IAAI,CAACT,MAAMC,QAAQO,IAAI,GAAG,OAAOZ,MAAM,uBAAuB;CAC9D,KAAK,MAAMc,SAASF,MAA8C;EAChE,MAAMd,OACJ,OAAOgB,UAAU,YAAYA,UAAU,OAAOA,MAAMhB,OAAO;EAC7D,IAAI,CAACK,OAAOL,IAAI,GAAG,OAAOE,MAAM,oCAAoC;EACpE,IAAIc,MAAMf,SAAS,QAAQ;GACzB,IAAIc,eACF,OAAOb,MAAM,sBAAsBe,OAAOD,MAAMf,IAAI,GAAG;GACzD;EACF;EACA,MAAMiB,SAASpB,cAAce,OAAOb,MAAM,SAAS;EACnD,IAAIkB,WAAWC,KAAAA,GACb,OAAOjB,MAAM,aAAaF,KAAKoB,KAAK,GAAG,EAAC,kBAAmB;EAE7D,IAAI,OAAOF,OAAOG,SAAS,UACzB,OAAOnB,MAAM,aAAaF,KAAKoB,KAAK,GAAG,EAAC,oBAAqB;EAE/D,MAAME,OAAO,IAAIC,KAAKL,OAAOG,IAAI;EACjC,IACE,CAAC,kEAAkEG,KACjEN,OAAOG,IACT,KACAX,OAAOe,MAAMH,KAAKI,QAAQ,CAAC,GAE3B,OAAOxB,MAAM,6BAA6BF,KAAKoB,KAAK,GAAG,GAAG;EAE5D,IAAIF,OAAOS,WAAWR,KAAAA,GAAW,OAAOG;EACxC,OAAQK,OAA4CT,OAAOW,OAAOP;CACpE;CACA,OAAOT;AACT;AAEA,MAAaiB,aAAaC,QACxBA,IAAIC,KAAKC,OAAO;CACd,IAAI,OAAOA,OAAO,YAAYA,OAAO,QAAQ,EAAE,UAAUA,KAAK,OAAOA;CACrE,MAAM,EAAEnB,MAAM,GAAGoB,SAASD;CAC1B,OAAO;EAAE,GAAGC;EAAMrB,OAAOD,YAAYsB,KAAKrB,OAAOC,IAAI;CAAE;AACzD,CAAC;AAEH,MAAaqB,kBACXE,aACM;CACN,IAAIA,SAASvB,SAASK,KAAAA,GAAW,OAAOkB;CACxC,MAAM,EAAEvB,MAAM,GAAGoB,SAASG;CAC1B,OAAO;EAAE,GAAGH;EAAME,SAASxB,YAAYsB,KAAKE,SAAStB,IAAI;CAAE;AAC7D;AAEA,MAAMyB,aACJC,MACAxC,MACAc,SACY;CACZ,IAAI0B,gBAAgBjB,MAAM;EACxBT,KAAK2B,KAAK;GAAEzC;GAAMC,MAAM;EAAO,CAAC;EAChC,OAAOuC,KAAKE,YAAY;CAC1B;CACA,IAAIpC,MAAMC,QAAQiC,IAAI,GACpB,OAAOA,KAAKR,KAAKW,MAAMC,MAAML,UAAUI,MAAM,CAAC,GAAG3C,MAAM4C,CAAC,GAAG9B,IAAI,CAAC;CAElE,IAAI,OAAO0B,SAAS,YAAYA,SAAS,MACvC,OAAOK,OAAOC,YACZD,OAAOE,KAAKP,IAAI,CAAC,CAACR,KAAKH,QAAQ,CAC7BA,KACAU,UAAWC,KAAiCX,MAAM,CAAC,GAAG7B,MAAM6B,GAAG,GAAGf,IAAI,CAAC,CACxE,CACH;CAEF,OAAO0B;AACT;;;AAIA,MAAaQ,gBACXC,WACuD;CACvD,MAAMnC,OAA6B,CAAA;CACnC,MAAMoC,UAAUD,OAAOjB,KAAKmB,OAAOP,MAAML,UAAUY,OAAO,CAACP,CAAC,GAAG9B,IAAI,CAAC;CACpE,OAAOA,KAAKsC,SAAS,IAAI;EAAEH,QAAQC;EAASpC;CAAK,IAAI,EAAEmC,QAAQC,QAAQ;AACzE;;AAGA,MAAaG,eACXxC,UACoD;CACpD,MAAMC,OAA6B,CAAA;CACnC,MAAMoC,UAAUX,UAAU1B,OAAO,CAAA,GAAIC,IAAI;CACzC,OAAOA,KAAKsC,SAAS,IAAI;EAAEvC,OAAOqC;EAASpC;CAAK,IAAI,EAAED,OAAOqC,QAAQ;AACvE"}
+{"version":3,"file":"meta.js","names":["encodeDocument","reviveDocumentValue","reviveValue","StatewireDocument","reviveOps","ops","map","op","meta","rest","value","reviveResponse","payload","response","T","undefined","encodeParams","params","MetaEntry"],"sources":["../../src/wire/meta.ts"],"sourcesContent":["import {\n  encodeDocument,\n  reviveDocumentValue as reviveValue,\n} from \"../document\";\nimport type { StatewireDocument } from \"../document\";\n\nexport { reviveDocumentValue as reviveValue } from \"../document\";\n\nexport const reviveOps = (ops: unknown[]): unknown[] =>\n  ops.map((op) => {\n    if (typeof op !== \"object\" || op === null || !(\"meta\" in op)) return op;\n    const { meta, ...rest } = op as { meta: unknown; value?: unknown };\n    return { ...rest, value: reviveValue(rest.value, meta) };\n  });\n\nexport const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(\n  response: T,\n): T => {\n  if (response.meta === undefined) return response;\n  const { meta, ...rest } = response;\n  return { ...rest, payload: reviveValue(rest.payload, meta) } as T;\n};\n\nexport const encodeParams = (\n  params: readonly unknown[],\n): { params: unknown[]; meta?: StatewireDocument.MetaEntry[] } => {\n  const { value, meta } = encodeDocument(params);\n  return meta\n    ? { params: value as unknown[], meta }\n    : { params: value as unknown[] };\n};\n"],"mappings":";;AAQA,MAAaI,aAAaC,QACxBA,IAAIC,KAAKC,OAAO;CACd,IAAI,OAAOA,OAAO,YAAYA,OAAO,QAAQ,EAAE,UAAUA,KAAK,OAAOA;CACrE,MAAM,EAAEC,MAAM,GAAGC,SAASF;CAC1B,OAAO;EAAE,GAAGE;EAAMC,OAAOR,oBAAYO,KAAKC,OAAOF,IAAI;CAAE;AACzD,CAAC;AAEH,MAAaG,kBACXE,aACM;CACN,IAAIA,SAASL,SAASO,KAAAA,GAAW,OAAOF;CACxC,MAAM,EAAEL,MAAM,GAAGC,SAASI;CAC1B,OAAO;EAAE,GAAGJ;EAAMG,SAASV,oBAAYO,KAAKG,SAASJ,IAAI;CAAE;AAC7D;AAEA,MAAaQ,gBACXC,WACgE;CAChE,MAAM,EAAEP,OAAOF,SAASR,eAAeiB,MAAM;CAC7C,OAAOT,OACH;EAAES,QAAQP;EAAoBF;CAAK,IACnC,EAAES,QAAQP,MAAmB;AACnC"}

package/dist/wire/ops.js

@@ -1,5 +1,5 @@
-import { recordMutations } from "../util/recordMutations.js";
 import { isUnsafeKey, walkStatePath } from "../util/statePath.js";
+import { recordMutations } from "../util/recordMutations.js";
 //#region src/wire/ops.ts
 const warnStripped = (key, parent) => {
 	if (typeof process === "undefined" || process.env["NODE_ENV"] !== "production") console.warn(`statewire: stripped unsafe key "${key}"` + (parent === void 0 ? "" : ` under "${parent}"`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "statewire",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "State over the wire: snapshot-first delta streaming and command submission for any state and any command",
   "license": "MIT",
   "repository": {

package/src/client/session.ts

@@ -1,3 +1,4 @@
+import { encodeDocument } from "../document";
 import {
   DEFAULT_PROTOCOL,
   WIRE_VERSION,
@@ -18,12 +19,7 @@ import type { StatewirePath } from "../wire/ops";
 import { MAX_COMMANDS_PER_FRAME } from "../wire/limits";
 import { TERMINAL } from "./connection";
 import type { StatewireCmd, StatewireSyn } from "./connection";
-import {
-  encodeParams,
-  encodeValue,
-  reviveResponse,
-  reviveValue,
-} from "../wire/meta";
+import { encodeParams, reviveResponse, reviveValue } from "../wire/meta";
 import { bindCommandsHost } from "../host/host";
 import type { CommandsInvocation, CommandsListener } from "../host/host";
 import type { Statewire } from "../types";
@@ -1165,7 +1161,7 @@ export const retryFailed = (
 
 const contextSnapshot = (documents: StatewireDocuments.State) =>
   [...documents.documents].map(([doc, d]) => {
-    const encoded = encodeValue(d.value);
+    const encoded = encodeDocument(d.value);
     return {
       op: "mount",
       ...(doc === 0 ? {} : { doc }),
@@ -1253,7 +1249,7 @@ const setContext = (
 ): void => {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     throw new Error("statewire: context must be a plain object");
-  const encoded = encodeValue(value);
+  const encoded = encodeDocument(value);
   changeContext(s, (documents) => {
     const found = [...documents.documents].find(
       ([, d]) => d.protocol === protocol && d.main,

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/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[] };
 };