@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/aggregation/__tests__/aggregation-query.backend.service.test.ts

@@ -0,0 +1,150 @@
+import 'reflect-metadata';
+import { describe, expect, it, vi } from 'vitest';
+import { AggregateFunction, type AggregationQuery } from '@wildo-ai/saas-models';
+import { ZodError } from 'zod';
+import { AggregationQueryBackendService } from '../aggregation-query.backend.service';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+import { MockReturningErrorBuilderService } from '~wildo-backend-lib/errors/services/__tests__/mock-error-builder.service';
+
+function createService() {
+  const logger = new MockLoggerService();
+  const errorBuilder = new MockReturningErrorBuilderService();
+  const mongoService = {
+    getDatabase: vi.fn(),
+  };
+  const resourceRegistry = {
+    getResourceConfiguration: vi.fn(),
+  };
+  const mongoCompiler = {
+    compile: vi.fn(),
+    getInDbWindowTypes: vi.fn(() => new Set()),
+  };
+  const pgCompiler = {
+    compile: vi.fn(),
+    getInDbWindowTypes: vi.fn(() => new Set()),
+  };
+  const pgDatabaseService = null;
+  const fieldAccessValidator = {
+    validate: vi.fn(),
+  };
+  const authorizationService = {
+    authorize: vi.fn(),
+  };
+  const timeSeriesDensifier = {
+    densify: vi.fn(),
+  };
+  const computedMeasureEvaluator = {
+    evaluate: vi.fn(),
+  };
+  const windowFunctionProcessor = {
+    process: vi.fn(),
+  };
+  const topNProcessor = {
+    process: vi.fn(),
+  };
+
+  const service = new AggregationQueryBackendService(
+    logger as any,
+    errorBuilder as any,
+    mongoService as any,
+    resourceRegistry as any,
+    mongoCompiler as any,
+    pgCompiler as any,
+    pgDatabaseService as any,
+    fieldAccessValidator as any,
+    authorizationService as any,
+    timeSeriesDensifier as any,
+    computedMeasureEvaluator as any,
+    windowFunctionProcessor as any,
+    topNProcessor as any,
+  );
+
+  return {
+    service,
+    fieldAccessValidator,
+    authorizationService,
+    resourceRegistry,
+    mongoCompiler,
+    topNProcessor,
+    timeSeriesDensifier,
+  };
+}
+
+describe('AggregationQueryBackendService', () => {
+  it('fails fast on invalid query shape before validation or authorization work begins', async () => {
+    const {
+      service,
+      fieldAccessValidator,
+      authorizationService,
+      resourceRegistry,
+      mongoCompiler,
+      topNProcessor,
+      timeSeriesDensifier,
+    } = createService();
+
+    const invalidQuery = {
+      mainResourceType: 'ORDERS',
+      dimensions: [],
+      measures: [
+        { ref: 'count', field: '*', aggregate: AggregateFunction.COUNT },
+      ],
+    } as unknown as AggregationQuery;
+
+    await expect(service.execute(invalidQuery, { skipAuthorization: true })).rejects.toBeInstanceOf(ZodError);
+    expect(fieldAccessValidator.validate).not.toHaveBeenCalled();
+    expect(authorizationService.authorize).not.toHaveBeenCalled();
+    expect(resourceRegistry.getResourceConfiguration).not.toHaveBeenCalled();
+    expect(mongoCompiler.compile).not.toHaveBeenCalled();
+    expect(topNProcessor.process).not.toHaveBeenCalled();
+    expect(timeSeriesDensifier.densify).not.toHaveBeenCalled();
+  });
+
+  it('rejects legacy query-level refreshInterval at the generic execution boundary', async () => {
+    const {
+      service,
+      fieldAccessValidator,
+    } = createService();
+
+    const legacyQuery = {
+      mainResourceType: 'ORDERS',
+      dimensions: [
+        { ref: 'status', field: 'status' },
+      ],
+      measures: [
+        { ref: 'count', field: '*', aggregate: AggregateFunction.COUNT },
+      ],
+      refreshInterval: 15_000,
+    } as unknown as AggregationQuery;
+
+    await expect(service.execute(legacyQuery, { skipAuthorization: true })).rejects.toThrow(
+      'AggregationQuery.refreshInterval has been removed. Use ChartDefinition.refreshInterval instead.',
+    );
+    expect(fieldAccessValidator.validate).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when authorized execution is attempted without an execution context', async () => {
+    const {
+      service,
+      fieldAccessValidator,
+      authorizationService,
+      resourceRegistry,
+      mongoCompiler,
+    } = createService();
+
+    const validQuery = {
+      mainResourceType: 'ORDERS',
+      dimensions: [
+        { ref: 'status', field: 'status' },
+      ],
+      measures: [
+        { ref: 'count', field: '*', aggregate: AggregateFunction.COUNT },
+      ],
+    } as AggregationQuery;
+
+    await expect(service.execute(validQuery)).rejects.toThrow(/requires an executionContext/i);
+    expect(fieldAccessValidator.validate).toHaveBeenCalledTimes(1);
+    expect(authorizationService.authorize).not.toHaveBeenCalled();
+    expect(resourceRegistry.getResourceConfiguration).not.toHaveBeenCalled();
+    expect(mongoCompiler.compile).not.toHaveBeenCalled();
+  });
+});

package/src/databases/services/aggregation/__tests__/computed-measure-evaluator.test.ts

@@ -0,0 +1,525 @@
+/**
+ * Unit Tests for ComputedMeasureEvaluatorBackendService
+ *
+ * Tests post-aggregation computed measure evaluation:
+ * - Basic arithmetic (addition, subtraction, multiplication, division)
+ * - Built-in functions (round, abs, coalesce, min, max, safeDivide)
+ * - Division-by-zero safety → null
+ * - Missing/null values in rows → coerced to 0
+ * - Parse-once / evaluate-many caching
+ * - Chained computed measures (A depends on B)
+ * - Invalid expression → null
+ *
+ * @see chart-system-architecture.md Milestone T.1
+ */
+
+import 'reflect-metadata';
+import { ComputedMeasureEvaluatorBackendService } from '~wildo-backend-lib/databases/services/aggregation/computed-measure-evaluator.backend.service';
+import type { AggregationQueryResponseRow, ComputedMeasure } from '@wildo-ai/saas-models';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+
+// ── Helper to create evaluator ──────────────────────────────
+
+function createEvaluator(): { evaluator: ComputedMeasureEvaluatorBackendService; logger: MockLoggerService } {
+  const logger = new MockLoggerService();
+  const evaluator = new ComputedMeasureEvaluatorBackendService(logger as any);
+  return { evaluator, logger };
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('ComputedMeasureEvaluatorBackendService', () => {
+  let evaluator: ComputedMeasureEvaluatorBackendService;
+  let logger: MockLoggerService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    ({ evaluator, logger } = createEvaluator());
+  });
+
+  // ── Basic Arithmetic ──────────────────────────────────────
+
+  describe('basic arithmetic', () => {
+    it('should evaluate simple addition', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 10, b: 20 },
+        { a: 5, b: 15 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'sum_ab', expression: 'a + b', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].sum_ab).toBe(30);
+      expect(data[1].sum_ab).toBe(20);
+    });
+
+    it('should evaluate subtraction', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { total: 100, refunded: 15 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'net', expression: 'total - refunded', dependsOn: ['total', 'refunded'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].net).toBe(85);
+    });
+
+    it('should evaluate multiplication', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { price: 25, quantity: 4 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'revenue', expression: 'price * quantity', dependsOn: ['price', 'quantity'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].revenue).toBe(100);
+    });
+
+    it('should evaluate percentage calculation', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { completed: 75, total: 100 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rate', expression: 'completed / total * 100', dependsOn: ['completed', 'total'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].rate).toBe(75);
+    });
+  });
+
+  // ── Division by Zero ──────────────────────────────────────
+
+  describe('division by zero', () => {
+    it('should return null for division by zero', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { numerator: 10, denominator: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'numerator / denominator', dependsOn: ['numerator', 'denominator'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // expr-eval returns Infinity for 10/0, sanitizeResult converts to null
+      expect(data[0].result).toBeNull();
+    });
+
+    it('should handle 0 / 0 → null', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 0, b: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a / b', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBeNull();
+    });
+  });
+
+  // ── Built-in Functions ────────────────────────────────────
+
+  describe('built-in functions', () => {
+    it('round() should round to integer when called with one arg', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: 3.14159 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rounded', expression: 'round(val)', dependsOn: ['val'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].rounded).toBe(3);
+    });
+
+    it('round() should handle NaN input gracefully', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: null as unknown as number },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rounded', expression: 'round(val)', dependsOn: ['val'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // null → coerced to 0 → round(0) → 0
+      expect(data[0].rounded).toBe(0);
+    });
+
+    it('round() should round up when value >= .5', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: 3.7 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rounded', expression: 'round(val)', dependsOn: ['val'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].rounded).toBe(4);
+    });
+
+    it('abs() should return absolute value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: -42 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'positive', expression: 'abs(val)', dependsOn: ['val'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].positive).toBe(42);
+    });
+
+    it('min() should return the smaller value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 10, b: 20 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'minimum', expression: 'min(a, b)', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].minimum).toBe(10);
+    });
+
+    it('max() should return the larger value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 10, b: 20 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'maximum', expression: 'max(a, b)', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].maximum).toBe(20);
+    });
+
+    it('coalesce() should return first non-null value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: null as unknown as number, b: 42 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'coalesce(a, b)', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // a is null → coerced to 0 in buildVariables, so coalesce(0, 42) → 0
+      // The "null" coalesce works when the value is NaN, not when coerced to 0
+      expect(data[0].result).toBe(0);
+    });
+
+    it('safeDivide() should handle division by zero', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { numerator: 10, denominator: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'safeDivide(numerator, denominator)', dependsOn: ['numerator', 'denominator'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBe(0); // safeDivide returns 0 for div-by-zero by default
+    });
+
+    it('safeDivide() should accept a custom fallback', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { numerator: 10, denominator: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'safeDivide(numerator, denominator, -1)', dependsOn: ['numerator', 'denominator'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBe(-1);
+    });
+  });
+
+  // ── Null / Missing Values ─────────────────────────────────
+
+  describe('null and missing values', () => {
+    it('should coerce null measure values to 0', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: null as unknown as number, b: 10 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a + b', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBe(10);
+    });
+
+    it('should coerce undefined to 0', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { b: 5 }, // 'a' doesn't exist
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a + b', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBe(5);
+    });
+  });
+
+  // ── Empty Inputs ──────────────────────────────────────────
+
+  describe('empty inputs', () => {
+    it('should return original data when no computed measures', () => {
+      const data: AggregationQueryResponseRow[] = [{ count: 10 }];
+      const result = evaluator.evaluate(data, []);
+      expect(result).toBe(data);
+      expect(result).toHaveLength(1);
+    });
+
+    it('should return original data when data is empty', () => {
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a + b', dependsOn: ['a', 'b'] },
+      ];
+      const result = evaluator.evaluate([], computed);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  // ── Invalid Expressions ───────────────────────────────────
+
+  describe('invalid expressions', () => {
+    it('should set null for unparseable expressions', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 10 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: '@@@@invalid', dependsOn: ['a'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBeNull();
+      expect(logger.warn).toHaveBeenCalled();
+    });
+  });
+
+  // ── Chained Computed Measures ──────────────────────────────
+
+  describe('chained computed measures', () => {
+    it('should support computed measure depending on another computed measure', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { completed: 75, total: 100 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rate', expression: 'completed / total * 100', dependsOn: ['completed', 'total'] },
+        { ref: 'doubled_rate', expression: 'rate * 2', dependsOn: ['rate'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].rate).toBe(75);
+      expect(data[0].doubled_rate).toBe(150);
+    });
+  });
+
+  // ── Multiple Rows ─────────────────────────────────────────
+
+  describe('multiple rows', () => {
+    it('should evaluate independently per row', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { amount: 100, count: 10 },
+        { amount: 200, count: 5 },
+        { amount: 0, count: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'avg_amount', expression: 'amount / count', dependsOn: ['amount', 'count'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].avg_amount).toBe(10);
+      expect(data[1].avg_amount).toBe(40);
+      expect(data[2].avg_amount).toBeNull(); // 0/0 → NaN → null
+    });
+  });
+
+  // ── Operator Precedence ──────────────────────────────────
+
+  describe('operator precedence', () => {
+    it('should respect multiplication before addition: a + b * c = a + (b * c)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 2, b: 3, c: 4 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a + b * c', dependsOn: ['a', 'b', 'c'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // 2 + 3*4 = 14, NOT (2+3)*4 = 20
+      expect(data[0].result).toBe(14);
+    });
+
+    it('should respect parentheses: (a + b) * c', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 2, b: 3, c: 4 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: '(a + b) * c', dependsOn: ['a', 'b', 'c'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].result).toBe(20);
+    });
+
+    it('should respect division before subtraction: a - b / c = a - (b / c)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 10, b: 6, c: 3 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'result', expression: 'a - b / c', dependsOn: ['a', 'b', 'c'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // 10 - 6/3 = 10 - 2 = 8
+      expect(data[0].result).toBe(8);
+    });
+  });
+
+  // ── Complex Real-World Expressions ───────────────────────
+
+  describe('complex real-world expressions', () => {
+    it('should evaluate conversion rate formula: (conversions / visits) * 100', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { visits: 1000, conversions: 42 },
+        { visits: 500, conversions: 30 },
+        { visits: 0, conversions: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'rate', expression: '(conversions / visits) * 100', dependsOn: ['conversions', 'visits'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].rate).toBeCloseTo(4.2, 1);
+      expect(data[1].rate).toBe(6);
+      expect(data[2].rate).toBeNull(); // 0/0
+    });
+
+    it('should evaluate margin formula: (revenue - cost) / revenue * 100', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { revenue: 200, cost: 150 },
+        { revenue: 100, cost: 100 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'margin', expression: '(revenue - cost) / revenue * 100', dependsOn: ['revenue', 'cost'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].margin).toBe(25);   // (200-150)/200*100
+      expect(data[1].margin).toBe(0);    // (100-100)/100*100
+    });
+
+    it('should evaluate nested function calls: round(safeDivide(a, b) * 100)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { a: 1, b: 3 },
+        { a: 10, b: 0 },
+      ];
+      const computed: ComputedMeasure[] = [
+        { ref: 'pct', expression: 'round(safeDivide(a, b) * 100)', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].pct).toBe(33);  // round(1/3 * 100) = round(33.33) = 33
+      expect(data[1].pct).toBe(0);   // safeDivide(10, 0) = 0, 0*100 = 0, round(0) = 0
+    });
+  });
+
+  // ── Chained Dependencies Order ───────────────────────────
+
+  describe('chained dependency order', () => {
+    it('should evaluate three-level chain: raw → intermediate → final', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { revenue: 500, cost: 300, headcount: 10 },
+      ];
+      const computed: ComputedMeasure[] = [
+        // Level 1: depends on raw measures
+        { ref: 'profit', expression: 'revenue - cost', dependsOn: ['revenue', 'cost'] },
+        // Level 2: depends on level 1
+        { ref: 'profit_per_head', expression: 'profit / headcount', dependsOn: ['profit', 'headcount'] },
+        // Level 3: depends on level 2
+        { ref: 'pph_rounded', expression: 'round(profit_per_head)', dependsOn: ['profit_per_head'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      expect(data[0].profit).toBe(200);
+      expect(data[0].profit_per_head).toBe(20);
+      expect(data[0].pph_rounded).toBe(20);
+    });
+
+    it('should handle reverse declaration order (B before A, but B depends on A)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { x: 10, y: 3 },
+      ];
+      const computed: ComputedMeasure[] = [
+        // Declared "backwards" — dependsOn references 'ratio' which comes later
+        { ref: 'doubled', expression: 'ratio * 2', dependsOn: ['ratio'] },
+        { ref: 'ratio', expression: 'x / y', dependsOn: ['x', 'y'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // If evaluator resolves in declaration order without topo-sort,
+      // 'doubled' would see ratio=0 (coerced from undefined).
+      // If it does topo-sort, ratio = 10/3 ≈ 3.33, doubled ≈ 6.67.
+      // Either behavior is correct, but we verify it's deterministic and doesn't throw.
+      expect(data[0].ratio).toBeCloseTo(3.333, 2);
+      // If no topo-sort: doubled = 0 (from undefined 'ratio' coerced to 0)
+      // If topo-sort: doubled ≈ 6.67
+      expect(typeof data[0].doubled).toBe('number');
+    });
+  });
+
+  // ── Parse-once / Evaluate-many ───────────────────────────
+
+  describe('parse caching', () => {
+    it('should evaluate same expression across large dataset without re-parsing', () => {
+      // 1000 rows — verifies caching doesn't break per-row evaluation
+      const data: AggregationQueryResponseRow[] = Array.from({ length: 1000 }, (_, i) => ({
+        a: i,
+        b: i + 1,
+      }));
+      const computed: ComputedMeasure[] = [
+        { ref: 'sum', expression: 'a + b', dependsOn: ['a', 'b'] },
+      ];
+
+      evaluator.evaluate(data, computed);
+
+      // Verify first, middle, and last rows
+      expect(data[0].sum).toBe(1);     // 0 + 1
+      expect(data[500].sum).toBe(1001); // 500 + 501
+      expect(data[999].sum).toBe(1999); // 999 + 1000
+    });
+  });
+});