@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/nodes.js

@@ -0,0 +1,199 @@
+/**
+ * Functions on nodes (F&O 3.1 section 13): names, root, children,
+ * innermost/outermost, generate-id and lang. Functions with an optional
+ * node argument use the context item when it is omitted.
+ *
+ * @module @tradik/xslt3/functions/nodes
+ */
+
+import { AtomicValue } from "../xdm/atomic.js";
+import { QNameValue } from "../xdm/qname.js";
+import { types } from "../xdm/types.js";
+import { booleanItem, stringItem } from "../xpath/eval/atomics.js";
+import {
+  childrenOf,
+  nodeLocalName,
+  nodeNamespace,
+  nodePrefix,
+  parentOf,
+  rootOf,
+} from "../xpath/eval/domNodes.js";
+import { focusNode } from "./focus.js";
+import { nodePathFunctions } from "./nodePaths.js";
+
+/**
+ * Definitions of a function of an optional node, with the context node as
+ * default (arity 0 and 1).
+ * @param {string} local
+ * @param {string} returns
+ * @param {(node: Node|undefined, context: object) => Array} impl - Called
+ *   with undefined for an empty argument
+ * @returns {object[]}
+ */
+export function nodeFunction(local, returns, impl) {
+  return [
+    {
+      local,
+      params: [],
+      returns,
+      focus: true,
+      impl: (_, context) => impl(focusNode(context), context),
+    },
+    {
+      local,
+      params: ["node()?"],
+      returns,
+      impl: ([arg], context) => impl(arg[0], context),
+    },
+  ];
+}
+
+/** @param {Node} node @returns {boolean} whether the node kind has a name */
+const isNamed = (node) =>
+  [1, 2, 7].includes(node.nodeType) ||
+  (node.nodeType === 13 && node.localName !== "");
+
+/** @param {Node} node @returns {string} the lexical QName of a node */
+function lexicalName(node) {
+  if (!isNamed(node)) return "";
+  const prefix = nodePrefix(node);
+  const local = nodeLocalName(node);
+  return prefix ? `${prefix}:${local}` : local;
+}
+
+/** @type {WeakMap<object, string>} */
+const ids = new WeakMap();
+let nextId = 0;
+
+/**
+ * @param {Node} node
+ * @returns {string} an identifier unique to the node
+ */
+function generateId(node) {
+  let id = ids.get(node);
+  if (id === undefined) {
+    id = `n${nextId++}`;
+    ids.set(node, id);
+  }
+  return id;
+}
+
+/**
+ * fn:lang: whether the xml:lang of a node matches a language.
+ * @param {string} language
+ * @param {Node} node
+ * @returns {boolean}
+ */
+function matchesLanguage(language, node) {
+  const xml = "http://www.w3.org/XML/1998/namespace";
+  for (let n = node; n; n = parentOf(n)) {
+    const value = n.nodeType === 1 ? n.getAttributeNS(xml, "lang") : null;
+    if (value !== null && n.hasAttributeNS(xml, "lang")) {
+      const actual = value.toLowerCase();
+      const wanted = language.toLowerCase();
+      return actual === wanted || actual.startsWith(`${wanted}-`);
+    }
+  }
+  return false;
+}
+
+/**
+ * The topmost or bottommost nodes of a set.
+ * @param {Node[]} nodes
+ * @param {object} context
+ * @param {boolean} inner - innermost (else outermost)
+ * @returns {Node[]}
+ */
+function nesting(nodes, context, inner) {
+  const set = new Set(nodes);
+  const hasAncestorIn = (node) => {
+    for (let p = parentOf(node); p; p = parentOf(p)) {
+      if (set.has(p)) return true;
+    }
+    return false;
+  };
+  const ancestors = new Set();
+  if (inner) {
+    for (const node of nodes) {
+      for (let p = parentOf(node); p; p = parentOf(p)) ancestors.add(p);
+    }
+  }
+  const kept = nodes.filter((node) =>
+    inner ? !ancestors.has(node) : !hasAncestorIn(node),
+  );
+  return context.order.sort(kept);
+}
+
+/** Function definitions. */
+export const nodeFunctions = [
+  ...nodeFunction("name", "xs:string", (node) => [
+    stringItem(node ? lexicalName(node) : ""),
+  ]),
+  ...nodeFunction("local-name", "xs:string", (node) => [
+    stringItem(node && isNamed(node) ? nodeLocalName(node) : ""),
+  ]),
+  ...nodeFunction("namespace-uri", "xs:anyURI", (node) => [
+    new AtomicValue(
+      types.anyURI,
+      node && (node.nodeType === 1 || node.nodeType === 2)
+        ? nodeNamespace(node)
+        : "",
+    ),
+  ]),
+  ...nodeFunction("node-name", "xs:QName?", (node) =>
+    node && isNamed(node)
+      ? [
+          new AtomicValue(
+            types.QName,
+            new QNameValue(
+              nodeNamespace(node),
+              nodeLocalName(node),
+              nodePrefix(node),
+            ),
+          ),
+        ]
+      : [],
+  ),
+  ...nodeFunction("root", "node()?", (node) => (node ? [rootOf(node)] : [])),
+  ...nodeFunction("has-children", "xs:boolean", (node) => [
+    booleanItem(Boolean(node) && childrenOf(node).length > 0),
+  ]),
+  ...nodeFunction("nilled", "xs:boolean?", (node) =>
+    node?.nodeType === 1 ? [booleanItem(false)] : [],
+  ),
+  ...nodeFunction("generate-id", "xs:string", (node) => [
+    stringItem(node ? generateId(node) : ""),
+  ]),
+  {
+    local: "innermost",
+    params: ["node()*"],
+    returns: "node()*",
+    impl: ([nodes], context) => nesting(nodes, context, true),
+  },
+  {
+    local: "outermost",
+    params: ["node()*"],
+    returns: "node()*",
+    impl: ([nodes], context) => nesting(nodes, context, false),
+  },
+  {
+    local: "lang",
+    params: ["xs:string?"],
+    returns: "xs:boolean",
+    focus: true,
+    impl: ([language], context) => [
+      booleanItem(
+        matchesLanguage(language[0]?.value ?? "", focusNode(context)),
+      ),
+    ],
+  },
+  {
+    local: "lang",
+    params: ["xs:string?", "node()"],
+    returns: "xs:boolean",
+    impl: ([language, [node]]) => [
+      booleanItem(matchesLanguage(language[0]?.value ?? "", node)),
+    ],
+  },
+  ...nodePathFunctions,
+];

package/src/functions/numeric.js

@@ -0,0 +1,148 @@
+/**
+ * Functions on numeric values (F&O 3.1 section 4.4): abs, ceiling, floor,
+ * round and round-half-to-even. Results have the primitive numeric type of
+ * the argument (xs:integer for integer subtypes). Decimal and integer
+ * rounding is exact; doubles (and floats, widened to doubles) are rounded
+ * through the shortest decimal that reads back as the double, so
+ * round(0.49999999999999994) is 0.
+ *
+ * @module @tradik/xslt3/functions/numeric
+ */
+
+import { AtomicValue } from "../xdm/atomic.js";
+import { Decimal } from "../xdm/decimal.js";
+import { numberToDecimal } from "../xdm/numeric.js";
+import { types } from "../xdm/types.js";
+import { define } from "./support.js";
+
+/**
+ * Rounds a decimal to `precision` fraction digits (negative: to a power of
+ * ten).
+ * @param {Decimal} value
+ * @param {number} precision
+ * @param {boolean} halfEven - Ties to even; otherwise toward +INF
+ * @returns {Decimal}
+ */
+export function roundDecimal(value, precision, halfEven) {
+  if (value.scale <= precision) return value;
+  const divisor = 10n ** BigInt(value.scale - precision);
+  let quotient = value.unscaled / divisor;
+  let remainder = value.unscaled % divisor;
+  if (remainder < 0n) {
+    quotient -= 1n;
+    remainder += divisor;
+  }
+  const twice = 2n * remainder;
+  const up =
+    twice > divisor ||
+    (twice === divisor && (!halfEven || quotient % 2n !== 0n));
+  return Decimal.of(up ? quotient + 1n : quotient, precision);
+}
+
+/**
+ * @param {AtomicValue} item
+ * @param {*} value
+ * @returns {AtomicValue} the value with the item's primitive numeric type
+ */
+function sameType(item, value) {
+  const type = typeof value === "bigint" ? types.integer : item.type.primitive;
+  return new AtomicValue(type, value);
+}
+
+/**
+ * Rounds a numeric item.
+ * @param {AtomicValue} item
+ * @param {number} precision - Already clamped to a safe range
+ * @param {boolean} halfEven
+ * @returns {AtomicValue}
+ */
+function roundItem(item, precision, halfEven) {
+  const { value } = item;
+  if (typeof value === "bigint") {
+    if (precision >= 0) return sameType(item, value);
+    return sameType(
+      item,
+      roundDecimal(Decimal.of(value), precision, halfEven).unscaled,
+    );
+  }
+  if (value instanceof Decimal) {
+    return sameType(item, roundDecimal(value, precision, halfEven));
+  }
+  if (!Number.isFinite(value) || value === 0) return sameType(item, value);
+  const isFloat = item.type.primitive === types.float;
+  // floats through their double value: xs:float("0.05") is above 0.05
+  const exact = numberToDecimal(value);
+  let rounded = Number(roundDecimal(exact, precision, halfEven).toString());
+  if (rounded === 0 && value < 0) rounded = -0;
+  return sameType(item, isFloat ? Math.fround(rounded) : rounded);
+}
+
+/** Largest precision that can change a double or decimal in practice. */
+const PRECISION_LIMIT = 10000;
+
+/**
+ * @param {Array<*>[]} args - [$arg, $precision?]
+ * @param {boolean} halfEven
+ * @returns {Array<*>}
+ */
+function roundFunction([arg, precision], halfEven) {
+  if (arg.length === 0) return [];
+  const p = precision === undefined ? 0n : precision[0].value;
+  const clamped =
+    p > BigInt(PRECISION_LIMIT)
+      ? PRECISION_LIMIT
+      : p < BigInt(-PRECISION_LIMIT)
+        ? -PRECISION_LIMIT
+        : Number(p);
+  return [roundItem(arg[0], clamped, halfEven)];
+}
+
+/**
+ * Declares a one-argument numeric function.
+ * @param {string} local
+ * @param {(value: *, item: AtomicValue) => *} apply - On the value
+ * @returns {import("./support.js").FunctionDefinition}
+ */
+const unary = (local, apply) =>
+  define(local, ["xs:numeric?"], "xs:numeric?", ([arg]) =>
+    arg.length === 0 ? [] : [sameType(arg[0], apply(arg[0].value))],
+  );
+
+/** @param {*} v @returns {*} the largest integer not above v */
+const floor = (v) =>
+  typeof v === "bigint"
+    ? v
+    : v instanceof Decimal
+      ? Decimal.of(v.floor())
+      : Math.floor(v);
+
+const N = "xs:numeric?";
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const numericFunctions = [
+  unary("abs", (v) =>
+    typeof v === "bigint"
+      ? v < 0n
+        ? -v
+        : v
+      : v instanceof Decimal
+        ? v.sign() < 0
+          ? v.neg()
+          : v
+        : Math.abs(v),
+  ),
+  unary("floor", floor),
+  unary("ceiling", (v) =>
+    typeof v === "bigint"
+      ? v
+      : v instanceof Decimal
+        ? floor(v.neg()).neg()
+        : Math.ceil(v),
+  ),
+  define("round", [N], N, (args) => roundFunction(args, false)),
+  define("round", [N, "xs:integer"], N, (args) => roundFunction(args, false)),
+  define("round-half-to-even", [N], N, (args) => roundFunction(args, true)),
+  define("round-half-to-even", [N, "xs:integer"], N, (args) =>
+    roundFunction(args, true),
+  ),
+];

package/src/functions/options.js

@@ -0,0 +1,58 @@
+/**
+ * Option maps (F&O 3.1 section 1.5, "Options"): the `$options` argument
+ * of fn:parse-json, fn:json-to-xml, fn:xml-to-json... Each known option
+ * is converted to its declared type with the function conversion rules
+ * (XPTY0004 when it cannot be), checked against its allowed values, and
+ * defaulted when absent; unknown options are ignored.
+ *
+ * @module @tradik/xslt3/functions/options
+ */
+
+import { XPathError } from "../errors.js";
+import { stringItem } from "../xpath/eval/atomics.js";
+import { coerce } from "../xpath/eval/coercion.js";
+import { sequenceTypeOf } from "../xpath/eval/functionItems.js";
+
+/**
+ * Declaration of one option.
+ * @typedef {object} OptionSpec
+ * @property {string} type - Sequence type of the value, e.g. "xs:boolean"
+ * @property {*} [default] - Value when the option is absent
+ * @property {string[]} [values] - Allowed values of a string option
+ */
+
+/**
+ * Reads an option map.
+ * @param {import("../items/map.js").XdmMap|undefined} map - The options
+ *   argument, undefined for the arity without it
+ * @param {Record<string, OptionSpec>} specs - Known options by key
+ * @param {string} invalidCode - Error code of a value outside `values`
+ *   (FOJS0005 for the JSON functions)
+ * @returns {Record<string, *>} option values by key: the JS value of
+ *   single atomic values (boolean, string), the item itself for functions,
+ *   `undefined` for absent options without default
+ * @throws {XPathError} XPTY0004 for a value of the wrong type,
+ *   `invalidCode` for a value that is not allowed
+ */
+export function readOptions(map, specs, invalidCode) {
+  const result = {};
+  for (const [key, spec] of Object.entries(specs)) {
+    const value = map?.get(stringItem(key));
+    if (value === undefined) {
+      result[key] = spec.default;
+      continue;
+    }
+    const [item] = coerce(value, sequenceTypeOf(spec.type), {
+      what: `option "${key}"`,
+    });
+    const plain = item?.value === undefined ? item : item.value;
+    if (spec.values && !spec.values.includes(plain)) {
+      throw new XPathError(
+        invalidCode,
+        `Invalid value "${plain}" of option "${key}"`,
+      );
+    }
+    result[key] = plain;
+  }
+  return result;
+}

package/src/functions/parseIetfDate.js

@@ -0,0 +1,104 @@
+/**
+ * fn:parse-ietf-date (F&O 3.1 section 9.9.1): the date formats of HTTP
+ * (RFC 822/1123, RFC 850 and asctime) to xs:dateTime, case-insensitive,
+ * with the liberal grammar of the specification.
+ *
+ * @module @tradik/xslt3/functions/parseIetfDate
+ */
+
+import { XPathError } from "../errors.js";
+import { fromLexical } from "../xdm/lexical.js";
+import { define } from "./support.js";
+
+const MONTHS = "jan feb mar apr may jun jul aug sep oct nov dec".split(" ");
+const ZONES = {
+  ut: 0,
+  utc: 0,
+  gmt: 0,
+  est: -5,
+  edt: -4,
+  cst: -6,
+  cdt: -5,
+  mst: -7,
+  mdt: -6,
+  pst: -8,
+  pdt: -7,
+};
+
+const S = "[\\t\\n\\r ]+";
+const DAY_NAME =
+  "(?:monday|tuesday|wednesday|thursday|friday|saturday|sunday|mon|tue|wed|thu|fri|sat|sun)";
+const MONTH = `(${MONTHS.join("|")})`;
+const DSEP = `(?:${S}|(?:${S})?-(?:${S})?)`;
+const TZ_NAME = "(?:utc|ut|gmt|est|edt|cst|cdt|mst|mdt|pst|pdt)";
+const TZ_OFFSET = `([+-])(\\d\\d?:(?:\\d\\d)?|\\d{1,4})(?:(?:${S})?\\((?:${S})?${TZ_NAME}(?:${S})?\\))?`;
+const TIME = `(\\d\\d?):(\\d\\d)(?::(\\d\\d(?:\\.\\d+)?))?(?:(?:${S})?(?:(${TZ_NAME})|${TZ_OFFSET}))?`;
+const YEAR = "(\\d\\d(?:\\d\\d)?)";
+const DATE_SPEC = `(\\d\\d?)${DSEP}${MONTH}${DSEP}${YEAR}${S}${TIME}`;
+const ASC_TIME = `${MONTH}${DSEP}(\\d\\d?)${S}${TIME}${S}${YEAR}`;
+const INPUT = new RegExp(
+  `^(?:${S})?(?:${DAY_NAME},?${S})?(?:${DATE_SPEC}|${ASC_TIME})(?:${S})?$`,
+  "i",
+);
+
+/** @param {string|number} n @param {number} width @returns {string} */
+const pad = (n, width) => String(n).padStart(width, "0");
+
+/**
+ * The timezone of a parsed date: offset, else zone name, else UTC.
+ * @param {string|undefined} name
+ * @param {string|undefined} sign
+ * @param {string|undefined} offset - "H", "HH", "HMM", "HHMM" or "H:MM"
+ * @returns {string} "Z" or "+HH:MM"
+ */
+function timezone(name, sign, offset) {
+  if (offset !== undefined) {
+    const [hours, minutes = "00"] = offset.includes(":")
+      ? offset.split(":")
+      : offset.length > 2
+        ? [offset.slice(0, -2), offset.slice(-2)]
+        : [offset];
+    return `${sign}${pad(hours, 2)}:${pad(minutes || "00", 2)}`;
+  }
+  const hours = ZONES[name?.toLowerCase()] ?? 0;
+  return hours === 0 ? "Z" : `-${pad(-hours, 2)}:00`;
+}
+
+/**
+ * Parses an IETF date.
+ * @param {string} text
+ * @returns {import("../xdm/atomic.js").AtomicValue} an xs:dateTime
+ * @throws {XPathError} FORG0010 when the text does not match the grammar
+ *   or is not a valid date and time
+ */
+export function parseIetfDate(text) {
+  const match = INPUT.exec(text);
+  if (!match) throw new XPathError("FORG0010", `Invalid IETF date "${text}"`);
+  // groups: datespec 1-9 (day, month, year, time 6), asctime 10-18
+  // (month, day, time 6, year)
+  const spec = match[1] !== undefined;
+  const g = spec ? match.slice(1, 10) : match.slice(10, 19);
+  const [day, month, year] = spec ? g : [g[1], g[0], g[8]];
+  const [hours, minutes, seconds = "00", name, sign, offset] = spec
+    ? g.slice(3, 9)
+    : g.slice(2, 8);
+  const fullYear = year.length === 2 ? `19${year}` : year;
+  const lexical =
+    `${fullYear}-${pad(MONTHS.indexOf(month.toLowerCase()) + 1, 2)}-` +
+    `${pad(day, 2)}T${pad(hours, 2)}:${minutes}:${pad(seconds, 2)}` +
+    timezone(name, sign, offset);
+  try {
+    return fromLexical("xs:dateTime", lexical);
+  } catch (error) {
+    throw new XPathError("FORG0010", `Invalid IETF date "${text}"`, {
+      cause: error,
+    });
+  }
+}
+
+/** Function definitions. */
+export const parseIetfDateFunctions = [
+  define("parse-ietf-date", ["xs:string?"], "xs:dateTime?", ([value]) =>
+    value.length ? [parseIetfDate(value[0].value)] : [],
+  ),
+];

package/src/functions/parseXml.js

@@ -0,0 +1,77 @@
+/**
+ * fn:parse-xml and fn:parse-xml-fragment (F&O 3.1 sections 14.6.2 and
+ * 14.6.3), through the dynamic context hook `parseXml` (see
+ * xpath/eval/resources.js). The documents have the static base URI as
+ * base URI and no document URI; a fragment is a document fragment (a
+ * document node that may hold several elements and text).
+ *
+ * @module @tradik/xslt3/functions/parseXml
+ */
+
+import { XPathError } from "../errors.js";
+import { setBaseUri } from "./baseUris.js";
+import { define } from "./support.js";
+
+/** A text declaration: optional version, required encoding. */
+const TEXT_DECLARATION =
+  /^<\?xml(?:\s+version\s*=\s*(["'])1\.\d+\1)?\s+encoding\s*=\s*(["'])[A-Za-z][\w.-]*\2\s*\?>/;
+
+/**
+ * Parses with the hook, reporting failures as FODC0006.
+ * @param {string} text
+ * @param {object} context
+ * @returns {Document}
+ */
+function parse(text, context) {
+  try {
+    return context.parseXml(text, context.staticBaseUri);
+  } catch (error) {
+    if (error.code === "FODC0006") throw error;
+    throw new XPathError("FODC0006", "The string is not well-formed XML", {
+      cause: error,
+    });
+  }
+}
+
+/**
+ * fn:parse-xml-fragment of a string: the content of an external parsed
+ * entity, parsed inside a wrapper element.
+ * @param {string} text
+ * @param {object} context
+ * @returns {DocumentFragment}
+ */
+function parseFragment(text, context) {
+  let content = text;
+  if (/^<\?xml[\s?]/.test(text)) {
+    const declaration = TEXT_DECLARATION.exec(text);
+    if (!declaration) {
+      throw new XPathError("FODC0006", "Invalid text declaration");
+    }
+    content = text.slice(declaration[0].length);
+  }
+  const document = parse(`<fragment>${content}</fragment>`, context);
+  const fragment = document.createDocumentFragment();
+  const wrapper = document.documentElement;
+  while (wrapper.firstChild) fragment.appendChild(wrapper.firstChild);
+  return setBaseUri(fragment, context.staticBaseUri);
+}
+
+/** Function definitions. */
+export const parseXmlFunctions = [
+  define(
+    "parse-xml",
+    ["xs:string?"],
+    "document-node(element(*))?",
+    ([arg], context) =>
+      arg.length
+        ? [setBaseUri(parse(arg[0].value, context), context.staticBaseUri)]
+        : [],
+  ),
+  define(
+    "parse-xml-fragment",
+    ["xs:string?"],
+    "document-node()?",
+    ([arg], context) =>
+      arg.length ? [parseFragment(arg[0].value, context)] : [],
+  ),
+];

package/src/functions/qnames.js

@@ -0,0 +1,68 @@
+/**
+ * Functions on QNames that need no node (F&O 3.1 section 10.2): QName,
+ * prefix-from-QName, local-name-from-QName and namespace-uri-from-QName.
+ * fn:resolve-QName and fn:namespace-uri-for-prefix need in-scope
+ * namespaces of an element and belong to the evaluator.
+ *
+ * @module @tradik/xslt3/functions/qnames
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue } from "../xdm/atomic.js";
+import { QNameValue } from "../xdm/qname.js";
+import { namePatterns, types } from "../xdm/types.js";
+import { define } from "./support.js";
+
+/**
+ * fn:QName on strings.
+ * @param {string} uri - "" for no namespace
+ * @param {string} lexical - "prefix:local" or "local"
+ * @returns {QNameValue}
+ * @throws {XPathError} FOCA0002 for an invalid lexical QName or a prefix
+ *   without namespace
+ */
+export function makeQName(uri, lexical) {
+  const parts = lexical.split(":");
+  if (
+    parts.length > 2 ||
+    !parts.every((part) => namePatterns.ncName.test(part)) ||
+    (parts.length === 2 && uri === "")
+  ) {
+    throw new XPathError("FOCA0002", `Invalid QName "${lexical}"`);
+  }
+  const [prefix, local] = parts.length === 2 ? parts : ["", parts[0]];
+  return new QNameValue(uri, local, prefix);
+}
+
+/**
+ * Declares an accessor of an optional xs:QName.
+ * @param {string} local
+ * @param {string} returns
+ * @param {(q: QNameValue) => AtomicValue|null} access
+ * @returns {import("./support.js").FunctionDefinition}
+ */
+const accessor = (local, returns, access) =>
+  define(local, ["xs:QName?"], returns, ([q]) => {
+    const result = q.length === 0 ? null : access(q[0].value);
+    return result === null ? [] : [result];
+  });
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const qnameFunctions = [
+  define("QName", ["xs:string?", "xs:string"], "xs:QName", ([uri, [q]]) => [
+    new AtomicValue(types.QName, makeQName(uri[0]?.value ?? "", q.value)),
+  ]),
+  accessor("prefix-from-QName", "xs:NCName?", (q) =>
+    q.prefix === "" ? null : new AtomicValue(types.NCName, q.prefix),
+  ),
+  accessor(
+    "local-name-from-QName",
+    "xs:NCName?",
+    (q) => new AtomicValue(types.NCName, q.localName),
+  ),
+  accessor(
+    "namespace-uri-from-QName",
+    "xs:anyURI?",
+    (q) => new AtomicValue(types.anyURI, q.namespaceURI),
+  ),
+];