@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/format/numberWords.js

@@ -0,0 +1,155 @@
+/**
+ * Numbering in words and other systems for format-integer and
+ * format-date/time (F&O 3.1 sections 4.6.1 and 9.8.4): English cardinal
+ * and ordinal words, ordinal suffixes, Roman numerals and alphabetic
+ * sequences.
+ *
+ * @module @tradik/xslt3/functions/format/numberWords
+ */
+
+const ONES = (
+  "zero one two three four five six seven eight nine ten eleven twelve " +
+  "thirteen fourteen fifteen sixteen seventeen eighteen nineteen"
+).split(" ");
+const TENS = "  twenty thirty forty fifty sixty seventy eighty ninety".split(
+  " ",
+);
+const SCALES = [
+  [10n ** 18n, "quintillion"],
+  [10n ** 15n, "quadrillion"],
+  [10n ** 12n, "trillion"],
+  [10n ** 9n, "billion"],
+  [10n ** 6n, "million"],
+  [1000n, "thousand"],
+];
+
+/**
+ * English cardinal words, e.g. "one hundred and twenty-three".
+ * @param {bigint} n - Non-negative
+ * @returns {string}
+ */
+export function cardinalWords(n) {
+  if (n < 20n) return ONES[Number(n)];
+  if (n < 100n) {
+    const units = n % 10n;
+    return TENS[Number(n / 10n)] + (units ? `-${ONES[Number(units)]}` : "");
+  }
+  if (n < 1000n) {
+    const rest = n % 100n;
+    return (
+      `${ONES[Number(n / 100n)]} hundred` +
+      (rest ? ` and ${cardinalWords(rest)}` : "")
+    );
+  }
+  const [scale, name] = SCALES.find(([s]) => n >= s) ?? SCALES[0];
+  const rest = n % scale;
+  const joiner = rest === 0n ? "" : rest < 100n ? " and " : " ";
+  return (
+    `${cardinalWords(n / scale)} ${name}` +
+    joiner +
+    (rest ? cardinalWords(rest) : "")
+  );
+}
+
+const IRREGULAR_ORDINALS = {
+  one: "first",
+  two: "second",
+  three: "third",
+  five: "fifth",
+  eight: "eighth",
+  nine: "ninth",
+  twelve: "twelfth",
+};
+
+/**
+ * English ordinal words, e.g. "twenty-first".
+ * @param {bigint} n - Non-negative
+ * @returns {string}
+ */
+export function ordinalWords(n) {
+  const words = cardinalWords(n);
+  const [, head, last] = /^(.*?)([a-z]+)$/.exec(words);
+  const ordinal =
+    IRREGULAR_ORDINALS[last] ??
+    (last.endsWith("y") ? `${last.slice(0, -1)}ieth` : `${last}th`);
+  return head + ordinal;
+}
+
+/**
+ * English ordinal suffix of a number: "st", "nd", "rd" or "th".
+ * @param {bigint} n - Non-negative
+ * @returns {string}
+ */
+export function ordinalSuffix(n) {
+  const lastTwo = n % 100n;
+  if (lastTwo >= 11n && lastTwo <= 13n) return "th";
+  return ["th", "st", "nd", "rd"][Number(n % 10n)] ?? "th";
+}
+
+const ROMAN = [
+  [1000n, "m"],
+  [900n, "cm"],
+  [500n, "d"],
+  [400n, "cd"],
+  [100n, "c"],
+  [90n, "xc"],
+  [50n, "l"],
+  [40n, "xl"],
+  [10n, "x"],
+  [9n, "ix"],
+  [5n, "v"],
+  [4n, "iv"],
+  [1n, "i"],
+];
+
+/** Largest number written in Roman numerals; larger ones use digits. */
+export const MAX_ROMAN = 4999n;
+
+/**
+ * Lower-case Roman numerals.
+ * @param {bigint} n - 1 to {@link MAX_ROMAN}
+ * @returns {string}
+ */
+export function roman(n) {
+  let result = "";
+  let rest = n;
+  for (const [value, letters] of ROMAN) {
+    while (rest >= value) {
+      result += letters;
+      rest -= value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Alphabetic numbering a, b, ..., z, aa, ab, ... (bijective base 26).
+ * @param {bigint} n - Positive
+ * @param {string} first - "a" or "A"
+ * @returns {string}
+ */
+export function alphabetic(n, first) {
+  const base = first.codePointAt(0);
+  let result = "";
+  for (let rest = n; rest > 0n; rest = (rest - 1n) / 26n) {
+    result = String.fromCodePoint(base + Number((rest - 1n) % 26n)) + result;
+  }
+  return result;
+}
+
+/**
+ * Applies the case of a word format token.
+ * @param {string} words - Lower-case words
+ * @param {string} token - "w", "W" or "Ww"
+ * @returns {string}
+ */
+export function caseWords(words, token) {
+  if (token === "W") return words.toUpperCase();
+  if (token === "Ww") {
+    // title case, with "and" kept lower-case as in the F&O examples
+    return words.replace(/(?<!\p{L})(?!and(?!\p{L}))\p{Ll}/gu, (c) =>
+      c.toUpperCase(),
+    );
+  }
+  return words;
+}

package/src/functions/format/place.js

@@ -0,0 +1,74 @@
+/**
+ * The $place argument of the format-dateTime family (F&O 3.1 section
+ * 9.8.4.8) given as an IANA timezone name: the value is adjusted to the
+ * offset of that timezone at that instant (daylight saving included), and
+ * the timezone gets its conventional abbreviation for [ZN]. Uses the
+ * timezone database of `Intl.DateTimeFormat`. Country codes are ignored.
+ *
+ * @module @tradik/xslt3/functions/format/place
+ */
+
+import { AtomicValue } from "../../xdm/atomic.js";
+import { types } from "../../xdm/types.js";
+import { adjustToTimezone } from "../datetime.js";
+
+/**
+ * The name of the timezone of an instant in a locale's style.
+ * @param {string} timeZone
+ * @param {number} instant - Milliseconds since the epoch
+ * @param {string} locale
+ * @param {string} style - "longOffset" or "short"
+ * @returns {string}
+ */
+function zoneName(timeZone, instant, locale, style) {
+  return new Intl.DateTimeFormat(locale, { timeZone, timeZoneName: style })
+    .formatToParts(instant)
+    .find((part) => part.type === "timeZoneName").value;
+}
+
+/**
+ * Adjusts a date or dateTime with a timezone to the timezone of a place.
+ * @param {string} kind - "dateTime", "date" or "time"
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @param {string|null|undefined} place
+ * @returns {{value: import("../../xdm/datetime.js").DateTimeValue,
+ *   zone: string|null}} the value to format and the timezone abbreviation
+ *   (null when the place is not a known IANA name or does not apply)
+ */
+export function applyPlace(kind, value, place) {
+  const timeZone = place?.trim() ?? "";
+  if (!timeZone.includes("/") || kind === "time" || value.timezone === null) {
+    return { value, zone: null };
+  }
+  const instant =
+    Date.UTC(
+      value.year,
+      value.month - 1,
+      value.day,
+      value.hour ?? 0,
+      value.minute ?? 0,
+    ) -
+    value.timezone * 60000;
+  let offsetName;
+  let zone;
+  try {
+    offsetName = zoneName(timeZone, instant, "en-US", "longOffset");
+    // American names (EST) first, then British ones (CET, BST)
+    zone = ["en-US", "en-GB"]
+      .map((locale) => zoneName(timeZone, instant, locale, "short"))
+      .find((name) => !/^GMT[+-]/.test(name));
+  } catch {
+    return { value, zone: null };
+  }
+  const [, sign, hours, minutes] = /^GMT(?:([+-])(\d\d):(\d\d))?$/.exec(
+    offsetName,
+  );
+  const offset = sign
+    ? (sign === "-" ? -1 : 1) * (Number(hours) * 60 + Number(minutes))
+    : 0;
+  const adjusted = adjustToTimezone(
+    new AtomicValue(types[kind], value),
+    offset,
+  );
+  return { value: adjusted.value, zone: zone ?? null };
+}

package/src/functions/format/timezoneFormat.js

@@ -0,0 +1,89 @@
+/**
+ * Timezone components [Z] and [z] of the format-dateTime family (F&O 3.1
+ * section 9.8.4.6): numeric offsets with one to four digits and optional
+ * separator, "t" for Z at UTC, military letters ([ZZ]) and a few North
+ * American and UTC names ([ZN]).
+ *
+ * @module @tradik/xslt3/functions/format/timezoneFormat
+ */
+
+import { zeroOf } from "./digitPattern.js";
+
+const MILITARY = "YXWVUTSRQPONZABCDEFGHIKLM";
+const NAMES = new Map([
+  [0, "GMT"],
+  [-300, "EST"],
+  [-360, "CST"],
+  [-420, "MST"],
+  [-480, "PST"],
+  [-600, "HST"],
+]);
+
+/**
+ * Formats an offset with a numeric presentation modifier such as "01:01",
+ * "0", "0000".
+ * @param {number} offset - Minutes
+ * @param {string} token
+ * @param {boolean} zuluAtZero - The "t" modifier: Z for UTC
+ * @returns {string}
+ */
+function numericOffset(offset, token, zuluAtZero) {
+  if (zuluAtZero && offset === 0) return "Z";
+  const chars = Array.from(token);
+  const digitChars = chars.filter((c) => /\p{Nd}/u.test(c));
+  const zero = digitChars.length ? zeroOf(digitChars[0]) : 0x30;
+  const separator = chars.find((c) => !/[\p{Nd}#]/u.test(c));
+  const hours = Math.floor(Math.abs(offset) / 60);
+  const minutes = Math.abs(offset) % 60;
+  const pad = (n, width) => String(n).padStart(width, "0");
+  let text;
+  if (separator !== undefined) {
+    const hourDigits = chars.indexOf(separator);
+    text = pad(hours, hourDigits) + separator + pad(minutes, 2);
+  } else if (digitChars.length >= 3) {
+    text = pad(hours, digitChars.length - 2) + pad(minutes, 2);
+  } else {
+    text =
+      pad(hours, digitChars.length) + (minutes ? `:${pad(minutes, 2)}` : "");
+  }
+  const digits = text.replace(/[0-9]/g, (d) =>
+    String.fromCodePoint(zero + Number(d)),
+  );
+  return (offset < 0 ? "-" : "+") + digits;
+}
+
+/**
+ * The numeric format of an offset without presentation modifier: "01:01",
+ * or only the hours (minutes when not zero) when a maximum width below
+ * five leaves no room for "hh:mm", as XSLT 2.0 erratum E29 has it.
+ * @param {import("./datePicture.js").Marker} marker
+ * @returns {string}
+ */
+function defaultToken(marker) {
+  if (marker.maxWidth === null || marker.maxWidth >= 5) {
+    return "01:01";
+  }
+  return "0".repeat(Math.min(2, Math.max(1, marker.minWidth ?? 1)));
+}
+
+/**
+ * Formats a timezone component.
+ * @param {number|null} timezone - Minutes, null when absent
+ * @param {import("./datePicture.js").Marker} marker - Component Z or z
+ * @param {string|null} [zone] - Name of the timezone, from the place
+ * @returns {string}
+ */
+export function formatTimezone(timezone, marker, zone = null) {
+  const token = marker.first ?? defaultToken(marker);
+  if (timezone === null) return token === "Z" ? "J" : "";
+  const gmt = marker.component === "z" ? "GMT" : "";
+  if (token === "Z" && timezone % 60 === 0 && Math.abs(timezone) <= 720) {
+    return MILITARY[timezone / 60 + 12];
+  }
+  if (/^(N|n|Nn)$/.test(token) && (zone || NAMES.has(timezone))) {
+    return zone ?? NAMES.get(timezone);
+  }
+  const numeric = /^[\p{Nd}#]/u.test(token) ? token : "01:01";
+  const text = gmt + numericOffset(timezone, numeric, marker.second === "t");
+  return marker.minWidth === null ? text : text.padEnd(marker.minWidth, " ");
+}

package/src/functions/higherOrder.js

@@ -0,0 +1,106 @@
+/**
+ * Higher-order functions (F&O 3.1 sections 16 and 17.2): functions on
+ * function items, and the functions that take function items.
+ *
+ * @module @tradik/xslt3/functions/higherOrder
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue } from "../xdm/atomic.js";
+import { types } from "../xdm/types.js";
+import { integerItem } from "../xpath/eval/atomics.js";
+import { sortFunctions } from "./sort.js";
+
+/** Function definitions. */
+export const higherOrderFunctions = [
+  {
+    local: "for-each",
+    params: ["item()*", "function(item()) as item()*"],
+    returns: "item()*",
+    impl: ([sequence, [f]]) => sequence.flatMap((item) => f.invoke([[item]])),
+  },
+  {
+    local: "filter",
+    params: ["item()*", "function(item()) as xs:boolean"],
+    returns: "item()*",
+    impl: ([sequence, [f]]) =>
+      sequence.filter((item) => f.invoke([[item]])[0].value),
+  },
+  {
+    local: "fold-left",
+    params: ["item()*", "item()*", "function(item()*, item()) as item()*"],
+    returns: "item()*",
+    impl: ([sequence, zero, [f]]) =>
+      sequence.reduce((acc, item) => f.invoke([acc, [item]]), zero),
+  },
+  {
+    local: "fold-right",
+    params: ["item()*", "item()*", "function(item(), item()*) as item()*"],
+    returns: "item()*",
+    impl: ([sequence, zero, [f]]) =>
+      sequence.reduceRight((acc, item) => f.invoke([[item], acc]), zero),
+  },
+  {
+    local: "for-each-pair",
+    params: ["item()*", "item()*", "function(item(), item()) as item()*"],
+    returns: "item()*",
+    impl: ([a, b, [f]]) => {
+      const result = [];
+      const length = Math.min(a.length, b.length);
+      for (let i = 0; i < length; i++) {
+        result.push(...f.invoke([[a[i]], [b[i]]]));
+      }
+      return result;
+    },
+  },
+  {
+    local: "apply",
+    params: ["function(*)", "array(*)"],
+    returns: "item()*",
+    impl: ([[f], [array]]) => {
+      if (f.arity !== array.size) {
+        throw new XPathError(
+          "FOAP0001",
+          `The function has arity ${f.arity}, the array ${array.size} members`,
+        );
+      }
+      return f.invoke(array.members);
+    },
+  },
+  {
+    local: "function-name",
+    params: ["function(*)"],
+    returns: "xs:QName?",
+    impl: ([[f]]) => (f.name ? [new AtomicValue(types.QName, f.name)] : []),
+  },
+  {
+    local: "function-arity",
+    params: ["function(*)"],
+    returns: "xs:integer",
+    impl: ([[f]]) => [integerItem(f.arity)],
+  },
+  {
+    local: "function-lookup",
+    params: ["xs:QName", "xs:integer"],
+    returns: "function(*)?",
+    focus: true,
+    impl: ([[name], [arity]], context) => {
+      const ctx = {
+        item: context.contextItem,
+        position: context.position,
+        size: context.size,
+        env: null,
+        dyn: context,
+      };
+      const { namespaceURI, localName } = name.value;
+      const f = context.lookupFunction(
+        namespaceURI,
+        localName,
+        Number(arity.value),
+        ctx,
+      );
+      return f ? [f] : [];
+    },
+  },
+  ...sortFunctions,
+];

package/src/functions/ids.js

@@ -0,0 +1,127 @@
+/**
+ * fn:id, fn:element-with-id and fn:idref (F&O 3.1 sections 14.5.2 to
+ * 14.5.4). Without a schema, IDs are `xml:id` attributes and attributes
+ * declared ID in the internal DTD subset; IDREF/IDREFS attributes are
+ * those declared so in the internal DTD subset (see attributeTypes.js).
+ * Elements are never IDs themselves (that needs a schema), so
+ * fn:element-with-id finds the same elements as fn:id.
+ *
+ * @module @tradik/xslt3/functions/ids
+ */
+
+import { XPathError } from "../errors.js";
+import { namePatterns } from "../xdm/types.js";
+import { attributesOf, rootOf } from "../xpath/eval/domNodes.js";
+import { attributeType } from "./attributeTypes.js";
+import { focusNode } from "./focus.js";
+import { define } from "./support.js";
+
+/** @param {string} s @returns {string[]} whitespace-separated tokens */
+const tokens = (s) => s.split(/[\t\n\r ]+/).filter(Boolean);
+
+/**
+ * The document node a search starts from.
+ * @param {Node} node
+ * @returns {Node}
+ * @throws {XPathError} FODC0001 when the tree is not rooted at a document
+ */
+function documentOf(node) {
+  const root = rootOf(node);
+  if (root.nodeType !== 9 && root.nodeType !== 11) {
+    throw new XPathError("FODC0001", "The tree is not rooted at a document");
+  }
+  return root;
+}
+
+/**
+ * The elements of a tree in document order.
+ * @param {Node} root
+ * @returns {Generator<Element>}
+ */
+function* elements(root) {
+  const stack = [root.firstChild];
+  while (stack.length) {
+    const node = stack.pop();
+    if (!node) continue;
+    stack.push(node.nextSibling);
+    if (node.nodeType === 1) {
+      yield node;
+      stack.push(node.firstChild);
+    }
+  }
+}
+
+/**
+ * fn:id: the elements with an ID attribute equal to one of the tokens,
+ * the first in document order for each value.
+ * @param {Array} args - [$arg, $node]
+ * @returns {Element[]}
+ */
+function findIds([values, [node]]) {
+  const wanted = new Set(values.flatMap((v) => tokens(v.value)));
+  const result = [];
+  for (const element of elements(documentOf(node))) {
+    if (wanted.size === 0) break;
+    for (const attribute of attributesOf(element)) {
+      const value = tokens(attribute.value).join(" ");
+      if (wanted.has(value) && attributeType(attribute, element) === "ID") {
+        wanted.delete(value);
+        if (result.at(-1) !== element) result.push(element);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * fn:idref: the IDREF and IDREFS attributes that refer to one of the IDs.
+ * @param {Array} args - [$arg, $node]
+ * @returns {Attr[]}
+ */
+function findIdrefs([values, [node]]) {
+  const wanted = new Set(
+    values
+      .map((v) => tokens(v.value).join(" "))
+      .filter((v) => namePatterns.ncName.test(v)),
+  );
+  const result = [];
+  if (wanted.size === 0) return result;
+  for (const element of elements(documentOf(node))) {
+    for (const attribute of attributesOf(element)) {
+      const type = attributeType(attribute, element);
+      if (
+        (type === "IDREF" || type === "IDREFS") &&
+        tokens(attribute.value).some((t) => wanted.has(t))
+      ) {
+        result.push(attribute);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Definitions of a function in its two arities (the context node, else
+ * the given node, locates the document).
+ * @param {string} local
+ * @param {string} returns
+ * @param {(args: Array) => Node[]} impl
+ * @returns {object[]}
+ */
+const family = (local, returns, impl) => [
+  define(
+    local,
+    ["xs:string*"],
+    returns,
+    ([values], context) => impl([values, [focusNode(context)]]),
+    { focus: true },
+  ),
+  define(local, ["xs:string*", "node()"], returns, impl),
+];
+
+/** Function definitions. */
+export const idFunctions = [
+  ...family("id", "element()*", findIds),
+  ...family("element-with-id", "element()*", findIds),
+  ...family("idref", "node()*", findIdrefs),
+];

package/src/functions/json/index.js

@@ -0,0 +1,17 @@
+/**
+ * The JSON functions of F&O 3.1 section 17.5: fn:parse-json, fn:json-doc,
+ * fn:json-to-xml and fn:xml-to-json.
+ *
+ * @module @tradik/xslt3/functions/json
+ */
+
+import { jsonToXmlFunctions } from "./jsonToXml.js";
+import { parseJsonFunctions } from "./parseJson.js";
+import { xmlToJsonFunctions } from "./xmlToJson.js";
+
+/** Function definitions. */
+export const jsonFunctions = [
+  ...parseJsonFunctions,
+  ...jsonToXmlFunctions,
+  ...xmlToJsonFunctions,
+];

package/src/functions/json/jsonChars.js

@@ -0,0 +1,110 @@
+/**
+ * The characters of JSON strings, with the escape sequences they were
+ * written with (fn:parse-json, fn:json-to-xml and the escaped strings of
+ * fn:xml-to-json).
+ *
+ * @module @tradik/xslt3/functions/json/jsonChars
+ */
+
+import { XPathError } from "../../errors.js";
+
+/**
+ * A character of a JSON string: its codepoint and, when it was written
+ * as an escape sequence, the sequence ("\\n", "\\uD834").
+ * @typedef {{cp: number, escape?: string}} JsonChar
+ */
+
+const SIMPLE_ESCAPES = {
+  '"': 0x22,
+  "\\": 0x5c,
+  "/": 0x2f,
+  b: 0x08,
+  f: 0x0c,
+  n: 0x0a,
+  r: 0x0d,
+  t: 0x09,
+};
+const HEX4 = /[0-9A-Fa-f]{4}/y;
+
+/**
+ * Reads the characters of a JSON string body.
+ * @param {string} text
+ * @param {number} start - Offset after the opening quote
+ * @param {(message: string) => never} fail - Raises the error
+ * @param {boolean} [quoted=true] - Ends at an unescaped quote, which must
+ *   come, and rejects control characters; else reads to the end
+ * @returns {{chars: JsonChar[], end: number}} the characters and the
+ *   offset of the closing quote (of the end)
+ */
+export function scanChars(text, start, fail, quoted = true) {
+  const chars = [];
+  let pos = start;
+  for (;;) {
+    const cp = text.codePointAt(pos);
+    if (cp === undefined) {
+      if (quoted) fail("unterminated string");
+      break;
+    }
+    if (quoted && cp === 0x22) break;
+    if (quoted && cp < 0x20) fail("control character in a string");
+    if (cp !== 0x5c) {
+      chars.push({ cp });
+      pos += cp > 0xffff ? 2 : 1;
+      continue;
+    }
+    const char = text[pos + 1];
+    if (char === "u") {
+      HEX4.lastIndex = pos + 2;
+      if (!HEX4.test(text)) fail("invalid \\u escape");
+      const escape = text.slice(pos, pos + 6);
+      chars.push({ cp: parseInt(escape.slice(2), 16), escape });
+      pos += 6;
+    } else if (char !== undefined && Object.hasOwn(SIMPLE_ESCAPES, char)) {
+      chars.push({ cp: SIMPLE_ESCAPES[char], escape: `\\${char}` });
+      pos += 2;
+    } else {
+      fail(`invalid escape \\${char ?? ""}`);
+    }
+  }
+  return { chars: pairSurrogates(chars), end: pos };
+}
+
+/**
+ * The characters of a string that holds JSON escape sequences (the
+ * content of an fn:xml-to-json string or key marked as escaped).
+ * @param {string} text
+ * @returns {JsonChar[]}
+ * @throws {XPathError} FOJS0007 for an invalid escape sequence
+ */
+export function unescapeJsonChars(text) {
+  const fail = (message) => {
+    throw new XPathError("FOJS0007", `Invalid JSON escape: ${message}`);
+  };
+  return scanChars(text, 0, fail, false).chars;
+}
+
+/**
+ * Joins escaped surrogate pairs (\uD834\uDD1E) into one character.
+ * @param {JsonChar[]} chars
+ * @returns {JsonChar[]}
+ */
+function pairSurrogates(chars) {
+  const result = [];
+  for (let i = 0; i < chars.length; i++) {
+    const high = chars[i];
+    const low = chars[i + 1];
+    if (
+      high.cp >= 0xd800 &&
+      high.cp <= 0xdbff &&
+      low?.cp >= 0xdc00 &&
+      low.cp <= 0xdfff
+    ) {
+      const cp = (high.cp - 0xd800) * 0x400 + (low.cp - 0xdc00) + 0x10000;
+      result.push({ cp, escape: `${high.escape ?? ""}${low.escape ?? ""}` });
+      i++;
+    } else {
+      result.push(high);
+    }
+  }
+  return result;
+}