fhirpath-ts 0.0.0-bootstrap.0

package/dist/api/dto.d.ts

@@ -0,0 +1,134 @@
+import '../functions/install.ts';
+import type { FhirTypeName } from '../typed/infer.ts';
+import type { TypedValue } from '../values/typed-value.ts';
+import type { AnyExpression, Compiler, EvaluateOptions } from './compile.ts';
+import type { ColumnOptions, ColumnResult, ProjectionColumn } from './project.ts';
+/** The object forms of ProjectionColumn — what a `@column`/`@criteria` decorator records. */
+export type ColumnSpec = Exclude<ProjectionColumn, string>;
+/**
+ * Ties `pick` to the table's row keys: with a table `choices`, `pick` must name
+ * a row field; without one, `pick` is rejected outright. Applied as a validation
+ * intersection on the options parameter, so a `pick` typo is a compile error at
+ * the decorator.
+ */
+type PickConstraint<Options> = Options extends {
+    choices: readonly (infer Row extends {
+        code: string;
+    })[];
+} ? {
+    pick?: keyof Row & string;
+} : {
+    pick?: never;
+};
+/** TypeScript error data for a DTO field that cannot hold its column result. */
+export interface ColumnTypeMismatch<Declared, Inferred> {
+    readonly __brand: 'fhirpath-ts: the declared field type cannot hold what this column yields';
+    readonly declared: Declared;
+    readonly inferred: Inferred;
+}
+/** Accepts unknown inference; `analyzeDto` checks an explicit column `type`. */
+type Checked<Inferred, Declared> = unknown extends Inferred ? (initial: Declared) => Declared : [Inferred] extends [Declared] ? (initial: Declared) => Declared : ColumnTypeMismatch<Declared, Inferred>;
+/** Every DTO instance carries the type its columns read, which is also their inference root. */
+export interface DtoInstance {
+    readonly fhirType: string;
+}
+/** The inference root for a DTO's columns: the `fhirType` of the class they are declared on. */
+type RootOf<This> = This extends {
+    readonly fhirType: infer Root extends string;
+} ? Root : 'opaque';
+/** A checked field decorator for a column whose value type is already fixed (a criteria). */
+type ColumnDecorator<Value> = <This extends DtoInstance, Declared>(target: undefined, context: ClassFieldDecoratorContext<This, Declared>) => Checked<Value, Declared>;
+/** A checked field decorator whose column value depends on the root it lands on. */
+type PathDecorator<Column extends {
+    path: string;
+}> = <This extends DtoInstance, Declared>(target: undefined, context: ClassFieldDecoratorContext<This, Declared>) => Checked<ColumnResult<Column, RootOf<This>>, Declared>;
+/**
+ * Environment values owned by a DTO. Declare them as `static env`, with keys
+ * written with or without `%`. They apply only to that DTO's column bodies.
+ * Subclasses merge values by key; annotate a base field as `DtoEnv` when a
+ * subclass should override only part of the record.
+ */
+export type DtoEnv = Record<string, unknown>;
+/** Base class returned by `defineDto()`, with the FHIR type used for column inference. */
+export type DtoBase<Root extends string> = (new () => {
+    readonly fhirType: Root;
+}) & {
+    readonly fhirType: Root;
+};
+/** A DTO class: a `defineDto()` base, or any class extending one. */
+export type DtoClass = (new () => DtoInstance) & {
+    readonly fhirType: string;
+};
+/** The DTO instance type returned by projection, including getters and methods. */
+export type DtoRow<C extends DtoClass> = InstanceType<C>;
+/** Data a DTO reads in addition to the projected resource. DTO-owned values use `static env`. */
+export interface DtoOptions {
+    /** Per-row bindings the columns read (EvaluateOptions.vars semantics; may reference per-call env). */
+    vars?: Record<string, AnyExpression | readonly TypedValue[]>;
+    /** Environment names supplied by `project()`, declared so DTO checks can resolve them. */
+    callerEnv?: readonly string[];
+}
+/** Everything a DTO class was declared with; `project()`, the engine, and `analyzeDto` all read it from here. */
+export interface DtoDefinition {
+    readonly fhirType: string;
+    /** A decorator always records an object form, so a consumer never has to handle the plain-string column. */
+    readonly columns: Readonly<Record<string, ColumnSpec>>;
+    /** The `static env` fields down the class chain, merged per name with the most derived winning. */
+    readonly env: Record<string, unknown> | undefined;
+    readonly vars: Record<string, AnyExpression | readonly TypedValue[]> | undefined;
+    /** Env names the projecting call supplies (see DtoOptions.callerEnv). */
+    readonly callerEnv: readonly string[] | undefined;
+}
+/**
+ * Creates a DTO base for one FHIR resource or datatype. The type becomes the
+ * context for relative column paths. Subclasses may add decorated fields,
+ * getters, methods, and shared base columns.
+ */
+export declare function defineDto<const Root extends FhirTypeName>(fhirType: Root, options?: DtoOptions): DtoBase<Root>;
+/**
+ * Declares one column of a DTO: the expression it reads, relative to the
+ * class's `fhirType`, plus the same options a `project()` column takes —
+ * `type`, `as`, `choices`/`pick`, `enum`, `default`, `collection`. The field's
+ * declared type is checked against what the expression yields, and is the type
+ * a projected row holds there.
+ */
+export declare function column<const Expr extends string>(path: Expr): PathDecorator<{
+    path: Expr;
+}>;
+export declare function column<const Expr extends string, const Options extends ColumnOptions>(path: Expr, options: Options & PickConstraint<Options>): PathDecorator<{
+    path: Expr;
+} & Options>;
+/**
+ * Declares a Boolean criteria column. It uses `FhirPathEngine.test()` rules: one
+ * Boolean returns itself, empty returns `false`, and several values are an
+ * error. A registered criteria function keeps the same behavior.
+ */
+export declare function criteria<const Expr extends string>(expr: Expr): ColumnDecorator<boolean>;
+/**
+ * Whether a value is a DTO class — one `defineDto()` produced, or a subclass of
+ * one. Lets tooling pick the DTOs out of a module's exports (see the
+ * `fhirpath-check` CLI) without instantiating anything that is not one.
+ */
+export declare function isDtoClass(value: unknown): value is DtoClass;
+/** Collects and caches a DTO's type, columns, environment, variables, and caller environment names. */
+export declare function dtoDefinition(cls: DtoClass): DtoDefinition;
+/**
+ * Adds DTO columns to the engine's function table. Each function keeps its DTO
+ * input type and environment. Same-name functions become overloads when their
+ * input types do not overlap.
+ */
+export declare function withDtos(defaults: EvaluateOptions, dtos: readonly DtoClass[], compile: Compiler): EvaluateOptions;
+/**
+ * Checks each resource against the DTO type before projection. Without this
+ * check, a wrong resource could produce a typed row filled with defaults.
+ * Datatype inputs have no `resourceType` to check.
+ */
+export declare function assertInputMatchesDto(input: unknown, dto: DtoClass): void;
+/**
+ * Merges DTO options with call options. DTO environment values win so projected
+ * and registered columns read the same value. Call variables win because they
+ * may replace a DTO's row binding.
+ */
+export declare function dtoCallOptions(dto: DtoClass, options: EvaluateOptions | undefined): EvaluateOptions | undefined;
+export {};
+//# sourceMappingURL=dto.d.ts.map

package/dist/api/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/api/dto.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAA;AAMhC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAG1D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAkB,eAAe,EAAwB,MAAM,cAAc,CAAA;AAClH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAEjF,6FAA6F;AAC7F,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAA;AAE1D;;;;;GAKG;AACH,KAAK,cAAc,CAAC,OAAO,IAAI,OAAO,SAAS;IAAE,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAA;CAAE,GACvG;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,GAAG,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAEpB,gFAAgF;AAChF,MAAM,WAAW,kBAAkB,CAAC,QAAQ,EAAE,QAAQ;IACpD,QAAQ,CAAC,OAAO,EAAE,0EAA0E,CAAA;IAC5F,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAC5B;AAED,gFAAgF;AAChF,KAAK,OAAO,CAAC,QAAQ,EAAE,QAAQ,IAAI,OAAO,SAAS,QAAQ,GACvD,CAAC,OAAO,EAAE,QAAQ,KAAK,QAAQ,GAC/B,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,GAC3B,CAAC,OAAO,EAAE,QAAQ,KAAK,QAAQ,GAC/B,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAE5C,gGAAgG;AAChG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,gGAAgG;AAChG,KAAK,MAAM,CAAC,IAAI,IAAI,IAAI,SAAS;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,SAAS,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,QAAQ,CAAA;AAEnG,6FAA6F;AAC7F,KAAK,eAAe,CAAC,KAAK,IAAI,CAAC,IAAI,SAAS,WAAW,EAAE,QAAQ,EAC/D,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,KAChD,OAAO,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;AAE7B,oFAAoF;AACpF,KAAK,aAAa,CAAC,MAAM,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,IAAI,CAAC,IAAI,SAAS,WAAW,EAAE,QAAQ,EACvF,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,0BAA0B,CAAC,IAAI,EAAE,QAAQ,CAAC,KAChD,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAE5C,0FAA0F;AAC1F,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,IAAI,CAAC,UAAU;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhH,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,CAAC,UAAU,WAAW,CAAC,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAA;AAE9E,mFAAmF;AACnF,MAAM,MAAM,MAAM,CAAC,CAAC,SAAS,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC,CAAA;AAExD,iGAAiG;AACjG,MAAM,WAAW,UAAU;IACzB,sGAAsG;IACtG,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,UAAU,EAAE,CAAC,CAAA;IAC5D,0FAA0F;IAC1F,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC9B;AAED,iHAAiH;AACjH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4GAA4G;IAC5G,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;IACtD,mGAAmG;IACnG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,UAAU,EAAE,CAAC,GAAG,SAAS,CAAA;IAChF,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAClD;AAmBD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,IAAI,SAAS,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlH;AA2BD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,aAAa,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAC5F,wBAAgB,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,KAAK,CAAC,OAAO,SAAS,aAAa,EACnF,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,GACzC,aAAa,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,CAAA;AAK1C;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAA;AA+DzF;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,CAuC1D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,QAAQ,EAAE,EAAE,OAAO,EAAE,QAAQ,GAAG,eAAe,CAiCjH;AA6ED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAUzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAa/G"}

package/dist/api/dto.js

@@ -0,0 +1,295 @@
+import "../functions/install.js";
+import { mergeEnvKeys, normalizeEnvKeys } from "../engine/context.js";
+import { FhirPathTypeError } from "../errors.js";
+import { functions as builtinFunctions } from "../functions/registry.js";
+import { canonicalFocusType, typesOverlap } from "../values/type-compat.js";
+import { toSubjects } from "./bundle.js";
+import { columnSignature, criteriaSignature } from "./column-signature.js";
+/** The `fhirType`/`vars` a `defineDto()` base was created with, by that base class. */
+const bases = new WeakMap();
+/**
+ * Columns by the class that declared them. A field decorator runs before its
+ * class exists, so it records through the initializer it returns, where `this`
+ * is the instance being built and `this.constructor` the class — `dtoDefinition`
+ * instantiates each DTO once to collect them.
+ */
+const declaredColumns = new WeakMap();
+/** Definitions already collected, keyed by the DTO class. */
+const definitions = new WeakMap();
+/** The DTO class whose field initializers may record columns during definition collection. */
+let collecting;
+/**
+ * Creates a DTO base for one FHIR resource or datatype. The type becomes the
+ * context for relative column paths. Subclasses may add decorated fields,
+ * getters, methods, and shared base columns.
+ */
+export function defineDto(fhirType, options = {}) {
+    const base = class {
+        /** On the prototype, so it stays out of a projected row's own keys. */
+        get fhirType() {
+            return fhirType;
+        }
+    };
+    // A readable name for project()/registration errors; a subclass replaces it.
+    Object.defineProperty(base, 'name', { value: `${fhirType}Dto` });
+    Object.defineProperty(base, 'fhirType', { value: fhirType, enumerable: true });
+    bases.set(base, { fhirType, ...options });
+    return base;
+}
+/** Records one column against the class being collected, and does nothing at any other time. */
+function recordColumn(instance, name, spec) {
+    const cls = instance.constructor;
+    if (cls !== collecting) {
+        return;
+    }
+    const own = declaredColumns.get(cls) ?? {};
+    own[name] = spec;
+    declaredColumns.set(cls, own);
+}
+/** The decorator both `column()` and `criteria()` return: record on construction, leave the field empty. */
+function fieldDecorator(spec) {
+    return (_target, context) => {
+        if (context.static || context.private) {
+            throw new FhirPathTypeError(`Column '${String(context.name)}' must be a public instance field`);
+        }
+        const name = String(context.name);
+        return function () {
+            recordColumn(this, name, spec);
+            return undefined;
+        };
+    };
+}
+export function column(path, options) {
+    return fieldDecorator({ path, ...options });
+}
+export function criteria(expr) {
+    return fieldDecorator({ test: expr });
+}
+/** A class and the classes it extends, most derived first. */
+function* classChain(cls) {
+    for (let current = cls; typeof current === 'function'; current = Object.getPrototypeOf(current)) {
+        yield current;
+    }
+}
+/** The `defineDto()` base a class descends from, with the fhirType/vars it fixed. */
+function baseOf(cls) {
+    for (const current of classChain(cls)) {
+        const base = bases.get(current);
+        if (base !== undefined) {
+            return base;
+        }
+    }
+    return undefined;
+}
+/**
+ * Merges each class's own `static env`, from the base to the most derived class.
+ * A getter is read once while the definition is collected. An empty result has
+ * no environment overlay.
+ */
+function declaredEnv(cls) {
+    const declared = [];
+    for (const current of classChain(cls)) {
+        const own = staticEnv(current);
+        if (own !== undefined) {
+            declared.unshift(own);
+        }
+    }
+    const merged = Object.assign({}, ...declared.map(normalizeEnvKeys));
+    return Object.keys(merged).length === 0 ? undefined : merged;
+}
+/**
+ * One class's own `static env`, as a field or a getter, checked for the shape
+ * the engine can bind. Names the class that declared it, which is the one to
+ * edit even when the projected DTO is several subclasses below.
+ */
+function staticEnv(cls) {
+    const declared = Object.getOwnPropertyDescriptor(cls, 'env');
+    if (declared === undefined) {
+        return undefined;
+    }
+    const own = declared.get === undefined ? declared.value : declared.get.call(cls);
+    if (own === undefined) {
+        return undefined;
+    }
+    if (typeof own !== 'object' || own === null || Array.isArray(own)) {
+        throw new FhirPathTypeError(`DTO ${cls.name} declares a static 'env' that is not a record of variables; ` +
+            'write it as { name: value }, the same shape as EvaluateOptions.env');
+    }
+    return own;
+}
+/**
+ * Whether a value is a DTO class — one `defineDto()` produced, or a subclass of
+ * one. Lets tooling pick the DTOs out of a module's exports (see the
+ * `fhirpath-check` CLI) without instantiating anything that is not one.
+ */
+export function isDtoClass(value) {
+    return typeof value === 'function' && baseOf(value) !== undefined;
+}
+/** Collects and caches a DTO's type, columns, environment, variables, and caller environment names. */
+export function dtoDefinition(cls) {
+    const cached = definitions.get(cls);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const base = baseOf(cls);
+    if (base === undefined) {
+        throw new FhirPathTypeError(`${cls.name || 'The class'} is not a DTO class; extend defineDto('<fhirType>') to declare one`);
+    }
+    // A field initializer may collect another DTO. Restore the outer class so its
+    // remaining fields are still recorded.
+    const outer = collecting;
+    collecting = cls;
+    try {
+        new cls();
+    }
+    finally {
+        collecting = outer;
+    }
+    // Copied, so the definition cannot be reached through the collection map.
+    const columns = { ...declaredColumns.get(cls) };
+    if (Object.keys(columns).length === 0) {
+        throw new FhirPathTypeError(`DTO ${cls.name} declares no columns; add a @column field`);
+    }
+    /* v8 ignore start -- TypeScript rejects a field that shadows the base's fhirType; this only fires for an untyped host (the demo playground runs transpile-only code) */
+    if ('fhirType' in columns) {
+        throw new FhirPathTypeError(`DTO ${cls.name} declares a column named 'fhirType', which every row already carries`);
+    }
+    /* v8 ignore stop */
+    const definition = {
+        fhirType: base.fhirType,
+        columns,
+        env: declaredEnv(cls),
+        vars: base.vars,
+        callerEnv: base.callerEnv,
+    };
+    definitions.set(cls, definition);
+    return definition;
+}
+/**
+ * Adds DTO columns to the engine's function table. Each function keeps its DTO
+ * input type and environment. Same-name functions become overloads when their
+ * input types do not overlap.
+ */
+export function withDtos(defaults, dtos, compile) {
+    if (dtos.length === 0) {
+        return defaults;
+    }
+    const { model } = defaults;
+    if (model === undefined) {
+        // The model selects a column from the call focus and separates same-name columns.
+        throw new FhirPathTypeError(`Registering DTOs (${dtos.map(dto => dto.name).join(', ')}) needs a model; ` +
+            'a column is written for one type, and without a model the engine cannot check a call against it. ' +
+            'Pass model to the engine, or project the DTO without registering it.');
+    }
+    const functions = { ...defaults.functions };
+    for (const dto of dtos) {
+        const definition = dtoDefinition(dto);
+        for (const [name, spec] of Object.entries(definition.columns)) {
+            // Without this, createContext fails later and names the function rather
+            // than the field that caused it.
+            if (builtinFunctions.has(name)) {
+                throw new FhirPathTypeError(`DTO ${dto.name} declares a column named '${name}', which is a built-in function; rename the field`);
+            }
+            functions[name] = declaredWith(functions[name], columnFunction(spec, compile, definition), model, () => `DTO ${dto.name} redefines the function '${name}'`);
+        }
+    }
+    return { ...defaults, functions };
+}
+/** Adds a column declaration when its focus type distinguishes it from every existing declaration. */
+function declaredWith(existing, column, model, blamed) {
+    if (existing === undefined) {
+        return column;
+    }
+    const declared = 'overloads' in existing ? existing.overloads : [existing];
+    for (const other of declared) {
+        const reason = indistinguishable(model, other, column);
+        if (reason !== undefined) {
+            throw new FhirPathTypeError(`${blamed()}: ${reason}`);
+        }
+    }
+    return { overloads: [...declared, column] };
+}
+/**
+ * Explains why focus-only dispatch cannot separate two declarations. Each side
+ * must declare input types, and those types must not overlap.
+ */
+function indistinguishable(model, a, b) {
+    const wanted = canonicalTypes(model, a.signature?.input?.types);
+    const claimed = canonicalTypes(model, b.signature?.input?.types);
+    if (wanted === undefined || claimed === undefined) {
+        return 'a declaration that names no input type answers every call, so nothing else may share its name';
+    }
+    const overlap = wanted.flatMap(one => claimed.filter(other => typesOverlap(model, one, other)).map(other => [one, other]));
+    const pair = overlap[0];
+    if (pair === undefined) {
+        return undefined;
+    }
+    // Equal types make the field name ambiguous, even though the type itself is clear.
+    return pair[0] === pair[1] ? `both are written for ${pair[0]}` : `a focus can be both ${pair[0]} and ${pair[1]}`;
+}
+/** Declared input types as the model names them, or undefined when the name declares none the model knows. */
+function canonicalTypes(model, types) {
+    if (types === undefined) {
+        return undefined;
+    }
+    const canonical = types
+        .map(type => canonicalFocusType(model, type))
+        .filter((type) => type !== undefined);
+    return canonical.length === 0 ? undefined : canonical;
+}
+/**
+ * Converts a DTO column into a typed expression function with the DTO's local
+ * environment. Criteria functions also carry the criteria Boolean rule. DTO
+ * variables remain projection-only because function calls have no row.
+ */
+function columnFunction(spec, compile, dto) {
+    const { fhirType, env } = dto;
+    if ('test' in spec) {
+        return {
+            expression: compile(spec.test),
+            criteria: true,
+            signature: criteriaSignature(fhirType),
+            ...(env !== undefined && { env }),
+        };
+    }
+    const signature = columnSignature(spec, fhirType);
+    return {
+        expression: compile(spec.path),
+        ...(signature !== undefined && { signature }),
+        ...(env !== undefined && { env }),
+    };
+}
+/**
+ * Checks each resource against the DTO type before projection. Without this
+ * check, a wrong resource could produce a typed row filled with defaults.
+ * Datatype inputs have no `resourceType` to check.
+ */
+export function assertInputMatchesDto(input, dto) {
+    const { fhirType } = dtoDefinition(dto);
+    toSubjects(input).forEach((subject, index) => {
+        const resourceType = subject.value?.resourceType;
+        if (typeof resourceType === 'string' && resourceType !== fhirType) {
+            throw new FhirPathTypeError(`project(): row ${index} is a ${resourceType}, but ${dto.name} declares fhirType '${fhirType}'`);
+        }
+    });
+}
+/**
+ * Merges DTO options with call options. DTO environment values win so projected
+ * and registered columns read the same value. Call variables win because they
+ * may replace a DTO's row binding.
+ */
+export function dtoCallOptions(dto, options) {
+    const { env, vars } = dtoDefinition(dto);
+    if (env === undefined && vars === undefined) {
+        return options;
+    }
+    const merged = { ...options };
+    if (env !== undefined) {
+        merged.env = mergeEnvKeys(options?.env, env);
+    }
+    if (vars !== undefined) {
+        merged.vars = mergeEnvKeys(vars, options?.vars);
+    }
+    return merged;
+}
+//# sourceMappingURL=dto.js.map

package/dist/api/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../../src/api/dto.ts"],"names":[],"mappings":"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"}

package/dist/api/engine.d.ts

@@ -0,0 +1,136 @@
+import type { R4TypeOf } from '../r4/generated/type-maps.ts';
+import type { FhirpathInput, FhirpathResult } from '../typed/infer.ts';
+import type { TypedValue } from '../values/typed-value.ts';
+import { type BundleLike } from './bundle.ts';
+import { type AnyExpression, CompiledExpression, type EvaluateOptions } from './compile.ts';
+import { type ConstraintCheckResult, type FhirConstraint } from './constraints.ts';
+import { type DtoClass } from './dto.ts';
+import { type Projection, type ProjectionColumns } 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;
+};
+/**
+ * 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 declare function recordEngines(): () => readonly FhirPathEngine[];
+/**
+ * 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 declare 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;
+    constructor({ cacheSize, resourceDtos, ...defaults }?: EngineOptions);
+    /** 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>;
+    /** Like `evaluate()`, keeping the internal typed representation (types, Decimal, Temporal). */
+    evaluateTyped(expression: AnyExpression, input?: unknown, options?: EvaluateOptions): TypedValue[];
+    /** 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>;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Replaces scalar defaults and merges `env`, `vars`, and `functions` by name.
+     * Per-call entries win. Environment keys are normalized with or without `%`.
+     */
+    private 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;
+    /** One entry of `functions`, with any string body parsed — reaching into an overload set for each member. */
+    private precompiledFunction;
+    private precompiledBody;
+}
+/** A compiled expression carrying an engine's defaults, so `evaluate(input)` needs nothing else. */
+export declare class BoundExpression<Expr extends string = string> {
+    readonly expression: CompiledExpression<Expr>;
+    private readonly engine;
+    constructor(engine: FhirPathEngine, expression: CompiledExpression<Expr>);
+    get source(): string;
+    evaluate<T extends keyof R4TypeOf>(input: EngineInput<Expr> | undefined, options: TypedEvaluateOptions<T>): R4TypeOf[T][];
+    evaluate(input?: EngineInput<Expr>, options?: EvaluateOptions): FhirpathResult<Expr>;
+    evaluateTyped(input?: unknown, options?: EvaluateOptions): TypedValue[];
+    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;
+    test(input: unknown, options?: EvaluateOptions): boolean;
+    /** The canonical form of the expression. */
+    toString(): string;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/api/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/api/engine.ts"],"names":[],"mappings":"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"}