@higher.archi/boe 1.0.0

package/src/core/operators/date/generators.ts

@@ -0,0 +1,232 @@
+/**
+ * Date Generator Operators
+ *
+ * Operators that generate dates relative to now.
+ * Takes a numeric offset and returns a Date.
+ */
+
+import { unaryOp } from '../operator';
+import { Operator } from '../types';
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Add months to a date, handling edge cases properly
+ */
+function addMonthsToDate(date: Date, months: number): Date {
+  const d = new Date(date);
+  const originalDay = d.getDate();
+  d.setMonth(d.getMonth() + months);
+  // Handle month overflow (e.g., Jan 31 + 1 month = Mar 3)
+  if (d.getDate() !== originalDay) {
+    d.setDate(0); // Set to last day of previous month
+  }
+  return d;
+}
+
+/**
+ * Add years to a date, handling leap year edge cases
+ */
+function addYearsToDate(date: Date, years: number): Date {
+  const d = new Date(date);
+  const originalDay = d.getDate();
+  d.setFullYear(d.getFullYear() + years);
+  // Handle Feb 29 -> Feb 28 for non-leap years
+  if (d.getDate() !== originalDay) {
+    d.setDate(0);
+  }
+  return d;
+}
+
+// =============================================================================
+// Time Constants
+// =============================================================================
+
+const MS_PER_SECOND = 1000;
+const MS_PER_MINUTE = 60 * MS_PER_SECOND;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+const MS_PER_WEEK = 7 * MS_PER_DAY;
+
+// =============================================================================
+// "Ago" Operators (Past)
+// =============================================================================
+
+export const secondsAgo: Operator = unaryOp<number>(
+  'secondsAgo',
+  (n) => new Date(Date.now() - n * MS_PER_SECOND),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N seconds ago from now',
+  }
+);
+
+export const minutesAgo: Operator = unaryOp<number>(
+  'minutesAgo',
+  (n) => new Date(Date.now() - n * MS_PER_MINUTE),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N minutes ago from now',
+  }
+);
+
+export const hoursAgo: Operator = unaryOp<number>(
+  'hoursAgo',
+  (n) => new Date(Date.now() - n * MS_PER_HOUR),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N hours ago from now',
+  }
+);
+
+export const daysAgo: Operator = unaryOp<number>(
+  'daysAgo',
+  (n) => new Date(Date.now() - n * MS_PER_DAY),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N days ago from now',
+  }
+);
+
+export const weeksAgo: Operator = unaryOp<number>(
+  'weeksAgo',
+  (n) => new Date(Date.now() - n * MS_PER_WEEK),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N weeks ago from now',
+  }
+);
+
+export const monthsAgo: Operator = unaryOp<number>(
+  'monthsAgo',
+  (n) => addMonthsToDate(new Date(), -n),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N months ago from now',
+  }
+);
+
+export const yearsAgo: Operator = unaryOp<number>(
+  'yearsAgo',
+  (n) => addYearsToDate(new Date(), -n),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N years ago from now',
+  }
+);
+
+// =============================================================================
+// "From Now" Operators (Future)
+// =============================================================================
+
+export const secondsFromNow: Operator = unaryOp<number>(
+  'secondsFromNow',
+  (n) => new Date(Date.now() + n * MS_PER_SECOND),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N seconds from now',
+  }
+);
+
+export const minutesFromNow: Operator = unaryOp<number>(
+  'minutesFromNow',
+  (n) => new Date(Date.now() + n * MS_PER_MINUTE),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N minutes from now',
+  }
+);
+
+export const hoursFromNow: Operator = unaryOp<number>(
+  'hoursFromNow',
+  (n) => new Date(Date.now() + n * MS_PER_HOUR),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N hours from now',
+  }
+);
+
+export const daysFromNow: Operator = unaryOp<number>(
+  'daysFromNow',
+  (n) => new Date(Date.now() + n * MS_PER_DAY),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N days from now',
+  }
+);
+
+export const weeksFromNow: Operator = unaryOp<number>(
+  'weeksFromNow',
+  (n) => new Date(Date.now() + n * MS_PER_WEEK),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N weeks from now',
+  }
+);
+
+export const monthsFromNow: Operator = unaryOp<number>(
+  'monthsFromNow',
+  (n) => addMonthsToDate(new Date(), n),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N months from now',
+  }
+);
+
+export const yearsFromNow: Operator = unaryOp<number>(
+  'yearsFromNow',
+  (n) => addYearsToDate(new Date(), n),
+  {
+    paramType: 'number',
+    returns: 'date',
+    category: 'date',
+    description: 'Returns a date N years from now',
+  }
+);
+
+export default [
+  // Past
+  secondsAgo,
+  minutesAgo,
+  hoursAgo,
+  daysAgo,
+  weeksAgo,
+  monthsAgo,
+  yearsAgo,
+  // Future
+  secondsFromNow,
+  minutesFromNow,
+  hoursFromNow,
+  daysFromNow,
+  weeksFromNow,
+  monthsFromNow,
+  yearsFromNow,
+];

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

@@ -0,0 +1,63 @@
+/**
+ * Date Operators
+ *
+ * Exports all date/temporal operators for registry registration.
+ *
+ * Categories:
+ * - Generators: Create dates relative to now (minutesAgo, daysFromNow)
+ * - Arithmetic: Add/subtract time units (addDays, subtractMonths)
+ * - Differences: Calculate differences between dates (diffMilliseconds, diffDays)
+ * - Comparisons: Compare two dates (isBefore, isAfter, isSameDay)
+ * - Extraction: Extract components from dates (getYear, getMonth, getDayOfWeek)
+ * - Boundaries: Snap dates to boundaries (startOfDay, endOfMonth)
+ * - Checks: Check date properties (isWeekend, isLeapYear, isFuture)
+ * - Constants: Special date values (now, today, tomorrow, yesterday)
+ * - Range: Range checks (isBetween)
+ */
+
+import generatorOps from './generators';
+import arithmeticOps from './arithmetic';
+import differenceOps from './differences';
+import comparisonOps from './comparisons';
+import extractionOps from './extraction';
+import boundaryOps from './boundaries';
+import checkOps from './checks';
+import constantOps from './constants';
+import rangeOps from './range';
+
+// Re-export individual operators
+export * from './generators';
+export * from './arithmetic';
+export * from './differences';
+export * from './comparisons';
+export * from './extraction';
+export * from './boundaries';
+export * from './checks';
+export * from './constants';
+export * from './range';
+
+/**
+ * All date operators as an array for bulk registration
+ */
+export const dateOperators = [
+  // Generators (14)
+  ...generatorOps,
+  // Arithmetic (14)
+  ...arithmeticOps,
+  // Differences (8)
+  ...differenceOps,
+  // Comparisons (6)
+  ...comparisonOps,
+  // Extraction (9)
+  ...extractionOps,
+  // Boundaries (8)
+  ...boundaryOps,
+  // Checks (6)
+  ...checkOps,
+  // Constants (4)
+  ...constantOps,
+  // Range (1)
+  ...rangeOps,
+];
+
+export default dateOperators;

package/src/core/operators/date/range.ts

@@ -0,0 +1,39 @@
+/**
+ * Date Range Operators
+ *
+ * Operators that check if dates fall within ranges.
+ */
+
+import { ternaryOp } from '../operator';
+import { Operator } from '../types';
+
+// =============================================================================
+// Range Operators
+// =============================================================================
+
+/**
+ * Checks if a date falls between two other dates (inclusive).
+ *
+ * Usage: ['isBetween', dateToCheck, startDate, endDate]
+ *
+ * Returns true if startDate <= dateToCheck <= endDate
+ */
+export const isBetween: Operator = ternaryOp<Date, Date, Date>(
+  'isBetween',
+  (date, start, end) => {
+    const time = date.getTime();
+    const startTime = start.getTime();
+    const endTime = end.getTime();
+    return time >= startTime && time <= endTime;
+  },
+  {
+    params: ['date', 'date', 'date'],
+    returns: 'boolean',
+    category: 'date',
+    description: 'Returns true if the date falls between start and end dates (inclusive)',
+  }
+);
+
+export default [
+  isBetween,
+];

package/src/core/operators/evaluator.ts

@@ -0,0 +1,245 @@
+/**
+ * Operator Evaluator
+ *
+ * Evaluates operators with runtime type resolution
+ * and value binding.
+ */
+
+import { Operator, ParameterType, PolymorphicOperator, ValidationResult } from './types';
+import { OperatorRegistry } from './registry';
+import { isPolymorphic } from './operator';
+
+/**
+ * Infer the type of a value at runtime
+ */
+export function inferType(value: unknown): ParameterType {
+  if (value === null || value === undefined) {
+    return 'any';
+  }
+
+  if (typeof value === 'string') {
+    return 'string';
+  }
+
+  if (typeof value === 'number') {
+    return 'number';
+  }
+
+  if (typeof value === 'boolean') {
+    return 'boolean';
+  }
+
+  if (value instanceof Date) {
+    return 'date';
+  }
+
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+
+  return 'any';
+}
+
+/**
+ * Evaluation context for resolving values
+ */
+export interface EvaluationContext {
+  /** Variables available for resolution */
+  variables?: Record<string, unknown>;
+  /** Custom type resolver */
+  typeResolver?: (value: unknown) => ParameterType;
+}
+
+/**
+ * Result of operator evaluation
+ */
+export interface EvaluationResult<T = unknown> {
+  success: boolean;
+  value?: T;
+  error?: string;
+}
+
+/**
+ * Operator Evaluator
+ *
+ * Handles the execution of operators with proper type resolution.
+ */
+export class OperatorEvaluator {
+  constructor(private registry: OperatorRegistry) {}
+
+  /**
+   * Evaluate an operator by name with given arguments
+   */
+  evaluate(
+    operatorName: string,
+    args: unknown[],
+    context?: EvaluationContext
+  ): EvaluationResult {
+    // Get the operator
+    const op = this.registry.get(operatorName);
+    if (!op) {
+      return {
+        success: false,
+        error: `Unknown operator: ${operatorName}`,
+      };
+    }
+
+    // Validate argument count
+    const validation = this.registry.validate(operatorName, args.length);
+    if (!validation.valid) {
+      return {
+        success: false,
+        error: validation.error,
+      };
+    }
+
+    try {
+      // Get the appropriate implementation
+      const impl = this.getImplementation(op, args, context);
+      if (!impl) {
+        return {
+          success: false,
+          error: `No implementation found for operator '${operatorName}' with given types`,
+        };
+      }
+
+      // Execute the operator
+      const result = impl(...args);
+      return {
+        success: true,
+        value: result,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  /**
+   * Get the appropriate implementation for the operator
+   */
+  private getImplementation(
+    op: Operator | PolymorphicOperator,
+    args: unknown[],
+    context?: EvaluationContext
+  ): ((...args: unknown[]) => unknown) | undefined {
+    if (!isPolymorphic(op)) {
+      return op.implementation;
+    }
+
+    // For polymorphic operators, resolve type from first argument
+    const firstArg = args[0];
+    const typeResolver = context?.typeResolver ?? inferType;
+    const type = typeResolver(firstArg);
+
+    // Try to get type-specific implementation
+    if (op.implementations[type]) {
+      return op.implementations[type];
+    }
+
+    // Fall back to default/any implementation
+    return op.defaultImplementation ?? op.implementations.any;
+  }
+
+  /**
+   * Evaluate a condition expression
+   *
+   * Format: [operator, ...operands]
+   */
+  evaluateCondition(
+    condition: [string, ...unknown[]],
+    context?: EvaluationContext
+  ): EvaluationResult<boolean> {
+    const [operatorName, ...operands] = condition;
+
+    // Resolve any variable references in operands
+    const resolvedOperands = context?.variables
+      ? operands.map((op) => this.resolveValue(op, context))
+      : operands;
+
+    const result = this.evaluate(operatorName, resolvedOperands, context);
+
+    if (!result.success) {
+      return { success: false, error: result.error };
+    }
+
+    return {
+      success: true,
+      value: Boolean(result.value),
+    };
+  }
+
+  /**
+   * Evaluate an arithmetic expression
+   *
+   * Format: [operator, ...operands]
+   */
+  evaluateExpression(
+    expression: [string, ...unknown[]],
+    context?: EvaluationContext
+  ): EvaluationResult<number> {
+    const [operatorName, ...operands] = expression;
+
+    // Resolve any variable references in operands
+    const resolvedOperands = context?.variables
+      ? operands.map((op) => this.resolveValue(op, context))
+      : operands;
+
+    const result = this.evaluate(operatorName, resolvedOperands, context);
+
+    if (!result.success) {
+      return { success: false, error: result.error };
+    }
+
+    if (typeof result.value !== 'number') {
+      return {
+        success: false,
+        error: `Expression did not return a number: ${typeof result.value}`,
+      };
+    }
+
+    return {
+      success: true,
+      value: result.value,
+    };
+  }
+
+  /**
+   * Resolve a value, handling variable references
+   */
+  private resolveValue(value: unknown, context: EvaluationContext): unknown {
+    // Handle variable references (e.g., "$variableName")
+    if (typeof value === 'string' && value.startsWith('$') && context.variables) {
+      const varName = value.slice(1);
+      return context.variables[varName] ?? value;
+    }
+
+    return value;
+  }
+
+  /**
+   * Validate a condition at compile time
+   */
+  validateCondition(condition: [string, ...unknown[]]): ValidationResult {
+    const [operatorName, ...operands] = condition;
+
+    if (typeof operatorName !== 'string') {
+      return { valid: false, error: 'Operator name must be a string' };
+    }
+
+    if (!this.registry.has(operatorName)) {
+      return { valid: false, error: `Unknown operator: ${operatorName}` };
+    }
+
+    return this.registry.validate(operatorName, operands.length);
+  }
+}
+
+/**
+ * Create an evaluator with a registry
+ */
+export function createEvaluator(registry: OperatorRegistry): OperatorEvaluator {
+  return new OperatorEvaluator(registry);
+}