@higher.archi/boe 1.0.0

package/src/core/operators/transform/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Transform Operators
+ *
+ * Exports all transform operators for registry registration.
+ */
+
+import trimOps from './trim';
+import caseOps from './case';
+import substringOps from './substring';
+import concatOps from './concat';
+import replaceOps from './replace';
+import padOps from './pad';
+import lengthOps from './length';
+
+export * from './trim';
+export * from './case';
+export * from './substring';
+export * from './concat';
+export * from './replace';
+export * from './pad';
+export * from './length';
+
+/**
+ * All transform operators as an array for bulk registration
+ */
+export const transformOperators = [
+  ...trimOps,
+  ...caseOps,
+  ...substringOps,
+  ...concatOps,
+  ...replaceOps,
+  ...padOps,
+  ...lengthOps,
+];
+
+export default transformOperators;

package/src/core/operators/transform/length.ts

@@ -0,0 +1,37 @@
+/**
+ * Length Operator
+ *
+ * Returns the length of a string or array.
+ */
+
+import { polymorphicOp } from '../operator';
+import { PolymorphicOperator } from '../types';
+
+/**
+ * Length - works on strings and arrays
+ *
+ * @example
+ * ['length', 'hello']     // 5
+ * ['length', [1, 2, 3]]   // 3
+ */
+export const length: PolymorphicOperator = polymorphicOp(
+  'length',
+  {
+    string: (str: string) => str.length,
+    array: (arr: any[]) => arr.length,
+    any: (val: any) => {
+      if (typeof val === 'string') return val.length;
+      if (Array.isArray(val)) return val.length;
+      return 0;
+    },
+  },
+  {
+    arity: 'unary',
+    returns: 'number',
+    category: 'transform',
+    description: 'Returns the length of a string or array',
+    aliases: ['len', 'count', 'size'],
+  }
+);
+
+export default [length];

package/src/core/operators/transform/pad.ts

@@ -0,0 +1,40 @@
+/**
+ * Pad Operators
+ *
+ * String padding operations.
+ */
+
+import { ternaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Pad start - pads the beginning of a string
+ */
+export const padStart: Operator = ternaryOp<string, number, string>(
+  'padStart',
+  (str, length, padChar) => str.padStart(length, padChar),
+  {
+    params: ['string', 'number', 'string'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Pads the beginning of a string to a specified length',
+    aliases: ['lpad'],
+  }
+);
+
+/**
+ * Pad end - pads the end of a string
+ */
+export const padEnd: Operator = ternaryOp<string, number, string>(
+  'padEnd',
+  (str, length, padChar) => str.padEnd(length, padChar),
+  {
+    params: ['string', 'number', 'string'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Pads the end of a string to a specified length',
+    aliases: ['rpad'],
+  }
+);
+
+export default [padStart, padEnd];

package/src/core/operators/transform/replace.ts

@@ -0,0 +1,38 @@
+/**
+ * Replace Operators
+ *
+ * String replacement operations.
+ */
+
+import { ternaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Replace - replaces first occurrence
+ */
+export const replace: Operator = ternaryOp<string, string, string>(
+  'replace',
+  (str, search, replacement) => str.replace(search, replacement),
+  {
+    params: ['string', 'string', 'string'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Replaces the first occurrence of a substring',
+  }
+);
+
+/**
+ * Replace all - replaces all occurrences
+ */
+export const replaceAll: Operator = ternaryOp<string, string, string>(
+  'replaceAll',
+  (str, search, replacement) => str.replaceAll(search, replacement),
+  {
+    params: ['string', 'string', 'string'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Replaces all occurrences of a substring',
+  }
+);
+
+export default [replace, replaceAll];

package/src/core/operators/transform/substring.ts

@@ -0,0 +1,69 @@
+/**
+ * Substring Operators
+ *
+ * String extraction operations.
+ */
+
+import { binaryOp, ternaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Substring with start and end
+ */
+export const substring: Operator = ternaryOp<string, number, number>(
+  'substring',
+  (str, start, end) => str.substring(start, end),
+  {
+    params: ['string', 'number', 'number'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Extracts a portion of a string between start and end indices',
+    aliases: ['substr'],
+  }
+);
+
+/**
+ * Slice - similar to substring but handles negative indices
+ */
+export const slice: Operator = ternaryOp<string, number, number>(
+  'slice',
+  (str, start, end) => str.slice(start, end),
+  {
+    params: ['string', 'number', 'number'],
+    returns: 'string',
+    category: 'transform',
+    description: 'Extracts a portion of a string (supports negative indices)',
+  }
+);
+
+/**
+ * Left - get first n characters
+ */
+export const left: Operator = binaryOp<string, number>(
+  'left',
+  (str, n) => str.slice(0, n),
+  {
+    leftType: 'string',
+    rightType: 'number',
+    returns: 'string',
+    category: 'transform',
+    description: 'Returns the first n characters of a string',
+  }
+);
+
+/**
+ * Right - get last n characters
+ */
+export const right: Operator = binaryOp<string, number>(
+  'right',
+  (str, n) => str.slice(-n),
+  {
+    leftType: 'string',
+    rightType: 'number',
+    returns: 'string',
+    category: 'transform',
+    description: 'Returns the last n characters of a string',
+  }
+);
+
+export default [substring, slice, left, right];

package/src/core/operators/transform/trim.ts

@@ -0,0 +1,54 @@
+/**
+ * Trim Operators
+ *
+ * String trimming operations.
+ */
+
+import { unaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Trim - removes whitespace from both ends
+ */
+export const trim: Operator = unaryOp<string>(
+  'trim',
+  (a) => a.trim(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Removes whitespace from both ends of a string',
+  }
+);
+
+/**
+ * Trim start - removes whitespace from beginning
+ */
+export const trimStart: Operator = unaryOp<string>(
+  'trimStart',
+  (a) => a.trimStart(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Removes whitespace from the beginning of a string',
+    aliases: ['ltrim', 'trimLeft'],
+  }
+);
+
+/**
+ * Trim end - removes whitespace from end
+ */
+export const trimEnd: Operator = unaryOp<string>(
+  'trimEnd',
+  (a) => a.trimEnd(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Removes whitespace from the end of a string',
+    aliases: ['rtrim', 'trimRight'],
+  }
+);
+
+export default [trim, trimStart, trimEnd];

package/src/core/operators/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Core Operator Type System
+ *
+ * Provides a formal type structure for operators that enables
+ * compile-time validation, introspection, and documentation generation.
+ */
+
+/**
+ * Supported parameter types for operator inputs
+ */
+export type ParameterType = 'string' | 'number' | 'boolean' | 'date' | 'array' | 'any';
+
+/**
+ * Parameter descriptor for operator inputs
+ */
+export interface OperatorParameter {
+  /** Parameter name for documentation/debugging */
+  name: string;
+  /** Expected type of this parameter */
+  type: ParameterType;
+  /** Human-readable description */
+  description?: string;
+  /** Whether this parameter is optional */
+  optional?: boolean;
+}
+
+/**
+ * Arity classification for operators
+ */
+export type OperatorArity = 'unary' | 'binary' | 'ternary' | 'variadic';
+
+/**
+ * Return type classification
+ */
+export type OperatorReturnType = 'boolean' | 'number' | 'string' | 'date' | 'array' | 'any';
+
+/**
+ * Category for operator grouping
+ */
+export type OperatorCategory =
+  | 'comparison'   // equals, notEquals, greaterThan, lessThan, etc.
+  | 'logical'      // and, or, not, xor
+  | 'arithmetic'   // add, subtract, multiply, divide, etc.
+  | 'string'       // contains, startsWith, endsWith, regex, etc.
+  | 'date'         // date comparisons and operations
+  | 'array'        // array operations (contains, in, isEmpty)
+  | 'phonetic'     // soundex, nysiis, caverphone2
+  | 'similarity'   // cosineSimilarity, etc.
+  | 'transform';   // trim, upper, lower, concat, substring, etc.
+
+/**
+ * Core Operator descriptor type
+ *
+ * Represents a complete operator definition including metadata,
+ * parameter specifications, and implementation.
+ */
+export interface Operator<
+  TParams extends OperatorParameter[] = OperatorParameter[],
+  TReturn extends OperatorReturnType = OperatorReturnType
+> {
+  /** Unique operator name (e.g., 'equals', 'contains') */
+  name: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  /** Operator category for grouping */
+  category: OperatorCategory;
+
+  /** Arity classification */
+  arity: OperatorArity;
+
+  /** Parameter definitions */
+  parameters: TParams;
+
+  /** Return type */
+  returns: TReturn;
+
+  /** The actual implementation function */
+  implementation: (...args: any[]) => any;
+
+  /** Optional aliases for this operator */
+  aliases?: string[];
+
+  /** Supported input types (for polymorphic operators like equals) */
+  supportedTypes?: ParameterType[];
+}
+
+/**
+ * Type-specific operator implementation
+ * Used for polymorphic operators that work across multiple types
+ */
+export interface TypedImplementation<T = any> {
+  type: ParameterType;
+  implementation: (...args: T[]) => any;
+}
+
+/**
+ * Polymorphic operator with multiple type-specific implementations
+ */
+export interface PolymorphicOperator extends Omit<Operator, 'implementation'> {
+  /** Map of type -> implementation */
+  implementations: Record<ParameterType, (...args: any[]) => any>;
+
+  /** Default implementation for 'any' type */
+  defaultImplementation?: (...args: any[]) => any;
+}
+
+/**
+ * Result of operator validation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  warnings?: string[];
+}
+
+/**
+ * Operator documentation export format
+ */
+export interface OperatorDoc {
+  name: string;
+  description?: string;
+  category: OperatorCategory;
+  arity: OperatorArity;
+  parameters: OperatorParameter[];
+  returns: OperatorReturnType;
+  aliases?: string[];
+  supportedTypes?: ParameterType[];
+  examples?: OperatorExample[];
+}
+
+/**
+ * Example usage for documentation
+ */
+export interface OperatorExample {
+  input: any[];
+  output: any;
+  description?: string;
+}

package/src/core/parser/errors.ts

@@ -0,0 +1,77 @@
+/**
+ * Custom error class for expression parsing errors.
+ *
+ * Provides detailed position information so users can locate
+ * exactly where in their expression the error occurred.
+ *
+ * Example error message:
+ *   ParseError: Unexpected character '@' at position 5
+ *   Input: $age @= 18
+ *              ^
+ */
+export class ParseError extends Error {
+  /**
+   * The character position in the input string where the error occurred.
+   * Zero-indexed from the start of the expression.
+   */
+  public readonly position: number;
+
+  /**
+   * The original input string that was being parsed.
+   * Stored so we can generate helpful error messages.
+   */
+  public readonly input?: string;
+
+  constructor(message: string, position: number, input?: string) {
+    // Build a detailed error message with position indicator
+    let fullMessage = `${message} at position ${position}`;
+
+    // If we have the input, show the problematic location
+    if (input !== undefined) {
+      fullMessage += `\nInput: ${input}\n       ${' '.repeat(position)}^`;
+    }
+
+    super(fullMessage);
+    this.name = 'ParseError';
+    this.position = position;
+    this.input = input;
+
+    // Maintain proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, ParseError.prototype);
+  }
+}
+
+/**
+ * Error thrown during tokenization phase.
+ * Indicates a problem with the lexical structure of the input.
+ *
+ * Common causes:
+ * - Unterminated string literal
+ * - Invalid character
+ * - Malformed number
+ */
+export class TokenizeError extends ParseError {
+  constructor(message: string, position: number, input?: string) {
+    super(message, position, input);
+    this.name = 'TokenizeError';
+    Object.setPrototypeOf(this, TokenizeError.prototype);
+  }
+}
+
+/**
+ * Error thrown during the parsing phase.
+ * Indicates a problem with the syntactic structure.
+ *
+ * Common causes:
+ * - Unexpected token
+ * - Missing operand
+ * - Unbalanced parentheses
+ * - Invalid operator usage
+ */
+export class SyntaxError extends ParseError {
+  constructor(message: string, position: number, input?: string) {
+    super(message, position, input);
+    this.name = 'SyntaxError';
+    Object.setPrototypeOf(this, SyntaxError.prototype);
+  }
+}

package/src/core/parser/index.ts

@@ -0,0 +1,133 @@
+/**
+ * Expression Parser Module
+ *
+ * Parses human-readable expression strings into S-expression condition arrays.
+ *
+ * Usage:
+ * ──────
+ * The parser is invoked via the ['expr', string] format in conditions:
+ *
+ *   const rule = {
+ *     condition: ['expr', '$age >= 18 and $status == "active"']
+ *   };
+ *
+ * This gets parsed to:
+ *
+ *   ['and', ['greaterThanOrEquals', '$age', 18], ['equals', '$status', 'active']]
+ *
+ * Supported Syntax:
+ * ─────────────────
+ * - Infix: $a > 5, $name contains "test"
+ * - Prefix (functional): gt($a, 5), contains($name, "test")
+ * - All aliases: >, gt, greaterThan all work
+ * - Multi-value: $x == 'a' or 'b' or 'c' → in($x, ['a', 'b', 'c'])
+ *
+ * Architecture:
+ * ─────────────
+ * 1. Tokenizer converts string to token stream
+ * 2. Pratt parser converts tokens to S-expression array
+ *
+ * Both phases are modular with small, focused files for maintainability.
+ */
+
+import type { Condition } from '../types/condition';
+import type { OperatorTable } from './types';
+import { tokenize } from './tokenizer';
+import { parseExpressionFromTokens } from './parser';
+import { createDefaultOperatorTable } from './operators';
+
+// Module-level cached operator table
+let cachedOperatorTable: OperatorTable | null = null;
+
+/**
+ * Gets the operator table, creating it if needed.
+ * Cached for performance since it's static.
+ */
+function getOperatorTable(): OperatorTable {
+  if (!cachedOperatorTable) {
+    cachedOperatorTable = createDefaultOperatorTable();
+  }
+  return cachedOperatorTable;
+}
+
+/**
+ * Parses a human-readable expression string into a condition array.
+ *
+ * @param expression - The expression string to parse
+ * @returns The parsed condition in S-expression format
+ *
+ * @example
+ * parseExpression('$age >= 18')
+ * // Returns: ['greaterThanOrEquals', '$age', 18]
+ *
+ * @example
+ * parseExpression('$name contains "test" and $active')
+ * // Returns: ['and', ['contains', '$name', 'test'], '$active']
+ *
+ * @example
+ * parseExpression('$status == "a" or "b" or "c"')
+ * // Returns: ['in', '$status', ['a', 'b', 'c']]
+ */
+export function parseExpression(expression: string): Condition {
+  const operatorTable = getOperatorTable();
+
+  // Phase 1: Tokenize
+  const tokens = tokenize(expression, operatorTable);
+
+  // Phase 2: Parse
+  const result = parseExpressionFromTokens(tokens, operatorTable, expression);
+
+  return result as Condition;
+}
+
+/**
+ * Checks if a condition input is an expression tuple ['expr', string].
+ *
+ * @param input - The condition input to check
+ * @returns True if it's an expression tuple
+ */
+export function isExpressionTuple(input: unknown): input is ['expr', string] {
+  return (
+    Array.isArray(input) &&
+    input.length === 2 &&
+    input[0] === 'expr' &&
+    typeof input[1] === 'string'
+  );
+}
+
+/**
+ * Processes a condition input, parsing expression tuples if present.
+ *
+ * If the input is ['expr', string], parses the string.
+ * Otherwise returns the input unchanged.
+ *
+ * @param input - The condition input (array or expression tuple)
+ * @returns The processed condition
+ */
+export function processConditionInput(input: unknown): Condition {
+  if (isExpressionTuple(input)) {
+    return parseExpression(input[1]);
+  }
+  return input as Condition;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Re-exports
+// ═══════════════════════════════════════════════════════════════════════
+
+// Types
+export type { Token, TokenType, OperatorInfo, OperatorTable } from './types';
+
+// Errors
+export { ParseError, TokenizeError, SyntaxError } from './errors';
+
+// Tokenizer (for advanced use cases)
+export { tokenize } from './tokenizer';
+
+// Operators (for extending the parser)
+export {
+  buildOperatorTable,
+  createDefaultOperatorTable,
+  OPERATOR_DEFINITIONS,
+  resolveAlias
+} from './operators';