fhirpath-ts 0.0.0-bootstrap.0

package/src/engine/evaluator.ts

@@ -0,0 +1,246 @@
+import '../functions/install.ts'
+
+import { FhirPathRuntimeError, FhirPathTypeError } from '../errors.ts'
+import { describeArity, lookupFunction } from '../functions/registry.ts'
+import type { AstNode } from '../parser/ast.ts'
+import { criteriaBoolean, singleton, wrapBoolean } from '../values/collection.ts'
+import { Temporal } from '../values/datetime.ts'
+import { Decimal } from '../values/decimal.ts'
+import { wrapNumeric } from '../values/numeric.ts'
+import {
+  SYSTEM_BOOLEAN,
+  SYSTEM_DATE,
+  SYSTEM_DATETIME,
+  SYSTEM_DECIMAL,
+  SYSTEM_INTEGER,
+  SYSTEM_LONG,
+  SYSTEM_QUANTITY,
+  SYSTEM_STRING,
+  SYSTEM_TIME,
+  toCollection,
+  type TypedValue,
+  unwrap,
+} from '../values/typed-value.ts'
+import {
+  type EvaluationContext,
+  forkVariables,
+  type HostFunction,
+  resolveEnvironmentVariable,
+  withEnvOverlay,
+  withFrame,
+} from './context.ts'
+import { navigateIdentifier } from './navigation.ts'
+import { evaluateBinary, evaluateTypeOp, evaluateUnary } from './operators/index.ts'
+import { resolveHostCall } from './type-matching.ts'
+
+function evaluateArgument(node: AstNode, context: EvaluationContext, _input: TypedValue[]): TypedValue[] {
+  // Arguments evaluate against $this (the current context item), not the function's
+  // input collection: `name.given.combine(name.family)` resolves name.family on the
+  // Patient. Lambda-style functions bind their own frame first, so they see each item.
+  const forked = forkVariables(context)
+  return evaluateNode(node, forked, forked.frame.thisValue)
+}
+
+/**
+ * Calls a host function after focus-type dispatch. Expression functions keep
+ * typed values, use the call focus as `$this`, and apply their local environment.
+ * Native functions receive eagerly evaluated plain JavaScript values.
+ */
+function evaluateHostFunction(
+  name: string,
+  entry: HostFunction,
+  args: AstNode[],
+  context: EvaluationContext,
+  input: TypedValue[]
+): TypedValue[] {
+  const host = resolveHostCall(name, entry, context, input)
+  if ('ast' in host) {
+    if (args.length > 0) {
+      throw new FhirPathTypeError(`Function '${name}' expects ${describeArity(0, 0)}, got ${args.length} arguments`)
+    }
+    if (context.activeExpressionFunctions.has(name)) {
+      throw new FhirPathRuntimeError(
+        `Expression-defined function '${name}' calls itself, directly or through another function`
+      )
+    }
+    context.activeExpressionFunctions.add(name)
+    try {
+      // Keep the function's environment local and recursion detection active.
+      const scoped = host.env === undefined ? context : withEnvOverlay(context, host.env)
+      // withFrame rebinds $this to the input and forks variables, so the
+      // body's defineVariable() bindings stay local to the body.
+      const result = withFrame(scoped, { thisValue: input }, forked => evaluateNode(host.ast, forked, input))
+      // Inside the try, so a body that returns several items still removes its
+      // name from activeExpressionFunctions on the way out.
+      return host.criteria === true ? wrapBoolean(criteriaBoolean(result)) : result
+    } finally {
+      context.activeExpressionFunctions.delete(name)
+    }
+  }
+  const minArity = host.minArity ?? 0
+  const maxArity = host.maxArity ?? Number.POSITIVE_INFINITY
+  if (args.length < minArity || args.length > maxArity) {
+    throw new FhirPathTypeError(
+      `Function '${name}' expects ${describeArity(minArity, maxArity)}, got ${args.length} arguments`
+    )
+  }
+  const argValues = args.map(node => evaluateArgument(node, context, input).map(unwrap))
+  return toCollection(host.fn(input.map(unwrap), ...argValues))
+}
+
+/** Evaluate one AST node against an input collection. */
+export function evaluateNode(node: AstNode, context: EvaluationContext, input: TypedValue[]): TypedValue[] {
+  switch (node.kind) {
+    case 'null':
+      return []
+    case 'boolean':
+      return [{ type: SYSTEM_BOOLEAN, value: node.value }]
+    case 'string':
+      return [{ type: SYSTEM_STRING, value: node.value }]
+    case 'number':
+      return [
+        node.isLong === true
+          ? { type: SYSTEM_LONG, value: BigInt(node.text) }
+          : evaluateNumberLiteral(node.text, node.isDecimal),
+      ]
+    case 'date':
+      return [{ type: SYSTEM_DATE, value: parseTemporalLiteral('date', node.text) }]
+    case 'dateTime':
+      return [{ type: SYSTEM_DATETIME, value: parseTemporalLiteral('dateTime', node.text) }]
+    case 'time':
+      return [{ type: SYSTEM_TIME, value: parseTemporalLiteral('time', node.text) }]
+    case 'quantity':
+      return [evaluateQuantityLiteral(node.value, node.unit, node.unitKind)]
+    case 'identifier':
+      return navigateIdentifier(context, node.name, input)
+    case 'special':
+      return evaluateSpecialVariable(node.name, context)
+    case 'external':
+      return resolveEnvironmentVariable(context, node.name)
+    case 'dot':
+      return evaluateNode(node.right, context, evaluateNode(node.left, context, input))
+    case 'indexer':
+      return evaluateIndexer(node.target, node.index, context, input)
+    case 'call': {
+      const host = context.functions.get(node.name)
+      if (host !== undefined) {
+        return evaluateHostFunction(node.name, host, node.args, context, input)
+      }
+      // Each function argument evaluates in its own defineVariable() scope.
+      return lookupFunction(node.name, node.args.length).evaluate(context, input, node.args, evaluateArgument)
+    }
+    case 'unary':
+      return evaluateUnary(context, node.operator, evaluateNode(node.operand, context, input))
+    case 'binary':
+      // Operator operands are separate chains; variables defined in one are not
+      // visible in the other (locked by the official defineVariable tests).
+      return evaluateBinary(
+        context,
+        node.operator,
+        evaluateNode(node.left, forkVariables(context), input),
+        evaluateNode(node.right, forkVariables(context), input)
+      )
+    case 'typeOp':
+      return evaluateTypeOp(context, node.operator, evaluateNode(node.operand, context, input), node.type)
+    /* v8 ignore start -- exhaustive fallback, unreachable for real ASTs */
+    default: {
+      const unreachable: never = node
+      throw new FhirPathRuntimeError(`Unhandled node ${String(unreachable)}`)
+    }
+    /* v8 ignore stop */
+  }
+}
+
+function evaluateNumberLiteral(text: string, isDecimal: boolean): TypedValue {
+  if (isDecimal) {
+    return { type: SYSTEM_DECIMAL, value: parseDecimalLiteral(text) }
+  }
+  // The grammar's NUMBER rule has no digit-count limit, so an integer literal can
+  // exceed 32 bits (or even 64). Widen through wrapNumeric the same way arithmetic
+  // results do, rather than truncating through a JS double (Number.parseInt loses
+  // precision above 2^53 and never reports the overflow).
+  return wrapNumeric(parseDecimalLiteral(text), 'Integer')
+}
+
+function parseDecimalLiteral(text: string): Decimal {
+  const parsed = Decimal.fromString(text)
+  /* v8 ignore next 3 -- the lexer only emits parseable decimal literals */
+  if (parsed === undefined) {
+    throw new FhirPathRuntimeError(`Invalid decimal literal ${text}`)
+  }
+  return parsed
+}
+
+function parseTemporalLiteral(kind: 'date' | 'dateTime' | 'time', text: string): Temporal {
+  const parsed =
+    kind === 'date'
+      ? Temporal.parseDate(text)
+      : kind === 'dateTime'
+        ? Temporal.parseDateTime(text)
+        : Temporal.parseTime(text)
+  if (!parsed) {
+    throw new FhirPathRuntimeError(`Invalid ${kind} literal @${kind === 'time' ? 'T' : ''}${text}`)
+  }
+  return parsed
+}
+
+function evaluateQuantityLiteral(value: string, unit: string, unitKind: 'ucum' | 'calendar'): TypedValue {
+  return {
+    type: SYSTEM_QUANTITY,
+    value: {
+      value: parseDecimalLiteral(value),
+      unit,
+      calendar: unitKind === 'calendar',
+    },
+  }
+}
+
+function evaluateSpecialVariable(name: 'this' | 'index' | 'total', context: EvaluationContext): TypedValue[] {
+  const frame = context.frame
+  switch (name) {
+    case 'this':
+      return frame.thisValue
+    case 'index': {
+      let current: typeof frame | undefined = frame
+      while (current && current.index === undefined) {
+        current = current.parent
+      }
+      if (!current || current.index === undefined) {
+        throw new FhirPathTypeError('$index is only defined inside iteration functions')
+      }
+      return [{ type: SYSTEM_INTEGER, value: current.index }]
+    }
+    case 'total': {
+      let current: typeof frame | undefined = frame
+      while (current && current.total === undefined) {
+        current = current.parent
+      }
+      if (!current || current.total === undefined) {
+        throw new FhirPathTypeError('$total is only defined inside aggregate()')
+      }
+      return current.total
+    }
+    /* v8 ignore start -- the parser only produces the three names above */
+    default:
+      return []
+    /* v8 ignore stop */
+  }
+}
+
+function evaluateIndexer(
+  target: AstNode,
+  indexNode: AstNode,
+  context: EvaluationContext,
+  input: TypedValue[]
+): TypedValue[] {
+  const collection = evaluateNode(target, context, input)
+  const index = singleton(evaluateNode(indexNode, context, input), SYSTEM_INTEGER)
+  if (index === undefined) {
+    return []
+  }
+  // The singleton check already guarantees an Integer, and out-of-range (including
+  // negative) array access yields undefined, which is the spec's empty result.
+  const item = collection[index.value as number]
+  /* v8 ignore next -- both halves run across the suites; v8 misattributes this line */
+  return item === undefined ? [] : [item]
+}

package/src/engine/navigation.ts

@@ -0,0 +1,106 @@
+import { FhirPathTypeError } from '../errors.ts'
+import { readModelProperty } from '../fhir/model-navigation.ts'
+import { OBJECT_TYPE, toTypedValue, type TypedValue } from '../values/typed-value.ts'
+import type { EvaluationContext } from './context.ts'
+
+/**
+ * Evaluate a bare identifier against the input. The spec's root rule (§10.1) applies
+ * first: an identifier naming the item's own type yields the item itself, which is
+ * how `Patient.name` works when the context is a Patient.
+ */
+export function navigateIdentifier(context: EvaluationContext, name: string, input: TypedValue[]): TypedValue[] {
+  const results: TypedValue[] = []
+  for (const item of input) {
+    if (matchesTypeName(context, item, name)) {
+      results.push(item)
+    } else if (context.model && item.type.startsWith(`${context.model.namespace}.`)) {
+      const modelRead = readModelProperty(context.model, item, name)
+      if (modelRead === undefined) {
+        // Choice elements go by stem name; a suffixed key like Observation.valueQuantity
+        // is the one unknown-element shape the official suites require to error at
+        // runtime. Everything else is the static analyzer's job (spec §11) — plain
+        // unknown elements navigate to empty, and types the model has never heard of
+        // (custom resourceTypes) read like raw JSON.
+        // See: https://hl7.org/fhirpath/en/index.html#type-safety-and-strict-evaluation
+        if (isChoiceKeyMisuse(context, item.type, name)) {
+          throw new FhirPathTypeError(
+            `Element '${name}' is not defined on ${item.type}; choice elements use their stem name`
+          )
+        }
+        if (
+          name === 'resourceType' ||
+          (context.model.listElements !== undefined && context.model.listElements(item.type) === undefined)
+        ) {
+          results.push(...getProperty(item, name))
+        }
+      } else {
+        results.push(...modelRead)
+      }
+    } else if (context.model) {
+      const modelRead = readModelProperty(context.model, item, name)
+      results.push(...(modelRead ?? getProperty(item, name)))
+    } else {
+      results.push(...getProperty(item, name))
+    }
+  }
+  return results
+}
+
+/** True for `valueQuantity`-style keys whose stem is a choice element of the type. */
+function isChoiceKeyMisuse(context: EvaluationContext, type: string, name: string): boolean {
+  const model = context.model as NonNullable<EvaluationContext['model']>
+  for (let position = 1; position < name.length; position++) {
+    if (!/[A-Z]/.test(name[position] as string)) {
+      continue
+    }
+    const stem = name.slice(0, position)
+    if (model.getElement(type, stem)?.isChoice === true) {
+      return true
+    }
+  }
+  return false
+}
+
+function matchesTypeName(context: EvaluationContext, item: TypedValue, name: string): boolean {
+  // Only the namespace strips off: the backbone type FHIR.ValueSet.expansion.contains
+  // must not answer to the element name 'contains'. Lowercase primitive type names
+  // (FHIR.code) never self-match either — `children().code` means the element.
+  if (!/^[A-Z]/.test(name)) {
+    // Lowercase names are always elements: `children().code` never filters by the
+    // primitive type FHIR.code.
+    return false
+  }
+  const separator = item.type.indexOf('.')
+  const local = separator === -1 ? item.type : item.type.slice(separator + 1)
+  if (local === name && item.type !== OBJECT_TYPE) {
+    return true
+  }
+  if (context.model) {
+    const canonical = context.model.resolveType(name)
+    if (canonical !== undefined) {
+      return context.model.isSubtypeOf(item.type, canonical)
+    }
+  }
+  return false
+}
+
+/** Read one child element from a complex value, flattening arrays. Missing → empty. */
+export function getProperty(item: TypedValue, name: string): TypedValue[] {
+  const value = item.value
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return []
+  }
+  // Own properties only: `Patient.constructor` or `x.toString` must be empty, not
+  // an inherited member leaking off Object.prototype.
+  if (!Object.hasOwn(value, name)) {
+    return []
+  }
+  const child = (value as Record<string, unknown>)[name]
+  if (child === undefined || child === null) {
+    return []
+  }
+  if (Array.isArray(child)) {
+    return child.filter(element => element !== null && element !== undefined).map(element => toTypedValue(element))
+  }
+  return [toTypedValue(child)]
+}

package/src/engine/operators/collections.ts

@@ -0,0 +1,34 @@
+import { FhirPathRuntimeError } from '../../errors.ts'
+import { SYSTEM_BOOLEAN, type TypedValue } from '../../values/typed-value.ts'
+import { pairEquals } from './equality.ts'
+import type { BinaryOperatorTable } from './index.ts'
+
+/** Merge with duplicate elimination using `=` semantics (spec §6.4.1 / `union()`). */
+export function unionCollections(left: TypedValue[], right: TypedValue[]): TypedValue[] {
+  const result: TypedValue[] = []
+  for (const item of [...left, ...right]) {
+    if (!result.some(existing => pairEquals(existing, item) === true)) {
+      result.push(item)
+    }
+  }
+  return result
+}
+
+/** `in`: left singleton membership; empty left → empty, empty right → false. */
+function inOperator(_context: unknown, left: TypedValue[], right: TypedValue[]): TypedValue[] {
+  if (left.length === 0) {
+    return []
+  }
+  if (left.length > 1) {
+    throw new FhirPathRuntimeError("The left operand of 'in' must have at most one item")
+  }
+  const item = left[0] as TypedValue
+  const found = right.some(candidate => pairEquals(item, candidate) === true)
+  return [{ type: SYSTEM_BOOLEAN, value: found }]
+}
+
+export const collectionOperators = {
+  '|': (_context, left, right) => unionCollections(left, right),
+  in: inOperator,
+  contains: (context, left, right) => inOperator(context, right, left),
+} satisfies BinaryOperatorTable

package/src/engine/operators/comparison.ts

@@ -0,0 +1,82 @@
+import { FhirPathTypeError } from '../../errors.ts'
+import { singleton } from '../../values/collection.ts'
+import { Temporal } from '../../values/datetime.ts'
+import { asNumeric } from '../../values/numeric.ts'
+import { coerceQuantityPair, compareQuantities } from '../../values/quantity.ts'
+import { compareTemporal } from '../../values/temporal-compare.ts'
+import { SYSTEM_BOOLEAN, SYSTEM_STRING, systemTypeOf, type TypedValue } from '../../values/typed-value.ts'
+import type { BinaryOperatorTable } from './index.ts'
+
+type ComparisonOperator = '<' | '>' | '<=' | '>='
+
+/**
+ * Order two singleton values (spec §6.2). Undefined means empty: an empty operand,
+ * a date/time precision mismatch, or units that cannot be compared.
+ */
+export function compareValues(a: TypedValue, b: TypedValue): number | undefined {
+  const numericA = asNumeric(a)
+  const numericB = asNumeric(b)
+  if (numericA && numericB) {
+    return numericA.value.compare(numericB.value)
+  }
+  if (systemTypeOf(a) === SYSTEM_STRING && systemTypeOf(b) === SYSTEM_STRING) {
+    const left = a.value as string
+    const right = b.value as string
+    if (left < right) {
+      return -1
+    }
+    return left > right ? 1 : 0
+  }
+  if (a.value instanceof Temporal && b.value instanceof Temporal) {
+    const comparison = compareTemporal(a.value, b.value)
+    if (comparison === 'differentPrecision') {
+      return undefined
+    }
+    if (comparison === 'incompatible') {
+      throw new FhirPathTypeError('Cannot compare a time with a date or dateTime')
+    }
+    return comparison
+  }
+  const quantityPair = coerceQuantityPair(a, b)
+  if (quantityPair) {
+    return compareQuantities(quantityPair[0], quantityPair[1])
+  }
+  throw new FhirPathTypeError(`Cannot compare ${a.type} with ${b.type}`)
+}
+
+function comparisonOperator(operator: ComparisonOperator) {
+  return (_context: unknown, left: TypedValue[], right: TypedValue[]): TypedValue[] => {
+    const a = singleton(left)
+    const b = singleton(right)
+    if (a === undefined || b === undefined) {
+      return []
+    }
+    const comparison = compareValues(a, b)
+    if (comparison === undefined) {
+      return []
+    }
+    let value: boolean
+    switch (operator) {
+      case '<':
+        value = comparison < 0
+        break
+      case '>':
+        value = comparison > 0
+        break
+      case '<=':
+        value = comparison <= 0
+        break
+      default:
+        value = comparison >= 0
+        break
+    }
+    return [{ type: SYSTEM_BOOLEAN, value }]
+  }
+}
+
+export const comparisonOperators = {
+  '<': comparisonOperator('<'),
+  '>': comparisonOperator('>'),
+  '<=': comparisonOperator('<='),
+  '>=': comparisonOperator('>='),
+} satisfies BinaryOperatorTable