fhirpath-ts 0.0.0-bootstrap.0

package/src/analyzer/signatures.ts

@@ -0,0 +1,260 @@
+import type { ValueKind } from '../values/type-compat.ts'
+
+interface StaticStateLike {
+  types: string[] | undefined
+  /** True: at most one item. False: may hold several. Undefined: cardinality unknown. */
+  single: boolean | undefined
+  /** Canonical resource types a Reference state may point to — resolve()'s result. */
+  targets?: string[]
+}
+
+/** Cardinality of a value combined from two parts: single only when both are. */
+export function singleAnd(a: boolean | undefined, b: boolean | undefined): boolean | undefined {
+  if (a === false || b === false) {
+    return false
+  }
+  return a === true && b === true ? true : undefined
+}
+
+/** Describes whether an argument is a lambda, condition, sort key, type name, or eager value. */
+export type ArgSpec = 'expression' | 'condition' | 'sort-key' | 'type-name' | 'any' | ValueKind
+
+/**
+ * The argument shapes a host function can declare. Host functions always
+ * receive eagerly evaluated values (HostFunction.fn), so only the eager specs
+ * are offered — declaring a lambda spec like `expression` would make the
+ * analyzer check semantics the runtime does not implement.
+ */
+export type ValueArgSpec = 'any' | ValueKind
+
+/**
+ * Accepted focus kind, cardinality, and model types. DTO functions may set
+ * `types`; built-ins must not because specification functions accept many types.
+ */
+export interface InputSpec {
+  kind?: ValueKind
+  singleton?: boolean
+  /** Canonical or local model type names ('CodeableConcept', 'System.String'). */
+  types?: string[]
+}
+
+/**
+ * The declared analyzer signature of a host-supplied function (HAPI's
+ * checkFunction): what input it accepts, how its arguments are treated, and
+ * what it returns. Result `types` use model or System names ('Patient',
+ * 'System.String'); omitting them keeps the result an unknown region.
+ */
+export interface CustomFunctionSignature {
+  input?: InputSpec
+  args?: ValueArgSpec[]
+  result?: { types?: string[]; single?: boolean }
+}
+
+export interface FunctionSignature {
+  input?: InputSpec
+  args?: ArgSpec[]
+  /**
+   * Result state from the input state and the analyzed argument states
+   * (undefined for `type-name` positions and missing optional arguments).
+   */
+  result: (input: StaticStateLike, args: readonly (StaticStateLike | undefined)[]) => StaticStateLike
+}
+
+const BOOLEAN = (): StaticStateLike => ({ types: ['System.Boolean'], single: true })
+const INTEGER = (): StaticStateLike => ({ types: ['System.Integer'], single: true })
+const STRING = (): StaticStateLike => ({ types: ['System.String'], single: true })
+const DECIMAL = (): StaticStateLike => ({ types: ['System.Decimal'], single: true })
+const UNKNOWN = (): StaticStateLike => ({ types: undefined, single: undefined })
+const SAME = (input: StaticStateLike): StaticStateLike => input
+
+/**
+ * The input's candidate types and reference targets at a different cardinality
+ * — the composition every selection/projection result goes through, so target
+ * metadata survives by construction instead of by per-function special cases.
+ */
+export function withSingle(input: StaticStateLike, single: boolean | undefined): StaticStateLike {
+  return input.targets === undefined
+    ? { types: input.types, single }
+    : { types: input.types, single, targets: input.targets }
+}
+
+const ITEM = (input: StaticStateLike): StaticStateLike => withSingle(input, true)
+
+/**
+ * The union of several alternative states (iif branches, coalesce arguments,
+ * merged collections): all candidate types, single only when every alternative
+ * is, and reference targets preserved when every non-empty alternative
+ * declares them (a statically empty side contributes nothing).
+ */
+export function unionStates(states: (StaticStateLike | undefined)[]): StaticStateLike {
+  const present = states.filter((state): state is StaticStateLike => state !== undefined)
+  const single = present.length > 0 ? present.map(state => state.single).reduce(singleAnd, true) : undefined
+  const contributing = present.filter(state => state.types === undefined || state.types.length > 0)
+  const targets =
+    contributing.length > 0 && contributing.every(state => state.targets !== undefined)
+      ? [...new Set(contributing.flatMap(state => state.targets as string[]))]
+      : undefined
+  const types =
+    present.length === 0 || present.some(state => state.types === undefined)
+      ? undefined
+      : [...new Set(present.flatMap(state => state.types as string[]))]
+  return targets === undefined ? { types, single } : { types, single, targets }
+}
+
+const STRING_FN: FunctionSignature = { input: { kind: 'String', singleton: true }, args: ['String'], result: STRING }
+const MATH_FN: FunctionSignature = { input: { kind: 'Numeric', singleton: true }, result: DECIMAL }
+
+/**
+ * What the analyzer knows about each function. Functions missing here still get
+ * arity checks from the runtime registry; their results become unknown.
+ */
+export const FUNCTION_SIGNATURES: Readonly<Record<string, FunctionSignature>> = {
+  empty: { result: BOOLEAN },
+  exists: { args: ['expression'], result: BOOLEAN },
+  all: { args: ['expression'], result: BOOLEAN },
+  allTrue: { input: { kind: 'Boolean' }, result: BOOLEAN },
+  anyTrue: { input: { kind: 'Boolean' }, result: BOOLEAN },
+  allFalse: { input: { kind: 'Boolean' }, result: BOOLEAN },
+  anyFalse: { input: { kind: 'Boolean' }, result: BOOLEAN },
+  count: { result: INTEGER },
+  distinct: { result: SAME },
+  isDistinct: { result: BOOLEAN },
+  subsetOf: { args: ['any'], result: BOOLEAN },
+  supersetOf: { args: ['any'], result: BOOLEAN },
+  // Filters cannot grow their input, so cardinality is preserved: filtering a
+  // single item yields at most one item.
+  where: { args: ['expression'], result: SAME },
+  select: {
+    args: ['expression'],
+    // The projection's analyzed state, collection-ized: single only when both
+    // the input and the projection body are single.
+    result: (input, args) => withSingle(args[0] ?? UNKNOWN(), singleAnd(input.single, args[0]?.single)),
+  },
+  repeat: { args: ['expression'], result: UNKNOWN },
+  // ofType/as results narrow to the named type; the analyzer computes that with
+  // the model (walkCall), so their table results are never consulted.
+  ofType: { args: ['type-name'], result: UNKNOWN },
+  is: { input: { singleton: true }, args: ['type-name'], result: BOOLEAN },
+  as: { input: { singleton: true }, args: ['type-name'], result: UNKNOWN },
+  single: { result: ITEM },
+  first: { result: ITEM },
+  last: { result: ITEM },
+  tail: { result: SAME },
+  skip: { args: ['Numeric'], result: SAME },
+  take: { args: ['Numeric'], result: SAME },
+  intersect: { args: ['any'], result: SAME },
+  exclude: { args: ['any'], result: SAME },
+  union: { args: ['any'], result: (input, args) => withSingle(unionStates([input, args[0]]), false) },
+  combine: { args: ['any'], result: (input, args) => withSingle(unionStates([input, args[0]]), false) },
+  iif: {
+    args: ['condition', 'expression', 'expression'],
+    // The union of the branch states; a missing else-branch contributes empty.
+    result: (_input, args) => unionStates([args[1], args[2] ?? { types: [], single: true }]),
+  },
+  // not() takes anything a Boolean test accepts (0/1, single items), so no kind pin.
+  not: { input: { singleton: true }, result: BOOLEAN },
+  trace: { args: ['String', 'expression'], result: SAME },
+  children: { result: UNKNOWN },
+  descendants: { result: UNKNOWN },
+  // A reference resolves to its declared target types (Reference.targetProfile,
+  // HAPI's TypeDetails.targets); an unconstrained reference stays unknown.
+  resolve: { result: input => ({ types: input.targets, single: input.single }) },
+  extension: { args: ['String'], result: UNKNOWN },
+  hasValue: { input: { singleton: true }, result: BOOLEAN },
+  getValue: { input: { singleton: true }, result: UNKNOWN },
+  htmlChecks: { input: { singleton: true }, result: BOOLEAN },
+  comparable: { input: { kind: 'Quantity', singleton: true }, args: ['Quantity'], result: BOOLEAN },
+  conformsTo: { input: { singleton: true }, args: ['String'], result: BOOLEAN },
+
+  length: { input: { kind: 'String', singleton: true }, result: INTEGER },
+  indexOf: { ...STRING_FN, result: INTEGER },
+  lastIndexOf: { ...STRING_FN, result: INTEGER },
+  substring: { input: { kind: 'String', singleton: true }, args: ['Numeric', 'Numeric'], result: STRING },
+  startsWith: { ...STRING_FN, result: BOOLEAN },
+  endsWith: { ...STRING_FN, result: BOOLEAN },
+  contains: { ...STRING_FN, result: BOOLEAN },
+  upper: { input: { kind: 'String', singleton: true }, result: STRING },
+  lower: { input: { kind: 'String', singleton: true }, result: STRING },
+  replace: { input: { kind: 'String', singleton: true }, args: ['String', 'String'], result: STRING },
+  matches: { ...STRING_FN, result: BOOLEAN },
+  matchesFull: { ...STRING_FN, result: BOOLEAN },
+  replaceMatches: { input: { kind: 'String', singleton: true }, args: ['String', 'String'], result: STRING },
+  toChars: {
+    input: { kind: 'String', singleton: true },
+    result: () => ({ types: ['System.String'], single: false }),
+  },
+  trim: { input: { kind: 'String', singleton: true }, result: STRING },
+  split: {
+    input: { kind: 'String', singleton: true },
+    args: ['String'],
+    result: () => ({ types: ['System.String'], single: false }),
+  },
+  join: { input: { kind: 'String' }, args: ['String'], result: STRING },
+  encode: STRING_FN,
+  decode: STRING_FN,
+  escape: STRING_FN,
+  unescape: STRING_FN,
+
+  abs: { input: { singleton: true }, result: UNKNOWN },
+  ceiling: { input: { kind: 'Numeric', singleton: true }, result: INTEGER },
+  floor: { input: { kind: 'Numeric', singleton: true }, result: INTEGER },
+  truncate: { input: { kind: 'Numeric', singleton: true }, result: INTEGER },
+  round: { input: { kind: 'Numeric', singleton: true }, args: ['Numeric'], result: DECIMAL },
+  exp: MATH_FN,
+  ln: MATH_FN,
+  sqrt: MATH_FN,
+  log: { input: { kind: 'Numeric', singleton: true }, args: ['Numeric'], result: DECIMAL },
+  power: { input: { kind: 'Numeric', singleton: true }, args: ['Numeric'], result: UNKNOWN },
+  aggregate: { args: ['expression', 'any'], result: UNKNOWN },
+  sum: { input: { kind: 'Numeric' }, result: UNKNOWN },
+  min: { input: { kind: 'Numeric' }, result: UNKNOWN },
+  max: { input: { kind: 'Numeric' }, result: UNKNOWN },
+  avg: { input: { kind: 'Numeric' }, result: DECIMAL },
+  sort: { args: ['sort-key'], result: SAME },
+
+  toBoolean: { input: { singleton: true }, result: BOOLEAN },
+  toInteger: { input: { singleton: true }, result: INTEGER },
+  toLong: { input: { singleton: true }, result: () => ({ types: ['System.Long'], single: true }) },
+  toDecimal: { input: { singleton: true }, result: DECIMAL },
+  toString: { input: { singleton: true }, result: STRING },
+  toDate: { input: { singleton: true }, result: () => ({ types: ['System.Date'], single: true }) },
+  toDateTime: { input: { singleton: true }, result: () => ({ types: ['System.DateTime'], single: true }) },
+  toTime: { input: { singleton: true }, result: () => ({ types: ['System.Time'], single: true }) },
+  toQuantity: {
+    input: { singleton: true },
+    args: ['String'],
+    result: () => ({ types: ['System.Quantity'], single: true }),
+  },
+  convertsToBoolean: { input: { singleton: true }, result: BOOLEAN },
+  convertsToInteger: { input: { singleton: true }, result: BOOLEAN },
+  convertsToLong: { input: { singleton: true }, result: BOOLEAN },
+  convertsToDecimal: { input: { singleton: true }, result: BOOLEAN },
+  convertsToString: { input: { singleton: true }, result: BOOLEAN },
+  convertsToDate: { input: { singleton: true }, result: BOOLEAN },
+  convertsToDateTime: { input: { singleton: true }, result: BOOLEAN },
+  convertsToTime: { input: { singleton: true }, result: BOOLEAN },
+  convertsToQuantity: { input: { singleton: true }, args: ['String'], result: BOOLEAN },
+
+  now: { result: () => ({ types: ['System.DateTime'], single: true }) },
+  today: { result: () => ({ types: ['System.Date'], single: true }) },
+  timeOfDay: { result: () => ({ types: ['System.Time'], single: true }) },
+  yearOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  monthOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  dayOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  hourOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  minuteOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  secondOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  millisecondOf: { input: { kind: 'Temporal', singleton: true }, result: INTEGER },
+  timezoneOffsetOf: { input: { kind: 'Temporal', singleton: true }, result: DECIMAL },
+  dateOf: { input: { kind: 'Temporal', singleton: true }, result: () => ({ types: ['System.Date'], single: true }) },
+  timeOf: { input: { kind: 'Temporal', singleton: true }, result: () => ({ types: ['System.Time'], single: true }) },
+  lowBoundary: { input: { singleton: true }, args: ['Numeric'], result: UNKNOWN },
+  highBoundary: { input: { singleton: true }, args: ['Numeric'], result: UNKNOWN },
+  precision: { input: { singleton: true }, result: INTEGER },
+  defineVariable: { args: ['String', 'expression'], result: SAME },
+  // Variadic: the analyzer repeats the last arg spec for every position, so one
+  // 'expression' entry covers all of coalesce's arguments. The result is the
+  // first non-empty argument, hence the union of all of them.
+  coalesce: { args: ['expression'], result: (_input, args) => unionStates([...args]) },
+  type: { result: UNKNOWN },
+}

package/src/api/bundle.ts

@@ -0,0 +1,132 @@
+import { FhirPathRuntimeError } from '../errors.ts'
+import type { ModelProvider } from '../model/provider.ts'
+import type { AstNode } from '../parser/ast.ts'
+
+/** The subset of a FHIR Bundle the engine needs in order to unwrap it. */
+export interface BundleLike {
+  resourceType: 'Bundle'
+  entry?: { resource?: unknown }[]
+}
+
+export function isBundle(value: unknown): value is BundleLike {
+  return typeof value === 'object' && value !== null && (value as { resourceType?: unknown }).resourceType === 'Bundle'
+}
+
+/** One unit of work for the per-resource engine methods (`filter`, `project`, `checkConstraints`). */
+export interface Subject {
+  value: unknown
+  /** Position in the input array or in `Bundle.entry`; absent for a single resource. */
+  index?: number
+}
+
+/**
+ * The per-resource view of an engine input: array items, a Bundle's entry
+ * resources (original entry positions kept, entries without a resource
+ * skipped), or the value itself.
+ */
+export function toSubjects(input: unknown): Subject[] {
+  if (Array.isArray(input)) {
+    return input.map((value, index) => ({ value, index }))
+  }
+  if (isBundle(input)) {
+    return (Array.isArray(input.entry) ? input.entry : [])
+      .map((entry, index) => ({ value: entry.resource, index }))
+      .filter(subject => subject.value != null)
+  }
+  return [{ value: input }]
+}
+
+const rootIdentifiersCache = new WeakMap<AstNode, ReadonlySet<string>>()
+
+/** Identifiers in root (path-head) position — the names that resolve against the input. */
+function rootIdentifiers(ast: AstNode): ReadonlySet<string> {
+  let heads = rootIdentifiersCache.get(ast)
+  if (!heads) {
+    const collected = new Set<string>()
+    collectRootIdentifiers(ast, collected)
+    rootIdentifiersCache.set(ast, collected)
+    heads = collected
+  }
+  return heads
+}
+
+function collectRootIdentifiers(node: AstNode, heads: Set<string>): void {
+  switch (node.kind) {
+    case 'identifier':
+      heads.add(node.name)
+      return
+    case 'dot':
+      // Only the head of a dotted path is a root; the right side is an element name,
+      // and arguments of dotted-in functions resolve against $this, not the input.
+      collectRootIdentifiers(node.left, heads)
+      return
+    case 'indexer':
+      collectRootIdentifiers(node.target, heads)
+      collectRootIdentifiers(node.index, heads)
+      return
+    case 'call':
+      for (const arg of node.args) {
+        collectRootIdentifiers(arg, heads)
+      }
+      return
+    case 'unary':
+      collectRootIdentifiers(node.operand, heads)
+      return
+    case 'binary':
+      collectRootIdentifiers(node.left, heads)
+      collectRootIdentifiers(node.right, heads)
+      return
+    case 'typeOp':
+      collectRootIdentifiers(node.operand, heads)
+      return
+    default:
+      return
+  }
+}
+
+/** Bundle element names (R4/R5 plus the Resource base), the fallback when no model is bound. */
+const BUNDLE_ELEMENTS = new Set([
+  'id',
+  'meta',
+  'implicitRules',
+  'language',
+  'identifier',
+  'type',
+  'timestamp',
+  'total',
+  'link',
+  'entry',
+  'signature',
+  'issues',
+])
+
+function isBundleElement(name: string, model: ModelProvider | undefined): boolean {
+  const bundleType = model?.resolveType('Bundle')
+  if (model && bundleType !== undefined) {
+    return model.getElement(bundleType, name) !== undefined
+  }
+  return BUNDLE_ELEMENTS.has(name)
+}
+
+/**
+ * Bundle in, entry resources out — unless the expression addresses the Bundle
+ * itself (a `Bundle` root). An expression whose root is a bare Bundle element
+ * (`entry.count()`, `type`) could mean either and throws instead of guessing.
+ */
+export function normalizeInput(input: unknown, ast: AstNode, model: ModelProvider | undefined): unknown {
+  if (!isBundle(input)) {
+    return input
+  }
+  const heads = rootIdentifiers(ast)
+  if (heads.has('Bundle')) {
+    return input
+  }
+  for (const head of heads) {
+    if (isBundleElement(head, model)) {
+      throw new FhirPathRuntimeError(
+        `Ambiguous expression for a Bundle input: '${head}' is a Bundle element, but a bare Bundle evaluates against its entry resources. Start the expression at Bundle to address the bundle, or wrap the input in an array to treat it as one resource.`
+      )
+    }
+  }
+  return toSubjects(input).map(subject => subject.value)
+}

package/src/api/cache.ts

@@ -0,0 +1,40 @@
+/** Small LRU built on Map insertion order; get() refreshes recency. */
+export class LruCache<V> {
+  private readonly capacity: number
+  private readonly entries = new Map<string, V>()
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 0) {
+      throw new RangeError(`LruCache capacity must be a non-negative integer, got ${capacity}`)
+    }
+    this.capacity = capacity
+  }
+
+  get(key: string): V | undefined {
+    const value = this.entries.get(key)
+    if (value !== undefined) {
+      this.entries.delete(key)
+      this.entries.set(key, value)
+    }
+    return value
+  }
+
+  set(key: string, value: V): void {
+    if (this.capacity === 0) {
+      return
+    }
+    if (this.entries.has(key)) {
+      this.entries.delete(key)
+    } else if (this.entries.size >= this.capacity) {
+      const oldest = this.entries.keys().next().value
+      if (oldest !== undefined) {
+        this.entries.delete(oldest)
+      }
+    }
+    this.entries.set(key, value)
+  }
+
+  get size(): number {
+    return this.entries.size
+  }
+}

package/src/api/column-signature.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared column signature rules for DTO registration, source walkers, and
+ * `analyzeDto`. This file accepts simple option shapes so it has no runtime or
+ * AST dependency.
+ */
+
+/** The column options this rule reads; `ColumnOptions` and an AST-derived record both satisfy it. */
+export interface ColumnTypeClaim {
+  /** The declared FHIR type (`ColumnOptions.type`). */
+  type?: string | undefined
+  /** Present when the column narrows to an `enum` of codes. */
+  enum?: unknown
+  /** Present when `as` reshapes values outside FHIRPath. */
+  as?: unknown
+  /** Present when `choices` decodes values outside FHIRPath. */
+  choices?: unknown
+}
+
+/**
+ * The type a column's values carry, or undefined when it claims nothing:
+ * `as`/`choices` hand values to JavaScript, so the expression's own result is all
+ * that can be said about them, while an `enum` only narrows codes that are
+ * Strings either way.
+ */
+export function columnResultType(column: ColumnTypeClaim): string | undefined {
+  if (column.as !== undefined || column.choices !== undefined) {
+    return undefined
+  }
+  return column.type ?? (column.enum !== undefined ? 'System.String' : undefined)
+}
+
+/**
+ * What a registered column declares as a function. `input` is the type the
+ * column was written for, which is the DTO class's `fhirType`. `result` is what
+ * its expression returns. A column may declare either, both, or neither. The
+ * shape is assignable to `CustomFunctionSignature`.
+ */
+export interface ColumnFunctionSignature {
+  input?: { types: string[] }
+  result?: { types: string[]; single: boolean }
+}
+
+/**
+ * Returns the function signature contributed by a column. `hostType` is the DTO
+ * type. A source walker may omit it when the class root is not visible.
+ */
+export function columnSignature(
+  column: ColumnTypeClaim & { collection?: boolean },
+  hostType?: string
+): ColumnFunctionSignature | undefined {
+  const type = columnResultType(column)
+  const input = hostType === undefined ? undefined : { types: [hostType] }
+  const result = type === undefined ? undefined : { types: [type], single: column.collection !== true }
+  if (input === undefined && result === undefined) {
+    return undefined
+  }
+  return { ...(input !== undefined && { input }), ...(result !== undefined && { result }) }
+}
+
+/**
+ * The signature a `@criteria` contributes. Its expression goes through the
+ * criteria rule (see `criteriaBoolean`), so the function returns a single
+ * Boolean whatever the expression returns. This is a function rather than a
+ * shared constant, so one caller cannot change what the next caller reads.
+ */
+export function criteriaSignature(hostType?: string): ColumnFunctionSignature {
+  return {
+    ...(hostType !== undefined && { input: { types: [hostType] } }),
+    result: { types: ['System.Boolean'], single: true },
+  }
+}