@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/datetime.js

@@ -0,0 +1,203 @@
+/**
+ * Functions on durations, dates and times (F&O 3.1 sections 8.3, 9.3 to
+ * 9.5, and the context functions of 16.1): component extraction,
+ * fn:dateTime, timezone adjustment, current-dateTime/date/time and
+ * implicit-timezone.
+ *
+ * @module @tradik/xslt3/functions/datetime
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue } from "../xdm/atomic.js";
+import { componentsOf, DateTimeValue } from "../xdm/datetime.js";
+import { Decimal } from "../xdm/decimal.js";
+import { DurationValue } from "../xdm/duration.js";
+import { fromLocalSeconds, localSeconds } from "../xdm/timeline.js";
+import { types } from "../xdm/types.js";
+import { decimalItem, define, integerItem } from "./support.js";
+
+/** @param {number} minutes @returns {AtomicValue} an xs:dayTimeDuration */
+export const timezoneDuration = (minutes) =>
+  new AtomicValue(
+    types.dayTimeDuration,
+    new DurationValue(0, Decimal.of(BigInt(minutes * 60))),
+  );
+
+/**
+ * Replaces the timezone of a date/time value, adjusting the local value
+ * when it had one (F&O 3.1 section 9.5).
+ * @param {AtomicValue} item - xs:dateTime, xs:date or xs:time
+ * @param {number|null} timezone - Minutes, null to remove the timezone
+ * @returns {AtomicValue}
+ */
+export function adjustToTimezone(item, timezone) {
+  const kind = item.type.primitive.localName;
+  const { value } = item;
+  let local = value;
+  if (value.timezone !== null && timezone !== null) {
+    const shift = Decimal.of(BigInt((timezone - value.timezone) * 60));
+    local = fromLocalSeconds(localSeconds(value).add(shift), timezone);
+  }
+  const fields = { timezone };
+  for (const name of componentsOf(kind)) fields[name] = local[name];
+  return new AtomicValue(types[kind], new DateTimeValue(fields));
+}
+
+/**
+ * The timezone argument of the adjust functions in minutes.
+ * @param {Array<AtomicValue>|undefined} sequence - Undefined: the implicit
+ *   timezone; empty: no timezone
+ * @param {object} context
+ * @returns {number|null}
+ * @throws {XPathError} FODT0003 for an invalid timezone
+ */
+function timezoneArg(sequence, context) {
+  if (sequence === undefined) return context.implicitTimezone ?? 0;
+  if (sequence.length === 0) return null;
+  const seconds = sequence[0].value.seconds;
+  const minutes = seconds.div(Decimal.of(60n));
+  if (!minutes.isInteger() || Math.abs(minutes.toNumber()) > 14 * 60) {
+    throw new XPathError("FODT0003", `Invalid timezone ${seconds}S`);
+  }
+  return minutes.toNumber();
+}
+
+/**
+ * Declares a function of one optional argument returning one optional
+ * value.
+ * @param {string} local
+ * @param {string} param
+ * @param {string} returns
+ * @param {(value: *) => AtomicValue|null} extract
+ * @returns {import("./support.js").FunctionDefinition}
+ */
+const accessor = (local, param, returns, extract) =>
+  define(local, [`${param}?`], `${returns}?`, ([arg]) => {
+    const result = arg.length === 0 ? null : extract(arg[0].value);
+    return result === null ? [] : [result];
+  });
+
+const component = (name) => (value) =>
+  name === "second" ? decimalItem(value.second) : integerItem(value[name]);
+const timezoneOf = (value) =>
+  value.timezone === null ? null : timezoneDuration(value.timezone);
+
+/** Component accessors by type: [type name, [function suffix, component]] */
+const extractors = [
+  ["dateTime", ["year", "month", "day", "hours", "minutes", "seconds"]],
+  ["date", ["year", "month", "day"]],
+  ["time", ["hours", "minutes", "seconds"]],
+];
+const componentNames = {
+  year: "year",
+  month: "month",
+  day: "day",
+  hours: "hour",
+  minutes: "minute",
+  seconds: "second",
+};
+
+const DAY = 86400n;
+/** Duration component extractors on (months, whole seconds, seconds). */
+const durationParts = {
+  years: (d) => integerItem(Math.trunc(d.months / 12)),
+  months: (d) => integerItem(d.months % 12),
+  days: (d) => integerItem(d.seconds.trunc() / DAY),
+  hours: (d) => integerItem((d.seconds.trunc() / 3600n) % 24n),
+  minutes: (d) => integerItem((d.seconds.trunc() / 60n) % 60n),
+  seconds: (d) => decimalItem(d.seconds.mod(Decimal.of(60n))),
+};
+
+/**
+ * The current date/time from the context, with the implicit timezone when
+ * it has none, projected on a type.
+ * @param {object} context
+ * @param {string} kind - "dateTime", "date" or "time"
+ * @returns {AtomicValue}
+ */
+function current(context, kind) {
+  const now = context.currentDateTime;
+  const fields = { timezone: now.timezone ?? context.implicitTimezone ?? 0 };
+  for (const name of componentsOf(kind)) fields[name] = now[name];
+  const type = kind === "dateTime" ? types.dateTimeStamp : types[kind];
+  return new AtomicValue(type, new DateTimeValue(fields));
+}
+
+/**
+ * fn:dateTime.
+ * @param {Array<AtomicValue>[]} args - [$date, $time]
+ * @returns {Array<AtomicValue>}
+ */
+function dateTime([date, time]) {
+  if (date.length === 0 || time.length === 0) return [];
+  const d = date[0].value;
+  const t = time[0].value;
+  if (d.timezone !== null && t.timezone !== null && d.timezone !== t.timezone) {
+    throw new XPathError("FORG0008", "The date and time timezones differ");
+  }
+  const value = new DateTimeValue({
+    ...t,
+    year: d.year,
+    month: d.month,
+    day: d.day,
+    timezone: d.timezone ?? t.timezone,
+  });
+  return [new AtomicValue(types.dateTime, value)];
+}
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const dateTimeFunctions = [
+  ...extractors.flatMap(([type, parts]) => [
+    ...parts.map((part) =>
+      accessor(
+        `${part}-from-${type}`,
+        `xs:${type}`,
+        part === "seconds" ? "xs:decimal" : "xs:integer",
+        component(componentNames[part]),
+      ),
+    ),
+    accessor(
+      `timezone-from-${type}`,
+      `xs:${type}`,
+      "xs:dayTimeDuration",
+      timezoneOf,
+    ),
+  ]),
+  ...Object.entries(durationParts).map(([part, extract]) =>
+    accessor(
+      `${part}-from-duration`,
+      "xs:duration",
+      part === "seconds" ? "xs:decimal" : "xs:integer",
+      extract,
+    ),
+  ),
+  define("dateTime", ["xs:date?", "xs:time?"], "xs:dateTime?", dateTime),
+  ...["dateTime", "date", "time"].flatMap((type) => {
+    const impl = ([arg, timezone], context) =>
+      arg.length === 0
+        ? []
+        : [adjustToTimezone(arg[0], timezoneArg(timezone, context))];
+    const local = `adjust-${type}-to-timezone`;
+    return [
+      define(local, [`xs:${type}?`], `xs:${type}?`, impl),
+      define(
+        local,
+        [`xs:${type}?`, "xs:dayTimeDuration?"],
+        `xs:${type}?`,
+        impl,
+      ),
+    ];
+  }),
+  define("current-dateTime", [], "xs:dateTimeStamp", (_a, context) => [
+    current(context, "dateTime"),
+  ]),
+  define("current-date", [], "xs:date", (_a, context) => [
+    current(context, "date"),
+  ]),
+  define("current-time", [], "xs:time", (_a, context) => [
+    current(context, "time"),
+  ]),
+  define("implicit-timezone", [], "xs:dayTimeDuration", (_a, context) => [
+    timezoneDuration(context.implicitTimezone ?? 0),
+  ]),
+];

package/src/functions/deepEqual.js

@@ -0,0 +1,132 @@
+/**
+ * fn:deep-equal (F&O 3.1 section 14.2.1) for atomic values and DOM nodes
+ * of any implementation (nodeType, namespaceURI, localName, nodeName,
+ * nodeValue, attributes and childNodes are read).
+ *
+ * Maps, arrays and function items are delegated to the hook
+ * `options.deepEqualItem(a, b, options)`, which the evaluator supplies
+ * through the dynamic context (`context.deepEqualItem`) because it owns
+ * their representation. Without the hook such items raise FOTY0015.
+ *
+ * @module @tradik/xslt3/functions/deepEqual
+ */
+
+import { XPathError } from "../errors.js";
+import { deepEqualAtomic } from "../xdm/compare.js";
+import { isAtomic, isNode } from "../xdm/atomic.js";
+import { nodeStringValue } from "../xdm/nodes.js";
+
+const XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/";
+const ELEMENT = 1;
+const ATTRIBUTE = 2;
+const PROCESSING_INSTRUCTION = 7;
+const COMMENT = 8;
+const DOCUMENT = 9;
+const DOCUMENT_FRAGMENT = 11;
+
+/**
+ * @typedef {object} DeepEqualOptions
+ * @property {(a: string, b: string) => number} collation
+ * @property {number} implicitTimezone
+ * @property {(a: *, b: *, options: DeepEqualOptions) => boolean} [deepEqualItem]
+ */
+
+/** @param {Node} node @returns {string} "{uri}local" */
+const expandedName = (node) =>
+  `{${node.namespaceURI ?? ""}}${node.localName ?? node.nodeName}`;
+
+/** @param {Node} node @returns {Node[]} children without comments and PIs */
+const significantChildren = (node) =>
+  Array.from(node.childNodes).filter(
+    (child) =>
+      child.nodeType !== COMMENT && child.nodeType !== PROCESSING_INSTRUCTION,
+  );
+
+/** @param {Element} node @returns {Attr[]} attributes without namespace declarations */
+const realAttributes = (node) =>
+  Array.from(node.attributes ?? []).filter(
+    (attr) => attr.namespaceURI !== XMLNS_NAMESPACE,
+  );
+
+/**
+ * @param {Node} a
+ * @param {Node} b
+ * @param {DeepEqualOptions} options
+ * @returns {boolean} whether two nodes are deep-equal
+ */
+export function deepEqualNodes(a, b, options) {
+  const kind = (node) =>
+    node.nodeType === DOCUMENT_FRAGMENT ? DOCUMENT : node.nodeType;
+  if (kind(a) !== kind(b)) return false;
+  const sameText = () =>
+    options.collation(nodeStringValue(a), nodeStringValue(b)) === 0;
+  switch (kind(a)) {
+    case DOCUMENT:
+      return childrenEqual(a, b, options);
+    case ELEMENT: {
+      if (expandedName(a) !== expandedName(b)) return false;
+      const attributes = realAttributes(a);
+      const others = realAttributes(b);
+      return (
+        attributes.length === others.length &&
+        attributes.every((attr) =>
+          others.some((other) => deepEqualNodes(attr, other, options)),
+        ) &&
+        childrenEqual(a, b, options)
+      );
+    }
+    case ATTRIBUTE:
+    case PROCESSING_INSTRUCTION:
+      return expandedName(a) === expandedName(b) && sameText();
+    default:
+      // text, comment and namespace nodes
+      return sameText();
+  }
+}
+
+/**
+ * @param {Node} a
+ * @param {Node} b
+ * @param {DeepEqualOptions} options
+ * @returns {boolean} whether the significant children are pairwise equal
+ */
+function childrenEqual(a, b, options) {
+  const x = significantChildren(a);
+  const y = significantChildren(b);
+  return (
+    x.length === y.length &&
+    x.every((child, i) => deepEqualNodes(child, y[i], options))
+  );
+}
+
+/**
+ * @param {*} a
+ * @param {*} b
+ * @param {DeepEqualOptions} options
+ * @returns {boolean} whether two items are deep-equal
+ * @throws {XPathError} FOTY0015 for function items without the hook
+ */
+function deepEqualItems(a, b, options) {
+  if (isAtomic(a) || isAtomic(b)) {
+    return isAtomic(a) && isAtomic(b) && deepEqualAtomic(a, b, options);
+  }
+  if (isNode(a) || isNode(b)) {
+    return isNode(a) && isNode(b) && deepEqualNodes(a, b, options);
+  }
+  if (options.deepEqualItem) return options.deepEqualItem(a, b, options);
+  throw new XPathError("FOTY0015", "deep-equal of function items");
+}
+
+/**
+ * Whether two sequences are deep-equal.
+ * @param {Array<*>} a
+ * @param {Array<*>} b
+ * @param {DeepEqualOptions} options
+ * @returns {boolean}
+ */
+export function deepEqualSequences(a, b, options) {
+  return (
+    a.length === b.length &&
+    a.every((item, i) => deepEqualItems(item, b[i], options))
+  );
+}

package/src/functions/diagnostics.js

@@ -0,0 +1,88 @@
+/**
+ * Error and diagnostic functions (F&O 3.1 sections 3 and 4): fn:error and
+ * fn:trace, and the document functions fn:doc and fn:doc-available.
+ *
+ * @module @tradik/xslt3/functions/diagnostics
+ */
+
+import { XPathError } from "../errors.js";
+import { booleanItem } from "../xpath/eval/atomics.js";
+
+/** Error code of an xs:QName: the local name in the err namespace. */
+function errorCode(qname) {
+  if (qname.namespaceURI === "http://www.w3.org/2005/xqt-errors") {
+    return qname.localName;
+  }
+  return `Q{${qname.namespaceURI}}${qname.localName}`;
+}
+
+/**
+ * fn:error.
+ * @param {Array<Array>} args
+ * @returns {never}
+ */
+function raise([code = [], description, object]) {
+  const qname = code[0]?.value;
+  const error = new XPathError(
+    qname ? errorCode(qname) : "FOER0000",
+    description?.[0]?.value ?? "Error raised by fn:error",
+  );
+  error.qname = qname;
+  error.errorObject = object;
+  throw error;
+}
+
+/** Function definitions. */
+export const diagnosticFunctions = [
+  { local: "error", params: [], returns: "item()*", impl: raise },
+  { local: "error", params: ["xs:QName?"], returns: "item()*", impl: raise },
+  {
+    local: "error",
+    params: ["xs:QName?", "xs:string"],
+    returns: "item()*",
+    impl: raise,
+  },
+  {
+    local: "error",
+    params: ["xs:QName?", "xs:string", "item()*"],
+    returns: "item()*",
+    impl: raise,
+  },
+  {
+    local: "trace",
+    params: ["item()*"],
+    returns: "item()*",
+    impl: ([value], context) => (context.trace(value, ""), value),
+  },
+  {
+    local: "trace",
+    params: ["item()*", "xs:string"],
+    returns: "item()*",
+    impl: ([value, [label]], context) => (
+      context.trace(value, label.value),
+      value
+    ),
+  },
+  {
+    local: "doc",
+    params: ["xs:string?"],
+    returns: "document-node()?",
+    impl: ([uri], context) =>
+      uri.length ? [context.loadDocument(uri[0].value)] : [],
+  },
+  {
+    local: "doc-available",
+    params: ["xs:string?"],
+    returns: "xs:boolean",
+    impl: ([uri], context) => {
+      if (!uri.length) return [booleanItem(false)];
+      try {
+        context.loadDocument(uri[0].value);
+        return [booleanItem(true)];
+      } catch {
+        // loadDocument raises only FODC0002 and FODC0005
+        return [booleanItem(false)];
+      }
+    },
+  },
+];

package/src/functions/focus.js

@@ -0,0 +1,34 @@
+/**
+ * Access to the focus from function implementations (definitions with
+ * `focus: true`).
+ *
+ * @module @tradik/xslt3/functions/focus
+ */
+
+import { XPathError } from "../errors.js";
+import { isNode } from "../xdm/atomic.js";
+
+/**
+ * @param {import("./registry.js").DynamicContext} context
+ * @returns {*} the context item
+ * @throws {XPathError} XPDY0002 when the focus is absent
+ */
+export function focusItem(context) {
+  if (context.contextItem === undefined) {
+    throw new XPathError("XPDY0002", "The context item is absent");
+  }
+  return context.contextItem;
+}
+
+/**
+ * @param {import("./registry.js").DynamicContext} context
+ * @returns {Node} the context item, which must be a node
+ * @throws {XPathError} XPDY0002 when absent, XPTY0004 when not a node
+ */
+export function focusNode(context) {
+  const item = focusItem(context);
+  if (!isNode(item)) {
+    throw new XPathError("XPTY0004", "The context item is not a node");
+  }
+  return item;
+}

package/src/functions/format/dateComponents.js

@@ -0,0 +1,176 @@
+/**
+ * Values and English names of the date/time components used by the
+ * format-dateTime family (F&O 3.1 section 9.8.4.1): day of year, ISO day
+ * of week and week numbers, 12-hour clock, names of months, days, am/pm
+ * and eras.
+ *
+ * @module @tradik/xslt3/functions/format/dateComponents
+ */
+
+import { civilFromDays, daysFromCivil } from "../../xdm/calendar.js";
+
+const MONTHS = (
+  "January February March April May June July August September October " +
+  "November December"
+).split(" ");
+const DAYS = "Monday Tuesday Wednesday Thursday Friday Saturday Sunday".split(
+  " ",
+);
+
+/**
+ * Conventional English abbreviations longer than three letters, by name;
+ * every name of more than three letters also abbreviates to its first
+ * three.
+ */
+const ABBREVIATIONS = {
+  Tuesday: ["Tues"],
+  Wednesday: ["Weds"],
+  Thursday: ["Thur", "Thurs"],
+  September: ["Sept"],
+};
+
+/**
+ * The longest abbreviation of a name that fits a maximum width, else the
+ * name truncated to it.
+ * @param {string} name - Capitalized English name
+ * @param {number} maxWidth
+ * @returns {string}
+ */
+function abbreviate(name, maxWidth) {
+  const chars = Array.from(name);
+  if (chars.length <= maxWidth) return name;
+  const candidates = [name.slice(0, 3), ...(ABBREVIATIONS[name] ?? [])];
+  const fitting = candidates.filter(
+    (c) => c.length <= maxWidth && c.length < chars.length,
+  );
+  return fitting.length
+    ? fitting[fitting.length - 1]
+    : chars.slice(0, maxWidth).join("");
+}
+
+/** Components available per value kind. */
+const AVAILABLE = {
+  dateTime: "YMDdFWwHhPmsfZzCE",
+  date: "YMDdFWwZzCE",
+  time: "HhPmsfZzC",
+};
+
+/**
+ * @param {string} kind - "dateTime", "date" or "time"
+ * @param {string} component
+ * @returns {boolean} whether the component exists in values of the kind
+ */
+export const isAvailable = (kind, component) =>
+  AVAILABLE[kind].includes(component);
+
+/**
+ * ISO day of the week, 1 (Monday) to 7 (Sunday), of a day number.
+ * @param {number} days - Days since 1970-01-01 (a Thursday)
+ * @returns {number}
+ */
+const isoDayOfWeek = (days) => ((((days + 3) % 7) + 7) % 7) + 1;
+
+/**
+ * Week numbers of a date: ISO week in year, and week in month where a
+ * Monday-to-Sunday week belongs to the month of its Thursday, except that
+ * the last days of a month whose Thursday is in the next month continue
+ * the count of their own month (as Saxon and the W3C tests do).
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @returns {{week: number, weekInMonth: number}}
+ */
+function weeks(value) {
+  const days = daysFromCivil(value.year, value.month, value.day);
+  const thursday = days - isoDayOfWeek(days) + 4;
+  const [year, , day] = civilFromDays(thursday);
+  const dayOfYear = thursday - daysFromCivil(year, 1, 1);
+  const monthStart = daysFromCivil(value.year, value.month, 1);
+  const dayInMonth = thursday >= monthStart ? thursday - monthStart + 1 : day;
+  return {
+    week: Math.floor(dayOfYear / 7) + 1,
+    weekInMonth: Math.floor((dayInMonth - 1) / 7) + 1,
+  };
+}
+
+/**
+ * The numeric value of a component (Y is the absolute year; s the whole
+ * seconds).
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @param {string} component - One of YMDdFWwHhms
+ * @returns {number}
+ */
+export function componentValue(value, component) {
+  switch (component) {
+    case "Y":
+      return Math.abs(value.year);
+    case "M":
+      return value.month;
+    case "D":
+      return value.day;
+    case "d":
+      return (
+        daysFromCivil(value.year, value.month, value.day) -
+        daysFromCivil(value.year, 1, 1) +
+        1
+      );
+    case "F":
+      return isoDayOfWeek(daysFromCivil(value.year, value.month, value.day));
+    case "W":
+      return weeks(value).week;
+    case "w":
+      return weeks(value).weekInMonth;
+    case "H":
+      return value.hour;
+    case "h":
+      return value.hour % 12 || 12;
+    case "m":
+      return value.minute;
+    default:
+      return Number(value.second.trunc());
+  }
+}
+
+/**
+ * The English name of a component, or null when it has none.
+ * @param {import("../../xdm/datetime.js").DateTimeValue} value
+ * @param {string} component
+ * @param {string} calendar - Calendar used, e.g. "AD"
+ * @returns {string|null}
+ */
+export function componentName(value, component, calendar) {
+  switch (component) {
+    case "M":
+      return MONTHS[value.month - 1];
+    case "F":
+      return DAYS[componentValue(value, "F") - 1];
+    case "P":
+      return value.hour < 12 ? "am" : "pm";
+    case "C":
+      return calendar;
+    case "E":
+      if (calendar === "ISO") return value.year < 0 ? "-" : "";
+      return value.year > 0 ? "AD" : "BC";
+    default:
+      return null;
+  }
+}
+
+/**
+ * Applies a name presentation modifier and the width modifier to a name.
+ * @param {string} name
+ * @param {string} token - "n", "N" or "Nn"
+ * @param {number|null} minWidth
+ * @param {number|null} maxWidth
+ * @returns {string}
+ */
+export function presentName(name, token, minWidth, maxWidth) {
+  const capitalized = name.charAt(0).toUpperCase() + name.slice(1);
+  const short =
+    maxWidth === null ? capitalized : abbreviate(capitalized, maxWidth);
+  const text =
+    token === "N"
+      ? short.toUpperCase()
+      : token === "n"
+        ? short.toLowerCase()
+        : short;
+  return minWidth === null ? text : text.padEnd(minWidth, " ");
+}