@procedures/json 0.0.0-stage → 0.2.3

package/dist/yaml.js

@@ -0,0 +1,111 @@
+/**
+ * YAML to JSON and back, with the `yaml` package (YAML 1.2, the core schema).
+ *
+ * - The parse gives only JSON values. A value that JSON does not have (`.inf`, `.nan`) is an
+ *   error. The explicit YAML 1.1 tags (`!!binary`, `!!timestamp`, `!!set`) give their text.
+ * - A key of a map that is a number, a boolean or null becomes its text. A key that is a map or a
+ *   list is an error.
+ * - The parse refuses more than 100 aliases (a resource attack) and a duplicate key.
+ * - Each object of the result has own data properties only, so a key `__proto__` stays data.
+ * - The text of a value is YAML 1.2 that a YAML 1.1 reader reads as the same value.
+ */
+import { Document, parseAllDocuments, parseDocument, Scalar, Schema, visit } from "yaml";
+import { formatPointer, JsonError, put } from "./value.js";
+// The log level "error" keeps the error of a second document, and prints nothing
+const PARSE_OPTIONS = { version: "1.2", schema: "core", resolveKnownTags: false, uniqueKeys: true, logLevel: "error", prettyErrors: true };
+/** The byte order mark. */
+const BOM = String.fromCharCode(0xfeff);
+/** The JSON value of a value of the parse. */
+function toJson(value, tokens) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new JsonError("INVALID_YAML", `yaml.parse: the value at "${formatPointer(tokens)}" is ${String(value)}, which JSON does not have`);
+        }
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => toJson(item, [...tokens, index]));
+    if (value instanceof Map) {
+        const out = {};
+        for (const [key, item] of value) {
+            if (key !== null && typeof key === "object") {
+                throw new JsonError("INVALID_YAML", `yaml.parse: a key at "${formatPointer(tokens)}" is a map or a list, which JSON does not have`);
+            }
+            const name = key === null ? "null" : String(key);
+            put(out, name, toJson(item, [...tokens, name]));
+        }
+        return out;
+    }
+    throw new JsonError("INVALID_YAML", `yaml.parse: the value at "${formatPointer(tokens)}" is not a JSON value`);
+}
+/** The JSON value of one document, or the error of its first problem. */
+function documentValue(document, index) {
+    const label = index === undefined ? "yaml.parse" : `yaml.parse, document ${index}`;
+    const problem = document.errors[0];
+    if (problem)
+        throw new JsonError("INVALID_YAML", `${label}: ${problem.message}`);
+    let value;
+    try {
+        value = document.toJS({ mapAsMap: true, maxAliasCount: 100 });
+    }
+    catch (error) {
+        throw new JsonError("INVALID_YAML", `${label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return toJson(value === undefined ? null : value, []);
+}
+/** This function parses YAML text into a JSON value. Bad YAML throws `INVALID_YAML`. */
+export function parseYaml(text, options = {}) {
+    if (options.all)
+        return parseAllDocuments(text, PARSE_OPTIONS).map((document, index) => {
+            if (!("errors" in document) || !("toJS" in document))
+                throw new JsonError("INVALID_YAML", "yaml.parse: the text is not YAML");
+            return documentValue(document, index);
+        });
+    return documentValue(parseDocument(text, PARSE_OPTIONS), undefined);
+}
+/**
+ * The plain scalars that a YAML 1.1 reader takes as a boolean, a null, a number, a date, a merge
+ * key or a value key. YAML 1.2 reads them as strings, so a 1.2 writer does not quote them.
+ */
+const YAML_1_1_TYPES = [
+    /^(?:y|Y|yes|Yes|YES|n|N|no|No|NO|true|True|TRUE|false|False|FALSE|on|On|ON|off|Off|OFF)$/,
+    /^(?:~|null|Null|NULL)$/,
+    /^[-+]?(?:0b[01_]+|0[0-7_]+|0|[1-9][0-9_]*|0x[0-9a-fA-F_]+|[1-9][0-9_]*(?::[0-5]?[0-9])+)$/,
+    /^[-+]?(?:(?:[0-9][0-9_]*)?\.[0-9._]*(?:[eE][-+]?[0-9]+)?|[0-9][0-9_]*(?::[0-5]?[0-9])+\.[0-9_]*|\.(?:inf|Inf|INF))$/,
+    /^\.(?:nan|NaN|NAN)$/,
+    /^[0-9]{4}-[0-9]{1,2}-[0-9]{1,2}/,
+    /^(?:<<|=)$/,
+    // The YAML 1.1 schema of the yaml package reads more forms: "e0" is a float there
+    ...new Schema({ schema: "yaml-1.1" }).tags.flatMap((tag) => tag.default === true && tag.tag !== "tag:yaml.org,2002:str" && "test" in tag && tag.test instanceof RegExp ? [tag.test] : []),
+];
+/**
+ * This function writes a JSON value as YAML text. The text is YAML 1.2, and a YAML 1.1 reader
+ * reads the same value: a string that YAML 1.1 takes as another type (`yes`, `no`, `on`, a
+ * date, `0777`, `1_000`) is in double quotes.
+ */
+export function stringifyYaml(value, options = {}) {
+    const document = new Document(value, {
+        version: "1.2",
+        schema: "core",
+        sortMapEntries: options.sortKeys ?? false,
+        aliasDuplicateObjects: false,
+    });
+    visit(document, {
+        Scalar(_key, node) {
+            const text = node.value;
+            if (typeof text !== "string")
+                return;
+            // A byte order mark at the start of a line is removed by a parser: it must be an escape.
+            // yaml 2.9.1 writes a block scalar whose first line has only spaces wrongly: " \n" came
+            // back as "\n", and " \nb" was not valid YAML. Double quotes keep such a text.
+            const blockRisk = /[\n\r]/.test(text) && /(^|[\n\r])[ \t]/.test(text);
+            if (blockRisk || text.includes(BOM) || YAML_1_1_TYPES.some((type) => type.test(text)))
+                node.type = Scalar.QUOTE_DOUBLE;
+        },
+    });
+    // Each byte order mark is in a string in double quotes, where the escape has the same value
+    return document.toString({ indent: options.indent ?? 2, lineWidth: options.lineWidth ?? 80 }).replaceAll(BOM, "\\uFEFF");
+}
+//# sourceMappingURL=yaml.js.map

package/dist/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,84 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/json",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.3",
+  "description": "Pure JSON and YAML procedures: a query with JSON Pointer or a path, JSON Patch, a diff, a merge patch, a JSON Schema check, and YAML to JSON and back.",
+  "keywords": [
+    "procedures",
+    "json",
+    "yaml",
+    "json-pointer",
+    "json-patch",
+    "merge-patch",
+    "json-schema",
+    "diff"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/json"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "devDependencies": {
+    "@mark1russell7/cue": "^1.0.0",
+    "fast-check": "^4.10.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.3",
+    "@procedures/compiler": "0.2.3",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/diff.ts

@@ -0,0 +1,58 @@
+/**
+ * The diff of two JSON values: a JSON Patch (RFC 6902) that changes the first value into the
+ * second value. `applyPatch(a, diffJson(a, b))` gives a value equal to `b`.
+ *
+ * - Two objects: a `remove` for each key that only the first has, a diff of each shared key, and
+ *   an `add` for each key that only the second has.
+ * - Two arrays: the items of the shared start and end stay. The items between them get a diff
+ *   for each shared position, then a `remove` or an `add` for each other item.
+ * - Other values: one `replace`.
+ *
+ * The patch never names `__proto__`, `constructor` or `prototype`, because `applyPatch` refuses
+ * them. When a difference is under such a key, the patch replaces the object that holds the key.
+ */
+
+import type { PatchOperation } from "./patch.js";
+import { cloneJson, formatPointer, hasOwn, jsonEqual, PROTOTYPE_KEYS, type JsonValue } from "./value.js";
+
+function diffAt(a: JsonValue, b: JsonValue, tokens: (string | number)[], out: PatchOperation[]): void {
+  if (jsonEqual(a, b)) return;
+  const path = formatPointer(tokens);
+  if (Array.isArray(a) && Array.isArray(b)) {
+    diffArrays(a, b, tokens, out);
+    return;
+  }
+  if (a !== null && b !== null && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    const named = [...keysA, ...keysB].some((key) => PROTOTYPE_KEYS.has(key) && !(hasOwn(a, key) && hasOwn(b, key) && jsonEqual(a[key]!, b[key]!)));
+    if (!named) {
+      for (const key of keysA) if (!hasOwn(b, key)) out.push({ op: "remove", path: formatPointer([...tokens, key]) });
+      for (const key of keysA) if (hasOwn(b, key)) diffAt(a[key]!, b[key]!, [...tokens, key], out);
+      for (const key of keysB) if (!hasOwn(a, key)) out.push({ op: "add", path: formatPointer([...tokens, key]), value: cloneJson(b[key]!) });
+      return;
+    }
+  }
+  out.push({ op: "replace", path, value: cloneJson(b) });
+}
+
+function diffArrays(a: JsonValue[], b: JsonValue[], tokens: (string | number)[], out: PatchOperation[]): void {
+  let start = 0;
+  while (start < a.length && start < b.length && jsonEqual(a[start]!, b[start]!)) start++;
+  let end = 0;
+  while (end < a.length - start && end < b.length - start && jsonEqual(a[a.length - 1 - end]!, b[b.length - 1 - end]!)) end++;
+  const middleA = a.length - start - end;
+  const middleB = b.length - start - end;
+  const shared = Math.min(middleA, middleB);
+  for (let i = 0; i < shared; i++) diffAt(a[start + i]!, b[start + i]!, [...tokens, start + i], out);
+  // The items after the shared positions: remove from the last one, so each index stays valid
+  for (let i = middleA - 1; i >= shared; i--) out.push({ op: "remove", path: formatPointer([...tokens, start + i]) });
+  for (let i = shared; i < middleB; i++) out.push({ op: "add", path: formatPointer([...tokens, start + i]), value: cloneJson(b[start + i]!) });
+}
+
+/** This function gives a JSON Patch that changes `a` into `b`. Equal values give an empty patch. */
+export function diffJson(a: JsonValue, b: JsonValue): PatchOperation[] {
+  const out: PatchOperation[] = [];
+  diffAt(a, b, [], out);
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+export { jsonQuery, jsonPatch, jsonDiff, jsonMerge, jsonValidate } from "./procedures/json/index.js";
+export { yamlParse, yamlStringify } from "./procedures/yaml/index.js";
+// The functions behind the procedures, for a program in the same process
+export { assertJson, cloneJson, jsonEqual, JsonError, PROTOTYPE_KEYS, formatPointer, escapeToken, type JsonErrorCode } from "./value.js";
+export { parsePointer, lookup, arrayIndex, type Lookup } from "./pointer.js";
+export { parsePath, queryPath, type PathMatch, type PathStep } from "./path.js";
+export { applyPatch } from "./patch.js";
+export { diffJson } from "./diff.js";
+export { mergePatch } from "./merge.js";
+export { validateJson, NOT_EXAMINED, type ValidationIssue, type ValidationResult } from "./schema.js";
+export { parseYaml, stringifyYaml, type YamlParseOptions, type YamlStringifyOptions } from "./yaml.js";

package/src/merge.ts

@@ -0,0 +1,34 @@
+/**
+ * JSON Merge Patch (RFC 7386): a patch is a JSON value of the same form as the target.
+ *
+ * - A patch that is an object changes the target member by member. A member with the value null
+ *   removes the key. Another member merges into the key.
+ * - A patch that is not an object replaces the target.
+ *
+ * The merge applies to a copy of the target. A key `__proto__`, `constructor` or `prototype` in
+ * an object of the patch is refused (roadmap R6).
+ */
+
+import { cloneJson, formatPointer, hasOwn, isPlainObject, JsonError, PROTOTYPE_KEYS, put, type JsonValue } from "./value.js";
+
+function mergeAt(target: JsonValue | undefined, patch: JsonValue, tokens: string[]): JsonValue {
+  if (!isPlainObject(patch)) return cloneJson(patch);
+  const result: Record<string, JsonValue> = isPlainObject(target) ? cloneJson(target as Record<string, JsonValue>) : {};
+  for (const key of Object.keys(patch)) {
+    if (PROTOTYPE_KEYS.has(key)) {
+      throw new JsonError("PROTOTYPE_KEY", `The merge patch has the key "${key}" at "${formatPointer([...tokens, key])}", which reaches a prototype`);
+    }
+    const value = patch[key] as JsonValue;
+    if (value === null) {
+      delete result[key];
+    } else {
+      put(result, key, mergeAt(hasOwn(result, key) ? result[key] : undefined, value, [...tokens, key]));
+    }
+  }
+  return result;
+}
+
+/** This function applies a JSON merge patch to a copy of the target and gives the result. */
+export function mergePatch(target: JsonValue, patch: JsonValue): JsonValue {
+  return mergeAt(target, patch, []);
+}

package/src/module.ts

@@ -0,0 +1,236 @@
+/**
+ * The procedures of @procedures/json as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/json
+ *
+ * Each procedure is pure (`PURE_EFFECTS`): its output comes from its input, and it reads and
+ * changes nothing else (roadmap R39).
+ */
+
+import { z } from "zod";
+import { defineModule, registerModules, PROCEDURE_REGISTRY, PURE_EFFECTS, type ProcedureModule, type ProcedureRegistry, createProcedure, zodAdapter } from "@procedures/client";
+import { jsonQuery } from "./procedures/json/query.js";
+import { jsonPatch } from "./procedures/json/patch.js";
+import { jsonDiff } from "./procedures/json/diff.js";
+import { jsonMerge } from "./procedures/json/merge.js";
+import { jsonValidate } from "./procedures/json/validate.js";
+import { yamlParse } from "./procedures/yaml/parse.js";
+import { yamlStringify } from "./procedures/yaml/stringify.js";
+import type {
+  JsonDiffInput,
+  JsonDiffOutput,
+  JsonMergeInput,
+  JsonMergeOutput,
+  JsonPatchInput,
+  JsonPatchOutput,
+  JsonQueryInput,
+  JsonQueryOutput,
+  JsonValidateInput,
+  JsonValidateOutput,
+  YamlParseInput,
+  YamlParseOutput,
+  YamlStringifyInput,
+  YamlStringifyOutput,
+} from "./types.js";
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+/** A JSON value. The handler examines it, so a key `__proto__` of the data reaches the check. */
+const json = (description: string) => z.unknown().describe(description);
+
+const operation = z.object({
+  op: z.enum(["add", "remove", "replace", "move", "copy", "test"]).describe("The operation"),
+  path: z.string().describe("The JSON Pointer of the location"),
+  from: z.string().optional().describe("The JSON Pointer of the source of move and copy"),
+  value: json("The value of add, replace and test").optional(),
+});
+
+const JsonQueryInputSchema = z.object({
+  value: json("The JSON value to search"),
+  pointer: z.string().optional().describe("A JSON Pointer (RFC 6901), for example /items/0/name. Give pointer or path"),
+  path: z.string().optional().describe("A path query, for example items[*].name or $..id. Give pointer or path"),
+});
+
+const JsonQueryOutputSchema = z.object({
+  found: z.boolean().describe("True when one or more values match"),
+  value: json("The value of the first match").optional(),
+  matches: z.array(z.object({ pointer: z.string().describe("The JSON Pointer of the match"), value: json("The value of the match") })).describe("Each match, in document order"),
+});
+
+const JsonPatchInputSchema = z.object({
+  value: json("The JSON value to change"),
+  patch: z.array(operation).describe("The operations of the JSON Patch (RFC 6902), in order"),
+});
+
+const JsonPatchOutputSchema = z.object({ value: json("The value after the patch") });
+
+const JsonDiffInputSchema = z.object({
+  from: json("The first JSON value"),
+  to: json("The second JSON value"),
+});
+
+const JsonDiffOutputSchema = z.object({
+  patch: z.array(operation).describe("The JSON Patch (RFC 6902) that changes from into to"),
+});
+
+const JsonMergeInputSchema = z.object({
+  target: json("The JSON value to change"),
+  patch: json("The merge patch (RFC 7386): an object of changes, where null removes a key"),
+});
+
+const JsonMergeOutputSchema = z.object({ value: json("The value after the merge") });
+
+const JsonValidateInputSchema = z.object({
+  value: json("The JSON value to examine"),
+  schema: json("The JSON Schema: an object or a boolean"),
+});
+
+const JsonValidateOutputSchema = z.object({
+  valid: z.boolean().describe("True when the check found no problem"),
+  errors: z.array(z.object({ pointer: z.string().describe("The JSON Pointer of the part"), message: z.string().describe("The problem") })).describe("Each problem"),
+  unchecked: z.array(z.string()).describe("The keywords of the schema that the check does not examine. Empty: the verdict is complete"),
+});
+
+const YamlParseInputSchema = z.object({
+  text: z.string().describe("The YAML text"),
+  all: z.boolean().optional().describe("True: the text can have more than one document, and value is the list of documents"),
+});
+
+const YamlParseOutputSchema = z.object({ value: json("The JSON value of the text") });
+
+const YamlStringifyInputSchema = z.object({
+  value: json("The JSON value to write"),
+  indent: z.number().int().min(1).max(8).optional().describe("The spaces of one level of indentation (default: 2)"),
+  lineWidth: z.number().int().min(0).optional().describe("The longest line before a fold. 0: no fold (default: 80)"),
+  sortKeys: z.boolean().optional().describe("True: the keys of each map in alphabetical order"),
+});
+
+const YamlStringifyOutputSchema = z.object({ text: z.string().describe("The YAML text") });
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+const jsonQueryProcedure = createProcedure()
+  .path(["json", "query"])
+  .input(zodAdapter<JsonQueryInput>(JsonQueryInputSchema))
+  .output(zodAdapter<JsonQueryOutput>(JsonQueryOutputSchema))
+  .meta({
+    description: "Find the values at a JSON Pointer or a path in a JSON value",
+    args: [],
+    shorts: { pointer: "p" },
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: JsonQueryInput): Promise<JsonQueryOutput> => jsonQuery(input))
+  .build();
+
+const jsonPatchProcedure = createProcedure()
+  .path(["json", "patch"])
+  .input(zodAdapter<JsonPatchInput>(JsonPatchInputSchema))
+  .output(zodAdapter<JsonPatchOutput>(JsonPatchOutputSchema))
+  .meta({
+    description: "Apply an RFC 6902 JSON Patch to a JSON value",
+    args: [],
+    shorts: {},
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: JsonPatchInput): Promise<JsonPatchOutput> => jsonPatch(input))
+  .build();
+
+const jsonDiffProcedure = createProcedure()
+  .path(["json", "diff"])
+  .input(zodAdapter<JsonDiffInput>(JsonDiffInputSchema))
+  .output(zodAdapter<JsonDiffOutput>(JsonDiffOutputSchema))
+  .meta({
+    description: "Give the RFC 6902 JSON Patch that changes one JSON value into another",
+    args: [],
+    shorts: {},
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: JsonDiffInput): Promise<JsonDiffOutput> => jsonDiff(input))
+  .build();
+
+const jsonMergeProcedure = createProcedure()
+  .path(["json", "merge"])
+  .input(zodAdapter<JsonMergeInput>(JsonMergeInputSchema))
+  .output(zodAdapter<JsonMergeOutput>(JsonMergeOutputSchema))
+  .meta({
+    description: "Apply an RFC 7386 JSON merge patch to a JSON value",
+    args: [],
+    shorts: {},
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: JsonMergeInput): Promise<JsonMergeOutput> => jsonMerge(input))
+  .build();
+
+const jsonValidateProcedure = createProcedure()
+  .path(["json", "validate"])
+  .input(zodAdapter<JsonValidateInput>(JsonValidateInputSchema))
+  .output(zodAdapter<JsonValidateOutput>(JsonValidateOutputSchema))
+  .meta({
+    description: "Examine a JSON value against a JSON Schema",
+    args: [],
+    shorts: {},
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: JsonValidateInput): Promise<JsonValidateOutput> => jsonValidate(input))
+  .build();
+
+const yamlParseProcedure = createProcedure()
+  .path(["yaml", "parse"])
+  .input(zodAdapter<YamlParseInput>(YamlParseInputSchema))
+  .output(zodAdapter<YamlParseOutput>(YamlParseOutputSchema))
+  .meta({
+    description: "Parse YAML text into a JSON value",
+    args: ["text"],
+    shorts: { all: "a" },
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: YamlParseInput): Promise<YamlParseOutput> => yamlParse(input))
+  .build();
+
+const yamlStringifyProcedure = createProcedure()
+  .path(["yaml", "stringify"])
+  .input(zodAdapter<YamlStringifyInput>(YamlStringifyInputSchema))
+  .output(zodAdapter<YamlStringifyOutput>(YamlStringifyOutputSchema))
+  .meta({
+    description: "Write a JSON value as YAML text",
+    args: [],
+    shorts: { indent: "i", sortKeys: "s" },
+    output: "json",
+    effects: PURE_EFFECTS,
+  })
+  .handler(async (input: YamlStringifyInput): Promise<YamlStringifyOutput> => yamlStringify(input))
+  .build();
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing.
+ */
+export const jsonModule: ProcedureModule = defineModule("@procedures/json", [
+  jsonQueryProcedure,
+  jsonPatchProcedure,
+  jsonDiffProcedure,
+  jsonMergeProcedure,
+  jsonValidateProcedure,
+  yamlParseProcedure,
+  yamlStringifyProcedure,
+]);
+
+export default jsonModule;
+
+/**
+ * This function registers the procedures of @procedures/json in a registry. The default is the
+ * global registry.
+ */
+export function registerJsonProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [jsonModule]);
+}