@procedures/json 0.0.0-stage → 0.2.3

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+import type { PatchOperation } from "./patch.js";
+
+export type { JsonValue } from "./value.js";
+export type { PatchOperation } from "./patch.js";
+
+// =============================================================================
+// json.query Types - Find the values at a JSON Pointer or a path in a JSON value
+// =============================================================================
+
+export interface JsonQueryInput {
+  /** The JSON value to search. */
+  value: unknown;
+  /** A JSON Pointer (RFC 6901): `/items/0/name`. Give `pointer` or `path`. */
+  pointer?: string | undefined;
+  /** A path query: `items[*].name`, `$..id`. Give `pointer` or `path`. */
+  path?: string | undefined;
+}
+
+export interface JsonQueryOutput {
+  /** True when one or more values match. */
+  found: boolean;
+  /** The value of the first match. */
+  value?: unknown;
+  /** Each match, in document order: its JSON Pointer and its value. */
+  matches: Array<{ pointer: string; value?: unknown }>;
+}
+
+// =============================================================================
+// json.patch Types - Apply an RFC 6902 JSON Patch to a JSON value
+// =============================================================================
+
+export interface JsonPatchInput {
+  value: unknown;
+  /** The operations, in order. */
+  patch: PatchOperation[];
+}
+
+export interface JsonPatchOutput {
+  /** The value after the patch. */
+  value?: unknown;
+}
+
+// =============================================================================
+// json.diff Types - Give the RFC 6902 JSON Patch that changes one JSON value into another
+// =============================================================================
+
+export interface JsonDiffInput {
+  from: unknown;
+  to: unknown;
+}
+
+export interface JsonDiffOutput {
+  /** The operations that change `from` into `to`. Equal values give an empty list. */
+  patch: PatchOperation[];
+}
+
+// =============================================================================
+// json.merge Types - Apply an RFC 7386 JSON merge patch to a JSON value
+// =============================================================================
+
+export interface JsonMergeInput {
+  /** The value to change. */
+  target: unknown;
+  /** The merge patch: an object of changes, where null removes a key. */
+  patch: unknown;
+}
+
+export interface JsonMergeOutput {
+  value?: unknown;
+}
+
+// =============================================================================
+// json.validate Types - Examine a JSON value against a JSON Schema
+// =============================================================================
+
+export interface JsonValidateInput {
+  value: unknown;
+  /** The JSON Schema: an object or a boolean. */
+  schema: unknown;
+}
+
+export interface JsonValidateOutput {
+  valid: boolean;
+  /** Each problem: the JSON Pointer of the part of the value, and a message. */
+  errors: Array<{ pointer: string; message: string }>;
+  /** The keywords of the schema that the check does not examine. Empty: the verdict is complete. */
+  unchecked: string[];
+}
+
+// =============================================================================
+// yaml.parse Types - Parse YAML text into a JSON value
+// =============================================================================
+
+export interface YamlParseInput {
+  text: string;
+  /** True: the text can have more than one document, and `value` is the list of documents. */
+  all?: boolean | undefined;
+}
+
+export interface YamlParseOutput {
+  value?: unknown;
+}
+
+// =============================================================================
+// yaml.stringify Types - Write a JSON value as YAML text
+// =============================================================================
+
+export interface YamlStringifyInput {
+  value: unknown;
+  /** The spaces of one level of indentation: 1 to 8. The default is 2. */
+  indent?: number | undefined;
+  /** The longest line before a fold. 0: no fold. The default is 80. */
+  lineWidth?: number | undefined;
+  /** True: the keys of each map in alphabetical order. */
+  sortKeys?: boolean | undefined;
+}
+
+export interface YamlStringifyOutput {
+  text: string;
+}

package/src/value.ts

@@ -0,0 +1,143 @@
+/**
+ * JSON values: the check, the copy and the comparison. The procedures of this package take and
+ * give only JSON values: null, booleans, finite numbers, strings, arrays and plain objects.
+ *
+ * Each object that this package makes has own data properties only, so a key `__proto__` of the
+ * data stays data: it does not change the prototype of the object (roadmap R6).
+ */
+
+/** A JSON value. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+/** The keys that reach a prototype. A pointer, a path or a patch of this package refuses them. */
+export const PROTOTYPE_KEYS: ReadonlySet<string> = new Set(["__proto__", "constructor", "prototype"]);
+
+/** The kinds of `JsonError`. */
+export type JsonErrorCode =
+  /** A value is not JSON: `undefined`, `NaN`, a function, a date or a class instance. */
+  | "NOT_JSON"
+  /** A JSON Pointer or a path query is not valid. */
+  | "INVALID_POINTER"
+  /** A pointer, a path or a patch names `__proto__`, `constructor` or `prototype`. */
+  | "PROTOTYPE_KEY"
+  /** An operation of a patch is not valid, or its location does not exist. */
+  | "INVALID_PATCH"
+  /** A `test` operation of a patch found another value. */
+  | "TEST_FAILED"
+  /** The YAML text is not valid, or it has a value that JSON does not have. */
+  | "INVALID_YAML"
+  /** The JSON Schema is not a schema. */
+  | "INVALID_SCHEMA";
+
+/** An error of a procedure of this package. A server sends it with the code `HANDLER_ERROR`. */
+export class JsonError extends Error {
+  override readonly name = "JsonError";
+
+  constructor(
+    readonly code: JsonErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** True for an object whose prototype is `Object.prototype` or null. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/** This function sets an own data property: a key `__proto__` stays data. */
+export function put(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
+/** True when the object has an own property with this key. */
+export function hasOwn(target: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(target, key);
+}
+
+/** The text of one reference token of a JSON Pointer (RFC 6901): `~` and `/` are escaped. */
+export function escapeToken(token: string | number): string {
+  return String(token).replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/** The JSON Pointer of a list of tokens. */
+export function formatPointer(tokens: readonly (string | number)[]): string {
+  return tokens.map((token) => `/${escapeToken(token)}`).join("");
+}
+
+/** The description of a value that is not JSON, or undefined for a JSON value. */
+function notJson(value: unknown): string | undefined {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return undefined;
+    case "number":
+      return Number.isFinite(value) ? undefined : `the number ${String(value)}`;
+    case "object":
+      if (value === null || Array.isArray(value) || isPlainObject(value)) return undefined;
+      return `an object of the class ${(value as { constructor?: { name?: string } }).constructor?.name ?? "unknown"}`;
+    default:
+      return `a value of the type ${typeof value}`;
+  }
+}
+
+/**
+ * This function throws `NOT_JSON` when a part of the value is not JSON. The message has the JSON
+ * Pointer of the part. `label` starts the message: the procedure and the field.
+ */
+export function assertJson(value: unknown, label: string): asserts value is JsonValue {
+  const stack: Array<{ value: unknown; tokens: (string | number)[] }> = [{ value, tokens: [] }];
+  const seen = new Set<object>();
+  while (stack.length > 0) {
+    const { value: current, tokens } = stack.pop()!;
+    const problem = notJson(current);
+    if (problem !== undefined) {
+      throw new JsonError("NOT_JSON", `${label}: the value at "${formatPointer(tokens)}" is ${problem}, which JSON does not have`);
+    }
+    if (current === null || typeof current !== "object") continue;
+    if (seen.has(current)) throw new JsonError("NOT_JSON", `${label}: the value at "${formatPointer(tokens)}" refers to itself`);
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (let index = current.length - 1; index >= 0; index--) stack.push({ value: current[index], tokens: [...tokens, index] });
+    } else {
+      for (const key of Object.keys(current)) stack.push({ value: (current as Record<string, unknown>)[key], tokens: [...tokens, key] });
+    }
+  }
+}
+
+/** A deep copy of a JSON value. Each object of the copy has own data properties only. */
+export function cloneJson<T extends JsonValue>(value: T): T;
+export function cloneJson(value: JsonValue): JsonValue {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item) => cloneJson(item));
+  const copy: Record<string, JsonValue> = {};
+  for (const key of Object.keys(value)) put(copy, key, cloneJson(value[key]!));
+  return copy;
+}
+
+/**
+ * True when two JSON values are equal: the same type and value, arrays with equal items in the
+ * same order, and objects with the same keys and equal values in any order. The number 0 and -0
+ * are equal, as in JSON.
+ */
+export function jsonEqual(a: JsonValue, b: JsonValue): boolean {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, index) => jsonEqual(item, b[index]!));
+  }
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+  return keysA.every((key) => hasOwn(b, key) && jsonEqual(a[key]!, b[key]!));
+}
+
+/** The JSON type of a value, for a message. */
+export function typeName(value: JsonValue | undefined): string {
+  if (value === undefined) return "nothing";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value === "object" ? "an object" : `a ${typeof value}`;
+}

package/src/yaml.ts

@@ -0,0 +1,128 @@
+/**
+ * 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, type JsonValue } from "./value.js";
+
+/** The options of the parse. */
+export interface YamlParseOptions {
+  /** True: the text can have more than one document, and the result is the list of documents. */
+  readonly all?: boolean | undefined;
+}
+
+/** The options of the text. */
+export interface YamlStringifyOptions {
+  /** The spaces of one level of indentation: 1 to 8. The default is 2. */
+  readonly indent?: number | undefined;
+  /** The longest line before a fold. 0: no fold. The default is 80. */
+  readonly lineWidth?: number | undefined;
+  /** True: the keys of each map in alphabetical order. The default keeps the order of the value. */
+  readonly sortKeys?: boolean | undefined;
+}
+
+// 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 } as const;
+
+/** The byte order mark. */
+const BOM = String.fromCharCode(0xfeff);
+
+/** The JSON value of a value of the parse. */
+function toJson(value: unknown, tokens: (string | number)[]): JsonValue {
+  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: Record<string, JsonValue> = {};
+    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: Document.Parsed, index: number | undefined): JsonValue {
+  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: unknown;
+  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: string, options: YamlParseOptions = {}): JsonValue {
+  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: readonly RegExp[] = [
+  /^(?: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: JsonValue, options: YamlStringifyOptions = {}): string {
+  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");
+}