@callis/ucum 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,1000 @@
+import { UCUM_ESSENCE_XML } from "./essence/ucum-essence-xml.js";
+import { Decimal, MAX_DECIMAL_DIGITS, minimalUnitSystem } from "@callis/core";
+// src/essence/xml-elements.ts
+const NAME = /[A-Za-z_:][-A-Za-z0-9_:.]*/y;
+const ATTRIBUTE = /\s+([A-Za-z_:][-A-Za-z0-9_:.]*)\s*=\s*(?:"([^"<]*)"|'([^'<]*)')/y;
+const TAG_END = /\s*(\/?)>/y;
+const PREDEFINED_ENTITIES = Object.freeze({
+	amp: "&",
+	apos: "'",
+	gt: ">",
+	lt: "<",
+	quot: "\""
+});
+/**
+* Reads the element tree of a well-formed XML document, as far as the UCUM essence file needs:
+* elements, attributes, comments, processing instructions and CDATA sections. Text is skipped.
+* Document type declarations are rejected, so no external or custom entities are ever expanded.
+*
+* @returns the root element, or `undefined` if the text is not well-formed.
+* @see https://www.w3.org/TR/xml/
+*/
+function readXmlElements(text) {
+	const stack = [];
+	let root;
+	let index = 0;
+	while (index < text.length) {
+		const open = text.indexOf("<", index);
+		if (open === -1) {
+			if (!isAllowedText(text.slice(index), stack.length)) return void 0;
+			break;
+		}
+		if (!isAllowedText(text.slice(index, open), stack.length)) return void 0;
+		if (text.startsWith("<?", open)) {
+			const end = text.indexOf("?>", open + 2);
+			if (end === -1) return void 0;
+			index = end + 2;
+		} else if (text.startsWith("<!--", open)) {
+			const end = text.indexOf("-->", open + 4);
+			if (end === -1) return void 0;
+			index = end + 3;
+		} else if (text.startsWith("<![CDATA[", open)) {
+			const end = text.indexOf("]]>", open + 9);
+			if (end === -1 || stack.length === 0) return void 0;
+			index = end + 3;
+		} else if (text.startsWith("<!", open)) return;
+		else if (text.startsWith("</", open)) {
+			NAME.lastIndex = open + 2;
+			const name = NAME.exec(text)?.[0];
+			const element = stack.pop();
+			if (name === void 0 || element === void 0 || element.name !== name) return void 0;
+			TAG_END.lastIndex = open + 2 + name.length;
+			const end = TAG_END.exec(text);
+			if (end === null || end[1] === "/") return void 0;
+			index = TAG_END.lastIndex;
+			const closed = {
+				name: element.name,
+				attributes: element.attributes,
+				children: element.children
+			};
+			const parent = stack.at(-1);
+			if (parent === void 0) root = closed;
+			else parent.children.push(closed);
+		} else {
+			if (root !== void 0) return void 0;
+			NAME.lastIndex = open + 1;
+			const name = NAME.exec(text)?.[0];
+			if (name === void 0) return void 0;
+			index = open + 1 + name.length;
+			const attributes = /* @__PURE__ */ new Map();
+			for (;;) {
+				ATTRIBUTE.lastIndex = index;
+				const attribute = ATTRIBUTE.exec(text);
+				if (attribute === null) break;
+				const [, key = "", double, single] = attribute;
+				const value = decodeEntities(double ?? single ?? "");
+				if (value === void 0 || attributes.has(key)) return void 0;
+				attributes.set(key, value);
+				index = ATTRIBUTE.lastIndex;
+			}
+			TAG_END.lastIndex = index;
+			const end = TAG_END.exec(text);
+			if (end === null) return void 0;
+			index = TAG_END.lastIndex;
+			if (end[1] === "/") {
+				const element = {
+					name,
+					attributes,
+					children: []
+				};
+				const parent = stack.at(-1);
+				if (parent === void 0) root = element;
+				else parent.children.push(element);
+			} else stack.push({
+				name,
+				attributes,
+				children: []
+			});
+		}
+	}
+	return stack.length === 0 ? root : void 0;
+}
+/** Text inside elements is skipped; outside the root element only whitespace may appear. */
+function isAllowedText(text, depth) {
+	return depth > 0 || /^[ \t\r\n]*$/.test(text);
+}
+/** Replaces the predefined entities and character references; undefined for anything else. */
+function decodeEntities(value) {
+	let invalid = false;
+	const decoded = value.replace(/&([^;]*);?/g, (match, reference) => {
+		if (!match.endsWith(";")) {
+			invalid = true;
+			return "";
+		}
+		if (Object.hasOwn(PREDEFINED_ENTITIES, reference)) return PREDEFINED_ENTITIES[reference] ?? "";
+		const code = /^#[0-9]+$/.test(reference) ? Number.parseInt(reference.slice(1), 10) : /^#x[0-9A-Fa-f]+$/.test(reference) ? Number.parseInt(reference.slice(2), 16) : NaN;
+		if (!Number.isInteger(code) || code < 1 || code > 1114111 || code >= 55296 && code <= 57343) {
+			invalid = true;
+			return "";
+		}
+		return String.fromCodePoint(code);
+	});
+	return invalid ? void 0 : decoded;
+}
+// src/essence/essence-reader.ts
+/**
+* Reads prefixes, base units and units from the text of `ucum-essence.xml`. Only the case-sensitive
+* `Code` attributes are used. Names, print symbols and the other descriptive content are skipped.
+*
+* @returns the definitions, or `undefined` if the text is not a well-formed essence document.
+* @see https://ucum.org/ucum#section-Character-Set-and-Lexical-Rules
+*/
+function readEssence(xml) {
+	const root = readXmlElements(xml);
+	if (root === void 0 || root.name !== "root") return void 0;
+	const prefixes = [];
+	const baseUnits = [];
+	const units = [];
+	for (const element of root.children) {
+		const code = element.attributes.get("Code");
+		if (element.name === "prefix") {
+			const value = child(element, "value")?.attributes.get("value");
+			if (code === void 0 || value === void 0) return void 0;
+			prefixes.push({
+				code,
+				value
+			});
+		} else if (element.name === "base-unit") {
+			const dimension = element.attributes.get("dim");
+			if (code === void 0 || dimension === void 0) return void 0;
+			baseUnits.push({
+				code,
+				dimension
+			});
+		} else if (element.name === "unit") {
+			const unit = readUnit(element, code);
+			if (unit === void 0) return void 0;
+			units.push(unit);
+		}
+	}
+	return {
+		version: root.attributes.get("version") ?? "",
+		revisionDate: root.attributes.get("revision-date") ?? "",
+		prefixes,
+		baseUnits,
+		units
+	};
+}
+function readUnit(element, code) {
+	const value = child(element, "value");
+	const unit = value?.attributes.get("Unit");
+	if (code === void 0 || value === void 0 || unit === void 0) return void 0;
+	const fn = child(value, "function");
+	let definition;
+	if (fn !== void 0) {
+		const name = fn.attributes.get("name");
+		const fnValue = fn.attributes.get("value");
+		const fnUnit = fn.attributes.get("Unit");
+		if (name === void 0 || fnValue === void 0 || fnUnit === void 0) return void 0;
+		definition = {
+			name,
+			value: fnValue,
+			unit: fnUnit
+		};
+	}
+	const isSpecial = element.attributes.get("isSpecial") === "yes";
+	if (isSpecial !== (definition !== void 0)) return void 0;
+	const factor = value.attributes.get("value");
+	if (!isSpecial && factor === void 0) return void 0;
+	return {
+		code,
+		isMetric: element.attributes.get("isMetric") === "yes",
+		isSpecial,
+		isArbitrary: element.attributes.get("isArbitrary") === "yes",
+		unit,
+		value: factor,
+		function: definition
+	};
+}
+function child(element, name) {
+	return element.children.find((candidate) => candidate.name === name);
+}
+// src/rational.ts
+/**
+* The largest numerator or denominator, in bits (about 21,000 decimal digits). A Decimal has at
+* most 10,000 digits on either side of the point, so a ratio of 10^20000 or more already maps
+* every non-zero Decimal outside that bound. Larger magnitudes are rejected before `BigInt` work
+* grows with them.
+*/
+const MAX_RATIONAL_BITS = 7e4;
+/**
+* The largest numerator or denominator of a unit magnitude, in bits (about 1,200 decimal digits).
+* The largest magnitude in the essence file needs a few hundred bits, and a realistic unit term
+* a few times more. Unit strings can come from untrusted data, and every `.` or `/` multiplies
+* magnitudes, so this much smaller bound keeps each step cheap: without it, a 10 kB string of
+* `[pi].[pi]…` would take about a minute of `BigInt` work before reaching the value bound.
+*/
+const MAX_MAGNITUDE_BITS = 4096;
+/** The rational 1. */
+const ONE = Object.freeze({
+	numerator: 1n,
+	denominator: 1n
+});
+/**
+* `numerator / denominator` in lowest terms, or `undefined` for a zero denominator or when either
+* part needs more than `limit` bits.
+*/
+function rational(numerator, denominator = 1n, limit = MAX_RATIONAL_BITS) {
+	if (denominator === 0n) return void 0;
+	if (denominator < 0n) {
+		numerator = -numerator;
+		denominator = -denominator;
+	}
+	const divisor = gcd(abs(numerator), denominator);
+	if (divisor > 1n) {
+		numerator /= divisor;
+		denominator /= divisor;
+	}
+	if (bitLength(numerator) > limit || bitLength(denominator) > limit) return;
+	return {
+		numerator,
+		denominator
+	};
+}
+/** `a × b`, or `undefined` when a part needs more than `limit` bits. */
+function multiply(a, b, limit = MAX_RATIONAL_BITS) {
+	return rational(a.numerator * b.numerator, a.denominator * b.denominator, limit);
+}
+/** `a / b`, or `undefined` when `b` is zero or a part needs more than `limit` bits. */
+function divide(a, b, limit = MAX_RATIONAL_BITS) {
+	return rational(a.numerator * b.denominator, a.denominator * b.numerator, limit);
+}
+/** `a + b`, or `undefined` on overflow. */
+function add(a, b) {
+	return rational(a.numerator * b.denominator + b.numerator * a.denominator, a.denominator * b.denominator);
+}
+/** `a - b`, or `undefined` on overflow. */
+function subtract(a, b) {
+	return rational(a.numerator * b.denominator - b.numerator * a.denominator, a.denominator * b.denominator);
+}
+/**
+* `base ^ exponent` for an integer exponent, or `undefined` for `0 ^ -n` and for results with a
+* part beyond `limit` bits. The size is checked before the power is computed.
+*/
+function power(base, exponent, limit = MAX_RATIONAL_BITS) {
+	if (!Number.isSafeInteger(exponent)) return void 0;
+	if (exponent === 0) return ONE;
+	const magnitude = Math.abs(exponent);
+	const size = Math.max(bitLength(base.numerator), bitLength(base.denominator));
+	if (size > 1 && (size - 1) * magnitude > limit) return void 0;
+	const n = BigInt(magnitude);
+	return exponent > 0 ? rational(base.numerator ** n, base.denominator ** n, limit) : rational(base.denominator ** n, base.numerator ** n, limit);
+}
+/** Orders two rationals exactly. */
+function compare(a, b) {
+	const left = a.numerator * b.denominator;
+	const right = b.numerator * a.denominator;
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+const DECIMAL_TEXT = /^([+-]?)([0-9]+)(?:\.([0-9]+))?(?:[eE]([+-]?[0-9]+))?$/;
+/**
+* Parses decimal text with an optional exponent, such as `1e-3`, `980665e-5` or `3.14159`, as the
+* exact rational it denotes. This is the number format of the essence file's `value` attributes.
+*/
+function parseDecimalText(text) {
+	const match = DECIMAL_TEXT.exec(text);
+	if (match === null) return void 0;
+	const [, sign = "", integer = "", fraction = "", exponentText = "0"] = match;
+	const exponent = Number(exponentText) - fraction.length;
+	if (!Number.isSafeInteger(exponent) || Math.abs(exponent) * 3 > 7e4) return;
+	const digits = BigInt(integer + fraction) * (sign === "-" ? -1n : 1n);
+	const scale = 10n ** BigInt(Math.abs(exponent));
+	return exponent >= 0 ? rational(digits * scale) : rational(digits, scale);
+}
+/** The number of bits in `|value|`. */
+function bitLength(value) {
+	return value === 0n ? 0 : abs(value).toString(2).length;
+}
+/** The greatest common divisor of two non-negative integers. */
+function gcd(a, b) {
+	while (b !== 0n) [a, b] = [b, a % b];
+	return a;
+}
+function abs(value) {
+	return value < 0n ? -value : value;
+}
+// src/decimal-rational.ts
+const COEFFICIENT_LIMIT = 10n ** BigInt(MAX_DECIMAL_DIGITS);
+/** Whether `coefficient × 10^-scale` is within the Decimal size bound. */
+function fits(coefficient, scale) {
+	return scale <= MAX_DECIMAL_DIGITS && coefficient < COEFFICIENT_LIMIT && -coefficient < COEFFICIENT_LIMIT;
+}
+/** The exact value of a Decimal as a rational. */
+function decimalToRational(value) {
+	return rational(value.coefficient, 10n ** BigInt(value.scale));
+}
+/**
+* Converts an exact result to a Decimal, as the minimal unit system does. A terminating result
+* keeps every digit and at least `minScale` digits after the point, so `1.0 'm'` becomes
+* `100.0 'cm'`; redundant zeros are only dropped when the value would not fit otherwise. A
+* recurring result is rounded once, by Decimal division (28 significant digits).
+*
+* @returns the Decimal, or `undefined` if it is outside the Decimal size bound.
+* @see https://hl7.org/fhirpath/STU3/en/index.html#unit-conversions
+*/
+function rationalToDecimal(value, minScale) {
+	let rest = value.denominator;
+	let twos = 0;
+	let fives = 0;
+	while (rest % 2n === 0n) {
+		rest /= 2n;
+		twos++;
+	}
+	while (rest % 5n === 0n) {
+		rest /= 5n;
+		fives++;
+	}
+	const places = Math.max(twos, fives);
+	if (places > MAX_DECIMAL_DIGITS) return void 0;
+	let coefficient = value.numerator * 2n ** BigInt(places - twos) * 5n ** BigInt(places - fives);
+	if (rest !== 1n) return fits(coefficient, places) && fits(rest, 0) ? Decimal.of(coefficient, places).divide(Decimal.of(rest)) : void 0;
+	let scale = places;
+	if (scale < minScale) {
+		coefficient *= 10n ** BigInt(minScale - scale);
+		scale = minScale;
+	}
+	while (!fits(coefficient, scale) && scale > 0 && coefficient % 10n === 0n) {
+		coefficient /= 10n;
+		scale--;
+	}
+	return fits(coefficient, scale) ? Decimal.of(coefficient, scale) : void 0;
+}
+/**
+* A strictly positive scale as `factor` and optional `divisor` Decimals: a terminating scale is a
+* single exact factor, and a recurring one such as 1/60 keeps both integers so that callers can
+* divide once at the end.
+*/
+function rationalToScale(value) {
+	if (value.numerator <= 0n) return void 0;
+	const exact = isTerminating(value.denominator) ? rationalToDecimal(value, 0) : void 0;
+	if (exact !== void 0) return { factor: exact };
+	return fits(value.numerator, 0) && fits(value.denominator, 0) ? {
+		factor: Decimal.of(value.numerator),
+		divisor: Decimal.of(value.denominator)
+	} : void 0;
+}
+function isTerminating(denominator) {
+	let rest = denominator;
+	while (rest % 2n === 0n) rest /= 2n;
+	while (rest % 5n === 0n) rest /= 5n;
+	return rest === 1n;
+}
+// src/dimension.ts
+/** The dimension of the unity `1`. */
+const DIMENSIONLESS = /* @__PURE__ */ new Map();
+/** The dimension with one axis at exponent 1. */
+function axis(code) {
+	return /* @__PURE__ */ new Map([[code, 1]]);
+}
+/**
+* `a × b^exponent`, or `undefined` if an exponent leaves the safe integer range.
+*/
+function combineDimensions(a, b, exponent = 1) {
+	const result = new Map(a);
+	for (const [code, value] of b) {
+		const product = value * exponent;
+		const sum = (result.get(code) ?? 0) + product;
+		if (!Number.isSafeInteger(product) || !Number.isSafeInteger(sum)) return void 0;
+		if (sum === 0) result.delete(code);
+		else result.set(code, sum);
+	}
+	return result;
+}
+/** Whether two dimensions are the same, so that their units are commensurable. */
+function sameDimension(a, b) {
+	if (a.size !== b.size) return false;
+	for (const [code, value] of a) if (b.get(code) !== value) return false;
+	return true;
+}
+/** Characters that end a symbol outside square brackets. */
+const DELIMITERS = /* @__PURE__ */ new Set([
+	".",
+	"/",
+	"(",
+	")",
+	"{",
+	"}"
+]);
+const DIGITS = /^[0-9]+$/;
+/**
+* Parses the syntax of a case-sensitive UCUM unit expression without looking up any symbol, so
+* `xyz` parses here and is rejected later. Whitespace and characters outside ASCII 33–126 are
+* invalid.
+*
+* @returns the term, or `undefined` if the text is not a syntactically valid unit expression.
+* @see https://ucum.org/ucum#section-Syntax-Rules
+*/
+function parseUnitExpression(text) {
+	if (text.length === 0) return void 0;
+	for (let index = 0; index < text.length; index++) {
+		const code = text.charCodeAt(index);
+		if (code < 33 || code > 126) return void 0;
+	}
+	const leading = text.startsWith("/");
+	const cursor = { index: leading ? 1 : 0 };
+	const term = parseTerm(text, cursor, leading ? -1 : 1, 0);
+	return term !== void 0 && cursor.index === text.length ? term : void 0;
+}
+function parseTerm(text, cursor, first, depth) {
+	const factors = [];
+	let operator = first;
+	for (;;) {
+		const component = parseComponent(text, cursor, depth);
+		if (component === void 0) return void 0;
+		factors.push({
+			operator,
+			component
+		});
+		const next = text[cursor.index];
+		if (next === ".") operator = 1;
+		else if (next === "/") operator = -1;
+		else return { factors };
+		cursor.index++;
+	}
+}
+function parseComponent(text, cursor, depth) {
+	const start = cursor.index;
+	const first = text[start];
+	if (first === "(") {
+		if (depth >= 32) return void 0;
+		cursor.index++;
+		const term = parseTerm(text, cursor, 1, depth + 1);
+		if (term === void 0 || text[cursor.index] !== ")") return void 0;
+		cursor.index++;
+		return {
+			kind: "group",
+			term
+		};
+	}
+	if (first === "{") {
+		const annotation = parseAnnotation(text, cursor);
+		return annotation === void 0 ? void 0 : {
+			kind: "annotation",
+			text: annotation
+		};
+	}
+	let index = start;
+	let brackets = 0;
+	for (; index < text.length; index++) {
+		const char = text.charAt(index);
+		if (char === "[") brackets++;
+		else if (char === "]") {
+			if (brackets === 0) return void 0;
+			brackets--;
+		} else if (brackets === 0 && DELIMITERS.has(char)) break;
+	}
+	if (brackets !== 0 || index === start) return void 0;
+	const run = text.slice(start, index);
+	cursor.index = index;
+	if (DIGITS.test(run)) return {
+		kind: "number",
+		value: BigInt(run),
+		exponent: 1
+	};
+	const split = exponentStart(run);
+	const symbol = run.slice(0, split);
+	const exponent = split === run.length ? 1 : Number(run.slice(split));
+	if (!Number.isSafeInteger(exponent)) return void 0;
+	if (DIGITS.test(symbol)) return {
+		kind: "number",
+		value: BigInt(symbol),
+		exponent
+	};
+	let annotation;
+	if (text[cursor.index] === "{") {
+		annotation = parseAnnotation(text, cursor);
+		if (annotation === void 0) return void 0;
+	}
+	return {
+		kind: "symbol",
+		symbol,
+		exponent,
+		annotation
+	};
+}
+/**
+* Where the exponent of a symbol starts: its trailing digits with an optional sign (§9), or the
+* end of the symbol if it has none. A linear scan, so long input cannot cause backtracking.
+*/
+function exponentStart(run) {
+	let start = run.length;
+	while (start > 0 && isDigit(run.charCodeAt(start - 1))) start--;
+	if (start === run.length) return run.length;
+	const sign = run[start - 1];
+	if (sign === "+" || sign === "-") start--;
+	return start === 0 ? run.length : start;
+}
+function isDigit(code) {
+	return code >= 48 && code <= 57;
+}
+/** Reads `{…}` at the cursor; the text inside may not contain another curly brace. */
+function parseAnnotation(text, cursor) {
+	const end = text.indexOf("}", cursor.index + 1);
+	if (end === -1) return void 0;
+	const annotation = text.slice(cursor.index + 1, end);
+	if (annotation.includes("{")) return void 0;
+	cursor.index = end + 1;
+	return annotation;
+}
+// src/resolve-unit.ts
+const UNSUPPORTED = Object.freeze({ kind: "unsupported" });
+/**
+* Resolves a case-sensitive UCUM expression such as `mg/dL` or `kg.m/s2` against the symbol
+* tables. Annotations are ignored (§12).
+*
+* @returns the unit, or `undefined` if it is invalid, uses an unknown symbol, has a zero
+*   number, or a magnitude on the way needs more than {@link MAX_MAGNITUDE_BITS} bits.
+* @see https://ucum.org/ucum#section-Semantics
+*/
+function resolveUnit(text, lookup) {
+	const syntax = parseUnitExpression(text);
+	if (syntax === void 0) return void 0;
+	const state = {
+		magnitude: ONE,
+		dimension: DIMENSIONLESS,
+		scalar: ONE,
+		arbitrary: false,
+		special: false,
+		terms: []
+	};
+	if (!accumulate(syntax, 1, state, lookup)) return void 0;
+	if (state.special) return resolveSpecial(syntax, lookup);
+	return {
+		magnitude: state.magnitude,
+		dimension: state.dimension,
+		terms: state.terms,
+		scalar: state.scalar,
+		arbitrary: state.arbitrary,
+		special: void 0
+	};
+}
+function accumulate(term, sign, state, lookup) {
+	for (const { operator, component } of term.factors) {
+		const direction = sign === operator ? 1 : -1;
+		switch (component.kind) {
+			case "annotation": break;
+			case "group":
+				if (!accumulate(component.term, direction, state, lookup)) return false;
+				break;
+			case "number": {
+				const value = power({
+					numerator: component.value,
+					denominator: 1n
+				}, component.exponent, MAX_MAGNITUDE_BITS);
+				const scaled = value === void 0 ? void 0 : power(value, direction);
+				if (scaled === void 0 || scaled.numerator === 0n) return false;
+				const magnitude = multiply(state.magnitude, scaled, MAX_MAGNITUDE_BITS);
+				const scalar = multiply(state.scalar, scaled, MAX_MAGNITUDE_BITS);
+				if (magnitude === void 0 || scalar === void 0) return false;
+				state.magnitude = magnitude;
+				state.scalar = scalar;
+				break;
+			}
+			case "symbol": {
+				const unit = simpleUnit(component.symbol, lookup);
+				if (unit === void 0) return false;
+				if (unit.atom.special !== void 0) {
+					state.special = true;
+					break;
+				}
+				const exponent = component.exponent * direction;
+				const perUnit = multiply(unit.prefix, unit.atom.magnitude, MAX_MAGNITUDE_BITS);
+				const scaled = perUnit === void 0 ? void 0 : power(perUnit, exponent, MAX_MAGNITUDE_BITS);
+				const magnitude = scaled === void 0 ? void 0 : multiply(state.magnitude, scaled, MAX_MAGNITUDE_BITS);
+				const dimension = combineDimensions(state.dimension, unit.atom.dimension, exponent);
+				if (perUnit === void 0 || magnitude === void 0 || dimension === void 0) return false;
+				state.magnitude = magnitude;
+				state.dimension = dimension;
+				state.arbitrary ||= unit.atom.arbitrary;
+				state.terms.push({
+					symbol: component.symbol,
+					exponent,
+					magnitude: perUnit,
+					dimension: unit.atom.dimension,
+					arbitrary: unit.atom.arbitrary
+				});
+				break;
+			}
+			default: return assertNever(component);
+		}
+	}
+	return true;
+}
+/**
+* Special units take no part in algebra (§22■1). Only a lone, unprefixed special unit with
+* exponent 1, such as `Cel` or `Cel{body}`, keeps its scale.
+*/
+function resolveSpecial(syntax, lookup) {
+	const [only, ...rest] = syntax.factors;
+	const component = only?.component;
+	const atom = rest.length === 0 && only?.operator === 1 && component?.kind === "symbol" && component.exponent === 1 ? lookup.atom(component.symbol) : void 0;
+	if (atom?.special?.kind === "affine") return {
+		magnitude: atom.magnitude,
+		dimension: atom.dimension,
+		terms: [],
+		scalar: ONE,
+		arbitrary: false,
+		special: atom.special
+	};
+	return {
+		magnitude: ONE,
+		dimension: DIMENSIONLESS,
+		terms: [],
+		scalar: ONE,
+		arbitrary: false,
+		special: UNSUPPORTED
+	};
+}
+/**
+* Splits a simple unit into prefix and atom. The prefix is the longest one whose remainder is a
+* metric atom; without such a prefix the whole symbol must be an atom (§4■4).
+*/
+function simpleUnit(symbol, lookup) {
+	for (const code of lookup.prefixCodes) {
+		if (symbol.length <= code.length || !symbol.startsWith(code)) continue;
+		const rest = symbol.slice(code.length);
+		if (!lookup.hasAtom(rest) || !lookup.isMetric(rest)) continue;
+		const atom = lookup.atom(rest);
+		const prefix = lookup.prefix(code);
+		return atom === void 0 || prefix === void 0 ? void 0 : {
+			prefix,
+			atom
+		};
+	}
+	const atom = lookup.atom(symbol);
+	return atom === void 0 ? void 0 : {
+		prefix: ONE,
+		atom
+	};
+}
+function assertNever(value) {
+	return value;
+}
+// src/ucum-unit-system.ts
+/**
+* The UCUM counterpart of each calendar keyword. Week to millisecond are equal to theirs; year and
+* month are only equivalent to `a` and `mo`.
+* @see https://hl7.org/fhirpath/STU3/#time-valued-quantities
+*/
+const CALENDAR_UCUM = Object.freeze({
+	year: "a",
+	month: "mo",
+	week: "wk",
+	day: "d",
+	hour: "h",
+	minute: "min",
+	second: "s",
+	millisecond: "ms"
+});
+/**
+* Creates a UCUM unit system from resolved symbol tables.
+*
+* Calendar keywords and the units the minimal unit system knows (`1` and the UCUM time units)
+* are handed to `minimalUnitSystem` whenever both units of an operation are among them, so the
+* calendar rules stay exactly as in core. Other units are resolved as UCUM expressions:
+* commensurable units convert exactly, `Cel` and `[degF]` convert on their offset scales, and
+* arbitrary or other special units only match the identical unit.
+*/
+function createUcumUnitSystem(lookup) {
+	const resolve = (unit) => resolveUnit(unit, lookup);
+	function convertUcum(value, from, to) {
+		const source = commensurable(resolve(from), resolve(to));
+		if (source === void 0) return void 0;
+		const exact = decimalToRational(value);
+		const base = exact === void 0 ? void 0 : toBase(exact, source[0]);
+		const result = base === void 0 ? void 0 : fromBase(base, source[1]);
+		return result === void 0 ? void 0 : rationalToDecimal(result, value.scale);
+	}
+	function compareUcum(a, from, b, to) {
+		const units = commensurable(resolve(from), resolve(to));
+		if (units === void 0) return void 0;
+		const left = decimalToRational(a);
+		const right = decimalToRational(b);
+		const leftBase = left === void 0 ? void 0 : toBase(left, units[0]);
+		const rightBase = right === void 0 ? void 0 : toBase(right, units[1]);
+		return leftBase === void 0 || rightBase === void 0 ? void 0 : compare(leftBase, rightBase);
+	}
+	function algebra(a, b, sign) {
+		const left = resolve(a);
+		const right = resolve(b);
+		if (left?.special !== void 0 || right?.special !== void 0) return void 0;
+		if (b === "1") return {
+			unit: a,
+			factor: Decimal.ONE
+		};
+		if (sign === 1 && a === "1") return {
+			unit: b,
+			factor: Decimal.ONE
+		};
+		if (sign === -1 && a === b) return {
+			unit: "1",
+			factor: Decimal.ONE
+		};
+		if (left === void 0 || right === void 0) return void 0;
+		const product = canonicalProduct(left, right, sign);
+		return product === void 0 || resolve(product.unit) === void 0 ? void 0 : product;
+	}
+	return Object.freeze({
+		parse(unit) {
+			return minimalUnitSystem.parse(unit) ?? (resolve(unit) === void 0 ? void 0 : { unit });
+		},
+		convert(value, from, to, options) {
+			const source = calendarKeyword(from);
+			const target = calendarKeyword(to);
+			if ((source ?? from) === (target ?? to)) return value;
+			if (isMinimalUnit(from) && isMinimalUnit(to)) return minimalUnitSystem.convert(value, from, to, options);
+			const explicit = options?.explicit === true;
+			const equivalence = !explicit && options?.equivalence === true;
+			const a = source === void 0 ? from : ucumCounterpart(source, equivalence);
+			const b = target === void 0 ? to : ucumCounterpart(target, equivalence || explicit);
+			return a === void 0 || b === void 0 ? void 0 : convertUcum(value, a, b);
+		},
+		compare(a, from, b, to) {
+			const source = calendarKeyword(from);
+			const target = calendarKeyword(to);
+			if ((source ?? from) === (target ?? to)) return a.compare(b);
+			if (isMinimalUnit(from) && isMinimalUnit(to)) return minimalUnitSystem.compare?.(a, from, b, to);
+			const x = source === void 0 ? from : ucumCounterpart(source, false);
+			const y = target === void 0 ? to : ucumCounterpart(target, false);
+			return x === void 0 || y === void 0 ? void 0 : compareUcum(a, x, b, y);
+		},
+		multiply(a, b) {
+			if (calendarKeyword(a) !== void 0 || calendarKeyword(b) !== void 0) return minimalUnitSystem.multiply(a, b);
+			return algebra(a, b, 1);
+		},
+		divide(a, b) {
+			if (calendarKeyword(a) !== void 0 || calendarKeyword(b) !== void 0) return minimalUnitSystem.divide(a, b);
+			return algebra(a, b, -1);
+		}
+	});
+}
+/** Both units if they can be converted into each other, else `undefined`. */
+function commensurable(a, b) {
+	if (a === void 0 || b === void 0) return void 0;
+	if (a.special?.kind === "unsupported" || b.special?.kind === "unsupported") return void 0;
+	if (a.arbitrary || b.arbitrary) return void 0;
+	return sameDimension(a.dimension, b.dimension) ? [a, b] : void 0;
+}
+/** The value in base units: `(value + offset) × magnitude` for `Cel` and `[degF]`. */
+function toBase(value, unit) {
+	const shifted = unit.special?.kind === "affine" ? add(value, unit.special.offset) : value;
+	return shifted === void 0 ? void 0 : multiply(shifted, unit.magnitude);
+}
+function fromBase(base, unit) {
+	const scaled = divide(base, unit.magnitude);
+	if (scaled === void 0 || unit.special?.kind !== "affine") return scaled;
+	return subtract(scaled, unit.special.offset);
+}
+/**
+* The product or quotient of two units in canonical form. Identical simple units add their
+* exponents (`cm2 / cm` is `cm`); a simple unit commensurable with an earlier one that has not
+* cancelled out is converted into it (`m/s × min` is `m` with factor 60, and `cm / m` is `1` with
+* factor 1/100). Arbitrary and dimensionless units only combine with identical ones. Integer
+* factors and annotations are folded into the scale.
+* @see https://hl7.org/fhirpath/STU3/en/index.html#multiplication
+*/
+function canonicalProduct(left, right, sign) {
+	let scale = sign === 1 ? multiply(left.scalar, right.scalar, MAX_MAGNITUDE_BITS) : divide(left.scalar, right.scalar, MAX_MAGNITUDE_BITS);
+	const terms = [];
+	const bySymbol = /* @__PURE__ */ new Map();
+	const byDimension = /* @__PURE__ */ new Map();
+	const inputs = [...left.terms.map((term) => ({
+		term,
+		exponent: term.exponent
+	})), ...right.terms.map((term) => ({
+		term,
+		exponent: term.exponent * sign
+	}))];
+	for (const input of inputs) {
+		if (scale === void 0) return void 0;
+		const merges = !input.term.arbitrary && input.term.dimension.size > 0;
+		const key = merges ? dimensionKey(input.term.dimension) : "";
+		const same = bySymbol.get(input.term.symbol);
+		const target = same ?? (merges ? byDimension.get(key) : void 0);
+		if (target === void 0) {
+			const entry = {
+				term: input.term,
+				exponent: input.exponent
+			};
+			terms.push(entry);
+			bySymbol.set(input.term.symbol, entry);
+			if (merges) byDimension.set(key, entry);
+			continue;
+		}
+		if (target !== same) {
+			const ratio = divide(input.term.magnitude, target.term.magnitude, MAX_MAGNITUDE_BITS);
+			const factor = ratio === void 0 ? void 0 : power(ratio, input.exponent, MAX_MAGNITUDE_BITS);
+			scale = factor === void 0 ? void 0 : multiply(scale, factor, MAX_MAGNITUDE_BITS);
+		}
+		target.exponent += input.exponent;
+		if (!Number.isSafeInteger(target.exponent)) return void 0;
+		if (target.exponent === 0) {
+			bySymbol.delete(target.term.symbol);
+			if (byDimension.get(key) === target) byDimension.delete(key);
+		}
+	}
+	if (scale === void 0) return void 0;
+	const parts = rationalToScale(scale);
+	if (parts === void 0) return void 0;
+	const unit = formatTerms(terms);
+	return parts.divisor === void 0 ? {
+		unit,
+		factor: parts.factor
+	} : {
+		unit,
+		factor: parts.factor,
+		divisor: parts.divisor
+	};
+}
+/** A string that two dimensions share exactly when they are the same. */
+function dimensionKey(dimension) {
+	return JSON.stringify([...dimension].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+/** Writes terms as `a.b2/c/d3`, or `/s` without a numerator, or `1` when nothing is left. */
+function formatTerms(terms) {
+	let numerator = "";
+	let denominator = "";
+	for (const { term, exponent } of terms) if (exponent > 0) numerator += `${numerator === "" ? "" : "."}${term.symbol}${exponent === 1 ? "" : exponent}`;
+	else if (exponent < 0) denominator += `/${term.symbol}${exponent === -1 ? "" : -exponent}`;
+	return numerator === "" && denominator === "" ? "1" : numerator + denominator;
+}
+/** The singular calendar keyword a unit spells, if any (`weeks` is `week`). */
+function calendarKeyword(unit) {
+	const singular = unit.endsWith("s") ? unit.slice(0, -1) : unit;
+	if (Object.hasOwn(CALENDAR_UCUM, unit)) return unit;
+	return Object.hasOwn(CALENDAR_UCUM, singular) ? singular : void 0;
+}
+/** The UCUM unit a calendar keyword may be related to; year/month only with equivalence. */
+function ucumCounterpart(keyword, yearAndMonth) {
+	if ((keyword === "year" || keyword === "month") && !yearAndMonth) return void 0;
+	return Object.hasOwn(CALENDAR_UCUM, keyword) ? CALENDAR_UCUM[keyword] : void 0;
+}
+/** Units the minimal unit system knows: `1`, calendar keywords and the UCUM time units. */
+function isMinimalUnit(unit) {
+	return minimalUnitSystem.parse(unit) !== void 0;
+}
+// src/unit-table.ts
+/**
+* The special-unit functions Callis converts, by function name in the essence file. Each is the
+* affine relation `proper = (value + offset) × magnitude`: `Cel` gives kelvin = °C + 273.15, and
+* `degF` gives (5/9 K) multiples = °F + 459.67. The essence file names these functions; their
+* definitions come from the UCUM specification text. Other special units are not convertible.
+* @see https://ucum.org/ucum#section-Special-Units-on-non-ratio-Scales
+*/
+const AFFINE_OFFSETS = Object.freeze({
+	Cel: Object.freeze({
+		numerator: 5463n,
+		denominator: 20n
+	}),
+	degF: Object.freeze({
+		numerator: 45967n,
+		denominator: 100n
+	})
+});
+/** A lookup that knows no units, for when the essence data cannot be read. */
+const EMPTY_UNIT_LOOKUP = Object.freeze({
+	hasAtom: () => false,
+	isMetric: () => false,
+	atom: () => void 0,
+	prefix: () => void 0,
+	prefixCodes: Object.freeze([])
+});
+/**
+* Resolves every prefix, base unit and unit of the essence data to a magnitude and dimension in
+* base units. Definitions refer to other units, so each atom is resolved once, on first need.
+* An atom whose definition is invalid, circular or out of bounds is left out.
+*/
+function buildUnitTable(data) {
+	const prefixes = /* @__PURE__ */ new Map();
+	for (const prefix of data.prefixes) {
+		const value = parseDecimalText(prefix.value);
+		if (value !== void 0 && value.numerator > 0n) prefixes.set(prefix.code, value);
+	}
+	const atoms = /* @__PURE__ */ new Map();
+	for (const base of data.baseUnits) atoms.set(base.code, {
+		code: base.code,
+		isMetric: true,
+		magnitude: ONE,
+		dimension: axis(base.code),
+		arbitrary: false,
+		special: void 0
+	});
+	const definitions = /* @__PURE__ */ new Map();
+	for (const unit of data.units) if (!atoms.has(unit.code) && !definitions.has(unit.code)) definitions.set(unit.code, unit);
+	const prefixCodes = Object.freeze([...prefixes.keys()].sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0)));
+	const pending = /* @__PURE__ */ new Set();
+	const failed = /* @__PURE__ */ new Set();
+	const lookup = {
+		hasAtom: (code) => atoms.has(code) || definitions.has(code),
+		isMetric: (code) => atoms.get(code)?.isMetric ?? definitions.get(code)?.isMetric ?? false,
+		atom: (code) => {
+			const known = atoms.get(code);
+			if (known !== void 0) return known;
+			const definition = definitions.get(code);
+			if (definition === void 0 || pending.has(code) || failed.has(code)) return void 0;
+			pending.add(code);
+			const atom = defineAtom(definition, lookup);
+			pending.delete(code);
+			if (atom === void 0) failed.add(code);
+			else atoms.set(code, atom);
+			return atom;
+		},
+		prefix: (code) => prefixes.get(code),
+		prefixCodes
+	};
+	for (const code of definitions.keys()) lookup.atom(code);
+	return Object.freeze({
+		hasAtom: (code) => atoms.has(code),
+		isMetric: (code) => atoms.get(code)?.isMetric ?? false,
+		atom: (code) => atoms.get(code),
+		prefix: (code) => prefixes.get(code),
+		prefixCodes
+	});
+}
+function defineAtom(definition, lookup) {
+	const source = definition.function ?? {
+		value: definition.value ?? "",
+		unit: definition.unit
+	};
+	const value = parseDecimalText(source.value);
+	const unit = resolveUnit(source.unit, lookup);
+	if (value === void 0 || value.numerator <= 0n || unit === void 0 || unit.special !== void 0) return;
+	const magnitude = multiply(value, unit.magnitude, MAX_MAGNITUDE_BITS);
+	if (magnitude === void 0) return void 0;
+	let special;
+	if (definition.function !== void 0) {
+		const name = definition.function.name;
+		const offset = Object.hasOwn(AFFINE_OFFSETS, name) ? AFFINE_OFFSETS[name] : void 0;
+		special = offset === void 0 ? { kind: "unsupported" } : {
+			kind: "affine",
+			offset
+		};
+	}
+	const dimension = definition.isArbitrary ? combineDimensions(unit.dimension, axis(definition.code)) : unit.dimension;
+	if (dimension === void 0) return void 0;
+	return {
+		code: definition.code,
+		isMetric: definition.isMetric,
+		magnitude,
+		dimension,
+		arbitrary: definition.isArbitrary || unit.arbitrary,
+		special
+	};
+}
+// src/index.ts
+/**
+* A `UnitSystem` with the full UCUM: prefixes, every unit of the essence file, unit expressions
+* such as `mg/dL` or `kg.m/s2`, annotations, `10*n` and `10^n`. Commensurable units convert
+* exactly; `Cel` and `[degF]` convert on their offset scales; arbitrary units and other special
+* units only match the identical unit. Calendar keywords keep the rules of the minimal unit
+* system in `@callis/core`. Unknown or invalid units give `undefined`; nothing throws.
+*
+* @example
+* ```ts
+* import { Decimal } from '@callis/core';
+* import { ucum } from '@callis/ucum';
+*
+* ucum.convert(Decimal.ONE, 'mg/dL', 'g/L')?.toString(); // '0.01'
+* ucum.compare?.(Decimal.ONE, 'kg', Decimal.of(1000n), 'g'); // 0
+* ```
+* @see https://ucum.org/ucum
+* @see https://hl7.org/fhirpath/STU3/#quantity
+*/
+const ucum = /* @__PURE__ */ createUcumUnitSystem(/* @__PURE__ */ loadUnitTable());
+function loadUnitTable() {
+	const essence = readEssence(UCUM_ESSENCE_XML);
+	return essence === void 0 ? EMPTY_UNIT_LOOKUP : buildUnitTable(essence);
+}
+export { ucum };
+
+//# sourceMappingURL=index.js.map