@atomic-ehr/fhirpath 0.0.1-canary.35b105d.20250724165800

package/src/api/expression.ts

@@ -0,0 +1,152 @@
+import type { ASTNode } from '../parser/ast';
+import type { 
+  FHIRPathExpression as IFHIRPathExpression,
+  CompiledExpression,
+  EvaluationContext,
+  CompileOptions,
+  AnalyzeOptions,
+  AnalysisResult
+} from './types';
+import { Interpreter } from '../interpreter/interpreter';
+import { Compiler } from '../compiler/compiler';
+import { analyzeFHIRPath } from '../analyzer/analyzer';
+import { RuntimeContextManager } from '../runtime/context';
+import { pprint } from '../parser/pprint';
+
+export class FHIRPathExpression implements IFHIRPathExpression {
+  constructor(
+    public readonly ast: ASTNode,
+    private readonly originalExpression: string
+  ) {}
+  
+  evaluate(input?: any, context?: EvaluationContext): any[] {
+    const interpreter = new Interpreter();
+    const inputArray = input === undefined ? [] : Array.isArray(input) ? input : [input];
+    const ctx = this.createContext(context, inputArray);
+    
+    const result = interpreter.evaluate(this.ast, inputArray, ctx);
+    
+    return result.value;
+  }
+  
+  compile(options?: CompileOptions): CompiledExpression {
+    const compiler = new Compiler();
+    const compiled = compiler.compile(this.ast);
+    
+    // Create the compiled function
+    const fn = (input?: any, context?: EvaluationContext): any[] => {
+      const inputArray = input === undefined ? [] : Array.isArray(input) ? input : [input];
+      const ctx = this.createContext(context, inputArray);
+      
+      return compiled.fn({
+        input: inputArray,
+        focus: inputArray,
+        env: ctx.env || {}
+      });
+    };
+    
+    // Add source property
+    Object.defineProperty(fn, 'source', {
+      value: options?.sourceMap ? this.originalExpression : this.toString(),
+      writable: false,
+      enumerable: true
+    });
+    
+    return fn as CompiledExpression;
+  }
+  
+  analyze(options?: AnalyzeOptions): AnalysisResult {
+    try {
+      // Create analyzer-compatible model provider
+      const analyzerModelProvider = options?.modelProvider ? {
+        resolveType: options.modelProvider.resolveType.bind(options.modelProvider),
+        getPropertyType: (type: any, propName: string) => {
+          const props = options.modelProvider!.getProperties(options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(type) : String(type));
+          const prop = props.find(p => p.name === propName);
+          if (!prop) return undefined;
+          return {
+            type: options.modelProvider!.resolveType(prop.type),
+            isSingleton: !prop.isCollection
+          };
+        },
+        isAssignable: (from: any, to: any) => {
+          const hierarchy = options.modelProvider!.getTypeHierarchy(options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(from) : String(from));
+          const toName = options.modelProvider!.getTypeName ? options.modelProvider!.getTypeName(to) : String(to);
+          return hierarchy.includes(toName);
+        },
+        getTypeName: (type: any) => String(type)
+      } : {
+        resolveType: () => undefined,
+        getPropertyType: () => undefined,
+        isAssignable: () => false,
+        getTypeName: () => 'unknown'
+      };
+      
+      const result = analyzeFHIRPath(this.ast, analyzerModelProvider);
+      
+      return {
+        type: result.resultType || { kind: 'unknown' },
+        isSingleton: result.resultIsSingleton || false,
+        errors: result.diagnostics.filter(d => d.severity === 'error').map(d => ({
+          message: d.message,
+          location: d.position ? {
+            line: d.position.line,
+            column: d.position.column,
+            offset: d.position.offset,
+            length: 1 // We don't have length info in Position
+          } : undefined,
+          code: 'ANALYSIS_ERROR'
+        })),
+        warnings: result.diagnostics.filter(d => d.severity === 'warning').map(d => ({
+          message: d.message,
+          location: d.position ? {
+            line: d.position.line,
+            column: d.position.column,
+            offset: d.position.offset,
+            length: 1
+          } : undefined,
+          code: 'ANALYSIS_WARNING'
+        }))
+      };
+    } catch (error) {
+      return {
+        type: { kind: 'unknown' },
+        isSingleton: false,
+        errors: [{
+          message: error instanceof Error ? error.message : String(error),
+          code: 'ANALYSIS_ERROR'
+        }],
+        warnings: []
+      };
+    }
+  }
+  
+  toString(): string {
+    return pprint(this.ast);
+  }
+  
+  private createContext(evalContext?: EvaluationContext, input: any[] = []) {
+    let ctx = RuntimeContextManager.create(input);
+    
+    if (evalContext?.variables) {
+      for (const [name, value] of Object.entries(evalContext.variables)) {
+        ctx = RuntimeContextManager.setVariable(ctx, name, Array.isArray(value) ? value : [value]);
+      }
+    }
+    
+    if (evalContext?.environment) {
+      // Environment variables would need to be handled through a different mechanism
+      // as the context.env only supports specific FHIRPath environment variables
+      // TODO: Consider how to handle custom environment variables
+    }
+    
+    // Store custom functions in context for interpreter to access
+    if (evalContext?.customFunctions) {
+      // TODO: Custom functions need to be implemented through the registry
+      // For now, we'll store them in env
+      (ctx as any).customFunctions = evalContext.customFunctions;
+    }
+    
+    return ctx;
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,57 @@
+import type {
+  FHIRPathExpression,
+  CompiledExpression,
+  EvaluationContext,
+  CompileOptions,
+  AnalyzeOptions,
+  AnalysisResult
+} from './types';
+import { FHIRPathParser } from '../parser/parser';
+import { FHIRPathExpression as Expression } from './expression';
+import { FHIRPathError, parseError } from './errors';
+import { publicRegistry } from './registry';
+
+// Parse expression into AST
+export function parse(expression: string): FHIRPathExpression {
+  try {
+    const parser = new FHIRPathParser(expression);
+    const ast = parser.parse();
+    return new Expression(ast, expression);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw parseError(error.message, undefined, expression);
+    }
+    throw parseError(String(error), undefined, expression);
+  }
+}
+
+// Evaluate expression directly
+export function evaluate(
+  expression: string | FHIRPathExpression,
+  input?: any,
+  context?: EvaluationContext
+): any[] {
+  const expr = typeof expression === 'string' ? parse(expression) : expression;
+  return expr.evaluate(input, context);
+}
+
+// Compile to optimized function
+export function compile(
+  expression: string | FHIRPathExpression,
+  options?: CompileOptions
+): CompiledExpression {
+  const expr = typeof expression === 'string' ? parse(expression) : expression;
+  return expr.compile(options);
+}
+
+// Analyze expression for validation
+export function analyze(
+  expression: string | FHIRPathExpression,
+  options?: AnalyzeOptions
+): AnalysisResult {
+  const expr = typeof expression === 'string' ? parse(expression) : expression;
+  return expr.analyze(options);
+}
+
+// Default registry instance
+export const registry = publicRegistry;

package/src/api/registry.ts

@@ -0,0 +1,128 @@
+import type { 
+  RegistryAPI, 
+  OperationMetadata, 
+  OperationInfo 
+} from './types';
+import { Registry } from '../registry/registry';
+import type { Operation } from '../registry/types';
+
+export class PublicRegistryAPI implements RegistryAPI {
+  listFunctions(): OperationMetadata[] {
+    return Registry.getAllFunctions().map(op => this.toMetadata(op));
+  }
+  
+  listOperators(): OperationMetadata[] {
+    const operators = [
+      ...Registry.getOperatorsByForm('infix'),
+      ...Registry.getOperatorsByForm('prefix'),
+      ...Registry.getOperatorsByForm('postfix')
+    ];
+    return operators.map(op => this.toMetadata(op));
+  }
+  
+  listAllOperations(): OperationMetadata[] {
+    return Registry.getAllOperations().map(op => this.toMetadata(op));
+  }
+  
+  hasOperation(name: string): boolean {
+    return Registry.get(name) !== undefined;
+  }
+  
+  hasFunction(name: string): boolean {
+    const op = Registry.get(name);
+    return op !== undefined && op.kind === 'function';
+  }
+  
+  hasOperator(symbol: string): boolean {
+    const op = Registry.get(symbol);
+    return op !== undefined && op.kind === 'operator';
+  }
+  
+  getOperationInfo(name: string): OperationInfo | undefined {
+    const op = Registry.get(name);
+    if (!op) return undefined;
+    
+    return this.toOperationInfo(op);
+  }
+  
+  canRegisterFunction(name: string): boolean {
+    // Check if name is valid and not already taken
+    if (!name || typeof name !== 'string') return false;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) return false;
+    
+    // Check if already exists as built-in
+    return !this.hasOperation(name);
+  }
+  
+  private toMetadata(op: Operation): OperationMetadata {
+    return {
+      name: op.name,
+      kind: op.kind,
+      syntax: {
+        notation: op.syntax.notation
+      }
+    };
+  }
+  
+  private toOperationInfo(op: Operation): OperationInfo {
+    const info: OperationInfo = {
+      ...this.toMetadata(op),
+      signature: {}
+    };
+    
+    // Add input signature for functions
+    if (op.kind === 'function' && op.signature.input) {
+      info.signature.input = {
+        types: this.extractTypes(op.signature.input.types),
+        cardinality: op.signature.input.cardinality
+      };
+    }
+    
+    // Add parameters
+    if ('parameters' in op.signature && op.signature.parameters && op.signature.parameters.length > 0) {
+      info.signature.parameters = op.signature.parameters.map((param: any) => ({
+        name: param.name,
+        types: this.extractTypes(param.types),
+        cardinality: param.cardinality,
+        optional: param.optional
+      }));
+    }
+    
+    // Add output signature
+    if (op.signature.output) {
+      info.signature.output = {
+        type: typeof op.signature.output.type === 'string' 
+          ? op.signature.output.type 
+          : 'dynamic',
+        cardinality: typeof op.signature.output.cardinality === 'string'
+          ? (op.signature.output.cardinality === 'all-singleton' ? 'singleton' : op.signature.output.cardinality as any)
+          : undefined
+      };
+    }
+    
+    // Add description if available (for now, operations don't have description in the type)
+    // TODO: Add description to Operation type if needed
+    
+    // Add examples if available (for now, operations don't have examples in the type)
+    // TODO: Add examples to Operation type if needed
+    
+    return info;
+  }
+  
+  private extractTypes(constraint?: any): string[] | undefined {
+    if (!constraint) return undefined;
+    
+    if (constraint.kind === 'primitive' || constraint.kind === 'class') {
+      return constraint.types;
+    } else if (constraint.kind === 'union' && constraint.types) {
+      return constraint.types;
+    } else if (constraint.kind === 'any') {
+      return ['any'];
+    }
+    
+    return undefined;
+  }
+}
+
+// Singleton instance
+export const publicRegistry = new PublicRegistryAPI();

package/src/api/types.ts

@@ -0,0 +1,154 @@
+import type { ASTNode } from '../parser/ast';
+import type { TypeRef } from '../analyzer/types';
+import type { Context } from '../interpreter/types';
+
+// Core expression interface
+export interface FHIRPathExpression {
+  readonly ast: ASTNode;
+  evaluate(input?: any, context?: EvaluationContext): any[];
+  compile(options?: CompileOptions): CompiledExpression;
+  analyze(options?: AnalyzeOptions): AnalysisResult;
+  toString(): string;
+}
+
+// Compiled expression function
+export interface CompiledExpression {
+  (input?: any, context?: EvaluationContext): any[];
+  readonly source: string;
+}
+
+// Evaluation context for expressions
+export interface EvaluationContext {
+  variables?: Record<string, any>;
+  environment?: Record<string, any>;
+  modelProvider?: ModelProvider;
+  customFunctions?: CustomFunctionMap;
+}
+
+// Custom function definition
+export type CustomFunction = (
+  context: Context,
+  input: any[],
+  ...args: any[]
+) => any[];
+
+export type CustomFunctionMap = Record<string, CustomFunction>;
+
+// Model provider interface
+export interface ModelProvider {
+  resolveType(typeName: string): TypeRef | undefined;
+  getTypeHierarchy(typeName: string): string[];
+  getProperties(typeName: string): PropertyDefinition[];
+  getTypeName?(type: TypeRef): string;
+}
+
+export interface PropertyDefinition {
+  name: string;
+  type: string;
+  isCollection: boolean;
+  isRequired: boolean;
+}
+
+// Compilation options
+export interface CompileOptions {
+  optimize?: boolean;
+  sourceMap?: boolean;
+}
+
+// Analysis options
+export interface AnalyzeOptions {
+  modelProvider?: ModelProvider;
+  strict?: boolean;
+}
+
+// Analysis result
+export interface AnalysisResult {
+  type: TypeRef;
+  isSingleton: boolean;
+  errors: AnalysisError[];
+  warnings: AnalysisWarning[];
+}
+
+export interface AnalysisError {
+  message: string;
+  location?: Location;
+  code: string;
+}
+
+export interface AnalysisWarning {
+  message: string;
+  location?: Location;
+  code: string;
+}
+
+export interface Location {
+  line: number;
+  column: number;
+  offset: number;
+  length: number;
+}
+
+// Registry API types
+export interface RegistryAPI {
+  // List operations by type
+  listFunctions(): OperationMetadata[];
+  listOperators(): OperationMetadata[];
+  listAllOperations(): OperationMetadata[];
+  
+  // Check existence
+  hasOperation(name: string): boolean;
+  hasFunction(name: string): boolean;
+  hasOperator(symbol: string): boolean;
+  
+  // Get operation metadata (read-only view)
+  getOperationInfo(name: string): OperationInfo | undefined;
+  
+  // Extension validation
+  canRegisterFunction(name: string): boolean;
+}
+
+// Simplified metadata for public consumption
+export interface OperationMetadata {
+  name: string;
+  kind: 'function' | 'operator' | 'literal';
+  syntax: {
+    notation: string;  // e.g., "a + b", "substring(start, length)"
+  };
+}
+
+export 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[];
+}
+
+// Builder interfaces
+export interface FHIRPathBuilder {
+  withModelProvider(provider: ModelProvider): this;
+  withCustomFunction(name: string, fn: CustomFunction): this;
+  withVariable(name: string, value: any): this;
+  build(): FHIRPathAPI;
+}
+
+export 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;
+}