@atomic-ehr/fhirpath 0.0.3 → 0.0.4

package/src/{model-provider.ts → model-provider.common.ts}

@@ -1,7 +1,14 @@
 import type { ModelProvider, TypeInfo, TypeName } from './types';
-import { CanonicalManager as createCanonicalManager, type Config, type CanonicalManager, type Resource } from '@atomic-ehr/fhir-canonical-manager';
 import { translate, type FHIRSchema, type StructureDefinition } from '@atomic-ehr/fhirschema';
 
+export type Resource = {
+  url?: string;
+  version?: string;
+  id: string;
+  resourceType: string;
+  [key: string]: any;
+};
+
 export interface FHIRModelContext {
   // Path in the resource (e.g., "Patient.name.given")
   path: string;
@@ -23,12 +30,6 @@ export interface FHIRModelContext {
   version?: string;
 }
 
-export interface FHIRModelProviderConfig {
-  packages: Array<{ name: string; version: string }>;
-  cacheDir?: string;
-  registryUrl?: string;
-}
-
 /**
  * FHIR ModelProvider implementation
  * 
@@ -37,8 +38,7 @@ export interface FHIRModelProviderConfig {
  * 
  * For best performance, pre-load common types during initialization.
  */
-export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
-  private canonicalManager: ReturnType<typeof createCanonicalManager>;
+export class FHIRModelProviderBase implements ModelProvider<FHIRModelContext> {
   private schemaCache: Map<string, FHIRSchema> = new Map();
   private hierarchyCache: Map<string, FHIRSchema[]> = new Map();
   private initialized = false;
@@ -105,26 +105,21 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     'xhtml': 'Xhtml'
   };
   
-  constructor(private config: FHIRModelProviderConfig = {
-    packages: [{ name: 'hl7.fhir.r4.core', version: '4.0.1' }]
-  }) {
-    const canonicalConfig: Config = {
-      packages: config.packages.map(p => `${p.name}@${p.version}`),
-      workingDir: config.cacheDir || './tmp/.fhir-cache'
-    };
-    
-    if (config.registryUrl) {
-      canonicalConfig.registry = config.registryUrl;
+  constructor() {
+    if (this.constructor === FHIRModelProviderBase) {
+      throw new Error("FHIRModelProviderBase can't be instantiated directly.");
     }
-    
-    this.canonicalManager = createCanonicalManager(canonicalConfig);
+  }
+
+  async prepare(): Promise<void> {
+    // Override this in your code
   }
   
   async initialize(): Promise<void> {
     if (this.initialized) return;
     
     try {
-      await this.canonicalManager.init();
+      await this.prepare();
       
       // Just discover type names for completions - schemas load lazily on demand
       await Promise.all([
@@ -142,6 +137,14 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     }
   }
   
+  async resolve(_canonicalUrl: string): Promise<Resource | null> {
+    throw new Error("Resolve not implemented.")
+  }
+
+  async search(_params: {kind: "primitive-type" | "complex-type" | "resource"}): Promise<Resource[]> {
+    throw new Error("Search not implemented.")
+  }
+
   private buildCanonicalUrl(typeName: string): string {
     // For R4 core types
     return `http://hl7.org/fhir/StructureDefinition/${typeName}`;
@@ -157,7 +160,7 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
     try {
       // Resolve canonical URL for the type
       const canonicalUrl = this.buildCanonicalUrl(typeName);
-      const resource = await this.canonicalManager.resolve(canonicalUrl);
+      const resource = await this.resolve(canonicalUrl);
       if (!resource || resource.resourceType !== 'StructureDefinition') {
         return undefined;
       }
@@ -614,7 +617,7 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
       return this.resourceTypesCache;
     }
     
-    const resources = await this.canonicalManager.search({ 
+    const resources = await this.search({
       kind: 'resource' 
     });
     
@@ -632,7 +635,7 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
       return this.complexTypesCache;
     }
     
-    const resources = await this.canonicalManager.search({ 
+    const resources = await this.search({
       kind: 'complex-type' 
     });
     
@@ -658,7 +661,7 @@ export class FHIRModelProvider implements ModelProvider<FHIRModelContext> {
       return this.primitiveTypesCache;
     }
     
-    const resources = await this.canonicalManager.search({ 
+    const resources = await this.search({
       kind: 'primitive-type' 
     });
     

package/src/model-provider.node.ts

@@ -0,0 +1,41 @@
+export * from './model-provider.common'
+import { CanonicalManager as createCanonicalManager, type Config,  } from '@atomic-ehr/fhir-canonical-manager';
+import { FHIRModelProviderBase, type Resource } from './model-provider.common';
+
+export interface FHIRModelProviderConfig {
+  packages: Array<{ name: string; version: string }>;
+  cacheDir?: string;
+  registryUrl?: string;
+}
+
+export class FHIRModelProvider extends FHIRModelProviderBase {
+  private canonicalManager: ReturnType<typeof createCanonicalManager>;
+
+  override async prepare(): Promise<void> {
+    await this.canonicalManager.init();
+  }
+
+  override async resolve(canonicalUrl: string): Promise<Resource> {
+    return await this.canonicalManager.resolve(canonicalUrl);
+  }
+
+  override async search(params: { kind: 'primitive-type' | 'complex-type' | 'resource' }): Promise<Resource[]> {
+    return await this.canonicalManager.search(params);
+  }
+
+  constructor(private config: FHIRModelProviderConfig = {
+    packages: [{ name: 'hl7.fhir.r4.core', version: '4.0.1' }]
+  }) {
+    super();
+    const canonicalConfig: Config = {
+      packages: config.packages.map(p => `${p.name}@${p.version}`),
+      workingDir: config.cacheDir || './tmp/.fhir-cache'
+    };
+
+    if (config.registryUrl) {
+      canonicalConfig.registry = config.registryUrl;
+    }
+
+    this.canonicalManager = createCanonicalManager(canonicalConfig);
+  }
+}

package/src/operations/allTrue-function.ts

@@ -8,16 +8,12 @@ export const evaluate: FunctionEvaluator = async (input, context, args, evaluato
     return { value: [box(true, { type: 'Boolean', singleton: true })], context };
   }
   
-  // Verify all inputs are booleans (unbox first)
-  for (let i = 0; i < input.length; i++) {
-    const unboxedValue = unbox(input[i]!);
-    if (typeof unboxedValue !== 'boolean') {
-      throw Errors.booleanOperationOnNonBoolean('allTrue', i, `${typeof unboxedValue}`);
-    }
-  }
-  
-  // Return true if all items are true, false if any item is false
-  const result = input.every(item => unbox(item) === true);
+  // Check all items: return false if any item is non-boolean or false
+  // Return true only if ALL items are boolean true
+  const result = input.every(item => {
+    const unboxedValue = unbox(item);
+    return unboxedValue === true;  // This will return false for non-booleans or false values
+  });
   
   return { value: [box(result, { type: 'Boolean', singleton: true })], context };
 };

package/src/operations/and-operator.ts

@@ -39,8 +39,8 @@ export const andOperator: OperatorDefinition & { evaluate: OperationEvaluator }
   signatures: [
     {
       name: 'and',
-      left: { type: 'Boolean', singleton: true },
-      right: { type: 'Boolean', singleton: true },
+      left: { type: 'Any', singleton: true },
+      right: { type: 'Any', singleton: true },
       result: { type: 'Boolean', singleton: true }
     }
   ],

package/src/operations/as-function.ts

@@ -19,6 +19,12 @@ const asEvaluator: FunctionEvaluator = async (
     return { value: [], context };
   }
   
+  // as() function only works on singleton values (single items), not collections
+  // According to FHIRPath spec section 6.6
+  if (input.length > 1) {
+    throw new Error('as() can only be used on single values, not on collections');
+  }
+  
   // Extract type name from the argument AST node
   let typeName: string;
   
@@ -29,6 +35,41 @@ const asEvaluator: FunctionEvaluator = async (
     throw new Error(`as() requires a type name as argument, got ${typeArg.type}`);
   }
   
+  // Validate the type name using ModelProvider if available
+  if (context.modelProvider) {
+    // Try to get the type from the model provider
+    const typeInfo = await context.modelProvider.getType(typeName);
+    if (!typeInfo) {
+      // Not a valid FHIR type, check if it's a System type
+      const systemTypes = ['Boolean', 'String', 'Integer', 'Decimal', 'Date', 'DateTime', 'Time', 'Quantity'];
+      const fhirPrimitiveTypes = ['boolean', 'integer', 'string', 'decimal', 'uri', 'url', 'canonical', 
+                                   'base64Binary', 'instant', 'date', 'dateTime', 'time', 'code', 'oid', 
+                                   'id', 'markdown', 'unsignedInt', 'positiveInt', 'uuid', 'xhtml'];
+      
+      if (!systemTypes.includes(typeName) && !fhirPrimitiveTypes.includes(typeName)) {
+        throw new Error(`Unknown type: ${typeName}`);
+      }
+    }
+  } else {
+    // Without ModelProvider, only allow basic System types and reject obvious invalid names
+    const systemTypes = ['Boolean', 'String', 'Integer', 'Decimal', 'Date', 'DateTime', 'Time'];
+    const fhirPrimitiveTypes = ['boolean', 'integer', 'string', 'decimal', 'uri', 'url', 'canonical', 
+                                 'base64Binary', 'instant', 'date', 'dateTime', 'time', 'code', 'oid', 
+                                 'id', 'markdown', 'unsignedInt', 'positiveInt', 'uuid'];
+    
+    // If it's not a known primitive type and looks invalid, reject it
+    if (!systemTypes.includes(typeName) && !fhirPrimitiveTypes.includes(typeName)) {
+      // Check if it looks like a valid type name (starts with letter, contains only valid chars)
+      if (!/^[A-Z][A-Za-z0-9]*$/.test(typeName) && !/^[a-z][a-z0-9]*$/i.test(typeName)) {
+        throw new Error(`Invalid type name: ${typeName}`);
+      }
+      // If it contains numbers but isn't a known type, it's likely invalid
+      if (/\d/.test(typeName) && typeName !== 'base64Binary') {
+        throw new Error(`Unknown type: ${typeName}`);
+      }
+    }
+  }
+  
   // Use the as operator implementation with the type name
   return asOperatorEvaluate(input, context, input, [typeName]);
 };

package/src/operations/combine-operator.ts

@@ -4,10 +4,23 @@ import type { OperationEvaluator } from '../types';
 import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: OperationEvaluator = async (input, context, left, right) => {
-  // Combine operator concatenates all values as strings
+  // & operator requires singleton operands (or empty)
   // Empty collections are treated as empty string
-  const leftStr = left.length === 0 ? '' : left.map(v => String(unbox(v))).join('');
-  const rightStr = right.length === 0 ? '' : right.map(v => String(unbox(v))).join('');
+  
+  // Check for multiple items in left operand
+  if (left.length > 1) {
+    const { Errors } = await import('../errors');
+    throw Errors.invalidOperation('& operator requires singleton operands, left operand contains multiple items');
+  }
+  
+  // Check for multiple items in right operand
+  if (right.length > 1) {
+    const { Errors } = await import('../errors');
+    throw Errors.invalidOperation('& operator requires singleton operands, right operand contains multiple items');
+  }
+  
+  const leftStr = left.length === 0 ? '' : String(unbox(left[0]));
+  const rightStr = right.length === 0 ? '' : String(unbox(right[0]));
   
   // Always return a string, even if both are empty
   return { value: [box(leftStr + rightStr, { type: 'String', singleton: true })], context };
@@ -20,7 +33,7 @@ export const combineOperator: OperatorDefinition & { evaluate: OperationEvaluato
   category: ['string'],
   precedence: PRECEDENCE.ADDITIVE,
   associativity: 'left',
-  description: 'String concatenation operator',
+  description: 'String concatenation operator that requires singleton operands. Empty collections are treated as empty strings.',
   examples: ['first & " " & last'],
   signatures: [
     {

package/src/operations/comparison.ts

@@ -142,6 +142,12 @@ export function collectionsEqual(left: FHIRPathValue[], right: FHIRPathValue[]):
     if (result.reason === 'complex types not equal') {
       return false;
     }
+    // Special case: Date vs Time are definitively not equal
+    // Per XML tests: Date != Time returns true, Date = Time returns false
+    if (result.reason === 'date vs time') {
+      return false;
+    }
+    // Other incomparable cases (e.g., Date vs DateTime with same date) remain incomparable
     return null;
   }
   return result.kind === 'equal';
@@ -173,6 +179,12 @@ export function collectionsNotEqual(left: FHIRPathValue[], right: FHIRPathValue[
     if (result.reason === 'complex types not equal') {
       return true;
     }
+    // Special case: Date vs Time are definitively not equal
+    // Per XML tests: Date != Time returns true, Date = Time returns false
+    if (result.reason === 'date vs time') {
+      return true;
+    }
+    // Other incomparable cases (e.g., Date vs DateTime with same date) remain incomparable
     return null;
   }
   return result.kind !== 'equal';
@@ -188,7 +200,15 @@ function isTemporalValue(value: unknown): value is TemporalValue {
 function isQuantity(value: unknown): value is QuantityValue {
   if (!value || typeof value !== 'object') return false;
   const v = value as any;
-  return 'unit' in v && 'value' in v && typeof v.value === 'number' && typeof v.unit === 'string';
+  // Check for FHIRPath quantity (has unit and value)
+  if ('unit' in v && 'value' in v && typeof v.value === 'number' && typeof v.unit === 'string') {
+    return true;
+  }
+  // Check for FHIR Quantity (has code or unit, and value)
+  if ('value' in v && typeof v.value === 'number' && ('code' in v || 'unit' in v)) {
+    return true;
+  }
+  return false;
 }
 
 function isComplex(value: unknown): value is object {
@@ -198,6 +218,12 @@ function isComplex(value: unknown): value is object {
 // Type-specific comparison functions
 
 function compareTemporal(a: TemporalValue, b: TemporalValue): ComparisonResult {
+  // Check for Date vs Time - these are definitively not equal
+  if ((isFHIRDate(a) && isFHIRTime(b)) || (isFHIRTime(a) && isFHIRDate(b))) {
+    // Date and Time are completely different types - not equal, not incomparable
+    return { kind: 'incomparable', reason: 'date vs time' };
+  }
+  
   // Use existing temporal comparison logic
   const compareResult = temporalCompare(a, b);
   
@@ -213,8 +239,20 @@ function compareTemporal(a: TemporalValue, b: TemporalValue): ComparisonResult {
   return { kind: 'greater' };
 }
 
+function normalizeQuantity(q: any): QuantityValue {
+  // For FHIR Quantity, use code field if present, otherwise unit
+  if ('code' in q && typeof q.code === 'string') {
+    return { value: q.value, unit: q.code };
+  }
+  return { value: q.value, unit: q.unit };
+}
+
 function compareQuantityValues(a: QuantityValue, b: QuantityValue): ComparisonResult {
-  const result = compareQuantities(a, b);
+  // Normalize both quantities to handle FHIR vs FHIRPath quantities
+  const normA = normalizeQuantity(a);
+  const normB = normalizeQuantity(b);
+  
+  const result = compareQuantities(normA, normB);
   
   if (result === null) {
     return { kind: 'incomparable', reason: 'incompatible quantity dimensions' };
@@ -534,31 +572,45 @@ const CALENDAR_TO_UCUM_MAP: Record<string, string> = {
  * Quantity equivalence with UCUM semantic comparison and calendar mappings
  */
 function quantityEquivalent(a: QuantityValue, b: QuantityValue): boolean | null {
-  // Check for calendar to UCUM equivalence
-  const aIsCalendar = CALENDAR_TO_UCUM_MAP[a.unit] !== undefined;
-  const bIsCalendar = CALENDAR_TO_UCUM_MAP[b.unit] !== undefined;
+  // Normalize both quantities to handle FHIR vs FHIRPath quantities
+  const normA = normalizeQuantity(a);
+  const normB = normalizeQuantity(b);
+  
+  // Use compareQuantities which now handles calendar unit conversions
+  const result = compareQuantities(normA, normB);
   
-  // Calendar to UCUM mapping
-  if (aIsCalendar && !bIsCalendar) {
-    const ucumUnit = CALENDAR_TO_UCUM_MAP[a.unit];
-    return ucumUnit === b.unit && a.value === b.value;
+  // Null means incomparable
+  if (result === null) {
+    return null;
   }
-  if (!aIsCalendar && bIsCalendar) {
-    const ucumUnit = CALENDAR_TO_UCUM_MAP[b.unit];
-    return ucumUnit === a.unit && a.value === b.value;
+  
+  // For equivalence, we check if they're equal when converted
+  // compareQuantities returns 0 for equal values
+  if (result === 0) {
+    return true;
   }
   
-  // Both calendar units - must be same unit and value
-  if (aIsCalendar && bIsCalendar) {
-    // Normalize to singular/plural
-    const aNorm = CALENDAR_TO_UCUM_MAP[a.unit];
-    const bNorm = CALENDAR_TO_UCUM_MAP[b.unit];
-    return aNorm === bNorm && a.value === b.value;
+  // For approximate equivalence (~), check if values are within tolerance
+  // This is primarily for handling precision differences like 4 g ~ 4.040 g
+  // We need special handling for common unit conversions with tolerance
+  
+  // Check if one is g and other is mg
+  if ((a.unit === 'g' && b.unit === 'mg') || (a.unit === 'mg' && b.unit === 'g')) {
+    // Convert both to mg for comparison
+    const aInMg = a.unit === 'g' ? a.value * 1000 : a.value;
+    const bInMg = b.unit === 'g' ? b.value * 1000 : b.value;
+    
+    // Check if within 1% tolerance for approximate equivalence
+    const diff = Math.abs(aInMg - bInMg);
+    const avg = (aInMg + bInMg) / 2;
+    const tolerance = avg * 0.01; // 1% tolerance
+    
+    return diff <= tolerance;
   }
   
-  // Standard UCUM semantic equivalence (1000 mg ~ 1 g)
-  const result = compareQuantities(a, b);
-  return result === 0;
+  // For other units, compareQuantities handles the conversion
+  // If it returned non-zero, they're not equivalent
+  return false;
 }
 
 /**

package/src/operations/convertsToQuantity-function.ts

@@ -50,13 +50,25 @@ export const evaluate: FunctionEvaluator = async (input, context, args, evaluato
     }
   }
   
-  // String - check if it can be parsed as a quantity (e.g., "10 mg", "5.5 km")
+  // String - check if it can be parsed as a quantity or plain number
   if (typeof inputValue === 'string') {
+    const trimmed = inputValue.trim();
+    
+    // First check if it's just a plain number (integer or decimal)
+    const numberRegex = /^(\+|-)?\d+(\.\d+)?$/;
+    if (numberRegex.test(trimmed)) {
+      const value = parseFloat(trimmed);
+      if (!isNaN(value)) {
+        // Plain number strings can be converted to quantity with unit '1'
+        return { value: [box(true, { type: 'Boolean', singleton: true })], context };
+      }
+    }
+    
     // Try to parse as quantity: number followed by space(s) and unit
-    // This matches the pattern: <number> <unit>
+    // This matches the pattern: <number> <unit> or <number> '<unit>'
     const quantityRegex = /^(\+|-)?\d+(\.\d+)?\s+.+$/;
     
-    if (!quantityRegex.test(inputValue.trim())) {
+    if (!quantityRegex.test(trimmed)) {
       return { value: [box(false, { type: 'Boolean', singleton: true })], context };
     }
     
@@ -67,7 +79,40 @@ export const evaluate: FunctionEvaluator = async (input, context, args, evaluato
     }
     
     const valueStr = parts[0];
-    const unit = parts.slice(1).join(' ');
+    let unit = parts.slice(1).join(' ');
+    
+    // Check if unit is quoted
+    const isQuoted = unit.startsWith("'") && unit.endsWith("'") && unit.length > 2;
+    
+    if (isQuoted) {
+      // Remove quotes for validation
+      unit = unit.slice(1, -1);
+    } else {
+      // For unquoted units, check special cases
+      // Calendar duration words are always valid
+      const CALENDAR_DURATION_WORDS = [
+        'year', 'years',
+        'month', 'months', 
+        'week', 'weeks',
+        'day', 'days',
+        'hour', 'hours',
+        'minute', 'minutes',
+        'second', 'seconds',
+        'millisecond', 'milliseconds'
+      ];
+      
+      // Time unit abbreviations that should NOT be accepted without quotes
+      // (they have calendar duration equivalents)
+      const TIME_UNIT_ABBREVS = ['wk', 'd', 'h', 'min', 's', 'ms'];
+      
+      if (TIME_UNIT_ABBREVS.includes(unit)) {
+        // These time abbreviations require quotes
+        return { value: [box(false, { type: 'Boolean', singleton: true })], context };
+      }
+      
+      // Calendar duration words are valid
+      // Other units (like mg, km, etc.) are also valid
+    }
     
     const value = parseFloat(valueStr!);
     if (isNaN(value)) {
@@ -84,10 +129,14 @@ export const evaluate: FunctionEvaluator = async (input, context, args, evaluato
     }
   }
   
-  // Integer or Decimal with no unit - not a valid quantity
-  // (quantities must have units)
+  // Integer or Decimal - can be converted to quantity with unit '1'
   if (typeof inputValue === 'number') {
-    return { value: [box(false, { type: 'Boolean', singleton: true })], context };
+    return { value: [box(true, { type: 'Boolean', singleton: true })], context };
+  }
+  
+  // Boolean - can be converted to quantity (1 or 0 with unit '1')
+  if (typeof inputValue === 'boolean') {
+    return { value: [box(true, { type: 'Boolean', singleton: true })], context };
   }
 
   // For all other types, return false

package/src/operations/decode-function.ts

@@ -0,0 +1,114 @@
+import type { FunctionDefinition, FunctionEvaluator } from '../types';
+import { Errors } from '../errors';
+import { box, unbox } from '../interpreter/boxing';
+
+export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
+  // Handle empty input collection
+  if (input.length === 0) {
+    return { value: [], context };
+  }
+  
+  // If input contains multiple items, signal an error
+  if (input.length > 1) {
+    throw Errors.invalidOperation('decode can only be applied to a singleton string');
+  }
+  
+  const boxedInputValue = input[0];
+  if (!boxedInputValue) {
+    return { value: [], context };
+  }
+  
+  const inputValue = unbox(boxedInputValue);
+  
+  // Type check the input - must be a string
+  if (typeof inputValue !== 'string') {
+    throw Errors.stringOperationOnNonString('decode');
+  }
+  
+  // decode() requires exactly one argument (format)
+  if (!args || args.length !== 1) {
+    throw Errors.invalidOperation('decode requires exactly one argument (format)');
+  }
+  
+  // Evaluate the format parameter
+  const formatArg = args[0];
+  if (!formatArg) {
+    return { value: [], context };
+  }
+  
+  const formatResult = await evaluator(formatArg, input, context);
+  if (formatResult.value.length === 0) {
+    // If no format is specified, the result is empty
+    return { value: [], context };
+  }
+  
+  if (formatResult.value.length > 1) {
+    throw Errors.invalidOperation('decode format must be a singleton string');
+  }
+  
+  const boxedFormat = formatResult.value[0];
+  if (!boxedFormat) {
+    return { value: [], context };
+  }
+  
+  const format = unbox(boxedFormat);
+  if (typeof format !== 'string') {
+    throw Errors.invalidOperation('decode format must be a string');
+  }
+  
+  let result: string;
+  
+  try {
+    switch (format.toLowerCase()) {
+      case 'hex': {
+        // Decode from hexadecimal
+        const bytes = Buffer.from(inputValue, 'hex');
+        result = bytes.toString('utf-8');
+        break;
+      }
+      case 'base64': {
+        // Standard base64 decoding
+        const bytes = Buffer.from(inputValue, 'base64');
+        result = bytes.toString('utf-8');
+        break;
+      }
+      case 'urlbase64': {
+        // URL-safe base64 decoding
+        // First, convert urlbase64 to standard base64 format if needed
+        // Replace URL-safe characters with standard base64 characters
+        const standardBase64 = inputValue.replace(/-/g, '+').replace(/_/g, '/');
+        const bytes = Buffer.from(standardBase64, 'base64');
+        result = bytes.toString('utf-8');
+        break;
+      }
+      default:
+        // Unknown format, return empty
+        return { value: [], context };
+    }
+  } catch (error) {
+    // If decoding fails (invalid encoding), throw an error
+    throw Errors.invalidOperation(`Failed to decode string with format '${format}': invalid encoding`);
+  }
+  
+  return { value: [box(result, { type: 'String', singleton: true })], context };
+};
+
+export const decodeFunction: FunctionDefinition & { evaluate: FunctionEvaluator } = {
+  name: 'decode',
+  category: ['string'],
+  description: 'Returns the result of decoding the input string according to the given format. Available formats are hex, base64, and urlbase64.',
+  examples: [
+    "'dGVzdA=='.decode('base64') // returns 'test'",
+    "'74657374'.decode('hex') // returns 'test'",
+    "'c3ViamVjdHM_X2Q='.decode('urlbase64') // returns 'subjects?_d'"
+  ],
+  signatures: [{
+    name: 'decode',
+    input: { type: 'String', singleton: true },
+    parameters: [
+      { name: 'format', type: { type: 'String', singleton: true } }
+    ],
+    result: { type: 'String', singleton: true }
+  }],
+  evaluate
+};

package/src/operations/divide-operator.ts

@@ -23,7 +23,7 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
       r && typeof r === 'object' && 'unit' in r) {
     const rightQuantity = r as QuantityValue;
     if (rightQuantity.value === 0) {
-      throw Errors.divisionByZero();
+      return { value: [], context };  // Return empty for division by zero
     }
     const result = divideQuantities(l as QuantityValue, rightQuantity);
     return { value: result ? [box(result, { type: 'Quantity', singleton: true })] : [], context };
@@ -32,7 +32,7 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
   // Handle quantity / number
   if (l && typeof l === 'object' && 'unit' in l && typeof r === 'number') {
     if (r === 0) {
-      throw Errors.divisionByZero();
+      return { value: [], context };  // Return empty for division by zero
     }
     const q = l as QuantityValue;
     return { value: [box({ value: q.value / r, unit: q.unit }, { type: 'Quantity', singleton: true })], context };
@@ -41,7 +41,7 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
   // Handle numeric division
   if (typeof l === 'number' && typeof r === 'number') {
     if (r === 0) {
-      throw Errors.divisionByZero();
+      return { value: [], context };  // Return empty for division by zero
     }
     return { value: [box(l / r, { type: 'Any', singleton: true })], context };
   }