@higher.archi/boe 1.0.0

package/src/core/operators/registry.ts

@@ -0,0 +1,254 @@
+/**
+ * Operator Registry
+ *
+ * Central registry for all operators with introspection,
+ * validation, and lookup capabilities.
+ */
+
+import {
+  Operator,
+  OperatorArity,
+  OperatorCategory,
+  OperatorDoc,
+  OperatorReturnType,
+  ParameterType,
+  PolymorphicOperator,
+  ValidationResult,
+} from './types';
+import { isPolymorphic } from './operator';
+
+/**
+ * Central registry for operators
+ */
+export class OperatorRegistry {
+  private operators: Map<string, Operator | PolymorphicOperator> = new Map();
+  private aliasMap: Map<string, string> = new Map();
+  private categoryIndex: Map<OperatorCategory, Set<string>> = new Map();
+  private arityIndex: Map<OperatorArity, Set<string>> = new Map();
+
+  /**
+   * Register an operator
+   */
+  register(op: Operator | PolymorphicOperator): this {
+    this.operators.set(op.name, op);
+
+    // Index aliases
+    op.aliases?.forEach((alias) => this.aliasMap.set(alias, op.name));
+
+    // Index by category
+    if (!this.categoryIndex.has(op.category)) {
+      this.categoryIndex.set(op.category, new Set());
+    }
+    this.categoryIndex.get(op.category)!.add(op.name);
+
+    // Index by arity
+    if (!this.arityIndex.has(op.arity)) {
+      this.arityIndex.set(op.arity, new Set());
+    }
+    this.arityIndex.get(op.arity)!.add(op.name);
+
+    return this;
+  }
+
+  /**
+   * Register multiple operators
+   */
+  registerAll(ops: (Operator | PolymorphicOperator)[]): this {
+    ops.forEach((op) => this.register(op));
+    return this;
+  }
+
+  /**
+   * Get operator by name or alias
+   */
+  get(name: string): Operator | PolymorphicOperator | undefined {
+    const resolvedName = this.aliasMap.get(name) ?? name;
+    return this.operators.get(resolvedName);
+  }
+
+  /**
+   * Get implementation function for a specific type
+   */
+  getImplementation(
+    name: string,
+    type?: ParameterType
+  ): ((...args: any[]) => any) | undefined {
+    const op = this.get(name);
+    if (!op) return undefined;
+
+    if (isPolymorphic(op)) {
+      if (type && op.implementations[type]) {
+        return op.implementations[type];
+      }
+      return op.defaultImplementation ?? op.implementations.any;
+    }
+
+    return op.implementation;
+  }
+
+  /**
+   * Check if operator exists
+   */
+  has(name: string): boolean {
+    const resolvedName = this.aliasMap.get(name) ?? name;
+    return this.operators.has(resolvedName);
+  }
+
+  /**
+   * Get all operators by category
+   */
+  getByCategory(category: OperatorCategory): (Operator | PolymorphicOperator)[] {
+    const names = this.categoryIndex.get(category);
+    if (!names) return [];
+    return [...names].map((name) => this.operators.get(name)!);
+  }
+
+  /**
+   * Get all operators by arity
+   */
+  getByArity(arity: OperatorArity): (Operator | PolymorphicOperator)[] {
+    const names = this.arityIndex.get(arity);
+    if (!names) return [];
+    return [...names].map((name) => this.operators.get(name)!);
+  }
+
+  /**
+   * Get all operators by return type
+   */
+  getByReturnType(
+    returns: OperatorReturnType
+  ): (Operator | PolymorphicOperator)[] {
+    return [...this.operators.values()].filter((op) => op.returns === returns);
+  }
+
+  /**
+   * Get operators that support a specific input type
+   */
+  getBySupportedType(type: ParameterType): (Operator | PolymorphicOperator)[] {
+    return [...this.operators.values()].filter((op) => {
+      if (isPolymorphic(op)) {
+        return type in op.implementations;
+      }
+      return op.supportedTypes?.includes(type) ?? true;
+    });
+  }
+
+  /**
+   * Validate operator call at compile time
+   */
+  validate(name: string, argCount: number, argTypes?: ParameterType[]): ValidationResult {
+    const op = this.get(name);
+    if (!op) {
+      return { valid: false, error: `Unknown operator: ${name}` };
+    }
+
+    // Validate argument count
+    const expectedCount = this.getExpectedArgCount(op);
+    if (op.arity !== 'variadic') {
+      if (argCount !== expectedCount) {
+        return {
+          valid: false,
+          error: `Operator '${name}' expects ${expectedCount} argument(s), got ${argCount}`,
+        };
+      }
+    } else if (argCount < 1) {
+      return {
+        valid: false,
+        error: `Variadic operator '${name}' requires at least 1 argument`,
+      };
+    }
+
+    // Validate argument types if provided
+    const warnings: string[] = [];
+    if (argTypes && op.parameters.length > 0) {
+      for (let i = 0; i < argTypes.length && i < op.parameters.length; i++) {
+        const expectedType = op.parameters[i].type;
+        const actualType = argTypes[i];
+        if (expectedType !== 'any' && actualType !== 'any' && expectedType !== actualType) {
+          warnings.push(
+            `Argument ${i + 1} expects type '${expectedType}', got '${actualType}'`
+          );
+        }
+      }
+    }
+
+    return { valid: true, warnings: warnings.length > 0 ? warnings : undefined };
+  }
+
+  /**
+   * Get expected argument count for an operator
+   */
+  private getExpectedArgCount(op: Operator | PolymorphicOperator): number {
+    switch (op.arity) {
+      case 'unary':
+        return 1;
+      case 'binary':
+        return 2;
+      case 'ternary':
+        return 3;
+      case 'variadic':
+        return -1;
+    }
+  }
+
+  /**
+   * Get all registered operator names
+   */
+  getAllNames(): string[] {
+    return [...this.operators.keys()];
+  }
+
+  /**
+   * Get all registered operators
+   */
+  getAll(): (Operator | PolymorphicOperator)[] {
+    return [...this.operators.values()];
+  }
+
+  /**
+   * Get all aliases
+   */
+  getAliases(): Map<string, string> {
+    return new Map(this.aliasMap);
+  }
+
+  /**
+   * Export all operators for documentation
+   */
+  toDocumentation(): OperatorDoc[] {
+    return [...this.operators.values()].map((op) => ({
+      name: op.name,
+      description: op.description,
+      category: op.category,
+      arity: op.arity,
+      parameters: op.parameters,
+      returns: op.returns,
+      aliases: op.aliases,
+      supportedTypes: isPolymorphic(op)
+        ? (Object.keys(op.implementations) as ParameterType[])
+        : op.supportedTypes,
+    }));
+  }
+
+  /**
+   * Get count of registered operators
+   */
+  get size(): number {
+    return this.operators.size;
+  }
+
+  /**
+   * Clear all registered operators
+   */
+  clear(): void {
+    this.operators.clear();
+    this.aliasMap.clear();
+    this.categoryIndex.clear();
+    this.arityIndex.clear();
+  }
+}
+
+/**
+ * Default global registry instance
+ */
+export const defaultRegistry = new OperatorRegistry();

package/src/core/operators/similarity/cosine.ts

@@ -0,0 +1,27 @@
+/**
+ * Cosine Similarity Operator
+ *
+ * Measures the cosine of the angle between two text vectors.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+import { cosineSimilarity as cosineSim } from '../../../functions/similarity';
+
+/**
+ * Cosine similarity - returns similarity score between 0 and 1
+ */
+export const cosineSimilarity: Operator = binaryOp<string>(
+  'cosineSimilarity',
+  (a, b) => cosineSim(a, b),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'number',
+    category: 'similarity',
+    description: 'Returns the cosine similarity between two strings (0 to 1)',
+    aliases: ['textSimilarity'],
+  }
+);
+
+export default [cosineSimilarity];

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

@@ -0,0 +1,18 @@
+/**
+ * Similarity Operators
+ *
+ * Exports all similarity operators for registry registration.
+ */
+
+import cosineOps from './cosine';
+
+export * from './cosine';
+
+/**
+ * All similarity operators as an array for bulk registration
+ */
+export const similarityOperators = [
+  ...cosineOps,
+];
+
+export default similarityOperators;

package/src/core/operators/string/contains.ts

@@ -0,0 +1,42 @@
+/**
+ * Contains Operator
+ *
+ * Checks if a string contains a substring.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Contains operator - checks if string contains substring
+ */
+export const contains: Operator = binaryOp<string>(
+  'contains',
+  (a, b) => a.includes(b),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string contains a substring',
+    aliases: ['includes'],
+  }
+);
+
+/**
+ * Contains ignore case - case-insensitive substring check
+ */
+export const containsIgnoreCase: Operator = binaryOp<string>(
+  'containsIgnoreCase',
+  (a, b) => a.toLowerCase().includes(b.toLowerCase()),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string contains a substring, ignoring case',
+    aliases: ['includesIgnoreCase'],
+  }
+);
+
+export default [contains, containsIgnoreCase];

package/src/core/operators/string/empty.ts

@@ -0,0 +1,55 @@
+/**
+ * Empty String Operators
+ *
+ * Checks if a string is empty or not.
+ */
+
+import { unaryOp, binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Is empty operator - checks if string is empty or whitespace only
+ */
+export const isEmpty: Operator = unaryOp<string>(
+  'isEmpty',
+  (a) => a.trim().length === 0,
+  {
+    paramType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string is empty or contains only whitespace',
+    aliases: ['blank', 'isBlank'],
+  }
+);
+
+/**
+ * Is not empty operator
+ */
+export const isNotEmpty: Operator = unaryOp<string>(
+  'isNotEmpty',
+  (a) => a.trim().length > 0,
+  {
+    paramType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string is not empty and contains non-whitespace characters',
+    aliases: ['notBlank', 'isNotBlank'],
+  }
+);
+
+/**
+ * Has length - checks if string has exact length
+ */
+export const hasLength: Operator = binaryOp<string, number>(
+  'hasLength',
+  (a, len) => a.length === len,
+  {
+    leftType: 'string',
+    rightType: 'number',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string has an exact length',
+  }
+);
+
+export default [isEmpty, isNotEmpty, hasLength];

package/src/core/operators/string/ends-with.ts

@@ -0,0 +1,40 @@
+/**
+ * Ends With Operator
+ *
+ * Checks if a string ends with a suffix.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Ends with operator
+ */
+export const endsWith: Operator = binaryOp<string>(
+  'endsWith',
+  (a, b) => a.endsWith(b),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string ends with a suffix',
+  }
+);
+
+/**
+ * Ends with ignore case
+ */
+export const endsWithIgnoreCase: Operator = binaryOp<string>(
+  'endsWithIgnoreCase',
+  (a, b) => a.toLowerCase().endsWith(b.toLowerCase()),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string ends with a suffix, ignoring case',
+  }
+);
+
+export default [endsWith, endsWithIgnoreCase];

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

@@ -0,0 +1,30 @@
+/**
+ * String Operators
+ *
+ * Exports all string operators for registry registration.
+ */
+
+import containsOps from './contains';
+import startsWithOps from './starts-with';
+import endsWithOps from './ends-with';
+import regexOps from './regex';
+import emptyOps from './empty';
+
+export * from './contains';
+export * from './starts-with';
+export * from './ends-with';
+export * from './regex';
+export * from './empty';
+
+/**
+ * All string operators as an array for bulk registration
+ */
+export const stringOperators = [
+  ...containsOps,
+  ...startsWithOps,
+  ...endsWithOps,
+  ...regexOps,
+  ...emptyOps,
+];
+
+export default stringOperators;

package/src/core/operators/string/regex.ts

@@ -0,0 +1,42 @@
+/**
+ * Regex Operator
+ *
+ * Tests if a string matches a regular expression pattern.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Regex operator - tests if string matches pattern
+ */
+export const regex: Operator = binaryOp<string>(
+  'regex',
+  (a, pattern) => new RegExp(pattern).test(a),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Tests if a string matches a regular expression pattern',
+    aliases: ['matches', 'match'],
+  }
+);
+
+/**
+ * Regex ignore case
+ */
+export const regexIgnoreCase: Operator = binaryOp<string>(
+  'regexIgnoreCase',
+  (a, pattern) => new RegExp(pattern, 'i').test(a),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Tests if a string matches a regular expression pattern, ignoring case',
+    aliases: ['matchesIgnoreCase'],
+  }
+);
+
+export default [regex, regexIgnoreCase];

package/src/core/operators/string/starts-with.ts

@@ -0,0 +1,40 @@
+/**
+ * Starts With Operator
+ *
+ * Checks if a string starts with a prefix.
+ */
+
+import { binaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Starts with operator
+ */
+export const startsWith: Operator = binaryOp<string>(
+  'startsWith',
+  (a, b) => a.startsWith(b),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string starts with a prefix',
+  }
+);
+
+/**
+ * Starts with ignore case
+ */
+export const startsWithIgnoreCase: Operator = binaryOp<string>(
+  'startsWithIgnoreCase',
+  (a, b) => a.toLowerCase().startsWith(b.toLowerCase()),
+  {
+    leftType: 'string',
+    rightType: 'string',
+    returns: 'boolean',
+    category: 'string',
+    description: 'Checks if a string starts with a prefix, ignoring case',
+  }
+);
+
+export default [startsWith, startsWithIgnoreCase];

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

@@ -0,0 +1,74 @@
+/**
+ * Case Transformation Operators
+ *
+ * String case transformation operations.
+ */
+
+import { unaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Upper case
+ */
+export const upper: Operator = unaryOp<string>(
+  'upper',
+  (a) => a.toUpperCase(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Converts a string to uppercase',
+    aliases: ['toUpperCase', 'uppercase'],
+  }
+);
+
+/**
+ * Lower case
+ */
+export const lower: Operator = unaryOp<string>(
+  'lower',
+  (a) => a.toLowerCase(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Converts a string to lowercase',
+    aliases: ['toLowerCase', 'lowercase'],
+  }
+);
+
+/**
+ * Capitalize - first letter uppercase
+ */
+export const capitalize: Operator = unaryOp<string>(
+  'capitalize',
+  (a) => a.charAt(0).toUpperCase() + a.slice(1).toLowerCase(),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Capitalizes the first letter of a string',
+  }
+);
+
+/**
+ * Title case - capitalize each word
+ */
+export const titleCase: Operator = unaryOp<string>(
+  'titleCase',
+  (a) =>
+    a
+      .toLowerCase()
+      .split(' ')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' '),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Converts a string to title case (capitalize each word)',
+    aliases: ['toTitleCase'],
+  }
+);
+
+export default [upper, lower, capitalize, titleCase];

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

@@ -0,0 +1,54 @@
+/**
+ * Concat Operators
+ *
+ * String concatenation operations.
+ */
+
+import { variadicOp, binaryOp, unaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Concat - concatenates one or more strings
+ */
+export const concat: Operator = variadicOp<string>(
+  'concat',
+  (...args) => args.join(''),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Concatenates one or more strings',
+    aliases: ['join', '+'],
+  }
+);
+
+/**
+ * Repeat - repeats a string n times
+ */
+export const repeat: Operator = binaryOp<string, number>(
+  'repeat',
+  (str, n) => str.repeat(n),
+  {
+    leftType: 'string',
+    rightType: 'number',
+    returns: 'string',
+    category: 'transform',
+    description: 'Repeats a string n times',
+  }
+);
+
+/**
+ * Reverse - reverses a string
+ */
+export const reverse: Operator = unaryOp<string>(
+  'reverse',
+  (str) => str.split('').reverse().join(''),
+  {
+    paramType: 'string',
+    returns: 'string',
+    category: 'transform',
+    description: 'Reverses a string',
+  }
+);
+
+export default [concat, repeat, reverse];