@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/databases/services/aggregation/time-series-densifier.backend.service.js

@@ -0,0 +1,320 @@
+/** ──────────────────────────────────────────────────────────────
+ * TimeSeriesDensifierBackendService
+ *
+ * Post-query in-memory densification for time-series data.
+ * DB compilers return sparse results; this service fills missing
+ * time buckets before computed measures and window functions.
+ *
+ * Features:
+ *   - Range resolution: explicit dateRange → context filters → global filters → data min/max
+ *   - Timezone-aware bucket generation
+ *   - Max 2,000 bucket guard
+ *   - `_filled: true` metadata on generated rows
+ *   - Fill values: 0 for numeric measures, null for non-numeric
+ *
+ * Ref: Densification spec (Q3) → L1560-1577
+ * Ref: fillMissingBuckets field → L631
+ * Ref: Timezone in densifier → L489
+ * ────────────────────────────────────────────────────────────── */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { AggregateFunction, ErrorType, ErrorCustomMessageReference, TimeGranularity, } from '@wildo-ai/saas-models';
+/** Aggregate functions that always produce numeric results and can safely default to 0 */
+const NUMERIC_AGGREGATES = new Set([
+    AggregateFunction.COUNT,
+    AggregateFunction.COUNT_DISTINCT,
+    AggregateFunction.SUM,
+    AggregateFunction.AVG,
+    AggregateFunction.MIN,
+    AggregateFunction.MAX,
+    AggregateFunction.MEDIAN,
+    AggregateFunction.PERCENTILE,
+    AggregateFunction.STDDEV,
+    AggregateFunction.VARIANCE,
+]);
+/** Maximum number of generated buckets before rejecting */
+const MAX_BUCKETS = 2_000;
+let TimeSeriesDensifierBackendService = class TimeSeriesDensifierBackendService {
+    logger;
+    errorBuilder;
+    constructor(logger, errorBuilder) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+    }
+    /**
+     * Densify time-series data by filling missing time buckets.
+     * Only operates on dimensions with `fillMissingBuckets: true` and a `timeGranularity`.
+     * Returns the original data if no densification is needed.
+     */
+    densify(input) {
+        const { query, data, resolvedFilter, timezone } = input;
+        // Find dimensions that need densification
+        const timeDims = query.dimensions.filter(d => d.fillMissingBuckets && d.timeGranularity);
+        if (timeDims.length === 0) {
+            return data;
+        }
+        // For MVP: densify on the first qualifying time dimension
+        const timeDim = timeDims[0];
+        const granularity = timeDim.timeGranularity;
+        const dimRef = timeDim.ref;
+        // Resolve date range
+        const range = this.resolveRange(timeDim, dimRef, data, resolvedFilter);
+        if (!range.from || !range.to) {
+            this.logger.debug(`TimeSeriesDensifier: could not resolve range for dimension '${dimRef}', skipping densification`);
+            return data;
+        }
+        // Generate all buckets
+        const buckets = this.generateBuckets(range.from, range.to, granularity, timezone);
+        // Guard: max buckets
+        if (buckets.length > MAX_BUCKETS) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AGGREGATION_MAX_BUCKETS_EXCEEDED,
+                context: {
+                    message: `Too many time buckets (${buckets.length}). Max allowed: ${MAX_BUCKETS}. Use a coarser granularity or narrow the date range.`,
+                    bucketCount: buckets.length,
+                    maxBuckets: MAX_BUCKETS,
+                    granularity,
+                },
+            });
+        }
+        // Build a lookup from existing data: bucket key → row
+        const existingRows = this.buildRowLookup(data, dimRef, granularity, timezone);
+        // Determine measure refs and their fill values (0 for numeric, null for non-numeric)
+        const measureFillValues = new Map();
+        for (const m of query.measures) {
+            measureFillValues.set(m.ref, NUMERIC_AGGREGATES.has(m.aggregate) ? 0 : null);
+        }
+        const otherDimRefs = query.dimensions.filter(d => d.ref !== dimRef).map(d => d.ref);
+        // If there are other (non-time) dimensions, densify per unique combination
+        if (otherDimRefs.length > 0) {
+            return this.densifyWithOtherDimensions(buckets, existingRows, dimRef, measureFillValues, otherDimRefs, data);
+        }
+        // Simple case: only time dimension
+        return this.densifySimple(buckets, existingRows, dimRef, measureFillValues);
+    }
+    // ── Range Resolution ───────────────────────────────────────
+    resolveRange(timeDim, dimRef, data, resolvedFilter) {
+        // Priority 1: Explicit dateRange on dimension
+        if (timeDim.dateRange?.from || timeDim.dateRange?.to) {
+            return {
+                from: timeDim.dateRange.from ? new Date(timeDim.dateRange.from) : null,
+                to: timeDim.dateRange.to ? new Date(timeDim.dateRange.to) : null,
+            };
+        }
+        // Priority 2 & 3: Extract bounds from resolved filter (covers both context filters and global filters)
+        if (resolvedFilter) {
+            const fieldFilter = resolvedFilter[timeDim.field];
+            if (fieldFilter && typeof fieldFilter === 'object') {
+                const from = fieldFilter['$gte'] || fieldFilter['$gt'];
+                const to = fieldFilter['$lte'] || fieldFilter['$lt'];
+                if (from || to) {
+                    return {
+                        from: from ? new Date(from) : null,
+                        to: to ? new Date(to) : null,
+                    };
+                }
+            }
+        }
+        // Priority 4: Fallback to data min/max (never invent unbounded ranges)
+        if (data.length === 0) {
+            return { from: null, to: null };
+        }
+        let minDate = null;
+        let maxDate = null;
+        for (const row of data) {
+            const val = row[dimRef];
+            if (val == null)
+                continue;
+            const date = val instanceof Date ? val : new Date(val);
+            if (isNaN(date.getTime()))
+                continue;
+            if (!minDate || date < minDate)
+                minDate = date;
+            if (!maxDate || date > maxDate)
+                maxDate = date;
+        }
+        return { from: minDate, to: maxDate };
+    }
+    // ── Bucket Generation ──────────────────────────────────────
+    generateBuckets(from, to, granularity, _timezone) {
+        const buckets = [];
+        let current = this.truncateToGranularity(new Date(from.getTime()), granularity);
+        const end = to;
+        // Safety: limit to MAX_BUCKETS + 1 to detect overflow
+        const maxIterations = MAX_BUCKETS + 1;
+        let iterations = 0;
+        while (current <= end && iterations < maxIterations) {
+            buckets.push(new Date(current.getTime()));
+            current = this.advanceBucket(current, granularity);
+            iterations++;
+        }
+        return buckets;
+    }
+    truncateToGranularity(date, granularity) {
+        const d = new Date(date.getTime());
+        switch (granularity) {
+            case TimeGranularity.MINUTE:
+                d.setUTCSeconds(0, 0);
+                break;
+            case TimeGranularity.HOUR:
+                d.setUTCMinutes(0, 0, 0);
+                break;
+            case TimeGranularity.DAY:
+                d.setUTCHours(0, 0, 0, 0);
+                break;
+            case TimeGranularity.WEEK:
+                // Truncate to Monday
+                d.setUTCHours(0, 0, 0, 0);
+                const dayOfWeek = d.getUTCDay();
+                const diff = dayOfWeek === 0 ? -6 : 1 - dayOfWeek;
+                d.setUTCDate(d.getUTCDate() + diff);
+                break;
+            case TimeGranularity.MONTH:
+                d.setUTCDate(1);
+                d.setUTCHours(0, 0, 0, 0);
+                break;
+            case TimeGranularity.QUARTER:
+                d.setUTCMonth(Math.floor(d.getUTCMonth() / 3) * 3, 1);
+                d.setUTCHours(0, 0, 0, 0);
+                break;
+            case TimeGranularity.YEAR:
+                d.setUTCMonth(0, 1);
+                d.setUTCHours(0, 0, 0, 0);
+                break;
+        }
+        return d;
+    }
+    advanceBucket(date, granularity) {
+        const d = new Date(date.getTime());
+        switch (granularity) {
+            case TimeGranularity.MINUTE:
+                d.setUTCMinutes(d.getUTCMinutes() + 1);
+                break;
+            case TimeGranularity.HOUR:
+                d.setUTCHours(d.getUTCHours() + 1);
+                break;
+            case TimeGranularity.DAY:
+                d.setUTCDate(d.getUTCDate() + 1);
+                break;
+            case TimeGranularity.WEEK:
+                d.setUTCDate(d.getUTCDate() + 7);
+                break;
+            case TimeGranularity.MONTH:
+                d.setUTCMonth(d.getUTCMonth() + 1);
+                break;
+            case TimeGranularity.QUARTER:
+                d.setUTCMonth(d.getUTCMonth() + 3);
+                break;
+            case TimeGranularity.YEAR:
+                d.setUTCFullYear(d.getUTCFullYear() + 1);
+                break;
+        }
+        return d;
+    }
+    // ── Row Lookup ─────────────────────────────────────────────
+    buildRowLookup(data, dimRef, granularity, _timezone) {
+        const lookup = new Map();
+        for (const row of data) {
+            const val = row[dimRef];
+            if (val == null)
+                continue;
+            const date = val instanceof Date ? val : new Date(val);
+            if (isNaN(date.getTime()))
+                continue;
+            const truncated = this.truncateToGranularity(date, granularity);
+            const key = truncated.toISOString();
+            const existing = lookup.get(key);
+            if (existing) {
+                existing.push(row);
+            }
+            else {
+                lookup.set(key, [row]);
+            }
+        }
+        return lookup;
+    }
+    // ── Densification (simple — no other dimensions) ───────────
+    densifySimple(buckets, existingRows, dimRef, measureFillValues) {
+        const result = [];
+        for (const bucket of buckets) {
+            const key = bucket.toISOString();
+            const existing = existingRows.get(key);
+            if (existing && existing.length > 0) {
+                // Use existing rows (multiple rows possible if split-by dimension)
+                result.push(...existing);
+            }
+            else {
+                // Generate a filled row
+                const filledRow = {
+                    [dimRef]: bucket.toISOString(),
+                    _filled: true,
+                };
+                for (const [mRef, fillValue] of measureFillValues) {
+                    filledRow[mRef] = fillValue;
+                }
+                result.push(filledRow);
+            }
+        }
+        return result;
+    }
+    // ── Densification (with other dimensions — split-by aware) ──
+    densifyWithOtherDimensions(buckets, existingRows, dimRef, measureFillValues, otherDimRefs, allData) {
+        // Collect all unique combinations of "other" dimension values
+        // Use JSON serialization for combo keys to avoid delimiter collisions
+        const combos = new Set();
+        for (const row of allData) {
+            const comboKey = JSON.stringify(otherDimRefs.map(d => row[d] ?? ''));
+            combos.add(comboKey);
+        }
+        const result = [];
+        for (const bucket of buckets) {
+            const key = bucket.toISOString();
+            const existingForBucket = existingRows.get(key) || [];
+            // Track which combos already have data for this bucket
+            const existingCombos = new Set();
+            for (const row of existingForBucket) {
+                const comboKey = JSON.stringify(otherDimRefs.map(d => row[d] ?? ''));
+                existingCombos.add(comboKey);
+                result.push(row);
+            }
+            // Fill missing combos for this bucket
+            for (const comboStr of combos) {
+                if (existingCombos.has(comboStr))
+                    continue;
+                const comboValues = JSON.parse(comboStr);
+                const filledRow = {
+                    [dimRef]: bucket.toISOString(),
+                    _filled: true,
+                };
+                for (let i = 0; i < otherDimRefs.length; i++) {
+                    filledRow[otherDimRefs[i]] = comboValues[i];
+                }
+                for (const [mRef, fillValue] of measureFillValues) {
+                    filledRow[mRef] = fillValue;
+                }
+                result.push(filledRow);
+            }
+        }
+        return result;
+    }
+};
+TimeSeriesDensifierBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __metadata("design:paramtypes", [Function, Function])
+], TimeSeriesDensifierBackendService);
+export { TimeSeriesDensifierBackendService };
+//# sourceMappingURL=time-series-densifier.backend.service.js.map

package/dist/esm/databases/services/aggregation/time-series-densifier.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-series-densifier.backend.service.js","sourceRoot":"","sources":["../../../../../src/databases/services/aggregation/time-series-densifier.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/databases/services/aggregation/topn-processor.backend.service.d.ts

@@ -0,0 +1,47 @@
+/** ──────────────────────────────────────────────────────────────
+ * TopNProcessorBackendService
+ *
+ * Post-processing step that reduces dimension cardinality:
+ *   1. For each dimension with topN, sort rows by the primary measure (descending)
+ *   2. Keep top N values
+ *   3. If groupOther is true, aggregate the remaining rows into an "Other" bucket
+ *
+ * Pipeline position: After DB execution, BEFORE TimeSeriesDensifier.
+ * This ensures densification only fills buckets for surviving dimension values,
+ * and running totals / window functions operate on the truncated set.
+ * ────────────────────────────────────────────────────────────── */
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import type { AggregationQuery } from '@wildo-ai/saas-models';
+export declare class TopNProcessorBackendService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Apply top-N processing for dimensions that have topN configured.
+     *
+     * For each dimension with `topN`, this:
+     * 1. Determines the primary measure to rank by (first measure in the query)
+     * 2. Ranks rows by that measure value (descending)
+     * 3. Keeps only the top N dimension values
+     * 4. If `groupOther` is true, aggregates the rest into an "Other" bucket
+     *
+     * If multiple dimensions have topN, they are processed sequentially.
+     */
+    process(data: Record<string, unknown>[], query: AggregationQuery): Record<string, unknown>[];
+    /**
+     * Apply top-N for a single dimension.
+     */
+    private applyTopN;
+    /**
+     * Aggregate overflow rows into an "Other" bucket.
+     *
+     * Groups by all OTHER dimensions (excluding the top-N dimension),
+     * then aggregates numeric measure values using the correct operation
+     * per measure (SUM for sum/count, MIN for min, MAX for max, AVG for avg).
+     *
+     * Note: AVG of averages is an approximation since we don't have
+     * per-group row counts. For exact results, use SUM with a computed
+     * measure that divides by count.
+     */
+    private aggregateOtherBucket;
+}
+//# sourceMappingURL=topn-processor.backend.service.d.ts.map

package/dist/esm/databases/services/aggregation/topn-processor.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topn-processor.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/databases/services/aggregation/topn-processor.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;oEAWoE;AAIpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAElG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAI9D,qBACa,2BAA2B;IAED,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAG3E;;;;;;;;;;OAUG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAC/B,KAAK,EAAE,gBAAgB,GACtB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAsB5B;;OAEG;IACH,OAAO,CAAC,SAAS;IAuDjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,oBAAoB;CAwF7B"}

package/dist/esm/databases/services/aggregation/topn-processor.backend.service.js

@@ -0,0 +1,187 @@
+/** ──────────────────────────────────────────────────────────────
+ * TopNProcessorBackendService
+ *
+ * Post-processing step that reduces dimension cardinality:
+ *   1. For each dimension with topN, sort rows by the primary measure (descending)
+ *   2. Keep top N values
+ *   3. If groupOther is true, aggregate the remaining rows into an "Other" bucket
+ *
+ * Pipeline position: After DB execution, BEFORE TimeSeriesDensifier.
+ * This ensures densification only fills buckets for surviving dimension values,
+ * and running totals / window functions operate on the truncated set.
+ * ────────────────────────────────────────────────────────────── */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { AggregateFunction } from '@wildo-ai/saas-models';
+const OTHER_BUCKET_LABEL = 'Other';
+let TopNProcessorBackendService = class TopNProcessorBackendService {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Apply top-N processing for dimensions that have topN configured.
+     *
+     * For each dimension with `topN`, this:
+     * 1. Determines the primary measure to rank by (first measure in the query)
+     * 2. Ranks rows by that measure value (descending)
+     * 3. Keeps only the top N dimension values
+     * 4. If `groupOther` is true, aggregates the rest into an "Other" bucket
+     *
+     * If multiple dimensions have topN, they are processed sequentially.
+     */
+    process(data, query) {
+        if (data.length === 0)
+            return data;
+        const topNDimensions = query.dimensions.filter(d => d.topN != null && d.topN > 0);
+        if (topNDimensions.length === 0)
+            return data;
+        // Determine the primary measure ref (first measure in the query)
+        const primaryMeasureRef = query.measures.length > 0 ? query.measures[0].ref : undefined;
+        if (!primaryMeasureRef) {
+            this.logger.warn('TopNProcessor: no measures defined, skipping top-N processing');
+            return data;
+        }
+        let result = data;
+        for (const dim of topNDimensions) {
+            result = this.applyTopN(result, dim.ref, dim.topN, dim.groupOther ?? false, primaryMeasureRef, query);
+        }
+        return result;
+    }
+    /**
+     * Apply top-N for a single dimension.
+     */
+    applyTopN(data, dimensionRef, topN, groupOther, primaryMeasureRef, query) {
+        // 1. Aggregate measure values by this dimension's value
+        //    This is needed because with split-by, there can be multiple rows per dimension value
+        const measureByDimValue = new Map();
+        for (const row of data) {
+            const dimValue = String(row[dimensionRef] ?? '');
+            const measureValue = Number(row[primaryMeasureRef] ?? 0);
+            measureByDimValue.set(dimValue, (measureByDimValue.get(dimValue) ?? 0) + measureValue);
+        }
+        // 2. Sort dimension values by the aggregated measure value (descending)
+        const rankedValues = [...measureByDimValue.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(entry => entry[0]);
+        // 3. Separate top-N values from the rest
+        const topValues = new Set(rankedValues.slice(0, topN));
+        const otherValues = new Set(rankedValues.slice(topN));
+        if (otherValues.size === 0) {
+            // All values fit in top-N — no filtering needed
+            return data;
+        }
+        this.logger.debug(`TopNProcessor: dimension '${dimensionRef}' top-${topN}: keeping ${topValues.size}, ` +
+            `${groupOther ? `aggregating ${otherValues.size} into "Other"` : `removing ${otherValues.size}`}`);
+        // 4. Partition rows
+        const topRows = data.filter(row => topValues.has(String(row[dimensionRef] ?? '')));
+        const otherRows = data.filter(row => otherValues.has(String(row[dimensionRef] ?? '')));
+        if (!groupOther || otherRows.length === 0) {
+            return topRows;
+        }
+        // 5. Aggregate "Other" rows
+        const otherBucketRows = this.aggregateOtherBucket(otherRows, dimensionRef, query);
+        return [...topRows, ...otherBucketRows];
+    }
+    /**
+     * Aggregate overflow rows into an "Other" bucket.
+     *
+     * Groups by all OTHER dimensions (excluding the top-N dimension),
+     * then aggregates numeric measure values using the correct operation
+     * per measure (SUM for sum/count, MIN for min, MAX for max, AVG for avg).
+     *
+     * Note: AVG of averages is an approximation since we don't have
+     * per-group row counts. For exact results, use SUM with a computed
+     * measure that divides by count.
+     */
+    aggregateOtherBucket(otherRows, topNDimensionRef, query) {
+        // Other dimensions (to preserve as group keys)
+        const otherDimensionRefs = query.dimensions
+            .map(d => d.ref)
+            .filter(ref => ref !== topNDimensionRef);
+        // Build a map of measureRef → aggregate function for correct aggregation
+        const measureAggregateMap = new Map();
+        for (const m of query.measures) {
+            measureAggregateMap.set(m.ref, m.aggregate);
+        }
+        // Group "other" rows by the remaining dimensions
+        const groups = new Map();
+        for (const row of otherRows) {
+            const groupKey = otherDimensionRefs.length > 0
+                ? JSON.stringify(otherDimensionRefs.map(ref => row[ref]))
+                : '__all__';
+            const group = groups.get(groupKey);
+            if (group) {
+                group.push(row);
+            }
+            else {
+                groups.set(groupKey, [row]);
+            }
+        }
+        // Build aggregated rows
+        const result = [];
+        for (const [, groupRows] of groups) {
+            const aggregated = {};
+            // Set the top-N dimension to "Other"
+            aggregated[topNDimensionRef] = OTHER_BUCKET_LABEL;
+            // Copy other dimension values from the first row (they're the same for the group)
+            for (const dimRef of otherDimensionRefs) {
+                aggregated[dimRef] = groupRows[0][dimRef];
+            }
+            // Aggregate measure values using the correct operation per aggregate function
+            for (const measureDef of query.measures) {
+                const values = groupRows
+                    .map(r => Number(r[measureDef.ref] ?? 0))
+                    .filter(v => !isNaN(v));
+                if (values.length === 0) {
+                    aggregated[measureDef.ref] = 0;
+                    continue;
+                }
+                const agg = measureAggregateMap.get(measureDef.ref);
+                switch (agg) {
+                    case AggregateFunction.MIN:
+                        aggregated[measureDef.ref] = Math.min(...values);
+                        break;
+                    case AggregateFunction.MAX:
+                        aggregated[measureDef.ref] = Math.max(...values);
+                        break;
+                    case AggregateFunction.AVG:
+                    case AggregateFunction.MEDIAN:
+                        // Averaging pre-aggregated averages is an approximation
+                        aggregated[measureDef.ref] = values.reduce((a, b) => a + b, 0) / values.length;
+                        break;
+                    default:
+                        // SUM, COUNT, COUNT_DISTINCT, and others: sum the values
+                        aggregated[measureDef.ref] = values.reduce((a, b) => a + b, 0);
+                        break;
+                }
+            }
+            // Preserve _filled flag if any row had it
+            const hasFilledRows = groupRows.some(r => r['_filled'] === true);
+            if (hasFilledRows) {
+                aggregated['_filled'] = true;
+            }
+            result.push(aggregated);
+        }
+        return result;
+    }
+};
+TopNProcessorBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __metadata("design:paramtypes", [Function])
+], TopNProcessorBackendService);
+export { TopNProcessorBackendService };
+//# sourceMappingURL=topn-processor.backend.service.js.map

package/dist/esm/databases/services/aggregation/topn-processor.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"topn-processor.backend.service.js","sourceRoot":"","sources":["../../../../../src/databases/services/aggregation/topn-processor.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/databases/services/aggregation/window-function-processor.backend.service.d.ts

@@ -0,0 +1,47 @@
+/** ──────────────────────────────────────────────────────────────
+ * WindowFunctionProcessorBackendService
+ *
+ * In-memory post-aggregation window function processor.
+ * Handles window functions that cannot be expressed in $setWindowFields:
+ *   - PERCENT_OF_TOTAL: value / sum(all values) * 100
+ *   - DIFFERENCE: current - previous
+ *   - PERCENT_CHANGE: (current - previous) / previous * 100
+ *   - MOVING_AVG: average of last N values
+ *
+ * Also serves as a full fallback if the DB doesn't support $setWindowFields
+ * (e.g., MongoDB < 5.0), handling ALL window function types in-memory.
+ *
+ * Pipeline position: step 10 — after densification (8) and computed measures (9).
+ * This ensures window functions operate on the complete, dense dataset.
+ *
+ * Ref: WindowFunctionType enum → L569-580
+ * Ref: Pipeline position → L410
+ * ────────────────────────────────────────────────────────────── */
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import type { AggregationQueryResponseRow, WindowFunction } from '@wildo-ai/saas-models';
+export declare class WindowFunctionProcessorBackendService {
+    private readonly logger;
+    constructor(logger: LoggerService);
+    /**
+     * Process window functions in-memory on the result data.
+     * Each window function adds a new field (keyed by `ref`) to every row.
+     * Respects partitionBy for segmented windows.
+     *
+     * @param data - Result rows (already densified and with computed measures)
+     * @param windowFunctions - Window function definitions to apply
+     * @returns Mutated data array with window function fields added
+     */
+    process(data: AggregationQueryResponseRow[], windowFunctions: WindowFunction[]): AggregationQueryResponseRow[];
+    private processPartitioned;
+    private processWindow;
+    private computePercentOfTotal;
+    private computeDifference;
+    private computePercentChange;
+    private computeMovingAvg;
+    private computeRunningTotal;
+    private computeRunningAvg;
+    private computeRank;
+    private computeShift;
+    private getNumericValue;
+}
+//# sourceMappingURL=window-function-processor.backend.service.d.ts.map

package/dist/esm/databases/services/aggregation/window-function-processor.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-function-processor.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/databases/services/aggregation/window-function-processor.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;oEAkBoE;AAIpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAElG,OAAO,KAAK,EACV,2BAA2B,EAC3B,cAAc,EACf,MAAM,uBAAuB,CAAC;AAE/B,qBACa,qCAAqC;IAEX,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAG3E;;;;;;;;OAQG;IACH,OAAO,CACL,IAAI,EAAE,2BAA2B,EAAE,EACnC,eAAe,EAAE,cAAc,EAAE,GAChC,2BAA2B,EAAE;IAoBhC,OAAO,CAAC,kBAAkB;IAgC1B,OAAO,CAAC,aAAa;IA6CrB,OAAO,CAAC,qBAAqB;IAoB7B,OAAO,CAAC,iBAAiB;IAiBzB,OAAO,CAAC,oBAAoB;IAiB5B,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,WAAW;IAgCnB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,eAAe;CAOxB"}