@atomic-ehr/fhirpath 0.0.2 → 0.0.3

package/src/operations/index.ts

@@ -34,6 +34,8 @@ export { containsOperator } from './contains-operator';
 export { isOperator } from './is-operator';
 export { asOperator } from './as-operator';
 export { ofTypeFunction } from './ofType-function';
+export { isFunction } from './is-function';
+export { asFunction } from './as-function';
 
 // Other operators
 export { unionOperator } from './union-operator';
@@ -43,6 +45,7 @@ export { dotOperator } from './dot-operator';
 // Functions
 export { whereFunction } from './where-function';
 export { selectFunction } from './select-function';
+export { repeatFunction } from './repeat-function';
 export { firstFunction } from './first-function';
 export { lastFunction } from './last-function';
 export { childrenFunction } from './children-function';
@@ -60,6 +63,19 @@ export { distinctFunction } from './distinct-function';
 export { isDistinctFunction } from './isDistinct-function';
 export { iifFunction } from './iif-function';
 export { defineVariableFunction } from './defineVariable-function';
+
+// Temporal functions
+export { 
+  nowFunction, 
+  todayFunction, 
+  timeOfDayFunction,
+  toDateFunction,
+  toDateTimeFunction,
+  toTimeFunction,
+  convertsToDateFunction,
+  convertsToDateTimeFunction,
+  convertsToTimeFunction
+} from './temporal-functions';
 export { joinFunction } from './join-function';
 export { replaceFunction } from './replace-function';
 export { unionFunction } from './union-function';
@@ -67,7 +83,12 @@ export { combineFunction } from './combine-function';
 export { intersectFunction } from './intersect-function';
 export { excludeFunction } from './exclude-function';
 export { indexOfFunction } from './indexOf-function';
+export { lastIndexOfFunction } from './lastIndexOf-function';
 export { substringFunction } from './substring-function';
+export { matchesFunction } from './matches-function';
+export { matchesFullFunction } from './matchesFull-function';
+export { replaceMatchesFunction } from './replaceMatches-function';
+export { toCharsFunction } from './toChars-function';
 export { containsFunction } from './contains-function';
 export { startsWithFunction } from './startsWith-function';
 export { endsWithFunction } from './endsWith-function';
@@ -88,9 +109,29 @@ export { toIntegerFunction } from './toInteger-function';
 export { toDecimalFunction } from './toDecimal-function';
 export { toStringFunction } from './toString-function';
 export { toBooleanFunction } from './toBoolean-function';
+export { toQuantityFunction } from './toQuantity-function';
+export { toLongFunction } from './toLong-function';
+export { convertsToBooleanFunction } from './convertsToBoolean-function';
+export { convertsToIntegerFunction } from './convertsToInteger-function';
+export { convertsToDecimalFunction } from './convertsToDecimal-function';
+export { convertsToStringFunction } from './convertsToString-function';
+export { convertsToQuantityFunction } from './convertsToQuantity-function';
+export { convertsToLongFunction } from './convertsToLong-function';
 
 // Utility functions
 export { traceFunction } from './trace-function';
+export { dateOfFunction } from './dateOf-function';
+export { timeOfFunction } from './timeOf-function';
+export { yearOfFunction } from './yearOf-function';
+export { monthOfFunction } from './monthOf-function';
+export { dayOfFunction } from './dayOf-function';
+export { hourOfFunction } from './hourOf-function';
+export { minuteOfFunction } from './minuteOf-function';
+export { secondOfFunction } from './secondOf-function';
+export { millisecondOfFunction } from './millisecondOf-function';
+export { timezoneOffsetOfFunction } from './timezoneOffsetOf-function';
+export { lowBoundaryFunction } from './lowBoundary-function';
+export { highBoundaryFunction } from './highBoundary-function';
 
 // Aggregate functions
 export { aggregateFunction } from './aggregate-function';

package/src/operations/indexOf-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition, FunctionEvaluator, LiteralNode } from '../types';
 import { Errors } from '../errors';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   // Check single item in input

package/src/operations/intersect-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition, FunctionEvaluator } from '../types';
 import { Errors } from '../errors';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   if (args.length !== 1) {

package/src/operations/is-function.ts

@@ -0,0 +1,59 @@
+import type { FunctionDefinition, FunctionEvaluator, ASTNode, RuntimeContext, NodeEvaluator } from '../types';
+import type { FHIRPathValue } from '../interpreter/boxing';
+import { NodeType, isIdentifierNode } from '../types';
+import { box } from '../interpreter/boxing';
+import { evaluate as isOperatorEvaluate } from './is-operator';
+
+const isEvaluator: FunctionEvaluator = async (
+  input: FHIRPathValue[], 
+  context: RuntimeContext, 
+  args: ASTNode[],
+  evaluator: NodeEvaluator
+) => {
+  // is() function takes one argument - the type name
+  if (args.length !== 1) {
+    return { value: [], context };
+  }
+  
+  const typeArg = args[0];
+  if (!typeArg) {
+    return { value: [], context };
+  }
+  
+  // Extract type name from the argument AST node
+  let typeName: string;
+  
+  if (isIdentifierNode(typeArg)) {
+    typeName = typeArg.name;
+  } else {
+    // For other node types, try to get the name
+    throw new Error(`is() requires a type name as argument, got ${typeArg.type}`);
+  }
+  
+  // Use the is operator implementation with the type name
+  return isOperatorEvaluate(input, context, input, [typeName]);
+};
+
+export { isEvaluator };
+
+export const isFunction: FunctionDefinition & { evaluate: typeof isEvaluator } = {
+  name: 'is',
+  category: ['type'],
+  description: 'Tests if the input is of the specified type',
+  examples: ['Patient.name.is(HumanName)', '"hello".is(String)', '5.is(Integer)'],
+  signatures: [
+    {
+      name: 'is-type-check', 
+      parameters: [{ 
+        name: 'type', 
+        type: { type: 'Any', singleton: true },
+        expression: true,
+        typeReference: true 
+      }],
+      input: { type: 'Any', singleton: true },
+      result: { type: 'Boolean', singleton: true }
+    }
+  ],
+  doesNotPropagateEmpty: false,
+  evaluate: isEvaluator
+};

package/src/operations/is-operator.ts

@@ -1,7 +1,8 @@
 import type { OperatorDefinition, TypeName } from '../types';
 import { PRECEDENCE } from '../types';
 import type { OperationEvaluator } from '../types';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
+import { isFHIRDate, isFHIRDateTime, isFHIRTime } from '../complex-types/temporal';
 
 export const evaluate: OperationEvaluator = async (input, context, left, right) => {
   // Right operand should be a type identifier
@@ -14,7 +15,7 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
   const item = unbox(boxedItem);
   const typeName = right[0] as string; // Should be a type name like 'String', 'Integer', etc.
   
-  // If we have a ModelProvider in context, use it for accurate type checking
+  // If we have a ModelProvider and typeInfo, use it for accurate type checking (handles subtypes)
   if (context.modelProvider && boxedItem?.typeInfo) {
     const matchingType = context.modelProvider.ofType(boxedItem.typeInfo, typeName as TypeName);
     return { 
@@ -23,9 +24,8 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
     };
   }
   
-  // Check if the box has type information
+  // Check if the box has type information (without ModelProvider, just check exact match)
   if (boxedItem?.typeInfo) {
-    // For now, just check exact type match (no subtype support without ModelProvider)
     return { 
       value: [box(boxedItem.typeInfo.type === typeName, { type: 'Boolean', singleton: true })], 
       context 
@@ -35,9 +35,7 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
   // For FHIR resources without typeInfo, try to get it from modelProvider
   if (context.modelProvider && item && typeof item === 'object' && 'resourceType' in item && typeof item.resourceType === 'string') {
     // Use cached type if available
-    const typeInfo = 'getTypeFromCache' in context.modelProvider 
-      ? (context.modelProvider as any).getTypeFromCache(item.resourceType)
-      : undefined;
+    const typeInfo = await context.modelProvider.getType(item.resourceType);
     if (typeInfo) {
       const matchingType = context.modelProvider.ofType(typeInfo, typeName as TypeName);
       return { 
@@ -63,10 +61,23 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
     case 'Decimal':
       return { value: [box(typeof item === 'number', { type: 'Boolean', singleton: true })], context };
     case 'Date':
+      // Check if it's a FHIRDate instance or has Date type
+      if (item && typeof item === 'object') {
+        return { value: [box(isFHIRDate(item) || (item as any).kind === 'FHIRDate', { type: 'Boolean', singleton: true })], context };
+      }
+      return { value: [box(false, { type: 'Boolean', singleton: true })], context };
     case 'DateTime':
+      // Check if it's a FHIRDateTime instance or has DateTime type
+      if (item && typeof item === 'object') {
+        return { value: [box(isFHIRDateTime(item) || (item as any).kind === 'FHIRDateTime', { type: 'Boolean', singleton: true })], context };
+      }
+      return { value: [box(false, { type: 'Boolean', singleton: true })], context };
     case 'Time':
-      // Simple check for date-like strings
-      return { value: [box(typeof item === 'string' && !isNaN(Date.parse(item)), { type: 'Boolean', singleton: true })], context };
+      // Check if it's a FHIRTime instance or has Time type
+      if (item && typeof item === 'object') {
+        return { value: [box(isFHIRTime(item) || (item as any).kind === 'FHIRTime', { type: 'Boolean', singleton: true })], context };
+      }
+      return { value: [box(false, { type: 'Boolean', singleton: true })], context };
     default:
       // For complex types, check resourceType
       if (item && typeof item === 'object' && 'resourceType' in item) {

package/src/operations/isDistinct-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition, FunctionEvaluator } from '../types';
 import { Errors } from '../errors';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   // isDistinct takes no arguments
@@ -35,6 +35,7 @@ export const evaluate: FunctionEvaluator = async (input, context, args, evaluato
 
 export const isDistinctFunction: FunctionDefinition & { evaluate: FunctionEvaluator } = {
   name: 'isDistinct',
+  doesNotPropagateEmpty: true,  // Returns true for empty collections
   category: ['existence'],
   description: 'Returns true if all the items in the input collection are distinct. To determine whether two items are distinct, the equals (=) operator is used. If the input collection is empty, the result is true.',
   examples: [

package/src/operations/join-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition } from '../types';
 import type { FunctionEvaluator } from '../types';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   // If input is empty, return empty

package/src/operations/last-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition } from '../types';
 import type { FunctionEvaluator } from '../types';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   if (input.length > 0) {

package/src/operations/lastIndexOf-function.ts

@@ -0,0 +1,85 @@
+import type { FunctionDefinition, FunctionEvaluator, LiteralNode } from '../types';
+import { Errors } from '../errors';
+import { box, unbox } from '../interpreter/boxing';
+
+export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
+  // Check single item in input
+  if (input.length === 0) {
+    return { value: [], context };
+  }
+  
+  if (input.length > 1) {
+    throw Errors.stringSingletonRequired('lastIndexOf', input.length);
+  }
+
+  const boxedInputValue = input[0];
+  if (!boxedInputValue) {
+    return { value: [], context };
+  }
+  
+  const inputValue = unbox(boxedInputValue);
+  if (typeof inputValue !== 'string') {
+    throw Errors.stringOperationOnNonString('lastIndexOf');
+  }
+
+  // Check arguments
+  if (args.length !== 1) {
+    throw Errors.wrongArgumentCount('lastIndexOf', 1, args.length);
+  }
+
+  // Evaluate substring argument
+  const substringArg = args[0];
+  if (!substringArg) {
+    throw Errors.argumentRequired('lastIndexOf', 'substring argument');
+  }
+  
+  const substringResult = await evaluator(substringArg, input, context);
+  
+  if (substringResult.value.length === 0) {
+    return { value: [], context };
+  }
+  
+  if (substringResult.value.length > 1) {
+    throw Errors.singletonRequired('lastIndexOf substring', substringResult.value.length);
+  }
+  
+  const boxedSubstring = substringResult.value[0];
+  if (!boxedSubstring) {
+    return { value: [], context };
+  }
+  
+  const substring = unbox(boxedSubstring);
+  if (typeof substring !== 'string') {
+    throw Errors.invalidStringOperation('lastIndexOf', 'substring argument');
+  }
+
+  // Handle empty substring - returns 0 per spec
+  if (substring === '') {
+    return { value: [box(0, { type: 'Integer', singleton: true })], context };
+  }
+
+  // Find the last index
+  const index = inputValue.lastIndexOf(substring);
+  
+  return { value: [box(index, { type: 'Integer', singleton: true })], context };
+};
+
+export const lastIndexOfFunction: FunctionDefinition & { evaluate: FunctionEvaluator } = {
+  name: 'lastIndexOf',
+  category: ['string'],
+  description: 'Returns the 0-based index of the last position substring is found in the input string, or -1 if it is not found',
+  examples: [
+    "'abcdefg'.lastIndexOf('bc')",
+    "'abcdefg'.lastIndexOf('x')",
+    "'abc abc'.lastIndexOf('a')"
+  ],
+  signatures: [{
+    name: 'lastIndexOf',
+    input: { type: 'String', singleton: true },
+    parameters: [
+      { name: 'substring', type: { type: 'String', singleton: true } }
+    ],
+    result: { type: 'Integer', singleton: true }
+  }],
+  evaluate
+};

package/src/operations/length-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition, FunctionEvaluator } from '../types';
 import { Errors } from '../errors';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   // Check single item in input

package/src/operations/less-operator.ts

@@ -1,9 +1,9 @@
 import type { OperatorDefinition } from '../types';
 import { PRECEDENCE } from '../types';
 import type { OperationEvaluator } from '../types';
-import { compareQuantities } from '../quantity-value';
-import type { QuantityValue } from '../quantity-value';
-import { box, unbox } from '../boxing';
+import { compareQuantities } from '../complex-types/quantity-value';
+import type { QuantityValue } from '../complex-types/quantity-value';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: OperationEvaluator = async (input, context, left, right) => {
   if (left.length === 0 || right.length === 0) {
@@ -24,6 +24,23 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
     return { value: result !== null ? [box(result < 0, { type: 'Boolean', singleton: true })] : [], context };
   }
   
+  // Check if both are temporal values (Date, DateTime, Time)
+  if (l && typeof l === 'object' && 'kind' in l &&
+      r && typeof r === 'object' && 'kind' in r) {
+    const temporalL = l as any;
+    const temporalR = r as any;
+    const kinds = ['FHIRDate', 'FHIRDateTime', 'FHIRTime'];
+    if (kinds.includes(temporalL.kind) && kinds.includes(temporalR.kind)) {
+      const { compare } = await import('../complex-types/temporal');
+      const result = compare(temporalL, temporalR);
+      // null means incomparable (different precisions), returns empty
+      if (result === null) {
+        return { value: [], context };
+      }
+      return { value: [box(result < 0, { type: 'Boolean', singleton: true })], context };
+    }
+  }
+  
   return { value: [box((l as any) < (r as any), { type: 'Boolean', singleton: true })], context };
 };
 

package/src/operations/less-or-equal-operator.ts

@@ -1,9 +1,9 @@
 import type { OperatorDefinition } from '../types';
 import { PRECEDENCE } from '../types';
 import type { OperationEvaluator } from '../types';
-import { compareQuantities } from '../quantity-value';
-import type { QuantityValue } from '../quantity-value';
-import { box, unbox } from '../boxing';
+import { compareQuantities } from '../complex-types/quantity-value';
+import type { QuantityValue } from '../complex-types/quantity-value';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: OperationEvaluator = async (input, context, left, right) => {
   if (left.length === 0 || right.length === 0) {
@@ -24,6 +24,23 @@ export const evaluate: OperationEvaluator = async (input, context, left, right)
     return { value: result !== null ? [box(result <= 0, { type: 'Boolean', singleton: true })] : [], context };
   }
   
+  // Check if both are temporal values (Date, DateTime, Time)
+  if (l && typeof l === 'object' && 'kind' in l &&
+      r && typeof r === 'object' && 'kind' in r) {
+    const temporalL = l as any;
+    const temporalR = r as any;
+    const kinds = ['FHIRDate', 'FHIRDateTime', 'FHIRTime'];
+    if (kinds.includes(temporalL.kind) && kinds.includes(temporalR.kind)) {
+      const { compare } = await import('../complex-types/temporal');
+      const result = compare(temporalL, temporalR);
+      // null means incomparable (different precisions), returns empty
+      if (result === null) {
+        return { value: [], context };
+      }
+      return { value: [box(result <= 0, { type: 'Boolean', singleton: true })], context };
+    }
+  }
+  
   return { value: [box((l as any) <= (r as any), { type: 'Boolean', singleton: true })], context };
 };
 

package/src/operations/less-than.ts

@@ -1,8 +1,8 @@
 import type { OperatorDefinition } from '../types';
 import { PRECEDENCE } from '../types';
 import type { OperationEvaluator } from '../types';
-import { box, unbox } from '../boxing';
-import { compareQuantities, type QuantityValue } from '../quantity-value';
+import { box, unbox } from '../interpreter/boxing';
+import { compareQuantities, type QuantityValue } from '../complex-types/quantity-value';
 
 export const evaluate: OperationEvaluator = async (input, context, left, right) => {
   if (left.length === 0 || right.length === 0) {

package/src/operations/lowBoundary-function.ts

@@ -0,0 +1,120 @@
+// lowBoundary() function - Returns the least possible value to the specified precision
+import type { FunctionDefinition, FunctionEvaluator } from '../types';
+import { box, unbox } from '../interpreter/boxing';
+import { 
+  isFHIRDate, isFHIRDateTime, isFHIRTime,
+  getDateLowBoundary, getDateTimeLowBoundary, getTimeLowBoundary 
+} from '../complex-types/temporal';
+import { getDecimalLowBoundary } from './decimal-boundaries';
+import { Errors } from '../errors';
+
+export const lowBoundaryEvaluator: FunctionEvaluator = async (input, context, args, evaluator) => {
+  // lowBoundary() takes optional precision parameter
+  if (args.length > 1) {
+    throw Errors.wrongArgumentCountRange('lowBoundary', 0, 1, args.length);
+  }
+  
+  // Empty input returns empty
+  if (input.length === 0) {
+    return { value: [], context };
+  }
+  
+  // Multiple items throws error
+  if (input.length > 1) {
+    throw Errors.singletonRequired('lowBoundary', input.length);
+  }
+  
+  const boxedValue = input[0];
+  if (!boxedValue) {
+    return { value: [], context };
+  }
+  
+  const value = unbox(boxedValue);
+  
+  // Get precision if provided
+  let precision: number | undefined;
+  if (args.length === 1) {
+    const precisionResult = await evaluator(args[0]!, input, context);
+    const precisionArg = precisionResult.value;
+    if (precisionArg.length === 0) {
+      return { value: [], context };
+    }
+    if (precisionArg.length > 1) {
+      throw Errors.singletonRequired('lowBoundary precision', precisionArg.length);
+    }
+    const precisionValue = unbox(precisionArg[0]!);
+    if (typeof precisionValue !== 'number' || !Number.isInteger(precisionValue)) {
+      throw Errors.invalidOperandType('lowBoundary precision', typeof precisionValue);
+    }
+    precision = precisionValue;
+  }
+  
+  // Handle Date
+  if (isFHIRDate(value)) {
+    const result = getDateLowBoundary(value, precision);
+    if (!result) {
+      return { value: [], context };
+    }
+    return { value: [box(result, { type: 'Date', singleton: true })], context };
+  }
+  
+  // Handle DateTime
+  if (isFHIRDateTime(value)) {
+    const result = getDateTimeLowBoundary(value, precision);
+    if (!result) {
+      return { value: [], context };
+    }
+    return { value: [box(result, { type: 'DateTime', singleton: true })], context };
+  }
+  
+  // Handle Time
+  if (isFHIRTime(value)) {
+    const result = getTimeLowBoundary(value, precision);
+    if (!result) {
+      return { value: [], context };
+    }
+    return { value: [box(result, { type: 'Time', singleton: true })], context };
+  }
+  
+  // For Decimal/Integer types
+  if (typeof value === 'number') {
+    const result = getDecimalLowBoundary(value, precision);
+    if (result === null) {
+      return { value: [], context };
+    }
+    // Determine the result type based on whether it's an integer or decimal
+    const isInteger = Number.isInteger(result);
+    return { 
+      value: [box(result, { type: isInteger ? 'Integer' : 'Decimal', singleton: true })], 
+      context 
+    };
+  }
+  
+  // Invalid type returns empty
+  return { value: [], context };
+};
+
+export const lowBoundaryFunction: FunctionDefinition & { evaluate: typeof lowBoundaryEvaluator } = {
+  name: 'lowBoundary',
+  category: ['utility'],
+  description: 'Returns the least possible value of the input to the specified precision',
+  examples: [
+    '@2014.lowBoundary(6)',
+    '@2014-01-01T08.lowBoundary(17)',
+    '@T10:30.lowBoundary(9)',
+    '1.587.lowBoundary()',
+    '1.587.lowBoundary(2)',
+    '1.lowBoundary(0)'
+  ],
+  signatures: [
+    {
+      name: 'lowBoundary',
+      input: { type: 'Any' as const, singleton: true },
+      parameters: [
+        { name: 'precision', type: { type: 'Integer' as const, singleton: true }, optional: true }
+      ],
+      result: { type: 'Any' as const, singleton: true }
+    }
+  ],
+  evaluate: lowBoundaryEvaluator
+};

package/src/operations/lower-function.ts

@@ -1,6 +1,6 @@
 import type { FunctionDefinition, FunctionEvaluator } from '../types';
 import { Errors } from '../errors';
-import { box, unbox } from '../boxing';
+import { box, unbox } from '../interpreter/boxing';
 
 export const evaluate: FunctionEvaluator = async (input, context, args, evaluator) => {
   // Handle empty input collection

package/src/operations/matches-function.ts

@@ -0,0 +1,86 @@
+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) => {
+  // Check single item in input
+  if (input.length === 0) {
+    return { value: [], context };
+  }
+  
+  if (input.length > 1) {
+    throw Errors.stringSingletonRequired('matches', input.length);
+  }
+
+  const boxedInputValue = input[0];
+  if (!boxedInputValue) {
+    return { value: [], context };
+  }
+  
+  const inputValue = unbox(boxedInputValue);
+  if (typeof inputValue !== 'string') {
+    throw Errors.stringOperationOnNonString('matches');
+  }
+
+  // Check arguments
+  if (args.length !== 1) {
+    throw Errors.wrongArgumentCount('matches', 1, args.length);
+  }
+
+  // Evaluate regex argument
+  const regexArg = args[0];
+  if (!regexArg) {
+    throw Errors.argumentRequired('matches', 'regex argument');
+  }
+  
+  const regexResult = await evaluator(regexArg, input, context);
+  
+  if (regexResult.value.length === 0) {
+    return { value: [], context };
+  }
+  
+  if (regexResult.value.length > 1) {
+    throw Errors.singletonRequired('matches regex', regexResult.value.length);
+  }
+  
+  const boxedRegex = regexResult.value[0];
+  if (!boxedRegex) {
+    return { value: [], context };
+  }
+  
+  const regexPattern = unbox(boxedRegex);
+  if (typeof regexPattern !== 'string') {
+    throw Errors.invalidStringOperation('matches', 'regex argument');
+  }
+
+  try {
+    // Create regex with unicode support and single line mode (dotAll)
+    // Per spec: case-sensitive, single line mode, allow Unicode
+    const regex = new RegExp(regexPattern, 'us');
+    const result = regex.test(inputValue);
+    
+    return { value: [box(result, { type: 'Boolean', singleton: true })], context };
+  } catch (error) {
+    throw new Error(`Invalid regular expression in matches(): ${(error as Error).message}`);
+  }
+};
+
+export const matchesFunction: FunctionDefinition & { evaluate: FunctionEvaluator } = {
+  name: 'matches',
+  category: ['string'],
+  description: 'Returns true when the input string matches the given regular expression',
+  examples: [
+    "'test string'.matches('t.+')",
+    "'test string'.matches('asd.+')",
+    "'first line\\nsecond line'.matches('line.second')"
+  ],
+  signatures: [{
+    name: 'matches',
+    input: { type: 'String', singleton: true },
+    parameters: [
+      { name: 'regex', type: { type: 'String', singleton: true } }
+    ],
+    result: { type: 'Boolean', singleton: true }
+  }],
+  evaluate
+};