@higher.archi/boe 1.0.0

package/src/core/operators/examples.ts

@@ -0,0 +1,233 @@
+/**
+ * Operator Examples
+ *
+ * Demonstrates evaluation for each OperatorCategory.
+ * Run with: npx ts-node packages/mesh/src/core/operators/examples.ts
+ */
+
+import { createDefaultRegistry, createEvaluator } from './index';
+
+const registry = createDefaultRegistry();
+const evaluator = createEvaluator(registry);
+
+console.log('='.repeat(60));
+console.log('OPERATOR EXAMPLES BY CATEGORY');
+console.log('='.repeat(60));
+
+// ============================================================
+// COMPARISON OPERATORS
+// ============================================================
+console.log('\n📊 COMPARISON OPERATORS\n');
+
+// equals
+console.log('equals("hello", "hello"):', evaluator.evaluate('equals', ['hello', 'hello']).value);
+console.log('equals(42, 42):', evaluator.evaluate('equals', [42, 42]).value);
+console.log('equals(42, 43):', evaluator.evaluate('equals', [42, 43]).value);
+
+// equalsIgnoreCase
+console.log('equalsIgnoreCase("Hello", "HELLO"):', evaluator.evaluate('equalsIgnoreCase', ['Hello', 'HELLO']).value);
+
+// notEquals
+console.log('notEquals("foo", "bar"):', evaluator.evaluate('notEquals', ['foo', 'bar']).value);
+
+// greaterThan / lessThan
+console.log('greaterThan(10, 5):', evaluator.evaluate('greaterThan', [10, 5]).value);
+console.log('lessThan(3, 7):', evaluator.evaluate('lessThan', [3, 7]).value);
+console.log('greaterThanOrEquals(5, 5):', evaluator.evaluate('greaterThanOrEquals', [5, 5]).value);
+
+// nullish checks
+console.log('isNull(null):', evaluator.evaluate('isNull', [null]).value);
+console.log('isUndefined(undefined):', evaluator.evaluate('isUndefined', [undefined]).value);
+console.log('isDefined("value"):', evaluator.evaluate('isDefined', ['value']).value);
+console.log('isNullish(null):', evaluator.evaluate('isNullish', [null]).value);
+
+// coalesce
+console.log('coalesce(null, "", undefined, "first valid"):', evaluator.evaluate('coalesce', [null, '', undefined, 'first valid']).value);
+
+// approximatelyEquals
+console.log('approximatelyEquals(0.1 + 0.2, 0.3):', evaluator.evaluate('approximatelyEquals', [0.1 + 0.2, 0.3]).value);
+
+// ============================================================
+// STRING OPERATORS
+// ============================================================
+console.log('\n📝 STRING OPERATORS\n');
+
+// contains
+console.log('contains("hello world", "world"):', evaluator.evaluate('contains', ['hello world', 'world']).value);
+console.log('containsIgnoreCase("Hello World", "WORLD"):', evaluator.evaluate('containsIgnoreCase', ['Hello World', 'WORLD']).value);
+
+// startsWith / endsWith
+console.log('startsWith("hello", "he"):', evaluator.evaluate('startsWith', ['hello', 'he']).value);
+console.log('endsWith("hello", "lo"):', evaluator.evaluate('endsWith', ['hello', 'lo']).value);
+
+// regex
+console.log('regex("test123", "^[a-z]+\\\\d+$"):', evaluator.evaluate('regex', ['test123', '^[a-z]+\\d+$']).value);
+
+// isEmpty / isNotEmpty
+console.log('isEmpty(""):', evaluator.evaluate('isEmpty', ['']).value);
+console.log('isEmpty("   "):', evaluator.evaluate('isEmpty', ['   ']).value);
+console.log('isNotEmpty("hello"):', evaluator.evaluate('isNotEmpty', ['hello']).value);
+
+// ============================================================
+// LOGICAL OPERATORS
+// ============================================================
+console.log('\n🔀 LOGICAL OPERATORS\n');
+
+// and
+console.log('and(true, true, true):', evaluator.evaluate('and', [true, true, true]).value);
+console.log('and(true, false, true):', evaluator.evaluate('and', [true, false, true]).value);
+
+// or
+console.log('or(false, false, true):', evaluator.evaluate('or', [false, false, true]).value);
+console.log('or(false, false, false):', evaluator.evaluate('or', [false, false, false]).value);
+
+// not
+console.log('not(true):', evaluator.evaluate('not', [true]).value);
+console.log('not(false):', evaluator.evaluate('not', [false]).value);
+
+// xor
+console.log('xor(true, false):', evaluator.evaluate('xor', [true, false]).value);
+console.log('xor(true, true):', evaluator.evaluate('xor', [true, true]).value);
+
+// ============================================================
+// ARITHMETIC OPERATORS
+// ============================================================
+console.log('\n🔢 ARITHMETIC OPERATORS\n');
+
+// add (polymorphic - numbers and strings)
+console.log('add(5, 3):', evaluator.evaluate('add', [5, 3]).value);
+console.log('add("hello", " world"):', evaluator.evaluate('add', ['hello', ' world']).value);
+
+// subtract / multiply / divide
+console.log('subtract(10, 4):', evaluator.evaluate('subtract', [10, 4]).value);
+console.log('multiply(6, 7):', evaluator.evaluate('multiply', [6, 7]).value);
+console.log('divide(20, 4):', evaluator.evaluate('divide', [20, 4]).value);
+console.log('modulo(17, 5):', evaluator.evaluate('modulo', [17, 5]).value);
+
+// power / sqrt
+console.log('power(2, 8):', evaluator.evaluate('power', [2, 8]).value);
+console.log('sqrt(64):', evaluator.evaluate('sqrt', [64]).value);
+
+// sum / product / average (variadic)
+console.log('sum(1, 2, 3, 4, 5):', evaluator.evaluate('sum', [1, 2, 3, 4, 5]).value);
+console.log('product(2, 3, 4):', evaluator.evaluate('product', [2, 3, 4]).value);
+console.log('average(10, 20, 30):', evaluator.evaluate('average', [10, 20, 30]).value);
+
+
+// min / max
+console.log('min(5, 3):', evaluator.evaluate('min', [5, 3]).value);
+console.log('max(5, 3):', evaluator.evaluate('max', [5, 3]).value);
+console.log('minAll(5, 2, 8, 1, 9):', evaluator.evaluate('minAll', [5, 2, 8, 1, 9]).value);
+console.log('maxAll(5, 2, 8, 1, 9):', evaluator.evaluate('maxAll', [5, 2, 8, 1, 9]).value);
+
+// rounding
+console.log('round(3.7):', evaluator.evaluate('round', [3.7]).value);
+console.log('floor(3.7):', evaluator.evaluate('floor', [3.7]).value);
+console.log('ceil(3.2):', evaluator.evaluate('ceil', [3.2]).value);
+console.log('abs(-42):', evaluator.evaluate('abs', [-42]).value);
+
+// number checks
+console.log('isEven(4):', evaluator.evaluate('isEven', [4]).value);
+console.log('isOdd(7):', evaluator.evaluate('isOdd', [7]).value);
+console.log('isPositive(5):', evaluator.evaluate('isPositive', [5]).value);
+console.log('isNegative(-3):', evaluator.evaluate('isNegative', [-3]).value);
+
+// ============================================================
+// ARRAY OPERATORS
+// ============================================================
+console.log('\n📚 ARRAY OPERATORS\n');
+
+// arrayContains
+console.log('arrayContains([1, 2, 3], 2):', evaluator.evaluate('arrayContains', [[1, 2, 3], 2]).value);
+console.log('arrayContains([1, 2, 3], 5):', evaluator.evaluate('arrayContains', [[1, 2, 3], 5]).value);
+
+// in (reversed - element in array)
+console.log('in("apple", ["apple", "banana", "cherry"]):', evaluator.evaluate('in', ['apple', ['apple', 'banana', 'cherry']]).value);
+
+// arrayIsEmpty / arrayIsNotEmpty
+console.log('arrayIsEmpty([]):', evaluator.evaluate('arrayIsEmpty', [[]]).value);
+console.log('arrayIsNotEmpty([1, 2]):', evaluator.evaluate('arrayIsNotEmpty', [[1, 2]]).value);
+
+// arrayLength
+console.log('arrayLength([1, 2, 3, 4, 5]):', evaluator.evaluate('arrayLength', [[1, 2, 3, 4, 5]]).value);
+
+// ============================================================
+// TRANSFORM OPERATORS
+// ============================================================
+console.log('\n🔄 TRANSFORM OPERATORS\n');
+
+// trim
+console.log('trim("  hello  "):', `"${evaluator.evaluate('trim', ['  hello  ']).value}"`);
+console.log('trimStart("  hello"):', `"${evaluator.evaluate('trimStart', ['  hello']).value}"`);
+console.log('trimEnd("hello  "):', `"${evaluator.evaluate('trimEnd', ['hello  ']).value}"`);
+
+// case transformations
+console.log('upper("hello"):', evaluator.evaluate('upper', ['hello']).value);
+console.log('lower("HELLO"):', evaluator.evaluate('lower', ['HELLO']).value);
+console.log('capitalize("hello world"):', evaluator.evaluate('capitalize', ['hello world']).value);
+console.log('titleCase("hello world"):', evaluator.evaluate('titleCase', ['hello world']).value);
+
+// substring / slice
+console.log('substring("hello world", 0, 5):', evaluator.evaluate('substring', ['hello world', 0, 5]).value);
+console.log('left("hello world", 5):', evaluator.evaluate('left', ['hello world', 5]).value);
+console.log('right("hello world", 5):', evaluator.evaluate('right', ['hello world', 5]).value);
+
+// replace
+console.log('replace("hello world", "world", "universe"):', evaluator.evaluate('replace', ['hello world', 'world', 'universe']).value);
+console.log('replaceAll("banana", "a", "o"):', evaluator.evaluate('replaceAll', ['banana', 'a', 'o']).value);
+
+// repeat / reverse
+console.log('repeat("ab", 3):', evaluator.evaluate('repeat', ['ab', 3]).value);
+console.log('reverse("hello"):', evaluator.evaluate('reverse', ['hello']).value);
+
+// pad
+console.log('padStart("42", 5, "0"):', evaluator.evaluate('padStart', ['42', 5, '0']).value);
+console.log('padEnd("hi", 5, "!"):', evaluator.evaluate('padEnd', ['hi', 5, '!']).value);
+
+// length
+console.log('stringLength("hello"):', evaluator.evaluate('stringLength', ['hello']).value);
+
+// ============================================================
+// PHONETIC OPERATORS
+// ============================================================
+console.log('\n🔊 PHONETIC OPERATORS\n');
+
+// soundex encoding
+console.log('soundex("Robert"):', evaluator.evaluate('soundex', ['Robert']).value);
+console.log('soundex("Rupert"):', evaluator.evaluate('soundex', ['Rupert']).value);
+
+// soundex match (variadic - matches ANY)
+console.log('soundexMatch("smith", "smyth"):', evaluator.evaluate('soundexMatch', ['smith', 'smyth']).value);
+console.log('soundexMatch("smith", "jones", "smythe", "brown"):', evaluator.evaluate('soundexMatch', ['smith', 'jones', 'smythe', 'brown']).value);
+
+// nysiis
+console.log('nysiis("Johnson"):', evaluator.evaluate('nysiis', ['Johnson']).value);
+console.log('nysiisMatch("johnson", "jonson", "jansen"):', evaluator.evaluate('nysiisMatch', ['johnson', 'jonson', 'jansen']).value);
+
+// caverphone2
+console.log('caverphone2("Thompson"):', evaluator.evaluate('caverphone2', ['Thompson']).value);
+
+// ============================================================
+// SIMILARITY OPERATORS
+// ============================================================
+console.log('\n📏 SIMILARITY OPERATORS\n');
+
+// cosine similarity
+console.log('cosineSimilarity("hello world", "hello there"):', evaluator.evaluate('cosineSimilarity', ['hello world', 'hello there']).value);
+console.log('cosineSimilarity("apple", "apple"):', evaluator.evaluate('cosineSimilarity', ['apple', 'apple']).value);
+console.log('cosineSimilarity("cat", "dog"):', evaluator.evaluate('cosineSimilarity', ['cat', 'dog']).value);
+
+// ============================================================
+// SUMMARY
+// ============================================================
+console.log('\n' + '='.repeat(60));
+console.log(`Total operators registered: ${registry.size}`);
+console.log('='.repeat(60));
+
+// List all operators by category
+const categories = ['comparison', 'string', 'logical', 'arithmetic', 'array', 'transform', 'phonetic', 'similarity'] as const;
+for (const category of categories) {
+  const ops = registry.getByCategory(category);
+  console.log(`\n${category.toUpperCase()} (${ops.length}):`);
+  console.log('  ' + ops.map(op => op.name).join(', '));
+}

package/src/core/operators/index.ts

@@ -0,0 +1,135 @@
+/**
+ * Operators - Formal Operator Type System
+ *
+ * A formal type-based operator system with compile-time validation,
+ * introspection, and documentation capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { createDefaultRegistry, createEvaluator } from './operators';
+ *
+ * const registry = createDefaultRegistry();
+ * const evaluator = createEvaluator(registry);
+ *
+ * // Evaluate a condition
+ * const result = evaluator.evaluateCondition(['equals', 'hello', 'hello']);
+ * console.log(result.value); // true
+ *
+ * // Evaluate an expression
+ * const sum = evaluator.evaluateExpression(['add', 5, 3]);
+ * console.log(sum.value); // 8
+ * ```
+ */
+
+// Import all operators first to ensure proper initialization order
+import { comparisonOperators } from './comparison';
+import { stringOperators } from './string';
+import { logicalOperators } from './logical';
+import { arithmeticOperators } from './arithmetic';
+import { arrayOperators } from './array';
+import { transformOperators } from './transform';
+import { phoneticOperators } from './phonetic';
+import { similarityOperators } from './similarity';
+import { dateOperators } from './date';
+import { OperatorRegistry, defaultRegistry } from './registry';
+
+// Core types
+export * from './types';
+
+// Operator factories
+export * from './operator';
+
+// Registry
+export { OperatorRegistry, defaultRegistry } from './registry';
+
+// Evaluator
+export { OperatorEvaluator, createEvaluator, inferType } from './evaluator';
+export type { EvaluationContext, EvaluationResult } from './evaluator';
+
+// Adapters for backward compatibility
+export {
+  OperatorAdapter,
+  getOperator,
+  getArithmeticOperator,
+  getDefaultAdapter,
+  createAdapter,
+  bindingToEvaluationContext,
+  createEvaluationContext,
+} from './adapters';
+
+// Re-export operator category arrays
+export { comparisonOperators };
+export { stringOperators };
+export { logicalOperators };
+export { arithmeticOperators };
+export { arrayOperators };
+export { transformOperators };
+export { phoneticOperators };
+export { similarityOperators };
+export { dateOperators };
+
+/**
+ * All built-in operators as a single array
+ */
+export const allOperators = [
+  ...comparisonOperators,
+  ...stringOperators,
+  ...logicalOperators,
+  ...arithmeticOperators,
+  ...arrayOperators,
+  ...transformOperators,
+  ...phoneticOperators,
+  ...similarityOperators,
+  ...dateOperators,
+];
+
+/**
+ * Create a new registry with all default operators registered
+ */
+export function createDefaultRegistry(): OperatorRegistry {
+  const registry = new OperatorRegistry();
+  registry.registerAll(allOperators);
+  return registry;
+}
+
+/**
+ * Pre-configured default registry with all operators
+ */
+export const operators = createDefaultRegistry();
+
+/**
+ * Get a typed operator implementation function
+ *
+ * Provides type-safe access to operator implementations by casting the return type.
+ * Returns undefined if the operator is not found.
+ *
+ * @example
+ * ```typescript
+ * const hoursAgo = getTypedOp<Date>('hoursAgo');
+ * const diffDays = getTypedOp<number>('diffDays');
+ * const isBefore = getTypedOp<boolean>('isBefore');
+ *
+ * if (hoursAgo) {
+ *   const date = hoursAgo(24); // date: Date
+ * }
+ * ```
+ *
+ * @param name - The operator name
+ * @param registry - Optional registry to use (defaults to the default registry)
+ * @returns The typed implementation function, or undefined if not found
+ */
+export function getTypedOp<TReturn>(
+  name: string,
+  registry: OperatorRegistry = defaultRegistry
+): ((...args: any[]) => TReturn) | undefined {
+  const op = registry.get(name);
+  if (!op) return undefined;
+
+  // Handle polymorphic operators (have 'implementations' map instead of 'implementation')
+  if ('implementations' in op) {
+    const impl = op.defaultImplementation ?? op.implementations.any;
+    return impl as ((...args: any[]) => TReturn) | undefined;
+  }
+
+  return op.implementation as (...args: any[]) => TReturn;
+}

package/src/core/operators/logical/and.ts

@@ -0,0 +1,25 @@
+/**
+ * And Operator
+ *
+ * Logical AND - returns true if all operands are true.
+ */
+
+import { variadicOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * And operator - returns true if all operands are true
+ */
+export const and: Operator = variadicOp<boolean>(
+  'and',
+  (...args) => args.every(Boolean),
+  {
+    paramType: 'boolean',
+    returns: 'boolean',
+    category: 'logical',
+    description: 'Returns true if all operands are true',
+    aliases: ['&&', 'all'],
+  }
+);
+
+export default [and];

package/src/core/operators/logical/if.ts

@@ -0,0 +1,31 @@
+/**
+ * If Operator (Ternary Conditional)
+ *
+ * Returns one of two values based on a boolean condition.
+ * Equivalent to the ternary operator: condition ? thenValue : elseValue
+ */
+
+import { ternaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * If operator - conditional value selection
+ *
+ * @example
+ * ['if', true, 'yes', 'no']  // returns 'yes'
+ * ['if', false, 100, 0]      // returns 0
+ * ['if', '$isVip', 0.10, 0]  // returns 0.10 if isVip is true
+ */
+export const ifOp: Operator = ternaryOp<boolean, unknown, unknown>(
+  'if',
+  (condition, thenValue, elseValue) => condition ? thenValue : elseValue,
+  {
+    params: ['boolean', 'any', 'any'],
+    returns: 'any',
+    category: 'logical',
+    description: 'Returns thenValue if condition is true, else elseValue',
+    aliases: ['cond', 'ternary', '?:'],
+  }
+);
+
+export default [ifOp];

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

@@ -0,0 +1,30 @@
+/**
+ * Logical Operators
+ *
+ * Exports all logical operators for registry registration.
+ */
+
+import andOps from './and';
+import orOps from './or';
+import notOps from './not';
+import xorOps from './xor';
+import ifOps from './if';
+
+export * from './and';
+export * from './or';
+export * from './not';
+export * from './xor';
+export * from './if';
+
+/**
+ * All logical operators as an array for bulk registration
+ */
+export const logicalOperators = [
+  ...andOps,
+  ...orOps,
+  ...notOps,
+  ...xorOps,
+  ...ifOps,
+];
+
+export default logicalOperators;

package/src/core/operators/logical/not.ts

@@ -0,0 +1,25 @@
+/**
+ * Not Operator
+ *
+ * Logical NOT - negates a boolean value.
+ */
+
+import { unaryOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Not operator - negates a boolean value
+ */
+export const not: Operator = unaryOp<boolean>(
+  'not',
+  (a) => !a,
+  {
+    paramType: 'boolean',
+    returns: 'boolean',
+    category: 'logical',
+    description: 'Negates a boolean value',
+    aliases: ['!', 'negate'],
+  }
+);
+
+export default [not];

package/src/core/operators/logical/or.ts

@@ -0,0 +1,25 @@
+/**
+ * Or Operator
+ *
+ * Logical OR - returns true if any operand is true.
+ */
+
+import { variadicOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Or operator - returns true if any operand is true
+ */
+export const or: Operator = variadicOp<boolean>(
+  'or',
+  (...args) => args.some(Boolean),
+  {
+    paramType: 'boolean',
+    returns: 'boolean',
+    category: 'logical',
+    description: 'Returns true if any operand is true',
+    aliases: ['||', 'any'],
+  }
+);
+
+export default [or];

package/src/core/operators/logical/xor.ts

@@ -0,0 +1,40 @@
+/**
+ * Xor Operator
+ *
+ * Logical XOR - returns true if exactly one operand is true.
+ */
+
+import { binaryOp, variadicOp } from '../operator';
+import { Operator } from '../types';
+
+/**
+ * Xor operator (binary) - returns true if exactly one operand is true
+ */
+export const xor: Operator = binaryOp<boolean>(
+  'xor',
+  (a, b) => a !== b,
+  {
+    leftType: 'boolean',
+    rightType: 'boolean',
+    returns: 'boolean',
+    category: 'logical',
+    description: 'Returns true if exactly one of two operands is true',
+    aliases: ['^'],
+  }
+);
+
+/**
+ * Xor variadic - returns true if an odd number of operands are true
+ */
+export const xorAll: Operator = variadicOp<boolean>(
+  'xorAll',
+  (...args) => args.filter(Boolean).length % 2 === 1,
+  {
+    paramType: 'boolean',
+    returns: 'boolean',
+    category: 'logical',
+    description: 'Returns true if an odd number of operands are true',
+  }
+);
+
+export default [xor, xorAll];