@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/json/jsonParser.js

@@ -0,0 +1,203 @@
+/**
+ * A strict JSON parser (RFC 7159) for fn:parse-json and fn:json-to-xml
+ * (F&O 3.1 section 17.5). Each value is handed to a builder as soon as it
+ * is read, so that each function makes its own result (DOM nodes, XDM
+ * items) without an intermediate tree; {@link TREE_BUILDER} makes a plain
+ * tree. Strings keep track of which characters were written as escape
+ * sequences, because the `escape` and `fallback` options treat them by
+ * their original form: a string without escape sequences is the slice of
+ * the text it is, the others a list of characters. The `liberal` option
+ * accepts nothing more (allowed: what a liberal parser accepts is
+ * implementation-defined).
+ *
+ * @module @tradik/xslt3/functions/json/jsonParser
+ */
+
+import { XPathError } from "../../errors.js";
+import { scanChars } from "./jsonChars.js";
+
+/** @typedef {import("./jsonChars.js").JsonChar} JsonChar */
+
+/**
+ * The characters of a JSON string: the string itself when it was written
+ * without escape sequences, else its characters.
+ * @typedef {string|JsonChar[]} JsonString
+ */
+
+/**
+ * @typedef {{kind: "object", entries: Array<[JsonString, JsonValue]>}
+ *   | {kind: "array", members: JsonValue[]}
+ *   | {kind: "string", chars: JsonString}
+ *   | {kind: "number", text: string}
+ *   | {kind: "boolean", value: boolean}
+ *   | {kind: "null"}} JsonValue
+ */
+
+/**
+ * Makes the result of each JSON value from the results of its members.
+ * @template T
+ * @typedef {object} JsonBuilder
+ * @property {(entries: Array<[JsonString, T]>) => T} object
+ * @property {(members: T[]) => T} array
+ * @property {(chars: JsonString) => T} string
+ * @property {(text: string) => T} number - The number as written
+ * @property {(value: boolean) => T} boolean
+ * @property {() => T} null
+ */
+
+/** @type {JsonBuilder<JsonValue>} The builder of a plain tree. */
+export const TREE_BUILDER = Object.freeze({
+  object: (entries) => ({ kind: "object", entries }),
+  array: (members) => ({ kind: "array", members }),
+  string: (chars) => ({ kind: "string", chars }),
+  number: (text) => ({ kind: "number", text }),
+  boolean: (value) => ({ kind: "boolean", value }),
+  null: () => ({ kind: "null" }),
+});
+
+const LITERALS = new Set(["true", "false", "null"]);
+const NUMBER = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+const WHITESPACE = /[ \t\n\r]*/y;
+const WORD = /[a-z]+/y;
+/** The body of a string up to a quote, a backslash or a control. */
+// eslint-disable-next-line no-control-regex -- JSON strings exclude them
+const PLAIN = /[^"\\\u0000-\u001f]*/y;
+
+/**
+ * @param {string} message
+ * @returns {never}
+ * @throws {XPathError} FOJS0001
+ */
+const syntaxError = (message) => {
+  throw new XPathError("FOJS0001", `Invalid JSON: ${message}`);
+};
+
+/** A recursive descent parser over one JSON text. */
+class Parser {
+  /**
+   * @param {string} text
+   * @param {JsonBuilder<*>} builder
+   */
+  constructor(text, builder) {
+    this.text = text;
+    this.pos = 0;
+    this.builder = builder;
+  }
+
+  /** Skips JSON whitespace. */
+  skip() {
+    WHITESPACE.lastIndex = this.pos;
+    WHITESPACE.exec(this.text);
+    this.pos = WHITESPACE.lastIndex;
+  }
+
+  /**
+   * @param {string} char - Expected character, after whitespace
+   */
+  expect(char) {
+    this.skip();
+    if (this.text[this.pos] !== char) {
+      syntaxError(`expected "${char}" at offset ${this.pos}`);
+    }
+    this.pos++;
+  }
+
+  /** @returns {*} what the builder makes of the value */
+  value() {
+    this.skip();
+    const char = this.text[this.pos];
+    if (char === "{") return this.object();
+    if (char === "[") return this.array();
+    if (char === '"') return this.builder.string(this.string());
+    WORD.lastIndex = this.pos;
+    const word = WORD.exec(this.text)?.[0];
+    if (LITERALS.has(word)) {
+      this.pos += word.length;
+      return word === "null"
+        ? this.builder.null()
+        : this.builder.boolean(word === "true");
+    }
+    NUMBER.lastIndex = this.pos;
+    const number = NUMBER.exec(this.text)?.[0];
+    if (number === undefined) syntaxError(`unexpected input at ${this.pos}`);
+    this.pos += number.length;
+    if (/^[\w.+-]/.test(this.text[this.pos] ?? "")) {
+      syntaxError(`invalid number at ${this.pos}`);
+    }
+    return this.builder.number(number);
+  }
+
+  /**
+   * Members of an object or array up to the closing bracket.
+   * @param {string} close
+   * @param {() => *} member
+   * @returns {Array}
+   */
+  list(close, member) {
+    this.pos++;
+    this.skip();
+    const items = [];
+    if (this.text[this.pos] === close) {
+      this.pos++;
+      return items;
+    }
+    for (;;) {
+      items.push(member());
+      this.skip();
+      const char = this.text[this.pos++];
+      if (char === close) return items;
+      if (char !== ",") syntaxError(`expected "," or "${close}"`);
+    }
+  }
+
+  /** @returns {*} */
+  object() {
+    const entries = this.list("}", () => {
+      this.skip();
+      if (this.text[this.pos] !== '"') syntaxError("expected a string key");
+      const key = this.string();
+      this.expect(":");
+      return [key, this.value()];
+    });
+    return this.builder.object(entries);
+  }
+
+  /** @returns {*} */
+  array() {
+    return this.builder.array(this.list("]", () => this.value()));
+  }
+
+  /** @returns {JsonString} the characters of a string literal */
+  string() {
+    const start = this.pos + 1;
+    PLAIN.lastIndex = start;
+    PLAIN.exec(this.text);
+    const plainEnd = PLAIN.lastIndex;
+    if (this.text[plainEnd] === '"') {
+      this.pos = plainEnd + 1;
+      return this.text.slice(start, plainEnd);
+    }
+    const { chars, end } = scanChars(this.text, start, syntaxError);
+    this.pos = end + 1;
+    return chars;
+  }
+}
+
+/**
+ * Parses a JSON text; a leading byte order mark is ignored.
+ * @template T
+ * @param {string} text
+ * @param {JsonBuilder<T>} [builder] - Makes the results (default: a plain
+ *   tree of {@link JsonValue})
+ * @returns {T} what the builder makes of the whole text
+ * @throws {XPathError} FOJS0001 when the text is not JSON
+ */
+export function parseJsonText(text, builder = TREE_BUILDER) {
+  const parser = new Parser(text.replace(/^\uFEFF/, ""), builder);
+  const value = parser.value();
+  parser.skip();
+  if (parser.pos < parser.text.length) {
+    syntaxError(`unexpected input after the value at ${parser.pos}`);
+  }
+  return value;
+}

package/src/functions/json/jsonStrings.js

@@ -0,0 +1,116 @@
+/**
+ * Strings between JSON and XDM (F&O 3.1 section 17.5): the `escape` and
+ * `fallback` options of fn:parse-json and fn:json-to-xml, and the escaping
+ * of strings written by fn:xml-to-json.
+ *
+ * @module @tradik/xslt3/functions/json/jsonStrings
+ */
+
+import { isXmlChar, stringItem } from "../support.js";
+
+const SHORT_ESCAPES = new Map([
+  [0x08, "\\b"],
+  [0x09, "\\t"],
+  [0x0a, "\\n"],
+  [0x0c, "\\f"],
+  [0x0d, "\\r"],
+  [0x22, '\\"'],
+  [0x5c, "\\\\"],
+  [0x2f, "\\/"],
+]);
+
+/**
+ * The escape sequence of a character: a two-character one where JSON has
+ * it, else \uXXXX (upper-case hex, a surrogate pair beyond the BMP).
+ * @param {number} cp
+ * @returns {string}
+ */
+export function escapeChar(cp) {
+  const short = SHORT_ESCAPES.get(cp);
+  if (short) return short;
+  const hex = (unit) =>
+    `\\u${unit.toString(16).toUpperCase().padStart(4, "0")}`;
+  if (cp < 0x10000) return hex(cp);
+  const offset = cp - 0x10000;
+  return hex(0xd800 + (offset >> 10)) + hex(0xdc00 + (offset & 0x3ff));
+}
+
+/**
+ * Whether a character is "special" for the escape option: a control
+ * character (x00-x1F, x7F-x9F), a codepoint that is not an XML character
+ * (lone surrogates included) or the backslash.
+ * @param {number} cp
+ * @returns {boolean}
+ */
+export const isSpecial = (cp) =>
+  cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f) || cp === 0x5c || !isXmlChar(cp);
+
+/**
+ * Characters that may need the escape or fallback option: controls, the
+ * C1 range, surrogates and the non-characters xFFFE and xFFFF (a superset
+ * of the special and non-XML characters of the BMP).
+ */
+// eslint-disable-next-line no-control-regex -- controls are escaped
+const MAY_CHANGE = /[\u0000-\u001f\u007f-\u009f\ud800-\udfff\uFFFE\uFFFF]/;
+
+/**
+ * The characters of a string written without escape sequences.
+ * @param {string} text
+ * @returns {import("./jsonChars.js").JsonChar[]}
+ */
+const charsOf = (text) =>
+  Array.from(text, (char) => ({ cp: char.codePointAt(0) }));
+
+/**
+ * The function that turns parsed JSON characters into a string under the
+ * escape and fallback options.
+ * @param {{escape: boolean, fallback?: import("../../items/function.js").FunctionItem}} options
+ * @returns {(chars: import("./jsonParser.js").JsonString) => string}
+ */
+export function stringDecoder({ escape, fallback }) {
+  const replace = fallback
+    ? (sequence) => fallback.invoke([[stringItem(sequence)]])[0].value
+    : () => "\uFFFD";
+  return (json) => {
+    // a string without escape sequences is mostly kept as it is
+    if (typeof json === "string" && !MAY_CHANGE.test(json)) return json;
+    const chars = typeof json === "string" ? charsOf(json) : json;
+    let result = "";
+    for (const { cp, escape: written } of chars) {
+      if (escape) {
+        result += isSpecial(cp) ? escapeChar(cp) : String.fromCodePoint(cp);
+      } else if (isXmlChar(cp)) {
+        result += String.fromCodePoint(cp);
+      } else {
+        result += replace(written ?? escapeChar(cp));
+      }
+    }
+    return result;
+  };
+}
+
+/**
+ * Escapes a string for JSON output (fn:xml-to-json): quotes, backslashes,
+ * solidus and control characters (x00-x1F, x7F-x9F).
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeJsonString(text) {
+  let result = "";
+  for (const char of text) {
+    const cp = char.codePointAt(0);
+    result += needsEscape(cp) ? escapeChar(cp) : char;
+  }
+  return result;
+}
+
+/**
+ * @param {number} cp
+ * @returns {boolean} whether xml-to-json writes the character escaped
+ */
+export const needsEscape = (cp) =>
+  cp <= 0x1f ||
+  (cp >= 0x7f && cp <= 0x9f) ||
+  cp === 0x22 ||
+  cp === 0x5c ||
+  cp === 0x2f;

package/src/functions/json/jsonToXml.js

@@ -0,0 +1,116 @@
+/**
+ * fn:json-to-xml (F&O 3.1 section 17.5.3): JSON to the XML representation
+ * of JSON, elements map, array, string, number, boolean and null in the
+ * fn namespace, built in a new document (dynamic context hook
+ * `createDocument`). A basic processor does not validate (validate=true
+ * raises FOJS0004).
+ *
+ * @module @tradik/xslt3/functions/json/jsonToXml
+ */
+
+import { XPathError } from "../../errors.js";
+import { setBaseUri } from "../baseUris.js";
+import { define, FN_NAMESPACE } from "../support.js";
+import { parseJsonText } from "./jsonParser.js";
+import { stringDecoder } from "./jsonStrings.js";
+import { jsonOptions } from "./parseJson.js";
+
+const SPECS = {
+  duplicates: {
+    type: "xs:string",
+    default: "retain",
+    values: ["reject", "use-first", "retain"],
+  },
+  validate: { type: "xs:boolean", default: false },
+};
+
+/**
+ * The JSON builder (see jsonParser.js) that makes the elements of the XML
+ * representation while the text is parsed, with no intermediate tree.
+ * @param {Document} document
+ * @param {object} options - escape, duplicates and the string decoder
+ * @returns {import("./jsonParser.js").JsonBuilder<Element>}
+ */
+function elementBuilder(document, options) {
+  const element = (name, content) => {
+    const result = document.createElementNS(FN_NAMESPACE, name);
+    if (content) result.appendChild(document.createTextNode(content));
+    return result;
+  };
+  return {
+    object(entries) {
+      const map = element("map");
+      const seen = new Set();
+      for (const [keyChars, child] of entries) {
+        const key = options.decode(keyChars);
+        if (seen.has(key) && options.duplicates !== "retain") {
+          if (options.duplicates === "reject") {
+            throw new XPathError("FOJS0003", `Duplicate key "${key}"`);
+          }
+          continue;
+        }
+        seen.add(key);
+        child.setAttribute("key", key);
+        if (options.escape && key.includes("\\")) {
+          child.setAttribute("escaped-key", "true");
+        }
+        map.appendChild(child);
+      }
+      return map;
+    },
+    array(members) {
+      const array = element("array");
+      for (const member of members) array.appendChild(member);
+      return array;
+    },
+    string(chars) {
+      const content = options.decode(chars);
+      const result = element("string", content);
+      if (options.escape && content.includes("\\")) {
+        result.setAttribute("escaped", "true");
+      }
+      return result;
+    },
+    number: (text) => element("number", text),
+    boolean: (value) => element("boolean", String(value)),
+    null: () => element("null"),
+  };
+}
+
+/**
+ * fn:json-to-xml of a string.
+ * @param {string} json
+ * @param {Array|undefined} optionsArg
+ * @param {{createDocument: () => Document, staticBaseUri?: string}} context
+ * @returns {Array} the document node, whose base URI is the static base URI
+ */
+function jsonToXml(json, optionsArg, context) {
+  const options = jsonOptions(optionsArg, SPECS);
+  if (options.validate) {
+    throw new XPathError(
+      "FOJS0004",
+      "validate=true needs a schema-aware processor",
+    );
+  }
+  const document = context.createDocument();
+  const builder = elementBuilder(document, {
+    ...options,
+    decode: stringDecoder(options),
+  });
+  document.appendChild(parseJsonText(json, builder));
+  return [setBaseUri(document, context.staticBaseUri)];
+}
+
+/** Function definitions. */
+export const jsonToXmlFunctions = [
+  define("json-to-xml", ["xs:string?"], "document-node()?", ([json], c) =>
+    json.length ? jsonToXml(json[0].value, undefined, c) : [],
+  ),
+  define(
+    "json-to-xml",
+    ["xs:string?", "map(*)"],
+    "document-node()?",
+    ([json, options], c) =>
+      json.length ? jsonToXml(json[0].value, options, c) : [],
+  ),
+];

package/src/functions/json/parseJson.js

@@ -0,0 +1,119 @@
+/**
+ * fn:parse-json and fn:json-doc (F&O 3.1 sections 17.5.1 and 17.5.2):
+ * JSON to maps, arrays, xs:string, xs:double and xs:boolean values (null
+ * is the empty sequence).
+ *
+ * @module @tradik/xslt3/functions/json/parseJson
+ */
+
+import { XPathError } from "../../errors.js";
+import { XdmArray } from "../../items/array.js";
+import { XdmMap } from "../../items/map.js";
+import { mapKey } from "../../items/mapKey.js";
+import { readOptions } from "../options.js";
+import { booleanItem, define, doubleItem, stringItem } from "../support.js";
+import { parseJsonText } from "./jsonParser.js";
+import { stringDecoder } from "./jsonStrings.js";
+
+/** Option declarations shared by parse-json and json-to-xml. */
+export const JSON_OPTIONS = {
+  liberal: { type: "xs:boolean", default: false },
+  escape: { type: "xs:boolean", default: false },
+  fallback: { type: "function(xs:string) as xs:string" },
+};
+
+/**
+ * Reads the options of a JSON parsing function.
+ * @param {Array} options - The options argument (a map), or undefined
+ * @param {Record<string, object>} specs - Declarations of the options
+ *   that differ between the functions (duplicates, validate)
+ * @returns {Record<string, *>}
+ * @throws {XPathError} FOJS0005 for invalid values, among which a fallback
+ *   function together with escape=true
+ */
+export function jsonOptions(options, specs) {
+  const result = readOptions(
+    options?.[0],
+    { ...JSON_OPTIONS, ...specs },
+    "FOJS0005",
+  );
+  if (result.escape && result.fallback) {
+    throw new XPathError(
+      "FOJS0005",
+      "The fallback option is not allowed with escape=true",
+    );
+  }
+  return result;
+}
+
+/**
+ * The JSON builder (see jsonParser.js) that makes XDM values while the
+ * text is parsed: each value is a sequence of at most one item.
+ * @param {(chars: import("./jsonParser.js").JsonString) => string} decode
+ *   - String decoder
+ * @param {string} duplicates - "reject", "use-first" or "use-last"
+ * @returns {import("./jsonParser.js").JsonBuilder<Array>}
+ */
+function xdmBuilder(decode, duplicates) {
+  return {
+    object(members) {
+      const entries = new Map();
+      for (const [keyChars, value] of members) {
+        const key = stringItem(decode(keyChars));
+        const k = mapKey(key);
+        if (entries.has(k)) {
+          if (duplicates === "reject") {
+            throw new XPathError("FOJS0003", `Duplicate key "${key.value}"`);
+          }
+          if (duplicates === "use-first") continue;
+        }
+        entries.set(k, { key, value });
+      }
+      return [new XdmMap(entries)];
+    },
+    array: (members) => [new XdmArray(members)],
+    string: (chars) => [stringItem(decode(chars))],
+    number: (text) => [doubleItem(Number(text))],
+    boolean: (value) => [booleanItem(value)],
+    null: () => [],
+  };
+}
+
+/**
+ * fn:parse-json of a string.
+ * @param {string} text
+ * @param {Array} [options] - The options argument
+ * @returns {Array}
+ */
+export function parseJson(text, options) {
+  const { duplicates, ...rest } = jsonOptions(options, {
+    duplicates: {
+      type: "xs:string",
+      default: "use-first",
+      values: ["reject", "use-first", "use-last"],
+    },
+  });
+  return parseJsonText(text, xdmBuilder(stringDecoder(rest), duplicates));
+}
+
+const OPTIONS = "map(*)";
+
+/** Function definitions. */
+export const parseJsonFunctions = [
+  define("parse-json", ["xs:string?"], "item()?", ([json]) =>
+    json.length ? parseJson(json[0].value) : [],
+  ),
+  define("parse-json", ["xs:string?", OPTIONS], "item()?", ([json, options]) =>
+    json.length ? parseJson(json[0].value, options) : [],
+  ),
+  define("json-doc", ["xs:string?"], "item()?", ([href], context) =>
+    href.length ? parseJson(context.loadText(href[0].value)) : [],
+  ),
+  define(
+    "json-doc",
+    ["xs:string?", OPTIONS],
+    "item()?",
+    ([href, options], context) =>
+      href.length ? parseJson(context.loadText(href[0].value), options) : [],
+  ),
+];

package/src/functions/json/xmlRepresentation.js

@@ -0,0 +1,103 @@
+/**
+ * Checks of the XML representation of JSON read by fn:xml-to-json (F&O
+ * 3.1 section 17.5.4): boolean attributes, allowed attributes, the text
+ * of simple elements and the members of maps and arrays (FOJS0006).
+ *
+ * @module @tradik/xslt3/functions/json/xmlRepresentation
+ */
+
+import { XPathError } from "../../errors.js";
+import { normalizeWhitespace, parseBoolean } from "../../xdm/strings.js";
+import { attributesOf } from "../../xpath/eval/domNodes.js";
+import { FN_NAMESPACE } from "../support.js";
+
+/**
+ * @param {string} message
+ * @returns {never}
+ * @throws {XPathError} FOJS0006
+ */
+export const invalid = (message) => {
+  throw new XPathError(
+    "FOJS0006",
+    `Invalid XML representation of JSON: ${message}`,
+  );
+};
+
+const ATTRIBUTES = new Set(["key", "escaped", "escaped-key"]);
+
+/**
+ * A boolean attribute of the representation.
+ * @param {Element} element
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function flag(element, name) {
+  if (!element.hasAttribute(name)) return false;
+  const value = parseBoolean(
+    normalizeWhitespace(element.getAttribute(name), "collapse"),
+  );
+  if (value === null) invalid(`${name}="${element.getAttribute(name)}"`);
+  return value;
+}
+
+/**
+ * The children of an element that matter: elements and text, without
+ * comments and processing instructions.
+ * @param {Element} element
+ * @returns {Node[]}
+ */
+const contentOf = (element) =>
+  [...element.childNodes].filter((n) => n.nodeType !== 7 && n.nodeType !== 8);
+
+/** @param {Node} node @returns {boolean} whether it is a text node */
+const isText = (node) => node.nodeType === 3 || node.nodeType === 4;
+
+/**
+ * Text content of a simple element (string, number, boolean, null).
+ * @param {Element} element
+ * @returns {string}
+ */
+export function textOf(element) {
+  let text = "";
+  for (const node of contentOf(element)) {
+    if (node.nodeType === 1) invalid(`element in <${element.localName}>`);
+    if (isText(node)) text += node.nodeValue;
+  }
+  return text;
+}
+
+/**
+ * The element children of a map or array.
+ * @param {Element} element
+ * @returns {Element[]}
+ */
+export function members(element) {
+  const result = [];
+  for (const node of contentOf(element)) {
+    if (node.nodeType === 1) result.push(node);
+    else if (isText(node) && /\S/.test(node.nodeValue)) {
+      invalid(`text in <${element.localName}>`);
+    }
+  }
+  return result;
+}
+
+/**
+ * Checks the attributes of an element: key and escaped-key, escaped on
+ * strings, and attributes in other namespaces than fn.
+ * @param {Element} element
+ * @throws {XPathError} FOJS0006 for another attribute
+ */
+export function checkAttributes(element) {
+  for (const attribute of attributesOf(element)) {
+    const uri = attribute.namespaceURI ?? "";
+    const allowed =
+      uri === ""
+        ? ATTRIBUTES.has(attribute.localName) &&
+          (attribute.localName !== "escaped" || element.localName === "string")
+        : uri !== FN_NAMESPACE;
+    if (!allowed) {
+      invalid(`attribute ${attribute.name} on <${element.localName}>`);
+    }
+  }
+}