@atomic-ehr/fhirpath 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -53,6 +53,7 @@ declare enum TokenType {
     DATETIME = 4,
     TIME = 5,
     QUANTITY = 6,// Quantity literals like 5 'mg'
+    DATE = 7,// Date literals like @2020-01-01
     OPERATOR = 10,// +, -, *, /, <, >, <=, >=, =, !=, ~, !~, |, &
     DOT = 50,// .
     COMMA = 51,// ,
@@ -93,8 +94,6 @@ declare class Lexer {
     private position;
     private line;
     private column;
-    private lspLine;
-    private lspCharacter;
     private options;
     private lineOffsets;
     constructor(input: string, options?: LexerOptions);
@@ -115,6 +114,10 @@ declare class Lexer {
     private readTime;
     private readTimeFormat;
     private readTimezone;
+    private static readonly OPERATORS;
+    private isOperatorStarter;
+    private readOperator;
+    private scanQuoted;
     private skipWhitespace;
     private skipLineComment;
     private skipBlockComment;
@@ -123,6 +126,9 @@ declare class Lexer {
     private peek;
     private isDigit;
     private isWhitespace;
+    private isIdentifierHead;
+    private isIdentifierPart;
+    private scanIdentifierBody;
     /**
      * Convert absolute offset to LSP Position
      */
@@ -143,6 +149,41 @@ declare class Lexer {
     static couldBeKeywordOperator(token: Token): boolean;
 }
 
+declare enum CursorContext {
+    Operator = "operator",
+    Identifier = "identifier",
+    Argument = "argument",
+    Index = "index",
+    Type = "type"
+}
+interface CursorNode extends BaseASTNode {
+    type: 'CursorNode';
+    context: CursorContext;
+    position: number;
+}
+interface CursorOperatorNode extends CursorNode {
+    context: CursorContext.Operator;
+}
+interface CursorIdentifierNode extends CursorNode {
+    context: CursorContext.Identifier;
+    partialText?: string;
+}
+interface CursorArgumentNode extends CursorNode {
+    context: CursorContext.Argument;
+    functionName: string;
+    argumentIndex: number;
+}
+interface CursorIndexNode extends CursorNode {
+    context: CursorContext.Index;
+}
+interface CursorTypeNode extends CursorNode {
+    context: CursorContext.Type;
+    typeOperator: 'is' | 'as' | 'ofType';
+    partialText?: string;
+}
+type AnyCursorNode = CursorOperatorNode | CursorIdentifierNode | CursorArgumentNode | CursorIndexNode | CursorTypeNode;
+declare function isCursorNode(node: any): node is CursorNode;
+
 declare enum PRECEDENCE {
     IMPLIES = 10,
     OR = 20,
@@ -163,6 +204,7 @@ type TypeName = 'Any' | 'Boolean' | 'String' | 'Integer' | 'Long' | 'Decimal' |
 interface TypeInfo<TypeContext = unknown> {
     type: TypeName;
     singleton?: boolean;
+    isEmpty?: boolean;
     namespace?: string;
     name?: string;
     modelContext?: TypeContext;
@@ -191,6 +233,7 @@ interface OperatorSignature {
 interface OperatorDefinition {
     symbol: string;
     name: string;
+    doesNotPropagateEmpty?: boolean;
     category: string[];
     precedence: PRECEDENCE;
     associativity: 'left' | 'right';
@@ -207,6 +250,7 @@ interface FunctionSignature {
         optional?: boolean;
         type: TypeInfo;
         expression?: boolean;
+        typeReference?: boolean;
     }>;
     result: TypeInfo | 'inputType' | 'inputTypeSingleton' | 'parameterType';
 }
@@ -217,14 +261,17 @@ interface FunctionDefinition {
     examples: string[];
     signatures: FunctionSignature[];
     evaluate: FunctionEvaluator;
+    inferResultType?: (analyzer: any, node: any, inputType?: TypeInfo) => Promise<TypeInfo>;
+    analyze?: (context: AnalysisContext, args: ASTNode[]) => Promise<InternalAnalysisResult> | InternalAnalysisResult;
+    doesNotPropagateEmpty?: boolean;
 }
 declare enum NodeType {
     EOF = "EOF",
     Binary = "Binary",
     Unary = "Unary",
-    TypeOrIdentifier = "TypeOrIdentifier",
     Identifier = "Identifier",
     Literal = "Literal",
+    TemporalLiteral = "TemporalLiteral",
     Function = "Function",
     Variable = "Variable",
     Index = "Index",
@@ -256,7 +303,7 @@ interface TriviaInfo {
     range: Range;
 }
 interface BaseASTNode {
-    type: NodeType | 'Error';
+    type: NodeType | 'Error' | 'CursorNode';
     range: Range;
     parent?: ASTNode;
     children?: ASTNode[];
@@ -280,15 +327,17 @@ interface IdentifierNode extends BaseASTNode {
     name: string;
     symbolKind?: SymbolKind.Variable | SymbolKind.Function | SymbolKind.Property;
 }
-interface TypeOrIdentifierNode extends BaseASTNode {
-    type: NodeType.TypeOrIdentifier;
-    name: string;
-}
 interface LiteralNode extends BaseASTNode {
     type: NodeType.Literal;
     value: any;
     valueType: 'string' | 'number' | 'boolean' | 'date' | 'time' | 'datetime' | 'null';
 }
+interface TemporalLiteralNode extends BaseASTNode {
+    type: NodeType.TemporalLiteral;
+    value: any;
+    valueType: 'date' | 'time' | 'datetime';
+    rawValue: string;
+}
 interface BinaryNode extends BaseASTNode {
     type: NodeType.Binary;
     operator: string;
@@ -338,9 +387,8 @@ interface QuantityNode extends BaseASTNode {
     type: NodeType.Quantity;
     value: number;
     unit: string;
-    isCalendarUnit?: boolean;
 }
-type ASTNode = IdentifierNode | TypeOrIdentifierNode | LiteralNode | BinaryNode | UnaryNode | FunctionNode | VariableNode | IndexNode | MembershipTestNode | TypeCastNode | CollectionNode | TypeReferenceNode | QuantityNode | ErrorNode;
+type ASTNode = IdentifierNode | LiteralNode | TemporalLiteralNode | BinaryNode | UnaryNode | FunctionNode | VariableNode | IndexNode | MembershipTestNode | TypeCastNode | CollectionNode | TypeReferenceNode | QuantityNode | ErrorNode | AnyCursorNode;
 interface RuntimeContext {
     input: any[];
     focus: any[];
@@ -371,6 +419,8 @@ interface Diagnostic {
 interface AnalysisResult {
     diagnostics: Diagnostic[];
     ast: ASTNode;
+    type?: TypeInfo;
+    userVariables?: Map<string, TypeInfo>;
 }
 interface ParseError {
     message: string;
@@ -383,7 +433,7 @@ interface ParseResult {
     errors: ParseError[];
     indexes?: {
         nodeById: Map<string, ASTNode>;
-        nodesByType: Map<NodeType | 'Error', ASTNode[]>;
+        nodesByType: Map<NodeType | 'Error' | 'CursorNode', ASTNode[]>;
         identifiers: Map<string, ASTNode[]>;
     };
     cursorContext?: {
@@ -394,6 +444,34 @@ interface ParseResult {
 }
 type OperationEvaluator = (input: FHIRPathValue[], context: RuntimeContext, ...args: any[]) => Promise<EvaluationResult>;
 type FunctionEvaluator = (input: FHIRPathValue[], context: RuntimeContext, args: ASTNode[], evaluator: (node: ASTNode, input: FHIRPathValue[], context: RuntimeContext) => Promise<EvaluationResult>) => Promise<EvaluationResult>;
+/**
+ * Result of analyzing a single AST node in the context-flow architecture.
+ */
+interface InternalAnalysisResult {
+    type: TypeInfo;
+    diagnostics: Diagnostic[];
+    context?: AnalysisContext;
+}
+/**
+ * Immutable context that flows through the analysis tree.
+ * Carries variable scopes and input types through the AST.
+ */
+declare class AnalysisContext {
+    readonly inputType: TypeInfo;
+    readonly systemVariables: ReadonlyMap<string, TypeInfo>;
+    readonly userVariables: ReadonlyMap<string, TypeInfo>;
+    private readonly analyzeNodeCallback;
+    readonly modelProvider?: ModelProvider | undefined;
+    readonly hasDynamicVariables: boolean;
+    readonly _chainHead: boolean;
+    constructor(inputType: TypeInfo, systemVariables: ReadonlyMap<string, TypeInfo>, userVariables: ReadonlyMap<string, TypeInfo>, analyzeNodeCallback: (node: ASTNode, ctx: AnalysisContext) => Promise<InternalAnalysisResult>, modelProvider?: ModelProvider | undefined, hasDynamicVariables?: boolean, _chainHead?: boolean);
+    withUserVariable(name: string, type: TypeInfo): AnalysisContext;
+    withSystemVariable(name: string, type: TypeInfo): AnalysisContext;
+    withInputType(type: TypeInfo): AnalysisContext;
+    withDynamicVariables(): AnalysisContext;
+    fork(): AnalysisContext;
+    analyzeNode(node: ASTNode): Promise<InternalAnalysisResult>;
+}
 
 interface ParserOptions {
     mode?: 'simple' | 'lsp';
@@ -411,16 +489,15 @@ declare class Parser {
     protected current: number;
     private mode;
     private options;
+    private preserveTriviaEffective;
     private errors?;
-    private nodeIdCounter?;
-    private nodeIndex?;
-    private nodesByType?;
-    private identifierIndex?;
-    private currentParent?;
     private input;
+    private leadingTriviaByTokenStart?;
+    private trailingTriviaByTokenEnd?;
+    private tokenByStart?;
+    private tokenByEnd?;
     private readonly synchronizationTokens;
     constructor(input: string, options?: ParserOptions);
-    private checkCursor;
     private injectCursorToken;
     private getRangeFromToken;
     private getRangeFromTokens;
@@ -432,15 +509,13 @@ declare class Parser {
     protected parseExpressionWithPrecedence(minPrecedence: number): ASTNode;
     protected parsePrimary(): ASTNode;
     protected parseInvocation(): ASTNode;
-    protected parseArgumentList(): ASTNode[];
+    protected parseArgumentList(functionName?: string): ASTNode[];
+    protected parseFunctionCall(nameNode: ASTNode): 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;
@@ -450,24 +525,22 @@ declare class Parser {
     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 createTemporalLiteralNode(rawValue: string, valueType: TemporalLiteralNode['valueType'], token: Token): TemporalLiteralNode;
     protected createBinaryNode(token: Token, left: ASTNode, right: ASTNode): BinaryNode;
     protected createUnaryNode(token: Token, operand: ASTNode): UnaryNode;
-    protected createFunctionNode(name: ASTNode, args: ASTNode[], startToken: Token): FunctionNode;
+    protected createFunctionNode(name: ASTNode, args: ASTNode[]): FunctionNode;
     protected createVariableNode(name: string, token: Token): VariableNode;
     protected createIndexNode(expression: ASTNode, index: ASTNode, startToken: Token): IndexNode;
     protected createMembershipTestNode(expression: ASTNode, targetType: string, startToken: Token): MembershipTestNode;
     protected createTypeCastNode(expression: ASTNode, targetType: string, startToken: Token): TypeCastNode;
     protected createCollectionNode(elements: ASTNode[], startToken: Token): CollectionNode;
-    protected createQuantityNode(value: number, unit: string, isCalendarUnit: boolean, startToken: Token, endToken: Token): QuantityNode;
-    protected handleError(message: string, token?: Token): never;
-    private enrichNodeForLSP;
+    protected createQuantityNode(value: number, unit: string, startToken: Token, endToken: Token): QuantityNode;
+    protected handleAstError(message: string, token?: Token): ErrorNode;
+    private reportError;
+    private throwSyntax;
     private createErrorNode;
     private addError;
     private synchronize;
-    private findNodeAtPosition;
-    private getExpectedTokens;
-    private getExpectedTokensForError;
-    private getCompletions;
 }
 declare function parse(input: string, options?: ParserOptions): ParseResult;
 
@@ -497,7 +570,7 @@ declare class Registry {
     /**
      * Get functions applicable to a specific type
      */
-    getFunctionsForType(typeName: TypeName | string): FunctionDefinition[];
+    getFunctionsForType: (typeName: TypeName | string) => FunctionDefinition[];
     /**
      * Get operators applicable to a specific type
      */
@@ -505,7 +578,9 @@ declare class Registry {
     /**
      * Check if a function is applicable to a type
      */
-    isFunctionApplicableToType(functionName: string, typeName: TypeName | string): boolean;
+    private getTypeInfoFromString;
+    isTypeCompatible(inputType: TypeInfo, requiredType: TypeInfo): boolean;
+    isFunctionApplicableToType(functionName: string, type: string): boolean;
     /**
      * Check if an operator is applicable to a type
      */
@@ -513,6 +588,10 @@ declare class Registry {
 }
 declare const registry: Registry;
 
+/**
+ * Runtime context manager that provides efficient prototype-based context operations
+ * for both interpreter and compiler.
+ */
 declare class Interpreter {
     private registry;
     private nodeEvaluators;
@@ -523,9 +602,27 @@ declare class Interpreter {
     private registerOperationEvaluators;
     evaluate(node: ASTNode, input?: any[], context?: RuntimeContext): Promise<EvaluationResult>;
     private createInitialContext;
+    /**
+     * Parse, analyze and evaluate a FHIRPath expression with optional
+     * model provider, variables and input type. Returns unboxed values
+     * with temporal values formatted as FHIRPath literals.
+     */
+    evaluateExpression(expression: string, options?: {
+        input?: unknown;
+        variables?: Record<string, unknown>;
+        inputType?: TypeInfo;
+        modelProvider?: ModelProvider;
+        now?: Date;
+    }): Promise<any[]>;
+    private getBooleanKind;
+    private boxBoolean;
+    private evaluateTemporalLiteral;
     private evaluateLiteral;
+    private handleExtension;
+    private handleChoiceTypes;
+    private handleUnionChoices;
+    private handleStandardProperty;
     private evaluateIdentifier;
-    private evaluateTypeOrIdentifier;
     private evaluateBinary;
     private evaluateUnary;
     private evaluateVariable;
@@ -537,51 +634,6 @@ declare class Interpreter {
     private evaluateQuantity;
 }
 
-declare enum CursorContext {
-    Operator = "operator",
-    Identifier = "identifier",
-    Argument = "argument",
-    Index = "index",
-    Type = "type"
-}
-interface CursorNode {
-    type: 'CursorNode';
-    context: CursorContext;
-    position: number;
-    range: {
-        start: {
-            line: number;
-            character: number;
-            offset: number;
-        };
-        end: {
-            line: number;
-            character: number;
-            offset: number;
-        };
-    };
-}
-interface CursorOperatorNode extends CursorNode {
-    context: CursorContext.Operator;
-}
-interface CursorIdentifierNode extends CursorNode {
-    context: CursorContext.Identifier;
-}
-interface CursorArgumentNode extends CursorNode {
-    context: CursorContext.Argument;
-    functionName: string;
-    argumentIndex: number;
-}
-interface CursorIndexNode extends CursorNode {
-    context: CursorContext.Index;
-}
-interface CursorTypeNode extends CursorNode {
-    context: CursorContext.Type;
-    typeOperator: 'is' | 'as' | 'ofType';
-}
-type AnyCursorNode = CursorOperatorNode | CursorIdentifierNode | CursorArgumentNode | CursorIndexNode | CursorTypeNode;
-declare function isCursorNode(node: any): node is CursorNode;
-
 interface AnalyzerOptions {
     cursorMode?: boolean;
 }
@@ -591,56 +643,104 @@ interface AnalysisResultWithCursor extends AnalysisResult {
         typeBeforeCursor?: TypeInfo;
         expectedType?: TypeInfo;
         cursorNode?: AnyCursorNode;
+        functionCall?: {
+            definition: FunctionDefinition;
+            argumentIndex: number;
+        };
     };
 }
 declare class Analyzer {
-    private diagnostics;
-    private variables;
     private modelProvider?;
-    private userVariableTypes;
-    private systemVariableTypes;
     private cursorMode;
     private stoppedAtCursor;
     private cursorContext?;
     constructor(modelProvider?: ModelProvider);
-    analyze(ast: ASTNode, userVariables?: Record<string, any>, inputType?: TypeInfo, options?: AnalyzerOptions): Promise<AnalysisResultWithCursor>;
-    private visitNode;
-    private visitBinaryOperator;
-    private visitIdentifier;
-    private visitFunctionCall;
-    private visitMembershipTest;
-    private visitTypeCast;
-    private validateVariable;
-    private collectDefinedVariables;
-    private collectDefinedVariablesWithTypes;
-    private inferType;
-    private inferErrorNodeType;
-    private inferLiteralType;
-    private inferBinaryType;
-    private inferNavigationType;
-    private inferUnaryType;
-    private inferFunctionType;
-    private inferIdentifierType;
-    private inferTypeOrIdentifierType;
-    private inferVariableType;
-    private inferCollectionType;
-    private inferTypeCastType;
-    private isTypeCompatible;
-    private isSubtypeOf;
-    private isNumericType;
-    private inferValueType;
-    private resolveResultType;
-    private checkBinaryOperatorTypes;
-    private checkFunctionArgumentTypes;
-    private typeToString;
     /**
-     * Infer the expected type at a cursor position based on context
+     * Parse and analyze a FHIRPath expression end-to-end, returning an AnalysisResult
+     * and structured diagnostics. Supports optional error recovery (LSP mode).
+     */
+    static analyzeExpression(expression: string, options?: {
+        variables?: Record<string, unknown>;
+        modelProvider?: ModelProvider;
+        inputType?: TypeInfo;
+        errorRecovery?: boolean;
+        parserOptions?: ParserOptions;
+    }): Promise<AnalysisResultWithCursor>;
+    /**
+     * Main entry point for context-flow analysis.
+     * Analyzes a node with the given context.
      */
-    private inferExpectedTypeForCursor;
+    private analyzeNode;
     /**
-     * Annotate AST with type information
+     * Analyzes binary operators with special handling for union and dot.
      */
-    private annotateAST;
+    private analyzeBinary;
+    /**
+     * Analyzes function calls, delegating to function's analyze method if available.
+    */
+    private analyzeFunction;
+    private getFunctionName;
+    private validateArity;
+    private validateUnionTypeFilters;
+    private analyzeArguments;
+    private matchAndDiagnoseSignature;
+    private propagatesEmpty;
+    private inferFunctionResultType;
+    /**
+     * Analyzes variable references, checking against context.
+     */
+    private analyzeVariable;
+    /**
+     * Analyzes identifier nodes (property access).
+     */
+    private analyzeIdentifier;
+    /**
+     * Analyzes literal values.
+     */
+    private analyzeLiteral;
+    private analyzeTemporalLiteral;
+    /**
+     * Analyzes unary operators.
+     */
+    private analyzeUnary;
+    /**
+     * Analyzes index operations.
+     */
+    private analyzeIndex;
+    /**
+     * Analyzes quantity literals.
+     */
+    private analyzeQuantity;
+    /**
+     * Analyzes collection literals.
+     */
+    private analyzeCollection;
+    /**
+     * Analyzes membership test (is operator).
+     */
+    private analyzeMembershipTest;
+    /**
+     * Analyzes type cast (as operator).
+     */
+    private analyzeTypeCast;
+    /**
+     * Analyzes error nodes.
+     */
+    private analyzeError;
+    /**
+     * Analyzes cursor nodes for completion.
+     */
+    private analyzeCursorNode;
+    /**
+     * Helper to create diagnostic errors.
+     */
+    private createError;
+    private createWarning;
+    /**
+     * Helper method to infer TypeInfo from runtime values (used for user variables).
+     */
+    private inferValueType;
+    analyze(ast: ASTNode, userVariables?: Record<string, any>, inputType?: TypeInfo, options?: AnalyzerOptions): Promise<AnalysisResultWithCursor>;
 }
 
 interface FHIRModelContext {
@@ -707,7 +807,6 @@ declare class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     getResourceTypes(): Promise<string[]>;
     getComplexTypes(): Promise<string[]>;
     getPrimitiveTypes(): Promise<string[]>;
-    getTypeFromCache(typeName: string): TypeInfo<FHIRModelContext> | undefined;
 }
 
 interface ASTMetadata {
@@ -769,6 +868,7 @@ declare const Errors: {
     unknownNodeType(nodeType: string, location?: Range): FHIRPathError;
     noEvaluatorFound(evaluatorType: string, name: string, location?: Range): FHIRPathError;
     variableNotDefined(name: string, location?: Range): FHIRPathError;
+    variableAlreadyDefined(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;
@@ -798,6 +898,8 @@ declare const Errors: {
     invalidPrecision(operation: string, location?: Range): FHIRPathError;
     invalidStringOperation(operation: string, paramName: string, location?: Range): FHIRPathError;
     invalidNumericOperation(operation: string, paramName: string, expectedType: string, location?: Range): FHIRPathError;
+    invalidTemporalUnit(temporalType: string, unit: string, location?: Range): FHIRPathError;
+    unsupportedTemporalUnitForType(temporalType: string, unit: string, location?: Range): FHIRPathError;
 };
 declare enum ErrorCodes {
     UNKNOWN_OPERATOR = "FP1001",
@@ -813,7 +915,7 @@ declare enum ErrorCodes {
     SINGLETON_REQUIRED = "FP2003",
     EMPTY_NOT_ALLOWED = "FP2004",
     ARGUMENT_REQUIRED = "FP2005",
-    OPERATOR_TYPE_MISMATCH = "FP3002",
+    OPERATOR_TYPE_MISMATCH = "FP3006",
     ARGUMENT_TYPE_MISMATCH = "FP3003",
     CONVERSION_FAILED = "FP3004",
     INVALID_VALUE_TYPE = "FP3005",
@@ -834,7 +936,11 @@ declare enum ErrorCodes {
     INVALID_OPERATION = "FP6005",
     INVALID_PRECISION = "FP6006",
     INVALID_STRING_OPERATION = "FP6007",
-    INVALID_NUMERIC_OPERATION = "FP6008"
+    INVALID_NUMERIC_OPERATION = "FP6008",
+    VARIABLE_ALREADY_DEFINED = "FP6009",
+    INVALID_TEMPORAL_UNIT = "FP6010",
+    UNSUPPORTED_TEMPORAL_UNIT_FOR_TYPE = "FP6011",
+    UNREACHABLE_CODE = "FP7001"
 }
 
 /**
@@ -863,7 +969,7 @@ interface CompletionItem {
     documentation?: string;
     /** Text to insert (if different from label) */
     insertText?: string;
-    /** Sort order */
+    /** Sort text for ordering (if different from label) */
     sortText?: string;
 }
 /**