fhirpath-ts 0.0.0-bootstrap.0

package/src/values/type-compat.ts

@@ -0,0 +1,133 @@
+/** Shared, conservative type compatibility for runtime dispatch and static checks. */
+import type { ModelProvider } from '../model/provider.ts'
+import { FHIR_PRIMITIVE_TO_SYSTEM, typeLocalName } from './typed-value.ts'
+
+/** Behavior families used by the static checks. */
+export type ValueKind = 'Boolean' | 'String' | 'Numeric' | 'Temporal' | 'Quantity' | 'Complex'
+
+export function valueKindOfTypeName(canonical: string): ValueKind {
+  const system = canonical.startsWith('System.') ? canonical : FHIR_PRIMITIVE_TO_SYSTEM[typeLocalName(canonical)]
+  switch (system) {
+    case 'System.Boolean':
+      return 'Boolean'
+    case 'System.String':
+      return 'String'
+    case 'System.Integer':
+    case 'System.Long':
+    case 'System.Decimal':
+      return 'Numeric'
+    case 'System.Date':
+    case 'System.DateTime':
+    case 'System.Time':
+      return 'Temporal'
+    case 'System.Quantity':
+      return 'Quantity'
+    default:
+      return canonical === 'FHIR.Quantity' || typeLocalName(canonical) === 'Quantity' ? 'Quantity' : 'Complex'
+  }
+}
+
+/**
+ * Resolves a focus type through its full name, then its local name. Unknown names
+ * return undefined so callers can skip claims the model cannot support.
+ */
+export function canonicalFocusType(model: ModelProvider, raw: string): string | undefined {
+  if (raw.startsWith('System.')) {
+    return raw
+  }
+  return model.resolveType(raw) ?? model.resolveType(typeLocalName(raw))
+}
+
+/** True when every `type` value is a `base` value, including FHIR-primitive → System subtyping. */
+function typeSatisfies(model: ModelProvider, type: string, base: string): boolean {
+  if (type === base || model.isSubtypeOf(type, base)) {
+    return true
+  }
+  return base.startsWith('System.') && FHIR_PRIMITIVE_TO_SYSTEM[typeLocalName(type)] === base
+}
+
+/**
+ * Returns whether one value may have both types. Compatible value kinds and
+ * either direction of the model hierarchy count. The model check must still run
+ * when kinds differ because `SimpleQuantity` and `Quantity` use different kinds.
+ */
+export function typesOverlap(model: ModelProvider, a: string, b: string): boolean {
+  const kind = valueKindOfTypeName(a)
+  if (kind !== 'Complex' && kind === valueKindOfTypeName(b)) {
+    return true
+  }
+  return typeSatisfies(model, a, b) || typeSatisfies(model, b, a)
+}
+
+/**
+ * The proof that a call is on the wrong focus: `wanted` lists the declared
+ * types and `found` lists the focus types, both as canonical names with
+ * duplicates removed. Callers report those two lists and add nothing of their
+ * own.
+ */
+export interface UnsatisfiedInput {
+  wanted: string[]
+  found: string[]
+}
+
+/**
+ * Returns proof only when every known focus type is incompatible with every
+ * declared input type. Missing models, unknown types, empty focus, and any
+ * matching type remain allowed. Runtime dispatch and the analyzer share this
+ * decision and report it in their own way.
+ */
+export function unsatisfiedInput(
+  model: ModelProvider | undefined,
+  declared: readonly string[] | undefined,
+  focus: Iterable<string>
+): UnsatisfiedInput | undefined {
+  if (model === undefined || declared === undefined) {
+    return undefined
+  }
+  const wanted = declared
+    .map(type => canonicalFocusType(model, type))
+    .filter((type): type is string => type !== undefined)
+  if (wanted.length === 0) {
+    return undefined
+  }
+  const found = new Set<string>()
+  for (const type of focus) {
+    const canonical = canonicalFocusType(model, type)
+    if (canonical === undefined || wanted.some(want => typesOverlap(model, canonical, want))) {
+      return undefined
+    }
+    found.add(canonical)
+  }
+  return found.size === 0 ? undefined : { wanted, found: [...found] }
+}
+
+/** Either the declaration a call resolves to, or the proof that none of them fits. */
+export type InputResolution<T> = { resolved: T } | { unsatisfied: UnsatisfiedInput }
+
+/**
+ * Selects the first same-name declaration accepted by the focus. If none fits,
+ * the result combines their expected and found types into one error. Unknown or
+ * empty focus selects the first declaration; registration prevents ambiguous
+ * known focus types.
+ */
+export function resolveByInput<T>(
+  model: ModelProvider | undefined,
+  candidates: readonly T[],
+  declaredTypesOf: (candidate: T) => readonly string[] | undefined,
+  focus: readonly string[]
+): InputResolution<T> {
+  const misses: UnsatisfiedInput[] = []
+  for (const candidate of candidates) {
+    const miss = unsatisfiedInput(model, declaredTypesOf(candidate), focus)
+    if (miss === undefined) {
+      return { resolved: candidate }
+    }
+    misses.push(miss)
+  }
+  return {
+    unsatisfied: {
+      wanted: [...new Set(misses.flatMap(miss => miss.wanted))],
+      found: [...new Set(misses.flatMap(miss => miss.found))],
+    },
+  }
+}

package/src/values/typed-value.ts

@@ -0,0 +1,151 @@
+import type { Temporal } from './datetime.ts'
+import { Decimal } from './decimal.ts'
+
+export const SYSTEM_BOOLEAN = 'System.Boolean'
+export const SYSTEM_STRING = 'System.String'
+export const SYSTEM_INTEGER = 'System.Integer'
+export const SYSTEM_LONG = 'System.Long'
+export const SYSTEM_DECIMAL = 'System.Decimal'
+export const SYSTEM_DATE = 'System.Date'
+export const SYSTEM_DATETIME = 'System.DateTime'
+export const SYSTEM_TIME = 'System.Time'
+export const SYSTEM_QUANTITY = 'System.Quantity'
+
+/** Placeholder type for plain objects when no model knows better. */
+export const OBJECT_TYPE = 'Object'
+
+/** A minimal Quantity value; unit algebra and UCUM conversion land in the quantity phase. */
+export interface QuantityValue {
+  value: Decimal
+  unit: string
+  /** True for calendar duration units (`4 days`), false for UCUM strings (`4 'd'`). */
+  calendar: boolean
+}
+
+/**
+ * A value paired with its type name, e.g. `System.Integer` or `FHIR.Patient`.
+ * Runtime representations: Boolean → boolean, String → string, Integer → number,
+ * Long → bigint, Decimal → Decimal, Date/DateTime/Time → Temporal,
+ * Quantity → QuantityValue, complex types → raw JSON.
+ */
+export interface TypedValue {
+  type: string
+  value: unknown
+  /** For FHIR primitives navigated with a model: the `_field` sibling (id/extension). */
+  primitiveElement?: unknown
+}
+
+/** FHIR primitive type names to their System twins (FHIR spec "types" page). */
+export const FHIR_PRIMITIVE_TO_SYSTEM: Readonly<Record<string, string>> = {
+  boolean: 'System.Boolean',
+  integer: 'System.Integer',
+  positiveInt: 'System.Integer',
+  unsignedInt: 'System.Integer',
+  integer64: 'System.Long',
+  decimal: 'System.Decimal',
+  date: 'System.Date',
+  dateTime: 'System.DateTime',
+  instant: 'System.DateTime',
+  time: 'System.Time',
+  string: 'System.String',
+  code: 'System.String',
+  id: 'System.String',
+  markdown: 'System.String',
+  uri: 'System.String',
+  url: 'System.String',
+  canonical: 'System.String',
+  oid: 'System.String',
+  uuid: 'System.String',
+  base64Binary: 'System.String',
+  xhtml: 'System.String',
+}
+
+/**
+ * The System type a value behaves as: System types answer themselves, FHIR
+ * primitives answer their twin (`FHIR.code` → `System.String`), everything else
+ * undefined. Operators dispatch on this so FHIR-typed primitives keep working.
+ */
+export function systemTypeOf(item: TypedValue): string | undefined {
+  if (item.type.startsWith('System.')) {
+    return item.type
+  }
+  return FHIR_PRIMITIVE_TO_SYSTEM[typeLocalName(item.type)]
+}
+
+/** The local part of a qualified type name: `System.Boolean` → `Boolean`. */
+export function typeLocalName(type: string): string {
+  const separator = type.lastIndexOf('.')
+  return separator === -1 ? type : type.slice(separator + 1)
+}
+
+/** Wrap a raw JSON value, inferring System types where possible. */
+export function toTypedValue(value: unknown): TypedValue {
+  if (typeof value === 'boolean') {
+    return { type: SYSTEM_BOOLEAN, value }
+  }
+  if (typeof value === 'string') {
+    return { type: SYSTEM_STRING, value }
+  }
+  if (typeof value === 'bigint') {
+    return { type: SYSTEM_LONG, value }
+  }
+  if (typeof value === 'number') {
+    if (Number.isSafeInteger(value)) {
+      return { type: SYSTEM_INTEGER, value }
+    }
+    const decimal = Decimal.fromNumber(value)
+    // NaN/Infinity have no FHIRPath representation; keep them opaque so operations
+    // against them fail with a clean type error instead of a raw TypeError.
+    return decimal === undefined ? { type: OBJECT_TYPE, value } : { type: SYSTEM_DECIMAL, value: decimal }
+  }
+  if (value instanceof Decimal) {
+    return { type: SYSTEM_DECIMAL, value }
+  }
+  if (isResource(value)) {
+    return { type: `FHIR.${value.resourceType}`, value }
+  }
+  return { type: OBJECT_TYPE, value }
+}
+
+function isResource(value: unknown): value is { resourceType: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { resourceType?: unknown }).resourceType === 'string'
+  )
+}
+
+/** Wrap an input (single value, array, or undefined) as a collection. */
+export function toCollection(value: unknown): TypedValue[] {
+  if (value === undefined || value === null) {
+    return []
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap(item => toCollection(item))
+  }
+  return [toTypedValue(value)]
+}
+
+/** Unwrap for the public API: internal value objects become plain JS values. */
+export function unwrap(typed: TypedValue): unknown {
+  const value = typed.value
+  if (value instanceof Decimal) {
+    return value.toNumber()
+  }
+  if (isTemporal(value)) {
+    return value.toString()
+  }
+  if (isQuantity(typed)) {
+    const quantity = value as QuantityValue
+    return { value: quantity.value.toNumber(), unit: quantity.unit }
+  }
+  return value
+}
+
+function isTemporal(value: unknown): value is Temporal {
+  return typeof value === 'object' && value !== null && 'kind' in value && 'toLiteralString' in value
+}
+
+function isQuantity(typed: TypedValue): boolean {
+  return typed.type === SYSTEM_QUANTITY
+}

package/src/values/ucum.ts

@@ -0,0 +1,181 @@
+import { Decimal } from './decimal.ts'
+
+/**
+ * Minimal UCUM support: enough units for quantity comparison, conversion, and the
+ * official test suites. Factors are exact Decimals, so `1 'm' = 100 'cm'` holds
+ * without float drift. Anything outside this table still works as an opaque unit
+ * that only compares with itself. Full UCUM (@lhncbc/ucum-lhc) is the documented
+ * upgrade path if conformance ever needs it.
+ */
+
+/** Base dimensions; every known unit reduces to a product of these. */
+type Dimension = 'g' | 'm' | 's' | 'mol' | '1'
+
+interface UnitAtom {
+  dimension: Dimension
+  /** Factor to the base unit of the dimension, as an exact decimal string. */
+  factor: string
+  /** Prefixable per UCUM metadata; bracketed and derived units are not. */
+  prefixable: boolean
+}
+
+const ATOMS: Readonly<Record<string, UnitAtom>> = {
+  m: { dimension: 'm', factor: '1', prefixable: true },
+  g: { dimension: 'g', factor: '1', prefixable: true },
+  s: { dimension: 's', factor: '1', prefixable: true },
+  mol: { dimension: 'mol', factor: '1', prefixable: true },
+  L: { dimension: 'm', factor: '0.001', prefixable: true }, // handled as m^3 via exponent bump below
+  l: { dimension: 'm', factor: '0.001', prefixable: true },
+  min: { dimension: 's', factor: '60', prefixable: false },
+  h: { dimension: 's', factor: '3600', prefixable: false },
+  d: { dimension: 's', factor: '86400', prefixable: false },
+  wk: { dimension: 's', factor: '604800', prefixable: false },
+  // UCUM's annum is the Julian year; the Julian month is a twelfth of it.
+  a: { dimension: 's', factor: '31557600', prefixable: false },
+  mo: { dimension: 's', factor: '2629800', prefixable: false },
+  '[lb_av]': { dimension: 'g', factor: '453.59237', prefixable: false },
+  '[oz_av]': { dimension: 'g', factor: '28.349523125', prefixable: false },
+  '[in_i]': { dimension: 'm', factor: '0.0254', prefixable: false },
+  '[ft_i]': { dimension: 'm', factor: '0.3048', prefixable: false },
+  '1': { dimension: '1', factor: '1', prefixable: false },
+  '%': { dimension: '1', factor: '0.01', prefixable: false },
+}
+
+/** Units that are volumes even though their atom row reduces through meters. */
+const VOLUME_ATOMS = new Set(['L', 'l'])
+
+const PREFIXES: Readonly<Record<string, string>> = {
+  T: '1000000000000',
+  G: '1000000000',
+  M: '1000000',
+  k: '1000',
+  h: '100',
+  da: '10',
+  d: '0.1',
+  c: '0.01',
+  m: '0.001',
+  u: '0.000001',
+  n: '0.000000001',
+  p: '0.000000000001',
+}
+
+export interface CanonicalUnit {
+  /** Multiplier to base units, exact. */
+  factor: Decimal
+  /** Dimension exponents, e.g. `g/m` → { g: 1, m: -1 }. Dimensionless entries are dropped. */
+  dimensions: Readonly<Record<string, number>>
+}
+
+/**
+ * Real UCUM exponents are single-digit (m2, cm3, s2). Larger ones would make
+ * powDecimal multiply huge exact BigInts — a tiny expression could hang the
+ * process — so anything past this stays an opaque unit.
+ */
+const MAX_EXPONENT_MAGNITUDE = 9
+
+/** One `atom` optionally followed by an integer exponent, e.g. `m2` or `cm3`. */
+function parseComponent(text: string): { factor: Decimal; dimension: Dimension; exponent: number } | undefined {
+  // Whole-text atoms first, so '1' is the unity unit rather than an empty atom with exponent 1.
+  const whole = resolveAtom(text)
+  if (whole) {
+    const volumeBump = VOLUME_ATOMS.has(whole.atomKey) ? 3 : 1
+    return { factor: whole.factor, dimension: whole.atom.dimension, exponent: volumeBump }
+  }
+  const match = /^(.*?)(-?\d+)?$/.exec(text)
+  /* v8 ignore next 3 -- the regex cannot fail on any string */
+  if (!match) {
+    return undefined
+  }
+  const [, atomText = '', exponentText] = match
+  const exponent = exponentText === undefined ? 1 : Number.parseInt(exponentText, 10)
+  if (Math.abs(exponent) > MAX_EXPONENT_MAGNITUDE) {
+    return undefined
+  }
+  const resolved = resolveAtom(atomText)
+  if (!resolved) {
+    return undefined
+  }
+  const volumeBump = VOLUME_ATOMS.has(resolved.atomKey) ? 3 : 1
+  const factor = powDecimal(resolved.factor, exponent)
+  return { factor, dimension: resolved.atom.dimension, exponent: exponent * volumeBump }
+}
+
+function resolveAtom(text: string): { atom: UnitAtom; atomKey: string; factor: Decimal } | undefined {
+  const direct = ATOMS[text]
+  if (direct) {
+    return { atom: direct, atomKey: text, factor: Decimal.fromString(direct.factor) as Decimal }
+  }
+  for (const [prefix, prefixFactor] of Object.entries(PREFIXES)) {
+    if (text.startsWith(prefix)) {
+      const rest = text.slice(prefix.length)
+      const atom = ATOMS[rest]
+      if (atom?.prefixable) {
+        const factor = (Decimal.fromString(atom.factor) as Decimal).multiply(
+          Decimal.fromString(prefixFactor) as Decimal
+        )
+        return { atom, atomKey: rest, factor }
+      }
+    }
+  }
+  return undefined
+}
+
+function powDecimal(base: Decimal, exponent: number): Decimal {
+  if (exponent === 0) {
+    return new Decimal(1n, 0)
+  }
+  let result = new Decimal(1n, 0)
+  for (let i = 0; i < Math.abs(exponent); i++) {
+    result = result.multiply(base)
+  }
+  if (exponent < 0) {
+    // Factors are exact positive decimals, so the inverse always exists.
+    return new Decimal(1n, 0).divide(result) as Decimal
+  }
+  return result
+}
+
+/**
+ * Reduce a UCUM expression (`mg`, `m2`, `g/m`, `kg.m/s2`) to base dimensions.
+ * Undefined for units outside the table — they stay opaque.
+ */
+export function canonicalizeUnit(unit: string): CanonicalUnit | undefined {
+  const [numerator, ...denominators] = unit.split('/')
+  let factor = new Decimal(1n, 0)
+  const dimensions: Record<string, number> = {}
+  const apply = (componentText: string, sign: 1 | -1): boolean => {
+    const component = parseComponent(componentText)
+    if (!component) {
+      return false
+    }
+    factor = sign === 1 ? factor.multiply(component.factor) : (factor.divide(component.factor) as Decimal)
+    if (component.dimension !== '1') {
+      const next = (dimensions[component.dimension] ?? 0) + sign * component.exponent
+      if (next === 0) {
+        delete dimensions[component.dimension]
+      } else {
+        dimensions[component.dimension] = next
+      }
+    }
+    return true
+  }
+  for (const part of (numerator ?? '').split('.')) {
+    if (!apply(part, 1)) {
+      return undefined
+    }
+  }
+  for (const denominator of denominators) {
+    for (const part of denominator.split('.')) {
+      if (!apply(part, -1)) {
+        return undefined
+      }
+    }
+  }
+  return { factor, dimensions }
+}
+
+export function sameDimensions(a: CanonicalUnit, b: CanonicalUnit): boolean {
+  const keysA = Object.keys(a.dimensions)
+  const keysB = Object.keys(b.dimensions)
+  return keysA.length === keysB.length && keysA.every(key => a.dimensions[key] === b.dimensions[key])
+}