|
| 1 | +// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | +// |
| 3 | +// ADR-0053 Phase 2 (D2): `engine.aggregate({ timezone })` routing. |
| 4 | +// |
| 5 | +// Native driver date bucketing (`date_trunc`) is UTC-only, so a non-UTC |
| 6 | +// reference timezone must force the in-memory path (uniform across drivers) |
| 7 | +// while UTC / unset keeps the native fast path. These tests pin both halves |
| 8 | +// using a driver that advertises native day bucketing and records whether its |
| 9 | +// native `aggregate()` was taken. |
| 10 | + |
| 11 | +import { describe, it, expect } from 'vitest'; |
| 12 | +import { ObjectQL } from './engine.js'; |
| 13 | + |
| 14 | +/** |
| 15 | + * A driver advertising native `day` granularity. Its native `aggregate()` |
| 16 | + * "buckets" in UTC (the only thing a real SQL `date_trunc` can do here) and |
| 17 | + * flags that it ran, so the test can assert which path the engine chose. |
| 18 | + */ |
| 19 | +function makeBucketingDriver(rows: any[]) { |
| 20 | + let nativeAggregateCalls = 0; |
| 21 | + const driver: any = { |
| 22 | + name: 'bucketing-mock', |
| 23 | + version: '0.0.0', |
| 24 | + supports: { queryDateGranularity: { day: true, week: true, month: true, quarter: true, year: true } }, |
| 25 | + async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; }, |
| 26 | + async find() { return rows.slice(); }, |
| 27 | + findStream() { throw new Error('ni'); }, |
| 28 | + async findOne() { return rows[0] ?? null; }, |
| 29 | + async create(_o: string, d: any) { return d; }, |
| 30 | + async update(_o: string, _id: string, d: any) { return d; }, |
| 31 | + async delete() { return true; }, |
| 32 | + async count() { return rows.length; }, |
| 33 | + async bulkCreate(_o: string, r: any[]) { return r; }, |
| 34 | + async bulkUpdate() { return []; }, async bulkDelete() {}, |
| 35 | + async beginTransaction() { return { __trx: true, commit: async () => {}, rollback: async () => {} }; }, |
| 36 | + async commit() {}, async rollback() {}, |
| 37 | + async aggregate(_object: string, ast: any) { |
| 38 | + nativeAggregateCalls += 1; |
| 39 | + // Simulate UTC `date_trunc` day bucketing + sum. |
| 40 | + const buckets = new Map<string, number>(); |
| 41 | + const gran = ast.groupBy?.[0]; |
| 42 | + const field = typeof gran === 'string' ? gran : gran.field; |
| 43 | + for (const r of rows) { |
| 44 | + const day = new Date(String(r[field])).toISOString().slice(0, 10); |
| 45 | + buckets.set(day, (buckets.get(day) ?? 0) + Number(r.amount)); |
| 46 | + } |
| 47 | + return Array.from(buckets, ([closed_at, total]) => ({ closed_at, total })); |
| 48 | + }, |
| 49 | + }; |
| 50 | + return { driver, nativeCalls: () => nativeAggregateCalls }; |
| 51 | +} |
| 52 | + |
| 53 | +// Two events 4h apart straddling the NY midnight: same UTC day (03-01), |
| 54 | +// different NY days (02-29 / 03-01). |
| 55 | +const ROWS = [ |
| 56 | + { closed_at: '2024-03-01T03:00:00.000Z', amount: 10 }, // NY 02-29 |
| 57 | + { closed_at: '2024-03-01T07:00:00.000Z', amount: 5 }, // NY 03-01 |
| 58 | +]; |
| 59 | + |
| 60 | +async function makeEngine(rows: any[]) { |
| 61 | + const { driver, nativeCalls } = makeBucketingDriver(rows); |
| 62 | + const engine = new ObjectQL(); |
| 63 | + engine.registerDriver(driver, true); |
| 64 | + await engine.init(); |
| 65 | + engine.registry.registerObject({ |
| 66 | + name: 'deal', |
| 67 | + fields: { closed_at: { type: 'date' }, amount: { type: 'number' } }, |
| 68 | + } as any); |
| 69 | + return { engine, nativeCalls }; |
| 70 | +} |
| 71 | + |
| 72 | +const dayBucket = { |
| 73 | + groupBy: [{ field: 'closed_at', dateGranularity: 'day' }], |
| 74 | + aggregations: [{ function: 'sum', field: 'amount', alias: 'total' }], |
| 75 | +}; |
| 76 | + |
| 77 | +describe('engine.aggregate timezone routing (ADR-0053 Phase 2)', () => { |
| 78 | + it('UTC / unset takes the native driver fast path', async () => { |
| 79 | + const { engine, nativeCalls } = await makeEngine(ROWS); |
| 80 | + const utc = await engine.aggregate('deal', { ...dayBucket, timezone: 'UTC' } as any); |
| 81 | + expect(nativeCalls()).toBe(1); |
| 82 | + expect(utc).toEqual([{ closed_at: '2024-03-01', total: 15 }]); |
| 83 | + |
| 84 | + const unset = await engine.aggregate('deal', { ...dayBucket } as any); |
| 85 | + expect(nativeCalls()).toBe(2); // native again |
| 86 | + expect(unset).toEqual([{ closed_at: '2024-03-01', total: 15 }]); |
| 87 | + }); |
| 88 | + |
| 89 | + it('non-UTC timezone forces in-memory bucketing on the reference day', async () => { |
| 90 | + const { engine, nativeCalls } = await makeEngine(ROWS); |
| 91 | + const ny = (await engine.aggregate('deal', { |
| 92 | + ...dayBucket, |
| 93 | + timezone: 'America/New_York', |
| 94 | + } as any)).sort((a: any, b: any) => String(a.closed_at).localeCompare(String(b.closed_at))); |
| 95 | + |
| 96 | + expect(nativeCalls()).toBe(0); // native path skipped |
| 97 | + expect(ny).toEqual([ |
| 98 | + { closed_at: '2024-02-29', total: 10 }, |
| 99 | + { closed_at: '2024-03-01', total: 5 }, |
| 100 | + ]); |
| 101 | + }); |
| 102 | +}); |
0 commit comments