@atomic-ehr/fhirpath 0.0.2 → 0.0.3

package/README.md

@@ -15,7 +15,7 @@ bun add @atomic-ehr/fhirpath
 ## Quick Start
 
 ```typescript
-import fhirpath from '@atomic-ehr/fhirpath';
+import { evaluate } from '@atomic-ehr/fhirpath';
 
 const patient = {
   name: [
@@ -26,14 +26,20 @@ const patient = {
 };
 
 // Simple evaluation (async)
-const givenNames = await fhirpath.evaluate('name.given', patient);
+const givenNames = await evaluate('name.given', { input: patient });
 console.log(givenNames); // ['John', 'James', 'Johnny']
 
 // With filtering
-const officialName = await fhirpath.evaluate('name.where(use = \'official\').given', patient);
+const officialName = await evaluate(
+  "name.where(use = 'official').given", 
+  { input: patient }
+);
 
-// Arithmetic
-const age = await fhirpath.evaluate('today().year() - birthDate.toDateTime().year()', patient);
+// With variables
+const result = await evaluate('%x + 5', { 
+  variables: { x: 10 } 
+});
+console.log(result); // [15]
 ```
 
 ## API Reference
@@ -47,68 +53,63 @@ const age = await fhirpath.evaluate('today().year() - birthDate.toDateTime().yea
 Parses a FHIRPath expression string into an AST (Abstract Syntax Tree) with optional parser features.
 
 ```typescript
-// Basic parsing (default - collects diagnostics)
-const result = fhirpath.parse('Patient.name.given');
-console.log(result.ast);         // The parsed AST
-console.log(result.diagnostics); // Array of any syntax issues
-console.log(result.hasErrors);   // Boolean indicating if there are errors
+import { parse } from '@atomic-ehr/fhirpath';
 
-// Parse with error on first syntax error (fastest)
-const ast = fhirpath.parseForEvaluation('Patient.name.given');
-// Throws immediately on syntax errors - best for production use
+// Basic parsing (collects diagnostics)
+const result = parse('Patient.name.given');
+console.log(result.ast);         // The parsed AST
+console.log(result.errors);      // Array of any syntax errors
 
-// Parse with advanced features for development tools
-const result = fhirpath.parse('Patient..name', {
-  errorRecovery: true,  // Continue parsing after errors
-  trackRanges: true     // Track source location for each AST node
+// Parse with error recovery for IDE tools
+const result = parse('Patient..name', {
+  mode: 'lsp',           // Enable LSP mode
+  errorRecovery: true    // Continue parsing after errors
 });
-console.log(result.isPartial);  // true - indicates incomplete AST due to errors
-console.log(result.ranges);     // Map of AST nodes to source locations
+console.log(result.errors);  // Contains parse errors
+console.log(result.ast);     // Partial AST with error nodes
 ```
 
 **Parser Options:**
-- `throwOnError?: boolean` - Throw on first error instead of collecting diagnostics (performance mode)
-- `trackRanges?: boolean` - Enable source range tracking for each AST node (useful for IDEs)
-- `errorRecovery?: boolean` - Enable error recovery to continue parsing after errors (useful for IDEs)
-- `maxErrors?: number` - Maximum number of errors to collect before stopping
+- `mode?: 'simple' | 'lsp'` - Parser mode (simple for fast parsing, lsp for IDE features)
+- `errorRecovery?: boolean` - Enable error recovery to continue parsing after errors (LSP mode only)
+- `cursorPosition?: number` - Cursor position for completion support (LSP mode only)
 
-#### `evaluate(expression: string | FHIRPathExpression, input?: any, context?: EvaluationContext): Promise<any[]>`
+#### `evaluate(expression: string, options?: EvaluateOptions): Promise<any[]>`
 
-Evaluates a FHIRPath expression against input data. **Note: This function is now async.**
+Evaluates a FHIRPath expression against input data. **Note: This function is async.**
 
 ```typescript
-// Evaluate with string expression
-const names = await fhirpath.evaluate('name.family', patient);
+import { evaluate } from '@atomic-ehr/fhirpath';
 
-// Evaluate with parsed expression
-const expr = fhirpath.parse('name.family');
-const names = await fhirpath.evaluate(expr, patient);
+// Simple evaluation
+const names = await evaluate('name.family', { input: patient });
 
-// With context variables
-const result = await fhirpath.evaluate('%myVar + 5', null, {
+// With variables
+const result = await evaluate('%myVar + 5', {
   variables: { myVar: 10 }
 }); // [15]
-```
 
-#### `compile(expression: string | FHIRPathExpression, options?: CompileOptions): Promise<CompiledExpression>`
-
-Compiles an expression into an optimized JavaScript function for better performance. **Note: Both compilation and execution are now async.**
-
-```typescript
-const compiled = await fhirpath.compile('name.given');
+// With model provider for type checking
+const modelProvider = new FHIRModelProvider({
+  packages: [{ name: 'hl7.fhir.r4.core', version: '4.0.1' }]
+});
+await modelProvider.initialize();
 
-// Use compiled function multiple times (async)
-const names1 = await compiled(patient1);
-const names2 = await compiled(patient2);
+const typed = await evaluate('Patient.name.given', {
+  input: patient,
+  modelProvider,
+  inputType: { type: 'Patient', singleton: true }
+});
 ```
 
+
 #### `analyze(expression: string, options?: AnalyzeOptions): Promise<AnalysisResult>`
 
 Performs static type analysis on a FHIRPath expression, with optional type checking using a FHIR model provider and error recovery for broken expressions. **Note: This function is now async.**
 
 ```typescript
 // Basic analysis
-const analysis = await fhirpath.analyze('name.given');
+const analysis = await analyze('name.given');
 console.log(analysis.diagnostics); // Array of any issues found
 console.log(analysis.ast); // The analyzed AST with type information
 
@@ -120,13 +121,13 @@ const modelProvider = new FHIRModelProvider({
 });
 await modelProvider.initialize();
 
-const analysis = await fhirpath.analyze('Patient.birthDate.substring(0, 4)', {
+const analysis = await analyze('Patient.birthDate.substring(0, 4)', {
   modelProvider
 });
 // Will report type error: substring() expects String but birthDate is date
 
 // With error recovery for IDE/tooling scenarios
-const analysis = await fhirpath.analyze('Patient.name.', {
+const analysis = await analyze('Patient.name.', {
   errorRecovery: true,  // Won't throw on syntax errors
   modelProvider
 });
@@ -134,11 +135,10 @@ console.log(analysis.diagnostics); // Contains parse error: "Expected identifier
 console.log(analysis.ast); // Partial AST with error nodes
 
 // With input type context
-const analysis = await fhirpath.analyze('name.given', {
+const analysis = await analyze('name.given', {
   modelProvider,
   inputType: { 
     type: 'HumanName',
-    namespace: 'FHIR',
     singleton: false 
   }
 });
@@ -150,15 +150,17 @@ const analysis = await fhirpath.analyze('name.given', {
 - `variables?: Record<string, unknown>` - Variables available in the expression context
 - `inputType?: TypeInfo` - Type information for the input context
 
-#### `inspect(expression: string | FHIRPathExpression, input?: any, context?: EvaluationContext, options?: InspectOptions): Promise<InspectResult>`
+#### `inspect(expression: string, options?: InspectOptions): Promise<InspectResult>`
 
-Evaluates an expression while capturing rich debugging information including traces, execution time, and AST. **Note: This function is now async.**
+Evaluates an expression while capturing rich debugging information including traces, execution time, and AST. **Note: This function is async.**
 
 ```typescript
+import { inspect } from '@atomic-ehr/fhirpath';
+
 // Basic usage - capture trace output
-const result = await fhirpath.inspect(
+const result = await inspect(
   'name.trace("names").given.trace("given names")',
-  patient
+  { input: patient }
 );
 
 console.log(result.result);        // ['John', 'James', 'Johnny']
@@ -173,18 +175,16 @@ result.traces.forEach(trace => {
 });
 
 // With options
-const detailedResult = await fhirpath.inspect(
+const detailedResult = await inspect(
   'Patient.name.where(use = "official")',
-  bundle,
-  undefined,
   { 
-    maxTraces: 100,      // Limit number of traces collected
-    recordSteps: true    // Future: enable step-by-step recording
+    input: bundle,
+    maxTraces: 100      // Limit number of traces collected
   }
 );
 
 // Error handling
-const errorResult = await fhirpath.inspect('invalid.expression()');
+const errorResult = await inspect('invalid.expression()', {});
 if (errorResult.errors) {
   console.log('Errors:', errorResult.errors);
 }
@@ -200,52 +200,29 @@ The `InspectResult` contains:
 - `warnings`: Any warnings (optional)
 - `evaluationSteps`: Step-by-step evaluation details (when enabled)
 
-### Convenience Functions
-
-#### `parseForEvaluation(expression: string): ASTNode`
-
-Parses an expression and returns just the AST, throwing on any syntax errors. This is the most performant option for production use.
-
-```typescript
-try {
-  const ast = fhirpath.parseForEvaluation('Patient.name.given');
-  // Use ast for evaluation
-} catch (error) {
-  console.error('Parse error:', error.message);
-}
-```
-
-#### `validate(expression: string): { valid: boolean; diagnostics: ParseDiagnostic[] }`
-
-Validates a FHIRPath expression syntax without throwing errors.
-
-```typescript
-const validation = fhirpath.validate('Patient..name');
-if (!validation.valid) {
-  console.log('Syntax errors:', validation.diagnostics);
-}
-```
 
 ### Registry API
 
 The registry provides introspection capabilities for available operations.
 
 ```typescript
+import { registry } from '@atomic-ehr/fhirpath';
+
 // List all available functions
-const functions = fhirpath.registry.listFunctions();
+const functions = registry.listFunctions();
 console.log(functions.map(f => f.name)); // ['where', 'select', 'first', ...]
 
-// Check if operation exists
-fhirpath.registry.hasFunction('where'); // true
-fhirpath.registry.hasOperator('+'); // true
+// List all available operators
+const operators = registry.listOperators();
+console.log(operators.map(o => o.name)); // ['+', '-', '*', ...]
 
-// Get operation details
-const whereInfo = fhirpath.registry.getOperationInfo('where');
-console.log(whereInfo.syntax.notation); // "where(expression)"
+// Get function metadata
+const whereFunction = registry.getFunction('where');
+console.log(whereFunction?.signatures); // Function signatures
 
-// Validate custom function names
-fhirpath.registry.canRegisterFunction('myFunc'); // true
-fhirpath.registry.canRegisterFunction('where'); // false (built-in)
+// Get operator metadata
+const plusOperator = registry.getOperator('+');
+console.log(plusOperator?.precedence); // Operator precedence
 ```
 
 ### FHIR Model Provider
@@ -290,73 +267,6 @@ The model provider supports:
 - Extension navigation
 - Full FHIR R4 type system
 
-### Builder Pattern
-
-For advanced configurations, use the builder pattern:
-
-```typescript
-import { FHIRPath } from '@atomic-ehr/fhirpath';
-
-const fp = FHIRPath.builder()
-  // Add custom functions
-  .withCustomFunction('double', async (context, input) => {
-    return input.map(x => x * 2);
-  })
-  
-  // Set default variables
-  .withVariable('defaultStatus', 'active')
-  
-  // Add model provider for type information
-  .withModelProvider({
-    getType: async (typeName) => { /* ... */ },
-    getElementType: async (parentType, propertyName) => { /* ... */ },
-    ofType: (type, typeName) => { /* ... */ },
-    getElementNames: (parentType) => { /* ... */ },
-    getChildrenType: async (parentType) => { /* ... */ }
-  })
-  
-  .build();
-
-// Use the configured instance (async)
-const result = await fp.evaluate('value.double()', { value: [5] }); // [10]
-const status = await fp.evaluate('%defaultStatus'); // ['active']
-```
-
-### Custom Functions
-
-Custom functions extend FHIRPath with domain-specific operations:
-
-```typescript
-const fp = FHIRPath.builder()
-  .withCustomFunction('age', async (context, input) => {
-    // Calculate age from birthDate
-    return input.map(birthDate => {
-      const today = new Date();
-      const birth = new Date(birthDate);
-      let age = today.getFullYear() - birth.getFullYear();
-      const monthDiff = today.getMonth() - birth.getMonth();
-      if (monthDiff < 0 || (monthDiff === 0 && today.getDate() < birth.getDate())) {
-        age--;
-      }
-      return age;
-    });
-  })
-  .withCustomFunction('fullName', async (context, input) => {
-    return input.map(name => {
-      if (name && typeof name === 'object') {
-        const given = Array.isArray(name.given) ? name.given.join(' ') : '';
-        const family = name.family || '';
-        return `${given} ${family}`.trim();
-      }
-      return '';
-    });
-  })
-  .build();
-
-// Use custom functions (async)
-const age = await fp.evaluate('birthDate.age()', patient);
-const fullNames = await fp.evaluate('name.fullName()', patient);
-```
 
 ### Error Handling
 
@@ -382,29 +292,26 @@ The library is fully typed with TypeScript:
 
 ```typescript
 import type {
-  FHIRPathExpression,
-  CompiledExpression,
-  EvaluationContext,
-  ModelProvider,
-  CustomFunction,
-  OperationInfo,
-  AnalysisResult,
-  InspectResult,
-  InspectOptions,
-  // Parser types
-  ParserOptions,
-  ParseResult,
-  ParseDiagnostic,
-  DiagnosticSeverity,
-  TextRange,
   ASTNode,
-  // Analyzer types
-  AnalyzeOptions,
+  AnalysisResult,
   Diagnostic,
+  DiagnosticSeverity,
   TypeInfo,
+  ModelProvider,
+  OperatorDefinition,
+  FunctionDefinition,
+  // Parser types
+  ParseResult,
   // FHIR Model Provider
   FHIRModelProvider,
-  FHIRModelProviderConfig
+  FHIRModelProviderConfig,
+  // Inspect types
+  InspectResult,
+  InspectOptions,
+  ASTMetadata,
+  // Completion types
+  CompletionItem,
+  CompletionOptions
 } from '@atomic-ehr/fhirpath';
 ```
 
@@ -415,13 +322,13 @@ The analyzer supports error recovery mode for IDE and tooling scenarios, allowin
 ```typescript
 // Normal mode - throws on syntax errors
 try {
-  const result = await fhirpath.analyze('Patient.name.');
+  const result = await analyze('Patient.name.');
 } catch (error) {
   console.error('Syntax error:', error.message);
 }
 
 // Error recovery mode - continues analysis despite errors
-const result = await fhirpath.analyze('Patient.name.', {
+const result = await analyze('Patient.name.', {
   errorRecovery: true
 });
 
@@ -437,14 +344,14 @@ console.log(result.diagnostics);
 console.log(result.ast); // Partial AST with error nodes
 
 // Complex broken expression - multiple errors reported
-const result2 = await fhirpath.analyze('Patient.name.where(use = ).given.', {
+const result2 = await analyze('Patient.name.where(use = ).given.', {
   errorRecovery: true,
   modelProvider
 });
 console.log(result2.diagnostics.length); // 2 errors
 
 // Type information is preserved for valid parts
-const result3 = await fhirpath.analyze('5 + 3 * ', {
+const result3 = await analyze('5 + 3 * ', {
   errorRecovery: true
 });
 // Even though expression is incomplete, literals 5 and 3 have type info
@@ -456,6 +363,107 @@ This is particularly useful for:
 - **Code completion**: Analyze partial expressions for context
 - **Linting tools**: Report all issues in a single pass
 
+## Supported Features
+
+### Complete FHIRPath Function Coverage
+
+This implementation supports **100% of FHIRPath functions** as defined in the specification:
+
+#### Arithmetic Functions (13)
+- **Basic**: `+`, `-`, `*`, `/`, `div`, `mod`, `power`
+- **Math**: `abs`, `ceiling`, `floor`, `round`, `sqrt`, `truncate`
+
+#### String Functions (19)
+- **Properties**: `length`
+- **Manipulation**: `substring`, `upper`, `lower`, `trim`, `toChars`, `repeat`
+- **Testing**: `startsWith`, `endsWith`, `contains`, `matches`, `matchesFull`
+- **Search**: `indexOf`, `lastIndexOf`
+- **Transform**: `replace`, `replaceMatches`, `split`, `join`
+
+#### Collection Functions (23)
+- **Filtering**: `where`, `select`, `ofType`
+- **Subsetting**: `first`, `last`, `tail`, `skip`, `take`, `single`
+- **Existence**: `exists`, `empty`, `count`, `distinct`, `isDistinct`
+- **Aggregation**: `all`, `allTrue`, `anyTrue`, `allFalse`, `anyFalse`
+- **Combining**: `combine`, `union`, `intersect`, `exclude`
+- **Membership**: `subsetOf`, `supersetOf`
+
+#### Type Functions (16)
+- **Conversion**: `toBoolean`, `toInteger`, `toLong`, `toDecimal`, `toString`, `toQuantity`
+- **Testing**: `convertsToBoolean`, `convertsToInteger`, `convertsToLong`, `convertsToDecimal`, `convertsToString`, `convertsToQuantity`
+- **Operators**: `is`, `as`
+- **Boundaries**: `highBoundary`, `lowBoundary`
+
+#### Temporal Functions (15)
+- **Current**: `now`, `today`, `timeOfDay`
+- **Extraction**: `dateOf`, `timeOf`, `yearOf`, `monthOf`, `dayOf`, `hourOf`, `minuteOf`, `secondOf`, `millisecondOf`, `timezoneOffsetOf`
+- **Arithmetic**: Full support for date/time arithmetic with durations
+
+#### Logical Operators (6)
+- **Boolean**: `and`, `or`, `xor`, `not`, `implies`
+- **Membership**: `in`, `contains`
+
+#### Comparison Operators (8)
+- **Equality**: `=`, `!=`, `~`, `!~`
+- **Ordering**: `<`, `>`, `<=`, `>=`
+
+#### Utility Functions (7)
+- **Control**: `iif`, `defineVariable`
+- **Navigation**: `children`, `descendants`
+- **Debugging**: `trace`
+- **Advanced**: `aggregate`
+- **Indexing**: Array indexing with `[n]`
+
+### Advanced Features
+
+#### FHIR Model Integration
+- Full R4, R5, STU3, DSTU2 support via `@atomic-ehr/fhir-canonical-manager`
+- Type-aware property navigation
+- Polymorphic type resolution
+- Choice type handling (e.g., `value[x]`)
+- Extension navigation
+
+#### UCUM Quantity Support
+- Complete UCUM unit system
+- Unit conversion and normalization
+- Quantity arithmetic with unit compatibility checking
+- Temporal quantity support (years, months, days, etc.)
+
+#### Temporal Types
+- FHIR Date, DateTime, and Time types
+- Timezone-aware operations
+- Partial date support (e.g., "2023", "2023-05")
+- Date/time boundary calculations
+- Duration arithmetic
+
+#### Variables and Context
+- User-defined variables with `%` prefix
+- Built-in variables: `$this`, `$index`, `$total`
+- System variables: `%context`, `%resource`, `%rootResource`, `%ucum`
+- Scoped variable definitions with `defineVariable()`
+
+#### Type System
+- Complete type inference
+- Union type support
+- Polymorphic function signatures
+- Type coercion rules
+- Singleton vs collection tracking
+
+#### Performance Optimizations
+- Compiled expression mode for repeated evaluations
+- Prototype-based context for minimal allocation
+- Schema and type hierarchy caching
+- Optimized operator dispatch
+- Lazy evaluation where applicable
+
+#### IDE and Tooling Support
+- LSP (Language Server Protocol) integration
+- Context-aware code completions
+- Error recovery for partial expressions
+- Source range tracking for diagnostics
+- Trivia preservation (comments, whitespace)
+- Step-by-step debugging with `inspect()`
+
 ## Common Use Cases
 
 ### Working with FHIR Resources
@@ -471,54 +479,542 @@ const bundle = {
 };
 
 // Get all patients
-const patients = await fhirpath.evaluate(
-  'entry.resource.where(resourceType = \'Patient\')',
-  bundle
+const patients = await evaluate(
+  "entry.resource.where(resourceType = 'Patient')",
+  { input: bundle }
 );
 
 // Get active patients
-const activePatients = await fhirpath.evaluate(
-  'entry.resource.where(resourceType = \'Patient\' and active = true)',
-  bundle
+const activePatients = await evaluate(
+  "entry.resource.where(resourceType = 'Patient' and active = true)",
+  { input: bundle }
 );
 
 // Count resources by type
-const patientCount = await fhirpath.evaluate(
-  'entry.resource.where(resourceType = \'Patient\').count()',
-  bundle
+const patientCount = await evaluate(
+  "entry.resource.where(resourceType = 'Patient').count()",
+  { input: bundle }
 ); // [2]
 ```
 
-### Complex Filtering
+### Complex Filtering and Navigation
+
+**Important Note on Polymorphic Properties**: In FHIR JSON, polymorphic properties like `value[x]` are stored with their type suffix (e.g., `valueQuantity`, `valueString`). However, in FHIRPath expressions, you access them without the suffix and use `ofType()` to filter by type:
+- JSON: `observation.valueQuantity.value`
+- FHIRPath: `observation.value.ofType(Quantity).value`
 
 ```typescript
+// Blood pressure observations (FHIR Observation resources)
 const observations = [
-  { code: { coding: [{ system: 'loinc', code: '1234' }] }, value: 140 },
-  { code: { coding: [{ system: 'loinc', code: '1234' }] }, value: 120 },
-  { code: { coding: [{ system: 'loinc', code: '5678' }] }, value: 98.6 }
+  { 
+    resourceType: 'Observation',
+    code: { coding: [{ system: 'loinc', code: '85354-9' }] }, 
+    valueQuantity: { value: 140, unit: 'mm[Hg]' },
+    effectiveDateTime: '2024-01-15T10:30:00Z'  // In FHIR JSON, stored as effectiveDateTime
+  },
+  { 
+    resourceType: 'Observation',
+    code: { coding: [{ system: 'loinc', code: '85354-9' }] }, 
+    valueQuantity: { value: 120, unit: 'mm[Hg]' },
+    effectiveDateTime: '2024-01-14T09:00:00Z'  // In FHIR JSON, stored as effectiveDateTime
+  },
+  { 
+    resourceType: 'Observation',
+    code: { coding: [{ system: 'loinc', code: '8310-5' }] }, 
+    valueQuantity: { value: 98.6, unit: '[degF]' },
+    effectiveDateTime: '2024-01-15T10:30:00Z'  // In FHIR JSON, stored as effectiveDateTime
+  }
 ];
 
-// Find high blood pressure readings
-const highBP = await fhirpath.evaluate(
-  'where(code.coding.exists(system = \'loinc\' and code = \'1234\') and value > 130)',
-  observations
+// Find high blood pressure readings (systolic > 130)
+// Note: In FHIRPath, polymorphic properties like value[x] are accessed directly as 'value'
+const highBP = await evaluate(
+  `where(code.coding.exists(system = 'loinc' and code = '85354-9') 
+    and value.ofType(Quantity).value > 130)`,
+  { input: observations }
+);
+
+// Get all observation values with units (for Quantity types)
+const valuesWithUnits = await evaluate(
+  "value.ofType(Quantity).select(value.toString() + ' ' + unit)",
+  { input: observations }
+); // ['140 mm[Hg]', '120 mm[Hg]', '98.6 [degF]']
+
+// Find most recent observation
+// Note: effective[x] can be DateTime, Period, Timing, or Instant
+const mostRecent = await evaluate(
+  'where(effective.ofType(dateTime) = effective.ofType(dateTime).max()).first()',
+  { input: observations }
 );
 ```
 
-### Date Manipulation
+### Patient Demographics and Identifiers
 
 ```typescript
 const patient = {
-  birthDate: '1990-05-15'
+  resourceType: 'Patient',
+  identifier: [
+    { system: 'http://hospital.org/mrn', value: 'MRN-12345' },
+    { system: 'http://hl7.org/fhir/sid/us-ssn', value: '123-45-6789' }
+  ],
+  name: [
+    { 
+      use: 'official', 
+      family: 'Smith', 
+      given: ['John', 'Robert'],
+      prefix: ['Dr']
+    },
+    { 
+      use: 'nickname', 
+      given: ['Johnny'] 
+    }
+  ],
+  telecom: [
+    { system: 'phone', value: '555-0123', use: 'home' },
+    { system: 'email', value: 'john@example.com', use: 'work' }
+  ],
+  birthDate: '1980-05-15',
+  address: [
+    {
+      use: 'home',
+      line: ['123 Main St', 'Apt 4B'],
+      city: 'Boston',
+      state: 'MA',
+      postalCode: '02101'
+    }
+  ]
 };
 
-// Check if patient is adult (>= 18 years)
-const isAdult = await fhirpath.evaluate(
-  'today() - birthDate.toDateTime() >= 18 years',
-  patient
+// Get patient's MRN
+const mrn = await evaluate(
+  "identifier.where(system = 'http://hospital.org/mrn').value",
+  { input: patient }
+); // ['MRN-12345']
+
+// Get full official name
+const fullName = await evaluate(
+  "name.where(use = 'official').select((prefix | {}).first() + ' ' + given.join(' ') + ' ' + family)",
+  { input: patient }
+); // ['Dr John Robert Smith']
+
+// Get all phone numbers
+const phones = await evaluate(
+  "telecom.where(system = 'phone').value",
+  { input: patient }
+); // ['555-0123']
+
+// Get home address as single line
+const address = await evaluate(
+  "address.where(use = 'home').select(line.join(', ') + ', ' + city + ', ' + state + ' ' + postalCode)",
+  { input: patient }
+); // ['123 Main St, Apt 4B, Boston, MA 02101']
+
+// Calculate age
+const age = await evaluate(
+  "today().toString().substring(0, 4).toInteger() - birthDate.substring(0, 4).toInteger()",
+  { input: patient }
+); // [44] (as of 2024)
+```
+
+### Medication and Dosage Calculations
+
+```typescript
+const medicationRequest = {
+  resourceType: 'MedicationRequest',
+  medication: {
+    coding: [{ 
+      system: 'http://www.nlm.nih.gov/research/umls/rxnorm',
+      code: '1049502',
+      display: 'Acetaminophen 325 MG Oral Tablet'
+    }]
+  },
+  dosageInstruction: [
+    {
+      timing: {
+        repeat: {
+          frequency: 2,
+          period: 1,
+          periodUnit: 'd'
+        }
+      },
+      doseAndRate: [{
+        doseQuantity: {
+          value: 650,
+          unit: 'mg',
+          system: 'http://unitsofmeasure.org'
+        }
+      }]
+    }
+  ],
+  dispenseRequest: {
+    quantity: {
+      value: 60,
+      unit: 'TAB'
+    },
+    expectedSupplyDuration: {
+      value: 30,
+      unit: 'd'
+    }
+  }
+};
+
+// Get medication name (medication[x] can be CodeableConcept or Reference)
+const medName = await evaluate(
+  'medication.ofType(CodeableConcept).coding.display.first()',
+  { input: medicationRequest }
+); // ['Acetaminophen 325 MG Oral Tablet']
+
+// Calculate daily dose
+const dailyDose = await evaluate(
+  'dosageInstruction.first().doseAndRate.doseQuantity.value * dosageInstruction.first().timing.repeat.frequency',
+  { input: medicationRequest }
+); // [1300] (650mg * 2 times per day)
+
+// Get supply duration
+const duration = await evaluate(
+  "dispenseRequest.expectedSupplyDuration.value.toString() + ' ' + dispenseRequest.expectedSupplyDuration.unit",
+  { input: medicationRequest }
+); // ['30 d']
+```
+
+### Date and Time Operations
+
+```typescript
+const appointment = {
+  resourceType: 'Appointment',
+  start: '2024-03-15T14:30:00Z',
+  end: '2024-03-15T15:00:00Z',
+  created: '2024-03-01T10:00:00Z',
+  participant: [
+    {
+      actor: { reference: 'Patient/123' },
+      required: 'required',
+      status: 'accepted'
+    },
+    {
+      actor: { reference: 'Practitioner/456' },
+      required: 'required',
+      status: 'accepted'
+    }
+  ]
+};
+
+// Calculate appointment duration in minutes
+const duration = await evaluate(
+  '(end - start) / 1 minute',
+  { input: appointment }
+); // [30]
+
+// Check if appointment is in the future
+const isFuture = await evaluate(
+  'start > now()',
+  { input: appointment }
+);
+
+// Get appointment date only
+const appointmentDate = await evaluate(
+  'start.toString().substring(0, 10)',
+  { input: appointment }
+); // ['2024-03-15']
+
+// Check if all participants accepted
+const allAccepted = await evaluate(
+  "participant.all(status = 'accepted')",
+  { input: appointment }
+); // [true]
+
+// Days until appointment
+const daysUntil = await evaluate(
+  '(start - now()) / 1 day',
+  { input: appointment }
 );
 ```
 
+### Laboratory Results Analysis
+
+```typescript
+const labResults = {
+  resourceType: 'Bundle',
+  entry: [
+    {
+      resource: {
+        resourceType: 'Observation',
+        code: { 
+          coding: [{ 
+            system: 'http://loinc.org',
+            code: '2951-2',
+            display: 'Sodium'
+          }]
+        },
+        valueQuantity: { value: 145, unit: 'mmol/L' },  // In actual FHIR, this is stored as valueQuantity
+        referenceRange: [{
+          low: { value: 136, unit: 'mmol/L' },
+          high: { value: 145, unit: 'mmol/L' }
+        }],
+        status: 'final',
+        effectiveDateTime: '2024-01-15T08:00:00Z'  // In FHIR JSON, stored as effectiveDateTime
+      }
+    },
+    {
+      resource: {
+        resourceType: 'Observation',
+        code: { 
+          coding: [{ 
+            system: 'http://loinc.org',
+            code: '2823-3',
+            display: 'Potassium'
+          }]
+        },
+        valueQuantity: { value: 5.5, unit: 'mmol/L' },  // In actual FHIR, this is stored as valueQuantity
+        referenceRange: [{
+          low: { value: 3.5, unit: 'mmol/L' },
+          high: { value: 5.0, unit: 'mmol/L' }
+        }],
+        status: 'final',
+        effectiveDateTime: '2024-01-15T08:00:00Z'  // In FHIR JSON, stored as effectiveDateTime
+      }
+    }
+  ]
+};
+
+// Find all abnormal results (outside reference range)
+const abnormalResults = await evaluate(
+  `entry.resource.where(
+    value.ofType(Quantity).value < referenceRange.low.value or 
+    value.ofType(Quantity).value > referenceRange.high.value
+  )`,
+  { input: labResults }
+);
+
+// Get test names and values
+const testSummary = await evaluate(
+  `entry.resource.select(
+    code.coding.display.first() + ': ' + 
+    value.ofType(Quantity).value.toString() + ' ' + 
+    value.ofType(Quantity).unit
+  )`,
+  { input: labResults }
+); // ['Sodium: 145 mmol/L', 'Potassium: 5.5 mmol/L']
+
+// Find critical values (e.g., potassium > 5.0)
+const criticalValues = await evaluate(
+  `entry.resource.where(
+    code.coding.exists(code = '2823-3') and 
+    value.ofType(Quantity).value > 5.0
+  )`,
+  { input: labResults }
+);
+```
+
+### Allergy and Intolerance Checking
+
+```typescript
+const allergyIntolerance = {
+  resourceType: 'AllergyIntolerance',
+  clinicalStatus: {
+    coding: [{
+      system: 'http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical',
+      code: 'active'
+    }]
+  },
+  verificationStatus: {
+    coding: [{
+      system: 'http://terminology.hl7.org/CodeSystem/allergyintolerance-verification',
+      code: 'confirmed'
+    }]
+  },
+  type: 'allergy',
+  category: ['medication'],
+  criticality: 'high',
+  code: {
+    coding: [{
+      system: 'http://www.nlm.nih.gov/research/umls/rxnorm',
+      code: '7980',
+      display: 'Penicillin'
+    }]
+  },
+  reaction: [
+    {
+      substance: {
+        coding: [{
+          system: 'http://www.nlm.nih.gov/research/umls/rxnorm',
+          code: '7980',
+          display: 'Penicillin'
+        }]
+      },
+      manifestation: [
+        {
+          coding: [{
+            system: 'http://snomed.info/sct',
+            code: '39579001',
+            display: 'Anaphylaxis'
+          }]
+        },
+        {
+          coding: [{
+            system: 'http://snomed.info/sct',
+            code: '271807003',
+            display: 'Rash'
+          }]
+        }
+      ],
+      severity: 'severe'
+    }
+  ]
+};
+
+// Check if allergy is active and confirmed
+const isActiveConfirmed = await evaluate(
+  "clinicalStatus.coding.code = 'active' and verificationStatus.coding.code = 'confirmed'",
+  { input: allergyIntolerance }
+); // [true]
+
+// Get all reaction manifestations
+const manifestations = await evaluate(
+  'reaction.manifestation.coding.display',
+  { input: allergyIntolerance }
+); // ['Anaphylaxis', 'Rash']
+
+// Check for severe reactions
+const hasSevereReaction = await evaluate(
+  "reaction.exists(severity = 'severe')",
+  { input: allergyIntolerance }
+); // [true]
+
+// Get allergen name
+const allergen = await evaluate(
+  'code.coding.display.first()',
+  { input: allergyIntolerance }
+); // ['Penicillin']
+```
+
+### Bundle Processing and Resource Extraction
+
+```typescript
+const bundle = {
+  resourceType: 'Bundle',
+  type: 'searchset',
+  total: 3,
+  entry: [
+    {
+      fullUrl: 'http://example.org/Patient/123',
+      resource: {
+        resourceType: 'Patient',
+        id: '123',
+        name: [{ family: 'Smith', given: ['John'] }],
+        birthDate: '1980-01-01'
+      }
+    },
+    {
+      fullUrl: 'http://example.org/Encounter/456',
+      resource: {
+        resourceType: 'Encounter',
+        id: '456',
+        status: 'finished',
+        class: { code: 'IMP' },
+        subject: { reference: 'Patient/123' }
+      }
+    },
+    {
+      fullUrl: 'http://example.org/Condition/789',
+      resource: {
+        resourceType: 'Condition',
+        id: '789',
+        clinicalStatus: {
+          coding: [{ code: 'active' }]
+        },
+        code: {
+          coding: [{
+            system: 'http://snomed.info/sct',
+            code: '44054006',
+            display: 'Diabetes mellitus type 2'
+          }]
+        },
+        subject: { reference: 'Patient/123' },
+        onsetDateTime: '2015-06-15'  // In FHIR JSON, stored as onsetDateTime
+      }
+    }
+  ]
+};
+
+// Extract all patients
+const patients = await evaluate(
+  "entry.resource.where(resourceType = 'Patient')",
+  { input: bundle }
+);
+
+// Get all active conditions
+const activeConditions = await evaluate(
+  "entry.resource.where(resourceType = 'Condition' and clinicalStatus.coding.code = 'active')",
+  { input: bundle }
+);
+
+// Count resources by type
+const patientCount = await evaluate(
+  "entry.resource.where(resourceType = 'Patient').count()",
+  { input: bundle }
+); // [1]
+
+// Get all resources for a specific patient
+const patientResources = await evaluate(
+  "entry.resource.where(subject.reference = 'Patient/123')",
+  { input: bundle }
+);
+
+// Extract condition names
+const conditions = await evaluate(
+  "entry.resource.where(resourceType = 'Condition').code.coding.display",
+  { input: bundle }
+); // ['Diabetes mellitus type 2']
+```
+
+### Using Variables and Advanced Control Flow
+
+```typescript
+// Using defineVariable for complex calculations
+const result = await evaluate(
+  `name
+    .defineVariable('fullName', given.first() + ' ' + family)
+    .select(%fullName + ' (' + use + ')')`,
+  {
+    input: {
+      name: [
+        { use: 'official', given: ['John'], family: 'Doe' },
+        { use: 'nickname', given: ['Johnny'], family: 'D' }
+      ]
+    }
+  }
+); // ['John Doe (official)', 'Johnny D (nickname)']
+
+// Using aggregate for running calculations
+const sum = await evaluate(
+  'aggregate(0, $total + $this)',
+  { input: [1, 2, 3, 4, 5] }
+); // [15]
+
+// Using iif for conditional logic
+const ageGroup = await evaluate(
+  "iif(age < 18, 'child', iif(age < 65, 'adult', 'senior'))",
+  { input: { age: 70 } }
+); // ['senior']
+
+// Complex aggregation with variables
+const stats = await evaluate(
+  `defineVariable('values', value)
+    .defineVariable('sum', %values.aggregate(0, $total + $this))
+    .defineVariable('count', %values.count())
+    .defineVariable('avg', %sum / %count)
+    .select('Average: ' + %avg.toString())`,
+  {
+    input: [
+      { value: 10 },
+      { value: 20 },
+      { value: 30 }
+    ]
+  }
+); // ['Average: 20']
+```
+
 ### Debugging Expressions
 
 Use the `inspect()` function to debug complex FHIRPath expressions:
@@ -532,14 +1028,14 @@ const bundle = {
 };
 
 // Debug a complex expression with traces
-const result = await fhirpath.inspect(
+const result = await inspect(
   `entry.resource
     .trace('all resources')
     .where(resourceType = 'Patient')
     .trace('patients only')
     .name.given
     .trace('all given names')`,
-  bundle
+  { input: bundle }
 );
 
 // Analyze the execution
@@ -562,48 +1058,30 @@ result.traces.forEach(trace => {
 
 ## Performance Tips
 
-1. **Use Fast Parsing for Production**: When parsing expressions in production, use `parseForEvaluation()` or enable `throwOnError`:
-   ```typescript
-   // Fastest - throws on first error
-   const ast = fhirpath.parseForEvaluation('name.given');
-   
-   // Or use throwOnError option
-   const result = fhirpath.parse('name.given', { throwOnError: true });
-   ```
-
-2. **Parse Once, Evaluate Many**: Parse expressions once and reuse the parsed AST:
+1. **Reuse Parsed Expressions**: Parse expressions once when possible:
    ```typescript
-   const expr = fhirpath.parse('name.given');
-   for (const patient of patients) {
-     const names = await fhirpath.evaluate(expr, patient);
-   }
+   const parsed = parse('name.given');
+   // Use parsed.ast for multiple evaluations
    ```
 
-3. **Use Compiled Functions**: For expressions evaluated frequently, use compilation:
+2. **Cache Analysis Results**: For repeated type checking, cache the analyzed AST:
    ```typescript
-   const getName = await fhirpath.compile('name.given');
-   const results = await Promise.all(patients.map(p => getName(p)));
+   const analysis = await analyze('name.given', { modelProvider });
+   // Reuse analysis.ast which includes type information
    ```
 
-4. **Disable Unnecessary Parser Features**: Only enable parser features you need:
+3. **Use Simple Parser Mode**: For production, use simple parsing:
    ```typescript
-   // For development tools (IDEs, linters)
-   const result = fhirpath.parse(expr, {
-     errorRecovery: true,  // Only if you need partial ASTs
-     trackRanges: true     // Only if you need source mapping
-   });
+   // Simple mode (default) - fastest
+   const result = parse('name.given');
    
-   // For production (fastest)
-   const ast = fhirpath.parseForEvaluation(expr);
+   // LSP mode - only for IDE tools
+   const result = parse('name.given', {
+     mode: 'lsp',
+     errorRecovery: true
+   });
    ```
 
-5. **Builder Instance**: Create a configured instance once and reuse:
-   ```typescript
-   const fp = FHIRPath.builder()
-     .withCustomFunction('myFunc', /* ... */)
-     .build();
-   // Use fp instance throughout your application
-   ```
 
 ## Contributing