@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/xdm/atomic.js

@@ -0,0 +1,142 @@
+/**
+ * Items of the data model: atomic values, nodes and the function items
+ * (maps, arrays, functions) that the evaluator adds later.
+ *
+ * Atomic value representations by primitive type:
+ * - xs:string family, xs:untypedAtomic, xs:anyURI: JS string
+ * - xs:boolean: JS boolean
+ * - xs:decimal: {@link Decimal}; xs:integer and subtypes: BigInt
+ * - xs:double, xs:float: JS number (float values pass through Math.fround)
+ * - durations: {@link DurationValue}; dates and times: {@link DateTimeValue}
+ * - xs:hexBinary, xs:base64Binary: Uint8Array
+ * - xs:QName, xs:NOTATION: {@link QNameValue}
+ *
+ * A sequence is a plain JS array of items.
+ *
+ * @module @tradik/xslt3/xdm/atomic
+ */
+
+import { XPathError } from "../errors.js";
+import { Decimal } from "./decimal.js";
+import { normalizeWhitespace } from "./strings.js";
+import { getType } from "./types.js";
+
+/**
+ * Property under which maps, arrays and function items declare their kind
+ * ("map", "array" or "function"). Arrays also expose `members`, an array
+ * of sequences, which atomization flattens.
+ */
+export const ITEM_KIND = Symbol.for("@tradik/xslt3/itemKind");
+
+/** An immutable atomic value: a type descriptor and a typed value. */
+export class AtomicValue {
+  /**
+   * Prefer {@link atomic}, which coerces and validates the value.
+   * @param {object} type - Type descriptor from the registry
+   * @param {*} value - Representation for the type's primitive
+   */
+  constructor(type, value) {
+    this.type = type;
+    this.value = value;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * @param {*} item
+ * @returns {"atomic"|"node"|"map"|"array"|"function"} the kind of an item
+ * @throws {XPathError} XPTY0004 for a value that is not an item
+ */
+export function itemKind(item) {
+  if (item instanceof AtomicValue) return "atomic";
+  // Nodes before the symbol: on a DOM node (a jsdom wrapper) the symbol is
+  // looked up along a long prototype chain
+  if (typeof item?.nodeType === "number") return "node";
+  if (item?.[ITEM_KIND]) return item[ITEM_KIND];
+  throw new XPathError("XPTY0004", `Not an XDM item: ${String(item)}`);
+}
+
+/** @param {*} item @returns {boolean} whether the item is an atomic value */
+export const isAtomic = (item) => item instanceof AtomicValue;
+/** @param {*} item @returns {boolean} whether the item is a DOM node */
+export const isNode = (item) =>
+  !isAtomic(item) && typeof item?.nodeType === "number";
+/** @param {*} item @returns {boolean} whether the item is a map */
+export const isMap = (item) => item?.[ITEM_KIND] === "map";
+/** @param {*} item @returns {boolean} whether the item is an array */
+export const isArray = (item) => item?.[ITEM_KIND] === "array";
+/** @param {*} item @returns {boolean} whether the item is a function item (maps and arrays are functions too) */
+export const isFunctionItem = (item) => Boolean(item?.[ITEM_KIND]);
+
+/**
+ * Checks the constraining facets of a type that is derived by restriction
+ * from a primitive (integer ranges, string patterns and whitespace,
+ * required timezone).
+ * @param {object} type
+ * @param {*} value - Representation for the type's primitive
+ * @returns {*} the value
+ * @throws {XPathError} FORG0001 when a facet is violated
+ */
+export function checkFacets(type, value) {
+  for (let t = type; t !== t.castPrimitive; t = t.base) {
+    const { minInclusive, maxInclusive, pattern, timezoneRequired } = t.facets;
+    const fails =
+      (minInclusive !== undefined && value < minInclusive) ||
+      (maxInclusive !== undefined && value > maxInclusive) ||
+      (pattern !== undefined && !pattern.test(value)) ||
+      (typeof value === "string" &&
+        normalizeWhitespace(value, t.whiteSpace) !== value) ||
+      (timezoneRequired === true && value.timezone === null);
+    if (fails) {
+      throw new XPathError(
+        "FORG0001",
+        `Value is not a valid ${type.prefixedName}`,
+      );
+    }
+  }
+  return value;
+}
+
+/** Coercions of JS values to the representation of a primitive. */
+const coercions = {
+  integer(value) {
+    if (typeof value === "bigint") return value;
+    if (Number.isInteger(value)) return BigInt(value);
+    throw new XPathError("FORG0001", `${value} is not an integer`);
+  },
+  decimal(value) {
+    if (value instanceof Decimal) return value;
+    const decimal = Decimal.parse(
+      typeof value === "bigint" ? `${value}` : String(value),
+    );
+    if (decimal === null) {
+      throw new XPathError("FORG0001", `${value} is not a decimal`);
+    }
+    return decimal;
+  },
+  float: (value) => Math.fround(value),
+};
+
+/**
+ * Builds an atomic value from a JS value in the type's representation
+ * (numbers and BigInts are accepted for xs:integer and xs:decimal, and
+ * floats are rounded); derived types have their facets checked.
+ * @param {string|object} typeName - "xs:integer", "integer", Clark name or descriptor
+ * @param {*} value
+ * @returns {AtomicValue}
+ * @throws {XPathError} XPST0080 for abstract types, FORG0001 for invalid
+ *   values and for xs:error
+ * @example atomic("xs:integer", 42); atomic("xs:string", "abc")
+ */
+export function atomic(typeName, value) {
+  const type = getType(typeName);
+  if (type.abstract) {
+    throw new XPathError("XPST0080", `${type.prefixedName} is abstract`);
+  }
+  if (type.localName === "error") {
+    throw new XPathError("FORG0001", "xs:error has no values");
+  }
+  const coerce = coercions[type.castPrimitive.localName];
+  const coerced = coerce ? coerce(value) : value;
+  return new AtomicValue(type, checkFacets(type, coerced));
+}

package/src/xdm/binary.js

@@ -0,0 +1,92 @@
+/**
+ * xs:hexBinary and xs:base64Binary: lexical parsing per XSD 1.1 Part 2 and
+ * canonical strings. Values are Uint8Arrays; no platform encoder (atob,
+ * Buffer) is used, so the module runs anywhere.
+ *
+ * @module @tradik/xslt3/xdm/binary
+ */
+
+const alphabet =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const base64Pattern =
+  /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=|[A-Za-z0-9+/][AQgw]==)?$/;
+
+/**
+ * Parses xs:hexBinary (whitespace already collapsed).
+ * @param {string} text
+ * @returns {Uint8Array|null} null when invalid
+ */
+export function parseHexBinary(text) {
+  if (text.length % 2 !== 0 || !/^[0-9A-Fa-f]*$/.test(text)) return null;
+  const bytes = new Uint8Array(text.length / 2);
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(text.slice(2 * i, 2 * i + 2), 16);
+  }
+  return bytes;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} canonical xs:hexBinary (upper case)
+ */
+export function formatHexBinary(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .toUpperCase();
+}
+
+/**
+ * Parses xs:base64Binary (whitespace already collapsed; single spaces
+ * between characters are allowed by the XSD grammar).
+ * @param {string} text
+ * @returns {Uint8Array|null} null when invalid
+ */
+export function parseBase64Binary(text) {
+  const compact = text.replaceAll(" ", "");
+  if (!base64Pattern.test(compact)) return null;
+  const data = compact.replace(/=+$/, "");
+  const bytes = new Uint8Array(Math.floor((data.length * 3) / 4));
+  let buffer = 0;
+  let bits = 0;
+  let index = 0;
+  for (const char of data) {
+    buffer = ((buffer << 6) | alphabet.indexOf(char)) & 0xfff;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes[index++] = (buffer >> bits) & 0xff;
+    }
+  }
+  return bytes;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} canonical xs:base64Binary (no whitespace, padded)
+ */
+export function formatBase64Binary(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const chunk =
+      (bytes[i] << 16) | ((bytes[i + 1] ?? 0) << 8) | (bytes[i + 2] ?? 0);
+    const chars = Math.min(4, Math.ceil(((bytes.length - i) * 8) / 6));
+    for (let j = 0; j < 4; j++) {
+      out += j < chars ? alphabet[(chunk >> (18 - 6 * j)) & 63] : "=";
+    }
+  }
+  return out;
+}
+
+/**
+ * Compares two byte arrays lexicographically (op:hexBinary-less-than).
+ * @param {Uint8Array} a
+ * @param {Uint8Array} b
+ * @returns {number} -1, 0 or 1
+ */
+export function compareBytes(a, b) {
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return Math.sign(a.length - b.length);
+}

package/src/xdm/calendar.js

@@ -0,0 +1,71 @@
+/**
+ * Proleptic Gregorian calendar arithmetic with astronomical year
+ * numbering, as in XSD 1.1 (year 0000 is 1 BCE and is a leap year).
+ *
+ * @module @tradik/xslt3/xdm/calendar
+ */
+
+/**
+ * @param {number} year
+ * @returns {boolean} whether the year is a leap year
+ */
+export function isLeapYear(year) {
+  return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+}
+
+const monthLengths = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+/**
+ * @param {number} year
+ * @param {number} month - 1 to 12
+ * @returns {number} number of days in the month
+ */
+export function daysInMonth(year, month) {
+  return month === 2 && isLeapYear(year) ? 29 : monthLengths[month - 1];
+}
+
+/**
+ * Days since 1970-01-01 of a civil date (H. Hinnant's algorithm).
+ * @param {number} year
+ * @param {number} month - 1 to 12
+ * @param {number} day - 1 to 31
+ * @returns {number}
+ */
+export function daysFromCivil(year, month, day) {
+  const y = month <= 2 ? year - 1 : year;
+  const era = Math.floor(y / 400);
+  const yearOfEra = y - era * 400;
+  const dayOfYear =
+    Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+  const dayOfEra =
+    yearOfEra * 365 +
+    Math.floor(yearOfEra / 4) -
+    Math.floor(yearOfEra / 100) +
+    dayOfYear;
+  return era * 146097 + dayOfEra - 719468;
+}
+
+/**
+ * Civil date of a day number (inverse of {@link daysFromCivil}).
+ * @param {number} days - Days since 1970-01-01
+ * @returns {[number, number, number]} [year, month, day]
+ */
+export function civilFromDays(days) {
+  const z = days + 719468;
+  const era = Math.floor(z / 146097);
+  const dayOfEra = z - era * 146097;
+  const yearOfEra = Math.floor(
+    (dayOfEra -
+      Math.floor(dayOfEra / 1460) +
+      Math.floor(dayOfEra / 36524) -
+      Math.floor(dayOfEra / 146096)) /
+      365,
+  );
+  const dayOfYear =
+    dayOfEra -
+    (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+  const mp = Math.floor((5 * dayOfYear + 2) / 153);
+  const day = dayOfYear - Math.floor((153 * mp + 2) / 5) + 1;
+  const month = mp < 10 ? mp + 3 : mp - 9;
+  return [yearOfEra + era * 400 + (month <= 2 ? 1 : 0), month, day];
+}

package/src/xdm/cast.js

@@ -0,0 +1,176 @@
+/**
+ * Casting between atomic types (F&O 3.1 section 19): the primitive-to-
+ * primitive table of 19.1, casting from strings (19.2) and casting to and
+ * from derived types (19.3).
+ *
+ * @module @tradik/xslt3/xdm/cast
+ */
+
+import { XPathError } from "../errors.js";
+import { AtomicValue, checkFacets } from "./atomic.js";
+import { componentsOf, DateTimeValue } from "./datetime.js";
+import { Decimal } from "./decimal.js";
+import { DurationValue } from "./duration.js";
+import { canonicalString, fromLexical } from "./lexical.js";
+import { numberToDecimal } from "./numeric.js";
+import { getType } from "./types.js";
+
+const durationKinds = ["duration", "yearMonthDuration", "dayTimeDuration"];
+
+/**
+ * @param {number} n
+ * @returns {number} n
+ * @throws {XPathError} FOCA0002 for NaN and the infinities
+ */
+function finite(n) {
+  if (!Number.isFinite(n)) {
+    throw new XPathError("FOCA0002", `Cannot cast ${n} to a decimal`);
+  }
+  return n;
+}
+
+/** @param {*} v @param {string} from @returns {number} numeric value as a double */
+function toDouble(v, from) {
+  if (from === "boolean") return v ? 1 : 0;
+  return from === "decimal" ? v.toNumber() : Number(v);
+}
+
+/**
+ * Projects a date/time value onto the components of another kind; missing
+ * time components become midnight (xs:date to xs:dateTime).
+ * @param {DateTimeValue} v
+ * @param {string} kind - Target primitive
+ * @returns {DateTimeValue}
+ */
+function project(v, kind) {
+  const fields = { timezone: v.timezone };
+  for (const name of componentsOf(kind)) {
+    fields[name] = v[name] ?? (name === "second" ? Decimal.ZERO : 0);
+  }
+  return new DateTimeValue(fields);
+}
+
+/**
+ * Conversions of the F&O 3.1 19.1 table, by target then source primitive
+ * (the "Y" and "M" cells; strings are handled by lexical parsing).
+ */
+const table = {
+  float: { double: Math.fround },
+  double: { float: (v) => v },
+  decimal: {
+    float: (v) => numberToDecimal(finite(v), true),
+    double: (v) => numberToDecimal(finite(v)),
+    integer: (v) => Decimal.of(v),
+    boolean: (v) => (v ? Decimal.of(1n) : Decimal.ZERO),
+  },
+  integer: {
+    float: (v) => BigInt(Math.trunc(finite(v))),
+    double: (v) => BigInt(Math.trunc(finite(v))),
+    decimal: (v) => v.trunc(),
+    boolean: (v) => (v ? 1n : 0n),
+  },
+  boolean: {
+    float: (v) => !(v === 0 || Number.isNaN(v)),
+    double: (v) => !(v === 0 || Number.isNaN(v)),
+    decimal: (v) => v.sign() !== 0,
+    integer: (v) => v !== 0n,
+  },
+  duration: {},
+  yearMonthDuration: {},
+  dayTimeDuration: {},
+  hexBinary: { base64Binary: (v) => v },
+  base64Binary: { hexBinary: (v) => v },
+  dateTime: { date: (v) => project(v, "dateTime") },
+  time: { dateTime: (v) => project(v, "time") },
+  date: { dateTime: (v) => project(v, "date") },
+};
+for (const from of ["integer", "decimal", "boolean"]) {
+  table.float[from] = (v) => Math.fround(toDouble(v, from));
+  table.double[from] = (v) => toDouble(v, from);
+}
+for (const to of durationKinds) {
+  for (const from of durationKinds) {
+    table[to][from] = (v) =>
+      new DurationValue(
+        to === "dayTimeDuration" ? 0 : v.months,
+        to === "yearMonthDuration" ? Decimal.ZERO : v.seconds,
+      );
+  }
+}
+for (const to of ["gYearMonth", "gYear", "gMonthDay", "gDay", "gMonth"]) {
+  table[to] = { dateTime: (v) => project(v, to), date: (v) => project(v, to) };
+}
+
+/**
+ * Converts a value between two primitive types of the casting table.
+ * @param {AtomicValue} item
+ * @param {object} target - Primitive type descriptor (F&O sense)
+ * @returns {*} the converted value representation
+ * @throws {XPathError} XPTY0004 when the table has no conversion
+ */
+function convertPrimitive(item, target) {
+  const from = item.type.castPrimitive.localName;
+  if (from === target.localName) return item.value;
+  if (target.localName === "string" || target.localName === "untypedAtomic") {
+    return canonicalString(item);
+  }
+  const convert = table[target.localName]?.[from];
+  if (!convert) {
+    throw new XPathError(
+      "XPTY0004",
+      `Cannot cast ${item.type.prefixedName} to ${target.prefixedName}`,
+    );
+  }
+  return convert(item.value);
+}
+
+/**
+ * Casts an atomic value to an atomic type (`$value cast as T`).
+ * @param {AtomicValue} item
+ * @param {string|object} typeName - Target type name or descriptor
+ * @param {object} [options]
+ * @param {import("./qname.js").NamespaceResolver} [options.resolveNamespace]
+ *   - Prefix resolver for casting strings to xs:QName
+ * @returns {AtomicValue}
+ * @throws {XPathError} XPST0080 (abstract target), XPTY0004 (cast not
+ *   allowed), FORG0001 (invalid value; always for xs:error), FOCA0002 (NaN/INF to decimal or
+ *   integer), FODT0001/FODT0002 (date/duration overflow), FONS0004
+ */
+export function cast(item, typeName, options = {}) {
+  const target = getType(typeName);
+  if (target.abstract) {
+    throw new XPathError("XPST0080", `Cannot cast to ${target.prefixedName}`);
+  }
+  if (target.localName === "error") {
+    throw new XPathError("FORG0001", "No value can be cast to xs:error");
+  }
+  if (item.type === target) return item;
+  const sourcePrimitive = item.type.primitive.localName;
+  if (sourcePrimitive === "string" || sourcePrimitive === "untypedAtomic") {
+    return fromLexical(target, item.value, options);
+  }
+  const value = convertPrimitive(item, target.castPrimitive);
+  if (target.castPrimitive.localName === "string") {
+    return fromLexical(target, value);
+  }
+  return new AtomicValue(target, checkFacets(target, value));
+}
+
+/**
+ * Whether a cast would succeed (`$value castable as T`). Static errors
+ * (unknown or abstract target type) and non-XPath errors are still raised.
+ * @param {AtomicValue} item
+ * @param {string|object} typeName
+ * @param {object} [options] - As for {@link cast}
+ * @returns {boolean}
+ */
+export function castable(item, typeName, options = {}) {
+  try {
+    cast(item, typeName, options);
+    return true;
+  } catch (error) {
+    const isStatic = error.code === "XPST0080" || error.code === "XPST0051";
+    if (!(error instanceof XPathError) || isStatic) throw error;
+    return false;
+  }
+}

package/src/xdm/compare.js

@@ -0,0 +1,192 @@
+/**
+ * Value comparisons of atomic values (XPath 3.1 section 3.7.1, operator
+ * mapping of appendix B.2, F&O 3.1 comparison operators) and the
+ * atomic-value equality of fn:deep-equal.
+ *
+ * @module @tradik/xslt3/xdm/compare
+ */
+
+import { XPathError } from "../errors.js";
+import { compareBytes } from "./binary.js";
+import { timelineSeconds } from "./timeline.js";
+import { Decimal } from "./decimal.js";
+import { compareCodepoints } from "./strings.js";
+import { derivesFrom } from "./types.js";
+
+/**
+ * Options of the comparison functions.
+ * @typedef {object} CompareOptions
+ * @property {number} [implicitTimezone=0] - Offset in minutes applied to
+ *   dates and times without a timezone
+ * @property {(a: string, b: string) => number} [collation] - String
+ *   comparison; defaults to the Unicode codepoint collation
+ */
+
+const numericRank = { decimal: 0, float: 1, double: 2 };
+const stringLike = new Set(["string", "anyURI", "untypedAtomic"]);
+const orderedTimes = new Set(["dateTime", "date", "time"]);
+const unorderedTimes = new Set([
+  "gYearMonth",
+  "gYear",
+  "gMonthDay",
+  "gDay",
+  "gMonth",
+]);
+
+/** @param {number} n @returns {number} sign of a difference, NaN kept */
+const sign = (n) => (Number.isNaN(n) ? NaN : Math.sign(n));
+
+/**
+ * Numeric value of an operand at a promotion level.
+ * @param {import("./atomic.js").AtomicValue} item
+ * @param {string} level - "decimal", "float" or "double"
+ * @returns {number|Decimal}
+ */
+function promote(item, level) {
+  const { value } = item;
+  if (level === "decimal") {
+    return typeof value === "bigint" ? Decimal.of(value) : value;
+  }
+  const number = typeof value === "number" ? value : Number(value.toString());
+  return level === "float" ? Math.fround(number) : number;
+}
+
+/**
+ * Compares two numeric values with type promotion (decimal → float →
+ * double).
+ * @returns {number} -1, 0, 1 or NaN when unordered
+ */
+function compareNumeric(a, b, pa, pb) {
+  if (typeof a.value === "bigint" && typeof b.value === "bigint") {
+    return a.value < b.value ? -1 : a.value > b.value ? 1 : 0;
+  }
+  const level = numericRank[pa] > numericRank[pb] ? pa : pb;
+  const x = promote(a, level);
+  const y = promote(b, level);
+  if (level === "decimal") return x.compare(y);
+  // Equal infinities: INF - INF is NaN, which would make them unordered
+  return x === y ? 0 : sign(x - y);
+}
+
+/**
+ * Compares two durations; ordering is only defined within
+ * xs:yearMonthDuration or within xs:dayTimeDuration.
+ * @returns {{order: number, ordered: boolean}}
+ */
+function compareDurations(a, b) {
+  const yearMonth =
+    derivesFrom(a.type, "yearMonthDuration") &&
+    derivesFrom(b.type, "yearMonthDuration");
+  const dayTime =
+    derivesFrom(a.type, "dayTimeDuration") &&
+    derivesFrom(b.type, "dayTimeDuration");
+  const months = Math.sign(a.value.months - b.value.months);
+  const seconds = a.value.seconds.compare(b.value.seconds);
+  if (yearMonth) return { order: months, ordered: true };
+  if (dayTime) return { order: seconds, ordered: true };
+  return { order: months === 0 && seconds === 0 ? 0 : NaN, ordered: false };
+}
+
+/**
+ * Compares two atomic values per the operator mapping.
+ * @param {import("./atomic.js").AtomicValue} a
+ * @param {import("./atomic.js").AtomicValue} b
+ * @param {CompareOptions} [options]
+ * @returns {{order: number, ordered: boolean}} `order` is -1, 0, 1, or NaN
+ *   when the values are unequal and unordered (NaN operands, mixed
+ *   durations); `ordered` tells whether lt/gt are defined for the pair
+ * @throws {XPathError} XPTY0004 when the types are not comparable
+ */
+export function compareAtomic(a, b, options = {}) {
+  const pa = a.type.primitive.localName;
+  const pb = b.type.primitive.localName;
+  if (pa in numericRank && pb in numericRank) {
+    return { order: compareNumeric(a, b, pa, pb), ordered: true };
+  }
+  if (stringLike.has(pa) && stringLike.has(pb)) {
+    const order = (options.collation ?? compareCodepoints)(a.value, b.value);
+    return { order: Math.sign(order), ordered: true };
+  }
+  if (pa !== pb) {
+    throw new XPathError(
+      "XPTY0004",
+      `Cannot compare ${a.type.prefixedName} with ${b.type.prefixedName}`,
+    );
+  }
+  if (pa === "boolean") {
+    return { order: Number(a.value) - Number(b.value), ordered: true };
+  }
+  if (pa === "duration") return compareDurations(a, b);
+  if (orderedTimes.has(pa) || unorderedTimes.has(pa)) {
+    const timezone = options.implicitTimezone ?? 0;
+    const order = timelineSeconds(a.value, timezone).compare(
+      timelineSeconds(b.value, timezone),
+    );
+    return { order, ordered: orderedTimes.has(pa) };
+  }
+  if (pa === "hexBinary" || pa === "base64Binary") {
+    return { order: compareBytes(a.value, b.value), ordered: true };
+  }
+  // xs:QName and xs:NOTATION: equality of namespace URI and local name
+  const equal =
+    a.value.namespaceURI === b.value.namespaceURI &&
+    a.value.localName === b.value.localName;
+  return { order: equal ? 0 : NaN, ordered: false };
+}
+
+/** Value comparison operators applied to an order (-1, 0, 1, NaN). */
+export const orderTests = {
+  eq: (order) => order === 0,
+  ne: (order) => order !== 0,
+  lt: (order) => order < 0,
+  le: (order) => order <= 0,
+  gt: (order) => order > 0,
+  ge: (order) => order >= 0,
+};
+
+/**
+ * Value comparison `a op b` of two atomic values (xs:untypedAtomic is
+ * compared as xs:string). Empty and multi-item operands are the
+ * evaluator's concern.
+ * @param {import("./atomic.js").AtomicValue} a
+ * @param {"eq"|"ne"|"lt"|"le"|"gt"|"ge"} op
+ * @param {import("./atomic.js").AtomicValue} b
+ * @param {CompareOptions} [options]
+ * @returns {boolean}
+ * @throws {XPathError} XPTY0004 when the types are not comparable with op
+ */
+export function valueCompare(a, op, b, options = {}) {
+  const { order, ordered } = compareAtomic(a, b, options);
+  if (!ordered && op !== "eq" && op !== "ne") {
+    throw new XPathError(
+      "XPTY0004",
+      `${op} is not defined for ${a.type.prefixedName}`,
+    );
+  }
+  return orderTests[op](order);
+}
+
+/**
+ * Equality of two atomic values as in fn:deep-equal and
+ * fn:distinct-values: incomparable types are unequal (no error) and NaN
+ * equals NaN.
+ * @param {import("./atomic.js").AtomicValue} a
+ * @param {import("./atomic.js").AtomicValue} b
+ * @param {CompareOptions} [options]
+ * @returns {boolean}
+ */
+export function deepEqualAtomic(a, b, options = {}) {
+  let order;
+  try {
+    ({ order } = compareAtomic(a, b, options));
+  } catch (error) {
+    if (!(error instanceof XPathError)) throw error;
+    return false;
+  }
+  return order === 0 || (Number.isNaN(order) && isNaNValue(a) && isNaNValue(b));
+}
+
+/** @param {import("./atomic.js").AtomicValue} item @returns {boolean} */
+function isNaNValue(item) {
+  return typeof item.value === "number" && Number.isNaN(item.value);
+}