@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xpath/eval/calls.js

@@ -0,0 +1,168 @@
+/**
+ * Compilers of function calls (XPath 3.1 section 3.1.5): static calls,
+ * partial application, named function references, dynamic calls and the
+ * arrow operator.
+ *
+ * @module @tradik/xslt3/xpath/eval/calls
+ */
+
+import { XPathError } from "../../errors.js";
+import { FunctionItem } from "../../items/function.js";
+import { isFunctionItem } from "../../xdm/atomic.js";
+import { integerItem } from "./atomics.js";
+import { functionItemOf, resolveFunction } from "./functionItems.js";
+import { contextItem } from "./scope.js";
+import { signatureOf } from "./sequenceType.js";
+import { namespaceOf } from "./staticContext.js";
+import { NS } from "../../functions/signatures.js";
+
+const isPlaceholder = (arg) => arg.type === "ArgumentPlaceholder";
+
+/**
+ * Partial application: a function item taking the placeholder arguments.
+ * @param {Array<Function|null>} args - Evaluators, null for placeholders
+ * @param {{params: object[], returns: object}|null} signature - Of the
+ *   target function, null when unknown
+ * @param {(ctx: object) => (args: Array<Array>) => Array} target - Gives
+ *   the function to call
+ * @returns {import("./scope.js").Evaluator}
+ */
+function partial(args, signature, target) {
+  const holes = [];
+  args.forEach((arg, i) => arg === null && holes.push(i));
+  return (ctx) => {
+    const { invoke, signature: actual = signature } = target(ctx);
+    const fixed = args.map((arg) => (arg === null ? null : arg(ctx)));
+    return [
+      new FunctionItem({
+        arity: holes.length,
+        signature: {
+          params: holes.map((i) => actual.params[i]),
+          returns: actual.returns,
+        },
+        invoke: (values) => {
+          const all = fixed.slice();
+          holes.forEach((hole, i) => (all[hole] = values[i]));
+          return invoke(all);
+        },
+      }),
+    ];
+  };
+}
+
+/**
+ * @param {Array} sequence - Value of the function expression
+ * @param {number} arity - Number of arguments supplied
+ * @returns {*} the function item to call
+ * @throws {XPathError} XPTY0004 when it is not a single function of that
+ *   arity
+ */
+function calledFunction(sequence, arity) {
+  const [item] = sequence;
+  if (sequence.length !== 1 || !isFunctionItem(item)) {
+    throw new XPathError(
+      "XPTY0004",
+      "A dynamic function call needs exactly one function item",
+    );
+  }
+  if (item.arity !== arity) {
+    throw new XPathError(
+      "XPTY0004",
+      `The function has arity ${item.arity}, not ${arity}`,
+    );
+  }
+  return item;
+}
+
+/** Compilers by node type. */
+export const callCompilers = {
+  FunctionCall(node, scope, compile) {
+    const { sc } = scope;
+    const uri = namespaceOf(node.name, sc, sc.defaultFunctionNamespace);
+    const local = node.name.local;
+    const arity = node.arguments.length;
+    const resolved = resolveFunction(uri, local, arity, sc);
+    const args = node.arguments.map((arg) =>
+      isPlaceholder(arg) ? null : compile(arg, scope),
+    );
+    if (resolved.signature === null) return () => resolved.call();
+    if (args.includes(null)) {
+      return partial(args, resolved.signature, (ctx) => ({
+        invoke: (values) => resolved.call(values, ctx),
+      }));
+    }
+    if (uri === NS.fn && arity === 0 && resolved.focus) {
+      if (local === "position") {
+        return (ctx) => (contextItem(ctx), [integerItem(ctx.position)]);
+      }
+      if (local === "last") {
+        return (ctx) => (contextItem(ctx), [integerItem(ctx.size)]);
+      }
+    }
+    const { call } = resolved;
+    if (arity === 1) {
+      const [arg] = args;
+      return (ctx) => call([arg(ctx)], ctx);
+    }
+    return (ctx) =>
+      call(
+        args.map((arg) => arg(ctx)),
+        ctx,
+      );
+  },
+
+  NamedFunctionRef(node, scope) {
+    const { sc } = scope;
+    const uri = namespaceOf(node.name, sc, sc.defaultFunctionNamespace);
+    const resolved = resolveFunction(uri, node.name.local, node.arity, sc);
+    return (ctx) => [functionItemOf(resolved, ctx)];
+  },
+
+  DynamicFunctionCall(node, scope, compile) {
+    const target = compile(node.functionExpr, scope);
+    const arity = node.arguments.length;
+    const args = node.arguments.map((arg) =>
+      isPlaceholder(arg) ? null : compile(arg, scope),
+    );
+    if (args.includes(null)) {
+      return partial(args, null, (ctx) => {
+        const item = calledFunction(target(ctx), arity);
+        return {
+          invoke: (values) => item.invoke(values),
+          signature: signatureOf(item),
+        };
+      });
+    }
+    return (ctx) => {
+      const item = calledFunction(target(ctx), arity);
+      return item.invoke(args.map((arg) => arg(ctx)));
+    };
+  },
+
+  ArrowExpr(node, scope, compile) {
+    const args = [node.expr, ...node.arguments];
+    const { start, end } = node;
+    if (node.functionName) {
+      return compile(
+        {
+          type: "FunctionCall",
+          name: node.functionName,
+          arguments: args,
+          start,
+          end,
+        },
+        scope,
+      );
+    }
+    return compile(
+      {
+        type: "DynamicFunctionCall",
+        functionExpr: node.functionExpr,
+        arguments: args,
+        start,
+        end,
+      },
+      scope,
+    );
+  },
+};

package/src/xpath/eval/coercion.js

@@ -0,0 +1,146 @@
+/**
+ * The coercion rules (XPath 3.1 section 3.1.5.2, "function conversion
+ * rules"): how a value is converted to an expected sequence type when it
+ * is passed to a function or returned from one. Atomization, casting of
+ * xs:untypedAtomic, numeric and URI promotion, function coercion, then a
+ * type check (XPTY0004); in XPath 1.0 compatibility mode the 1.0
+ * conversions to string and number come first.
+ *
+ * @module @tradik/xslt3/xpath/eval/coercion
+ */
+
+import { XPathError } from "../../errors.js";
+import { isFunctionItem } from "../../xdm/atomic.js";
+import { cast } from "../../xdm/cast.js";
+import { toNumber } from "../../xdm/generalCompare.js";
+import { atomize, stringValue } from "../../xdm/nodes.js";
+import { derivesFrom, types } from "../../xdm/types.js";
+import { FunctionItem } from "../../items/function.js";
+import { stringItem } from "./atomics.js";
+import { matchesSequenceType } from "./sequenceType.js";
+
+/**
+ * Promotes or casts one atomic value towards the expected atomic types.
+ * @param {import("../../xdm/atomic.js").AtomicValue} value
+ * @param {object[]} expected - Atomic type descriptors
+ * @returns {import("../../xdm/atomic.js").AtomicValue}
+ */
+function convertAtomic(value, expected) {
+  if (expected.some((t) => derivesFrom(value.type, t))) return value;
+  if (value.type === types.untypedAtomic) {
+    if (
+      expected.some((t) => t.primitive === types.QName || t === types.NOTATION)
+    ) {
+      throw new XPathError(
+        "XPTY0117",
+        "An untyped value cannot be converted to xs:QName or xs:NOTATION",
+      );
+    }
+    const target = expected.length > 1 ? types.double : expected[0];
+    return target.abstract ? value : cast(value, target);
+  }
+  const primitive = value.type.primitive.localName;
+  for (const target of expected) {
+    const name = target.localName;
+    const numeric =
+      (name === "double" &&
+        (primitive === "decimal" || primitive === "float")) ||
+      (name === "float" && primitive === "decimal");
+    if (numeric || (name === "string" && primitive === "anyURI")) {
+      return cast(value, target);
+    }
+  }
+  return value;
+}
+
+/**
+ * XPath 1.0 compatibility mode conversions of an argument: only the
+ * first item is kept for a single expected item, converted with fn:string
+ * for xs:string and fn:number for xs:double.
+ * @param {Array} sequence
+ * @param {object|null} itemType - Expected item type
+ * @param {string} occurrence
+ * @returns {Array}
+ */
+function compatible(sequence, itemType, occurrence) {
+  if (occurrence === "*" || occurrence === "+") return sequence;
+  const first = sequence.slice(0, 1);
+  const expected = itemType?.kind === "atomic" ? itemType.types[0] : null;
+  if (expected === types.string) {
+    return [stringItem(first.length ? stringValue(first[0]) : "")];
+  }
+  if (expected === types.double) {
+    const value = atomize(first)[0];
+    return [value ? toNumber(value) : toNumber(stringItem("NaN"))];
+  }
+  return first;
+}
+
+/**
+ * Function coercion: wraps a function item so that it has the signature
+ * of a function test.
+ * @param {*} item
+ * @param {object} test - Compiled TypedFunctionTest
+ * @param {string} what - Description for error messages
+ * @returns {FunctionItem}
+ */
+function coerceFunction(item, test, what) {
+  if (item.arity !== test.params.length) {
+    throw new XPathError(
+      "XPTY0004",
+      `The ${what} must be a function of arity ${test.params.length}`,
+    );
+  }
+  return new FunctionItem({
+    name: item.name,
+    arity: item.arity,
+    signature: { params: test.params, returns: test.returns },
+    invoke: (args) =>
+      coerce(
+        item.invoke(
+          args.map((arg, i) =>
+            coerce(arg, test.params[i], {
+              what: `argument ${i + 1} of ${what}`,
+            }),
+          ),
+        ),
+        test.returns,
+        { what: `result of ${what}` },
+      ),
+  });
+}
+
+/**
+ * Converts a value to an expected sequence type.
+ * @param {Array} sequence
+ * @param {import("./sequenceType.js").SequenceType} type
+ * @param {{what: string, compatible?: boolean}} options - `what` names
+ *   the value in error messages; `compatible` applies the XPath 1.0 rules
+ * @returns {Array} the converted value
+ * @throws {XPathError} XPTY0004 when the value does not match the type,
+ *   cast errors (FORG0001...) for untyped values
+ */
+export function coerce(sequence, type, options) {
+  const itemType = type.itemType;
+  if (itemType?.kind === "item" && type.occurrence === "*") return sequence;
+  let value = sequence;
+  if (options.compatible) {
+    value = compatible(value, itemType, type.occurrence);
+  }
+  if (itemType?.kind === "atomic") {
+    value = atomize(value).map((v) => convertAtomic(v, itemType.types));
+  } else if (itemType?.kind === "function") {
+    value = value.map((item) =>
+      isFunctionItem(item) && !itemType.matches(item)
+        ? coerceFunction(item, itemType, options.what)
+        : item,
+    );
+  }
+  if (!matchesSequenceType(value, type)) {
+    throw new XPathError(
+      "XPTY0004",
+      `The ${options.what} does not match the required type`,
+    );
+  }
+  return value;
+}

package/src/xpath/eval/compiler.js

@@ -0,0 +1,71 @@
+/**
+ * The compiler: static analysis and translation of an AST into nested
+ * closures, in one pass. Names are resolved (XPST0081), variables
+ * (XPST0008), functions (XPST0017) and types (XPST0051, XPST0080) checked,
+ * and each node becomes an evaluator `(ctx) => Item[]`, so evaluation
+ * never walks the AST again.
+ *
+ * @module @tradik/xslt3/xpath/eval/compiler
+ */
+
+import { XPathError } from "../../errors.js";
+import { callCompilers } from "./calls.js";
+import { constructorCompilers } from "./constructors.js";
+import { flowCompilers } from "./flow.js";
+import { inlineCompilers } from "./inline.js";
+import { operatorCompilers } from "./operators.js";
+import { pathCompilers } from "./paths.js";
+import { primaryCompilers } from "./primary.js";
+import { typeCompilers } from "./typeExprs.js";
+
+/** Compilers by AST node type. */
+const compilers = {
+  ...primaryCompilers,
+  ...flowCompilers,
+  ...operatorCompilers,
+  ...typeCompilers,
+  ...pathCompilers,
+  ...callCompilers,
+  ...inlineCompilers,
+  ...constructorCompilers,
+};
+
+/**
+ * Compiles an expression node.
+ * @param {import("../syntax/ast.js").Expr} node
+ * @param {import("./scope.js").Scope} scope
+ * @returns {import("./scope.js").Evaluator}
+ * @throws {XPathError} the static errors of the expression
+ */
+export function compileNode(node, scope) {
+  const compiler = compilers[node.type];
+  if (!compiler) {
+    throw new XPathError("XPST0003", `Unsupported expression ${node.type}`);
+  }
+  return compiler(node, scope, compileNode);
+}
+
+/**
+ * Runs a function, turning the RangeErrors of JavaScript limits (stack
+ * depth of deeply nested expressions or recursive functions, string,
+ * array and BigInt sizes) into XPDY0130, the error for implementation
+ * limits.
+ * @template T
+ * @param {() => T} run
+ * @returns {T}
+ * @throws {XPathError} XPDY0130 instead of a RangeError
+ */
+export function withinLimits(run) {
+  try {
+    return run();
+  } catch (error) {
+    if (error instanceof RangeError) {
+      throw new XPathError(
+        "XPDY0130",
+        `Implementation limit exceeded: ${error.message}`,
+        { cause: error },
+      );
+    }
+    throw error;
+  }
+}

package/src/xpath/eval/constructors.js

@@ -0,0 +1,129 @@
+/**
+ * Compilers of map and array constructors and of the lookup operator `?`
+ * (XPath 3.1 sections 3.11.1 to 3.11.3).
+ *
+ * @module @tradik/xslt3/xpath/eval/constructors
+ */
+
+import { XPathError } from "../../errors.js";
+import { XdmArray } from "../../items/array.js";
+import { XdmMap } from "../../items/map.js";
+import { AtomicValue, isArray, isMap } from "../../xdm/atomic.js";
+import { atomize } from "../../xdm/nodes.js";
+import { types } from "../../xdm/types.js";
+import { contextItem } from "./scope.js";
+
+/**
+ * Compiles the key specifier of a lookup.
+ * @param {import("../syntax/ast.js").Lookup} node
+ * @param {import("./scope.js").Scope} scope
+ * @param {Function} compile
+ * @returns {((ctx: object) => import("../../xdm/atomic.js").AtomicValue[])|null}
+ *   the keys, null for the wildcard
+ */
+function compileKeys(node, scope, compile) {
+  switch (node.keyKind) {
+    case "wildcard":
+      return null;
+    case "name": {
+      const keys = [new AtomicValue(types.string, node.key)];
+      return () => keys;
+    }
+    case "integer": {
+      const keys = [new AtomicValue(types.integer, BigInt(node.key))];
+      return () => keys;
+    }
+    default: {
+      const expr = compile(node.key, scope);
+      return (ctx) => atomize(expr(ctx));
+    }
+  }
+}
+
+/**
+ * Looks keys up in one map or array.
+ * @param {*} item
+ * @param {import("../../xdm/atomic.js").AtomicValue[]|null} keys - null for
+ *   all entries or members
+ * @param {Array} result - Values are appended
+ * @throws {XPathError} XPTY0004 for an item that is neither a map nor an
+ *   array, or a non-integer array key; FOAY0001 for a position out of
+ *   bounds
+ */
+function lookup(item, keys, result) {
+  if (isMap(item)) {
+    if (keys === null) {
+      for (const { value } of item.entries.values()) result.push(...value);
+    } else {
+      for (const key of keys) result.push(...(item.get(key) ?? []));
+    }
+  } else if (isArray(item)) {
+    if (keys === null) {
+      for (const member of item.members) result.push(...member);
+    } else {
+      for (const key of keys) result.push(...item.invoke([[key]]));
+    }
+  } else {
+    throw new XPathError(
+      "XPTY0004",
+      "The lookup operator applies to maps and arrays only",
+    );
+  }
+}
+
+/** Compilers by node type. */
+export const constructorCompilers = {
+  MapConstructor(node, scope, compile) {
+    const entries = node.entries.map((entry) => ({
+      key: compile(entry.key, scope),
+      value: compile(entry.value, scope),
+    }));
+    return (ctx) => {
+      const pairs = entries.map(({ key, value }) => {
+        const keys = atomize(key(ctx));
+        if (keys.length !== 1) {
+          throw new XPathError(
+            "XPTY0004",
+            "A map key must be a single atomic value",
+          );
+        }
+        return [keys[0], value(ctx)];
+      });
+      const duplicate = () => {
+        throw new XPathError("XQDY0137", "Duplicate key in a map constructor");
+      };
+      return [XdmMap.from(pairs, duplicate)];
+    };
+  },
+
+  SquareArrayConstructor(node, scope, compile) {
+    const members = node.members.map((member) => compile(member, scope));
+    return (ctx) => [new XdmArray(members.map((member) => member(ctx)))];
+  },
+
+  CurlyArrayConstructor(node, scope, compile) {
+    const expr = compile(node.expr, scope);
+    return (ctx) => [new XdmArray(expr(ctx).map((item) => [item]))];
+  },
+
+  Lookup(node, scope, compile) {
+    const base = compile(node.base, scope);
+    const keys = compileKeys(node, scope, compile);
+    return (ctx) => {
+      const items = base(ctx);
+      const keyValues = keys && keys(ctx);
+      const result = [];
+      for (const item of items) lookup(item, keyValues, result);
+      return result;
+    };
+  },
+
+  UnaryLookup(node, scope, compile) {
+    const keys = compileKeys(node, scope, compile);
+    return (ctx) => {
+      const result = [];
+      lookup(contextItem(ctx), keys && keys(ctx), result);
+      return result;
+    };
+  },
+};

package/src/xpath/eval/decimalFormats.js

@@ -0,0 +1,93 @@
+/**
+ * Decimal formats of the static context (XPath 3.1 section 2.1.1), used by
+ * fn:format-number. Formats are given by name: a lexical QName or an EQName
+ * (prefixes resolved with the static namespaces), "" for the default one.
+ *
+ * Properties are read in camelCase (`decimalSeparator`) or as the
+ * attribute names of xsl:decimal-format (`decimal-separator`, `NaN`).
+ *
+ * @module @tradik/xslt3/xpath/eval/decimalFormats
+ */
+
+/** Property names of a decimal format, by attribute name. */
+const PROPERTIES = {
+  "decimal-separator": "decimalSeparator",
+  "grouping-separator": "groupingSeparator",
+  "exponent-separator": "exponentSeparator",
+  infinity: "infinity",
+  "minus-sign": "minusSign",
+  NaN: "nan",
+  nan: "nan",
+  percent: "percent",
+  "per-mille": "perMille",
+  "zero-digit": "zeroDigit",
+  digit: "digit",
+  "pattern-separator": "patternSeparator",
+};
+const CAMEL = new Set(Object.values(PROPERTIES));
+
+/**
+ * The properties of a format definition.
+ * @param {object} definition
+ * @returns {object} camelCase properties
+ */
+function propertiesOf(definition) {
+  const properties = {};
+  for (const [key, value] of Object.entries(definition)) {
+    const name = PROPERTIES[key] ?? (CAMEL.has(key) ? key : null);
+    if (name) properties[name] = value;
+  }
+  return properties;
+}
+
+/**
+ * Expanded name of a format definition: a prefix declared on the
+ * definition itself (an `xmlns:p` property, as xsl:decimal-format
+ * elements have) comes first, then the static namespaces.
+ * @param {string} name
+ * @param {object} definition
+ * @param {(name: string) => string} expand
+ * @returns {string|null} Clark name, "" for the default format, null when
+ *   the prefix is not declared
+ */
+function definitionKey(name, definition, expand) {
+  if (name === "") return "";
+  const colon = name.indexOf(":");
+  const own =
+    colon > 0 && !name.startsWith("Q{")
+      ? definition[`xmlns:${name.slice(0, colon)}`]
+      : undefined;
+  if (own !== undefined) return `{${own}}${name.slice(colon + 1)}`;
+  try {
+    return expand(name);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds the decimal formats of a static context.
+ * @param {Array<object>|object|Map|undefined} formats - An array of
+ *   definitions with a `name` property (absent for the default format),
+ *   or definitions by name
+ * @param {(name: string) => string} expand - Expands a name as written
+ *   to a Clark name (throws for an undeclared prefix)
+ * @returns {{get: (name: string) => object|undefined}} the formats by
+ *   name (surrounding whitespace ignored); get() returns undefined for an
+ *   unknown name or prefix
+ */
+export function createDecimalFormats(formats, expand) {
+  const entries = Array.isArray(formats)
+    ? formats.map((format) => [format.name ?? "", format])
+    : formats instanceof Map
+      ? [...formats]
+      : Object.entries(formats ?? {});
+  const byName = new Map();
+  for (const [name, format] of entries) {
+    const key = definitionKey(name.trim(), format, expand);
+    if (key !== null) byName.set(key, propertiesOf(format));
+  }
+  return {
+    get: (name) => byName.get(definitionKey(name.trim(), {}, expand)),
+  };
+}

package/src/xpath/eval/descendantMemo.js

@@ -0,0 +1,77 @@
+/**
+ * Axis results remembered for the rest of an evaluation, so that
+ * `for $c in ... return //item[@cat = $c]` walks the tree and looks the
+ * attributes up once instead of once per iteration:
+ *
+ * - the descendant axes of a document node, always;
+ * - the attributes looked up by name, once the evaluation has walked a
+ *   tree a second time (a remembered descendant axis was used): before
+ *   that, in one pass over the tree, remembering costs more than it saves.
+ *
+ * Only an evaluation that owns its dynamic context turns it on
+ * (compileXPath's evaluate sets `dyn.descendantMemo`): an XPath evaluation
+ * does not change existing trees (the nodes that functions build are new,
+ * complete trees), so a remembered result stays exact while it runs. A
+ * caller that shares a dynamic context over trees it changes leaves it
+ * off.
+ *
+ * @module @tradik/xslt3/xpath/eval/descendantMemo
+ */
+
+import { axes } from "./axes.js";
+
+/** Axes worth remembering: whole subtrees. */
+const MEMO_AXES = new Set(["descendant", "descendant-or-self"]);
+
+/**
+ * @typedef {object} DescendantMemo
+ * @property {Map<string, Map<Function, Map<Node, Node[]>>>|null} results -
+ *   By axis, node test and context node
+ * @property {boolean} repeated - Whether a remembered descendant axis was
+ *   used again
+ */
+
+/** @returns {DescendantMemo} the memo of an evaluation */
+export const createDescendantMemo = () => ({ results: null, repeated: false });
+
+/**
+ * Whether the result of an axis is remembered.
+ * @returns {boolean}
+ */
+function isRemembered(memo, name, node, test, limit) {
+  if (name === "attribute") {
+    return memo.repeated && test.qname !== undefined && limit >= 1;
+  }
+  const type = node.nodeType;
+  return (
+    limit === Infinity && MEMO_AXES.has(name) && (type === 9 || type === 11)
+  );
+}
+
+/**
+ * The nodes of an axis, from the memo of the evaluation when there is one
+ * and the axis is remembered.
+ * @param {string} name - Axis name
+ * @param {Node} node - Context node
+ * @param {(node: Node) => boolean} test - Node test (one function per
+ *   compiled step, so it identifies the step)
+ * @param {number} limit - Most nodes to collect
+ * @param {object} dyn - Dynamic context
+ * @returns {Node[]} the nodes in axis order (a new array)
+ */
+export function axisNodes(name, node, test, limit, dyn) {
+  const memo = dyn.descendantMemo;
+  if (!memo || !isRemembered(memo, name, node, test, limit)) {
+    return axes[name](node, test, limit);
+  }
+  // Created on first use: most evaluations never need it
+  memo.results ??= new Map();
+  let byTest = memo.results.get(name);
+  if (!byTest) memo.results.set(name, (byTest = new Map()));
+  let byNode = byTest.get(test);
+  if (!byNode) byTest.set(test, (byNode = new Map()));
+  let nodes = byNode.get(node);
+  if (nodes) memo.repeated = true;
+  else byNode.set(node, (nodes = axes[name](node, test, limit)));
+  return nodes.slice();
+}