@atomic-ehr/fhirpath 0.0.1-canary.8687028.20250724113707

package/src/interpreter/types.ts

@@ -0,0 +1,132 @@
+// Core types for FHIRPath interpreter following the stream-processing mental model
+
+/**
+ * The result of evaluating any FHIRPath expression.
+ * Every expression returns a collection and potentially modified context.
+ */
+export interface EvaluationResult {
+  value: any[];  // Always a collection (even single values are collections of one)
+  context: Context;
+}
+
+/**
+ * Context carries variables and environment data parallel to the data stream.
+ * It flows through expressions and can be modified by certain operations.
+ * 
+ * Uses JavaScript prototype chain for efficient inheritance.
+ */
+export interface Context {
+  // User-defined variables (%varName)
+  // Using Record instead of Map for prototype chain compatibility
+  variables: Record<string, any[]>;
+  
+  // Special environment variables
+  env: {
+    $this?: any[];    // Current item in iterator functions
+    $index?: number;  // Current index in iterator functions
+    $total?: any[];   // Accumulator in aggregate function
+  };
+  
+  // Root context variables
+  $context?: any[];      // Original input to the expression
+  $resource?: any[];     // Current resource being processed
+  $rootResource?: any[]; // Top-level resource
+  
+  // Custom functions (if any)
+  customFunctions?: Record<string, (context: Context, input: any[], ...args: any[]) => any[]>;
+}
+
+/**
+ * Error thrown during evaluation with position information
+ */
+export class EvaluationError extends Error {
+  constructor(
+    message: string,
+    public position?: { line: number; column: number; offset: number }
+  ) {
+    super(message);
+    this.name = 'EvaluationError';
+  }
+}
+
+/**
+ * Type information for runtime type checking
+ */
+export interface TypeInfo {
+  namespace: string;  // 'System' or 'FHIR'
+  name: string;       // Type name like 'String', 'Patient'
+  isCollection?: boolean;
+}
+
+/**
+ * Helper type for ensuring we always work with collections
+ */
+export type Collection<T = any> = T[];
+
+/**
+ * Singleton conversion result
+ */
+export type SingletonResult<T = any> = T | undefined;
+
+/**
+ * Helper functions for working with collections
+ */
+export const CollectionUtils = {
+  /**
+   * Convert any value to a collection
+   */
+  toCollection(value: any): any[] {
+    if (value === null || value === undefined) {
+      return [];
+    }
+    return Array.isArray(value) ? value : [value];
+  },
+
+  /**
+   * Apply singleton evaluation rules
+   * @returns The single value or undefined if rules don't apply
+   * @throws Error if multiple items when single expected
+   */
+  toSingleton(collection: any[], expectedType?: string): SingletonResult {
+    if (collection.length === 0) {
+      return undefined; // Empty propagates
+    }
+    
+    if (collection.length === 1) {
+      const value = collection[0];
+      
+      // Rule 2: Collection with one item, expecting Boolean → true
+      if (expectedType === 'boolean' && typeof value !== 'boolean') {
+        return true;
+      }
+      
+      // Rule 1: Collection with one item convertible to expected type → use it
+      return value;
+    }
+    
+    // Rule 4: Multiple items → ERROR
+    throw new EvaluationError(`Expected single value but got ${collection.length} items`);
+  },
+
+  /**
+   * Check if a collection is empty
+   */
+  isEmpty(collection: any[]): boolean {
+    return collection.length === 0;
+  },
+
+  /**
+   * Flatten nested collections
+   */
+  flatten(collection: any[]): any[] {
+    const result: any[] = [];
+    for (const item of collection) {
+      if (Array.isArray(item)) {
+        result.push(...item);
+      } else {
+        result.push(item);
+      }
+    }
+    return result;
+  }
+};

package/src/lexer/char-tables.ts

@@ -0,0 +1,37 @@
+// Character classification lookup table for O(1) checks
+export const CHAR_FLAGS = new Uint8Array(128);
+
+// Bit flags for character properties
+export const FLAG_DIGIT = 1 << 0;
+export const FLAG_ALPHA = 1 << 1;
+export const FLAG_WHITESPACE = 1 << 2;
+export const FLAG_IDENTIFIER_START = 1 << 3;
+export const FLAG_IDENTIFIER_CONT = 1 << 4;
+
+// Initialize lookup table (called once at startup)
+export function initCharTables(): void {
+  // Digits
+  for (let i = 48; i <= 57; i++) {
+    CHAR_FLAGS[i]! |= FLAG_DIGIT | FLAG_IDENTIFIER_CONT;
+  }
+  
+  // Letters
+  for (let i = 65; i <= 90; i++) {
+    CHAR_FLAGS[i]! |= FLAG_ALPHA | FLAG_IDENTIFIER_START | FLAG_IDENTIFIER_CONT;
+  }
+  for (let i = 97; i <= 122; i++) {
+    CHAR_FLAGS[i]! |= FLAG_ALPHA | FLAG_IDENTIFIER_START | FLAG_IDENTIFIER_CONT;
+  }
+  
+  // Underscore
+  CHAR_FLAGS[95]! |= FLAG_IDENTIFIER_START | FLAG_IDENTIFIER_CONT;
+  
+  // Whitespace
+  CHAR_FLAGS[32]! |= FLAG_WHITESPACE;  // space
+  CHAR_FLAGS[9]! |= FLAG_WHITESPACE;   // tab
+  CHAR_FLAGS[10]! |= FLAG_WHITESPACE;  // newline
+  CHAR_FLAGS[13]! |= FLAG_WHITESPACE;  // carriage return
+}
+
+// Initialize the table immediately
+initCharTables();

package/src/lexer/errors.ts

@@ -0,0 +1,31 @@
+import type { Position } from './token';
+
+export class LexerError extends Error {
+  constructor(
+    message: string,
+    public position: Position,
+    public char?: string
+  ) {
+    super(message);
+    this.name = 'LexerError';
+  }
+
+  override toString(): string {
+    const location = `${this.position.line}:${this.position.column}`;
+    const charInfo = this.char ? ` (found '${this.char}')` : '';
+    return `${this.name}: ${this.message} at ${location}${charInfo}`;
+  }
+}
+
+export function formatError(error: LexerError, input: string): string {
+  const lines = input.split('\n');
+  const line = lines[error.position.line - 1] || '';
+  const pointer = ' '.repeat(error.position.column - 1) + '^';
+  
+  return [
+    error.toString(),
+    '',
+    line,
+    pointer
+  ].join('\n');
+}

package/src/lexer/index.ts

@@ -0,0 +1,5 @@
+export { FHIRPathLexer, lex } from './lexer';
+export type { Token, Position } from './token';
+export { TokenType, Channel } from './token';
+export { LexerError, formatError } from './errors';
+export { CHAR_FLAGS, FLAG_DIGIT, FLAG_ALPHA, FLAG_WHITESPACE, FLAG_IDENTIFIER_START, FLAG_IDENTIFIER_CONT } from './char-tables';