@atomic-ehr/fhirpath 0.0.1-canary.69eb286.20250724163205

package/README.md

@@ -0,0 +1,307 @@
+# @atomic-ehr/fhirpath
+
+A TypeScript implementation of FHIRPath, the path-based navigation and extraction language for FHIR (Fast Healthcare Interoperability Resources).
+
+## Installation
+
+```bash
+npm install @atomic-ehr/fhirpath
+# or
+bun add @atomic-ehr/fhirpath
+```
+
+## Quick Start
+
+```typescript
+import fhirpath from '@atomic-ehr/fhirpath';
+
+const patient = {
+  name: [
+    { given: ['John', 'James'], family: 'Doe' },
+    { given: ['Johnny'], family: 'Doe' }
+  ],
+  birthDate: '1990-01-01'
+};
+
+// Simple evaluation
+const givenNames = fhirpath.evaluate('name.given', patient);
+console.log(givenNames); // ['John', 'James', 'Johnny']
+
+// With filtering
+const officialName = fhirpath.evaluate('name.where(use = \'official\').given', patient);
+
+// Arithmetic
+const age = fhirpath.evaluate('today().year() - birthDate.toDateTime().year()', patient);
+```
+
+## API Reference
+
+### Core Functions
+
+#### `parse(expression: string): FHIRPathExpression`
+
+Parses a FHIRPath expression string into an AST (Abstract Syntax Tree).
+
+```typescript
+const expr = fhirpath.parse('Patient.name.given');
+// Use the parsed expression multiple times
+const result1 = fhirpath.evaluate(expr, patient1);
+const result2 = fhirpath.evaluate(expr, patient2);
+```
+
+#### `evaluate(expression: string | FHIRPathExpression, input?: any, context?: EvaluationContext): any[]`
+
+Evaluates a FHIRPath expression against input data.
+
+```typescript
+// Evaluate with string expression
+const names = fhirpath.evaluate('name.family', patient);
+
+// Evaluate with parsed expression
+const expr = fhirpath.parse('name.family');
+const names = fhirpath.evaluate(expr, patient);
+
+// With context variables
+const result = fhirpath.evaluate('%myVar + 5', null, {
+  variables: { myVar: 10 }
+}); // [15]
+```
+
+#### `compile(expression: string | FHIRPathExpression, options?: CompileOptions): CompiledExpression`
+
+Compiles an expression into an optimized JavaScript function for better performance.
+
+```typescript
+const compiled = fhirpath.compile('name.given');
+
+// Use compiled function multiple times
+const names1 = compiled(patient1);
+const names2 = compiled(patient2);
+```
+
+#### `analyze(expression: string | FHIRPathExpression, options?: AnalyzeOptions): AnalysisResult`
+
+Performs static type analysis on an expression.
+
+```typescript
+const analysis = fhirpath.analyze('name.given');
+console.log(analysis.type); // Type information
+console.log(analysis.errors); // Any type errors
+```
+
+### Registry API
+
+The registry provides introspection capabilities for available operations.
+
+```typescript
+// List all available functions
+const functions = fhirpath.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
+
+// Get operation details
+const whereInfo = fhirpath.registry.getOperationInfo('where');
+console.log(whereInfo.syntax.notation); // "where(expression)"
+
+// Validate custom function names
+fhirpath.registry.canRegisterFunction('myFunc'); // true
+fhirpath.registry.canRegisterFunction('where'); // false (built-in)
+```
+
+### 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', (context, input) => {
+    return input.map(x => x * 2);
+  })
+  
+  // Set default variables
+  .withVariable('defaultStatus', 'active')
+  
+  // Add model provider for type information
+  .withModelProvider({
+    resolveType: (typeName) => { /* ... */ },
+    getTypeHierarchy: (typeName) => { /* ... */ },
+    getProperties: (typeName) => { /* ... */ }
+  })
+  
+  .build();
+
+// Use the configured instance
+const result = fp.evaluate('value.double()', { value: [5] }); // [10]
+const status = fp.evaluate('%defaultStatus'); // ['active']
+```
+
+### Custom Functions
+
+Custom functions extend FHIRPath with domain-specific operations:
+
+```typescript
+const fp = FHIRPath.builder()
+  .withCustomFunction('age', (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', (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
+const age = fp.evaluate('birthDate.age()', patient);
+const fullNames = fp.evaluate('name.fullName()', patient);
+```
+
+### Error Handling
+
+All API functions throw `FHIRPathError` for invalid expressions or runtime errors:
+
+```typescript
+import { FHIRPathError, ErrorCode } from '@atomic-ehr/fhirpath';
+
+try {
+  fhirpath.parse('invalid..expression');
+} catch (error) {
+  if (error instanceof FHIRPathError) {
+    console.error(`Error: ${error.message}`);
+    console.error(`Code: ${error.code}`);
+    console.error(`Location: Line ${error.location?.line}, Column ${error.location?.column}`);
+  }
+}
+```
+
+### Type Definitions
+
+The library is fully typed with TypeScript:
+
+```typescript
+import type {
+  FHIRPathExpression,
+  CompiledExpression,
+  EvaluationContext,
+  ModelProvider,
+  CustomFunction,
+  OperationInfo,
+  AnalysisResult
+} from '@atomic-ehr/fhirpath';
+```
+
+## Common Use Cases
+
+### Working with FHIR Resources
+
+```typescript
+const bundle = {
+  resourceType: 'Bundle',
+  entry: [
+    { resource: { resourceType: 'Patient', id: '1', active: true } },
+    { resource: { resourceType: 'Patient', id: '2', active: false } },
+    { resource: { resourceType: 'Observation', status: 'final' } }
+  ]
+};
+
+// Get all patients
+const patients = fhirpath.evaluate(
+  'entry.resource.where(resourceType = \'Patient\')',
+  bundle
+);
+
+// Get active patients
+const activePatients = fhirpath.evaluate(
+  'entry.resource.where(resourceType = \'Patient\' and active = true)',
+  bundle
+);
+
+// Count resources by type
+const patientCount = fhirpath.evaluate(
+  'entry.resource.where(resourceType = \'Patient\').count()',
+  bundle
+); // [2]
+```
+
+### Complex Filtering
+
+```typescript
+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 }
+];
+
+// Find high blood pressure readings
+const highBP = fhirpath.evaluate(
+  'where(code.coding.exists(system = \'loinc\' and code = \'1234\') and value > 130)',
+  observations
+);
+```
+
+### Date Manipulation
+
+```typescript
+const patient = {
+  birthDate: '1990-05-15'
+};
+
+// Check if patient is adult (>= 18 years)
+const isAdult = fhirpath.evaluate(
+  'today() - birthDate.toDateTime() >= 18 years',
+  patient
+);
+```
+
+## Performance Tips
+
+1. **Parse Once, Evaluate Many**: Parse expressions once and reuse the parsed AST:
+   ```typescript
+   const expr = fhirpath.parse('name.given');
+   for (const patient of patients) {
+     const names = fhirpath.evaluate(expr, patient);
+   }
+   ```
+
+2. **Use Compiled Functions**: For expressions evaluated frequently, use compilation:
+   ```typescript
+   const getName = fhirpath.compile('name.given');
+   const results = patients.map(p => getName(p));
+   ```
+
+3. **Builder Instance**: Create a configured instance once and reuse:
+   ```typescript
+   const fp = FHIRPath.builder()
+     .withCustomFunction('myFunc', /* ... */)
+     .build();
+   // Use fp instance throughout your application
+   ```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,225 @@
+interface ASTNode {
+    type: NodeType;
+    position: Position;
+    resultType?: unknown;
+    isSingleton?: boolean;
+}
+interface Position {
+    line: number;
+    column: number;
+    offset: number;
+}
+declare enum NodeType {
+    Identifier = 0,
+    TypeOrIdentifier = 1,// Uppercase identifiers that could be types (Patient, Observation)
+    Binary = 2,// All binary operators including dot
+    Unary = 3,// unary +, -, not
+    Union = 4,// | operator (special handling for multiple operands)
+    Function = 5,// Function calls
+    Literal = 6,// numbers, strings, booleans, dates, null
+    Variable = 7,// $this, $index, $total, %var
+    Collection = 8,// {} empty collection or {expr1, expr2, ...}
+    MembershipTest = 9,// 'is' operator
+    TypeCast = 10,// 'as' operator
+    TypeReference = 11,// Type name in ofType()
+    Index = 12
+}
+
+/**
+ * Type system interfaces for FHIRPath type analysis
+ *
+ * Uses opaque type references to allow flexible implementation
+ */
+type TypeRef = unknown;
+
+/**
+ * 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.
+ */
+interface Context {
+    variables: Record<string, any[]>;
+    env: {
+        $this?: any[];
+        $index?: number;
+        $total?: any[];
+    };
+    $context?: any[];
+    $resource?: any[];
+    $rootResource?: any[];
+    customFunctions?: Record<string, (context: Context, input: any[], ...args: any[]) => any[]>;
+}
+
+interface FHIRPathExpression {
+    readonly ast: ASTNode;
+    evaluate(input?: any, context?: EvaluationContext): any[];
+    compile(options?: CompileOptions): CompiledExpression;
+    analyze(options?: AnalyzeOptions): AnalysisResult;
+    toString(): string;
+}
+interface CompiledExpression {
+    (input?: any, context?: EvaluationContext): any[];
+    readonly source: string;
+}
+interface EvaluationContext {
+    variables?: Record<string, any>;
+    environment?: Record<string, any>;
+    modelProvider?: ModelProvider;
+    customFunctions?: CustomFunctionMap;
+}
+type CustomFunction = (context: Context, input: any[], ...args: any[]) => any[];
+type CustomFunctionMap = Record<string, CustomFunction>;
+interface ModelProvider {
+    resolveType(typeName: string): TypeRef | undefined;
+    getTypeHierarchy(typeName: string): string[];
+    getProperties(typeName: string): PropertyDefinition[];
+    getTypeName?(type: TypeRef): string;
+}
+interface PropertyDefinition {
+    name: string;
+    type: string;
+    isCollection: boolean;
+    isRequired: boolean;
+}
+interface CompileOptions {
+    optimize?: boolean;
+    sourceMap?: boolean;
+}
+interface AnalyzeOptions {
+    modelProvider?: ModelProvider;
+    strict?: boolean;
+}
+interface AnalysisResult {
+    type: TypeRef;
+    isSingleton: boolean;
+    errors: AnalysisError[];
+    warnings: AnalysisWarning[];
+}
+interface AnalysisError {
+    message: string;
+    location?: Location;
+    code: string;
+}
+interface AnalysisWarning {
+    message: string;
+    location?: Location;
+    code: string;
+}
+interface Location {
+    line: number;
+    column: number;
+    offset: number;
+    length: number;
+}
+interface RegistryAPI {
+    listFunctions(): OperationMetadata[];
+    listOperators(): OperationMetadata[];
+    listAllOperations(): OperationMetadata[];
+    hasOperation(name: string): boolean;
+    hasFunction(name: string): boolean;
+    hasOperator(symbol: string): boolean;
+    getOperationInfo(name: string): OperationInfo | undefined;
+    canRegisterFunction(name: string): boolean;
+}
+interface OperationMetadata {
+    name: string;
+    kind: 'function' | 'operator' | 'literal';
+    syntax: {
+        notation: string;
+    };
+}
+interface OperationInfo extends OperationMetadata {
+    signature: {
+        input?: {
+            types?: string[];
+            cardinality?: 'singleton' | 'collection' | 'any';
+        };
+        parameters?: Array<{
+            name: string;
+            types?: string[];
+            cardinality?: 'singleton' | 'collection' | 'any';
+            optional?: boolean;
+        }>;
+        output?: {
+            type?: string | 'dynamic';
+            cardinality?: 'singleton' | 'collection' | 'preserve-input';
+        };
+    };
+    description?: string;
+    examples?: string[];
+}
+interface FHIRPathBuilder {
+    withModelProvider(provider: ModelProvider): this;
+    withCustomFunction(name: string, fn: CustomFunction): this;
+    withVariable(name: string, value: any): this;
+    build(): FHIRPathAPI;
+}
+interface FHIRPathAPI {
+    parse(expression: string): FHIRPathExpression;
+    evaluate(expression: string | FHIRPathExpression, input?: any): any[];
+    compile(expression: string | FHIRPathExpression): CompiledExpression;
+    analyze(expression: string | FHIRPathExpression): AnalysisResult;
+    registry: RegistryAPI;
+}
+
+declare class PublicRegistryAPI implements RegistryAPI {
+    listFunctions(): OperationMetadata[];
+    listOperators(): OperationMetadata[];
+    listAllOperations(): OperationMetadata[];
+    hasOperation(name: string): boolean;
+    hasFunction(name: string): boolean;
+    hasOperator(symbol: string): boolean;
+    getOperationInfo(name: string): OperationInfo | undefined;
+    canRegisterFunction(name: string): boolean;
+    private toMetadata;
+    private toOperationInfo;
+    private extractTypes;
+}
+
+declare function parse(expression: string): FHIRPathExpression;
+declare function evaluate(expression: string | FHIRPathExpression, input?: any, context?: EvaluationContext): any[];
+declare function compile(expression: string | FHIRPathExpression, options?: CompileOptions): CompiledExpression;
+declare function analyze(expression: string | FHIRPathExpression, options?: AnalyzeOptions): AnalysisResult;
+declare const registry: PublicRegistryAPI;
+
+declare class FHIRPath {
+    static builder(): FHIRPathBuilder;
+}
+
+declare enum ErrorCode {
+    PARSE_ERROR = "PARSE_ERROR",
+    SYNTAX_ERROR = "SYNTAX_ERROR",
+    UNEXPECTED_TOKEN = "UNEXPECTED_TOKEN",
+    UNTERMINATED_STRING = "UNTERMINATED_STRING",
+    INVALID_ESCAPE = "INVALID_ESCAPE",
+    TYPE_ERROR = "TYPE_ERROR",
+    TYPE_MISMATCH = "TYPE_MISMATCH",
+    UNKNOWN_TYPE = "UNKNOWN_TYPE",
+    CARDINALITY_ERROR = "CARDINALITY_ERROR",
+    RUNTIME_ERROR = "RUNTIME_ERROR",
+    UNDEFINED_VARIABLE = "UNDEFINED_VARIABLE",
+    UNDEFINED_FUNCTION = "UNDEFINED_FUNCTION",
+    INVALID_ARGUMENT = "INVALID_ARGUMENT",
+    DIVISION_BY_ZERO = "DIVISION_BY_ZERO",
+    ANALYSIS_ERROR = "ANALYSIS_ERROR",
+    UNREACHABLE_CODE = "UNREACHABLE_CODE",
+    AMBIGUOUS_TYPE = "AMBIGUOUS_TYPE"
+}
+declare class FHIRPathError extends Error {
+    code: ErrorCode;
+    location?: Location | undefined;
+    expression?: string | undefined;
+    constructor(message: string, code: ErrorCode, location?: Location | undefined, expression?: string | undefined);
+    toString(): string;
+}
+
+declare const _default: {
+    parse: typeof parse;
+    evaluate: typeof evaluate;
+    compile: typeof compile;
+    analyze: typeof analyze;
+    registry: PublicRegistryAPI;
+};
+
+export { type AnalysisError, type AnalysisResult, type AnalysisWarning, type AnalyzeOptions, type CompileOptions, type CompiledExpression, type CustomFunction, type CustomFunctionMap, ErrorCode, type EvaluationContext, FHIRPath, type FHIRPathAPI, type FHIRPathBuilder, FHIRPathError, type FHIRPathExpression, type Location, type ModelProvider, type OperationInfo, type OperationMetadata, type PropertyDefinition, type RegistryAPI, analyze, compile, _default as default, evaluate, parse, registry };