@higher.archi/boe 1.0.0

package/src/engines/pricing/strategy.ts

@@ -0,0 +1,736 @@
+/**
+ * Pricing Engine Strategy
+ *
+ * Executes pricing calculations:
+ * - Resolves scenario values
+ * - Calculates component prices using appropriate pricing mode
+ * - Applies adjustments (discounts, minimums, maximums)
+ * - Computes metrics for comparison
+ */
+
+import { CompiledOperand, CompiledCondition } from '../../core';
+
+import {
+  CompiledPricingRuleSet,
+  CompiledPricingComponent,
+  CompiledPricingMode,
+  CompiledAdjustment,
+  CompiledMetric,
+  CompiledMeter,
+  PricingOptions,
+  PricingResult,
+  ScenarioComparisonResult,
+  ScenarioResult,
+  ComponentResult,
+  AdjustmentResult,
+  MeterResult,
+  PricingSummary
+} from './types';
+
+import {
+  calculateFlat,
+  calculateGraduated,
+  calculateVolume,
+  CalculatorContext,
+  TierCalculationResult,
+  formatCurrency,
+  formatNumber,
+  round,
+  calculateDiscount
+} from './calculator';
+
+// ========================================
+// Simple Value Context
+// ========================================
+
+/**
+ * Simple context for resolving values - no working memory needed.
+ */
+type ValueContext = Record<string, unknown>;
+
+/**
+ * Resolve a compiled operand to its value using simple context.
+ */
+function resolveOperandValue(operand: CompiledOperand, context: ValueContext): unknown {
+  if (operand.type === 'constant') {
+    return operand.value;
+  }
+
+  if (operand.type === 'property') {
+    const { param, path } = operand.ref;
+
+    // First check if the param directly exists in context
+    let value = context[param];
+
+    // If path has elements, traverse them
+    if (path.length > 0 && value !== undefined && value !== null) {
+      for (const key of path) {
+        if (value === null || value === undefined) return undefined;
+        value = (value as Record<string, unknown>)[key];
+      }
+    }
+
+    return value;
+  }
+
+  if (operand.type === 'expression') {
+    return evaluateSimpleExpression(operand.compiled, context);
+  }
+
+  return undefined;
+}
+
+/**
+ * Evaluate a simple expression (arithmetic operations).
+ */
+function evaluateSimpleExpression(expr: CompiledCondition, context: ValueContext): unknown {
+  const { op, operands } = expr;
+
+  if (!operands || operands.length === 0) {
+    return undefined;
+  }
+
+  // Get operand values
+  const values = operands.map(o => resolveOperandValue(o, context));
+
+  // Arithmetic operations
+  switch (op) {
+    case 'add':
+      return (values[0] as number) + (values[1] as number);
+    case 'subtract':
+      return (values[0] as number) - (values[1] as number);
+    case 'multiply':
+      return (values[0] as number) * (values[1] as number);
+    case 'divide':
+      return (values[1] as number) !== 0 ? (values[0] as number) / (values[1] as number) : 0;
+    case 'modulo':
+      return (values[0] as number) % (values[1] as number);
+    case 'power':
+      return Math.pow(values[0] as number, values[1] as number);
+    case 'min':
+      return Math.min(values[0] as number, values[1] as number);
+    case 'max':
+      return Math.max(values[0] as number, values[1] as number);
+    case 'abs':
+      return Math.abs(values[0] as number);
+    case 'ceil':
+      return Math.ceil(values[0] as number);
+    case 'floor':
+      return Math.floor(values[0] as number);
+    case 'round':
+      return Math.round(values[0] as number);
+    case 'sqrt':
+      return Math.sqrt(values[0] as number);
+    default:
+      return values[0];
+  }
+}
+
+/**
+ * Evaluate a condition for discounts.
+ */
+function evaluateCondition(condition: CompiledCondition, context: ValueContext): boolean {
+  const { op, operands, children } = condition;
+
+  // Logical operators
+  if (op === 'and' && children) {
+    return children.every(child => evaluateCondition(child, context));
+  }
+  if (op === 'or' && children) {
+    return children.some(child => evaluateCondition(child, context));
+  }
+  if (op === 'not' && children) {
+    return !evaluateCondition(children[0], context);
+  }
+
+  if (!operands || operands.length < 2) {
+    return false;
+  }
+
+  const left = resolveOperandValue(operands[0], context);
+  const right = resolveOperandValue(operands[1], context);
+
+  // Comparison operators
+  switch (op) {
+    case 'equals':
+      return left === right;
+    case 'notEquals':
+      return left !== right;
+    case 'greaterThan':
+      return (left as number) > (right as number);
+    case 'greaterThanOrEquals':
+      return (left as number) >= (right as number);
+    case 'lessThan':
+      return (left as number) < (right as number);
+    case 'lessThanOrEquals':
+      return (left as number) <= (right as number);
+    default:
+      return false;
+  }
+}
+
+/**
+ * Create a calculator context from value context.
+ */
+function createCalculatorContext(valueContext: ValueContext): CalculatorContext {
+  return {
+    resolve: (operand: CompiledOperand): number => {
+      const value = resolveOperandValue(operand, valueContext);
+      return typeof value === 'number' ? value : 0;
+    }
+  };
+}
+
+// ========================================
+// Pricing Mode Execution
+// ========================================
+
+/**
+ * Execute a pricing mode and return the result.
+ */
+function executePricingMode(
+  pricing: CompiledPricingMode,
+  quantity: number,
+  calcContext: CalculatorContext
+): TierCalculationResult {
+  switch (pricing.mode) {
+    case 'flat':
+      return calculateFlat(quantity, pricing.pricePerUnit, calcContext);
+
+    case 'graduated':
+      return calculateGraduated(quantity, pricing.tiers, calcContext);
+
+    case 'volume':
+      return calculateVolume(quantity, pricing.brackets, calcContext);
+
+    case 'formula': {
+      const total = calcContext.resolve(pricing.calculate);
+      return {
+        total,
+        breakdown: [{
+          tier: 'Formula',
+          range: 'Calculated',
+          units: quantity,
+          rate: quantity > 0 ? total / quantity : 0,
+          subtotal: total
+        }]
+      };
+    }
+
+    case 'multi-meter':
+      throw new Error('Multi-meter should be handled by executeMeter');
+  }
+}
+
+/**
+ * Execute a meter calculation.
+ */
+function executeMeter(
+  meter: CompiledMeter,
+  valueContext: ValueContext,
+  calcContext: CalculatorContext
+): MeterResult {
+  const quantity = resolveOperandValue(meter.quantity, valueContext) as number || 0;
+  const result = executePricingMode(meter.pricing, quantity, calcContext);
+
+  return {
+    id: meter.id,
+    name: meter.name,
+    quantity,
+    unit: meter.unit,
+    tierBreakdown: result.breakdown,
+    subtotal: result.total
+  };
+}
+
+// ========================================
+// Component Execution
+// ========================================
+
+/**
+ * Execute pricing for a single component.
+ */
+function executeComponent(
+  component: CompiledPricingComponent,
+  scenarioId: string,
+  precision: number
+): ComponentResult {
+  // Get scenario values for this component
+  const scenarioValues = component.scenarioValues[scenarioId] || {};
+
+  // Build value context from scenario values
+  const valueContext: ValueContext = { ...scenarioValues };
+
+  const calcContext = createCalculatorContext(valueContext);
+
+  // Resolve quantity
+  const quantity = resolveOperandValue(component.quantity, valueContext) as number || 0;
+
+  // Resolve attributes
+  const attributes: Record<string, unknown> = {};
+  for (const [key, operand] of Object.entries(component.attributes)) {
+    attributes[key] = resolveOperandValue(operand, valueContext);
+  }
+
+  // Handle multi-meter pricing separately
+  if (component.pricing.mode === 'multi-meter') {
+    const meters = component.pricing.meters.map(m =>
+      executeMeter(m, valueContext, calcContext)
+    );
+    const subtotal = round(
+      meters.reduce((sum, m) => sum + m.subtotal, 0),
+      precision
+    );
+
+    return {
+      sku: component.sku,
+      name: component.name,
+      attributes,
+      quantity,
+      unit: component.unit,
+      meters,
+      subtotal
+    };
+  }
+
+  // Execute standard pricing mode
+  const result = executePricingMode(component.pricing, quantity, calcContext);
+
+  return {
+    sku: component.sku,
+    name: component.name,
+    attributes,
+    quantity,
+    unit: component.unit,
+    tierBreakdown: result.breakdown,
+    subtotal: round(result.total, precision)
+  };
+}
+
+// ========================================
+// Adjustment Execution
+// ========================================
+
+/**
+ * Execute adjustments and return results.
+ */
+function executeAdjustments(
+  adjustments: CompiledAdjustment[],
+  componentsTotal: number,
+  valueContext: ValueContext,
+  precision: number
+): { results: AdjustmentResult[]; adjustedTotal: number } {
+  const results: AdjustmentResult[] = [];
+  let currentTotal = componentsTotal;
+
+  for (const adjustment of adjustments) {
+    switch (adjustment.type) {
+      case 'discount': {
+        // Check condition if present
+        if (adjustment.condition) {
+          const conditionMet = evaluateCondition(adjustment.condition, valueContext);
+          if (!conditionMet) continue;
+        }
+
+        const discountAmount = calculateDiscount(
+          currentTotal,
+          adjustment.percent,
+          adjustment.amount
+        );
+
+        if (discountAmount > 0) {
+          results.push({
+            type: 'discount',
+            name: adjustment.name,
+            percent: adjustment.percent,
+            amount: round(-discountAmount, precision)
+          });
+          currentTotal -= discountAmount;
+        }
+        break;
+      }
+
+      case 'minimum': {
+        if (currentTotal < adjustment.amount) {
+          const increase = adjustment.amount - currentTotal;
+          results.push({
+            type: 'minimum',
+            name: adjustment.name,
+            amount: round(increase, precision)
+          });
+          currentTotal = adjustment.amount;
+        }
+        break;
+      }
+
+      case 'maximum': {
+        if (currentTotal > adjustment.amount) {
+          const decrease = currentTotal - adjustment.amount;
+          results.push({
+            type: 'maximum',
+            name: adjustment.name,
+            amount: round(-decrease, precision)
+          });
+          currentTotal = adjustment.amount;
+        }
+        break;
+      }
+    }
+  }
+
+  return {
+    results,
+    adjustedTotal: round(currentTotal, precision)
+  };
+}
+
+// ========================================
+// Metric Computation
+// ========================================
+
+/**
+ * Compute metrics for a pricing result.
+ */
+function computeMetrics(
+  metrics: CompiledMetric[],
+  components: ComponentResult[],
+  summary: PricingSummary,
+  scenarioValues: Record<string, unknown>,
+  precision: number
+): Record<string, number> {
+  const result: Record<string, number> = {};
+
+  // Build context with all values available for metric calculations
+  const context: ValueContext = {
+    ...scenarioValues,
+    summary,
+    componentsTotal: summary.componentsTotal,
+    adjustmentsTotal: summary.adjustmentsTotal,
+    total: summary.total,
+    componentCount: components.length
+  };
+
+  // Add component values by SKU
+  for (const comp of components) {
+    context[comp.sku] = {
+      subtotal: comp.subtotal,
+      quantity: comp.quantity
+    };
+  }
+
+  for (const metric of metrics) {
+    const value = resolveOperandValue(metric.calculate, context);
+    result[metric.id] = round(typeof value === 'number' ? value : 0, precision);
+  }
+
+  return result;
+}
+
+// ========================================
+// Result Formatting
+// ========================================
+
+/**
+ * Format a pricing result as a string.
+ */
+function formatPricingResult(
+  ruleId: string,
+  ruleName: string | undefined,
+  scenario: string | undefined,
+  components: ComponentResult[],
+  adjustments: AdjustmentResult[],
+  summary: PricingSummary,
+  metrics: Record<string, number>,
+  executionTimeMs: number,
+  currency: string,
+  precision: number
+): string {
+  const lines: string[] = [];
+
+  lines.push('╔════════════════════════════════════════════════════════════════╗');
+  lines.push(`║  PRICING RESULT: ${ruleName || ruleId}`.padEnd(66) + '║');
+  if (scenario) {
+    lines.push(`║  Scenario: ${scenario}`.padEnd(66) + '║');
+  }
+  lines.push('╠════════════════════════════════════════════════════════════════╣');
+
+  // Components
+  lines.push('║  COMPONENTS'.padEnd(66) + '║');
+  lines.push('╟────────────────────────────────────────────────────────────────╢');
+
+  for (const comp of components) {
+    const subtotal = formatCurrency(comp.subtotal, currency, precision);
+    lines.push(`║  ${comp.name}`.padEnd(50) + subtotal.padStart(15) + ' ║');
+
+    if (comp.meters) {
+      for (const meter of comp.meters) {
+        const meterTotal = formatCurrency(meter.subtotal, currency, precision);
+        lines.push(`║    └─ ${meter.name}: ${formatNumber(meter.quantity)} ${meter.unit}`.padEnd(50) + meterTotal.padStart(15) + ' ║');
+      }
+    } else if (comp.tierBreakdown && comp.tierBreakdown.length > 1) {
+      for (const tier of comp.tierBreakdown) {
+        const tierTotal = formatCurrency(tier.subtotal, currency, precision);
+        lines.push(`║    └─ ${tier.range}: ${formatNumber(tier.units)} @ ${formatCurrency(tier.rate, currency, 4)}`.padEnd(50) + tierTotal.padStart(15) + ' ║');
+      }
+    }
+  }
+
+  // Adjustments
+  if (adjustments.length > 0) {
+    lines.push('╟────────────────────────────────────────────────────────────────╢');
+    lines.push('║  ADJUSTMENTS'.padEnd(66) + '║');
+
+    for (const adj of adjustments) {
+      const amount = formatCurrency(adj.amount, currency, precision);
+      const label = adj.percent ? `${adj.name} (${adj.percent}%)` : adj.name;
+      lines.push(`║  ${label}`.padEnd(50) + amount.padStart(15) + ' ║');
+    }
+  }
+
+  // Summary
+  lines.push('╠════════════════════════════════════════════════════════════════╣');
+  const total = formatCurrency(summary.total, currency, precision);
+  lines.push(`║  TOTAL`.padEnd(50) + total.padStart(15) + ' ║');
+
+  // Metrics
+  if (Object.keys(metrics).length > 0) {
+    lines.push('╟────────────────────────────────────────────────────────────────╢');
+    lines.push('║  METRICS'.padEnd(66) + '║');
+
+    for (const [key, value] of Object.entries(metrics)) {
+      const formatted = formatCurrency(value, currency, precision);
+      lines.push(`║  ${key}`.padEnd(50) + formatted.padStart(15) + ' ║');
+    }
+  }
+
+  lines.push('╠════════════════════════════════════════════════════════════════╣');
+  lines.push(`║  Processing time: ${executionTimeMs.toFixed(2)}ms`.padEnd(66) + '║');
+  lines.push('╚════════════════════════════════════════════════════════════════╝');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format scenario comparison result as a string.
+ */
+function formatComparisonResult(
+  ruleId: string,
+  scenarios: Record<string, ScenarioResult>,
+  executionTimeMs: number,
+  currency: string,
+  precision: number
+): string {
+  const lines: string[] = [];
+  const scenarioEntries = Object.entries(scenarios);
+
+  lines.push('╔════════════════════════════════════════════════════════════════╗');
+  lines.push(`║  SCENARIO COMPARISON: ${ruleId}`.padEnd(66) + '║');
+  lines.push('╠════════════════════════════════════════════════════════════════╣');
+
+  // Summary table
+  const headers = ['Scenario', 'Components', 'Adjustments', 'Total'];
+  lines.push(`║  ${headers[0].padEnd(20)} ${headers[1].padEnd(12)} ${headers[2].padEnd(12)} ${headers[3].padEnd(12)}`.padEnd(65) + '║');
+  lines.push('╟────────────────────────────────────────────────────────────────╢');
+
+  for (const [, scenario] of scenarioEntries) {
+    const comp = formatCurrency(scenario.summary.componentsTotal, currency, precision);
+    const adj = formatCurrency(scenario.summary.adjustmentsTotal, currency, precision);
+    const total = formatCurrency(scenario.summary.total, currency, precision);
+    lines.push(`║  ${scenario.name.padEnd(20)} ${comp.padEnd(12)} ${adj.padEnd(12)} ${total.padEnd(12)}`.padEnd(65) + '║');
+  }
+
+  lines.push('╠════════════════════════════════════════════════════════════════╣');
+  lines.push(`║  Processing time: ${executionTimeMs.toFixed(2)}ms`.padEnd(66) + '║');
+  lines.push('╚════════════════════════════════════════════════════════════════╝');
+
+  return lines.join('\n');
+}
+
+// ========================================
+// Main Strategy Class
+// ========================================
+
+export class PricingStrategy {
+  /**
+   * Calculate pricing for a single scenario.
+   */
+  calculate(
+    ruleSet: CompiledPricingRuleSet,
+    ruleId: string,
+    options: PricingOptions = {}
+  ): PricingResult {
+    const startTime = performance.now();
+
+    // Find the rule
+    const rule = ruleSet.rules.find(r => r.id === ruleId);
+    if (!rule) {
+      throw new Error(`Rule not found: ${ruleId}`);
+    }
+
+    // Determine scenario
+    const scenarioId = options.scenario
+      || ruleSet.scenarios.defaultScenario
+      || Object.keys(ruleSet.scenarios.definitions)[0];
+
+    if (!scenarioId) {
+      throw new Error('No scenario specified and no default scenario defined');
+    }
+
+    const scenarioDefinition = ruleSet.scenarios.definitions[scenarioId];
+    if (!scenarioDefinition && Object.keys(ruleSet.scenarios.definitions).length > 0) {
+      throw new Error(`Unknown scenario: ${scenarioId}`);
+    }
+
+    // Execute components
+    const components: ComponentResult[] = [];
+    for (const component of rule.components) {
+      const result = executeComponent(
+        component,
+        scenarioId,
+        ruleSet.config.precision
+      );
+      components.push(result);
+      options.onComponent?.(component.sku, result);
+    }
+
+    // Calculate components total
+    const componentsTotal = round(
+      components.reduce((sum, c) => sum + c.subtotal, 0),
+      ruleSet.config.precision
+    );
+
+    // Gather all scenario values for adjustments
+    const allScenarioValues: Record<string, unknown> = {};
+    for (const comp of rule.components) {
+      Object.assign(allScenarioValues, comp.scenarioValues[scenarioId] || {});
+    }
+
+    // Execute adjustments
+    const { results: adjustments, adjustedTotal } = executeAdjustments(
+      rule.adjustments,
+      componentsTotal,
+      allScenarioValues,
+      ruleSet.config.precision
+    );
+
+    for (const adj of adjustments) {
+      options.onAdjustment?.(adj);
+    }
+
+    // Build summary
+    const summary: PricingSummary = {
+      componentsTotal,
+      adjustmentsTotal: round(adjustedTotal - componentsTotal, ruleSet.config.precision),
+      total: adjustedTotal
+    };
+
+    // Compute metrics
+    const metrics = computeMetrics(
+      rule.metrics,
+      components,
+      summary,
+      allScenarioValues,
+      ruleSet.config.precision
+    );
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    const result: PricingResult = {
+      ruleId: rule.id,
+      ruleName: rule.name,
+      scenario: scenarioId,
+      components,
+      adjustments,
+      summary,
+      metrics,
+      executionTimeMs,
+      toString: function() {
+        return formatPricingResult(
+          this.ruleId,
+          this.ruleName,
+          this.scenario,
+          this.components,
+          this.adjustments,
+          this.summary,
+          this.metrics,
+          this.executionTimeMs,
+          ruleSet.config.currency,
+          ruleSet.config.precision
+        );
+      }
+    };
+
+    return result;
+  }
+
+  /**
+   * Calculate pricing for multiple scenarios for comparison.
+   */
+  calculateScenarios(
+    ruleSet: CompiledPricingRuleSet,
+    ruleId: string,
+    scenarioIds?: string[]
+  ): ScenarioComparisonResult {
+    const startTime = performance.now();
+
+    // Determine which scenarios to calculate
+    const scenarios = scenarioIds
+      || Object.keys(ruleSet.scenarios.definitions);
+
+    if (scenarios.length === 0) {
+      throw new Error('No scenarios to calculate');
+    }
+
+    // Calculate each scenario
+    const results: Record<string, ScenarioResult> = {};
+
+    for (const scenarioId of scenarios) {
+      const scenarioDefinition = ruleSet.scenarios.definitions[scenarioId];
+      if (!scenarioDefinition) {
+        throw new Error(`Unknown scenario: ${scenarioId}`);
+      }
+
+      const pricingResult = this.calculate(ruleSet, ruleId, { scenario: scenarioId });
+
+      // Get scenario values for inputs
+      const rule = ruleSet.rules.find(r => r.id === ruleId)!;
+      const inputs: Record<string, unknown> = {};
+      for (const comp of rule.components) {
+        Object.assign(inputs, comp.scenarioValues[scenarioId] || {});
+      }
+
+      results[scenarioId] = {
+        name: scenarioDefinition.name,
+        description: scenarioDefinition.description,
+        inputs,
+        components: pricingResult.components,
+        adjustments: pricingResult.adjustments,
+        summary: pricingResult.summary,
+        metrics: pricingResult.metrics
+      };
+    }
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    const comparisonResult: ScenarioComparisonResult = {
+      rulesetId: ruleSet.id,
+      ruleId,
+      scenarios: results,
+      executionTimeMs,
+      toString: function() {
+        return formatComparisonResult(
+          this.ruleId,
+          this.scenarios,
+          this.executionTimeMs,
+          ruleSet.config.currency,
+          ruleSet.config.precision
+        );
+      }
+    };
+
+    return comparisonResult;
+  }
+}
+
+// Export singleton instance
+export const pricingStrategy = new PricingStrategy();