@kubohiroya/turbowarp-structured-data 0.4.0

package/src/block-definitions.json

@@ -0,0 +1,98 @@
+{
+  "extensionName": "Structured Data",
+  "blocks": [
+    {
+      "opcode": "parseJson", "blockType": "COMMAND", "text": "parse JSON [TEXT] as [NAME]", "description": "Parse JSON text into the target-local structured data namespace.",
+      "arguments": {"TEXT": {"type": "STRING", "defaultValue": "{\"name\":\"TurboWarp\"}"}, "NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "void", "effect": "state", "immutable": true, "errors": ["INVALID_JSON", "INVALID_NAME", "PARSE_LIMIT_EXCEEDED"],
+      "server": {"supported": true, "irOperation": "structuredData.parseJson"}
+    },
+    {
+      "opcode": "parseYaml", "blockType": "COMMAND", "text": "parse YAML [TEXT] as [NAME]", "description": "Parse safe YAML text into the target-local structured data namespace.",
+      "arguments": {"TEXT": {"type": "STRING", "defaultValue": "name: TurboWarp"}, "NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "void", "effect": "state", "immutable": true, "errors": ["INVALID_YAML", "INVALID_NAME", "PARSE_LIMIT_EXCEEDED"],
+      "server": {"supported": true, "irOperation": "structuredData.parseYaml"}
+    },
+    {
+      "opcode": "toJson", "blockType": "REPORTER", "text": "to JSON [NAME]", "description": "Render named structured data as canonical JSON.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "jsonText", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND"],
+      "server": {"supported": true, "irOperation": "structuredData.toJson"}
+    },
+    {
+      "opcode": "toYaml", "blockType": "REPORTER", "text": "to YAML [NAME]", "description": "Render named structured data as deterministic YAML.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "yamlText", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND"],
+      "server": {"supported": true, "irOperation": "structuredData.toYaml"}
+    },
+    {
+      "opcode": "hasStructuredData", "blockType": "BOOLEAN", "text": "structured data [NAME] exists?", "description": "Report whether the current target has named structured data.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "boolean", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME"],
+      "server": {"supported": true, "irOperation": "structuredData.hasData"}
+    },
+    {
+      "opcode": "deleteStructuredData", "blockType": "COMMAND", "text": "delete structured data [NAME]", "description": "Delete named structured data from the current target.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}},
+      "resultType": "void", "effect": "state", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND"],
+      "server": {"supported": true, "irOperation": "structuredData.deleteData"}
+    },
+    {
+      "opcode": "getJsonAtPath", "blockType": "REPORTER", "text": "get JSON from [NAME] at path [PATH]", "description": "Return a named value at a path as JSON.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$.name", "normalizesTo": "pathSegments"}},
+      "resultType": "jsonText", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE"],
+      "server": {"supported": true, "irOperation": "structuredData.get"}
+    },
+    {
+      "opcode": "hasPath", "blockType": "BOOLEAN", "text": "structured data [NAME] has path [PATH]?", "description": "Report whether a path exists in named structured data.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$.name", "normalizesTo": "pathSegments"}},
+      "resultType": "boolean", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "TYPE_MISMATCH"],
+      "server": {"supported": true, "irOperation": "structuredData.has"}
+    },
+    {
+      "opcode": "setJsonAtPath", "blockType": "COMMAND", "text": "set [NAME] at path [PATH] to JSON [VALUE]", "description": "Immutably update a named value and replace its binding.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$.name", "normalizesTo": "pathSegments"}, "VALUE": {"type": "STRING", "defaultValue": "\"Scratch\""}},
+      "resultType": "void", "effect": "state", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_JSON", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE"],
+      "server": {"supported": true, "irOperation": "structuredData.set"}
+    },
+    {
+      "opcode": "deleteAtPath", "blockType": "COMMAND", "text": "delete path [PATH] from [NAME]", "description": "Immutably delete a path and replace its named binding.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$.name", "normalizesTo": "pathSegments"}},
+      "resultType": "void", "effect": "state", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE"],
+      "server": {"supported": true, "irOperation": "structuredData.delete"}
+    },
+    {
+      "opcode": "keysAtPath", "blockType": "REPORTER", "text": "keys in [NAME] at path [PATH]", "description": "Return sorted object keys as JSON.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$", "normalizesTo": "pathSegments"}},
+      "resultType": "jsonText", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE"],
+      "server": {"supported": true, "irOperation": "structuredData.keys"}
+    },
+    {
+      "opcode": "lengthAtPath", "blockType": "REPORTER", "text": "length of array in [NAME] at path [PATH]", "description": "Return the array length.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$", "normalizesTo": "pathSegments"}},
+      "resultType": "number", "effect": "pure", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE"],
+      "server": {"supported": true, "irOperation": "structuredData.length"}
+    },
+    {
+      "opcode": "forEachAtPath", "blockType": "LOOP", "text": "for each in [NAME] at path [PATH] max [MAX]", "description": "Iterate named data deterministically with a static maximum.",
+      "arguments": {"NAME": {"type": "STRING", "defaultValue": "data"}, "PATH": {"type": "STRING", "defaultValue": "$", "normalizesTo": "pathSegments"}, "MAX": {"type": "NUMBER", "defaultValue": 100, "staticLiteral": true, "minimum": 1, "maximum": 1000}},
+      "resultType": "void", "effect": "control", "immutable": true, "errors": ["INVALID_NAME", "DATA_NOT_FOUND", "INVALID_PATH", "PATH_NOT_FOUND", "TYPE_MISMATCH", "INDEX_OUT_OF_RANGE", "ITERATION_LIMIT_EXCEEDED"],
+      "server": {"supported": true, "irOperation": "structuredData.forEach"}
+    },
+    {
+      "opcode": "currentKey", "blockType": "REPORTER", "text": "current key", "description": "Return the current object key or array index string.",
+      "arguments": {}, "resultType": "string", "effect": "control", "immutable": true, "errors": ["ITERATION_CONTEXT_REQUIRED"],
+      "server": {"supported": true, "irOperation": "structuredData.currentKey"}
+    },
+    {
+      "opcode": "currentIndex", "blockType": "REPORTER", "text": "current index", "description": "Return the zero-based iteration number.",
+      "arguments": {}, "resultType": "number", "effect": "control", "immutable": true, "errors": ["ITERATION_CONTEXT_REQUIRED"],
+      "server": {"supported": true, "irOperation": "structuredData.currentIndex"}
+    },
+    {
+      "opcode": "currentValueJson", "blockType": "REPORTER", "text": "current value JSON", "description": "Return the current iteration value as JSON.",
+      "arguments": {}, "resultType": "jsonText", "effect": "control", "immutable": true, "errors": ["ITERATION_CONTEXT_REQUIRED"],
+      "server": {"supported": true, "irOperation": "structuredData.currentValue"}
+    }
+  ]
+}

package/src/codecs.ts

@@ -0,0 +1,204 @@
+import {
+  isAlias,
+  isMap,
+  isScalar,
+  isSeq,
+  LineCounter,
+  parseDocument,
+  type Node as YamlNode,
+  type Pair as YamlPair
+} from 'yaml';
+import {
+  compareUnicodeCodePoints,
+  parseJson,
+  stringifyJson,
+  StructuredDataError,
+  type JsonValue
+} from './core.js';
+
+export const PARSE_LIMITS = {
+  maxInputBytes: 256 * 1024,
+  maxDepth: 64,
+  maxNodes: 50_000
+} as const;
+
+interface ParseBudget {
+  nodes: number;
+}
+
+const SIMPLE_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/u;
+
+export function parseJsonDocument(source: string): JsonValue {
+  validateInputSize(source);
+  const value = parseJson(source);
+  validateValueBudget(value, {nodes: 0}, 0);
+  return value;
+}
+
+export function parseYamlDocument(source: string): JsonValue {
+  validateInputSize(source);
+  const lineCounter = new LineCounter();
+  const document = parseDocument(source, {
+    lineCounter,
+    prettyErrors: false,
+    schema: 'core',
+    uniqueKeys: true
+  });
+  const problem = document.errors[0] ?? document.warnings[0];
+  if (problem) {
+    const {line, column} = yamlPosition(lineCounter, problem.pos[0]);
+    throw new StructuredDataError(
+      'INVALID_YAML',
+      `${problem.code} at line ${line}, column ${column}: ${problem.message}`
+    );
+  }
+  try {
+    return valueFromYamlNode(document.contents, {nodes: 0}, 0, lineCounter);
+  } catch (error) {
+    if (error instanceof StructuredDataError) throw error;
+    throw new StructuredDataError(
+      'INVALID_YAML',
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+
+export function renderJsonDocument(value: JsonValue): string {
+  return stringifyJson(value);
+}
+
+export function renderYamlDocument(value: JsonValue): string {
+  return renderYamlValue(value, 0);
+}
+
+function valueFromYamlNode(
+  node: YamlNode<unknown> | null | unknown,
+  budget: ParseBudget,
+  depth: number,
+  lineCounter: LineCounter
+): JsonValue {
+  consumeBudget(budget, depth);
+  if (node === null) return null;
+  if (isAlias(node)) {
+    throw new StructuredDataError('INVALID_YAML', 'YAML aliases are not allowed.');
+  }
+  if (isScalar(node)) {
+    const value = node.value;
+    if (
+      value === null ||
+      typeof value === 'string' ||
+      typeof value === 'boolean' ||
+      (typeof value === 'number' && Number.isFinite(value))
+    ) {
+      return value;
+    }
+    throw new StructuredDataError('INVALID_YAML', 'YAML contains an unsupported scalar value.');
+  }
+  if (isSeq(node)) {
+    return node.items.map((item) => valueFromYamlNode(item, budget, depth + 1, lineCounter));
+  }
+  if (isMap(node)) {
+    return Object.fromEntries(
+      node.items.map((item) => yamlPairToEntry(item, budget, depth, lineCounter))
+    );
+  }
+  throw new StructuredDataError('INVALID_YAML', 'YAML contains an unsupported node type.');
+}
+
+function yamlPairToEntry(
+  pair: YamlPair,
+  budget: ParseBudget,
+  depth: number,
+  lineCounter: LineCounter
+): [string, JsonValue] {
+  if (!isScalar(pair.key) || typeof pair.key.value !== 'string') {
+    throw new StructuredDataError('INVALID_YAML', 'YAML map keys must be strings.');
+  }
+  return [pair.key.value, valueFromYamlNode(pair.value, budget, depth + 1, lineCounter)];
+}
+
+function validateValueBudget(value: JsonValue, budget: ParseBudget, depth: number): void {
+  consumeBudget(budget, depth);
+  if (Array.isArray(value)) {
+    for (const item of value) validateValueBudget(item, budget, depth + 1);
+  } else if (typeof value === 'object' && value !== null) {
+    for (const item of Object.values(value)) validateValueBudget(item, budget, depth + 1);
+  }
+}
+
+function consumeBudget(budget: ParseBudget, depth: number): void {
+  if (depth > PARSE_LIMITS.maxDepth) {
+    throw new StructuredDataError(
+      'PARSE_LIMIT_EXCEEDED',
+      `Data exceeds maximum nesting depth ${PARSE_LIMITS.maxDepth}.`
+    );
+  }
+  budget.nodes += 1;
+  if (budget.nodes > PARSE_LIMITS.maxNodes) {
+    throw new StructuredDataError(
+      'PARSE_LIMIT_EXCEEDED',
+      `Data exceeds maximum node count ${PARSE_LIMITS.maxNodes}.`
+    );
+  }
+}
+
+function validateInputSize(source: string): void {
+  const bytes = new TextEncoder().encode(source).byteLength;
+  if (bytes > PARSE_LIMITS.maxInputBytes) {
+    throw new StructuredDataError(
+      'PARSE_LIMIT_EXCEEDED',
+      `Input is ${bytes} bytes; maximum is ${PARSE_LIMITS.maxInputBytes}.`
+    );
+  }
+}
+
+function renderYamlValue(value: JsonValue, indent: number): string {
+  if (isObject(value)) {
+    const entries = Object.keys(value).sort(compareUnicodeCodePoints);
+    if (entries.length === 0) return `${spaces(indent)}{}`;
+    return entries
+      .map((key) => renderValuePair(key, value[key] as JsonValue, indent))
+      .join('\n');
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return `${spaces(indent)}[]`;
+    return value.map((item) => renderSequenceItem(item, indent)).join('\n');
+  }
+  return `${spaces(indent)}${renderScalar(value)}`;
+}
+
+function renderValuePair(key: string, value: JsonValue, indent: number): string {
+  const prefix = `${spaces(indent)}${renderKey(key)}:`;
+  if (!isObject(value) && !Array.isArray(value)) return `${prefix} ${renderScalar(value)}`;
+  return `${prefix}\n${renderYamlValue(value, indent + 2)}`;
+}
+
+function renderSequenceItem(value: JsonValue, indent: number): string {
+  const prefix = `${spaces(indent)}-`;
+  if (!isObject(value) && !Array.isArray(value)) return `${prefix} ${renderScalar(value)}`;
+  return `${prefix}\n${renderYamlValue(value, indent + 2)}`;
+}
+
+function renderKey(key: string): string {
+  return SIMPLE_KEY_PATTERN.test(key) ? key : JSON.stringify(key);
+}
+
+function renderScalar(value: null | boolean | number | string): string {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return String(value);
+  return JSON.stringify(value);
+}
+
+function isObject(value: JsonValue): value is {[key: string]: JsonValue} {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function yamlPosition(counter: LineCounter, offset: number): {line: number; column: number} {
+  const position = counter.linePos(offset);
+  return {line: position.line, column: position.col};
+}
+
+function spaces(count: number): string {
+  return ' '.repeat(count);
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+export const STRUCTURED_DATA_MVP_DEFAULT = false;
+export const NAMED_DATA_REGISTRY_MVP_DEFAULT = false;
+
+export function isStructuredDataMvpEnabled(
+  source: {STRUCTURED_DATA_MVP?: unknown} = globalThis as {STRUCTURED_DATA_MVP?: unknown}
+): boolean {
+  const value = source.STRUCTURED_DATA_MVP;
+  return value === undefined ? STRUCTURED_DATA_MVP_DEFAULT : value === true || value === 'true';
+}
+
+export function isNamedDataRegistryMvpEnabled(
+  source: {NAMED_DATA_REGISTRY_MVP?: unknown} = globalThis as {
+    NAMED_DATA_REGISTRY_MVP?: unknown;
+  }
+): boolean {
+  const value = source.NAMED_DATA_REGISTRY_MVP;
+  return value === undefined ? NAMED_DATA_REGISTRY_MVP_DEFAULT : value === true || value === 'true';
+}
+
+export const extensionConfig = {
+  id: 'kubohiroyastructureddata',
+  slug: 'structured-data',
+  name: 'Structured Data',
+  description: 'Named structured data with JSON/YAML codecs for TurboWarp and server compilation.',
+  author: 'Hiroya Kubo',
+  license: 'MPL-2.0',
+  unsandboxed: true,
+  docsURI: 'https://kubohiroya.github.io/turbowarp-structured-data/',
+  blockIconURI:
+    'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0OCA0OCI+PHJlY3QgeD0iNCIgeT0iOCIgd2lkdGg9IjE4IiBoZWlnaHQ9IjE0IiByeD0iMyIgZmlsbD0iIzRDOTdGRiIvPjxyZWN0IHg9IjI2IiB5PSI4IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjNTlDMDU5Ii8+PHJlY3QgeD0iMTUiIHk9IjI2IiB3aWR0aD0iMTgiIGhlaWdodD0iMTQiIHJ4PSIzIiBmaWxsPSIjRkZBQjE5Ii8+PC9zdmc+'
+} as const;

package/src/core.ts

@@ -0,0 +1,309 @@
+export const STRUCTURED_DATA_ERROR_CODES = [
+  'INVALID_JSON',
+  'INVALID_YAML',
+  'INVALID_NAME',
+  'DATA_NOT_FOUND',
+  'INVALID_PATH',
+  'PATH_NOT_FOUND',
+  'TYPE_MISMATCH',
+  'INDEX_OUT_OF_RANGE',
+  'ITERATION_LIMIT_EXCEEDED',
+  'ITERATION_CONTEXT_REQUIRED',
+  'PARSE_LIMIT_EXCEEDED'
+] as const;
+
+export type StructuredDataErrorCode = (typeof STRUCTURED_DATA_ERROR_CODES)[number];
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | {[key: string]: JsonValue};
+export type PathSegment = {kind: 'key'; value: string} | {kind: 'index'; value: number};
+
+export class StructuredDataError extends Error {
+  public readonly code: StructuredDataErrorCode;
+
+  public constructor(code: StructuredDataErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'StructuredDataError';
+    this.code = code;
+  }
+}
+
+export function parseJson(text: unknown): JsonValue {
+  try {
+    const value: unknown = JSON.parse(String(text));
+    assertJsonValue(value);
+    return value;
+  } catch (error) {
+    if (error instanceof StructuredDataError) throw error;
+    throw new StructuredDataError('INVALID_JSON', 'Input must be valid JSON.');
+  }
+}
+
+export function isValidJson(text: unknown): boolean {
+  try {
+    parseJson(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function normalizeJson(text: unknown): string {
+  return stringifyJson(parseJson(text));
+}
+
+export function stringifyJson(value: JsonValue): string {
+  if (Array.isArray(value)) return `[${value.map(stringifyJson).join(',')}]`;
+  if (isJsonObject(value)) {
+    return `{${Object.keys(value)
+      .sort(compareUnicodeCodePoints)
+      .map((key) => `${JSON.stringify(key)}:${stringifyJson(value[key] as JsonValue)}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function parsePath(input: unknown): PathSegment[] {
+  const path = String(input);
+  if (!path.startsWith('$')) invalidPath();
+  const segments: PathSegment[] = [];
+  let cursor = 1;
+
+  while (cursor < path.length) {
+    if (path[cursor] === '.') {
+      const match = /^[A-Za-z_][A-Za-z0-9_]*/u.exec(path.slice(cursor + 1));
+      if (!match) invalidPath();
+      segments.push({kind: 'key', value: match[0]});
+      cursor += match[0].length + 1;
+      continue;
+    }
+
+    if (path[cursor] !== '[') invalidPath();
+    cursor += 1;
+    if (path[cursor] === '"') {
+      const end = scanJsonString(path, cursor);
+      let key: unknown;
+      try {
+        key = JSON.parse(path.slice(cursor, end));
+      } catch {
+        invalidPath();
+      }
+      if (typeof key !== 'string' || path[end] !== ']') invalidPath();
+      segments.push({kind: 'key', value: key});
+      cursor = end + 1;
+      continue;
+    }
+
+    const match = /^(0|[1-9][0-9]*)\]/u.exec(path.slice(cursor));
+    if (!match) invalidPath();
+    const index = Number(match[1]);
+    if (!Number.isSafeInteger(index)) invalidPath();
+    segments.push({kind: 'index', value: index});
+    cursor += match[0].length;
+  }
+
+  return segments;
+}
+
+export function getAtPath(root: JsonValue, segments: readonly PathSegment[]): JsonValue {
+  let current = root;
+  for (const segment of segments) current = readSegment(current, segment);
+  return current;
+}
+
+export function hasAtPath(root: JsonValue, segments: readonly PathSegment[]): boolean {
+  try {
+    getAtPath(root, segments);
+    return true;
+  } catch (error) {
+    if (
+      error instanceof StructuredDataError &&
+      (error.code === 'PATH_NOT_FOUND' || error.code === 'INDEX_OUT_OF_RANGE')
+    ) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+export function setAtPath(
+  root: JsonValue,
+  segments: readonly PathSegment[],
+  replacement: JsonValue
+): JsonValue {
+  if (segments.length === 0) return cloneJson(replacement);
+  return updateParent(root, segments, (parent, segment) => {
+    if (segment.kind === 'key') {
+      if (!isJsonObject(parent)) typeMismatch('Object path segment requires an object.');
+      return {...parent, [segment.value]: cloneJson(replacement)};
+    }
+    if (!Array.isArray(parent)) typeMismatch('Index path segment requires an array.');
+    if (segment.value >= parent.length) indexOutOfRange();
+    const result = parent.slice();
+    result[segment.value] = cloneJson(replacement);
+    return result;
+  });
+}
+
+export function deleteAtPath(root: JsonValue, segments: readonly PathSegment[]): JsonValue {
+  if (segments.length === 0) {
+    throw new StructuredDataError('INVALID_PATH', 'The root value cannot be deleted.');
+  }
+  return updateParent(root, segments, (parent, segment) => {
+    if (segment.kind === 'key') {
+      if (!isJsonObject(parent)) typeMismatch('Object path segment requires an object.');
+      if (!Object.hasOwn(parent, segment.value)) pathNotFound();
+      const result = {...parent};
+      delete result[segment.value];
+      return result;
+    }
+    if (!Array.isArray(parent)) typeMismatch('Index path segment requires an array.');
+    if (segment.value >= parent.length) indexOutOfRange();
+    const result = parent.slice();
+    result.splice(segment.value, 1);
+    return result;
+  });
+}
+
+export function keysAtPath(root: JsonValue, segments: readonly PathSegment[]): string[] {
+  const value = getAtPath(root, segments);
+  if (!isJsonObject(value)) typeMismatch('Keys require an object.');
+  return Object.keys(value).sort(compareUnicodeCodePoints);
+}
+
+export function lengthAtPath(root: JsonValue, segments: readonly PathSegment[]): number {
+  const value = getAtPath(root, segments);
+  if (!Array.isArray(value)) typeMismatch('Length requires an array.');
+  return value.length;
+}
+
+export interface IterationEntry {
+  key: string;
+  value: JsonValue;
+}
+
+export function iterationEntries(
+  root: JsonValue,
+  segments: readonly PathSegment[],
+  maximum: number
+): IterationEntry[] {
+  if (!Number.isInteger(maximum) || maximum < 1 || maximum > 1000) {
+    throw new StructuredDataError('ITERATION_LIMIT_EXCEEDED', 'Maximum must be from 1 to 1000.');
+  }
+  const value = getAtPath(root, segments);
+  const entries = Array.isArray(value)
+    ? value.map((item, index) => ({key: String(index), value: item}))
+    : isJsonObject(value)
+      ? Object.keys(value)
+          .sort(compareUnicodeCodePoints)
+          .map((key) => ({key, value: value[key] as JsonValue}))
+      : typeMismatch('Iteration requires an array or object.');
+  if (entries.length > maximum) {
+    throw new StructuredDataError(
+      'ITERATION_LIMIT_EXCEEDED',
+      `Collection contains ${entries.length} items, above maximum ${maximum}.`
+    );
+  }
+  return entries;
+}
+
+function updateParent(
+  root: JsonValue,
+  segments: readonly PathSegment[],
+  update: (parent: JsonValue, segment: PathSegment) => JsonValue
+): JsonValue {
+  const [segment, ...remaining] = segments;
+  if (!segment) return root;
+  if (remaining.length === 0) return update(root, segment);
+  const child = readSegment(root, segment);
+  const next = updateParent(child, remaining, update);
+  if (segment.kind === 'key') {
+    if (!isJsonObject(root)) typeMismatch('Object path segment requires an object.');
+    return {...root, [segment.value]: next};
+  }
+  if (!Array.isArray(root)) typeMismatch('Index path segment requires an array.');
+  const result = root.slice();
+  result[segment.value] = next;
+  return result;
+}
+
+function readSegment(value: JsonValue, segment: PathSegment): JsonValue {
+  if (segment.kind === 'key') {
+    if (!isJsonObject(value)) typeMismatch('Object path segment requires an object.');
+    if (!Object.hasOwn(value, segment.value)) pathNotFound();
+    return value[segment.value] as JsonValue;
+  }
+  if (!Array.isArray(value)) typeMismatch('Index path segment requires an array.');
+  if (segment.value >= value.length) indexOutOfRange();
+  return value[segment.value] as JsonValue;
+}
+
+function cloneJson(value: JsonValue): JsonValue {
+  if (Array.isArray(value)) return value.map(cloneJson);
+  if (isJsonObject(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .map((key) => [key, cloneJson(value[key] as JsonValue)])
+    );
+  }
+  return value;
+}
+
+function assertJsonValue(value: unknown): asserts value is JsonValue {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (Array.isArray(value)) {
+    for (const item of value) assertJsonValue(item);
+    return;
+  }
+  if (typeof value === 'object') {
+    for (const item of Object.values(value)) assertJsonValue(item);
+    return;
+  }
+  throw new StructuredDataError('INVALID_JSON', 'JSON contains an unsupported value.');
+}
+
+function isJsonObject(value: JsonValue): value is {[key: string]: JsonValue} {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function scanJsonString(path: string, start: number): number {
+  let escaped = false;
+  for (let index = start + 1; index < path.length; index += 1) {
+    const character = path[index];
+    if (escaped) {
+      escaped = false;
+    } else if (character === '\\') {
+      escaped = true;
+    } else if (character === '"') {
+      return index + 1;
+    }
+  }
+  invalidPath();
+}
+
+export function compareUnicodeCodePoints(left: string, right: string): number {
+  const leftPoints = Array.from(left, (character) => character.codePointAt(0) as number);
+  const rightPoints = Array.from(right, (character) => character.codePointAt(0) as number);
+  const length = Math.min(leftPoints.length, rightPoints.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (leftPoints[index] as number) - (rightPoints[index] as number);
+    if (difference !== 0) return difference;
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function invalidPath(): never {
+  throw new StructuredDataError('INVALID_PATH', 'Path does not match the supported syntax.');
+}
+
+function pathNotFound(): never {
+  throw new StructuredDataError('PATH_NOT_FOUND', 'Path does not exist.');
+}
+
+function typeMismatch(message: string): never {
+  throw new StructuredDataError('TYPE_MISMATCH', message);
+}
+
+function indexOutOfRange(): never {
+  throw new StructuredDataError('INDEX_OUT_OF_RANGE', 'Array index is out of range.');
+}