@atomic-ehr/fhirpath 0.0.1 → 0.0.2-canary.2fee5d9.20250808110507

package/README.md

@@ -1,5 +1,7 @@
 # @atomic-ehr/fhirpath
 
+[![npm version](https://badge.fury.io/js/@atomic-ehr%2Ffhirpath.svg)](https://www.npmjs.com/package/@atomic-ehr/fhirpath)
+
 A TypeScript implementation of FHIRPath, the path-based navigation and extraction language for FHIR (Fast Healthcare Interoperability Resources).
 
 ## Installation

package/dist/index.d.ts

@@ -1,5 +1,37 @@
 import { FHIRSchema } from '@atomic-ehr/fhirschema';
 
+/**
+ * Symbol to mark boxed values
+ */
+declare const BOXED_SYMBOL: unique symbol;
+/**
+ * Extension structure for FHIR primitive elements
+ */
+interface Extension {
+    url: string;
+    [key: string]: any;
+}
+/**
+ * Metadata for FHIR primitive elements (e.g., _gender for gender property)
+ */
+interface PrimitiveElement {
+    id?: string;
+    extension?: Extension[];
+}
+/**
+ * Boxed FHIRPath value with metadata
+ */
+interface FHIRPathValue<T = any> {
+    /** The actual value */
+    value: T;
+    /** Type information from ModelProvider */
+    typeInfo?: TypeInfo;
+    /** Primitive element extension (for primitives only) */
+    primitiveElement?: PrimitiveElement;
+    /** Internal marker to identify boxed values */
+    [BOXED_SYMBOL]: true;
+}
+
 /**
  * Simplified FHIRPath Lexer
  *
@@ -139,6 +171,7 @@ interface ModelProvider<TypeContext = unknown> {
     getElementType(parentType: TypeInfo<TypeContext>, propertyName: string): TypeInfo<TypeContext> | undefined;
     ofType(type: TypeInfo<TypeContext>, typeName: TypeName): TypeInfo<TypeContext> | undefined;
     getElementNames(parentType: TypeInfo<TypeContext>): string[];
+    getChildrenType(parentType: TypeInfo<TypeContext>): TypeInfo<TypeContext> | undefined;
 }
 interface OperatorSignature {
     name: string;
@@ -301,9 +334,11 @@ interface RuntimeContext {
     input: any[];
     focus: any[];
     variables: Record<string, any>;
+    currentNode?: ASTNode;
+    modelProvider?: ModelProvider;
 }
 interface EvaluationResult {
-    value: any[];
+    value: FHIRPathValue[];
     context: RuntimeContext;
 }
 declare enum DiagnosticSeverity {
@@ -346,51 +381,8 @@ interface ParseResult {
         availableCompletions: string[];
     };
 }
-type OperationEvaluator = (input: any[], context: RuntimeContext, ...args: any[]) => EvaluationResult;
-type FunctionEvaluator = (input: any[], context: RuntimeContext, args: ASTNode[], evaluator: (node: ASTNode, input: any[], context: RuntimeContext) => EvaluationResult) => EvaluationResult;
-
-/**
- * Abstract base parser with shared parsing logic
- * Subclasses must implement node creation and error handling
- */
-declare abstract class BaseParser<TNode extends BaseASTNode = BaseASTNode> {
-    protected lexer: Lexer;
-    protected tokens: Token[];
-    protected current: number;
-    constructor(input: string, lexerOptions?: LexerOptions);
-    protected abstract createIdentifierNode(name: string, token: Token): TNode;
-    protected abstract createLiteralNode(value: any, valueType: 'string' | 'number' | 'boolean' | 'date' | 'time' | 'datetime' | 'null', token: Token): TNode;
-    protected abstract createBinaryNode(token: Token, left: TNode, right: TNode): TNode;
-    protected abstract createUnaryNode(token: Token, operand: TNode): TNode;
-    protected abstract createFunctionNode(name: TNode, args: TNode[], startToken: Token): TNode;
-    protected abstract createVariableNode(name: string, token: Token): TNode;
-    protected abstract createIndexNode(expression: TNode, index: TNode, startToken: Token): TNode;
-    protected abstract createMembershipTestNode(expression: TNode, targetType: string, startToken: Token): TNode;
-    protected abstract createTypeCastNode(expression: TNode, targetType: string, startToken: Token): TNode;
-    protected abstract createCollectionNode(elements: TNode[], startToken: Token): TNode;
-    protected abstract createQuantityNode(value: number, unit: string, isCalendarUnit: boolean, startToken: Token, endToken: Token): TNode;
-    protected abstract handleError(message: string, token?: Token): never | TNode;
-    protected expression(): TNode;
-    protected parseExpressionWithPrecedence(minPrecedence: number): TNode;
-    protected parsePrimary(): TNode;
-    protected parseInvocation(): TNode;
-    protected parseArgumentList(): TNode[];
-    protected parseCollectionElements(): TNode[];
-    protected parseTypeName(): string;
-    protected parseStringValue(raw: string): string;
-    protected parseIdentifierValue(raw: string): string;
-    protected isFunctionCall(node: TNode): boolean;
-    protected isBinaryOperatorToken(token: Token): boolean;
-    protected isKeywordAllowedAsMember(token: Token): boolean;
-    protected isKeywordAllowedAsIdentifier(token: Token): boolean;
-    protected peek(): Token;
-    protected previous(): Token;
-    protected isAtEnd(): boolean;
-    protected advance(): Token;
-    protected check(type: TokenType): boolean;
-    protected match(...types: TokenType[]): boolean;
-    protected consume(type: TokenType, message: string): Token;
-}
+type OperationEvaluator = (input: FHIRPathValue[], context: RuntimeContext, ...args: any[]) => EvaluationResult;
+type FunctionEvaluator = (input: FHIRPathValue[], context: RuntimeContext, args: ASTNode[], evaluator: (node: ASTNode, input: FHIRPathValue[], context: RuntimeContext) => EvaluationResult) => EvaluationResult;
 
 interface ParserOptions {
     mode?: 'simple' | 'lsp';
@@ -401,7 +393,10 @@ interface ParserOptions {
         cursorPosition: number;
     };
 }
-declare class Parser extends BaseParser<ASTNode> {
+declare class Parser {
+    protected lexer: Lexer;
+    protected tokens: Token[];
+    protected current: number;
     private mode;
     private options;
     private errors?;
@@ -419,6 +414,26 @@ declare class Parser extends BaseParser<ASTNode> {
     parse(): ParseResult;
     private parseSimple;
     private parseLSP;
+    protected expression(): ASTNode;
+    protected parseExpressionWithPrecedence(minPrecedence: number): ASTNode;
+    protected parsePrimary(): ASTNode;
+    protected parseInvocation(): ASTNode;
+    protected parseArgumentList(): ASTNode[];
+    protected parseCollectionElements(): ASTNode[];
+    protected parseTypeName(): string;
+    protected parseStringValue(raw: string): string;
+    protected parseIdentifierValue(raw: string): string;
+    protected isFunctionCall(node: ASTNode): boolean;
+    protected isBinaryOperatorToken(token: Token): boolean;
+    protected isKeywordAllowedAsMember(token: Token): boolean;
+    protected isKeywordAllowedAsIdentifier(token: Token): boolean;
+    protected peek(): Token;
+    protected previous(): Token;
+    protected isAtEnd(): boolean;
+    protected advance(): Token;
+    protected check(type: TokenType): boolean;
+    protected match(...types: TokenType[]): boolean;
+    protected consume(type: TokenType, message: string): Token;
     protected createIdentifierNode(name: string, token: Token): ASTNode;
     protected createLiteralNode(value: any, valueType: LiteralNode['valueType'], token: Token): LiteralNode;
     protected createBinaryNode(token: Token, left: ASTNode, right: ASTNode): BinaryNode;
@@ -473,7 +488,8 @@ declare class Interpreter {
     private nodeEvaluators;
     private operationEvaluators;
     private functionEvaluators;
-    constructor(registry?: Registry);
+    private modelProvider?;
+    constructor(registry?: Registry, modelProvider?: ModelProvider<any>);
     private registerOperationEvaluators;
     evaluate(node: ASTNode, input?: any[], context?: RuntimeContext): EvaluationResult;
     private createInitialContext;
@@ -496,14 +512,18 @@ declare class Analyzer {
     private variables;
     private modelProvider?;
     private userVariableTypes;
+    private systemVariableTypes;
     constructor(modelProvider?: ModelProvider);
     analyze(ast: ASTNode, userVariables?: Record<string, any>, inputType?: TypeInfo): AnalysisResult;
     private visitNode;
     private visitBinaryOperator;
     private visitIdentifier;
     private visitFunctionCall;
+    private visitMembershipTest;
+    private visitTypeCast;
     private validateVariable;
-    private addDiagnostic;
+    private collectDefinedVariables;
+    private collectDefinedVariablesWithTypes;
     private inferType;
     private inferErrorNodeType;
     private inferLiteralType;
@@ -567,7 +587,7 @@ declare class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     private initialized;
     private readonly typeMapping;
     private readonly commonTypes;
-    constructor(config: FHIRModelProviderConfig);
+    constructor(config?: FHIRModelProviderConfig);
     initialize(): Promise<void>;
     private buildCanonicalUrl;
     private loadSchemaAsync;
@@ -581,45 +601,143 @@ declare class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     getElementType(parentType: TypeInfo<FHIRModelContext>, propertyName: string): TypeInfo<FHIRModelContext> | undefined;
     ofType(type: TypeInfo<FHIRModelContext>, typeName: TypeName): TypeInfo<FHIRModelContext> | undefined;
     getElementNames(parentType: TypeInfo<FHIRModelContext>): string[];
+    getChildrenType(parentType: TypeInfo<FHIRModelContext>): TypeInfo<FHIRModelContext> | undefined;
     loadType(typeName: string): Promise<TypeInfo<FHIRModelContext> | undefined>;
 }
 
-interface TraceEntry {
-    name: string;
-    values: any[];
+interface ASTMetadata {
+    complexity: number;
     depth: number;
-    timestamp: number;
-    projection?: any[];
-}
-interface InspectOptions {
-    input?: unknown;
-    variables?: Record<string, unknown>;
-    maxTraces?: number;
+    operationCount: Map<string, number>;
 }
 interface InspectResult {
-    expression: string;
-    result: any[];
-    ast: ASTNode;
-    traces: TraceEntry[];
-    executionTime: number;
-    errors?: Array<{
-        type: string;
-        message: string;
-        location?: {
-            line: number;
-            column: number;
-        };
-    }>;
-    warnings?: Array<{
-        code: string;
-        message: string;
+    result: FHIRPathValue[];
+    ast: {
+        node: ASTNode;
+        metadata: ASTMetadata;
+    };
+    diagnostics: {
+        warnings: Diagnostic[];
+        hints: Array<{
+            message: string;
+            suggestion?: string;
+        }>;
+    };
+    performance: {
+        parseTime: number;
+        analyzeTime: number;
+        evalTime: number;
+        totalTime: number;
+        operationTimings: Map<string, number>;
+    };
+    traces?: Array<{
+        label: string;
+        value: FHIRPathValue[];
+        timestamp: number;
     }>;
 }
+interface InspectOptions {
+    input?: any;
+    variables?: Record<string, any>;
+    includeTraces?: boolean;
+    maxDepth?: number;
+}
 declare function inspect(expression: string, options?: InspectOptions): InspectResult;
 
+/**
+ * Base error class for all FHIRPath errors
+ */
+declare class FHIRPathError extends Error {
+    code: string;
+    location?: Range | undefined;
+    constructor(code: string, message: string, location?: Range | undefined);
+}
+/**
+ * Error factory with specialized constructors
+ */
+declare const Errors: {
+    unknownOperator(operator: string, location?: Range): FHIRPathError;
+    unknownFunction(name: string, location?: Range): FHIRPathError;
+    unknownVariable(name: string, location?: Range): FHIRPathError;
+    unknownUserVariable(name: string, location?: Range): FHIRPathError;
+    unknownProperty(property: string, type: string, location?: Range): FHIRPathError;
+    unknownNodeType(nodeType: string, location?: Range): FHIRPathError;
+    noEvaluatorFound(evaluatorType: string, name: string, location?: Range): FHIRPathError;
+    variableNotDefined(name: string, location?: Range): FHIRPathError;
+    wrongArgumentCount(funcName: string, expected: number, actual: number, location?: Range): FHIRPathError;
+    wrongArgumentCountRange(funcName: string, min: number, max: number, actual: number, location?: Range): FHIRPathError;
+    singletonRequired(funcName: string, actualCount: number, location?: Range): FHIRPathError;
+    stringSingletonRequired(funcName: string, actualCount: number, location?: Range): FHIRPathError;
+    emptyNotAllowed(funcName: string, location?: Range): FHIRPathError;
+    argumentRequired(funcName: string, argumentName: string, location?: Range): FHIRPathError;
+    typeNotAssignable(sourceType: string, targetType: string, location?: Range): FHIRPathError;
+    operatorTypeMismatch(operator: string, leftType: string, rightType: string, location?: Range): FHIRPathError;
+    argumentTypeMismatch(argIndex: number, funcName: string, expected: string, actual: string, location?: Range): FHIRPathError;
+    conversionFailed(value: string, targetType: string, location?: Range): FHIRPathError;
+    invalidValueType(expected: string, actual: string, location?: Range): FHIRPathError;
+    invalidOperandType(operation: string, type: string, location?: Range): FHIRPathError;
+    stringOperationOnNonString(operation: string, location?: Range): FHIRPathError;
+    numericOperationOnNonNumeric(operation: string, location?: Range): FHIRPathError;
+    booleanOperationOnNonBoolean(operation: string, index: number, actualType: string, location?: Range): FHIRPathError;
+    modelProviderRequired(operation: string, location?: Range): FHIRPathError;
+    unexpectedToken(token: string, location?: Range): FHIRPathError;
+    expectedToken(expected: string, actual: string, location?: Range): FHIRPathError;
+    invalidSyntax(details: string, location?: Range): FHIRPathError;
+    expectedIdentifier(after: string, actual: string, location?: Range): FHIRPathError;
+    expectedTypeName(actual: string, location?: Range): FHIRPathError;
+    divisionByZero(location?: Range): FHIRPathError;
+    invalidDateTimeFormat(format: string, location?: Range): FHIRPathError;
+    incompatibleUnits(unit1: string, unit2: string, location?: Range): FHIRPathError;
+    indexOutOfBounds(index: number, size: number, location?: Range): FHIRPathError;
+    invalidOperation(details: string, location?: Range): FHIRPathError;
+    invalidPrecision(operation: string, location?: Range): FHIRPathError;
+    invalidStringOperation(operation: string, paramName: string, location?: Range): FHIRPathError;
+    invalidNumericOperation(operation: string, paramName: string, expectedType: string, location?: Range): FHIRPathError;
+};
+declare enum ErrorCodes {
+    UNKNOWN_OPERATOR = "FP1001",
+    UNKNOWN_FUNCTION = "FP1002",
+    UNKNOWN_VARIABLE = "FP1003",
+    UNKNOWN_USER_VARIABLE = "FP1004",
+    UNKNOWN_PROPERTY = "FP1005",
+    UNKNOWN_NODE_TYPE = "FP1006",
+    NO_EVALUATOR_FOUND = "FP1007",
+    VARIABLE_NOT_DEFINED = "FP1008",
+    WRONG_ARGUMENT_COUNT = "FP2001",
+    WRONG_ARGUMENT_COUNT_RANGE = "FP2002",
+    SINGLETON_REQUIRED = "FP2003",
+    EMPTY_NOT_ALLOWED = "FP2004",
+    ARGUMENT_REQUIRED = "FP2005",
+    TYPE_NOT_ASSIGNABLE = "FP3001",
+    OPERATOR_TYPE_MISMATCH = "FP3002",
+    ARGUMENT_TYPE_MISMATCH = "FP3003",
+    CONVERSION_FAILED = "FP3004",
+    INVALID_VALUE_TYPE = "FP3005",
+    INVALID_OPERAND_TYPE = "FP3006",
+    STRING_OPERATION_ON_NON_STRING = "FP3007",
+    NUMERIC_OPERATION_ON_NON_NUMERIC = "FP3008",
+    BOOLEAN_OPERATION_ON_NON_BOOLEAN = "FP3009",
+    MODEL_PROVIDER_REQUIRED = "FP4001",
+    UNEXPECTED_TOKEN = "FP5001",
+    EXPECTED_TOKEN = "FP5002",
+    INVALID_SYNTAX = "FP5003",
+    EXPECTED_IDENTIFIER = "FP5004",
+    EXPECTED_TYPE_NAME = "FP5005",
+    DIVISION_BY_ZERO = "FP6001",
+    INVALID_DATE_TIME_FORMAT = "FP6002",
+    INCOMPATIBLE_UNITS = "FP6003",
+    INDEX_OUT_OF_BOUNDS = "FP6004",
+    INVALID_OPERATION = "FP6005",
+    INVALID_PRECISION = "FP6006",
+    INVALID_STRING_OPERATION = "FP6007",
+    INVALID_NUMERIC_OPERATION = "FP6008"
+}
+
 interface EvaluateOptions {
     input?: unknown;
     variables?: Record<string, unknown>;
+    modelProvider?: ModelProvider;
+    inputType?: TypeInfo;
 }
 declare function evaluate(expression: string, options?: EvaluateOptions): any[];
 declare function analyze(expression: string, options?: {
@@ -629,4 +747,4 @@ declare function analyze(expression: string, options?: {
     errorRecovery?: boolean;
 }): AnalysisResult;
 
-export { type ASTNode, type AnalysisResult, Analyzer, type Diagnostic, DiagnosticSeverity, type EvaluateOptions, type FHIRModelContext, FHIRModelProvider, type FHIRModelProviderConfig, type FunctionDefinition, type InspectOptions, type InspectResult, Interpreter, type ModelProvider as ModelTypeProvider, type OperatorDefinition, type ParseResult, Parser, Registry, type TraceEntry, type TypeInfo, type TypeName, analyze, evaluate, inspect, parse, registry };
+export { type ASTMetadata, type ASTNode, type AnalysisResult, Analyzer, type Diagnostic, DiagnosticSeverity, ErrorCodes, Errors, type EvaluateOptions, type FHIRModelContext, FHIRModelProvider, type FHIRModelProviderConfig, FHIRPathError, type FunctionDefinition, type InspectOptions, type InspectResult, Interpreter, type ModelProvider as ModelTypeProvider, type OperatorDefinition, type ParseResult, Parser, Registry, type TypeInfo, type TypeName, analyze, evaluate, inspect, parse, registry };