@atomic-ehr/fhirpath 0.0.1-canary.8687028.20250724113707

package/src/interpreter/context.ts

@@ -0,0 +1,181 @@
+import type { Context } from './types';
+
+/**
+ * Context management utilities for FHIRPath interpreter.
+ * Context flows parallel to data through expressions.
+ * 
+ * Uses JavaScript prototype chain for efficient inheritance.
+ */
+export class ContextManager {
+  /**
+   * Create a new empty context
+   */
+  static create(initialInput?: any[]): Context {
+    // Create base context with null prototype to avoid Object.prototype pollution
+    const context = Object.create(null) as Context;
+    
+    // Initialize with prototype-based objects
+    context.variables = Object.create(null);
+    context.env = Object.create(null);
+    
+    // Set root variables
+    context.$context = initialInput;
+    context.$resource = initialInput;
+    context.$rootResource = initialInput;
+    
+    return context;
+  }
+
+  /**
+   * Create a child context inheriting from parent via prototype chain
+   * O(1) operation - no copying needed
+   */
+  static copy(context: Context): Context {
+    // Create child context with parent as prototype
+    const newContext = Object.create(context) as Context;
+    
+    // Create child objects that inherit from parent's objects
+    newContext.variables = Object.create(context.variables);
+    newContext.env = Object.create(context.env);
+    
+    // Root variables are inherited automatically through prototype chain
+    // No need to copy them unless they change
+    
+    return newContext;
+  }
+
+  /**
+   * Add or update a variable in context
+   * Only sets on current context level, shadowing parent values
+   */
+  static setVariable(context: Context, name: string, value: any[]): Context {
+    const newContext = this.copy(context);
+    newContext.variables[name] = value;
+    return newContext;
+  }
+
+  /**
+   * Get a variable value from context
+   * Uses prototype chain for lookup
+   */
+  static getVariable(context: Context, name: string): any[] | undefined {
+    // Check user-defined variables first (prototype chain handles inheritance)
+    if (name in context.variables) {
+      return context.variables[name];
+    }
+
+    // Check special root variables
+    switch (name) {
+      case 'context':
+        return context.$context;
+      case 'resource':
+        return context.$resource;
+      case 'rootResource':
+        return context.$rootResource;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Set iterator context ($this, $index) - used by where(), select(), etc.
+   */
+  static setIteratorContext(
+    context: Context, 
+    item: any, 
+    index: number
+  ): Context {
+    const newContext = this.copy(context);
+    // Only set changed values - prototype provides the rest
+    newContext.env.$this = [item];
+    newContext.env.$index = index;
+    return newContext;
+  }
+
+  /**
+   * Set aggregate context ($total) - used by aggregate()
+   */
+  static setAggregateContext(
+    context: Context,
+    total: any[]
+  ): Context {
+    const newContext = this.copy(context);
+    newContext.env.$total = total;
+    return newContext;
+  }
+
+  /**
+   * Clear iterator/aggregate context - restore to original
+   */
+  static clearEnv(context: Context): Context {
+    const newContext = this.copy(context);
+    // Create fresh env object, effectively hiding parent's env values
+    newContext.env = Object.create(null);
+    return newContext;
+  }
+
+  /**
+   * Get special environment variable
+   */
+  static getEnvVariable(context: Context, name: '$this' | '$index' | '$total'): any {
+    switch (name) {
+      case '$this':
+        return context.env.$this;
+      case '$index':
+        return context.env.$index;
+      case '$total':
+        return context.env.$total;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Check if a variable exists in context (including inherited)
+   */
+  static hasVariable(context: Context, name: string): boolean {
+    return (name in context.variables) || 
+           ['context', 'resource', 'rootResource'].includes(name);
+  }
+
+  /**
+   * Debug helper - get all variables including inherited ones
+   * Traverses prototype chain to collect all variables
+   */
+  static getAllVariables(context: Context): Record<string, any[]> {
+    const result: Record<string, any[]> = {};
+    
+    // Traverse prototype chain for user variables
+    let currentVars = context.variables;
+    while (currentVars) {
+      for (const key in currentVars) {
+        if (!(key in result) && Object.prototype.hasOwnProperty.call(currentVars, key)) {
+          result[`%${key}`] = currentVars[key]!;
+        }
+      }
+      currentVars = Object.getPrototypeOf(currentVars);
+    }
+
+    // Root variables
+    if (context.$context) result['%context'] = context.$context;
+    if (context.$resource) result['%resource'] = context.$resource;
+    if (context.$rootResource) result['%rootResource'] = context.$rootResource;
+
+    // Environment variables (also traverse prototype chain)
+    let currentEnv = context.env;
+    while (currentEnv) {
+      if (currentEnv.$this !== undefined && !('$this' in result)) {
+        result['$this'] = currentEnv.$this;
+      }
+      if (currentEnv.$index !== undefined && !('$index' in result)) {
+        result['$index'] = [currentEnv.$index];
+      }
+      if (currentEnv.$total !== undefined && !('$total' in result)) {
+        result['$total'] = currentEnv.$total;
+      }
+      currentEnv = Object.getPrototypeOf(currentEnv);
+    }
+
+    return result;
+  }
+}

package/src/interpreter/interpreter.ts

@@ -0,0 +1,429 @@
+import type { 
+  ASTNode, 
+  LiteralNode, 
+  IdentifierNode, 
+  VariableNode,
+  BinaryNode,
+  UnaryNode,
+  FunctionNode,
+  CollectionNode,
+  IndexNode,
+  UnionNode,
+  MembershipTestNode,
+  TypeCastNode,
+  TypeReferenceNode,
+  TypeOrIdentifierNode
+} from '../parser/ast';
+import { NodeType } from '../parser/ast';
+import { TokenType } from '../lexer/token';
+import type { Context, EvaluationResult } from './types';
+import { EvaluationError, CollectionUtils } from './types';
+import { ContextManager } from './context';
+import { TypeSystem } from '../registry/utils/type-system';
+import { Registry } from '../registry';
+import type { Interpreter as IInterpreter } from '../registry/types';
+
+// Import registry to trigger operation registration
+import '../registry';
+
+// Type for node evaluator functions
+type NodeEvaluator = (node: any, input: any[], context: Context) => EvaluationResult;
+
+/**
+ * FHIRPath Interpreter - evaluates AST nodes following the stream-processing model.
+ * Every node is a processing unit: (input, context) → (output, new context)
+ * 
+ * This refactored version uses object lookup instead of switch statements.
+ */
+export class Interpreter implements IInterpreter {
+  // Object lookup for node evaluators
+  private readonly nodeEvaluators: Record<NodeType, NodeEvaluator> = {
+    [NodeType.Literal]: this.evaluateLiteral.bind(this),
+    [NodeType.Identifier]: this.evaluateIdentifier.bind(this),
+    [NodeType.TypeOrIdentifier]: this.evaluateTypeOrIdentifier.bind(this),
+    [NodeType.Variable]: this.evaluateVariable.bind(this),
+    [NodeType.Binary]: this.evaluateBinary.bind(this),
+    [NodeType.Unary]: this.evaluateUnary.bind(this),
+    [NodeType.Function]: this.evaluateFunction.bind(this),
+    [NodeType.Collection]: this.evaluateCollection.bind(this),
+    [NodeType.Index]: this.evaluateIndex.bind(this),
+    [NodeType.Union]: this.evaluateUnion.bind(this),
+    [NodeType.MembershipTest]: this.evaluateMembershipTest.bind(this),
+    [NodeType.TypeCast]: this.evaluateTypeCast.bind(this),
+    [NodeType.TypeReference]: this.evaluateTypeReference.bind(this),
+  };
+
+  /**
+   * Main evaluation method - uses object lookup instead of switch
+   */
+  evaluate(node: ASTNode, input: any[], context: Context): EvaluationResult {
+    try {
+      // Ensure $this is set in the context if not already present
+      if (!context.env.$this) {
+        context = {
+          ...context,
+          env: {
+            ...context.env,
+            $this: input
+          }
+        };
+      }
+      
+      const evaluator = this.nodeEvaluators[node.type];
+      
+      if (!evaluator) {
+        throw new EvaluationError(
+          `Unknown node type: ${node.type}`,
+          node.position
+        );
+      }
+      
+      return evaluator(node, input, context);
+    } catch (error) {
+      // Add position information if not already present
+      if (error instanceof EvaluationError && !error.position && node.position) {
+        error.position = node.position;
+      }
+      throw error;
+    }
+  }
+
+  private evaluateLiteral(node: LiteralNode, input: any[], context: Context): EvaluationResult {
+    // If literal has operation reference from parser
+    if (node.operation && node.operation.kind === 'literal') {
+      return node.operation.evaluate(this, context, input);
+    }
+    
+    // Fallback for legacy literals
+    const value = node.value === null ? [] : [node.value];
+    return { value, context };
+  }
+
+  private evaluateIdentifier(node: IdentifierNode, input: any[], context: Context): EvaluationResult {
+    // Identifier performs property navigation on each item in input
+    const results: any[] = [];
+    
+    for (const item of input) {
+      if (item == null || typeof item !== 'object') {
+        // Primitives don't have properties - skip
+        continue;
+      }
+      
+      const value = item[node.name];
+      if (value !== undefined) {
+        // Add to results - flatten if array
+        if (Array.isArray(value)) {
+          results.push(...value);
+        } else {
+          results.push(value);
+        }
+      }
+      // Missing properties return empty (not added to results)
+    }
+    
+    return { value: results, context };
+  }
+
+  private evaluateTypeOrIdentifier(node: TypeOrIdentifierNode, input: any[], context: Context): EvaluationResult {
+    // TypeOrIdentifier can act as either a type reference or property navigation
+    // For now, treat it as an identifier
+    return this.evaluateIdentifier(node as any, input, context);
+  }
+
+  private evaluateVariable(node: VariableNode, input: any[], context: Context): EvaluationResult {
+    // Variables ignore input and return value from context
+    let value: any[] = [];
+    
+    if (node.name.startsWith('$')) {
+      // Special environment variables - use object lookup
+      const envVarHandlers: Record<string, () => any[]> = {
+        '$this': () => context.env.$this || [],
+        '$index': () => context.env.$index !== undefined ? [context.env.$index] : [],
+        '$total': () => context.env.$total || [],
+      };
+      
+      const handler = envVarHandlers[node.name];
+      if (!handler) {
+        throw new EvaluationError(`Unknown special variable: ${node.name}`, node.position);
+      }
+      value = handler();
+    } else {
+      // User-defined variables (remove % prefix if present)
+      const varName = node.name.startsWith('%') ? node.name.substring(1) : node.name;
+      value = ContextManager.getVariable(context, varName) || [];
+    }
+    
+    return { value, context };
+  }
+
+  private evaluateBinary(node: BinaryNode, input: any[], context: Context): EvaluationResult {
+    // Special handling for dot operator - it's a pipeline
+    if (node.operator === TokenType.DOT) {
+      // Phase 1: Evaluate left with original input/context
+      const leftResult = this.evaluate(node.left, input, context);
+      
+      // Phase 2: Evaluate right with left's output as input
+      const rightResult = this.evaluate(node.right, leftResult.value, leftResult.context);
+      
+      return rightResult;
+    }
+    
+    // Handle case where parser incorrectly creates BinaryNode for unary minus
+    if (!node.left && !node.right && (node as any).operand) {
+      // This is actually a unary operation
+      const unaryOp = Registry.getByToken(node.operator, 'prefix');
+      if (unaryOp && unaryOp.kind === 'operator') {
+        const operandResult = this.evaluate((node as any).operand, input, context);
+        return unaryOp.evaluate(this, operandResult.context, input, operandResult.value);
+      }
+    }
+
+    // Get operation from registry (binary operators are infix)
+    const operation = node.operation || Registry.getByToken(node.operator, 'infix');
+    if (!operation || operation.kind !== 'operator') {
+      throw new EvaluationError(`Unknown operator: ${node.operator}`, node.position);
+    }
+    
+    if (!node.left || !node.right) {
+      throw new EvaluationError(`Binary operator ${node.operator} missing operands`, node.position);
+    }
+    
+    const leftResult = this.evaluate(node.left, input, context);
+    const rightResult = this.evaluate(node.right, input, leftResult.context);
+    
+    // Use operation's evaluate method
+    return operation.evaluate(this, rightResult.context, input, leftResult.value, rightResult.value);
+  }
+
+  private evaluateUnary(node: UnaryNode, input: any[], context: Context): EvaluationResult {
+    // Get operation from registry (unary operators are prefix)
+    // Don't use node.operation as parser might have assigned wrong operation
+    const operation = Registry.getByToken(node.operator, 'prefix');
+    if (!operation || operation.kind !== 'operator') {
+      throw new EvaluationError(`Unknown unary operator: ${node.operator}`, node.position);
+    }
+    
+    // Evaluate operand
+    const operandResult = this.evaluate(node.operand, input, context);
+    
+    // Use operation's evaluate method
+    return operation.evaluate(this, operandResult.context, input, operandResult.value);
+  }
+
+  private evaluateFunction(node: FunctionNode, input: any[], context: Context): EvaluationResult {
+    // Extract function name and handle method call syntax
+    let funcName: string;
+    let functionInput = input;
+    
+    if (node.name.type === NodeType.Identifier) {
+      funcName = (node.name as IdentifierNode).name;
+    } else if (node.name.type === NodeType.Binary && (node.name as BinaryNode).operator === TokenType.DOT) {
+      // Method call syntax: expression.function(args)
+      const binaryNode = node.name as BinaryNode;
+      
+      // Evaluate the left side to get the input
+      const leftResult = this.evaluate(binaryNode.left, input, context);
+      functionInput = leftResult.value;
+      context = leftResult.context;
+      
+      // Get the function name from the right side
+      if (binaryNode.right.type === NodeType.Identifier) {
+        funcName = (binaryNode.right as IdentifierNode).name;
+      } else {
+        throw new EvaluationError('Invalid method call syntax', node.position);
+      }
+    } else {
+      throw new EvaluationError('Complex function names not yet supported', node.position);
+    }
+    
+    // Check for custom functions first
+    if (context.customFunctions && funcName in context.customFunctions) {
+      const customFunc = context.customFunctions[funcName];
+      
+      // Evaluate all arguments
+      const evaluatedArgs: any[] = [];
+      for (const arg of node.arguments) {
+        const argResult = this.evaluate(arg, functionInput, context);
+        evaluatedArgs.push(argResult.value);
+        context = argResult.context;
+      }
+      
+      // Call custom function
+      const result = customFunc!(context, functionInput, ...evaluatedArgs);
+      return { value: result, context };
+    }
+    
+    // Get function from registry
+    const operation = Registry.get(funcName);
+    if (!operation || operation.kind !== 'function') {
+      throw new EvaluationError(`Unknown function: ${funcName}`, node.position);
+    }
+    
+    // Check propagateEmptyInput flag
+    if (operation.signature.propagatesEmpty && functionInput.length === 0) {
+      return { value: [], context };
+    }
+    
+    // Evaluate arguments based on parameter definitions
+    const evaluatedArgs: any[] = [];
+    for (let i = 0; i < node.arguments.length; i++) {
+      const arg = node.arguments[i];
+      const param = operation.signature.parameters[i];
+      
+      if (param && param.kind === 'expression') {
+        // Pass expression as-is, will be evaluated by the function
+        evaluatedArgs.push(arg);
+      } else {
+        // Evaluate the argument to get its value
+        const argResult = this.evaluate(arg!, functionInput, context);
+        evaluatedArgs.push(argResult.value);
+        context = argResult.context;
+      }
+    }
+    
+    // Use operation's evaluate method
+    return operation.evaluate(this, context, functionInput, ...evaluatedArgs);
+  }
+
+  private evaluateCollection(node: CollectionNode, input: any[], context: Context): EvaluationResult {
+    // Evaluate each element and combine results
+    const results: any[] = [];
+    let currentContext = context;
+
+    for (const element of node.elements) {
+      const result = this.evaluate(element, input, currentContext);
+      results.push(...result.value);
+      currentContext = result.context;
+    }
+
+    return { value: results, context: currentContext };
+  }
+
+  private evaluateIndex(node: IndexNode, input: any[], context: Context): EvaluationResult {
+    // Evaluate the expression being indexed
+    const exprResult = this.evaluate(node.expression, input, context);
+    
+    // Evaluate the index expression in the original context
+    const indexResult = this.evaluate(node.index, input, context);
+    
+    // Index must be a single integer
+    if (indexResult.value.length === 0) {
+      return { value: [], context: indexResult.context };
+    }
+    
+    const index = CollectionUtils.toSingleton(indexResult.value);
+    if (typeof index !== 'number' || !Number.isInteger(index)) {
+      throw new EvaluationError('Index must be an integer', node.position);
+    }
+    
+    // FHIRPath uses 0-based indexing
+    if (index < 0 || index >= exprResult.value.length) {
+      // Out of bounds returns empty
+      return { value: [], context: indexResult.context };
+    }
+    
+    return { value: [exprResult.value[index]], context: indexResult.context };
+  }
+
+  private evaluateUnion(node: UnionNode, input: any[], context: Context): EvaluationResult {
+    // Union combines results from all operands
+    const results: any[] = [];
+    let currentContext = context;
+
+    for (const operand of node.operands) {
+      const result = this.evaluate(operand, input, currentContext);
+      results.push(...result.value);
+      // Thread context through operands
+      currentContext = result.context;
+    }
+
+    return { value: results, context: currentContext };
+  }
+
+  private evaluateMembershipTest(node: MembershipTestNode, input: any[], context: Context): EvaluationResult {
+    // Evaluate the expression to get values to test
+    const exprResult = this.evaluate(node.expression, input, context);
+    
+    // Empty collection: is returns empty
+    if (exprResult.value.length === 0) {
+      return { value: [], context: exprResult.context };
+    }
+    
+    // Check if ALL values match the type
+    for (const value of exprResult.value) {
+      if (!TypeSystem.isType(value, node.targetType)) {
+        return { value: [false], context: exprResult.context };
+      }
+    }
+    
+    // All values match the type
+    return { value: [true], context: exprResult.context };
+  }
+
+  private evaluateTypeCast(node: TypeCastNode, input: any[], context: Context): EvaluationResult {
+    // Evaluate the expression to get values to cast
+    const exprResult = this.evaluate(node.expression, input, context);
+    
+    // For each value, attempt to cast to the target type
+    const results: any[] = [];
+    for (const value of exprResult.value) {
+      // If already the correct type, keep it
+      if (TypeSystem.isType(value, node.targetType)) {
+        results.push(value);
+      }
+      // Otherwise, try to cast (returns null if fails)
+      else {
+        const castValue = TypeSystem.cast(value, node.targetType);
+        if (castValue !== null) {
+          results.push(castValue);
+        }
+        // Failed casts are filtered out (not added to results)
+      }
+    }
+    
+    // Return filtered collection
+    return { value: results, context: exprResult.context };
+  }
+
+  private evaluateTypeReference(node: TypeReferenceNode, input: any[], context: Context): EvaluationResult {
+    // Type references don't evaluate to values directly
+    throw new EvaluationError(`Type reference cannot be evaluated: ${node.typeName}`, node.position);
+  }
+}
+
+/**
+ * Helper function to evaluate a FHIRPath expression
+ */
+export function evaluateFHIRPath(
+  expression: string | ASTNode, 
+  input: any, 
+  context?: Context
+): any[] {
+  // Parse if string
+  const ast = typeof expression === 'string' 
+    ? require('../parser').parse(expression)
+    : expression;
+
+  // Convert input to collection
+  const inputCollection = CollectionUtils.toCollection(input);
+
+  // Create context if not provided and set initial $this
+  let evalContext = context || ContextManager.create(inputCollection);
+  
+  // Set initial $this to the input collection if not already set
+  if (!evalContext.env.$this) {
+    evalContext = {
+      ...evalContext,
+      env: {
+        ...evalContext.env,
+        $this: inputCollection
+      }
+    };
+  }
+
+  // Create interpreter and evaluate
+  const interpreter = new Interpreter();
+  const result = interpreter.evaluate(ast, inputCollection, evalContext);
+
+  return result.value;
+}