@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xdm/index.js

@@ -0,0 +1,47 @@
+/**
+ * The XPath and XQuery Data Model 3.1 for a basic (non-schema-aware)
+ * processor: atomic types and values, casting, comparisons, arithmetic,
+ * atomization and effective boolean value.
+ *
+ * @module @tradik/xslt3/xdm
+ */
+
+export { XPathError } from "../errors.js";
+export {
+  allTypes,
+  derivesFrom,
+  getType,
+  isNumericType,
+  namePatterns,
+  types,
+  XS_NAMESPACE,
+} from "./types.js";
+export {
+  atomic,
+  AtomicValue,
+  checkFacets,
+  isArray,
+  isAtomic,
+  isFunctionItem,
+  isMap,
+  isNode,
+  ITEM_KIND,
+  itemKind,
+} from "./atomic.js";
+export { Decimal, DIVISION_SCALE } from "./decimal.js";
+export { DateTimeValue, MAX_YEAR } from "./datetime.js";
+export { DurationValue } from "./duration.js";
+export { QNameValue } from "./qname.js";
+export { canonicalString, fromLexical } from "./lexical.js";
+export { cast, castable } from "./cast.js";
+export { compareAtomic, deepEqualAtomic, valueCompare } from "./compare.js";
+export { generalCompare, toNumber } from "./generalCompare.js";
+export { arithmetic, unaryArithmetic } from "./arithmetic.js";
+export {
+  atomize,
+  effectiveBooleanValue,
+  nodeStringValue,
+  stringValue,
+  typedValue,
+} from "./nodes.js";
+export { compareCodepoints, normalizeWhitespace } from "./strings.js";

package/src/xdm/lexical.js

@@ -0,0 +1,126 @@
+/**
+ * Lexical spaces of all built-in atomic types: parsing a string into a
+ * typed value (F&O 3.1 19.2, casting from xs:string) and the canonical
+ * string of a value (F&O 3.1 19.1.1, casting to xs:string).
+ *
+ * @module @tradik/xslt3/xdm/lexical
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue, checkFacets } from "./atomic.js";
+import {
+  formatBase64Binary,
+  formatHexBinary,
+  parseBase64Binary,
+  parseHexBinary,
+} from "./binary.js";
+import { formatDateTime, parseDateTime } from "./datetime.js";
+import { formatDuration, parseDuration } from "./duration.js";
+import {
+  formatDouble,
+  parseDecimal,
+  parseDouble,
+  parseFloat32,
+  parseInteger,
+} from "./numeric.js";
+import { parseQName } from "./qname.js";
+import { normalizeWhitespace, parseBoolean } from "./strings.js";
+import { getType } from "./types.js";
+
+const identity = (text) => text;
+const durationKinds = ["duration", "yearMonthDuration", "dayTimeDuration"];
+const dateTimeKinds = [
+  "dateTime",
+  "date",
+  "time",
+  "gYearMonth",
+  "gYear",
+  "gMonthDay",
+  "gDay",
+  "gMonth",
+];
+
+/** Parsers by cast-primitive local name: (text, kind, options) → value | null. */
+const parsers = {
+  untypedAtomic: identity,
+  string: identity,
+  anyURI: identity,
+  boolean: parseBoolean,
+  decimal: parseDecimal,
+  integer: parseInteger,
+  double: parseDouble,
+  float: parseFloat32,
+  hexBinary: parseHexBinary,
+  base64Binary: parseBase64Binary,
+  QName: (text, _kind, options) => parseQName(text, options.resolveNamespace),
+};
+for (const kind of durationKinds) {
+  parsers[kind] = (text) => parseDuration(kind, text);
+}
+for (const kind of dateTimeKinds) {
+  parsers[kind] = (text) => parseDateTime(kind, text);
+}
+
+/** Formatters by cast-primitive local name: value → canonical string. */
+const formatters = {
+  untypedAtomic: identity,
+  string: identity,
+  anyURI: identity,
+  boolean: String,
+  decimal: String,
+  integer: String,
+  double: (value) => formatDouble(value),
+  float: (value) => formatDouble(value, true),
+  hexBinary: formatHexBinary,
+  base64Binary: formatBase64Binary,
+  QName: String,
+  NOTATION: String,
+};
+for (const kind of durationKinds) {
+  formatters[kind] = (value) => formatDuration(kind, value);
+}
+for (const kind of dateTimeKinds) {
+  formatters[kind] = (value) => formatDateTime(kind, value);
+}
+
+/**
+ * Converts a string to a value of an atomic type by the rules of XSD
+ * validation: whiteSpace facet, lexical space, then the other facets.
+ * @param {string|object} typeName - Target type
+ * @param {string} text
+ * @param {object} [options]
+ * @param {import("./qname.js").NamespaceResolver} [options.resolveNamespace]
+ *   - Prefix resolver for xs:QName
+ * @returns {AtomicValue}
+ * @throws {XPathError} XPST0080 for abstract types, FORG0001 for invalid
+ *   text, FODT0001/FODT0002 for out-of-range dates/durations, FONS0004 for
+ *   unbound QName prefixes
+ */
+export function fromLexical(typeName, text, options = {}) {
+  const type = getType(typeName);
+  if (type.abstract) {
+    throw new XPathError("XPST0080", `Cannot cast to ${type.prefixedName}`);
+  }
+  const parse = parsers[type.castPrimitive.localName];
+  const normalized = normalizeWhitespace(text, type.whiteSpace);
+  const value = parse
+    ? parse(normalized, type.castPrimitive.localName, options)
+    : null;
+  if (value === null) {
+    throw new XPathError(
+      "FORG0001",
+      `"${text}" is not a valid ${type.prefixedName}`,
+    );
+  }
+  return new AtomicValue(type, checkFacets(type, value));
+}
+
+/**
+ * Canonical string of an atomic value (the result of casting it to
+ * xs:string).
+ * @param {AtomicValue} item
+ * @returns {string}
+ */
+export function canonicalString(item) {
+  return formatters[item.type.castPrimitive.localName](item.value);
+}

package/src/xdm/nodes.js

@@ -0,0 +1,170 @@
+/**
+ * Accessors of the data model for any item: string value, typed value
+ * (atomization) and effective boolean value.
+ *
+ * Nodes are DOM nodes of any implementation; only `nodeType`, `nodeValue`
+ * and `firstChild`/`nextSibling` (else `childNodes`) are read. Without a schema, elements, attributes, text
+ * and document nodes have an xs:untypedAtomic typed value; comments,
+ * processing instructions and namespace nodes an xs:string one.
+ *
+ * @module @tradik/xslt3/xdm/nodes
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue, itemKind } from "./atomic.js";
+import { canonicalString } from "./lexical.js";
+import { types } from "./types.js";
+
+const TEXT_NODE = 3;
+const CDATA_SECTION_NODE = 4;
+const PROCESSING_INSTRUCTION_NODE = 7;
+const COMMENT_NODE = 8;
+/** nodeType used for XPath namespace nodes by DOM-based XPath engines. */
+const NAMESPACE_NODE = 13;
+const ELEMENT_NODE = 1;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_FRAGMENT_NODE = 11;
+const containers = new Set([
+  ELEMENT_NODE,
+  DOCUMENT_NODE,
+  DOCUMENT_FRAGMENT_NODE,
+]);
+
+/**
+ * Appends the text of the descendant text nodes of a node.
+ * @param {Node} node
+ * @param {string[]} parts
+ */
+function collectText(node, parts) {
+  // firstChild/nextSibling: childNodes is a live list behind a Proxy in
+  // jsdom, several times slower to iterate
+  if (node.firstChild !== undefined) {
+    for (let child = node.firstChild; child; child = child.nextSibling) {
+      const type = child.nodeType;
+      if (type === TEXT_NODE || type === CDATA_SECTION_NODE) {
+        parts.push(child.nodeValue);
+      } else if (type === ELEMENT_NODE) {
+        collectText(child, parts);
+      }
+    }
+    return;
+  }
+  for (const child of node.childNodes) {
+    if (child.nodeType === TEXT_NODE || child.nodeType === CDATA_SECTION_NODE) {
+      parts.push(child.nodeValue);
+    } else if (child.nodeType === ELEMENT_NODE) {
+      collectText(child, parts);
+    }
+  }
+}
+
+/**
+ * String value of a node (dm:string-value): the concatenated descendant
+ * text of elements and documents, the value of other nodes.
+ * @param {Node} node
+ * @returns {string}
+ */
+export function nodeStringValue(node) {
+  return stringValueOf(node, node.nodeType);
+}
+
+/**
+ * nodeStringValue() of a node whose nodeType was read already.
+ * @param {Node} node
+ * @param {number} type - Its nodeType
+ * @returns {string}
+ */
+function stringValueOf(node, type) {
+  if (!containers.has(type)) return node.nodeValue ?? "";
+  const first = node.firstChild;
+  if (first && first.nextSibling === null) {
+    // A single child, typically the text of a leaf element
+    const type = first.nodeType;
+    if (type === TEXT_NODE || type === CDATA_SECTION_NODE) {
+      return first.nodeValue;
+    }
+  }
+  const parts = [];
+  collectText(node, parts);
+  return parts.join("");
+}
+
+/** Node types whose typed value is an xs:string. */
+const stringTyped = new Set([
+  PROCESSING_INSTRUCTION_NODE,
+  COMMENT_NODE,
+  NAMESPACE_NODE,
+]);
+
+/**
+ * Typed value of a node (dm:typed-value) in a non-schema-aware processor.
+ * @param {Node} node
+ * @returns {AtomicValue}
+ */
+export function typedValue(node) {
+  const nodeType = node.nodeType;
+  const type = stringTyped.has(nodeType) ? types.string : types.untypedAtomic;
+  return new AtomicValue(type, stringValueOf(node, nodeType));
+}
+
+/**
+ * Atomizes a sequence (fn:data): atomic values are kept, nodes give their
+ * typed value, arrays are flattened recursively.
+ * @param {Array} sequence
+ * @returns {AtomicValue[]}
+ * @throws {XPathError} FOTY0013 for maps and function items
+ */
+export function atomize(sequence) {
+  const result = [];
+  for (const item of sequence) {
+    const kind = itemKind(item);
+    if (kind === "atomic") result.push(item);
+    else if (kind === "node") result.push(typedValue(item));
+    else if (kind === "array") result.push(...atomize(item.members.flat()));
+    else throw new XPathError("FOTY0013", `A ${kind} cannot be atomized`);
+  }
+  return result;
+}
+
+/**
+ * String value of an item (fn:string).
+ * @param {*} item - Atomic value or node
+ * @returns {string}
+ * @throws {XPathError} FOTY0014 for maps, arrays and function items
+ */
+export function stringValue(item) {
+  const kind = itemKind(item);
+  if (kind === "atomic") return canonicalString(item);
+  if (kind === "node") return nodeStringValue(item);
+  throw new XPathError("FOTY0014", `A ${kind} has no string value`);
+}
+
+const stringPrimitives = new Set(["string", "anyURI", "untypedAtomic"]);
+const numericPrimitives = new Set(["decimal", "float", "double"]);
+
+/**
+ * Effective boolean value of a sequence (fn:boolean, XPath 3.1 2.4.3).
+ * @param {Array} sequence
+ * @returns {boolean}
+ * @throws {XPathError} FORG0006 when the sequence has no EBV
+ */
+export function effectiveBooleanValue(sequence) {
+  if (sequence.length === 0) return false;
+  const first = sequence[0];
+  const kind = itemKind(first);
+  if (kind === "node") return true;
+  if (kind === "atomic" && sequence.length === 1) {
+    const { type, value } = first;
+    const primitive = type.primitive.localName;
+    if (primitive === "boolean") return value;
+    if (stringPrimitives.has(primitive)) return value.length > 0;
+    if (numericPrimitives.has(primitive)) {
+      if (typeof value === "object") return value.sign() !== 0;
+      return !(Number.isNaN(value) || value === 0 || value === 0n);
+    }
+  }
+  throw new XPathError(
+    "FORG0006",
+    "The sequence has no effective boolean value",
+  );
+}

package/src/xdm/numeric.js

@@ -0,0 +1,122 @@
+/**
+ * Lexical forms of the numeric types (XSD 1.1 Part 2) and their canonical
+ * string representations for casting to xs:string (F&O 3.1 section 19.1.2).
+ *
+ * Value representations: xs:decimal is a {@link Decimal}, xs:integer and
+ * its subtypes are BigInts, xs:double and xs:float are JS numbers (floats
+ * rounded with Math.fround; -0, NaN and the infinities are kept).
+ *
+ * @module @tradik/xslt3/xdm/numeric
+ */
+
+import { Decimal } from "./decimal.js";
+
+const integerPattern = /^[+-]?\d+$/;
+const doublePattern = /^[+-]?(\d+(\.\d*)?|\.\d+)([Ee][+-]?\d+)?$/;
+const specialDoubles = new Map([
+  ["INF", Infinity],
+  ["+INF", Infinity],
+  ["-INF", -Infinity],
+  ["NaN", NaN],
+]);
+
+/**
+ * Parses an xs:integer lexical form (already whitespace-collapsed).
+ * @param {string} text
+ * @returns {bigint|null} null when invalid
+ */
+export function parseInteger(text) {
+  return integerPattern.test(text) ? BigInt(text) : null;
+}
+
+/**
+ * Parses an xs:decimal lexical form.
+ * @param {string} text
+ * @returns {Decimal|null} null when invalid
+ */
+export function parseDecimal(text) {
+  return Decimal.parse(text);
+}
+
+/**
+ * Parses an xs:double lexical form, including "INF", "+INF", "-INF",
+ * "NaN" and negative zero.
+ * @param {string} text
+ * @returns {number|null} null when invalid
+ */
+export function parseDouble(text) {
+  if (specialDoubles.has(text)) return specialDoubles.get(text);
+  return doublePattern.test(text) ? Number(text) : null;
+}
+
+/**
+ * Parses an xs:float lexical form. The decimal text is rounded to a double
+ * first and then to a float, which can differ from direct rounding in the
+ * last bit for rare inputs.
+ * @param {string} text
+ * @returns {number|null} null when invalid
+ */
+export function parseFloat32(text) {
+  const value = parseDouble(text);
+  return value === null ? null : Math.fround(value);
+}
+
+/**
+ * Shortest decimal digits that read back as the same double, or as the
+ * same float when `isFloat` is set.
+ * @param {number} n - Finite, non-zero
+ * @param {boolean} isFloat
+ * @returns {{digits: string, exponent: number}} significant digits
+ *   d1d2d3… without trailing zeros; the value is d1.d2d3… × 10^exponent
+ */
+function shortestDigits(n, isFloat) {
+  let text = n.toExponential();
+  for (let precision = 0; isFloat && precision < 9; precision++) {
+    const candidate = n.toExponential(precision);
+    if (Math.fround(Number(candidate)) === n) {
+      text = candidate;
+      break;
+    }
+  }
+  const [mantissa, exponent] = text.split("e");
+  const digits = mantissa.replace(/^-/, "").replace(".", "").replace(/0+$/, "");
+  return { digits, exponent: Number(exponent) };
+}
+
+/**
+ * Canonical string of an xs:double or xs:float value (F&O 3.1 19.1.2):
+ * plain decimal notation for magnitudes in [1e-6, 1e6), otherwise
+ * scientific "1.0E10" / "1.5E-7"; "INF", "-INF", "NaN", "0", "-0".
+ * @param {number} n
+ * @param {boolean} [isFloat=false] - Use the shortest float digits
+ * @returns {string}
+ */
+export function formatDouble(n, isFloat = false) {
+  if (Number.isNaN(n)) return "NaN";
+  if (n === Infinity) return "INF";
+  if (n === -Infinity) return "-INF";
+  if (n === 0) return Object.is(n, -0) ? "-0" : "0";
+  const { digits, exponent } = shortestDigits(n, isFloat);
+  const sign = n < 0 ? "-" : "";
+  const magnitude = Math.abs(n);
+  if (magnitude >= 1e-6 && magnitude < 1e6) {
+    return (
+      sign + Decimal.of(BigInt(digits), digits.length - 1 - exponent).toString()
+    );
+  }
+  return `${sign}${digits[0]}.${digits.slice(1) || "0"}E${exponent}`;
+}
+
+/**
+ * Converts a finite double or float to the decimal it prints as (the
+ * shortest round-trip digits), as used for casting to xs:decimal.
+ * @param {number} n - Finite number
+ * @param {boolean} [isFloat=false]
+ * @returns {Decimal}
+ */
+export function numberToDecimal(n, isFloat = false) {
+  if (n === 0) return Decimal.ZERO;
+  const { digits, exponent } = shortestDigits(n, isFloat);
+  const unscaled = BigInt(digits);
+  return Decimal.of(n < 0 ? -unscaled : unscaled, digits.length - 1 - exponent);
+}

package/src/xdm/qname.js

@@ -0,0 +1,65 @@
+/**
+ * xs:QName and xs:NOTATION values: `{ prefix, namespaceURI, localName }`,
+ * with "" for no prefix and no namespace. Casting from a string needs a
+ * namespace resolver for the prefix.
+ *
+ * @module @tradik/xslt3/xdm/qname
+ */
+
+import { XPathError } from "../errors.js";
+import { namePatterns } from "./types.js";
+
+/** A qualified name. */
+export class QNameValue {
+  /**
+   * @param {string} namespaceURI - "" for no namespace
+   * @param {string} localName
+   * @param {string} [prefix=""]
+   */
+  constructor(namespaceURI, localName, prefix = "") {
+    this.namespaceURI = namespaceURI;
+    this.localName = localName;
+    this.prefix = prefix;
+    Object.freeze(this);
+  }
+
+  /** @returns {string} "prefix:local" or "local" */
+  toString() {
+    return this.prefix ? `${this.prefix}:${this.localName}` : this.localName;
+  }
+}
+
+/**
+ * Resolves a namespace prefix ("" for the default namespace used for
+ * unprefixed names) to a URI, or returns null/undefined when unbound.
+ * @callback NamespaceResolver
+ * @param {string} prefix
+ * @returns {string|null|undefined}
+ */
+
+/**
+ * Parses a lexical QName (whitespace already collapsed).
+ * @param {string} text
+ * @param {NamespaceResolver} [resolveNamespace] - Without it only
+ *   unprefixed names can be cast, and they get no namespace
+ * @returns {QNameValue|null} null when the text is not a lexical QName
+ * @throws {XPathError} FONS0004 when the prefix is not bound
+ */
+export function parseQName(text, resolveNamespace) {
+  const parts = text.split(":");
+  if (
+    parts.length > 2 ||
+    !parts.every((part) => namePatterns.ncName.test(part))
+  ) {
+    return null;
+  }
+  const [prefix, localName] = parts.length === 2 ? parts : ["", parts[0]];
+  const namespaceURI = resolveNamespace?.(prefix) ?? (prefix ? null : "");
+  if (namespaceURI === null) {
+    throw new XPathError(
+      "FONS0004",
+      `No namespace is bound to the prefix ${prefix}`,
+    );
+  }
+  return new QNameValue(namespaceURI, localName, prefix);
+}

package/src/xdm/strings.js

@@ -0,0 +1,52 @@
+/**
+ * String helpers of the data model: the whiteSpace facet, the xs:boolean
+ * lexical space and codepoint string comparison.
+ *
+ * @module @tradik/xslt3/xdm/strings
+ */
+
+/**
+ * Applies a whiteSpace facet value (XSD 1.1 Part 2 section 4.3.6). Only the
+ * XML whitespace characters (space, tab, CR, LF) are affected.
+ * @param {string} text
+ * @param {"preserve"|"replace"|"collapse"} mode
+ * @returns {string}
+ */
+export function normalizeWhitespace(text, mode) {
+  if (mode === "preserve") return text;
+  const replaced = text.replace(/[\t\n\r]/g, " ");
+  // not String#trim, which also strips non-XML whitespace such as U+00A0
+  return mode === "replace"
+    ? replaced
+    : replaced.replace(/ {2,}/g, " ").replace(/^ | $/g, "");
+}
+
+/**
+ * Parses the xs:boolean lexical forms "true", "false", "1", "0".
+ * @param {string} text - Whitespace-collapsed
+ * @returns {boolean|null} null when invalid
+ */
+export function parseBoolean(text) {
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
+  return null;
+}
+
+/**
+ * Compares strings by Unicode codepoints (the default collation), unlike
+ * the JS operators, which compare UTF-16 code units.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} -1, 0 or 1
+ */
+export function compareCodepoints(a, b) {
+  if (a === b) return 0;
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const x = a.codePointAt(i);
+    const y = b.codePointAt(i);
+    if (x !== y) return x < y ? -1 : 1;
+    if (x > 0xffff) i++;
+  }
+  return a.length < b.length ? -1 : 1;
+}