@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/serialize/params/settings.js

@@ -0,0 +1,153 @@
+/**
+ * Normalized serialization settings: the parameters given to the API
+ * (camelCase or hyphenated names) converted, defaulted and checked for the
+ * conflicts of Serialization 3.1 (SEPM0009, SEPM0010) and the values this
+ * serializer does not support (SESU0007, SESU0011, SESU0013).
+ *
+ * @module @tradik/xslt3/serialize/params/settings
+ */
+
+import { XPathError } from "../../errors.js";
+import { resolveEncoding } from "../output/encoding.js";
+import { PARAMETER_KINDS, toCamelCase, toHyphenated } from "./names.js";
+import { CONVERTERS } from "./values.js";
+
+/**
+ * @typedef {object} Settings
+ * @property {string} method
+ * @property {boolean} allowDuplicateNames
+ * @property {boolean} byteOrderMark - Default: yes for UTF-16 only
+ * @property {Set<string>} cdataSectionElements - Clark names
+ * @property {string} [doctypePublic]
+ * @property {string} [doctypeSystem]
+ * @property {import("../output/encoding.js").Encoding} encoding
+ * @property {boolean} escapeUriAttributes
+ * @property {number} htmlVersion - 5 or 4 (html and xhtml methods)
+ * @property {boolean} includeContentType
+ * @property {boolean} indent
+ * @property {string} [itemSeparator]
+ * @property {string} jsonNodeOutputMethod
+ * @property {string} mediaType
+ * @property {string} normalizationForm - "none", "NFC", "NFD", "NFKC", "NFKD"
+ * @property {boolean} omitXmlDeclaration
+ * @property {"yes"|"no"|"omit"} standalone
+ * @property {Set<string>} suppressIndentation - Clark names
+ * @property {boolean} undeclarePrefixes
+ * @property {Map<string, string>|null} useCharacterMaps
+ * @property {string} version - XML version (xml and xhtml methods)
+ */
+
+/** Defaults of the parameters that have one (camelCase names). */
+const DEFAULTS = Object.freeze({
+  method: "xml",
+  allowDuplicateNames: false,
+  cdataSectionElements: new Set(),
+  encoding: "UTF-8",
+  escapeUriAttributes: true,
+  includeContentType: true,
+  indent: false,
+  jsonNodeOutputMethod: "xml",
+  normalizationForm: "none",
+  omitXmlDeclaration: false,
+  standalone: "omit",
+  suppressIndentation: new Set(),
+  undeclarePrefixes: false,
+  useCharacterMaps: null,
+});
+
+const NORMALIZATION_FORMS = new Set(["NFC", "NFD", "NFKC", "NFKD", "none"]);
+
+/**
+ * Converts the given parameters (undefined values are absent).
+ * @param {Record<string, *>} params
+ * @returns {Record<string, *>} converted values by camelCase name
+ */
+function convert(params) {
+  const values = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    const hyphenated = key.includes("-") ? key : toHyphenated(key);
+    const kind = PARAMETER_KINDS[hyphenated];
+    if (!kind) continue;
+    values[toCamelCase(hyphenated)] = CONVERTERS[kind](hyphenated, value);
+  }
+  return values;
+}
+
+/**
+ * The HTML version requested for the html and xhtml methods: html-version,
+ * else (html method) version, else 5 for html and 4 (XHTML 1.0) for xhtml.
+ * @param {Record<string, *>} values - Converted values
+ * @returns {number} 4 or 5
+ * @throws {XPathError} SESU0013 for other versions
+ */
+function htmlVersionOf(values) {
+  let version = values.htmlVersion;
+  if (version === undefined && values.method === "html" && values.version) {
+    version = CONVERTERS.decimal("version", values.version);
+  }
+  if (version === undefined) return values.method === "xhtml" ? 4 : 5;
+  // Decimal versions compared with a tolerance: 5, 5.0, 4.0 and 4.01
+  const near = (target) => Math.abs(version - target) < 1e-9;
+  if (near(5)) return 5;
+  if (near(4) || near(4.01)) return 4;
+  throw new XPathError("SESU0013", `Unsupported HTML version ${version}`);
+}
+
+/**
+ * Checks the XML-related parameters of the xml and xhtml methods.
+ * @param {Settings} settings
+ * @throws {XPathError} SESU0013, SEPM0009 or SEPM0010
+ */
+function checkXml(settings) {
+  const { version, omitXmlDeclaration, standalone } = settings;
+  if (version !== "1.0" && version !== "1.1") {
+    throw new XPathError("SESU0013", `Unsupported XML version ${version}`);
+  }
+  if (omitXmlDeclaration && standalone !== "omit") {
+    throw new XPathError(
+      "SEPM0009",
+      "standalone conflicts with omit-xml-declaration",
+    );
+  }
+  if (omitXmlDeclaration && version !== "1.0" && settings.doctypeSystem) {
+    throw new XPathError(
+      "SEPM0009",
+      "doctype-system with XML 1.1 needs the XML declaration",
+    );
+  }
+  if (settings.undeclarePrefixes && version === "1.0") {
+    throw new XPathError("SEPM0010", "undeclare-prefixes needs XML 1.1");
+  }
+}
+
+/**
+ * Normalizes serialization parameters.
+ * @param {Record<string, *>} [params] - Parameters by camelCase or
+ *   hyphenated name (unknown names are ignored)
+ * @returns {Settings}
+ * @throws {XPathError} SEPM0016 for invalid values, SEPM0009/SEPM0010 for
+ *   conflicts, SESU0007/SESU0011/SESU0013 for unsupported values
+ */
+export function normalizeSettings(params = {}) {
+  const values = { ...DEFAULTS, ...convert(params) };
+  if (!NORMALIZATION_FORMS.has(values.normalizationForm)) {
+    throw new XPathError(
+      "SESU0011",
+      `Unsupported normalization form ${values.normalizationForm}`,
+    );
+  }
+  const htmlLike = values.method === "html" || values.method === "xhtml";
+  const settings = {
+    ...values,
+    encoding: resolveEncoding(values.encoding),
+    byteOrderMark: values.byteOrderMark ?? /^utf-?16$/i.test(values.encoding),
+    htmlVersion: htmlLike ? htmlVersionOf(values) : 5,
+    mediaType: values.mediaType ?? "text/html",
+    version: values.method === "html" ? "1.0" : (values.version ?? "1.0"),
+  };
+  if (settings.method === "xml" || settings.method === "xhtml") {
+    checkXml(settings);
+  }
+  return settings;
+}

package/src/serialize/params/values.js

@@ -0,0 +1,163 @@
+/**
+ * Conversion of serialization parameter values given in the JavaScript
+ * API (booleans, numbers, strings, arrays, Maps, objects) or as the
+ * lexical `value` attributes of an `output:serialization-parameters`
+ * element into their normalized form. A value outside the domain of its
+ * parameter is a SEPM0016 error (the element form turns it into SEPM0017).
+ *
+ * @module @tradik/xslt3/serialize/params/values
+ */
+
+import { XPathError } from "../../errors.js";
+import { METHODS } from "./names.js";
+
+/**
+ * @param {string} name - Parameter name
+ * @param {*} value - Rejected value
+ * @returns {XPathError} SEPM0016
+ */
+export const invalidValue = (name, value) =>
+  new XPathError(
+    "SEPM0016",
+    `Invalid value ${JSON.stringify(String(value))} of serialization parameter ${name}`,
+  );
+
+const TRUE_WORDS = new Set(["yes", "true", "1"]);
+const FALSE_WORDS = new Set(["no", "false", "0"]);
+
+/**
+ * @param {string} name
+ * @param {boolean|string} value - A boolean or yes/no, true/false, 1/0
+ * @returns {boolean}
+ */
+export function toBoolean(name, value) {
+  if (typeof value === "boolean") return value;
+  const word = String(value).trim();
+  if (TRUE_WORDS.has(word)) return true;
+  if (FALSE_WORDS.has(word)) return false;
+  throw invalidValue(name, value);
+}
+
+/**
+ * @param {string} name
+ * @param {boolean|string|null} value - A boolean, yes/no/omit or null (omit)
+ * @returns {"yes"|"no"|"omit"}
+ */
+export function toStandalone(name, value) {
+  if (value === null || String(value).trim() === "omit") return "omit";
+  return toBoolean(name, value) ? "yes" : "no";
+}
+
+/**
+ * Expanded name of an element name in Clark notation, the form names are
+ * compared in.
+ * @param {string} namespaceURI - "" for no namespace
+ * @param {string} localName
+ * @returns {string} "{uri}local"
+ */
+export const clarkName = (namespaceURI, localName) =>
+  `{${namespaceURI}}${localName}`;
+
+const EQNAME = /^(?:Q?\{([^{}]*)\})?([^\s{}:]+)$/;
+
+/**
+ * One element name: a QName object (`{namespaceURI, localName}`), an
+ * EQName `Q{uri}local`, Clark notation `{uri}local`, a local name, or a
+ * prefixed name when a resolver is given.
+ * @param {string} name - Parameter name, for errors
+ * @param {*} value
+ * @param {(prefix: string) => string|undefined} [resolve] - Prefix lookup
+ * @returns {string} the name in Clark notation
+ */
+export function toClarkName(name, value, resolve) {
+  if (typeof value === "object" && value !== null) {
+    return clarkName(value.namespaceURI ?? "", value.localName);
+  }
+  const text = String(value);
+  const colon = text.indexOf(":");
+  if (resolve && colon > 0 && !text.startsWith("Q{")) {
+    const uri = resolve(text.slice(0, colon));
+    if (uri === undefined) throw invalidValue(name, value);
+    return clarkName(uri, text.slice(colon + 1));
+  }
+  const match = EQNAME.exec(text);
+  if (!match) throw invalidValue(name, value);
+  return clarkName(match[1] ?? "", match[2]);
+}
+
+/**
+ * A list of element names: an array or Set of names, or one string of
+ * whitespace-separated names.
+ * @param {string} name
+ * @param {*} value
+ * @param {(prefix: string) => string|undefined} [resolve]
+ * @returns {Set<string>} names in Clark notation
+ */
+export function toNameSet(name, value, resolve) {
+  const list =
+    typeof value === "string"
+      ? value.split(/\s+/).filter(Boolean)
+      : [...(value[Symbol.iterator] ? value : [value])];
+  return new Set(list.map((item) => toClarkName(name, item, resolve)));
+}
+
+/**
+ * The output method: one of {@link METHODS}. Extension methods (QNames
+ * in a namespace) are not supported.
+ * @param {string} name
+ * @param {*} value - A string or a QName object
+ * @returns {string}
+ */
+export function toMethod(name, value) {
+  if (typeof value === "object" && value !== null) {
+    if (value.namespaceURI) {
+      throw invalidValue(name, `Q{${value.namespaceURI}}${value.localName}`);
+    }
+    return toMethod(name, value.localName);
+  }
+  const text = String(value).trim();
+  if (METHODS.includes(text)) return text;
+  throw invalidValue(name, value);
+}
+
+/**
+ * @param {string} name
+ * @param {number|string|{toNumber: () => number}} value - A decimal
+ * @returns {number}
+ */
+export function toDecimal(name, value) {
+  if (typeof value === "number") return value;
+  if (typeof value?.toNumber === "function") return value.toNumber();
+  const text = String(value).trim();
+  if (!/^[+-]?(\d+(\.\d*)?|\.\d+)$/.test(text)) throw invalidValue(name, value);
+  return Number(text);
+}
+
+/**
+ * A character map: a Map or a plain object from single characters to
+ * replacement strings.
+ * @param {string} name
+ * @param {Map<string, string>|Record<string, string>} value
+ * @returns {Map<string, string>}
+ */
+export function toCharacterMap(name, value) {
+  const entries =
+    value instanceof Map ? [...value.entries()] : Object.entries(value);
+  const map = new Map();
+  for (const [character, replacement] of entries) {
+    if ([...character].length !== 1) throw invalidValue(name, character);
+    map.set(character, String(replacement));
+  }
+  return map;
+}
+
+/** Converters by parameter kind (see PARAMETER_KINDS). */
+export const CONVERTERS = Object.freeze({
+  boolean: toBoolean,
+  string: (_, value) => String(value),
+  qnames: toNameSet,
+  method: toMethod,
+  decimal: toDecimal,
+  standalone: toStandalone,
+  characterMap: toCharacterMap,
+});

package/src/serialize/sequence.js

@@ -0,0 +1,111 @@
+/**
+ * Sequence normalization (Serialization 3.1 section 2), done by the xml,
+ * xhtml, html and text methods before they write anything: arrays are
+ * flattened, atomic values become strings (joined by a space, or by the
+ * item-separator between all items), document nodes are replaced by their
+ * children and adjacent text is merged.
+ *
+ * The result is the list of the children of the normalized document:
+ * strings for text nodes and DOM nodes for elements, comments and
+ * processing instructions.
+ *
+ * @module @tradik/xslt3/serialize/sequence
+ */
+
+import { XPathError } from "../errors.js";
+import { canonicalString, itemKind } from "../xdm/index.js";
+
+const ATTRIBUTE_NODE = 2;
+const TEXT_NODE = 3;
+const CDATA_SECTION_NODE = 4;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_TYPE_NODE = 10;
+const DOCUMENT_FRAGMENT_NODE = 11;
+const NAMESPACE_NODE = 13;
+
+/**
+ * Flattens arrays, without recursion.
+ * @param {Array} sequence
+ * @returns {Array} the items, arrays replaced by their members' items
+ */
+export function flattenArrays(sequence) {
+  const result = [];
+  const pending = [[sequence, 0]];
+  while (pending.length) {
+    const top = pending[pending.length - 1];
+    if (top[1] === top[0].length) {
+      pending.pop();
+      continue;
+    }
+    const item = top[0][top[1]++];
+    if (itemKind(item) === "array") pending.push([item.members.flat(), 0]);
+    else result.push(item);
+  }
+  return result;
+}
+
+/**
+ * Appends a node, or the children of a document node, merging text.
+ * @param {Array<string|Node>} out
+ * @param {Node} node
+ */
+function appendNode(out, node) {
+  const type = node.nodeType;
+  if (type === DOCUMENT_NODE || type === DOCUMENT_FRAGMENT_NODE) {
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      if (child.nodeType !== DOCUMENT_TYPE_NODE) appendNode(out, child);
+    }
+  } else if (type === TEXT_NODE || type === CDATA_SECTION_NODE) {
+    appendText(out, node.nodeValue);
+  } else if (type === ATTRIBUTE_NODE || type === NAMESPACE_NODE) {
+    throw new XPathError(
+      "SENR0001",
+      "An attribute or namespace node cannot be serialized on its own",
+    );
+  } else {
+    out.push(node);
+  }
+}
+
+/**
+ * Appends text, merging it with preceding text.
+ * @param {Array<string|Node>} out
+ * @param {string} text
+ */
+function appendText(out, text) {
+  if (text === "") return;
+  const last = out.length - 1;
+  if (typeof out[last] === "string") out[last] += text;
+  else out.push(text);
+}
+
+/**
+ * Normalizes a sequence.
+ * @param {Array} sequence - XDM items
+ * @param {string} [itemSeparator] - Separator between all items; when
+ *   absent, adjacent atomic values are separated by a space
+ * @returns {Array<string|Node>} the content of the normalized document
+ * @throws {XPathError} SENR0001 for attribute and namespace nodes, maps
+ *   and function items
+ */
+export function normalizeSequence(sequence, itemSeparator) {
+  const out = [];
+  let previousAtomic = false;
+  flattenArrays(sequence).forEach((item, index) => {
+    const kind = itemKind(item);
+    if (itemSeparator !== undefined && index > 0) {
+      appendText(out, itemSeparator);
+    }
+    if (kind === "atomic") {
+      const separator =
+        previousAtomic && itemSeparator === undefined ? " " : "";
+      appendText(out, separator + canonicalString(item));
+    } else if (kind === "node") {
+      appendNode(out, item);
+    } else {
+      throw new XPathError("SENR0001", `A ${kind} cannot be serialized`);
+    }
+    previousAtomic = kind === "atomic";
+  });
+  return out;
+}

package/src/xdm/arithmetic.js

@@ -0,0 +1,155 @@
+/**
+ * Arithmetic operators of XPath 3.1 (section 3.5, appendix B.2) on atomic
+ * values: numeric operators with type promotion here, date/time and
+ * duration operators in {@link module:@tradik/xslt3/xdm/temporalArithmetic}.
+ *
+ * xs:integer arithmetic is exact (BigInt), xs:decimal arithmetic is exact
+ * except division, which keeps {@link DIVISION_SCALE} fraction digits;
+ * xs:float results are rounded with Math.fround; xs:double follows IEEE 754.
+ *
+ * @module @tradik/xslt3/xdm/arithmetic
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue } from "./atomic.js";
+import { cast } from "./cast.js";
+import { Decimal } from "./decimal.js";
+import { temporalArithmetic } from "./temporalArithmetic.js";
+import { isNumericType, types } from "./types.js";
+
+/**
+ * xs:untypedAtomic operands are cast to xs:double (XPath 3.1 3.5).
+ * @param {AtomicValue} item
+ * @returns {AtomicValue}
+ */
+function prepare(item) {
+  return item.type === types.untypedAtomic ? cast(item, types.double) : item;
+}
+
+/** @param {string} what @returns {never} */
+function divisionByZero(what) {
+  throw new XPathError("FOAR0001", `Division by zero in ${what}`);
+}
+
+/** Exact operators on BigInt (xs:integer) operands. */
+const integerOps = {
+  "+": (a, b) => a + b,
+  "-": (a, b) => a - b,
+  "*": (a, b) => a * b,
+  div: (a, b) => decimalOps.div(Decimal.of(a), Decimal.of(b)),
+  idiv: (a, b) => (b === 0n ? divisionByZero("idiv") : a / b),
+  mod: (a, b) => (b === 0n ? divisionByZero("mod") : a % b),
+};
+
+/** Operators on {@link Decimal} operands. */
+const decimalOps = {
+  "+": (a, b) => a.add(b),
+  "-": (a, b) => a.sub(b),
+  "*": (a, b) => a.mul(b),
+  div: (a, b) => (b.sign() === 0 ? divisionByZero("div") : a.div(b)),
+  idiv: (a, b) => (b.sign() === 0 ? divisionByZero("idiv") : a.idiv(b)),
+  mod: (a, b) => (b.sign() === 0 ? divisionByZero("mod") : a.mod(b)),
+};
+
+/** IEEE operators on JS numbers; `round` is Math.fround for xs:float. */
+function floatingOp(op, a, b, round) {
+  switch (op) {
+    case "+":
+      return round(a + b);
+    case "-":
+      return round(a - b);
+    case "*":
+      return round(a * b);
+    case "div":
+      return round(a / b);
+    case "mod":
+      return round(a % b);
+    default: {
+      if (b === 0) divisionByZero("idiv");
+      const quotient = round(a / b);
+      if (!Number.isFinite(quotient)) {
+        throw new XPathError("FOAR0002", "idiv of NaN or infinite values");
+      }
+      return BigInt(Math.trunc(quotient));
+    }
+  }
+}
+
+/**
+ * Numeric operation with promotion integer → decimal → float → double.
+ * @param {AtomicValue} a
+ * @param {string} op
+ * @param {AtomicValue} b
+ * @returns {AtomicValue}
+ */
+function numericArithmetic(a, op, b) {
+  const pa = a.type.primitive.localName;
+  const pb = b.type.primitive.localName;
+  if (pa === "decimal" && pb === "decimal") {
+    const integers = typeof a.value === "bigint" && typeof b.value === "bigint";
+    const toDecimal = (v) => (typeof v === "bigint" ? Decimal.of(v) : v);
+    const value = integers
+      ? integerOps[op](a.value, b.value)
+      : decimalOps[op](toDecimal(a.value), toDecimal(b.value));
+    return new AtomicValue(
+      typeof value === "bigint" ? types.integer : types.decimal,
+      value,
+    );
+  }
+  const isDouble = pa === "double" || pb === "double";
+  const asNumber = (item) =>
+    cast(item, isDouble ? types.double : types.float).value;
+  const value = floatingOp(
+    op,
+    asNumber(a),
+    asNumber(b),
+    isDouble ? Number : Math.fround,
+  );
+  if (typeof value === "bigint") return new AtomicValue(types.integer, value);
+  return new AtomicValue(isDouble ? types.double : types.float, value);
+}
+
+/**
+ * Binary arithmetic `a op b` on two atomic values: numbers, durations,
+ * dates and times (empty operands are the evaluator's concern).
+ * @param {AtomicValue} a
+ * @param {"+"|"-"|"*"|"div"|"idiv"|"mod"} op
+ * @param {AtomicValue} b
+ * @param {{implicitTimezone?: number}} [options] - Implicit timezone in
+ *   minutes, for subtracting dates and times
+ * @returns {AtomicValue}
+ * @throws {XPathError} XPTY0004 for unsupported operand types, FOAR0001
+ *   for division by zero, FOAR0002 for idiv of NaN/INF, FORG0001 for
+ *   untyped operands that are not numbers, FODT0001/FODT0002/FOCA0005 for
+ *   date and duration arithmetic
+ */
+export function arithmetic(a, op, b, options = {}) {
+  const x = prepare(a);
+  const y = prepare(b);
+  if (isNumericType(x.type) && isNumericType(y.type)) {
+    return numericArithmetic(x, op, y);
+  }
+  return temporalArithmetic(x, op, y, options);
+}
+
+/**
+ * Unary minus or plus on a numeric value (xs:untypedAtomic is cast to
+ * xs:double). The result has the operand's primitive numeric type.
+ * @param {"-"|"+"} op
+ * @param {AtomicValue} a
+ * @returns {AtomicValue}
+ * @throws {XPathError} XPTY0004 for non-numeric operands
+ */
+export function unaryArithmetic(op, a) {
+  const x = prepare(a);
+  if (!isNumericType(x.type)) {
+    throw new XPathError(
+      "XPTY0004",
+      `Unary ${op} is not defined for ${x.type.prefixedName}`,
+    );
+  }
+  const { value } = x;
+  const type = typeof value === "bigint" ? types.integer : x.type.primitive;
+  if (op === "+") return new AtomicValue(type, value);
+  return new AtomicValue(type, value instanceof Decimal ? value.neg() : -value);
+}