statewire 0.0.0-0 → 0.0.2

package/src/wire/meta.ts

@@ -0,0 +1,101 @@
+import { walkStatePath } from "../util/statePath";
+
+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). Unknown types
+ * are skipped; a path that does not resolve to a valid target faults. */
+export const reviveValue = (value: unknown, meta: unknown): 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") 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 (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 const reviveOps = (ops: unknown[]): unknown[] =>
+  ops.map((op) => {
+    if (typeof op !== "object" || op === null || !("meta" in op)) return op;
+    const { meta, ...rest } = op as { meta: unknown; value?: unknown };
+    return { ...rest, value: reviveValue(rest.value, meta) };
+  });
+
+export const reviveResponse = <T extends { payload?: unknown; meta?: unknown }>(
+  response: T,
+): T => {
+  if (response.meta === undefined) return response;
+  const { meta, ...rest } = response;
+  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 };
+};

package/src/wire/ops.ts

@@ -0,0 +1,202 @@
+import { recordMutations } from "../util/recordMutations";
+import { isUnsafeKey, walkStatePath } from "../util/statePath";
+import type { Statewire } from "../types";
+
+export type StatewirePath = readonly (string | number)[];
+
+const warnStripped = (key: string, parent: string | undefined) => {
+  if (
+    typeof process === "undefined" ||
+    process.env["NODE_ENV"] !== "production"
+  ) {
+    console.warn(
+      `statewire: stripped unsafe key "${key}"` +
+        (parent === undefined ? "" : ` under "${parent}"`),
+    );
+  }
+};
+
+const unserializable = (
+  kind: "function" | "undefined",
+  path: readonly (string | number)[],
+): never => {
+  throw new Error(
+    `statewire: cannot serialize ${kind}` +
+      (path.length === 0 ? "" : ` at ${path.join(".")}`),
+  );
+};
+
+const sanitizeAt = (
+  value: unknown,
+  parent: string | undefined,
+  path: readonly (string | number)[],
+): unknown => {
+  if (value instanceof Date) return new Date(value.getTime());
+  if (Array.isArray(value)) {
+    return value.map((item, index) => {
+      if (item === undefined) unserializable("undefined", [...path, index]);
+      return sanitizeAt(item, undefined, [...path, index]);
+    });
+  }
+  if (typeof value === "object" && value !== null) {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) {
+      if (isUnsafeKey(key, parent)) {
+        warnStripped(key, parent);
+        continue;
+      }
+      const item = (value as Record<string, unknown>)[key];
+      if (item === undefined) continue;
+      out[key] = sanitizeAt(item, key, [...path, key]);
+    }
+    return out;
+  }
+  if (typeof value === "function") unserializable("function", path);
+  return value;
+};
+
+// One clone pass: strips unsafe keys (with a warning); explicit-undefined
+// object entries are omitted (delete semantics), functions and undefined
+// list items throw.
+export const sanitizeValue = (value: unknown, parent?: string): unknown =>
+  sanitizeAt(value, parent, parent === undefined ? [] : [parent]);
+
+type MutableOp = Extract<Statewire.Op, { op: "replace" | "add" | "remove" }>;
+
+const invalid = (op: MutableOp) =>
+  new Error(`Statewire cannot apply ${op.op} at path: ${op.path.join(".")}`);
+
+const insertedText = (
+  current: string,
+  op: Extract<MutableOp, { op: "add" }>,
+  offset: number,
+): string => {
+  if (typeof op.value !== "string" || offset > current.length) {
+    throw invalid(op);
+  }
+  return current.slice(0, offset) + op.value + current.slice(offset);
+};
+
+const applyAdd = (
+  box: { state: unknown },
+  op: Extract<MutableOp, { op: "add" }>,
+) => {
+  const offset = op.path[op.path.length - 1];
+  const walked = walkStatePath(box.state, op.path.slice(0, -1), "resolve");
+  if (
+    walked === undefined ||
+    typeof offset !== "number" ||
+    !Number.isInteger(offset) ||
+    offset < 0
+  ) {
+    throw invalid(op);
+  }
+  const target = walked.leaf;
+  if (Array.isArray(target)) {
+    if (offset > target.length) throw invalid(op);
+    target.splice(offset, 0, sanitizeValue(op.value));
+  } else if (typeof target === "string") {
+    const next = insertedText(target, op, offset);
+    if (op.path.length === 1) {
+      box.state = next;
+    } else {
+      (walked.parent as Record<string | number, unknown>)[walked.key] = next;
+    }
+  } else {
+    throw invalid(op);
+  }
+};
+
+const applyInList = (list: unknown[], index: number, op: MutableOp) => {
+  if (index >= list.length) throw invalid(op);
+  if (op.op === "replace") {
+    list[index] = sanitizeValue(op.value);
+  } else {
+    list.splice(index, 1);
+  }
+};
+
+const applyInObject = (
+  obj: Record<string, unknown>,
+  key: string,
+  op: MutableOp,
+) => {
+  if (op.op === "replace") {
+    obj[key] = sanitizeValue(op.value, key);
+  } else {
+    if (!Object.hasOwn(obj, key)) throw invalid(op);
+    delete obj[key];
+  }
+};
+
+const applyOpToDraft = (box: { state: unknown }, op: MutableOp): void => {
+  if (op.op === "add") {
+    if (op.path.length === 0) throw invalid(op);
+    applyAdd(box, op);
+    return;
+  }
+  if (op.path.length === 0) {
+    if (op.op !== "replace") throw invalid(op);
+    box.state = sanitizeValue(op.value);
+    return;
+  }
+  const walked = walkStatePath(box.state, op.path, "parent");
+  if (walked === undefined) throw invalid(op);
+  if (typeof walked.key === "number") {
+    applyInList(walked.parent as unknown[], walked.key, op);
+  } else {
+    applyInObject(walked.parent as Record<string, unknown>, walked.key, op);
+  }
+};
+
+const warnedOps = new Set<unknown>();
+const warnUnknownOp = (type: unknown) => {
+  if (warnedOps.has(type)) return;
+  warnedOps.add(type);
+  console.warn(`statewire: ignoring unknown op type ${JSON.stringify(type)}`);
+};
+
+const unboxPaths = (paths: readonly StatewirePath[]): StatewirePath[] =>
+  paths.map((path) => path.slice(1));
+
+export const applyOp = (
+  root: unknown,
+  op: MutableOp,
+): { state: unknown; changedPaths: StatewirePath[] } => {
+  const recorded = recordMutations({ state: root }, (draft) =>
+    applyOpToDraft(draft, op),
+  );
+  return {
+    state: recorded.state.state,
+    changedPaths: unboxPaths(recorded.changedPaths),
+  };
+};
+
+export const applyOps = (
+  state: unknown,
+  ops: readonly unknown[],
+): {
+  state: unknown;
+  events: unknown[];
+  changedPaths: StatewirePath[];
+} => {
+  const events: unknown[] = [];
+  const mutable: MutableOp[] = [];
+  for (const op of ops as Statewire.Op[]) {
+    if (op.op === "event") {
+      events.push(sanitizeValue(op.value));
+    } else if (op.op === "replace" || op.op === "add" || op.op === "remove") {
+      mutable.push(op);
+    } else {
+      warnUnknownOp((op as { op: unknown }).op);
+    }
+  }
+  const recorded = recordMutations({ state }, (draft) => {
+    for (const op of mutable) applyOpToDraft(draft, op);
+  });
+  return {
+    state: recorded.state.state,
+    events,
+    changedPaths: unboxPaths(recorded.changedPaths),
+  };
+};

package/index.js

@@ -1 +0,0 @@
-throw new Error("statewire: placeholder release — not yet published");