@wildo-ai/saas-backend-lib 1.0.1

package/src/databases/services/aggregation/__tests__/window-function-processor.test.ts

@@ -0,0 +1,598 @@
+/**
+ * Unit Tests for WindowFunctionProcessorBackendService
+ *
+ * Tests in-memory window function processing:
+ * - PERCENT_OF_TOTAL: value / sum * 100
+ * - DIFFERENCE: current - previous
+ * - PERCENT_CHANGE: (current - prev) / prev * 100
+ * - MOVING_AVG: average of last N rows
+ * - RUNNING_TOTAL (fallback): cumulative sum
+ * - RUNNING_AVG (fallback): cumulative average
+ * - RANK / DENSE_RANK: ranking by source value
+ * - LAG / LEAD: shifted value access
+ * - Partitioning: segmented windows via partitionBy
+ *
+ * @see chart-system-architecture.md Milestone T.1
+ */
+
+import 'reflect-metadata';
+import { WindowFunctionProcessorBackendService } from '~wildo-backend-lib/databases/services/aggregation/window-function-processor.backend.service';
+import { WindowFunctionType } from '@wildo-ai/saas-models';
+import type { AggregationQueryResponseRow, WindowFunction } from '@wildo-ai/saas-models';
+import { MockLoggerService } from '~wildo-backend-lib/monitoring/logger/services/__tests__/mock-logger.service';
+
+function createProcessor(): WindowFunctionProcessorBackendService {
+  return new WindowFunctionProcessorBackendService(new MockLoggerService() as any);
+}
+
+// =============================================================================
+// TESTS
+// =============================================================================
+
+describe('WindowFunctionProcessorBackendService', () => {
+  let processor: WindowFunctionProcessorBackendService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    processor = createProcessor();
+  });
+
+  // ── PERCENT_OF_TOTAL ──────────────────────────────────────
+
+  describe('PERCENT_OF_TOTAL', () => {
+    it('should compute percentage of total for each row', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { category: 'A', count: 25 },
+        { category: 'B', count: 50 },
+        { category: 'C', count: 25 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'pct', sourceRef: 'count', type: WindowFunctionType.PERCENT_OF_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].pct).toBe(25);
+      expect(data[1].pct).toBe(50);
+      expect(data[2].pct).toBe(25);
+    });
+
+    it('should return null when total is 0', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 0 },
+        { count: 0 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'pct', sourceRef: 'count', type: WindowFunctionType.PERCENT_OF_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].pct).toBeNull();
+      expect(data[1].pct).toBeNull();
+    });
+  });
+
+  // ── DIFFERENCE ────────────────────────────────────────────
+
+  describe('DIFFERENCE', () => {
+    it('should compute difference from previous row', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { month: '2025-01', count: 10 },
+        { month: '2025-02', count: 15 },
+        { month: '2025-03', count: 12 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'diff', sourceRef: 'count', type: WindowFunctionType.DIFFERENCE },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].diff).toBeNull(); // No previous
+      expect(data[1].diff).toBe(5);    // 15 - 10
+      expect(data[2].diff).toBe(-3);   // 12 - 15
+    });
+  });
+
+  // ── PERCENT_CHANGE ────────────────────────────────────────
+
+  describe('PERCENT_CHANGE', () => {
+    it('should compute percent change from previous row', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 100 },
+        { count: 150 },
+        { count: 120 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'pct_change', sourceRef: 'count', type: WindowFunctionType.PERCENT_CHANGE },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].pct_change).toBeNull();   // No previous
+      expect(data[1].pct_change).toBe(50);     // (150 - 100) / 100 * 100
+      expect(data[2].pct_change).toBe(-20);    // (120 - 150) / 150 * 100
+    });
+
+    it('should return null when previous value is 0', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 0 },
+        { count: 10 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'pct_change', sourceRef: 'count', type: WindowFunctionType.PERCENT_CHANGE },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[1].pct_change).toBeNull();
+    });
+  });
+
+  // ── MOVING_AVG ────────────────────────────────────────────
+
+  describe('MOVING_AVG', () => {
+    it('should compute moving average with default window size 3', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: 20 },
+        { count: 30 },
+        { count: 40 },
+        { count: 50 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'ma', sourceRef: 'count', type: WindowFunctionType.MOVING_AVG },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].ma).toBe(10);      // avg(10)
+      expect(data[1].ma).toBe(15);      // avg(10, 20)
+      expect(data[2].ma).toBe(20);      // avg(10, 20, 30)
+      expect(data[3].ma).toBe(30);      // avg(20, 30, 40)
+      expect(data[4].ma).toBe(40);      // avg(30, 40, 50)
+    });
+
+    it('should respect custom windowSize', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: 20 },
+        { count: 30 },
+        { count: 40 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'ma', sourceRef: 'count', type: WindowFunctionType.MOVING_AVG, windowSize: 2 },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].ma).toBe(10);     // avg(10)
+      expect(data[1].ma).toBe(15);     // avg(10, 20)
+      expect(data[2].ma).toBe(25);     // avg(20, 30)
+      expect(data[3].ma).toBe(35);     // avg(30, 40)
+    });
+  });
+
+  // ── RUNNING_TOTAL ─────────────────────────────────────────
+
+  describe('RUNNING_TOTAL', () => {
+    it('should compute cumulative sum', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { amount: 100 },
+        { amount: 200 },
+        { amount: 50 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'cumulative', sourceRef: 'amount', type: WindowFunctionType.RUNNING_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].cumulative).toBe(100);
+      expect(data[1].cumulative).toBe(300);
+      expect(data[2].cumulative).toBe(350);
+    });
+  });
+
+  // ── RUNNING_AVG ───────────────────────────────────────────
+
+  describe('RUNNING_AVG', () => {
+    it('should compute cumulative average', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { amount: 100 },
+        { amount: 200 },
+        { amount: 300 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'cumavg', sourceRef: 'amount', type: WindowFunctionType.RUNNING_AVG },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].cumavg).toBe(100);       // 100/1
+      expect(data[1].cumavg).toBe(150);       // 300/2
+      expect(data[2].cumavg).toBe(200);       // 600/3
+    });
+  });
+
+  // ── RANK ──────────────────────────────────────────────────
+
+  describe('RANK', () => {
+    it('should assign standard ranking with gaps after ties', () => {
+      // Critical test: RANK skips positions after ties.
+      // 5 values: 70, 80, 90, 90, 100
+      // RANK: 1, 2, 3, 3, 5 (gap: no rank 4)
+      const data: AggregationQueryResponseRow[] = [
+        { score: 100 },
+        { score: 90 },
+        { score: 70 },
+        { score: 90 },
+        { score: 80 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'rank', sourceRef: 'score', type: WindowFunctionType.RANK },
+      ];
+
+      processor.process(data, wf);
+
+      // Sorted ascending: 70 (1), 80 (2), 90 (3), 90 (3), 100 (5) — rank 4 is SKIPPED
+      expect(data[2].rank).toBe(1);  // score=70
+      expect(data[4].rank).toBe(2);  // score=80
+      expect(data[1].rank).toBe(3);  // score=90
+      expect(data[3].rank).toBe(3);  // score=90 (tied)
+      expect(data[0].rank).toBe(5);  // score=100 → rank 5, NOT 4 (gap after two rank-3s)
+    });
+  });
+
+  // ── DENSE_RANK ────────────────────────────────────────────
+
+  describe('DENSE_RANK', () => {
+    it('should assign dense ranking with NO gaps after ties', () => {
+      // Same data as RANK test, but DENSE_RANK: 1, 2, 3, 3, 4 (no gap)
+      const data: AggregationQueryResponseRow[] = [
+        { score: 100 },
+        { score: 90 },
+        { score: 70 },
+        { score: 90 },
+        { score: 80 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'drank', sourceRef: 'score', type: WindowFunctionType.DENSE_RANK },
+      ];
+
+      processor.process(data, wf);
+
+      // Sorted: 70 (1), 80 (2), 90 (3), 90 (3), 100 (4) — no gaps
+      expect(data[2].drank).toBe(1);  // score=70
+      expect(data[4].drank).toBe(2);  // score=80
+      expect(data[1].drank).toBe(3);  // score=90
+      expect(data[3].drank).toBe(3);  // score=90 (tied)
+      expect(data[0].drank).toBe(4);  // score=100 → rank 4, NOT 5 (no gap)
+    });
+
+    it('should demonstrate RANK vs DENSE_RANK difference on identical data', () => {
+      // Same data, both window functions applied
+      const data: AggregationQueryResponseRow[] = [
+        { v: 10 },
+        { v: 20 },
+        { v: 20 },
+        { v: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'r', sourceRef: 'v', type: WindowFunctionType.RANK },
+        { ref: 'dr', sourceRef: 'v', type: WindowFunctionType.DENSE_RANK },
+      ];
+
+      processor.process(data, wf);
+
+      // For value=30 (last when sorted):
+      // RANK: 1, 2, 2, 4 → value=30 gets rank 4 (gap)
+      // DENSE_RANK: 1, 2, 2, 3 → value=30 gets rank 3 (no gap)
+      expect(data[3].r).toBe(4);
+      expect(data[3].dr).toBe(3);
+    });
+  });
+
+  // ── LAG ───────────────────────────────────────────────────
+
+  describe('LAG', () => {
+    it('should access previous row value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: 20 },
+        { count: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'prev', sourceRef: 'count', type: WindowFunctionType.LAG },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].prev).toBeNull();  // No previous
+      expect(data[1].prev).toBe(10);
+      expect(data[2].prev).toBe(20);
+    });
+  });
+
+  // ── LEAD ──────────────────────────────────────────────────
+
+  describe('LEAD', () => {
+    it('should access next row value', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: 20 },
+        { count: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'next', sourceRef: 'count', type: WindowFunctionType.LEAD },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].next).toBe(20);
+      expect(data[1].next).toBe(30);
+      expect(data[2].next).toBeNull();  // No next
+    });
+  });
+
+  // ── PARTITIONING ──────────────────────────────────────────
+
+  describe('partitioning', () => {
+    it('should process RUNNING_TOTAL per partition', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { region: 'US', amount: 100 },
+        { region: 'EU', amount: 50 },
+        { region: 'US', amount: 200 },
+        { region: 'EU', amount: 75 },
+      ];
+      const wf: WindowFunction[] = [
+        {
+          ref: 'cum',
+          sourceRef: 'amount',
+          type: WindowFunctionType.RUNNING_TOTAL,
+          partitionBy: 'region',
+        },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].cum).toBe(100);  // US: 100
+      expect(data[1].cum).toBe(50);   // EU: 50
+      expect(data[2].cum).toBe(300);  // US: 100 + 200
+      expect(data[3].cum).toBe(125);  // EU: 50 + 75
+    });
+
+    it('should process PERCENT_OF_TOTAL per partition', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { region: 'US', count: 30 },
+        { region: 'EU', count: 40 },
+        { region: 'US', count: 70 },
+        { region: 'EU', count: 60 },
+      ];
+      const wf: WindowFunction[] = [
+        {
+          ref: 'pct',
+          sourceRef: 'count',
+          type: WindowFunctionType.PERCENT_OF_TOTAL,
+          partitionBy: 'region',
+        },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].pct).toBe(30);   // US: 30/100 * 100
+      expect(data[1].pct).toBe(40);   // EU: 40/100 * 100
+      expect(data[2].pct).toBe(70);   // US: 70/100 * 100
+      expect(data[3].pct).toBe(60);   // EU: 60/100 * 100
+    });
+
+    it('should process DIFFERENCE per partition (first row of EACH partition is null)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { region: 'US', month: '01', count: 10 },
+        { region: 'EU', month: '01', count: 5 },
+        { region: 'US', month: '02', count: 15 },
+        { region: 'EU', month: '02', count: 12 },
+        { region: 'US', month: '03', count: 9 },
+      ];
+      const wf: WindowFunction[] = [
+        {
+          ref: 'diff',
+          sourceRef: 'count',
+          type: WindowFunctionType.DIFFERENCE,
+          partitionBy: 'region',
+        },
+      ];
+
+      processor.process(data, wf);
+
+      // US partition: [10, 15, 9] → diffs: [null, +5, -6]
+      expect(data[0].diff).toBeNull();   // US first → null
+      expect(data[2].diff).toBe(5);      // US: 15 - 10
+      expect(data[4].diff).toBe(-6);     // US: 9 - 15
+
+      // EU partition: [5, 12] → diffs: [null, +7]
+      expect(data[1].diff).toBeNull();   // EU first → null
+      expect(data[3].diff).toBe(7);      // EU: 12 - 5
+    });
+
+    it('should process MOVING_AVG per partition', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { region: 'US', count: 10 },
+        { region: 'EU', count: 100 },
+        { region: 'US', count: 20 },
+        { region: 'EU', count: 200 },
+        { region: 'US', count: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        {
+          ref: 'ma',
+          sourceRef: 'count',
+          type: WindowFunctionType.MOVING_AVG,
+          windowSize: 2,
+          partitionBy: 'region',
+        },
+      ];
+
+      processor.process(data, wf);
+
+      // US partition: [10, 20, 30]
+      expect(data[0].ma).toBe(10);    // avg(10)
+      expect(data[2].ma).toBe(15);    // avg(10, 20)
+      expect(data[4].ma).toBe(25);    // avg(20, 30) — window=2
+
+      // EU partition: [100, 200]
+      expect(data[1].ma).toBe(100);   // avg(100)
+      expect(data[3].ma).toBe(150);   // avg(100, 200)
+    });
+  });
+
+  // ── EDGE CASES ────────────────────────────────────────────
+
+  describe('edge cases', () => {
+    it('should handle empty data', () => {
+      const wf: WindowFunction[] = [
+        { ref: 'cum', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL },
+      ];
+
+      const result = processor.process([], wf);
+
+      expect(result).toHaveLength(0);
+    });
+
+    it('should handle empty window functions', () => {
+      const data: AggregationQueryResponseRow[] = [{ count: 10 }];
+
+      const result = processor.process(data, []);
+
+      expect(result).toBe(data);
+    });
+
+    it('should handle single row', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 42 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'pct', sourceRef: 'count', type: WindowFunctionType.PERCENT_OF_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].pct).toBe(100);
+    });
+
+    it('should apply multiple window functions and verify cross-function consistency', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: 20 },
+        { count: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'cum', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL },
+        { ref: 'diff', sourceRef: 'count', type: WindowFunctionType.DIFFERENCE },
+        { ref: 'pct', sourceRef: 'count', type: WindowFunctionType.PERCENT_OF_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      // Row 0
+      expect(data[0].cum).toBe(10);
+      expect(data[0].diff).toBeNull();
+      expect(data[0].pct).toBeCloseTo(16.67, 1);
+
+      // Row 1
+      expect(data[1].cum).toBe(30);    // 10 + 20
+      expect(data[1].diff).toBe(10);   // 20 - 10
+      expect(data[1].pct).toBeCloseTo(33.33, 1);
+
+      // Row 2
+      expect(data[2].cum).toBe(60);    // 10 + 20 + 30
+      expect(data[2].diff).toBe(10);   // 30 - 20
+      expect(data[2].pct).toBe(50);    // 30/60*100
+
+      // Cross-check: all PERCENT_OF_TOTAL should sum to 100
+      const pctSum = (data[0].pct as number) + (data[1].pct as number) + (data[2].pct as number);
+      expect(pctSum).toBeCloseTo(100, 0);
+
+      // Cross-check: RUNNING_TOTAL of last row = global sum
+      expect(data[2].cum).toBe(10 + 20 + 30);
+    });
+  });
+
+  // ── Negative Values & Financial Scenarios ──────────────────
+
+  describe('negative values', () => {
+    it('RUNNING_TOTAL should handle negative values (P&L scenario)', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { month: 'Jan', profit: 100 },
+        { month: 'Feb', profit: -50 },
+        { month: 'Mar', profit: -80 },
+        { month: 'Apr', profit: 200 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'cum', sourceRef: 'profit', type: WindowFunctionType.RUNNING_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].cum).toBe(100);   // 100
+      expect(data[1].cum).toBe(50);    // 100 + (-50)
+      expect(data[2].cum).toBe(-30);   // 100 + (-50) + (-80)
+      expect(data[3].cum).toBe(170);   // 100 + (-50) + (-80) + 200
+    });
+
+    it('PERCENT_CHANGE should handle sign changes correctly', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: 100 },
+        { val: -50 },  // dropped to negative
+        { val: 25 },   // recovered from negative
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'chg', sourceRef: 'val', type: WindowFunctionType.PERCENT_CHANGE },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].chg).toBeNull();
+      expect(data[1].chg).toBe(-150);  // (-50 - 100) / 100 * 100 = -150%
+      expect(data[2].chg).toBe(-150);  // (25 - (-50)) / (-50) * 100 = -150%
+    });
+
+    it('RUNNING_AVG should maintain precision with mixed values', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { val: 10 },
+        { val: 20 },
+        { val: -30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'ravg', sourceRef: 'val', type: WindowFunctionType.RUNNING_AVG },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].ravg).toBe(10);      // 10/1
+      expect(data[1].ravg).toBe(15);      // 30/2
+      expect(data[2].ravg).toBeCloseTo(0, 5);  // 0/3
+    });
+  });
+
+  // ── Null/Missing Source Values ─────────────────────────────
+
+  describe('null source values', () => {
+    it('RUNNING_TOTAL should treat null as 0', () => {
+      const data: AggregationQueryResponseRow[] = [
+        { count: 10 },
+        { count: null as unknown as number },
+        { count: 30 },
+      ];
+      const wf: WindowFunction[] = [
+        { ref: 'cum', sourceRef: 'count', type: WindowFunctionType.RUNNING_TOTAL },
+      ];
+
+      processor.process(data, wf);
+
+      expect(data[0].cum).toBe(10);
+      expect(data[1].cum).toBe(10);  // null → 0
+      expect(data[2].cum).toBe(40);
+    });
+  });
+});