@higher.archi/boe 1.0.0

package/src/core/parser/operators/aliases.ts

@@ -0,0 +1,358 @@
+import type { OperatorInfo } from '../types';
+import {
+  PRECEDENCE_AND,
+  PRECEDENCE_COMPARISON,
+  PRECEDENCE_NOT,
+  PRECEDENCE_OR,
+  PRECEDENCE_ADDITIVE,
+  PRECEDENCE_MULTIPLICATIVE
+} from './precedence';
+
+/**
+ * Operator Alias Definitions
+ *
+ * This file defines all the aliases for each operator. An alias is any
+ * way the operator can be written in an expression:
+ *   - Symbol form: >, >=, ==, &&, ||
+ *   - Short form: gt, gte, eq, and, or
+ *   - Full name: greaterThan, greaterThanOrEquals, equals
+ *
+ * Each entry maps to an OperatorInfo with:
+ *   - canonical: The official operator name used in output
+ *   - precedence: Binding power (higher = tighter)
+ *   - associativity: How to group same-precedence operators
+ *   - arity: Number of operands the operator takes
+ *
+ * Note: This is a static definition. For dynamic operators from the
+ * registry, see operator-table.ts which can merge these with registry ops.
+ */
+
+/**
+ * Type alias for the operator definition entries.
+ * Omits 'canonical' since we derive it from the key.
+ */
+type OperatorDef = Omit<OperatorInfo, 'canonical'>;
+
+/**
+ * Core operators with all their aliases.
+ *
+ * Structure: { canonicalName: { def, aliases[] } }
+ *
+ * The canonical name is the one that appears in the output S-expression.
+ * All aliases resolve to this canonical name.
+ */
+export const OPERATOR_DEFINITIONS: Record<
+  string,
+  { def: OperatorDef; aliases: string[] }
+> = {
+  // ═══════════════════════════════════════════════════════════════════
+  // LOGICAL OPERATORS
+  // ═══════════════════════════════════════════════════════════════════
+
+  and: {
+    def: {
+      precedence: PRECEDENCE_AND,
+      associativity: 'left',
+      arity: 'variadic' // and($a, $b, $c) flattens to ['and', $a, $b, $c]
+    },
+    aliases: ['&&']
+  },
+
+  or: {
+    def: {
+      precedence: PRECEDENCE_OR,
+      associativity: 'left',
+      arity: 'variadic' // or($a, $b, $c) flattens to ['or', $a, $b, $c]
+    },
+    aliases: ['||']
+  },
+
+  not: {
+    def: {
+      precedence: PRECEDENCE_NOT,
+      associativity: 'right',
+      arity: 'unary'
+    },
+    aliases: ['!']
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - Relational
+  // ═══════════════════════════════════════════════════════════════════
+
+  greaterThan: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['>', 'gt']
+  },
+
+  greaterThanOrEquals: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['>=', 'gte']
+  },
+
+  lessThan: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['<', 'lt']
+  },
+
+  lessThanOrEquals: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['<=', 'lte']
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - Equality
+  // ═══════════════════════════════════════════════════════════════════
+
+  equals: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['==', 'eq']
+  },
+
+  notEquals: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['!=', 'neq', 'ne']
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - String
+  // ═══════════════════════════════════════════════════════════════════
+
+  contains: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  startsWith: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  endsWith: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  matches: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - String (Case-Insensitive)
+  // ═══════════════════════════════════════════════════════════════════
+
+  containsIgnoreCase: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['icontains']
+  },
+
+  startsWithIgnoreCase: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['istartsWith', 'istartswith']
+  },
+
+  endsWithIgnoreCase: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['iendsWith', 'iendswith']
+  },
+
+  equalsIgnoreCase: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['iequals', 'ieq']
+  },
+
+  notEqualsIgnoreCase: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: ['inotEquals', 'ineq']
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - Membership
+  // ═══════════════════════════════════════════════════════════════════
+
+  in: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary' // $x in [1, 2, 3]
+    },
+    aliases: []
+  },
+
+  notIn: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // COMPARISON OPERATORS - Temporal
+  // ═══════════════════════════════════════════════════════════════════
+
+  isBefore: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  isAfter: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'binary'
+    },
+    aliases: []
+  },
+
+  isBetween: {
+    def: {
+      precedence: PRECEDENCE_COMPARISON,
+      associativity: 'none',
+      arity: 'ternary' // $date isBetween $start and $end
+    },
+    aliases: []
+  },
+
+  // ═══════════════════════════════════════════════════════════════════
+  // ARITHMETIC OPERATORS
+  // ═══════════════════════════════════════════════════════════════════
+
+  add: {
+    def: {
+      precedence: PRECEDENCE_ADDITIVE,
+      associativity: 'left',
+      arity: 'binary'
+    },
+    aliases: ['+']
+  },
+
+  subtract: {
+    def: {
+      precedence: PRECEDENCE_ADDITIVE,
+      associativity: 'left',
+      arity: 'binary'
+    },
+    aliases: ['-']
+  },
+
+  multiply: {
+    def: {
+      precedence: PRECEDENCE_MULTIPLICATIVE,
+      associativity: 'left',
+      arity: 'binary'
+    },
+    aliases: ['*']
+  },
+
+  divide: {
+    def: {
+      precedence: PRECEDENCE_MULTIPLICATIVE,
+      associativity: 'left',
+      arity: 'binary'
+    },
+    aliases: ['/']
+  },
+
+  modulo: {
+    def: {
+      precedence: PRECEDENCE_MULTIPLICATIVE,
+      associativity: 'left',
+      arity: 'binary'
+    },
+    aliases: ['%', 'mod']
+  }
+};
+
+/**
+ * Gets the canonical name for any operator alias.
+ *
+ * @param alias - Any form of the operator (symbol, short, or full)
+ * @returns The canonical operator name, or undefined if not found
+ *
+ * Examples:
+ *   resolveAlias('>') → 'greaterThan'
+ *   resolveAlias('gt') → 'greaterThan'
+ *   resolveAlias('greaterThan') → 'greaterThan'
+ */
+export function resolveAlias(alias: string): string | undefined {
+  // Check if it's already a canonical name
+  if (OPERATOR_DEFINITIONS[alias]) {
+    return alias;
+  }
+
+  // Search through all operators for this alias
+  for (const [canonical, { aliases }] of Object.entries(OPERATOR_DEFINITIONS)) {
+    if (aliases.includes(alias)) {
+      return canonical;
+    }
+  }
+
+  return undefined;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Operator Module
+ *
+ * This module handles operator definitions, aliases, and precedence.
+ * It provides the operator table used by both the tokenizer and parser.
+ *
+ * Key concepts:
+ *   - Canonical name: The official operator name (e.g., 'greaterThan')
+ *   - Alias: Any form that resolves to the canonical (e.g., '>', 'gt')
+ *   - Precedence: Binding power (higher = binds tighter)
+ *   - Associativity: How same-precedence ops group (left, right, none)
+ */
+
+export {
+  buildOperatorTable,
+  createDefaultOperatorTable,
+  isKnownOperator,
+  getCanonicalName
+} from './operator-table';
+
+export { OPERATOR_DEFINITIONS, resolveAlias } from './aliases';
+
+export {
+  PRECEDENCE_OR,
+  PRECEDENCE_AND,
+  PRECEDENCE_NOT,
+  PRECEDENCE_COMPARISON,
+  PRECEDENCE_ADDITIVE,
+  PRECEDENCE_MULTIPLICATIVE,
+  PRECEDENCE_UNARY,
+  PRECEDENCE_PRIMARY,
+  getPrecedenceForCategory
+} from './precedence';
+
+export type { OperatorCategory } from './precedence';

package/src/core/parser/operators/operator-table.ts

@@ -0,0 +1,107 @@
+import type { OperatorInfo, OperatorTable } from '../types';
+import { OPERATOR_DEFINITIONS } from './aliases';
+import { PRECEDENCE_PRIMARY } from './precedence';
+
+/**
+ * Builds the operator lookup table.
+ *
+ * The table maps every possible operator form (symbol, short name,
+ * full name) to its OperatorInfo. This allows O(1) lookup when
+ * tokenizing and parsing.
+ *
+ * Sources:
+ *   1. Static definitions in aliases.ts (core operators)
+ *   2. Dynamic operators from the registry (temporal, custom, etc.)
+ *
+ * @param registryOperators - Optional map of additional operators from registry
+ * @returns Complete operator table with all aliases resolved
+ */
+export function buildOperatorTable(
+  registryOperators?: Map<string, { aliases?: string[] }>
+): OperatorTable {
+  const table: OperatorTable = new Map();
+
+  // ─────────────────────────────────────────────────────────────────────
+  // Add static operator definitions
+  // ─────────────────────────────────────────────────────────────────────
+  for (const [canonical, { def, aliases }] of Object.entries(
+    OPERATOR_DEFINITIONS
+  )) {
+    const info: OperatorInfo = {
+      canonical,
+      ...def
+    };
+
+    // Add the canonical name itself
+    table.set(canonical, info);
+
+    // Add all aliases pointing to same info
+    for (const alias of aliases) {
+      table.set(alias, info);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────
+  // Add dynamic operators from registry (if provided)
+  // ─────────────────────────────────────────────────────────────────────
+  if (registryOperators) {
+    for (const [name, opDef] of registryOperators) {
+      // Skip if already defined in static definitions
+      if (table.has(name)) {
+        continue;
+      }
+
+      // Create operator info with sensible defaults
+      // Most registry operators are functions (temporal, etc.)
+      const info: OperatorInfo = {
+        canonical: name,
+        precedence: PRECEDENCE_PRIMARY, // Functions have highest precedence
+        associativity: 'none',
+        arity: 'binary' // Default assumption, parser handles variadic
+      };
+
+      table.set(name, info);
+
+      // Add any aliases
+      if (opDef.aliases) {
+        for (const alias of opDef.aliases) {
+          if (!table.has(alias)) {
+            table.set(alias, info);
+          }
+        }
+      }
+    }
+  }
+
+  return table;
+}
+
+/**
+ * Creates a default operator table with just the static definitions.
+ * Use this when you don't have access to the full operator registry.
+ */
+export function createDefaultOperatorTable(): OperatorTable {
+  return buildOperatorTable();
+}
+
+/**
+ * Checks if a string is a known operator (in any form).
+ */
+export function isKnownOperator(
+  table: OperatorTable,
+  name: string
+): boolean {
+  return table.has(name);
+}
+
+/**
+ * Gets the canonical name for an operator, or returns the input
+ * if it's not a known operator (might be a function).
+ */
+export function getCanonicalName(
+  table: OperatorTable,
+  name: string
+): string {
+  const info = table.get(name);
+  return info ? info.canonical : name;
+}

package/src/core/parser/operators/precedence.ts

@@ -0,0 +1,94 @@
+/**
+ * Operator Precedence Levels
+ *
+ * These constants define the binding power of operators.
+ * Higher numbers bind more tightly than lower numbers.
+ *
+ * For example, in "$a + $b * $c":
+ *   - * has higher precedence than +
+ *   - So it parses as $a + ($b * $c), not ($a + $b) * $c
+ *
+ * Precedence Scale (1-8):
+ *   1 - Logical OR (lowest, evaluated last)
+ *   2 - Logical AND
+ *   3 - Logical NOT (unary prefix)
+ *   4 - Comparison operators
+ *   5 - Addition and subtraction
+ *   6 - Multiplication and division
+ *   7 - Unary minus (negation)
+ *   8 - Function calls, literals, parentheses (highest)
+ *
+ * Note: Parentheses override precedence - they're always evaluated first.
+ */
+
+/** Logical OR: or, || */
+export const PRECEDENCE_OR = 1;
+
+/** Logical AND: and, && */
+export const PRECEDENCE_AND = 2;
+
+/** Logical NOT (unary): not, ! */
+export const PRECEDENCE_NOT = 3;
+
+/**
+ * Comparison operators:
+ *   - Relational: >, >=, <, <=, gt, gte, lt, lte
+ *   - Equality: ==, !=, equals, notEquals
+ *   - String: contains, startsWith, endsWith, matches
+ *   - Membership: in, notIn
+ *   - Temporal: isBefore, isAfter, isBetween
+ */
+export const PRECEDENCE_COMPARISON = 4;
+
+/** Addition and subtraction: +, - (binary) */
+export const PRECEDENCE_ADDITIVE = 5;
+
+/** Multiplication, division, modulo: *, /, % */
+export const PRECEDENCE_MULTIPLICATIVE = 6;
+
+/** Unary minus (negation): -$x */
+export const PRECEDENCE_UNARY = 7;
+
+/**
+ * Highest precedence:
+ *   - Function calls: daysAgo(7), now()
+ *   - Literals: 42, "hello", true
+ *   - Property refs: $age, $user.name
+ *   - Parenthesized expressions: ($a + $b)
+ */
+export const PRECEDENCE_PRIMARY = 8;
+
+/**
+ * Maps operator categories to their precedence level.
+ * Used by the operator table builder to assign precedence.
+ */
+export type OperatorCategory =
+  | 'logical-or'
+  | 'logical-and'
+  | 'logical-not'
+  | 'comparison'
+  | 'additive'
+  | 'multiplicative'
+  | 'unary'
+  | 'primary';
+
+export function getPrecedenceForCategory(category: OperatorCategory): number {
+  switch (category) {
+    case 'logical-or':
+      return PRECEDENCE_OR;
+    case 'logical-and':
+      return PRECEDENCE_AND;
+    case 'logical-not':
+      return PRECEDENCE_NOT;
+    case 'comparison':
+      return PRECEDENCE_COMPARISON;
+    case 'additive':
+      return PRECEDENCE_ADDITIVE;
+    case 'multiplicative':
+      return PRECEDENCE_MULTIPLICATIVE;
+    case 'unary':
+      return PRECEDENCE_UNARY;
+    case 'primary':
+      return PRECEDENCE_PRIMARY;
+  }
+}