fhirpath-ts 0.0.0-bootstrap.0

package/src/values/quantity.ts

@@ -0,0 +1,358 @@
+import { Decimal } from './decimal.ts'
+import { asNumeric } from './numeric.ts'
+import { type QuantityValue, SYSTEM_QUANTITY, type TypedValue, typeLocalName } from './typed-value.ts'
+import { canonicalizeUnit, sameDimensions } from './ucum.ts'
+
+/** FHIR Quantity and its specializations coerce to System.Quantity for comparison. */
+const FHIR_QUANTITY_TYPES = new Set([
+  'Quantity',
+  'Age',
+  'Distance',
+  'Duration',
+  'Count',
+  'SimpleQuantity',
+  'MoneyQuantity',
+])
+
+/**
+ * Calendar duration data used to build every lookup below. Years and months use
+ * months; smaller units use seconds. Week-and-smaller UCUM forms are equal to
+ * calendar values. Year and month UCUM forms are equivalent only.
+ */
+interface CalendarUnit {
+  plural: string
+  family: 'month' | 'second'
+  factor: string
+  ucum: string
+  exact: boolean
+}
+
+const CALENDAR_UNITS: Readonly<Record<string, CalendarUnit>> = {
+  year: { plural: 'years', family: 'month', factor: '12', ucum: 'a', exact: false },
+  month: { plural: 'months', family: 'month', factor: '1', ucum: 'mo', exact: false },
+  week: { plural: 'weeks', family: 'second', factor: '604800', ucum: 'wk', exact: true },
+  day: { plural: 'days', family: 'second', factor: '86400', ucum: 'd', exact: true },
+  hour: { plural: 'hours', family: 'second', factor: '3600', ucum: 'h', exact: true },
+  minute: { plural: 'minutes', family: 'second', factor: '60', ucum: 'min', exact: true },
+  second: { plural: 'seconds', family: 'second', factor: '1', ucum: 's', exact: true },
+  millisecond: { plural: 'milliseconds', family: 'second', factor: '0.001', ucum: 'ms', exact: true },
+}
+
+const CALENDAR_UNIT_ENTRIES = Object.entries(CALENDAR_UNITS)
+
+/** Plural keyword → singular (`years` → `year`). */
+const SINGULAR_CALENDAR_UNITS: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.map(([singular, unit]) => [unit.plural, singular])
+)
+
+/** Year/month family, factor in months. */
+const MONTH_FAMILY: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.filter(([, unit]) => unit.family === 'month').map(([singular, unit]) => [singular, unit.factor])
+)
+
+/** Week-and-below family, factor in seconds (all exact). */
+const SECOND_FAMILY: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.filter(([, unit]) => unit.family === 'second').map(([singular, unit]) => [
+    singular,
+    unit.factor,
+  ])
+)
+
+/** Calendar words that equal their UCUM twin (week and below). */
+const CALENDAR_TO_UCUM_EXACT: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.filter(([, unit]) => unit.exact).map(([singular, unit]) => [singular, unit.ucum])
+)
+
+/** Every calendar word to its UCUM twin (equivalence-only for year/month). */
+const CALENDAR_TO_UCUM_LOOSE: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.map(([singular, unit]) => [singular, unit.ucum])
+)
+
+/**
+ * FHIR Quantities with UCUM time-valued codes convert to calendar duration
+ * keywords (FHIR fhirpath page, "Use of FHIR Quantity"): a Duration of 1 'a'
+ * behaves as `1 year`.
+ */
+const UCUM_TIME_TO_CALENDAR: Readonly<Record<string, string>> = Object.fromEntries(
+  CALENDAR_UNIT_ENTRIES.map(([singular, unit]) => [unit.ucum, singular])
+)
+
+const UCUM_SYSTEM = 'http://unitsofmeasure.org'
+
+/** Read a TypedValue as a quantity: System.Quantity directly, FHIR Quantity objects by value+code/unit. */
+export function coerceQuantity(item: TypedValue): QuantityValue | undefined {
+  if (item.type === SYSTEM_QUANTITY) {
+    return item.value as QuantityValue
+  }
+  if (!(item.type.startsWith('FHIR.') && FHIR_QUANTITY_TYPES.has(typeLocalName(item.type)))) {
+    return undefined
+  }
+  const raw = item.value as { value?: unknown; code?: unknown; unit?: unknown; system?: unknown }
+  if (typeof raw !== 'object' || raw === null || typeof raw.value !== 'number') {
+    return undefined
+  }
+  const value = Decimal.fromNumber(raw.value)
+  if (!value) {
+    return undefined
+  }
+  if (raw.system === UCUM_SYSTEM && typeof raw.code === 'string' && UCUM_TIME_TO_CALENDAR[raw.code] !== undefined) {
+    return { value, unit: UCUM_TIME_TO_CALENDAR[raw.code] as string, calendar: true }
+  }
+  const unit = typeof raw.code === 'string' ? raw.code : typeof raw.unit === 'string' ? raw.unit : '1'
+  return { value, unit, calendar: false }
+}
+
+/** A quantity as-is, or a number implicitly converted to a unity quantity (spec §5.5). */
+export function promoteQuantity(item: TypedValue): QuantityValue | undefined {
+  const coerced = coerceQuantity(item)
+  if (coerced) {
+    return coerced
+  }
+  const numeric = asNumeric(item)
+  return numeric === undefined ? undefined : { value: numeric.value, unit: '1', calendar: false }
+}
+
+/**
+ * Coerce a pair of operands for quantity operations. Integers, Longs, and
+ * Decimals implicitly convert to unity quantities (spec §5.5) when the other
+ * side is a quantity: `9 = 9 '1'` and `2 * 4 'kg'` both work.
+ */
+export function coerceQuantityPair(a: TypedValue, b: TypedValue): [QuantityValue, QuantityValue] | undefined {
+  const quantityA = coerceQuantity(a)
+  const quantityB = coerceQuantity(b)
+  if (quantityA && quantityB) {
+    return [quantityA, quantityB]
+  }
+  if (quantityA) {
+    const numeric = asNumeric(b)
+    return numeric ? [quantityA, { value: numeric.value, unit: '1', calendar: false }] : undefined
+  }
+  if (quantityB) {
+    const numeric = asNumeric(a)
+    return numeric ? [{ value: numeric.value, unit: '1', calendar: false }, quantityB] : undefined
+  }
+  return undefined
+}
+
+/** `4 days` and `1 day` use the same unit; plurals normalize to the singular word. */
+export function normalizeCalendarUnit(unit: string): string {
+  return SINGULAR_CALENDAR_UNITS[unit] ?? unit
+}
+
+function calendarFamily(unit: string): { family: 'month' | 'second'; factor: Decimal } | undefined {
+  const singular = normalizeCalendarUnit(unit)
+  const monthFactor = MONTH_FAMILY[singular]
+  if (monthFactor !== undefined) {
+    return { family: 'month', factor: Decimal.fromString(monthFactor) as Decimal }
+  }
+  const secondFactor = SECOND_FAMILY[singular]
+  if (secondFactor !== undefined) {
+    return { family: 'second', factor: Decimal.fromString(secondFactor) as Decimal }
+  }
+  /* v8 ignore next 2 -- the lexer only produces the units above */
+  return undefined
+}
+
+/**
+ * Compare two quantities. Undefined when the units are not comparable: different
+ * dimensions, opaque units with different spellings, or calendar words above
+ * seconds against UCUM time units (those are only equivalent, spec §6.1).
+ */
+export function compareQuantities(a: QuantityValue, b: QuantityValue): -1 | 0 | 1 | undefined {
+  if (a.calendar && b.calendar) {
+    const familyA = calendarFamily(a.unit)
+    const familyB = calendarFamily(b.unit)
+    if (!(familyA && familyB) || familyA.family !== familyB.family) {
+      return undefined
+    }
+    return a.value.multiply(familyA.factor).compare(b.value.multiply(familyB.factor))
+  }
+  if (a.calendar || b.calendar) {
+    const [calendar, ucum] = a.calendar ? [a, b] : [b, a]
+    const exactTwin = CALENDAR_TO_UCUM_EXACT[normalizeCalendarUnit(calendar.unit)]
+    if (exactTwin === undefined) {
+      return undefined
+    }
+    const comparison = compareUcum({ ...calendar, unit: exactTwin, calendar: false }, ucum)
+    return comparison === undefined ? undefined : a.calendar ? comparison : (-comparison as -1 | 0 | 1)
+  }
+  return compareUcum(a, b)
+}
+
+function compareUcum(a: QuantityValue, b: QuantityValue): -1 | 0 | 1 | undefined {
+  if (a.unit === b.unit) {
+    return a.value.compare(b.value)
+  }
+  const canonicalA = canonicalizeUnit(a.unit)
+  const canonicalB = canonicalizeUnit(b.unit)
+  if (!(canonicalA && canonicalB && sameDimensions(canonicalA, canonicalB))) {
+    return undefined
+  }
+  return a.value.multiply(canonicalA.factor).compare(b.value.multiply(canonicalB.factor))
+}
+
+/**
+ * Equivalence: calendar durations match their UCUM twins (`1 year ~ 1 'a'`), and
+ * values compare after conversion, rounded to the least precise operand
+ * (`4 'g' ~ 4040 'mg'` is true: 4.04 g rounds to 4 at scale 0).
+ */
+export function quantitiesEquivalent(a: QuantityValue, b: QuantityValue): boolean {
+  const ucumA = asUcum(a)
+  const ucumB = asUcum(b)
+  const scale = Math.max(Math.min(a.value.scale, b.value.scale), 0)
+  const converted = convertQuantity(ucumB, ucumA.unit)
+  if (converted !== undefined) {
+    return ucumA.value.round(scale).equals(converted.value.round(scale))
+  }
+  return compareUcum({ ...ucumA, value: ucumA.value.round(scale) }, { ...ucumB, value: ucumB.value.round(scale) }) === 0
+}
+
+/** A calendar duration as its loose UCUM twin (`1 year` → `1 'a'`); UCUM passes through. */
+export function calendarToUcumLoose(quantity: QuantityValue): QuantityValue {
+  return asUcum(quantity)
+}
+
+function asUcum(quantity: QuantityValue): QuantityValue {
+  if (!quantity.calendar) {
+    return quantity
+  }
+  const twin = CALENDAR_TO_UCUM_LOOSE[normalizeCalendarUnit(quantity.unit)]
+  /* v8 ignore next 3 -- every calendar word has a loose twin */
+  if (twin === undefined) {
+    return quantity
+  }
+  return { ...quantity, unit: twin, calendar: false }
+}
+
+/** True for `year`/`days`/... — never for UCUM codes like `wk` or `mo`. */
+function isCalendarWord(unit: string): boolean {
+  const singular = normalizeCalendarUnit(unit)
+  return MONTH_FAMILY[singular] !== undefined || SECOND_FAMILY[singular] !== undefined
+}
+
+/**
+ * Convert to another unit. UCUM↔UCUM converts through base dimensions; calendar
+ * words convert within their family (`12 months` → `1 year`, `1 week` → `7 days`),
+ * and week-and-below calendar words cross into UCUM through their exact twins
+ * (`1 'wk'` → `7 days`). Year and month never convert to definite UCUM durations.
+ * Undefined when no exact conversion exists.
+ */
+export function convertQuantity(quantity: QuantityValue, targetUnit: string): QuantityValue | undefined {
+  if (quantity.unit === targetUnit && !quantity.calendar === !isCalendarWord(targetUnit)) {
+    return quantity
+  }
+  const targetIsCalendar = isCalendarWord(targetUnit)
+  if (quantity.calendar || targetIsCalendar) {
+    return convertCalendar(quantity, targetUnit, targetIsCalendar)
+  }
+  const source = canonicalizeUnit(quantity.unit)
+  const target = canonicalizeUnit(targetUnit)
+  if (!(source && target && sameDimensions(source, target))) {
+    return undefined
+  }
+  const converted = quantity.value.multiply(source.factor).divide(target.factor)
+  return converted === undefined ? undefined : { value: converted, unit: targetUnit, calendar: false }
+}
+
+function convertCalendar(
+  quantity: QuantityValue,
+  targetUnit: string,
+  targetIsCalendar: boolean
+): QuantityValue | undefined {
+  const sourceFamily = quantity.calendar ? calendarFamily(quantity.unit) : undefined
+  const targetFamily = targetIsCalendar ? calendarFamily(normalizeCalendarUnit(targetUnit)) : undefined
+  if (quantity.calendar && targetIsCalendar) {
+    if (!(sourceFamily && targetFamily) || sourceFamily.family !== targetFamily.family) {
+      return undefined
+    }
+    const converted = quantity.value.multiply(sourceFamily.factor).divide(targetFamily.factor)
+    return converted === undefined ? undefined : { value: converted, unit: targetUnit, calendar: true }
+  }
+  if (quantity.calendar) {
+    // Calendar → UCUM: only week-and-below are definite; year/month stay calendar-only.
+    if (sourceFamily?.family !== 'second') {
+      return undefined
+    }
+    const twin = CALENDAR_TO_UCUM_EXACT[normalizeCalendarUnit(quantity.unit)] as string
+    return convertQuantity({ value: quantity.value, unit: twin, calendar: false }, targetUnit)
+  }
+  // UCUM → calendar word: cross through seconds; year/month targets are indefinite.
+  if (targetFamily?.family !== 'second') {
+    return undefined
+  }
+  const source = canonicalizeUnit(quantity.unit)
+  const secondsPerTarget = canonicalizeUnit(
+    CALENDAR_TO_UCUM_EXACT[normalizeCalendarUnit(targetUnit)] as string
+  ) as NonNullable<ReturnType<typeof canonicalizeUnit>>
+  if (!(source && sameDimensions(source, secondsPerTarget))) {
+    return undefined
+  }
+  const converted = quantity.value.multiply(source.factor).divide(secondsPerTarget.factor)
+  return converted === undefined ? undefined : { value: converted, unit: targetUnit, calendar: true }
+}
+
+/**
+ * Bring two quantities to a shared unit for + and -; the spec picks the more
+ * granular (smaller) unit of the two. Undefined when they cannot be converted.
+ */
+export function alignQuantities(
+  a: QuantityValue,
+  b: QuantityValue
+): { left: Decimal; right: Decimal; unit: string; calendar: boolean } | undefined {
+  if (a.unit === b.unit && a.calendar === b.calendar) {
+    return { left: a.value, right: b.value, unit: a.unit, calendar: a.calendar }
+  }
+  if (a.calendar && b.calendar) {
+    const familyA = calendarFamily(a.unit)
+    const familyB = calendarFamily(b.unit)
+    if (!(familyA && familyB) || familyA.family !== familyB.family) {
+      return undefined
+    }
+    const smaller = familyA.factor.compare(familyB.factor) <= 0 ? a : b
+    const factor = calendarFamily(smaller.unit)?.factor as Decimal
+    return {
+      left: a.value.multiply(familyA.factor).divide(factor) as Decimal,
+      right: b.value.multiply(familyB.factor).divide(factor) as Decimal,
+      unit: normalizeCalendarUnit(smaller.unit),
+      calendar: true,
+    }
+  }
+  if (a.calendar || b.calendar) {
+    const exactA = a.calendar ? CALENDAR_TO_UCUM_EXACT[normalizeCalendarUnit(a.unit)] : a.unit
+    const exactB = b.calendar ? CALENDAR_TO_UCUM_EXACT[normalizeCalendarUnit(b.unit)] : b.unit
+    if (exactA === undefined || exactB === undefined) {
+      return undefined
+    }
+    return alignQuantities(
+      { value: a.value, unit: exactA, calendar: false },
+      { value: b.value, unit: exactB, calendar: false }
+    )
+  }
+  const canonicalA = canonicalizeUnit(a.unit)
+  const canonicalB = canonicalizeUnit(b.unit)
+  if (!(canonicalA && canonicalB && sameDimensions(canonicalA, canonicalB))) {
+    return undefined
+  }
+  const targetUnit = canonicalA.factor.compare(canonicalB.factor) <= 0 ? a.unit : b.unit
+  const left = convertQuantity(a, targetUnit)
+  const right = convertQuantity(b, targetUnit)
+  /* v8 ignore next 3 -- both conversions share the dimensions checked above */
+  if (!(left && right)) {
+    return undefined
+  }
+  return { left: left.value, right: right.value, unit: targetUnit, calendar: false }
+}
+
+/** Compose the result unit of quantity multiplication or division. */
+export function composeUnits(operator: '*' | '/', a: string, b: string): string {
+  if (operator === '*') {
+    if (a === '1') {
+      return b
+    }
+    return b === '1' ? a : `${a}.${b}`
+  }
+  if (a === b) {
+    return '1'
+  }
+  return b === '1' ? a : `${a}/${b}`
+}

package/src/values/temporal-arithmetic.ts

@@ -0,0 +1,231 @@
+import { FhirPathRuntimeError } from '../errors.ts'
+import { daysInMonth, GREGORIAN_UTC_YEAR_OFFSET, Temporal, type TemporalPrecision } from './datetime.ts'
+import { normalizeCalendarUnit } from './quantity.ts'
+import type { QuantityValue } from './typed-value.ts'
+
+/** Position of each precision on the component ladder used for duration conversion. */
+const COMPONENT_LEVELS: Readonly<Record<string, number>> = {
+  year: 0,
+  month: 1,
+  day: 2,
+  hour: 3,
+  minute: 4,
+  second: 5,
+  millisecond: 6,
+}
+
+/** Truncated-division factors for converting a duration one level up (day→month uses 30). */
+const UP_CONVERSION_FACTORS = [12, 30, 24, 60, 60, 1000]
+
+const UCUM_TIME_UNITS: Readonly<Record<string, { level: number; multiplier: number }>> = {
+  wk: { level: 2, multiplier: 7 },
+  d: { level: 2, multiplier: 1 },
+  h: { level: 3, multiplier: 1 },
+  min: { level: 4, multiplier: 1 },
+  s: { level: 5, multiplier: 1 },
+  ms: { level: 6, multiplier: 1 },
+}
+
+const MS_PER_LEVEL: Readonly<Record<number, number>> = {
+  2: 86400000,
+  3: 3600000,
+  4: 60000,
+  5: 1000,
+  6: 1,
+}
+
+interface Duration {
+  /** Component level the duration applies to (0=year ... 6=millisecond). */
+  level: number
+  /** Amount in that component's unit; may be fractional only at the seconds level. */
+  amount: number
+}
+
+function resolveDuration(quantity: QuantityValue): Duration {
+  // The decimal portion of units above seconds is ignored (spec §6.6.7, official
+  // testPlusDate2: 7.7 days adds 7) — truncate before any week/day expansion.
+  const value = quantity.value.toNumber()
+  const wholeAmount = Math.trunc(value)
+  const unit = normalizeCalendarUnit(quantity.unit)
+  if (COMPONENT_LEVELS[unit] !== undefined || unit === 'week') {
+    if (unit === 'week') {
+      return { level: 2, amount: wholeAmount * 7 }
+    }
+    const level = COMPONENT_LEVELS[unit] as number
+    return { level, amount: level >= 5 ? value : wholeAmount }
+  }
+  if (quantity.calendar) {
+    /* v8 ignore next 2 -- the lexer only produces the calendar words above */
+    throw new FhirPathRuntimeError(`Unknown calendar duration unit '${quantity.unit}'`)
+  }
+  const ucum = UCUM_TIME_UNITS[quantity.unit]
+  if (!ucum) {
+    // The spec reserves UCUM 'a' and 'mo' (definite 365/30-day durations) as errors
+    // for calendar arithmetic; calendar words must be used instead.
+    throw new FhirPathRuntimeError(
+      `Cannot use UCUM unit '${quantity.unit}' for date/time arithmetic; use a calendar duration keyword`
+    )
+  }
+  const amount = ucum.level >= 5 ? value * ucum.multiplier : wholeAmount * ucum.multiplier
+  return { level: ucum.level, amount }
+}
+
+/** Week is not a real component; it resolves to days before this table is consulted. */
+function precisionLevel(precision: TemporalPrecision): number {
+  return COMPONENT_LEVELS[precision] as number
+}
+
+/**
+ * `temporal ± quantity` (spec §6.6.7): the duration converts down to the value's
+ * precision with truncation (`@2014 + 23 months` adds 1 year), calendar components
+ * roll over, and day-of-month clamps (`@2020-01-31 + 1 month` → `@2020-02-29`).
+ * Undefined when the resulting year leaves 0001–9999.
+ */
+export function addDuration(temporal: Temporal, quantity: QuantityValue, sign: 1 | -1): Temporal | undefined {
+  const duration = resolveDuration(quantity)
+  // Times have no year/month/day components to add to.
+  const dayLevel = 2
+  if (temporal.kind === 'time' && duration.level <= dayLevel) {
+    throw new FhirPathRuntimeError(`Cannot add a quantity of '${quantity.unit}' to a Time value`)
+  }
+  let level = duration.level
+  let amount = duration.amount * sign
+  let targetLevel = Math.min(precisionLevel(temporal.precision), temporal.kind === 'date' ? 2 : 6)
+  // Fractional seconds add as milliseconds (R5); millisecond-level additions
+  // extend a second-precision value to milliseconds instead of truncating.
+  if (level === 5 && !Number.isInteger(amount)) {
+    level = 6
+    amount = Math.round(amount * 1000)
+  }
+  if (level === 6 && targetLevel === 5) {
+    targetLevel = 6
+  }
+  while (level > targetLevel) {
+    if (level === 2 && targetLevel === 0) {
+      // Days convert straight to years; going through 30-day months undercounts.
+      amount = Math.trunc(amount / 365)
+      level = 0
+      break
+    }
+    amount = Math.trunc(amount / (UP_CONVERSION_FACTORS[level - 1] as number))
+    level -= 1
+  }
+  if (amount === 0) {
+    return temporal
+  }
+  if (level <= 1) {
+    return addCalendarComponent(temporal, level, amount)
+  }
+  return addMilliseconds(temporal, amount * (MS_PER_LEVEL[level] as number))
+}
+
+function addCalendarComponent(temporal: Temporal, level: number, amount: number): Temporal | undefined {
+  let year = temporal.year as number
+  let month = temporal.month
+  if (level === 0) {
+    year += amount
+  } else {
+    const zeroBased = (month ?? 1) - 1 + amount
+    year += Math.floor(zeroBased / 12)
+    month = (((zeroBased % 12) + 12) % 12) + 1
+  }
+  if (year < 1 || year > 9999) {
+    return undefined
+  }
+  let day = temporal.day
+  if (day !== undefined && month !== undefined) {
+    day = Math.min(day, daysInMonth(year, month))
+  }
+  return rebuild(temporal, { year, month, day })
+}
+
+function addMilliseconds(temporal: Temporal, deltaMs: number): Temporal | undefined {
+  if (temporal.kind === 'time') {
+    const baseMs =
+      (temporal.hour ?? 0) * 3600000 +
+      (temporal.minute ?? 0) * 60000 +
+      Math.round(((temporal.second ?? 0) + fractionOf(temporal)) * 1000)
+    // Time arithmetic wraps around the day.
+    const dayMs = 86400000
+    const total = (((baseMs + deltaMs) % dayMs) + dayMs) % dayMs
+    return rebuild(temporal, componentsFromDayMs(total, temporal))
+  }
+  const shifted = new Date(
+    Date.UTC(
+      (temporal.year as number) + GREGORIAN_UTC_YEAR_OFFSET,
+      (temporal.month ?? 1) - 1,
+      temporal.day ?? 1,
+      temporal.hour ?? 0,
+      temporal.minute ?? 0,
+      0,
+      Math.round(((temporal.second ?? 0) + fractionOf(temporal)) * 1000) + deltaMs
+    )
+  )
+  const year = shifted.getUTCFullYear() - 400
+  if (year < 1 || year > 9999) {
+    return undefined
+  }
+  return rebuild(temporal, {
+    year,
+    month: temporal.month === undefined ? undefined : shifted.getUTCMonth() + 1,
+    day: temporal.day === undefined ? undefined : shifted.getUTCDate(),
+    hour: temporal.hour === undefined ? undefined : shifted.getUTCHours(),
+    minute: temporal.minute === undefined ? undefined : shifted.getUTCMinutes(),
+    second: temporal.second === undefined ? undefined : shifted.getUTCSeconds(),
+    fraction:
+      temporal.fraction === undefined && shifted.getUTCMilliseconds() === 0
+        ? undefined
+        : String(shifted.getUTCMilliseconds()).padStart(3, '0'),
+  })
+}
+
+function componentsFromDayMs(
+  totalMs: number,
+  temporal: Temporal
+): { hour: number; minute?: number | undefined; second?: number | undefined; fraction?: string | undefined } {
+  const hour = Math.floor(totalMs / 3600000)
+  const minute = Math.floor((totalMs % 3600000) / 60000)
+  const second = Math.floor((totalMs % 60000) / 1000)
+  const ms = totalMs % 1000
+  return {
+    hour,
+    minute: temporal.minute === undefined ? undefined : minute,
+    second: temporal.second === undefined ? undefined : second,
+    fraction: temporal.fraction === undefined && ms === 0 ? undefined : String(ms).padStart(3, '0'),
+  }
+}
+
+function fractionOf(temporal: Temporal): number {
+  return temporal.fraction === undefined ? 0 : Number.parseFloat(`0.${temporal.fraction}`)
+}
+
+function rebuild(
+  temporal: Temporal,
+  overrides: {
+    year?: number | undefined
+    month?: number | undefined
+    day?: number | undefined
+    hour?: number | undefined
+    minute?: number | undefined
+    second?: number | undefined
+    fraction?: string | undefined
+  }
+): Temporal {
+  const rebuilt = Temporal.fromFields(temporal.kind, {
+    year: 'year' in overrides ? overrides.year : temporal.year,
+    month: 'month' in overrides ? overrides.month : temporal.month,
+    day: 'day' in overrides ? overrides.day : temporal.day,
+    hour: 'hour' in overrides ? overrides.hour : temporal.hour,
+    minute: 'minute' in overrides ? overrides.minute : temporal.minute,
+    second: 'second' in overrides ? overrides.second : temporal.second,
+    fraction: 'fraction' in overrides ? overrides.fraction : temporal.fraction,
+    timezoneOffsetMinutes: temporal.timezoneOffsetMinutes,
+  })
+  /* v8 ignore next 3 -- arithmetic always produces in-range components */
+  if (!rebuilt) {
+    throw new FhirPathRuntimeError('Date/time arithmetic produced an invalid value')
+  }
+  return rebuilt
+}
+
+export type { Duration }

package/src/values/temporal-compare.ts

@@ -0,0 +1,65 @@
+import { GREGORIAN_UTC_YEAR_OFFSET, type Temporal } from './datetime.ts'
+
+/**
+ * Precision levels for comparison. Seconds and milliseconds are one level: the spec
+ * treats the second field as a decimal, so `@T10:00:00` and `@T10:00:00.0` compare
+ * as equal values rather than as a precision mismatch.
+ */
+const LEVELS = ['year', 'month', 'day', 'hour', 'minute', 'second'] as const
+type Level = (typeof LEVELS)[number]
+
+export type TemporalComparison = -1 | 0 | 1 | 'differentPrecision' | 'incompatible'
+
+/**
+ * Compare two temporal values per spec §6.1/§6.4: equal at the shared precision but
+ * with different precisions → 'differentPrecision' (empty for `=` and `<`); a time
+ * never compares with a date/dateTime. Values without a timezone are treated as UTC.
+ */
+export function compareTemporal(a: Temporal, b: Temporal): TemporalComparison {
+  if ((a.kind === 'time') !== (b.kind === 'time')) {
+    return 'incompatible'
+  }
+  const levelA = comparisonLevel(a)
+  const levelB = comparisonLevel(b)
+  const shared = Math.min(levelA, levelB)
+  // At time precision, a value with a timezone and one without cannot be ordered (spec §6.1).
+  if (shared >= 3 && (a.timezoneOffsetMinutes === undefined) !== (b.timezoneOffsetMinutes === undefined)) {
+    return 'differentPrecision'
+  }
+  const rankA = rank(a, shared)
+  const rankB = rank(b, shared)
+  if (rankA < rankB) {
+    return -1
+  }
+  if (rankA > rankB) {
+    return 1
+  }
+  return levelA === levelB ? 0 : 'differentPrecision'
+}
+
+function comparisonLevel(value: Temporal): number {
+  const precision = value.precision === 'millisecond' ? 'second' : value.precision
+  return LEVELS.indexOf(precision as Level)
+}
+
+/**
+ * Milliseconds on a common axis, truncated to `level`. Years are shifted by +400 to
+ * dodge Date.UTC's 0-99 → 19xx mapping; the Gregorian calendar repeats exactly every
+ * 400 years, so ordering and equality are unaffected.
+ */
+function rank(value: Temporal, level: number): number {
+  const year = (value.year ?? 1970) + GREGORIAN_UTC_YEAR_OFFSET
+  const month = level >= 1 ? (value.month ?? 1) : 1
+  const day = level >= 2 ? (value.day ?? 1) : 1
+  const hour = level >= 3 ? (value.hour ?? 0) : 0
+  let minute = level >= 4 ? (value.minute ?? 0) : 0
+  let milliseconds = 0
+  if (level >= 5) {
+    const fraction = value.fraction === undefined ? 0 : Number.parseFloat(`0.${value.fraction}`)
+    milliseconds = Math.round(((value.second ?? 0) + fraction) * 1000)
+  }
+  if (level >= 3 && value.timezoneOffsetMinutes !== undefined) {
+    minute -= value.timezoneOffsetMinutes
+  }
+  return Date.UTC(year, month - 1, day, hour, minute, 0, milliseconds)
+}