@fhir-dsl/fhirpath 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,542 @@
+import { Quantity, CodeableConcept, Coding, HumanName, Identifier, Reference, Period, Range, Ratio, Resource } from '@fhir-dsl/types';
+
+/** Strip array wrapper and undefined/null to get the element type */
+type Unwrap<T> = NonNullable<T extends readonly (infer U)[] ? U : T>;
+/** True when the unwrapped type is a JS primitive (terminal — no further navigation) */
+type IsPrimitive<T> = Unwrap<T> extends string | number | boolean ? true : false;
+/** String keys available for navigation on the unwrapped type */
+type NavKeys<T> = string & keyof Unwrap<T>;
+interface FhirTypeMap {
+    Quantity: Quantity;
+    CodeableConcept: CodeableConcept;
+    Coding: Coding;
+    HumanName: HumanName;
+    Identifier: Identifier;
+    Reference: Reference;
+    Period: Period;
+    Range: Range;
+    Ratio: Ratio;
+    string: string;
+    String: string;
+    boolean: boolean;
+    Boolean: boolean;
+    integer: number;
+    Integer: number;
+    decimal: number;
+    Decimal: number;
+}
+/**
+ * A predicate expression node used inside where(), select(), all(), etc.
+ * Supports navigation, comparison operators, and boolean logic.
+ */
+type FhirPathPredicate<T> = PredicateOps<T> & (IsPrimitive<T> extends true ? unknown : {
+    readonly [K in NavKeys<T>]: FhirPathPredicate<Unwrap<T>[K]>;
+});
+interface PredicateOps<T> {
+    /** Equals comparison */
+    eq(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Not equals comparison */
+    neq(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Less than comparison */
+    lt(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Greater than comparison */
+    gt(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Less than or equal comparison */
+    lte(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Greater than or equal comparison */
+    gte(value: Unwrap<T> | FhirPathPredicate<Unwrap<T>>): FhirPathPredicate<boolean>;
+    /** Boolean AND */
+    and(other: FhirPathPredicate<boolean>): FhirPathPredicate<boolean>;
+    /** Boolean OR */
+    or(other: FhirPathPredicate<boolean>): FhirPathPredicate<boolean>;
+    /** Boolean XOR */
+    xor(other: FhirPathPredicate<boolean>): FhirPathPredicate<boolean>;
+    /** Boolean NOT */
+    not(): FhirPathPredicate<boolean>;
+    /** Boolean IMPLIES */
+    implies(other: FhirPathPredicate<boolean>): FhirPathPredicate<boolean>;
+    /** String contains */
+    contains(substring: string): FhirPathPredicate<boolean>;
+    /** String starts with */
+    startsWith(prefix: string): FhirPathPredicate<boolean>;
+    /** String ends with */
+    endsWith(suffix: string): FhirPathPredicate<boolean>;
+    /** Regex match */
+    matches(regex: string): FhirPathPredicate<boolean>;
+    /** Existence check */
+    exists(): FhirPathPredicate<boolean>;
+    /** Empty check */
+    empty(): FhirPathPredicate<boolean>;
+    /** Count */
+    count(): FhirPathPredicate<number>;
+    /** Type check */
+    is(typeName: string): FhirPathPredicate<boolean>;
+    /** Type cast */
+    as(typeName: string): FhirPathPredicate<T>;
+}
+interface FhirPathCoreOps<T> {
+    /** Return the compiled FHIRPath expression string */
+    compile(): string;
+    /** Evaluate the expression against a resource, returning a collection */
+    evaluate(resource: unknown): Unwrap<T>[];
+}
+interface FhirPathExistenceOps<T> {
+    /** Filter by field equality (legacy shorthand) */
+    where<K extends NavKeys<T>>(field: K, value: string): FhirPathExpr<T>;
+    /** Filter by expression predicate */
+    where(predicate: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<boolean>): FhirPathExpr<T>;
+    /** True if collection is non-empty, or if any item matches criteria */
+    exists(): FhirPathExpr<boolean>;
+    exists(predicate: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<boolean>): FhirPathExpr<boolean>;
+    /** True if all items match criteria */
+    all(predicate: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<boolean>): FhirPathExpr<boolean>;
+    /** True if all items are true */
+    allTrue(): FhirPathExpr<boolean>;
+    /** True if any item is true */
+    anyTrue(): FhirPathExpr<boolean>;
+    /** True if all items are false */
+    allFalse(): FhirPathExpr<boolean>;
+    /** True if any item is false */
+    anyFalse(): FhirPathExpr<boolean>;
+    /** Number of elements */
+    count(): FhirPathExpr<number>;
+    /** True if collection is empty */
+    empty(): FhirPathExpr<boolean>;
+    /** Remove duplicate values */
+    distinct(): FhirPathExpr<T>;
+    /** True if all values are distinct */
+    isDistinct(): FhirPathExpr<boolean>;
+}
+interface FhirPathSubsetOps<T> {
+    /** First element */
+    first(): FhirPathExpr<Unwrap<T>>;
+    /** Last element */
+    last(): FhirPathExpr<Unwrap<T>>;
+    /** Exactly one element or error */
+    single(): FhirPathExpr<Unwrap<T>>;
+    /** All but the first element */
+    tail(): FhirPathExpr<T>;
+    /** Skip first n elements */
+    skip(count: number): FhirPathExpr<T>;
+    /** Take first n elements */
+    take(count: number): FhirPathExpr<T>;
+    /** Elements present in both collections */
+    intersect(other: FhirPathExpr<T>): FhirPathExpr<T>;
+    /** Elements not present in other collection */
+    exclude(other: FhirPathExpr<T>): FhirPathExpr<T>;
+}
+interface FhirPathProjectionOps<T> {
+    /** Project each element through expression */
+    select<R>(projection: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<R>): FhirPathExpr<R>;
+    /** Recursively project until stable */
+    repeat<R>(projection: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<R>): FhirPathExpr<R>;
+    /** Filter collection to elements of the specified type */
+    ofType<N extends keyof FhirTypeMap>(type: N): FhirPathExpr<FhirTypeMap[N]>;
+}
+interface FhirPathCombiningOps<T> {
+    /** Merge two collections (deduplicated) */
+    union(other: FhirPathExpr<T>): FhirPathExpr<T>;
+    /** Merge two collections (with duplicates) */
+    combine(other: FhirPathExpr<T>): FhirPathExpr<T>;
+}
+interface FhirPathStringOps {
+    /** Index of substring (-1 if not found) */
+    indexOf(substring: string): FhirPathExpr<number>;
+    /** Extract substring */
+    substring(start: number, length?: number): FhirPathExpr<string>;
+    /** True if string starts with prefix */
+    startsWith(prefix: string): FhirPathExpr<boolean>;
+    /** True if string ends with suffix */
+    endsWith(suffix: string): FhirPathExpr<boolean>;
+    /** True if string contains substring */
+    contains(substring: string): FhirPathExpr<boolean>;
+    /** Convert to uppercase */
+    upper(): FhirPathExpr<string>;
+    /** Convert to lowercase */
+    lower(): FhirPathExpr<string>;
+    /** Replace occurrences of pattern */
+    replace(pattern: string, substitution: string): FhirPathExpr<string>;
+    /** True if string matches regex */
+    matches(regex: string): FhirPathExpr<boolean>;
+    /** Replace regex matches */
+    replaceMatches(regex: string, substitution: string): FhirPathExpr<string>;
+    /** String length */
+    length(): FhirPathExpr<number>;
+    /** Split string into characters */
+    toChars(): FhirPathExpr<string>;
+}
+interface FhirPathMathOps {
+    /** Absolute value */
+    abs(): FhirPathExpr<number>;
+    /** Round up to integer */
+    ceiling(): FhirPathExpr<number>;
+    /** e^x */
+    exp(): FhirPathExpr<number>;
+    /** Round down to integer */
+    floor(): FhirPathExpr<number>;
+    /** Natural logarithm */
+    ln(): FhirPathExpr<number>;
+    /** Logarithm with base */
+    log(base: number): FhirPathExpr<number>;
+    /** Raise to power */
+    power(exponent: number): FhirPathExpr<number>;
+    /** Round to precision */
+    round(precision?: number): FhirPathExpr<number>;
+    /** Square root */
+    sqrt(): FhirPathExpr<number>;
+    /** Truncate to integer */
+    truncate(): FhirPathExpr<number>;
+}
+interface FhirPathConversionOps {
+    /** Convert to boolean */
+    toBoolean(): FhirPathExpr<boolean>;
+    /** Convert to integer */
+    toInteger(): FhirPathExpr<number>;
+    /** Convert to decimal */
+    toDecimal(): FhirPathExpr<number>;
+    /** Convert to string (FHIRPath toString) */
+    toFhirString(): FhirPathExpr<string>;
+    /** Convert to date */
+    toDate(): FhirPathExpr<string>;
+    /** Convert to dateTime */
+    toDateTime(): FhirPathExpr<string>;
+    /** Convert to time */
+    toTime(): FhirPathExpr<string>;
+    /** Convert to Quantity */
+    toQuantity(unit?: string): FhirPathExpr<Quantity>;
+    /** Can convert to boolean? */
+    convertsToBoolean(): FhirPathExpr<boolean>;
+    /** Can convert to integer? */
+    convertsToInteger(): FhirPathExpr<boolean>;
+    /** Can convert to decimal? */
+    convertsToDecimal(): FhirPathExpr<boolean>;
+    /** Can convert to string? */
+    convertsToString(): FhirPathExpr<boolean>;
+    /** Can convert to date? */
+    convertsToDate(): FhirPathExpr<boolean>;
+    /** Can convert to dateTime? */
+    convertsToDateTime(): FhirPathExpr<boolean>;
+    /** Can convert to time? */
+    convertsToTime(): FhirPathExpr<boolean>;
+    /** Can convert to Quantity? */
+    convertsToQuantity(): FhirPathExpr<boolean>;
+}
+interface FhirPathUtilityOps<T> {
+    /** Debug trace (returns input unchanged) */
+    trace(name: string): FhirPathExpr<T>;
+    /** Immediate children of each element */
+    children(): FhirPathExpr<unknown>;
+    /** All descendants of each element */
+    descendants(): FhirPathExpr<unknown>;
+    /** Conditional: if criterion then trueResult else otherwiseResult */
+    iif<R>(criterion: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<boolean>, trueResult: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<R>, otherwiseResult?: ($this: FhirPathPredicate<Unwrap<T>>) => FhirPathPredicate<R>): FhirPathExpr<R>;
+    /** Current dateTime */
+    now(): FhirPathExpr<string>;
+    /** Current time */
+    timeOfDay(): FhirPathExpr<string>;
+    /** Current date */
+    today(): FhirPathExpr<string>;
+}
+/** Composed FHIRPath operations interface */
+interface FhirPathOps<T> extends FhirPathCoreOps<T>, FhirPathExistenceOps<T>, FhirPathSubsetOps<T>, FhirPathProjectionOps<T>, FhirPathCombiningOps<T>, FhirPathStringOps, FhirPathMathOps, FhirPathConversionOps, FhirPathUtilityOps<T> {
+}
+/**
+ * A type-safe FHIRPath expression node.
+ *
+ * When `T` resolves to a complex FHIR type, every property of the unwrapped
+ * type is available as a navigable key with full autocomplete.
+ * When `T` resolves to a primitive, only collection operations remain.
+ */
+type FhirPathExpr<T> = FhirPathOps<T> & (IsPrimitive<T> extends true ? unknown : {
+    readonly [K in NavKeys<T>]: FhirPathExpr<Unwrap<T>[K]>;
+});
+/** Constraint for the `fhirpath()` entry point — accepts any FHIR Resource. */
+type FhirPathResource = Resource;
+
+/**
+ * Create a type-safe FHIRPath expression builder for a FHIR resource type.
+ *
+ * @example
+ * ```typescript
+ * import type { Patient } from "./fhir/r4";
+ *
+ * const expr = fhirpath<Patient>("Patient").name.family;
+ * expr.compile()              // "Patient.name.family"
+ * expr.evaluate(somePatient)  // ["Smith", "Doe"]
+ *
+ * // Expression predicates:
+ * fhirpath<Patient>("Patient")
+ *   .name.where($this => $this.use.eq("official")).family
+ * ```
+ */
+declare function fhirpath<T extends FhirPathResource>(resourceType: string): FhirPathExpr<T>;
+
+/**
+ * Structured representation of each FHIRPath operation step.
+ *
+ * A compiled expression is an ordered array of PathOp values.
+ * The evaluator walks them left-to-right against a resource.
+ */
+interface CompiledPredicate {
+    ops: PathOp[];
+    compiledPath: string;
+}
+type NavOp = {
+    type: "nav";
+    prop: string;
+} | {
+    type: "children";
+} | {
+    type: "descendants";
+};
+type FilterOp = {
+    type: "where";
+    predicate: CompiledPredicate;
+} | {
+    type: "where_simple";
+    field: string;
+    value: string;
+} | {
+    type: "select";
+    projection: CompiledPredicate;
+} | {
+    type: "repeat";
+    projection: CompiledPredicate;
+} | {
+    type: "ofType";
+    typeName: string;
+} | {
+    type: "exists";
+} | {
+    type: "exists_predicate";
+    predicate: CompiledPredicate;
+} | {
+    type: "all";
+    predicate: CompiledPredicate;
+} | {
+    type: "allTrue";
+} | {
+    type: "anyTrue";
+} | {
+    type: "allFalse";
+} | {
+    type: "anyFalse";
+} | {
+    type: "count";
+} | {
+    type: "empty";
+} | {
+    type: "distinct";
+} | {
+    type: "isDistinct";
+} | {
+    type: "subsetOf";
+    other: CompiledPredicate;
+} | {
+    type: "supersetOf";
+    other: CompiledPredicate;
+};
+type SubsetOp = {
+    type: "first";
+} | {
+    type: "last";
+} | {
+    type: "single";
+} | {
+    type: "tail";
+} | {
+    type: "skip";
+    num: number;
+} | {
+    type: "take";
+    num: number;
+} | {
+    type: "intersect";
+    other: CompiledPredicate;
+} | {
+    type: "exclude";
+    other: CompiledPredicate;
+};
+type CombineOp = {
+    type: "union";
+    other: CompiledPredicate;
+} | {
+    type: "combine";
+    other: CompiledPredicate;
+};
+type StringOp = {
+    type: "indexOf";
+    substring: string;
+} | {
+    type: "substring";
+    start: number;
+    length?: number;
+} | {
+    type: "startsWith";
+    prefix: string;
+} | {
+    type: "endsWith";
+    suffix: string;
+} | {
+    type: "str_contains";
+    substring: string;
+} | {
+    type: "upper";
+} | {
+    type: "lower";
+} | {
+    type: "replace";
+    pattern: string;
+    substitution: string;
+} | {
+    type: "matches";
+    regex: string;
+} | {
+    type: "replaceMatches";
+    regex: string;
+    substitution: string;
+} | {
+    type: "str_length";
+} | {
+    type: "toChars";
+};
+type MathOp = {
+    type: "abs";
+} | {
+    type: "ceiling";
+} | {
+    type: "exp";
+} | {
+    type: "floor";
+} | {
+    type: "ln";
+} | {
+    type: "log";
+    base: number;
+} | {
+    type: "power";
+    exponent: number;
+} | {
+    type: "round";
+    precision?: number;
+} | {
+    type: "sqrt";
+} | {
+    type: "truncate";
+};
+type ConversionOp = {
+    type: "toBoolean";
+} | {
+    type: "toInteger";
+} | {
+    type: "toDecimal";
+} | {
+    type: "toFhirString";
+} | {
+    type: "toDate";
+} | {
+    type: "toDateTime";
+} | {
+    type: "toTime";
+} | {
+    type: "toQuantity";
+    unit?: string;
+} | {
+    type: "convertsToBoolean";
+} | {
+    type: "convertsToInteger";
+} | {
+    type: "convertsToDecimal";
+} | {
+    type: "convertsToString";
+} | {
+    type: "convertsToDate";
+} | {
+    type: "convertsToDateTime";
+} | {
+    type: "convertsToTime";
+} | {
+    type: "convertsToQuantity";
+};
+type UtilityOp = {
+    type: "trace";
+    name: string;
+} | {
+    type: "now";
+} | {
+    type: "timeOfDay";
+} | {
+    type: "today";
+} | {
+    type: "iif";
+    criterion: CompiledPredicate;
+    trueResult: CompiledPredicate;
+    otherwiseResult?: CompiledPredicate;
+};
+type OperatorOp = {
+    type: "eq";
+    value: unknown;
+} | {
+    type: "neq";
+    value: unknown;
+} | {
+    type: "lt";
+    value: unknown;
+} | {
+    type: "gt";
+    value: unknown;
+} | {
+    type: "lte";
+    value: unknown;
+} | {
+    type: "gte";
+    value: unknown;
+} | {
+    type: "and";
+    other: CompiledPredicate;
+} | {
+    type: "or";
+    other: CompiledPredicate;
+} | {
+    type: "xor";
+    other: CompiledPredicate;
+} | {
+    type: "not";
+} | {
+    type: "implies";
+    other: CompiledPredicate;
+} | {
+    type: "is";
+    typeName: string;
+} | {
+    type: "as";
+    typeName: string;
+};
+type LiteralOp = {
+    type: "literal";
+    value: unknown;
+};
+type PathOp = NavOp | FilterOp | SubsetOp | CombineOp | StringOp | MathOp | ConversionOp | UtilityOp | OperatorOp | LiteralOp;
+
+/**
+ * Evaluate a sequence of FHIRPath operations against a resource.
+ * Returns the resulting collection.
+ */
+declare function evaluate(ops: PathOp[], resource: unknown): unknown[];
+
+/**
+ * Expression system for FHIRPath predicate callbacks.
+ *
+ * Used inside where(), select(), all(), exists(criteria), iif(), etc.
+ * The callback receives a `$this` proxy that captures navigation and
+ * comparison ops into a CompiledPredicate.
+ */
+
+/** Symbol used to extract internal ops from a predicate proxy */
+declare const PREDICATE_SYMBOL: unique symbol;
+/** Extract a CompiledPredicate from a predicate proxy result */
+declare function extractPredicate(proxy: unknown): CompiledPredicate;
+/** Create a predicate proxy representing `$this` inside expression callbacks */
+declare function createPredicateProxy(path: string, ops: PathOp[]): unknown;
+
+export { type CombineOp, type CompiledPredicate, type ConversionOp, type FhirPathExpr, type FhirPathOps, type FhirPathPredicate, type FhirPathResource, type FhirTypeMap, type FilterOp, type IsPrimitive, type LiteralOp, type MathOp, type NavKeys, type NavOp, type OperatorOp, PREDICATE_SYMBOL, type PathOp, type PredicateOps, type StringOp, type SubsetOp, type Unwrap, type UtilityOp, createPredicateProxy, evaluate, extractPredicate, fhirpath };