@atomic-ehr/fhirpath 0.0.1-canary.0c6931e.20250727185306

package/src/runtime/context.ts

@@ -0,0 +1,158 @@
+
+/**
+ * Unified runtime context that works with both interpreter and compiler.
+ * Uses prototype-based inheritance for efficient context copying.
+ * 
+ * Variable Storage Convention:
+ * - Special variables: $this, $index, $total (prefixed with $)
+ * - Environment variables: %context, %resource, %rootResource (stored with % prefix)
+ * - User-defined variables: stored with % prefix (e.g., %x, %y)
+ */
+export interface RuntimeContext {
+  input: any[];
+  focus: any[];
+  variables: Record<string, any>;
+}
+
+/**
+ * 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 special variable ($this, $index, $total)
+   */
+  static setSpecialVariable(context: RuntimeContext, name: string, value: any): RuntimeContext {
+    const newContext = this.copy(context);
+    const varKey = `$${name}`;
+    newContext.variables[varKey] = value;
+    
+    // Update input/focus for $this
+    if (name === 'this' && Array.isArray(value) && value.length === 1) {
+      newContext.input = value;
+      newContext.focus = value;
+    }
+    
+    return newContext;
+  }
+
+  /**
+   * Set iterator context ($this, $index)
+   */
+  static withIterator(
+    context: RuntimeContext, 
+    item: any, 
+    index: number
+  ): RuntimeContext {
+    let newContext = this.setSpecialVariable(context, 'this', [item]);
+    newContext = this.setSpecialVariable(newContext, 'index', index);
+    return newContext;
+  }
+
+  /**
+   * Set a user-defined variable in the context
+   */
+  static setVariable(context: RuntimeContext, name: string, value: any[], allowRedefinition: boolean = false): RuntimeContext {
+    // Check for system variables
+    const systemVariables = ['context', 'resource', 'rootResource', 'ucum', 'sct', 'loinc'];
+    if (systemVariables.includes(name)) {
+      // Silently return original context for system variable redefinition
+      return context;
+    }
+    
+    // Add % prefix for user-defined variables
+    const varKey = name.startsWith('%') ? name : `%${name}`;
+    
+    // Check if variable already exists (unless redefinition is allowed)
+    if (!allowRedefinition && context.variables && Object.prototype.hasOwnProperty.call(context.variables, varKey)) {
+      // Silently return original context for variable redefinition
+      return context;
+    }
+    
+    const newContext = this.copy(context);
+    newContext.variables[varKey] = value;
+    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}`;
+    return context.variables[varKey];
+  }
+
+}

package/src/runtime/debug-context.ts

@@ -0,0 +1,135 @@
+import type { RuntimeContext } from './context';
+import type { TraceEntry, EvaluationStep, InspectOptions } from '../api/types';
+
+/**
+ * Debug-enabled runtime context that extends RuntimeContext
+ * with debugging capabilities for inspect() function
+ */
+export interface DebugRuntimeContext extends RuntimeContext {
+  debugMode: true;
+  traces: TraceEntry[];
+  steps?: EvaluationStep[];
+  startTime: number;
+  callStack: CallStackEntry[];
+  inspectOptions?: InspectOptions;
+}
+
+interface CallStackEntry {
+  expression: string;
+  nodeType: string;
+  timestamp: number;
+}
+
+/**
+ * Check if a context is a debug context
+ */
+export function isDebugContext(context: RuntimeContext): context is DebugRuntimeContext {
+  return 'debugMode' in context && context.debugMode === true;
+}
+
+/**
+ * Create a debug context from a regular context
+ */
+export function createDebugContext(
+  context: RuntimeContext,
+  options?: InspectOptions
+): DebugRuntimeContext {
+  const debugContext = Object.create(context) as DebugRuntimeContext;
+  debugContext.debugMode = true;
+  debugContext.traces = [];
+  debugContext.startTime = performance.now();
+  debugContext.callStack = [];
+  debugContext.inspectOptions = options;
+  
+  if (options?.recordSteps) {
+    debugContext.steps = [];
+  }
+  
+  return debugContext;
+}
+
+/**
+ * Add a trace entry to the debug context
+ */
+export function addTrace(
+  context: DebugRuntimeContext,
+  name: string,
+  values: any[]
+): void {
+  // Check trace limit
+  if (context.inspectOptions?.maxTraces && 
+      context.traces.length >= context.inspectOptions.maxTraces) {
+    return;
+  }
+  
+  const trace: TraceEntry = {
+    name,
+    values,
+    timestamp: performance.now() - context.startTime,
+    depth: context.callStack.length
+  };
+  
+  context.traces.push(trace);
+}
+
+/**
+ * Record an evaluation step
+ */
+export function recordStep(
+  context: DebugRuntimeContext,
+  nodeType: string,
+  expression: string,
+  input: any[],
+  output: any[]
+): void {
+  if (!context.steps) return;
+  
+  // Check step limit
+  if (context.inspectOptions?.maxSteps && 
+      context.steps.length >= context.inspectOptions.maxSteps) {
+    return;
+  }
+  
+  const stepStart = performance.now();
+  
+  const step: EvaluationStep = {
+    nodeType,
+    expression,
+    input,
+    output,
+    variables: { ...context.variables }, // Snapshot current variables
+    timestamp: stepStart - context.startTime,
+    duration: 0 // Will be calculated when step completes
+  };
+  
+  context.steps.push(step);
+}
+
+/**
+ * Push an entry onto the call stack
+ */
+export function pushCallStack(
+  context: DebugRuntimeContext,
+  expression: string,
+  nodeType: string
+): void {
+  context.callStack.push({
+    expression,
+    nodeType,
+    timestamp: performance.now() - context.startTime
+  });
+}
+
+/**
+ * Pop an entry from the call stack
+ */
+export function popCallStack(context: DebugRuntimeContext): void {
+  context.callStack.pop();
+}
+
+/**
+ * Get the current call stack depth
+ */
+export function getCallDepth(context: DebugRuntimeContext): number {
+  return context.callStack.length;
+}