fhirpath-ts 0.0.0-bootstrap.0

package/src/api/engine.ts

@@ -0,0 +1,328 @@
+import { mergeEnvKeys } from '../engine/context.ts'
+import type { R4TypeOf } from '../r4/generated/type-maps.ts'
+import type { FhirpathInput, FhirpathResult } from '../typed/infer.ts'
+import { criteriaBoolean } from '../values/collection.ts'
+import type { TypedValue } from '../values/typed-value.ts'
+import { type BundleLike, isBundle, normalizeInput, toSubjects } from './bundle.ts'
+import {
+  type AnyExpression,
+  CompiledExpression,
+  type Compiler,
+  createCachedCompiler,
+  type CustomFunction,
+  type EvaluateOptions,
+  type SingleCustomFunction,
+} from './compile.ts'
+import { type ConstraintCheckResult, evaluateConstraints, type FhirConstraint } from './constraints.ts'
+import { assertInputMatchesDto, dtoCallOptions, type DtoClass, dtoDefinition, withDtos } from './dto.ts'
+import { type Projection, type ProjectionColumns, projectRows } from './project.ts'
+
+/**
+ * What engine methods accept as input: one resource, an array of resources, or a
+ * Bundle — a Bundle behaves as its entry resources unless the expression
+ * references `Bundle` in root position (then it addresses the bundle itself).
+ * An expression that starts at a bare Bundle element (`entry.count()`, `type`)
+ * is ambiguous and throws. Wrap a Bundle in an array (`[bundle]`) to force
+ * treating it as one resource.
+ */
+export type EngineInput<Expr extends string = string> = FhirpathInput<Expr> | readonly unknown[] | BundleLike
+
+/** Per-call options that declare a result type when inference returns `unknown`. Runtime code ignores `type`. */
+export type TypedEvaluateOptions<T extends keyof R4TypeOf> = EvaluateOptions & { type: T }
+
+/** Engines created during the current recording session. */
+let session: FhirPathEngine[] | undefined
+
+/**
+ * Records engines created while project modules are imported. Call the returned
+ * function to close the session and read its engines. Only one session is active
+ * at a time, and closing it releases the recorded engine references.
+ */
+export function recordEngines(): () => readonly FhirPathEngine[] {
+  const open: FhirPathEngine[] = []
+  session = open
+  return () => {
+    if (session === open) {
+      session = undefined
+    }
+    return open
+  }
+}
+
+function recordEngine(engine: FhirPathEngine): void {
+  session?.push(engine)
+}
+
+/**
+ * What a `FhirPathEngine` takes at construction: the `EvaluateOptions` it binds
+ * as per-call defaults, plus settings that belong to the engine itself.
+ */
+export interface EngineOptions extends EvaluateOptions {
+  /**
+   * Max number of distinct expression texts this engine keeps parsed, in its own
+   * LRU (not shared with other engines or the free `evaluate()`). Defaults to 500;
+   * 0 disables reuse. Expressions passed via `compile()` bypass it.
+   *
+   * Read once, at construction: unlike the `EvaluateOptions` fields, this is not
+   * part of `defaults` and a per-call `options` argument cannot change it.
+   */
+  cacheSize?: number
+  /**
+   * DTOs whose columns become typed FHIRPath functions. Registration requires a
+   * model and publishes every column name, but it does not publish DTO `env` or
+   * `vars`. Same-name columns are allowed only when their input types do not
+   * overlap. See `docs/api.md#registering-dto-columns-as-functions`.
+   */
+  resourceDtos?: readonly DtoClass[]
+}
+
+/**
+ * A FHIRPath engine with shared model and evaluation defaults. Per-call values
+ * replace defaults, while `env`, `vars`, and `functions` merge by name. Keep an
+ * engine for reuse because its parse cache is private to that instance.
+ */
+export class FhirPathEngine {
+  /** The per-call options bound at construction; engine-only settings are not part of them. */
+  readonly defaults: EvaluateOptions
+  /**
+   * The DTO classes registered at construction (EngineOptions.resourceDtos), in
+   * order. Kept so tooling can check them against this engine's own model,
+   * functions and env — see `analyzeEngineDtos` in `fhirpath-ts/analyzer`.
+   */
+  readonly dtos: readonly DtoClass[]
+  private readonly compileCached: Compiler
+
+  constructor({ cacheSize, resourceDtos, ...defaults }: EngineOptions = {}) {
+    this.compileCached = createCachedCompiler(cacheSize)
+    this.dtos = resourceDtos ?? []
+    this.defaults = this.precompiled(withDtos(defaults, this.dtos, this.compileCached))
+    recordEngine(this)
+  }
+
+  /** Compile (LRU-cached by expression text) and evaluate in one call; typed like `compile().evaluate()`. */
+  evaluate<const Expr extends string, T extends keyof R4TypeOf>(
+    expression: Expr | CompiledExpression<Expr>,
+    input: EngineInput<Expr> | undefined,
+    options: TypedEvaluateOptions<T>
+  ): R4TypeOf[T][]
+  evaluate<const Expr extends string>(
+    expression: Expr | CompiledExpression<Expr>,
+    input?: EngineInput<Expr>,
+    options?: EvaluateOptions
+  ): FhirpathResult<Expr>
+  evaluate(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): unknown[] {
+    const compiled = this.compileCached(expression)
+    const merged = this.merged(options)
+    return compiled.evaluate(normalizeInput(input, compiled.ast, merged.model), merged)
+  }
+
+  /** Like `evaluate()`, keeping the internal typed representation (types, Decimal, Temporal). */
+  evaluateTyped(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): TypedValue[] {
+    const compiled = this.compileCached(expression)
+    const merged = this.merged(options)
+    return compiled.evaluateTyped(normalizeInput(input, compiled.ast, merged.model), merged)
+  }
+
+  /** Parse once for reuse, with this engine's defaults bound. Does not touch the parse cache. */
+  compile<const Expr extends string>(expression: Expr): BoundExpression<Expr> {
+    return new BoundExpression(this, new CompiledExpression(expression))
+  }
+
+  /** The first result, or undefined when the expression comes up empty. */
+  first<const Expr extends string, T extends keyof R4TypeOf>(
+    expression: Expr | CompiledExpression<Expr>,
+    input: EngineInput<Expr> | undefined,
+    options: TypedEvaluateOptions<T>
+  ): R4TypeOf[T] | undefined
+  first<const Expr extends string>(
+    expression: Expr | CompiledExpression<Expr>,
+    input?: EngineInput<Expr>,
+    options?: EvaluateOptions
+  ): FhirpathResult<Expr>[number] | undefined
+  first(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): unknown {
+    return this.evaluate(expression, input, options)[0]
+  }
+
+  /**
+   * Boolean criteria evaluation, the semantics FHIR invariants, Subscription
+   * criteria, and `enableWhen` share. A single boolean returns itself, a single
+   * non-boolean item returns true, and more than one item is an error, which is
+   * spec §4.5 singleton evaluation. Empty returns false, which is the criteria
+   * convention layered on top of it; see `criteriaBoolean`.
+   */
+  test(input: unknown, expression: AnyExpression, options?: EvaluateOptions): boolean {
+    return criteriaBoolean(this.evaluateTyped(expression, input, options))
+  }
+
+  /**
+   * The items (or Bundle entry resources) whose criteria hold, by `test()`
+   * semantics. Criteria run against each item directly — not via `test()` — so
+   * an item that is itself a Bundle is not unwrapped again.
+   */
+  filter<T>(input: readonly T[], expression: AnyExpression, options?: EvaluateOptions): T[]
+  filter(input: BundleLike, expression: AnyExpression, options?: EvaluateOptions): unknown[]
+  filter(input: readonly unknown[] | BundleLike, expression: AnyExpression, options?: EvaluateOptions): unknown[] {
+    const compiled = this.compileCached(expression)
+    const merged = this.merged(options)
+    return toSubjects(input)
+      .map(subject => subject.value)
+      .filter(value => criteriaBoolean(compiled.evaluateTyped(value, merged)))
+  }
+
+  /**
+   * Projects each resource into a flat row. Columns return one optional value
+   * unless `collection: true` is set. `%rowIndex` and `%rowTotal` are available
+   * in every column. All columns compile before any row is read.
+   */
+  project<C extends DtoClass>(
+    input: readonly unknown[] | BundleLike,
+    dto: C,
+    options?: EvaluateOptions
+  ): InstanceType<C>[]
+  project<C extends DtoClass>(input: unknown, dto: C, options?: EvaluateOptions): InstanceType<C>
+  project<const Columns extends ProjectionColumns>(
+    input: readonly unknown[] | BundleLike,
+    columns: Columns,
+    options?: EvaluateOptions
+  ): Projection<Columns>[]
+  project<const Columns extends ProjectionColumns>(
+    input: unknown,
+    columns: Columns,
+    options?: EvaluateOptions
+  ): Projection<Columns>
+  project(input: unknown, columns: ProjectionColumns | DtoClass, options?: EvaluateOptions): unknown {
+    if (typeof columns === 'function') {
+      assertInputMatchesDto(input, columns)
+    }
+    const rows =
+      typeof columns === 'function'
+        ? projectRows(
+            input,
+            dtoDefinition(columns).columns,
+            this.merged(dtoCallOptions(columns, options)),
+            this.compileCached
+          )
+            // Materialize each row as a class instance, so the DTO's own methods
+            // and getters see the projected values.
+            .map(row => Object.assign(new columns(), row))
+        : projectRows(input, columns, this.merged(options), this.compileCached)
+    return Array.isArray(input) || isBundle(input) ? rows : rows[0]
+  }
+
+  /**
+   * Evaluates FHIR constraint expressions. Arrays and Bundles add the resource
+   * index to each issue. Expression errors become failed issues. This is not full
+   * profile validation.
+   */
+  checkConstraints(
+    input: unknown,
+    constraints: readonly FhirConstraint[],
+    options?: EvaluateOptions
+  ): ConstraintCheckResult {
+    return evaluateConstraints(input, constraints, this.merged(options), this.compileCached)
+  }
+
+  /**
+   * Replaces scalar defaults and merges `env`, `vars`, and `functions` by name.
+   * Per-call entries win. Environment keys are normalized with or without `%`.
+   */
+  private merged(options?: EvaluateOptions): EvaluateOptions {
+    if (!options) {
+      return this.defaults
+    }
+    const precompiled = this.precompiled(options)
+    const merged = { ...this.defaults, ...precompiled }
+    if (this.defaults.env && precompiled.env) {
+      merged.env = mergeEnvKeys(this.defaults.env, precompiled.env)
+    }
+    if (this.defaults.vars && precompiled.vars) {
+      merged.vars = mergeEnvKeys(this.defaults.vars, precompiled.vars)
+    }
+    if (this.defaults.functions && precompiled.functions) {
+      merged.functions = { ...this.defaults.functions, ...precompiled.functions }
+    }
+    return merged
+  }
+
+  /**
+   * `vars` expressions and expression-function bodies given as strings parse
+   * through this engine's LRU here, once per call at most — so per-row
+   * evaluation inside project() never re-parses them.
+   */
+  private precompiled(options: EvaluateOptions): EvaluateOptions {
+    const out = { ...options }
+    if (options.vars) {
+      out.vars = Object.fromEntries(
+        Object.entries(options.vars).map(([name, value]) => [
+          name,
+          typeof value === 'string' ? this.compileCached(value) : value,
+        ])
+      )
+    }
+    if (options.functions) {
+      out.functions = Object.fromEntries(
+        Object.entries(options.functions).map(([name, fn]) => [name, this.precompiledFunction(fn)])
+      )
+    }
+    return out
+  }
+
+  /** One entry of `functions`, with any string body parsed — reaching into an overload set for each member. */
+  private precompiledFunction(fn: CustomFunction): CustomFunction {
+    return 'overloads' in fn
+      ? { overloads: fn.overloads.map(overload => this.precompiledBody(overload)) }
+      : this.precompiledBody(fn)
+  }
+
+  private precompiledBody(fn: SingleCustomFunction): SingleCustomFunction {
+    return 'expression' in fn && typeof fn.expression === 'string'
+      ? { ...fn, expression: this.compileCached(fn.expression) }
+      : fn
+  }
+}
+
+/** A compiled expression carrying an engine's defaults, so `evaluate(input)` needs nothing else. */
+export class BoundExpression<Expr extends string = string> {
+  readonly expression: CompiledExpression<Expr>
+  private readonly engine: FhirPathEngine
+
+  constructor(engine: FhirPathEngine, expression: CompiledExpression<Expr>) {
+    this.engine = engine
+    this.expression = expression
+  }
+
+  get source(): string {
+    return this.expression.source
+  }
+
+  evaluate<T extends keyof R4TypeOf>(
+    input: EngineInput<Expr> | undefined,
+    options: TypedEvaluateOptions<T>
+  ): R4TypeOf[T][]
+  evaluate(input?: EngineInput<Expr>, options?: EvaluateOptions): FhirpathResult<Expr>
+  evaluate(input?: EngineInput<Expr>, options?: EvaluateOptions): unknown {
+    return this.engine.evaluate(this.expression, input, options)
+  }
+
+  evaluateTyped(input?: unknown, options?: EvaluateOptions): TypedValue[] {
+    return this.engine.evaluateTyped(this.expression, input, options)
+  }
+
+  first<T extends keyof R4TypeOf>(
+    input: EngineInput<Expr> | undefined,
+    options: TypedEvaluateOptions<T>
+  ): R4TypeOf[T] | undefined
+  first(input?: EngineInput<Expr>, options?: EvaluateOptions): FhirpathResult<Expr>[number] | undefined
+  first(input?: EngineInput<Expr>, options?: EvaluateOptions): unknown {
+    return this.engine.first(this.expression, input, options)
+  }
+
+  test(input: unknown, options?: EvaluateOptions): boolean {
+    return this.engine.test(input, this.expression, options)
+  }
+
+  /** The canonical form of the expression. */
+  toString(): string {
+    return this.expression.toString()
+  }
+}

package/src/api/evaluate.ts

@@ -0,0 +1,11 @@
+import { type AnyExpression, createCachedCompiler, type EvaluateOptions } from './compile.ts'
+
+const compileCached = createCachedCompiler()
+
+/**
+ * Evaluate a FHIRPath expression against an input and return plain JS values.
+ * Parsed expressions are kept in a module-level LRU keyed by the expression text.
+ */
+export function evaluate(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): unknown[] {
+  return compileCached(expression).evaluate(input, options)
+}

package/src/api/project.ts

@@ -0,0 +1,255 @@
+import { type EvaluationContext, forkVariables } from '../engine/context.ts'
+import { evaluateNode } from '../engine/evaluator.ts'
+import { FhirPathRuntimeError } from '../errors.ts'
+import type { R4TypeOf } from '../r4/generated/type-maps.ts'
+import type { FhirpathResultIn } from '../typed/infer.ts'
+import { criteriaBoolean } from '../values/collection.ts'
+import { toCollection, type TypedValue, unwrap } from '../values/typed-value.ts'
+import { toSubjects } from './bundle.ts'
+import { type Compiler, contextFactory, type EvaluateOptions } from './compile.ts'
+
+/**
+ * One `project()` column. A string or `{ path }` returns one optional value.
+ * `collection` keeps every value, `default` fills an empty result, and `test`
+ * returns one criteria boolean. `as`, `choices`, and `enum` are alternative
+ * value conversions. `type` declares a result type for TypeScript and is not
+ * checked at runtime. See `docs/api.md#project` for all options.
+ */
+export type ProjectionColumn = string | ({ path: string } & ColumnOptions) | { test: string }
+
+/** Options shared by plain project columns and DTO `@column` fields. */
+export type ColumnOptions = {
+  collection?: boolean
+  type?: keyof R4TypeOf
+  default?: unknown
+} & (
+  | { as?: 'Date' | ((value: unknown) => unknown); choices?: never; pick?: never; enum?: never }
+  | { choices: Readonly<Record<string, unknown>>; as?: never; pick?: never; enum?: never }
+  | { choices: readonly { code: string }[]; pick?: string; as?: never; enum?: never }
+  | { enum: readonly string[]; as?: never; choices?: never; pick?: never }
+)
+
+export type ProjectionColumns = Record<string, ProjectionColumn>
+
+type ColumnPath<Column> = Column extends string
+  ? Column
+  : Column extends { path: infer Path extends string }
+    ? Path
+    : never
+
+/** Infers the values after the selected conversion, or from the path when no conversion is set. */
+type ColumnValues<Column, Root extends string> = Column extends { as: (value: never) => infer R }
+  ? R[]
+  : Column extends { as: 'Date' }
+    ? Date[]
+    : Column extends { choices: readonly (infer Row extends { code: string })[] }
+      ? Column extends { pick: infer Key extends keyof Row }
+        ? Row[Key][]
+        : Row[]
+      : Column extends { choices: infer M extends Readonly<Record<string, unknown>> }
+        ? M[keyof M][]
+        : Column extends { enum: readonly (infer V extends string)[] }
+          ? V[]
+          : Column extends { type: infer T extends keyof R4TypeOf }
+            ? R4TypeOf[T][]
+            : FhirpathResultIn<ColumnPath<Column>, Root>
+
+/** A column's output type. A default replaces `undefined`; a collection returns every value. */
+export type ColumnResult<
+  Column extends string | { path: string } | { test: string },
+  Root extends string = 'opaque',
+> = Column extends {
+  test: string
+}
+  ? boolean
+  : Column extends { collection: true }
+    ? ColumnValues<Column, Root>
+    : Column extends { default: infer D }
+      ? ColumnValues<Column, Root>[number] | D
+      : ColumnValues<Column, Root>[number] | undefined
+
+/** The row shape `project()` produces: each column's type inferred from its expression. */
+export type Projection<Columns extends ProjectionColumns, Root extends string = 'opaque'> = {
+  -readonly [K in keyof Columns]: ColumnResult<Columns[K], Root>
+}
+
+/** The `as: 'Date'` coercion; a value that is not a parseable date string becomes empty. */
+function toJsDates(values: unknown[]): Date[] {
+  return values.flatMap(value => {
+    if (typeof value !== 'string') {
+      return []
+    }
+    const date = new Date(value)
+    return Number.isNaN(date.getTime()) ? [] : [date]
+  })
+}
+
+/** The string key `choices` looks up: primitives via String(), anything else never matches. */
+function mapKey(value: unknown): string | undefined {
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+    ? String(value)
+    : undefined
+}
+
+/** The `choices` lookup over a plain Record: own keys only; a miss becomes empty. */
+function recordLookup(choices: Readonly<Record<string, unknown>>): (values: unknown[]) => unknown[] {
+  return values =>
+    values.flatMap(value => {
+      const key = mapKey(value)
+      return key !== undefined && Object.hasOwn(choices, key) ? [choices[key]] : []
+    })
+}
+
+/** Looks up display rows by `code`. The first row wins; a missing row or field returns empty. */
+function tableLookup(rows: readonly { code: string }[], pick: string | undefined): (values: unknown[]) => unknown[] {
+  const byCode = new Map<string, { code: string }>()
+  for (const row of rows) {
+    if (!byCode.has(row.code)) {
+      byCode.set(row.code, row)
+    }
+  }
+  return values =>
+    values.flatMap(value => {
+      const key = mapKey(value)
+      const row = key === undefined ? undefined : byCode.get(key)
+      if (row === undefined) {
+        return []
+      }
+      if (pick === undefined) {
+        return [row]
+      }
+      const field = (row as Record<string, unknown>)[pick]
+      return field === undefined ? [] : [field]
+    })
+}
+
+/** The `enum` check: values outside the listed strings become empty. */
+function enumLookup(allowed: readonly string[]): (values: unknown[]) => unknown[] {
+  const members = new Set<unknown>(allowed)
+  return values => values.filter(value => members.has(value))
+}
+
+/** The table form of `choices`; Array.isArray alone cannot exclude the Record form for the checker. */
+function isTable(
+  choices: Readonly<Record<string, unknown>> | readonly { code: string }[]
+): choices is readonly { code: string }[] {
+  return Array.isArray(choices)
+}
+
+/** Resolve a column's `as`/`choices`/`enum` option into its values mapping. */
+function coercion(spec: Extract<ProjectionColumn, { path: string }>): (values: unknown[]) => unknown[] {
+  if (spec.choices !== undefined) {
+    return isTable(spec.choices) ? tableLookup(spec.choices, spec.pick) : recordLookup(spec.choices)
+  }
+  if (spec.enum !== undefined) {
+    return enumLookup(spec.enum)
+  }
+  if (spec.as === 'Date') {
+    return toJsDates
+  }
+  if (typeof spec.as === 'function') {
+    const as = spec.as
+    return values => values.map(as)
+  }
+  return values => values
+}
+
+/** Checks conversion options for JavaScript callers and transpile-only code. */
+function assertShaperOptions(name: string, spec: Extract<ProjectionColumn, { path: string }>): void {
+  const shapers = [spec.as, spec.choices, spec.enum].filter(option => option !== undefined).length
+  if (shapers > 1) {
+    throw new FhirPathRuntimeError(
+      `project(): column '${name}' declares more than one of 'as', 'choices', 'enum'; use one`
+    )
+  }
+  if (spec.pick !== undefined && !Array.isArray(spec.choices)) {
+    throw new FhirPathRuntimeError(
+      `project(): column '${name}' has 'pick' without a table 'choices' (an array of { code, … } rows)`
+    )
+  }
+  if (spec.pick !== undefined && Array.isArray(spec.choices) && spec.choices.length > 0) {
+    const pick = spec.pick
+    // A field no row carries is a typo, not a sparse table — fail at plan time.
+    if (!spec.choices.some(row => Object.hasOwn(row as object, pick))) {
+      throw new FhirPathRuntimeError(`project(): column '${name}' picks '${pick}', which no row of its table has`)
+    }
+  }
+}
+
+/**
+ * A column resolved against one compiler, ready to run once per row-context.
+ * Each read forks the context's variables, so one column's defineVariable()
+ * never leaks into the next. `at` locates the row for an error message.
+ */
+type ColumnReader = (root: TypedValue[], context: EvaluationContext, at: RowPosition) => unknown
+
+/** Where a row sits in the batch, for the errors that need to point at one of many. */
+interface RowPosition {
+  index: number
+  total: number
+}
+
+/**
+ * Which row an error came from, when there is more than one to choose between.
+ * A single-resource projection has no position worth reporting, so it says
+ * nothing rather than "row 0".
+ */
+function inRow({ index, total }: RowPosition): string {
+  return total > 1 ? ` in row ${index}` : ''
+}
+
+/** Take the column union apart once, at plan time; rows only run the result. */
+function planColumn(name: string, column: ProjectionColumn, compile: Compiler): ColumnReader {
+  if (typeof column !== 'string' && 'test' in column) {
+    const criteria = compile(column.test)
+    return (root, context) => criteriaBoolean(evaluateNode(criteria.ast, forkVariables(context), root))
+  }
+  const spec: Extract<ProjectionColumn, { path: string }> = typeof column === 'string' ? { path: column } : column
+  assertShaperOptions(name, spec)
+  const expression = compile(spec.path)
+  const applyAs = coercion(spec)
+  const empty = 'default' in spec ? spec.default : undefined
+  return (root, context, at) => {
+    const values = evaluateNode(expression.ast, forkVariables(context), root).map(unwrap)
+    if (spec.collection === true) {
+      return applyAs(values)
+    }
+    // The scalar-column rule counts the expression's values, before any `as`
+    // coercion or `choices` miss drops them. One row of a batch can be the only
+    // one that breaks it, so the message says which — `%rowIndex` numbering,
+    // the same the columns see.
+    if (values.length > 1) {
+      throw new FhirPathRuntimeError(
+        `project(): column '${name}' yielded ${values.length} values${inRow(at)}; append first() or set collection: true`
+      )
+    }
+    const coerced = applyAs(values)
+    return coerced.length > 0 ? coerced[0] : empty
+  }
+}
+
+/**
+ * Projects one row per input subject. Each row gets one shared context, so
+ * variables bind once and every column reads the same values. Runtime
+ * `%rowIndex` and `%rowTotal` replace matching environment entries.
+ */
+export function projectRows(
+  input: unknown,
+  columns: ProjectionColumns,
+  options: EvaluateOptions,
+  compile: Compiler
+): Record<string, unknown>[] {
+  const readers = Object.entries(columns).map(([name, column]) => [name, planColumn(name, column, compile)] as const)
+  const makeContext = contextFactory(options)
+  const subjects = toSubjects(input)
+  return subjects.map((subject, index) => {
+    const root = toCollection(subject.value)
+    const at: RowPosition = { index, total: subjects.length }
+    const context = makeContext(root, { rowIndex: index, rowTotal: subjects.length })
+    const row: Record<string, unknown> = {}
+    for (const [name, read] of readers) {
+      row[name] = read(root, context, at)
+    }
+    return row
+  })
+}

package/src/api/tagged.ts

@@ -0,0 +1,35 @@
+import { FhirPathError } from '../errors.ts'
+import type { R4TypeOf } from '../r4/generated/type-maps.ts'
+import type { FhirpathInput, FhirpathResult, FhirpathResultIn, FhirTypeName } from '../typed/infer.ts'
+import { CompiledExpression } from './compile.ts'
+
+/**
+ * Compiles a FHIRPath expression. The call form infers supported literal
+ * expressions. Its optional input type gives relative paths a type context for
+ * inference and source checks. The tagged form returns `unknown[]` because
+ * TypeScript does not preserve the literal type. Tags reject interpolation; use
+ * environment variables for data.
+ */
+export function fhirpath<
+  const Expr extends string,
+  const Root extends FhirTypeName,
+  TResult extends unknown[] = FhirpathResultIn<Expr, Root>,
+>(expression: Expr, inputType: Root): CompiledExpression<Expr, R4TypeOf[Root], TResult>
+export function fhirpath<
+  const Expr extends string,
+  TInput = FhirpathInput<Expr>,
+  TResult extends unknown[] = FhirpathResult<Expr>,
+>(expression: Expr): CompiledExpression<Expr, TInput, TResult>
+export function fhirpath(strings: TemplateStringsArray, ...substitutions: never[]): CompiledExpression
+export function fhirpath(input: string | TemplateStringsArray, ...rest: unknown[]): CompiledExpression {
+  if (typeof input === 'string') {
+    // The optional input type is used by TypeScript and source checks only.
+    return new CompiledExpression(input)
+  }
+  if (rest.length > 0) {
+    throw new FhirPathError(
+      'fhirpath`...` does not support interpolation; pass values as environment variables instead'
+    )
+  }
+  return new CompiledExpression(input[0] as string)
+}