@atomic-ehr/fhirpath 0.0.2 → 0.0.3

package/src/errors.ts

@@ -70,6 +70,10 @@ export const Errors = {
     return new FHIRPathError(ErrorCodes.VARIABLE_NOT_DEFINED, `Variable '${name}' is not defined in the current scope`, location);
   },
   
+  variableAlreadyDefined(name: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.VARIABLE_ALREADY_DEFINED, `Variable '${name}' already defined in current scope`, location);
+  },
+  
   // Arity errors (2000-2999)
   wrongArgumentCount(funcName: string, expected: number, actual: number, location?: Range): FHIRPathError {
     return new FHIRPathError(ErrorCodes.WRONG_ARGUMENT_COUNT, `${funcName} expects ${expected} arguments, got ${actual}`, location);
@@ -192,6 +196,18 @@ export const Errors = {
   
   invalidNumericOperation(operation: string, paramName: string, expectedType: string, location?: Range): FHIRPathError {
     return new FHIRPathError(ErrorCodes.INVALID_NUMERIC_OPERATION, `${operation} ${paramName} must be ${expectedType}`, location);
+  },
+  
+  invalidTemporalUnit(temporalType: string, unit: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(ErrorCodes.INVALID_TEMPORAL_UNIT, `Cannot use variable-duration unit '${unit}' with ${temporalType} - use calendar duration keywords instead`, location);
+  },
+
+  unsupportedTemporalUnitForType(temporalType: string, unit: string, location?: Range): FHIRPathError {
+    return new FHIRPathError(
+      ErrorCodes.UNSUPPORTED_TEMPORAL_UNIT_FOR_TYPE,
+      `Unit '${unit}' is not allowed for ${temporalType} arithmetic; allowed units: years, months, weeks, days`,
+      location
+    );
   }
 };
 
@@ -216,7 +232,7 @@ export enum ErrorCodes {
   
   // Type errors (3000-3999)
   // FP3001 - removed (unified with FP3006)
-  OPERATOR_TYPE_MISMATCH = 'FP3002',
+  OPERATOR_TYPE_MISMATCH = 'FP3006',
   ARGUMENT_TYPE_MISMATCH = 'FP3003',
   CONVERSION_FAILED = 'FP3004',
   INVALID_VALUE_TYPE = 'FP3005',
@@ -243,5 +259,11 @@ export 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',
+  
+  // Static analysis warnings (7000-7999)
+  UNREACHABLE_CODE = 'FP7001'
+}

package/src/index.ts

@@ -1,9 +1,9 @@
 import { Parser } from './parser';
-import { Interpreter, RuntimeContextManager } from './interpreter';
+import { Interpreter } from './interpreter';
 import { Analyzer } from './analyzer';
 import type { AnalysisResult } from './types';
-import { box, unbox } from './boxing';
-import { FHIRPathError, Errors } from './errors';
+import { DiagnosticSeverity } from './types';
+import { FHIRPathError, Errors, ErrorCodes } from './errors';
 
 export interface EvaluateOptions {
   input?: unknown;
@@ -16,79 +16,13 @@ export async function evaluate(
   expression: string,
   options: EvaluateOptions = {}
 ): Promise<any[]> {
-  const parser = new Parser(expression);
-  const parseResult = parser.parse();
-  
-  // Check for parse errors
-  if (parseResult.errors.length > 0) {
-    // For backward compatibility, throw the first error
-    const firstError = parseResult.errors[0]!;
-    throw Errors.invalidSyntax(firstError.message);
-  }
-  
-  // ALWAYS analyze the AST
-  const analyzer = new Analyzer(options.modelProvider);
-  const analysisResult = await analyzer.analyze(
-    parseResult.ast, 
-    options.variables,
-    options.inputType
-  );
-  
-  // Check for analysis errors
-  const errors = analysisResult.diagnostics.filter(d => d.severity === 1); // DiagnosticSeverity.Error
-  if (errors.length > 0) {
-    // Throw the first error
-    const firstError = errors[0]!;
-    if (firstError.code) {
-      // Always throw as FHIRPathError if we have a code
-      throw new FHIRPathError(firstError.code, firstError.message, firstError.range);
-    } else {
-      // Otherwise throw a generic error
-      throw new Error(firstError.message);
-    }
-  }
-  
-  // Use the analyzed AST with type information
   const interpreter = new Interpreter(undefined, options.modelProvider);
-  const input = options.input === undefined ? [] : Array.isArray(options.input) ? options.input : [options.input];
-  
-  // Box input with typeInfo if we have a modelProvider and the input is a FHIR resource
-  let boxedInput = input;
-  if (options.modelProvider) {
-    boxedInput = await Promise.all(input.map(async item => {
-      if (item && typeof item === 'object' && 'resourceType' in item && typeof item.resourceType === 'string') {
-        // Get type info asynchronously
-        const typeInfo = await options.modelProvider!.getType(item.resourceType);
-        if (typeInfo) {
-          return box(item, typeInfo);
-        }
-      }
-      return item;
-    }));
-  }
-  
-  // Create context with variables if provided
-  let context = RuntimeContextManager.create(input);
-  
-  // Set $this to the boxed input (required for expressions like $this.where(...))
-  context = RuntimeContextManager.setVariable(context, '$this', boxedInput);
-  
-  // Add model provider to context if available
-  if (options.modelProvider) {
-    context.modelProvider = options.modelProvider;
-  }
-  
-  if (options.variables) {
-    for (const [key, value] of Object.entries(options.variables)) {
-      const varValue = Array.isArray(value) ? value : [value];
-      context = RuntimeContextManager.setVariable(context, key, varValue);
-    }
-  }
-  
-  const result = await interpreter.evaluate(analysisResult.ast, input, context);
-  
-  // Unbox the results before returning
-  return result.value.map(unbox);
+  return interpreter.evaluateExpression(expression, {
+    input: options.input,
+    variables: options.variables,
+    inputType: options.inputType,
+    modelProvider: options.modelProvider,
+  });
 }
 
 export async function analyze(
@@ -100,33 +34,12 @@ export async function analyze(
     errorRecovery?: boolean;
   } = {}
 ): Promise<AnalysisResult> {
-  // Use LSP mode with error recovery if requested
-  const parserOptions = options.errorRecovery 
-    ? { mode: 'lsp' as const, errorRecovery: true }
-    : undefined;
-    
-  const parser = new Parser(expression, parserOptions);
-  const parseResult = parser.parse();
-  
-  // Check for parse errors only if error recovery is disabled
-  if (!options.errorRecovery && parseResult.errors.length > 0) {
-    // For backward compatibility, throw the first error
-    const firstError = parseResult.errors[0]!;
-    throw Errors.invalidSyntax(firstError.message);
-  }
-  
-  const ast = parseResult.ast;
-  
-  // Create analyzer with optional model provider
-  const analyzer = new Analyzer(options.modelProvider);
-  const analysisResult = await analyzer.analyze(ast, options.variables, options.inputType);
-  
-  // If error recovery is enabled, merge parse errors into diagnostics
-  if (options.errorRecovery && parseResult.errors.length > 0) {
-    // Parse errors are already converted to diagnostics by the analyzer
-    // when it encounters Error nodes in the AST
-  }
-  
+  const analysisResult = await Analyzer.analyzeExpression(expression, {
+    variables: options.variables,
+    modelProvider: options.modelProvider,
+    inputType: options.inputType,
+    errorRecovery: options.errorRecovery,
+  });
   return analysisResult;
 }
 
@@ -183,7 +96,7 @@ export type {
 } from './completion-provider';
 
 // Export cursor node types for LSP integration
-export { CursorContext, isCursorNode } from './cursor-nodes';
+export { CursorContext, isCursorNode } from './parser/cursor-nodes';
 export type {
   CursorNode,
   CursorOperatorNode,
@@ -192,4 +105,4 @@ export type {
   CursorIndexNode,
   CursorTypeNode,
   AnyCursorNode
-} from './cursor-nodes';
+} from './parser/cursor-nodes';

package/src/inspect.ts

@@ -1,9 +1,10 @@
 import type { TypeInfo, ASTNode, Diagnostic } from './types';
-import type { FHIRPathValue } from './boxing';
+import type { FHIRPathValue } from './interpreter/boxing';
 import { NodeType, DiagnosticSeverity } from './types';
 import { parse } from './parser';
 import { Analyzer } from './analyzer';
-import { Interpreter, RuntimeContextManager } from './interpreter';
+import { Interpreter } from './interpreter';
+import { RuntimeContextManager } from './interpreter/runtime-context';
 import type { RuntimeContext } from './types';
 
 export interface ASTMetadata {
@@ -137,7 +138,6 @@ function analyzeAST(node: ASTNode, maxDepth = 100): ASTMetadata {
       case NodeType.Identifier:
       case NodeType.Variable:
       case NodeType.TypeReference:
-      case NodeType.TypeOrIdentifier:
         complexity += 1;
         break;
     }
@@ -334,4 +334,4 @@ export async function inspect(
     },
     ...(options.includeTraces && { traces })
   };
-}
+}

package/src/{boxing.ts → interpreter/boxing.ts}

@@ -1,4 +1,4 @@
-import type {TypeInfo} from './types';
+import type {TypeInfo} from '../types';
 export type {TypeInfo};
 
 /**

package/src/interpreter/navigator.ts

@@ -0,0 +1,94 @@
+import type { ModelProvider, TypeInfo, TypeName } from '../types';
+import { box, type FHIRPathValue } from './boxing';
+
+interface ChoiceHit {
+  readonly value: any;
+  readonly typeInfo: TypeInfo;
+  readonly primitiveElement?: any;
+}
+
+function getPrimitiveElement(item: Record<string, unknown>, prop: string): any | undefined {
+  const primitiveElementName = `_${prop}`;
+  return Object.prototype.hasOwnProperty.call(item, primitiveElementName)
+    ? (item as any)[primitiveElementName]
+    : undefined;
+}
+
+async function maybeParseTemporal(
+  value: any,
+  expected: TypeInfo | undefined,
+  modelProvider?: ModelProvider
+): Promise<any> {
+  if (!modelProvider || !expected || typeof value !== 'string') {
+    return value;
+  }
+  if (expected.type === 'Date' || expected.type === 'DateTime' || expected.type === 'Time') {
+    const { parseTemporalLiteral } = await import('../complex-types/temporal');
+    return parseTemporalLiteral('@' + value);
+  }
+  return value;
+}
+
+async function reboxResource(
+  value: any,
+  singleton: boolean,
+  modelProvider?: ModelProvider
+): Promise<FHIRPathValue> {
+  let resourceTypeInfo: TypeInfo | undefined;
+  if (modelProvider && typeof value?.resourceType === 'string') {
+    resourceTypeInfo = await modelProvider.getType(value.resourceType);
+    if (resourceTypeInfo) {
+      resourceTypeInfo = { ...resourceTypeInfo, singleton };
+    }
+  }
+  if (!resourceTypeInfo) {
+    // Default to 'Any' type when no provider or type info not found
+    resourceTypeInfo = { type: 'Any', singleton };
+  }
+  return box(value, resourceTypeInfo);
+}
+
+async function detectChoiceValues(
+  item: Record<string, unknown>,
+  base: string,
+  modelProvider?: ModelProvider
+): Promise<ChoiceHit[]> {
+  // Detect properties like baseXxx where Xxx is a type suffix
+  const possible = Object.keys(item).filter((k) => k.startsWith(base) && k !== base && k.length > base.length);
+  if (possible.length === 0) {
+    return [];
+  }
+  const hits: ChoiceHit[] = [];
+  for (const choiceProp of possible) {
+    const value = (item as any)[choiceProp];
+    if (value === null || value === undefined) {
+      continue;
+    }
+    const choiceName = choiceProp.substring(base.length);
+    const primitiveElement = getPrimitiveElement(item, choiceProp);
+    let choiceType: TypeInfo | undefined;
+    if (modelProvider) {
+      // Ask model provider for precise type if available; fallback to using suffix as TypeName
+      const providerType = await modelProvider.getType(choiceName);
+      if (providerType) {
+        choiceType = providerType;
+      }
+    }
+    if (!choiceType) {
+      choiceType = { type: choiceName as TypeName, singleton: !Array.isArray(value) };
+    } else {
+      choiceType = { ...choiceType, singleton: !Array.isArray(value) };
+    }
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        hits.push({ value: v, typeInfo: { ...choiceType, singleton: true }, primitiveElement });
+      }
+    } else {
+      hits.push({ value, typeInfo: choiceType, primitiveElement });
+    }
+  }
+  return hits;
+}
+
+export { getPrimitiveElement, maybeParseTemporal, reboxResource, detectChoiceValues };
+

package/src/interpreter/runtime-context.ts

@@ -0,0 +1,273 @@
+import { Errors } from '../errors';
+import type { RuntimeContext } from '../types';
+import { box } from './boxing';
+
+// Temporal creators used for deterministic caches
+import { createDateTime, createDate, createTime } from '../complex-types/temporal';
+
+export interface BootstrapOptions {
+  modelProvider?: import('../types').ModelProvider;
+  variables?: Record<string, unknown>;
+  now?: Date; // provide deterministic time for tests
+}
+
+/**
+ * Runtime context manager that provides efficient prototype-based context operations
+ * for both interpreter and compiler.
+ */
+export class RuntimeContextManager {
+  /**
+   * Create a new runtime context
+   */
+  static create(input: any[], initialVariables?: Record<string, any>): RuntimeContext {
+    const context = Object.create(null) as RuntimeContext;
+
+    context.input = input;
+    context.focus = input;
+
+    // Create variables object with null prototype to avoid pollution
+    context.variables = Object.create(null);
+
+    // Set root context variables with % prefix
+    context.variables['%context'] = input;
+    context.variables['%resource'] = input;
+    context.variables['%rootResource'] = input;
+
+    // Add any initial variables (with % prefix for user-defined)
+    if (initialVariables) {
+      for (const [key, value] of Object.entries(initialVariables)) {
+        // Add % prefix if not already present and not a special variable
+        const varKey = key.startsWith('$') || key.startsWith('%') ? key : `%${key}`;
+        context.variables[varKey] = value;
+      }
+    }
+
+    return context;
+  }
+
+  /**
+   * Create a child context using prototype inheritance
+   * O(1) operation - no copying needed
+   */
+  static copy(context: RuntimeContext): RuntimeContext {
+    // Create child context with parent as prototype
+    const newContext = Object.create(context) as RuntimeContext;
+
+    // Create child variables that inherit from parent's variables
+    newContext.variables = Object.create(context.variables);
+
+    // input and focus are inherited through prototype chain
+    // Only set them if they need to change
+
+    return newContext;
+  }
+
+  /**
+   * Create a new context with updated input/focus
+   */
+  static withInput(context: RuntimeContext, input: any[], focus?: any[]): RuntimeContext {
+    const newContext = this.copy(context);
+    newContext.input = input;
+    newContext.focus = focus ?? input;
+    return newContext;
+  }
+
+  /**
+   * Set iterator context ($this, $index)
+   */
+  static withIterator(
+    context: RuntimeContext,
+    item: any,
+    index: number
+  ): RuntimeContext {
+    let newContext = this.setVariable(context, '$this', [item], true);
+    newContext = this.setVariable(newContext, '$index', index, true);
+    return newContext;
+  }
+
+  /**
+   * Set a variable in the context (handles both special $ and user % variables)
+   */
+  static setVariable(context: RuntimeContext, name: string, value: any, allowRedefinition: boolean = false): RuntimeContext {
+    // Ensure value is array for consistency (except for special variables like $index)
+    const arrayValue = (name === '$index' || name === '$total') ? value :
+                      Array.isArray(value) ? value : [value];
+
+    // Determine variable key based on prefix
+    let varKey = name;
+    if (!name.startsWith('$') && !name.startsWith('%')) {
+      // No prefix - assume user-defined variable, add % prefix
+      varKey = `%${name}`;
+    }
+
+    // Check for system variables (with or without % prefix)
+    const systemVariables = ['context', 'resource', 'rootResource', 'ucum', 'sct', 'loinc'];
+    const baseVarName = varKey.startsWith('%') ? varKey.substring(1) : varKey;
+    if (systemVariables.includes(baseVarName)) {
+      // Throw error when trying to override system variables
+      throw Errors.invalidOperation(`Cannot override system variable: ${baseVarName}`);
+    }
+
+    // Check if variable already exists (unless redefinition is allowed)
+    // Use 'in' operator to check prototype chain (inherited variables)
+    // Exclude iteration variables ($this, $index, $total) which can be redefined in nested scopes
+    const iterationVariables = ['$this', '$index', '$total'];
+    if (!allowRedefinition && context.variables && varKey in context.variables && !iterationVariables.includes(varKey)) {
+      // Per FHIRPath spec §1.5.10.3: throw error on variable redefinition
+      throw Errors.variableAlreadyDefined(name);
+    }
+
+    // Create new context and set variable
+    const newContext = this.copy(context);
+    newContext.variables[varKey] = arrayValue;
+
+    // Special handling for $this
+    if (varKey === '$this' && Array.isArray(arrayValue) && arrayValue.length === 1) {
+      newContext.input = arrayValue;
+      newContext.focus = arrayValue;
+    }
+
+    return newContext;
+  }
+
+  /**
+   * Get a variable from context
+   */
+  static getVariable(context: RuntimeContext, name: string): any | undefined {
+    // Handle special cases
+    if (name === '$this' || name === '$index' || name === '$total') {
+      return context.variables[name];
+    }
+
+    // Handle environment variables (with or without % prefix)
+    if (name === 'context' || name === '%context') {
+      return context.variables['%context'];
+    }
+    if (name === 'resource' || name === '%resource') {
+      return context.variables['%resource'];
+    }
+    if (name === 'rootResource' || name === '%rootResource') {
+      return context.variables['%rootResource'];
+    }
+
+    // Handle user-defined variables (add % prefix if not present)
+    const varKey = name.startsWith('%') ? name : `%${name}`;
+    // Use 'in' operator to check prototype chain for inherited variables
+    if (varKey in context.variables) {
+      return context.variables[varKey];
+    }
+    return undefined;
+  }
+
+  /**
+   * Bootstrap a runtime context with input, system variables, temporal caches,
+   * optional model provider, and user variables. Applies boxing policy for
+   * FHIR resources when a model provider is available.
+   */
+  static async bootstrapContext(
+    rawInput: unknown | unknown[],
+    options: BootstrapOptions = {}
+  ): Promise<{ context: RuntimeContext; input: any[] }> {
+    const { modelProvider, variables, now } = options;
+
+    // Normalize input to array
+    const inputArray = Array.isArray(rawInput)
+      ? rawInput
+      : rawInput === undefined || rawInput === null
+        ? []
+        : [rawInput];
+
+    // Box input with typeInfo when possible (FHIR resources)
+    let boxedInput = inputArray as any[];
+    if (modelProvider) {
+      boxedInput = await Promise.all(
+        inputArray.map(async (item) => {
+          if (
+            item &&
+            typeof item === 'object' &&
+            'resourceType' in (item as any) &&
+            typeof (item as any).resourceType === 'string'
+          ) {
+            const ti = await modelProvider.getType((item as any).resourceType);
+            return ti ? box(item, ti) : item;
+          }
+          return item;
+        })
+      );
+    }
+
+    // Create context with BOXED input so system vars keep typeInfo
+    let context = RuntimeContextManager.create(boxedInput);
+
+    // Set $this to the boxed input (expressions may rely on $this)
+    context = RuntimeContextManager.setVariable(context, '$this', boxedInput);
+
+    // Pre-cache temporal values (single timestamp for now/today/timeOfDay)
+    const ts = now ?? new Date();
+    const dateTime = createDateTime(
+      ts.getFullYear(),
+      ts.getMonth() + 1,
+      ts.getDate(),
+      ts.getHours(),
+      ts.getMinutes(),
+      ts.getSeconds(),
+      ts.getMilliseconds(),
+      -ts.getTimezoneOffset()
+    );
+    context = RuntimeContextManager.setVariable(
+      context,
+      '__fhirpath_now_cache__',
+      box(dateTime, { type: 'DateTime', singleton: true })
+    );
+
+    const date = createDate(dateTime.year, dateTime.month, dateTime.day);
+    context = RuntimeContextManager.setVariable(
+      context,
+      '__fhirpath_today_cache__',
+      box(date, { type: 'Date', singleton: true })
+    );
+
+    const time = createTime(
+      dateTime.hour!,
+      dateTime.minute,
+      dateTime.second,
+      dateTime.millisecond
+    );
+    context = RuntimeContextManager.setVariable(
+      context,
+      '__fhirpath_timeOfDay_cache__',
+      box(time, { type: 'Time', singleton: true })
+    );
+
+    // Attach model provider to context
+    if (modelProvider) {
+      context.modelProvider = modelProvider;
+    }
+
+    // Add user variables, boxing FHIR resources when modelProvider present
+    if (variables) {
+      for (const [key, rawVal] of Object.entries(variables)) {
+        const values = Array.isArray(rawVal) ? rawVal : [rawVal];
+        const maybeBoxed = modelProvider
+          ? await Promise.all(
+              values.map(async (v) => {
+                if (
+                  v &&
+                  typeof v === 'object' &&
+                  'resourceType' in (v as any) &&
+                  typeof (v as any).resourceType === 'string'
+                ) {
+                  const ti = await modelProvider.getType((v as any).resourceType);
+                  return ti ? box(v, ti) : v;
+                }
+                return v;
+              })
+            )
+          : values;
+        context = RuntimeContextManager.setVariable(context, key, maybeBoxed);
+      }
+    }
+
+    return { context, input: boxedInput };
+  }
+}