fhirpath-ts 0.0.0-bootstrap.0

package/src/values/datetime.ts

@@ -0,0 +1,285 @@
+export type TemporalKind = 'date' | 'dateTime' | 'time'
+
+export type TemporalPrecision = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond'
+
+const DATE_PATTERN = /^(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?$/
+const TIME_PATTERN = /^(\d{2})(?::(\d{2})(?::(\d{2})(?:\.(\d+))?)?)?$/
+const TIMEZONE_PATTERN = /(Z|[+-]\d{2}:\d{2})$/
+
+/**
+ * A Date, DateTime, or Time value with partial precision. Components beyond the
+ * value's precision are undefined; comparison across precisions is decided by the
+ * operators (spec §6.2/§6.4), not here.
+ */
+export class Temporal {
+  readonly kind: TemporalKind
+  readonly year: number | undefined
+  readonly month: number | undefined
+  readonly day: number | undefined
+  readonly hour: number | undefined
+  readonly minute: number | undefined
+  readonly second: number | undefined
+  /** Fraction-of-second digits as written, e.g. `559` or `5591`; undefined when absent. */
+  readonly fraction: string | undefined
+  /** Offset in minutes; 0 for `Z`; undefined when the literal has no timezone. */
+  readonly timezoneOffsetMinutes: number | undefined
+
+  private constructor(fields: {
+    kind: TemporalKind
+    year?: number | undefined
+    month?: number | undefined
+    day?: number | undefined
+    hour?: number | undefined
+    minute?: number | undefined
+    second?: number | undefined
+    fraction?: string | undefined
+    timezoneOffsetMinutes?: number | undefined
+  }) {
+    this.kind = fields.kind
+    this.year = fields.year
+    this.month = fields.month
+    this.day = fields.day
+    this.hour = fields.hour
+    this.minute = fields.minute
+    this.second = fields.second
+    this.fraction = fields.fraction
+    this.timezoneOffsetMinutes = fields.timezoneOffsetMinutes
+  }
+
+  /** Parse the text of a date literal (`2014-01`) or FHIR date value. */
+  static parseDate(text: string): Temporal | undefined {
+    const match = DATE_PATTERN.exec(text)
+    if (!match) {
+      return undefined
+    }
+    const [, year, month, day] = match
+    return Temporal.build('date', {
+      year: Number(year),
+      month: optionalNumber(month),
+      day: optionalNumber(day),
+    })
+  }
+
+  /** Parse the text of a dateTime literal (`2014-01-25T14:30:00Z`, `2014T`). */
+  static parseDateTime(text: string): Temporal | undefined {
+    const timeSeparator = text.indexOf('T')
+    if (timeSeparator === -1) {
+      const dateOnly = Temporal.parseDate(text)
+      return dateOnly ? dateOnly.withKind('dateTime') : undefined
+    }
+    const datePart = text.slice(0, timeSeparator)
+    let timePart = text.slice(timeSeparator + 1)
+    const dateMatch = DATE_PATTERN.exec(datePart)
+    if (!dateMatch) {
+      return undefined
+    }
+    let timezoneOffsetMinutes: number | undefined
+    const timezoneMatch = TIMEZONE_PATTERN.exec(timePart)
+    if (timezoneMatch) {
+      timezoneOffsetMinutes = parseTimezone(timezoneMatch[1] as string)
+      timePart = timePart.slice(0, -(timezoneMatch[1] as string).length)
+    }
+    let time: RegExpExecArray | null = null
+    if (timePart !== '') {
+      time = TIME_PATTERN.exec(timePart)
+      if (!time) {
+        return undefined
+      }
+    }
+    return Temporal.build('dateTime', {
+      year: Number(dateMatch[1]),
+      month: optionalNumber(dateMatch[2]),
+      day: optionalNumber(dateMatch[3]),
+      hour: optionalNumber(time?.[1]),
+      minute: optionalNumber(time?.[2]),
+      second: optionalNumber(time?.[3]),
+      fraction: time?.[4],
+      timezoneOffsetMinutes,
+    })
+  }
+
+  /** Parse the text of a time literal (`14:30:14.559`). Times have no timezone. */
+  static parseTime(text: string): Temporal | undefined {
+    const match = TIME_PATTERN.exec(text)
+    if (!match) {
+      return undefined
+    }
+    const [, hour, minute, second, fraction] = match
+    return Temporal.build('time', {
+      hour: Number(hour),
+      minute: optionalNumber(minute),
+      second: optionalNumber(second),
+      fraction,
+    })
+  }
+
+  /** Build from components with the same range validation as parsing. */
+  static fromFields(
+    kind: TemporalKind,
+    fields: {
+      year?: number | undefined
+      month?: number | undefined
+      day?: number | undefined
+      hour?: number | undefined
+      minute?: number | undefined
+      second?: number | undefined
+      fraction?: string | undefined
+      timezoneOffsetMinutes?: number | undefined
+    }
+  ): Temporal | undefined {
+    return Temporal.build(kind, fields)
+  }
+
+  private static build(
+    kind: TemporalKind,
+    fields: {
+      year?: number | undefined
+      month?: number | undefined
+      day?: number | undefined
+      hour?: number | undefined
+      minute?: number | undefined
+      second?: number | undefined
+      fraction?: string | undefined
+      timezoneOffsetMinutes?: number | undefined
+    }
+  ): Temporal | undefined {
+    if (!(
+      inRange(fields.month, 1, 12) &&
+      inRange(fields.day, 1, 31) &&
+      inRange(fields.hour, 0, 23) &&
+      inRange(fields.minute, 0, 59) &&
+      inRange(fields.second, 0, 60)
+    )) {
+      return undefined
+    }
+    // @2019-02-29 is not a date; timezone offsets only exist within -12:00..+14:00.
+    if (
+      fields.day !== undefined &&
+      fields.month !== undefined &&
+      fields.year !== undefined &&
+      fields.day > daysInMonth(fields.year, fields.month)
+    ) {
+      return undefined
+    }
+    if (fields.timezoneOffsetMinutes !== undefined && Math.abs(fields.timezoneOffsetMinutes) > 14 * 60) {
+      return undefined
+    }
+    return new Temporal({ kind, ...fields })
+  }
+
+  get precision(): TemporalPrecision {
+    if (this.fraction !== undefined) {
+      return 'millisecond'
+    }
+    if (this.second !== undefined) {
+      return 'second'
+    }
+    if (this.minute !== undefined) {
+      return 'minute'
+    }
+    if (this.hour !== undefined) {
+      return 'hour'
+    }
+    if (this.day !== undefined) {
+      return 'day'
+    }
+    if (this.month !== undefined) {
+      return 'month'
+    }
+    return 'year'
+  }
+
+  private withKind(kind: TemporalKind): Temporal {
+    return new Temporal({
+      kind,
+      year: this.year,
+      month: this.month,
+      day: this.day,
+      hour: this.hour,
+      minute: this.minute,
+      second: this.second,
+      fraction: this.fraction,
+      timezoneOffsetMinutes: this.timezoneOffsetMinutes,
+    })
+  }
+
+  toString(): string {
+    const parts: string[] = []
+    if (this.year !== undefined) {
+      parts.push(pad4(this.year))
+      if (this.month !== undefined) {
+        parts.push(`-${pad2(this.month)}`)
+        if (this.day !== undefined) {
+          parts.push(`-${pad2(this.day)}`)
+        }
+      }
+    }
+    if (this.kind === 'dateTime' && this.hour !== undefined) {
+      parts.push('T')
+    }
+    if (this.hour !== undefined) {
+      parts.push(pad2(this.hour))
+      if (this.minute !== undefined) {
+        parts.push(`:${pad2(this.minute)}`)
+        if (this.second !== undefined) {
+          parts.push(`:${pad2(this.second)}`)
+          if (this.fraction !== undefined) {
+            parts.push(`.${this.fraction}`)
+          }
+        }
+      }
+      if (this.timezoneOffsetMinutes !== undefined) {
+        parts.push(formatTimezone(this.timezoneOffsetMinutes))
+      }
+    }
+    return parts.join('')
+  }
+
+  /** Literal form including the `@` (and `@T` for times); used when printing values. */
+  toLiteralString(): string {
+    return this.kind === 'time' ? `@T${this.toString()}` : `@${this.toString()}`
+  }
+}
+
+function optionalNumber(text: string | undefined): number | undefined {
+  return text === undefined ? undefined : Number(text)
+}
+
+/**
+ * Offset added to a FHIRPath year before handing it to `Date.UTC`, which maps
+ * years 0–99 to 1900–1999. Shifting by a whole multiple of 400 preserves the
+ * proleptic Gregorian leap rule exactly while moving small years out of that
+ * remapped range, so date math on years 1–99 stays correct.
+ */
+export const GREGORIAN_UTC_YEAR_OFFSET = 400
+
+/** Days in a month (1-based), correct across the full FHIRPath year range. */
+export function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year + GREGORIAN_UTC_YEAR_OFFSET, month, 0)).getUTCDate()
+}
+
+function inRange(value: number | undefined, min: number, max: number): boolean {
+  return value === undefined || (value >= min && value <= max)
+}
+
+function parseTimezone(text: string): number {
+  if (text === 'Z') {
+    return 0
+  }
+  const sign = text.startsWith('-') ? -1 : 1
+  const hours = Number(text.slice(1, 3))
+  const minutes = Number(text.slice(4, 6))
+  return sign * (hours * 60 + minutes)
+}
+
+function formatTimezone(offsetMinutes: number): string {
+  if (offsetMinutes === 0) {
+    return 'Z'
+  }
+  const sign = offsetMinutes < 0 ? '-' : '+'
+  const absolute = Math.abs(offsetMinutes)
+  return `${sign}${pad2(Math.floor(absolute / 60))}:${pad2(absolute % 60)}`
+}
+
+const pad2 = (value: number): string => String(value).padStart(2, '0')
+const pad4 = (value: number): string => String(value).padStart(4, '0')

package/src/values/decimal.ts

@@ -0,0 +1,213 @@
+/**
+ * Exact decimal arithmetic on a BigInt mantissa with an explicit scale (count of
+ * fraction digits). The scale doubles as the value's precision: `1.10` keeps scale 2,
+ * which `precision()` and the boundary functions rely on. No floats are involved in
+ * `+ - * / div mod`, comparison, or rounding, so `0.1 + 0.2 = 0.3` holds exactly.
+ */
+export class Decimal {
+  /** Scaled integer including the sign: `-1.25` is digits `-125n`, scale 2. */
+  readonly digits: bigint
+  /** Number of fraction digits; never negative. */
+  readonly scale: number
+
+  constructor(digits: bigint, scale: number) {
+    this.digits = digits
+    this.scale = scale
+  }
+
+  /** Parse a decimal string. Accepts exponent notation for values arriving from JSON numbers. */
+  static fromString(text: string): Decimal | undefined {
+    const match = /^([+-]?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(text.trim())
+    if (!match) {
+      return undefined
+    }
+    const [, sign, whole, fraction = '', exponentText] = match
+    let digits = BigInt(`${whole}${fraction}`)
+    if (sign === '-') {
+      digits = -digits
+    }
+    let scale = fraction.length
+    const exponent = exponentText === undefined ? 0 : Number.parseInt(exponentText, 10)
+    // JS numbers never stringify past e±308; a larger exponent can only come from
+    // hostile input and would allocate a giant BigInt.
+    if (Math.abs(exponent) > 400) {
+      return undefined
+    }
+    if (exponent > 0) {
+      const shift = Math.min(exponent, scale)
+      scale -= shift
+      digits *= 10n ** BigInt(exponent - shift)
+    } else if (exponent < 0) {
+      scale -= exponent
+    }
+    return new Decimal(digits, scale)
+  }
+
+  static fromNumber(value: number): Decimal | undefined {
+    if (!Number.isFinite(value)) {
+      return undefined
+    }
+    return Decimal.fromString(String(value))
+  }
+
+  static zero(): Decimal {
+    return new Decimal(0n, 0)
+  }
+
+  isZero(): boolean {
+    return this.digits === 0n
+  }
+
+  isNegative(): boolean {
+    return this.digits < 0n
+  }
+
+  /** True when the value has no fraction part (trailing fraction zeros count as none). */
+  isInteger(): boolean {
+    return this.digits % 10n ** BigInt(this.scale) === 0n
+  }
+
+  negate(): Decimal {
+    return new Decimal(-this.digits, this.scale)
+  }
+
+  abs(): Decimal {
+    return this.digits < 0n ? this.negate() : this
+  }
+
+  add(other: Decimal): Decimal {
+    const [a, b, scale] = alignScales(this, other)
+    return new Decimal(a + b, scale)
+  }
+
+  subtract(other: Decimal): Decimal {
+    const [a, b, scale] = alignScales(this, other)
+    return new Decimal(a - b, scale)
+  }
+
+  multiply(other: Decimal): Decimal {
+    return new Decimal(this.digits * other.digits, this.scale + other.scale)
+  }
+
+  /** Division; empty (undefined) when dividing by zero. Result is exact up to 24+ fraction digits, then rounded half away from zero and trimmed. */
+  divide(other: Decimal): Decimal | undefined {
+    if (other.digits === 0n) {
+      return undefined
+    }
+    const targetScale = Math.max(this.scale, other.scale, 8) + 16
+    const numerator = this.digits * 10n ** BigInt(targetScale + other.scale - this.scale)
+    return new Decimal(divideHalfAwayFromZero(numerator, other.digits), targetScale).trimTrailingZeros()
+  }
+
+  /** Truncated integer division (`div`); empty when dividing by zero. */
+  integerDivide(other: Decimal): Decimal | undefined {
+    if (other.digits === 0n) {
+      return undefined
+    }
+    const [a, b] = alignScales(this, other)
+    return new Decimal(a / b, 0)
+  }
+
+  /** Remainder (`mod`) with the sign of the dividend; empty when dividing by zero. */
+  modulo(other: Decimal): Decimal | undefined {
+    if (other.digits === 0n) {
+      return undefined
+    }
+    const [a, b, scale] = alignScales(this, other)
+    return new Decimal(a % b, scale)
+  }
+
+  compare(other: Decimal): -1 | 0 | 1 {
+    const [a, b] = alignScales(this, other)
+    if (a < b) {
+      return -1
+    }
+    return a > b ? 1 : 0
+  }
+
+  /** Numeric equality; trailing zeros do not matter (`0.5 = 0.50`). */
+  equals(other: Decimal): boolean {
+    return this.compare(other) === 0
+  }
+
+  /** Round half away from zero to `fractionDigits` fraction digits. */
+  round(fractionDigits = 0): Decimal {
+    if (fractionDigits >= this.scale) {
+      return this
+    }
+    const factor = 10n ** BigInt(this.scale - fractionDigits)
+    return new Decimal(divideHalfAwayFromZero(this.digits, factor), fractionDigits)
+  }
+
+  /** Drop the fraction part toward zero. */
+  truncate(): Decimal {
+    return new Decimal(this.digits / 10n ** BigInt(this.scale), 0)
+  }
+
+  ceiling(): Decimal {
+    const whole = this.truncate()
+    if (this.digits > 0n && !this.isInteger()) {
+      return new Decimal(whole.digits + 1n, 0)
+    }
+    return whole
+  }
+
+  floor(): Decimal {
+    const whole = this.truncate()
+    if (this.digits < 0n && !this.isInteger()) {
+      return new Decimal(whole.digits - 1n, 0)
+    }
+    return whole
+  }
+
+  /** Reduce the scale by removing trailing fraction zeros, keeping at least `minScale`. */
+  trimTrailingZeros(minScale = 0): Decimal {
+    let digits = this.digits
+    let scale = this.scale
+    while (scale > minScale && digits % 10n === 0n) {
+      digits /= 10n
+      scale -= 1
+    }
+    return scale === this.scale ? this : new Decimal(digits, scale)
+  }
+
+  /** Rescale to exactly `scale` fraction digits (padding with zeros or rounding). */
+  withScale(scale: number): Decimal {
+    if (scale <= this.scale) {
+      return this.round(scale)
+    }
+    return new Decimal(this.digits * 10n ** BigInt(scale - this.scale), scale)
+  }
+
+  toString(): string {
+    const negative = this.digits < 0n
+    const text = (negative ? -this.digits : this.digits).toString().padStart(this.scale + 1, '0')
+    const whole = text.slice(0, text.length - this.scale)
+    const fraction = this.scale > 0 ? `.${text.slice(text.length - this.scale)}` : ''
+    return `${negative ? '-' : ''}${whole}${fraction}`
+  }
+
+  toNumber(): number {
+    return Number(this.toString())
+  }
+}
+
+function alignScales(a: Decimal, b: Decimal): [bigint, bigint, number] {
+  const scale = Math.max(a.scale, b.scale)
+  return [a.digits * 10n ** BigInt(scale - a.scale), b.digits * 10n ** BigInt(scale - b.scale), scale]
+}
+
+function divideHalfAwayFromZero(numerator: bigint, denominator: bigint): bigint {
+  const quotient = numerator / denominator
+  const remainder = numerator % denominator
+  if (remainder === 0n) {
+    return quotient
+  }
+  const absRemainder = remainder < 0n ? -remainder : remainder
+  const absDenominator = denominator < 0n ? -denominator : denominator
+  if (absRemainder * 2n >= absDenominator) {
+    const negativeResult = numerator < 0n !== denominator < 0n
+    return quotient + (negativeResult ? -1n : 1n)
+  }
+  return quotient
+}

package/src/values/numeric.ts

@@ -0,0 +1,63 @@
+import { Decimal } from './decimal.ts'
+import { SYSTEM_DECIMAL, SYSTEM_INTEGER, SYSTEM_LONG, systemTypeOf, type TypedValue } from './typed-value.ts'
+
+export type NumericKind = 'Integer' | 'Long' | 'Decimal'
+
+export interface NumericOperand {
+  kind: NumericKind
+  value: Decimal
+}
+
+const INTEGER_MIN = -2147483648n
+const INTEGER_MAX = 2147483647n
+export const LONG_MIN = -9223372036854775808n
+export const LONG_MAX = 9223372036854775807n
+
+/** Read an Integer/Long/Decimal operand as a Decimal, remembering its kind. */
+export function asNumeric(item: TypedValue): NumericOperand | undefined {
+  switch (systemTypeOf(item)) {
+    case SYSTEM_INTEGER:
+      return { kind: 'Integer', value: Decimal.fromString(String(item.value as number)) as Decimal }
+    case SYSTEM_LONG:
+      return { kind: 'Long', value: Decimal.fromString((item.value as bigint).toString()) as Decimal }
+    case SYSTEM_DECIMAL:
+      return { kind: 'Decimal', value: item.value as Decimal }
+    default:
+      return undefined
+  }
+}
+
+/** The wider of two numeric kinds: Decimal > Long > Integer (spec implicit conversion). */
+export function widerKind(a: NumericKind, b: NumericKind): NumericKind {
+  if (a === 'Decimal' || b === 'Decimal') {
+    return 'Decimal'
+  }
+  if (a === 'Long' || b === 'Long') {
+    return 'Long'
+  }
+  return 'Integer'
+}
+
+/**
+ * Wrap a numeric result as the narrowest type that represents it exactly.
+ * Integer is 32-bit and Long is 64-bit, so their arithmetic can produce a whole
+ * number too large for the type. When that happens, widen to the next integer
+ * type that holds the value (Integer → Long → Decimal), but never below the
+ * operands' own kind. This keeps the value exact rather than dropping it (empty)
+ * or wrapping it around the way some engines do. Decimal results pass through
+ * unchanged.
+ */
+export function wrapNumeric(value: Decimal, kind: NumericKind): TypedValue {
+  if (kind === 'Decimal') {
+    return { type: SYSTEM_DECIMAL, value }
+  }
+  const whole = value.trimTrailingZeros()
+  const big = BigInt(whole.toString())
+  if (kind === 'Integer' && big >= INTEGER_MIN && big <= INTEGER_MAX) {
+    return { type: SYSTEM_INTEGER, value: Number(big) }
+  }
+  if (big >= LONG_MIN && big <= LONG_MAX) {
+    return { type: SYSTEM_LONG, value: big }
+  }
+  return { type: SYSTEM_DECIMAL, value: whole }
+}