@tradik/xslt3 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, spagu (tradik) and the XSLT-Processor contributors (see CONTRIBUTORS.md)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @tradik/xslt3
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@tradik/xslt3.svg)](https://www.npmjs.com/package/@tradik/xslt3)
+[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22.8-brightgreen.svg)](https://nodejs.org/)
+
+XSLT 3.0 and XPath 3.1 in JavaScript, with no runtime dependencies. It also
+runs XSLT 2.0 stylesheets, and 1.0 ones in backwards-compatible mode, in
+Node.js and in browsers, on any DOM (the browser's, jsdom, @xmldom/xmldom).
+
+| W3C test suite | Applicable tests | Passing |
+|---|---:|---:|
+| qt3tests (XPath 3.1, functions and operators) | 21,787 | 99.9% |
+| xslt30-test (XSLT 3.0 and 2.0) | 7,914 | 98.2% |
+
+Schema awareness and streaming are not supported (stylesheets that ask for
+streaming run without it).
+
+## Install
+
+```sh
+npm install @tradik/xslt3
+```
+
+## XSLT 3.0
+
+```js
+import { compileStylesheet, serialize } from "@tradik/xslt3";
+
+const parseXml = (text) =>
+  new DOMParser().parseFromString(text, "application/xml");
+
+const stylesheet = compileStylesheet(
+  `<xsl:stylesheet version="3.0" expand-text="yes"
+       xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+     <xsl:output method="html" html-version="5"/>
+     <xsl:template match="orders">
+       <ul>
+         <xsl:for-each-group select="order" group-by="@city">
+           <xsl:sort select="current-grouping-key()"/>
+           <li>{current-grouping-key()}: {sum(current-group()/@total)}</li>
+         </xsl:for-each-group>
+       </ul>
+     </xsl:template>
+   </xsl:stylesheet>`,
+  { parseXml },
+);
+
+const result = stylesheet.transform({ source: parseXml(ordersXml) });
+serialize([result.principal].flat(), result.output);
+// <ul><li>Gdańsk: 80</li><li>Kraków: 162.75</li></ul>
+```
+
+`transform()` returns the principal result, the `xsl:result-document`
+outputs (a `Map` by URI), the `xsl:message` output and the `xsl:output`
+parameters. An `XSLTProcessor` class with the browser's method names is also
+exported.
+
+## XPath 3.1
+
+```js
+import { compileXPath, evaluateXPath } from "@tradik/xslt3";
+
+evaluateXPath("sum((1, 2, 3)) * 2", null); // [xs:integer 12]
+
+const query = compileXPath("//item[@price > $min]/@id ! string()", {
+  variables: ["min"],
+});
+query.evaluate(document, { variables: { min: 10 } });
+```
+
+## Through the XSLT 1.0 package
+
+[@tradik/xslt-processor](https://www.npmjs.com/package/@tradik/xslt-processor),
+the browser `XSLTProcessor` with Chrome's XSLT 1.0 behaviour, hands
+stylesheets that declare version 2.0 or 3.0 to this package when you opt in:
+
+```js
+const processor = new XSLTProcessor({ xsltVersion: "auto" });
+await processor.importStylesheetAsync(stylesheet);
+```
+
+## Security
+
+Expressions and stylesheets read nothing outside the data you pass unless you
+allow it: `doc()` needs a `documentLoader`, `unparsed-text()` and `json-doc()`
+a `textLoader`, `collection()` a `collections` option. `xsl:evaluate` can be
+switched off for untrusted input with `transform({ dynamicEvaluation: false })`.
+
+## Documentation
+
+- [Design, options and results](https://github.com/spagu/XSLT-Processor/blob/main/docs/XSLT3.md)
+- [Benchmarks](https://github.com/spagu/XSLT-Processor/blob/main/docs/BENCHMARKS.md)
+- [Playground](https://xslt-processor.tradik.com/playground/?mode=xslt3) (XSLT 3.0 and XPath 3.1 in the browser)
+- [Changelog](https://github.com/spagu/XSLT-Processor/blob/main/CHANGELOG.md)
+
+## License
+
+BSD-3-Clause, see [LICENSE.md](LICENSE.md).

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@tradik/xslt3",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "XSLT 3.0 and XPath 3.1 in JavaScript: also runs XSLT 2.0 stylesheets and 1.0 ones in backwards-compatible mode, with no runtime dependencies",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-test-coverage --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=96 --test-coverage-exclude=\"**/*.test.js\" \"src/**/*.test.js\""
+  },
+  "engines": {
+    "node": ">=22.8.0"
+  },
+  "license": "BSD-3-Clause",
+  "author": "tradik",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/spagu/XSLT-Processor.git",
+    "directory": "packages/xslt3"
+  },
+  "homepage": "https://xslt-processor.tradik.com/",
+  "bugs": {
+    "url": "https://github.com/spagu/XSLT-Processor/issues"
+  },
+  "keywords": [
+    "xslt",
+    "xslt3",
+    "xslt2",
+    "xpath",
+    "xpath3",
+    "xml",
+    "json",
+    "transform"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Errors of the XPath, XSLT and F&O specifications, identified by their
+ * error code (a local name in the err namespace, e.g. "XPST0003").
+ *
+ * @module @tradik/xslt3/errors
+ */
+
+/** An error with a W3C error code. */
+export class XPathError extends Error {
+  /**
+   * @param {string} code - Error code, e.g. "XPST0003"
+   * @param {string} message - Description
+   * @param {ErrorOptions} [options] - Standard error options (cause)
+   */
+  constructor(code, message, options) {
+    super(`${code}: ${message}`, options);
+    this.name = "XPathError";
+    this.code = code;
+  }
+}

package/src/functions/aggregates.js

@@ -0,0 +1,144 @@
+/**
+ * Aggregate functions (F&O 3.1 section 14.4): avg, max, min and sum.
+ * xs:untypedAtomic values are cast to xs:double; numbers are promoted to a
+ * common type; durations must all be xs:yearMonthDuration or all
+ * xs:dayTimeDuration for sum and avg.
+ *
+ * @module @tradik/xslt3/functions/aggregates
+ */
+
+import { XPathError } from "../errors.js";
+import { arithmetic } from "../xdm/arithmetic.js";
+import { cast } from "../xdm/cast.js";
+import { compareAtomic } from "../xdm/compare.js";
+import { derivesFrom, isNumericType, types } from "../xdm/types.js";
+import { collationArg } from "./collations.js";
+import { define, integerItem } from "./support.js";
+
+/** @param {string} message @returns {never} */
+const invalid = (message) => {
+  throw new XPathError("FORG0006", message);
+};
+
+const numericLevels = ["decimal", "float", "double"];
+
+/**
+ * Casts xs:untypedAtomic to xs:double, numbers to their common type and
+ * xs:anyURI to xs:string when mixed with strings.
+ * @param {Array<import("../xdm/atomic.js").AtomicValue>} items
+ * @returns {Array<import("../xdm/atomic.js").AtomicValue>}
+ */
+export function promoteAll(items) {
+  const values = items.map((item) =>
+    item.type === types.untypedAtomic ? cast(item, types.double) : item,
+  );
+  const primitives = new Set(values.map((v) => v.type.primitive.localName));
+  if (values.every((v) => isNumericType(v.type))) {
+    const level = Math.max(
+      ...[...primitives].map((p) => numericLevels.indexOf(p)),
+    );
+    if (level === 0) return values;
+    const target = types[numericLevels[level]];
+    return values.map((v) => cast(v, target));
+  }
+  if (primitives.has("anyURI") && primitives.has("string")) {
+    // only the URIs are promoted: an xs:token stays an xs:token
+    return values.map((v) =>
+      v.type.primitive === types.anyURI ? cast(v, types.string) : v,
+    );
+  }
+  return values;
+}
+
+/**
+ * The kind of total a sum adds up, checking that all items share it.
+ * @param {Array<import("../xdm/atomic.js").AtomicValue>} values
+ * @throws {XPathError} FORG0006 for mixed or non-additive types
+ */
+function checkAdditive(values) {
+  const kinds = new Set(
+    values.map(({ type }) => {
+      if (isNumericType(type)) return "numeric";
+      if (derivesFrom(type, types.yearMonthDuration)) return "yearMonth";
+      if (derivesFrom(type, types.dayTimeDuration)) return "dayTime";
+      return invalid(`Cannot sum or average ${type.prefixedName} values`);
+    }),
+  );
+  if (kinds.size > 1) invalid("Cannot sum or average values of mixed types");
+}
+
+/**
+ * The sum of a non-empty sequence.
+ * @param {Array<import("../xdm/atomic.js").AtomicValue>} items
+ * @returns {import("../xdm/atomic.js").AtomicValue}
+ */
+function total(items) {
+  const values = promoteAll(items);
+  checkAdditive(values);
+  return values
+    .slice(1)
+    .reduce((sum, value) => arithmetic(sum, "+", value), values[0]);
+}
+
+/**
+ * fn:max or fn:min.
+ * @param {Array<*>[]} args - [$arg, $collation?]
+ * @param {object} context
+ * @param {number} direction - 1 for max, -1 for min
+ * @returns {Array<*>}
+ */
+function extreme([items, collation], context, direction) {
+  const options = {
+    collation: collationArg(collation, context).compare,
+    implicitTimezone: context.implicitTimezone ?? 0,
+  };
+  if (items.length === 0) return [];
+  const values = promoteAll(items);
+  const nan = values.find(
+    (v) => typeof v.value === "number" && Number.isNaN(v.value),
+  );
+  let best = values[0];
+  for (const value of values) {
+    let result;
+    try {
+      result = compareAtomic(value, best, options);
+    } catch {
+      invalid("max and min need mutually comparable values");
+    }
+    if (!result.ordered) invalid(`${value.type.prefixedName} is not ordered`);
+    if (result.order * direction > 0) best = value;
+  }
+  return [nan ?? best];
+}
+
+/**
+ * fn:sum.
+ * @param {Array<*>[]} args - [$arg, $zero?]
+ * @returns {Array<*>}
+ */
+function sum([items, zero]) {
+  if (items.length === 0) return zero ?? [integerItem(0)];
+  return [total(items)];
+}
+
+const ATOMS = "xs:anyAtomicType*";
+const ATOM_OPT = "xs:anyAtomicType?";
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const aggregateFunctions = [
+  define("avg", [ATOMS], ATOM_OPT, ([items]) =>
+    items.length === 0
+      ? []
+      : [arithmetic(total(items), "div", integerItem(items.length))],
+  ),
+  define("max", [ATOMS], ATOM_OPT, (args, c) => extreme(args, c, 1)),
+  define("max", [ATOMS, "xs:string"], ATOM_OPT, (args, c) =>
+    extreme(args, c, 1),
+  ),
+  define("min", [ATOMS], ATOM_OPT, (args, c) => extreme(args, c, -1)),
+  define("min", [ATOMS, "xs:string"], ATOM_OPT, (args, c) =>
+    extreme(args, c, -1),
+  ),
+  define("sum", [ATOMS], "xs:anyAtomicType", sum),
+  define("sum", [ATOMS, ATOM_OPT], ATOM_OPT, sum),
+];

package/src/functions/arraySort.js

@@ -0,0 +1,33 @@
+/**
+ * array:sort (F&O 3.1 section 17.3.19): the members of an array sorted
+ * like fn:sort sorts items.
+ *
+ * @module @tradik/xslt3/functions/arraySort
+ */
+
+import { XdmArray } from "../items/array.js";
+import { NS } from "./signatures.js";
+import { sortByKeys } from "./sort.js";
+
+/**
+ * array:sort.
+ * @returns {Array}
+ */
+const sort = ([[array], collation, key], context) => [
+  new XdmArray(
+    sortByKeys(array.members, collation, key?.[0], context, (member) => member),
+  ),
+];
+
+/** Function definitions. */
+export const arraySortFunctions = [
+  ["array(*)"],
+  ["array(*)", "xs:string?"],
+  ["array(*)", "xs:string?", "function(item()*) as xs:anyAtomicType*"],
+].map((params) => ({
+  namespace: NS.array,
+  local: "sort",
+  params,
+  returns: "array(*)",
+  impl: sort,
+}));

package/src/functions/arrays.js

@@ -0,0 +1,181 @@
+/**
+ * Functions on arrays (F&O 3.1 section 17.3), in the namespace
+ * http://www.w3.org/2005/xpath-functions/array.
+ *
+ * @module @tradik/xslt3/functions/arrays
+ */
+
+import { XPathError } from "../errors.js";
+import { XdmArray } from "../items/array.js";
+import { isArray } from "../xdm/atomic.js";
+import { integerItem } from "../xpath/eval/atomics.js";
+import { arraySortFunctions } from "./arraySort.js";
+import { NS } from "./signatures.js";
+
+/**
+ * @param {string} local
+ * @param {string[]} params
+ * @param {string} returns
+ * @param {Function} impl
+ * @returns {object} a definition in the array namespace
+ */
+const arrayFunction = (local, params, returns, impl) => ({
+  namespace: NS.array,
+  local,
+  params,
+  returns,
+  impl,
+});
+
+/**
+ * Checks a position for insertion (1 to size + 1).
+ * @param {XdmArray} array
+ * @param {*} position - xs:integer
+ * @returns {number} 0-based index
+ */
+function insertionIndex(array, position) {
+  const index = Number(position.value) - 1;
+  if (!(index >= 0 && index <= array.size)) {
+    throw new XPathError(
+      "FOAY0001",
+      `Position ${position.value} is out of bounds`,
+    );
+  }
+  return index;
+}
+
+/**
+ * Flattens arrays in a sequence, recursively.
+ * @param {Array} sequence
+ * @returns {Array}
+ */
+const flatten = (sequence) =>
+  sequence.flatMap((item) =>
+    isArray(item) ? flatten(item.members.flat()) : [item],
+  );
+
+/**
+ * array:subsequence.
+ * @returns {Array}
+ */
+function subarray([[array], [start], length]) {
+  const from = Number(start.value) - 1;
+  if (from < 0 || from > array.size) {
+    throw new XPathError("FOAY0001", "Subarray start out of bounds");
+  }
+  const count = length ? Number(length[0].value) : array.size - from;
+  if (count < 0) throw new XPathError("FOAY0002", "Negative length");
+  if (from + count > array.size) {
+    throw new XPathError("FOAY0001", "Subarray out of bounds");
+  }
+  return [new XdmArray(array.members.slice(from, from + count))];
+}
+
+/** Function definitions. */
+export const arrayFunctions = [
+  arrayFunction("size", ["array(*)"], "xs:integer", ([[a]]) => [
+    integerItem(a.size),
+  ]),
+  arrayFunction("get", ["array(*)", "xs:integer"], "item()*", ([[a], [i]]) =>
+    a.get(i.value),
+  ),
+  arrayFunction(
+    "put",
+    ["array(*)", "xs:integer", "item()*"],
+    "array(*)",
+    ([[a], [i], v]) => {
+      a.get(i.value);
+      const members = a.members.slice();
+      members[Number(i.value) - 1] = v;
+      return [new XdmArray(members)];
+    },
+  ),
+  arrayFunction("append", ["array(*)", "item()*"], "array(*)", ([[a], v]) => [
+    new XdmArray([...a.members, v]),
+  ]),
+  ...[2, 3].map((arity) =>
+    arrayFunction(
+      "subarray",
+      ["array(*)", "xs:integer", "xs:integer"].slice(0, arity),
+      "array(*)",
+      subarray,
+    ),
+  ),
+  arrayFunction(
+    "remove",
+    ["array(*)", "xs:integer*"],
+    "array(*)",
+    ([[a], positions]) => {
+      const removed = new Set(
+        positions.map((p) => (a.get(p.value), Number(p.value) - 1)),
+      );
+      return [new XdmArray(a.members.filter((_, i) => !removed.has(i)))];
+    },
+  ),
+  arrayFunction(
+    "insert-before",
+    ["array(*)", "xs:integer", "item()*"],
+    "array(*)",
+    ([[a], [p], v]) => {
+      const members = a.members.slice();
+      members.splice(insertionIndex(a, p), 0, v);
+      return [new XdmArray(members)];
+    },
+  ),
+  arrayFunction("head", ["array(*)"], "item()*", ([[a]]) => a.get(1)),
+  arrayFunction("tail", ["array(*)"], "array(*)", ([[a]]) => {
+    a.get(1);
+    return [new XdmArray(a.members.slice(1))];
+  }),
+  arrayFunction("reverse", ["array(*)"], "array(*)", ([[a]]) => [
+    new XdmArray(a.members.slice().reverse()),
+  ]),
+  arrayFunction("join", ["array(*)*"], "array(*)", ([arrays]) => [
+    new XdmArray(arrays.flatMap((a) => a.members)),
+  ]),
+  arrayFunction("flatten", ["item()*"], "item()*", ([sequence]) =>
+    flatten(sequence),
+  ),
+  arrayFunction(
+    "for-each",
+    ["array(*)", "function(item()*) as item()*"],
+    "array(*)",
+    ([[a], [f]]) => [new XdmArray(a.members.map((m) => f.invoke([m])))],
+  ),
+  arrayFunction(
+    "filter",
+    ["array(*)", "function(item()*) as xs:boolean"],
+    "array(*)",
+    ([[a], [f]]) => [
+      new XdmArray(a.members.filter((m) => f.invoke([m])[0].value)),
+    ],
+  ),
+  arrayFunction(
+    "fold-left",
+    ["array(*)", "item()*", "function(item()*, item()*) as item()*"],
+    "item()*",
+    ([[a], zero, [f]]) =>
+      a.members.reduce((acc, m) => f.invoke([acc, m]), zero),
+  ),
+  arrayFunction(
+    "fold-right",
+    ["array(*)", "item()*", "function(item()*, item()*) as item()*"],
+    "item()*",
+    ([[a], zero, [f]]) =>
+      a.members.reduceRight((acc, m) => f.invoke([m, acc]), zero),
+  ),
+  arrayFunction(
+    "for-each-pair",
+    ["array(*)", "array(*)", "function(item()*, item()*) as item()*"],
+    "array(*)",
+    ([[a], [b], [f]]) => {
+      const length = Math.min(a.size, b.size);
+      const members = [];
+      for (let i = 0; i < length; i++) {
+        members.push(f.invoke([a.members[i], b.members[i]]));
+      }
+      return [new XdmArray(members)];
+    },
+  ),
+  ...arraySortFunctions,
+];

package/src/functions/attributeTypes.js

@@ -0,0 +1,58 @@
+/**
+ * Attribute types declared in the internal DTD subset of a document
+ * (`<!ATTLIST>` declarations), which make attributes IDs, IDREFs or
+ * IDREFS without a schema (XDM 3.1: the is-id and is-idrefs properties).
+ * DOM implementations that expose `doctype.internalSubset` (such as
+ * @xmldom/xmldom) are supported; external DTD subsets are not read.
+ * `xml:id` attributes are always IDs.
+ *
+ * @module @tradik/xslt3/functions/attributeTypes
+ */
+
+import { XML_NAMESPACE } from "../xpath/eval/namespaceNodes.js";
+
+const ATTLIST = /<!ATTLIST\s+([^\s>]+)((?:[^>"']|"[^"]*"|'[^']*')*)>/g;
+const ATTRIBUTE_DEF =
+  /([^\s()"']+)\s+(\([^)]*\)|NOTATION\s*\([^)]*\)|[A-Z]+)\s+(?:#REQUIRED|#IMPLIED|(?:#FIXED\s+)?(?:"[^"]*"|'[^']*'))/g;
+
+/** @type {WeakMap<object, Map<string, string>>} */
+const cache = new WeakMap();
+
+/**
+ * Declared types of the attributes of a document, by "element attribute".
+ * @param {Document} document
+ * @returns {Map<string, string>} e.g. "chapter id" to "ID"
+ */
+function declaredTypes(document) {
+  let types = cache.get(document);
+  if (!types) {
+    types = new Map();
+    const subset = document.doctype?.internalSubset ?? "";
+    for (const [, element, body] of subset.matchAll(ATTLIST)) {
+      for (const [, attribute, type] of body.matchAll(ATTRIBUTE_DEF)) {
+        const key = `${element} ${attribute}`;
+        if (!types.has(key)) types.set(key, type);
+      }
+    }
+    cache.set(document, types);
+  }
+  return types;
+}
+
+/**
+ * The type of an attribute: "ID" for xml:id, else its DTD declaration.
+ * @param {Attr} attribute
+ * @param {Element} element - Its parent
+ * @returns {string|undefined} "ID", "IDREF", "IDREFS", "CDATA"...
+ */
+export function attributeType(attribute, element) {
+  if (
+    attribute.namespaceURI === XML_NAMESPACE &&
+    attribute.localName === "id"
+  ) {
+    return "ID";
+  }
+  return declaredTypes(element.ownerDocument).get(
+    `${element.nodeName} ${attribute.name}`,
+  );
+}