mongoose-query-find 3.2.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +425 -89
- package/dist/analytics.d.ts +267 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +877 -0
- package/dist/analytics.js.map +1 -0
- package/dist/index.d.ts +8 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,877 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* QueryAnalytics - Advanced, allowlisted analytics builder for Mongoose (v8/v9)
|
|
4
|
+
*
|
|
5
|
+
* Sits alongside QueryFind (Model.find()) and QueryAggregate (generic pipeline
|
|
6
|
+
* builder). QueryAnalytics is purpose-built for dashboards/reporting.
|
|
7
|
+
* Assumes a modern MongoDB server (7.0+): uses $setWindowFields, $rank,
|
|
8
|
+
* $shift, $stdDevPop and $percentile natively — no manual fallbacks.
|
|
9
|
+
*
|
|
10
|
+
* Feature map:
|
|
11
|
+
* - timeSeries() bucketed metrics over time, gap-filled
|
|
12
|
+
* - cumulativeSeries() time series + native running-total column
|
|
13
|
+
* - compare() period-over-period, % change
|
|
14
|
+
* - breakdown() top-N by a dimension
|
|
15
|
+
* - rankedBreakdown() breakdown + dense rank per row (native $setWindowFields)
|
|
16
|
+
* - multiBreakdown() pivot by two dimensions
|
|
17
|
+
* - funnel() sequential step conversion
|
|
18
|
+
* - cohortRetention() cohort-by-cohort retention matrix
|
|
19
|
+
* - sessionize() gap-based event sessionization ($setWindowFields + $shift)
|
|
20
|
+
* - percentiles() p50/p90/p99/... via native $percentile
|
|
21
|
+
* - stdDevOutliers() flag documents beyond N std deviations
|
|
22
|
+
* - metrics() one-shot multi-metric summary (single round trip)
|
|
23
|
+
* - movingAverage/trend pure-JS post-processing on an existing series
|
|
24
|
+
* - forecast() simple linear-regression projection (pure JS)
|
|
25
|
+
* - heatmap() weekday x hour-of-day matrix
|
|
26
|
+
* - watch() live change-stream subscription for dashboards
|
|
27
|
+
* - toCSV/toNDJSON export helpers
|
|
28
|
+
* - dashboard() run several analytics calls in parallel, keyed
|
|
29
|
+
* - built-in TTL cache
|
|
30
|
+
*
|
|
31
|
+
* Usage:
|
|
32
|
+
* const qa = new QueryAnalytics(OrderModel, { timezone: 'Asia/Dhaka' })
|
|
33
|
+
* .match({ branchId, status: { $ne: 'CANCELLED' } })
|
|
34
|
+
* .dateRange('createdAt', { from: '2026-08-01', to: '2026-08-31' });
|
|
35
|
+
*
|
|
36
|
+
* const series = await qa.timeSeries({
|
|
37
|
+
* dateField: 'createdAt', interval: 'day',
|
|
38
|
+
* metrics: [{ name: 'revenue', op: 'sum', field: 'total' }, { name: 'orders', op: 'count' }],
|
|
39
|
+
* });
|
|
40
|
+
*/
|
|
41
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
42
|
+
exports.QueryAnalytics = exports.QueryAnalyticsError = void 0;
|
|
43
|
+
const date_fns_1 = require("date-fns");
|
|
44
|
+
const date_fns_tz_1 = require("date-fns-tz");
|
|
45
|
+
// ─── Constants ────────────────────────────────────────────────────────────────
|
|
46
|
+
const DEFAULT_TIMEZONE = 'Asia/Dhaka';
|
|
47
|
+
const DEFAULT_MAX_TIME_MS = 8000;
|
|
48
|
+
const PLAIN_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
49
|
+
const BANNED_STAGE_OPERATORS = new Set(['$out', '$merge']);
|
|
50
|
+
class QueryAnalyticsError extends Error {
|
|
51
|
+
constructor(message) {
|
|
52
|
+
super(message);
|
|
53
|
+
this.name = 'QueryAnalyticsError';
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
exports.QueryAnalyticsError = QueryAnalyticsError;
|
|
57
|
+
// ─── Helpers ──────────────────────────────────────────────────────────────────
|
|
58
|
+
function resolveTimezone(tz) {
|
|
59
|
+
const candidate = tz && tz.trim() ? tz.trim() : DEFAULT_TIMEZONE;
|
|
60
|
+
try {
|
|
61
|
+
Intl.DateTimeFormat(undefined, { timeZone: candidate });
|
|
62
|
+
return candidate;
|
|
63
|
+
}
|
|
64
|
+
catch {
|
|
65
|
+
return DEFAULT_TIMEZONE;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
function shiftLocalDateString(dateStr, days) {
|
|
69
|
+
const [y, m, d] = dateStr.split('-').map(Number);
|
|
70
|
+
const anchor = new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
|
|
71
|
+
return (0, date_fns_1.addDays)(anchor, days).toISOString().slice(0, 10);
|
|
72
|
+
}
|
|
73
|
+
function isPlainObject(v) {
|
|
74
|
+
return (v !== null &&
|
|
75
|
+
typeof v === 'object' &&
|
|
76
|
+
!Array.isArray(v) &&
|
|
77
|
+
!(v instanceof Date) &&
|
|
78
|
+
Object.getPrototypeOf(v) === Object.prototype);
|
|
79
|
+
}
|
|
80
|
+
function rejectBannedStages(stage) {
|
|
81
|
+
if (Array.isArray(stage)) {
|
|
82
|
+
stage.forEach(rejectBannedStages);
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
if (!isPlainObject(stage))
|
|
86
|
+
return;
|
|
87
|
+
for (const k in stage) {
|
|
88
|
+
if (BANNED_STAGE_OPERATORS.has(k)) {
|
|
89
|
+
throw new QueryAnalyticsError(`Disallowed pipeline stage: "${k}"`);
|
|
90
|
+
}
|
|
91
|
+
rejectBannedStages(stage[k]);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
function buildGroupExpr(specs) {
|
|
95
|
+
const group = {};
|
|
96
|
+
for (const spec of specs) {
|
|
97
|
+
if (spec.op === 'count') {
|
|
98
|
+
group[spec.name] = { $sum: 1 };
|
|
99
|
+
}
|
|
100
|
+
else if (spec.op === 'distinctCount') {
|
|
101
|
+
if (!spec.field)
|
|
102
|
+
throw new QueryAnalyticsError(`"${spec.name}" needs "field" for distinctCount`);
|
|
103
|
+
group[`__set_${spec.name}`] = { $addToSet: `$${spec.field}` };
|
|
104
|
+
}
|
|
105
|
+
else {
|
|
106
|
+
if (!spec.field)
|
|
107
|
+
throw new QueryAnalyticsError(`"${spec.name}" needs "field" for op "${spec.op}"`);
|
|
108
|
+
group[spec.name] = { [`$${spec.op}`]: `$${spec.field}` };
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
return group;
|
|
112
|
+
}
|
|
113
|
+
function finalizeDistinctCounts(row, specs) {
|
|
114
|
+
const out = {};
|
|
115
|
+
for (const spec of specs) {
|
|
116
|
+
if (spec.op === 'distinctCount') {
|
|
117
|
+
const set = row[`__set_${spec.name}`];
|
|
118
|
+
out[spec.name] = Array.isArray(set) ? set.length : 0;
|
|
119
|
+
}
|
|
120
|
+
else {
|
|
121
|
+
out[spec.name] = row[spec.name] ?? 0;
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
return out;
|
|
125
|
+
}
|
|
126
|
+
function dateTruncStage(dateField, interval, timezone, weekStartsOn, outField = '__bucket') {
|
|
127
|
+
const unitMap = {
|
|
128
|
+
hour: 'hour',
|
|
129
|
+
day: 'day',
|
|
130
|
+
week: 'week',
|
|
131
|
+
month: 'month',
|
|
132
|
+
};
|
|
133
|
+
return {
|
|
134
|
+
$addFields: {
|
|
135
|
+
[outField]: {
|
|
136
|
+
$dateTrunc: {
|
|
137
|
+
date: `$${dateField}`,
|
|
138
|
+
unit: unitMap[interval],
|
|
139
|
+
timezone,
|
|
140
|
+
...(interval === 'week'
|
|
141
|
+
? {
|
|
142
|
+
startOfWeek: ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'][weekStartsOn],
|
|
143
|
+
}
|
|
144
|
+
: {}),
|
|
145
|
+
},
|
|
146
|
+
},
|
|
147
|
+
},
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
function nextBucket(d, interval) {
|
|
151
|
+
switch (interval) {
|
|
152
|
+
case 'hour':
|
|
153
|
+
return (0, date_fns_1.addHours)(d, 1);
|
|
154
|
+
case 'day':
|
|
155
|
+
return (0, date_fns_1.addDays)(d, 1);
|
|
156
|
+
case 'week':
|
|
157
|
+
return (0, date_fns_1.addWeeks)(d, 1);
|
|
158
|
+
case 'month':
|
|
159
|
+
return (0, date_fns_1.addMonths)(d, 1);
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
function periodOffset(from, to, interval) {
|
|
163
|
+
const msPerUnit = {
|
|
164
|
+
hour: 3600000,
|
|
165
|
+
day: 86400000,
|
|
166
|
+
week: 7 * 86400000,
|
|
167
|
+
month: 30 * 86400000, // approximate; cohort bucketing itself is exact via $dateTrunc
|
|
168
|
+
};
|
|
169
|
+
return Math.round((to.getTime() - from.getTime()) / msPerUnit[interval]);
|
|
170
|
+
}
|
|
171
|
+
const _cacheStore = new Map();
|
|
172
|
+
function cacheGet(key) {
|
|
173
|
+
const hit = _cacheStore.get(key);
|
|
174
|
+
if (!hit)
|
|
175
|
+
return undefined;
|
|
176
|
+
if (Date.now() > hit.expiresAt) {
|
|
177
|
+
_cacheStore.delete(key);
|
|
178
|
+
return undefined;
|
|
179
|
+
}
|
|
180
|
+
return hit.value;
|
|
181
|
+
}
|
|
182
|
+
function cacheSet(key, value, ttlMs) {
|
|
183
|
+
if (ttlMs <= 0)
|
|
184
|
+
return;
|
|
185
|
+
_cacheStore.set(key, { value, expiresAt: Date.now() + ttlMs });
|
|
186
|
+
}
|
|
187
|
+
// ─── QueryAnalytics ─────────────────────────────────────────────────────────
|
|
188
|
+
class QueryAnalytics {
|
|
189
|
+
constructor(model, options = {}) {
|
|
190
|
+
this._serverConditions = {};
|
|
191
|
+
this._extraStages = [];
|
|
192
|
+
this.model = model;
|
|
193
|
+
this.options = {
|
|
194
|
+
timezone: resolveTimezone(options.timezone),
|
|
195
|
+
maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
|
|
196
|
+
allowDiskUse: options.allowDiskUse ?? false,
|
|
197
|
+
weekStartsOn: options.weekStartsOn ?? 6,
|
|
198
|
+
cacheTTLMs: options.cacheTTLMs ?? 0,
|
|
199
|
+
};
|
|
200
|
+
}
|
|
201
|
+
get timezone() {
|
|
202
|
+
return this.options.timezone;
|
|
203
|
+
}
|
|
204
|
+
// ── Base filter (server-only; never client-overridable) ────────────────────
|
|
205
|
+
/** Adds/merges a hard condition into the base $match. Call as many times as needed. */
|
|
206
|
+
match(conditions) {
|
|
207
|
+
Object.assign(this._serverConditions, conditions);
|
|
208
|
+
return this;
|
|
209
|
+
}
|
|
210
|
+
/** Escape hatch for extra developer-authored stages spliced in before analytics-specific stages. Blocks $out/$merge. */
|
|
211
|
+
addStage(stage) {
|
|
212
|
+
rejectBannedStages(stage);
|
|
213
|
+
this._extraStages.push(stage);
|
|
214
|
+
return this;
|
|
215
|
+
}
|
|
216
|
+
/** Hard local-date range condition on `field`, e.g. { from: '2026-08-01', to: '2026-08-31' } (inclusive). */
|
|
217
|
+
dateRange(field, range) {
|
|
218
|
+
if (!PLAIN_DATE_RE.test(range.from) || !PLAIN_DATE_RE.test(range.to)) {
|
|
219
|
+
throw new QueryAnalyticsError(`dateRange: "from"/"to" must be YYYY-MM-DD, got "${range.from}" / "${range.to}"`);
|
|
220
|
+
}
|
|
221
|
+
const tz = this.options.timezone;
|
|
222
|
+
const start = (0, date_fns_tz_1.fromZonedTime)(`${range.from}T00:00:00.000`, tz);
|
|
223
|
+
const end = (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(range.to, 1)}T00:00:00.000`, tz);
|
|
224
|
+
this._serverConditions[field] = { $gte: start, $lt: end };
|
|
225
|
+
return this;
|
|
226
|
+
}
|
|
227
|
+
clone() {
|
|
228
|
+
const c = new QueryAnalytics(this.model, this.options);
|
|
229
|
+
c._serverConditions = { ...this._serverConditions };
|
|
230
|
+
c._extraStages = [...this._extraStages];
|
|
231
|
+
return c;
|
|
232
|
+
}
|
|
233
|
+
baseMatchStage() {
|
|
234
|
+
return Object.keys(this._serverConditions).length > 0
|
|
235
|
+
? { $match: this._serverConditions }
|
|
236
|
+
: null;
|
|
237
|
+
}
|
|
238
|
+
basePipeline() {
|
|
239
|
+
const pipeline = [];
|
|
240
|
+
const m = this.baseMatchStage();
|
|
241
|
+
if (m)
|
|
242
|
+
pipeline.push(m);
|
|
243
|
+
pipeline.push(...this._extraStages);
|
|
244
|
+
return pipeline;
|
|
245
|
+
}
|
|
246
|
+
async run(pipeline, cacheKey) {
|
|
247
|
+
const ttl = this.options.cacheTTLMs;
|
|
248
|
+
if (ttl > 0 && cacheKey) {
|
|
249
|
+
const hit = cacheGet(cacheKey);
|
|
250
|
+
if (hit)
|
|
251
|
+
return hit;
|
|
252
|
+
}
|
|
253
|
+
// Single, deliberate boundary cast — see the Stage type comment above.
|
|
254
|
+
const agg = this.model.aggregate(pipeline);
|
|
255
|
+
if (this.options.maxTimeMS > 0)
|
|
256
|
+
agg.option({ maxTimeMS: this.options.maxTimeMS });
|
|
257
|
+
if (this.options.allowDiskUse)
|
|
258
|
+
agg.allowDiskUse(true);
|
|
259
|
+
const result = await agg.exec();
|
|
260
|
+
if (ttl > 0 && cacheKey)
|
|
261
|
+
cacheSet(cacheKey, result, ttl);
|
|
262
|
+
return result;
|
|
263
|
+
}
|
|
264
|
+
/** Clears every cached analytics result (across all instances/models). */
|
|
265
|
+
static clearCache() {
|
|
266
|
+
_cacheStore.clear();
|
|
267
|
+
}
|
|
268
|
+
// ── Time series ──────────────────────────────────────────────────────────
|
|
269
|
+
/**
|
|
270
|
+
* Buckets documents by `dateField` into `interval`-sized, timezone-aligned
|
|
271
|
+
* buckets and computes `metrics` per bucket. Fills gaps with zero-valued
|
|
272
|
+
* buckets so charts never show a broken line for empty days.
|
|
273
|
+
*/
|
|
274
|
+
async timeSeries(opts) {
|
|
275
|
+
const { dateField, interval, metrics, fillGaps = true } = opts;
|
|
276
|
+
const pipeline = [
|
|
277
|
+
...this.basePipeline(),
|
|
278
|
+
dateTruncStage(dateField, interval, this.options.timezone, this.options.weekStartsOn),
|
|
279
|
+
{ $group: { _id: '$__bucket', ...buildGroupExpr(metrics) } },
|
|
280
|
+
{ $sort: { _id: 1 } },
|
|
281
|
+
];
|
|
282
|
+
const rows = await this.run(pipeline);
|
|
283
|
+
const points = rows.map((r) => ({
|
|
284
|
+
bucket: r._id.toISOString(),
|
|
285
|
+
...finalizeDistinctCounts(r, metrics),
|
|
286
|
+
}));
|
|
287
|
+
if (!fillGaps || points.length === 0)
|
|
288
|
+
return points;
|
|
289
|
+
const filled = [];
|
|
290
|
+
let cursor = new Date(points[0].bucket);
|
|
291
|
+
const end = new Date(points[points.length - 1].bucket);
|
|
292
|
+
const byBucket = new Map(points.map((p) => [p.bucket, p]));
|
|
293
|
+
const zero = Object.fromEntries(metrics.map((m) => [m.name, 0]));
|
|
294
|
+
while (cursor <= end) {
|
|
295
|
+
const key = cursor.toISOString();
|
|
296
|
+
filled.push(byBucket.get(key) ?? { bucket: key, ...zero });
|
|
297
|
+
cursor = nextBucket(cursor, interval);
|
|
298
|
+
}
|
|
299
|
+
return filled;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Same bucketing as timeSeries(), plus a native running-total column per
|
|
303
|
+
* metric (computed server-side via $setWindowFields — no JS post-pass).
|
|
304
|
+
*/
|
|
305
|
+
async cumulativeSeries(opts) {
|
|
306
|
+
const { dateField, interval, metrics } = opts;
|
|
307
|
+
const cumulativeFields = {};
|
|
308
|
+
for (const spec of metrics) {
|
|
309
|
+
if (spec.op === 'distinctCount')
|
|
310
|
+
continue; // running distinct-count isn't a well-defined windowed sum
|
|
311
|
+
cumulativeFields[`${spec.name}_cumulative`] = {
|
|
312
|
+
$sum: `$${spec.name}`,
|
|
313
|
+
window: { documents: ['unbounded', 'current'] },
|
|
314
|
+
};
|
|
315
|
+
}
|
|
316
|
+
const pipeline = [
|
|
317
|
+
...this.basePipeline(),
|
|
318
|
+
dateTruncStage(dateField, interval, this.options.timezone, this.options.weekStartsOn),
|
|
319
|
+
{ $group: { _id: '$__bucket', ...buildGroupExpr(metrics) } },
|
|
320
|
+
{ $sort: { _id: 1 } },
|
|
321
|
+
{
|
|
322
|
+
$setWindowFields: {
|
|
323
|
+
sortBy: { _id: 1 },
|
|
324
|
+
output: cumulativeFields,
|
|
325
|
+
},
|
|
326
|
+
},
|
|
327
|
+
];
|
|
328
|
+
const rows = await this.run(pipeline);
|
|
329
|
+
return rows.map((r) => {
|
|
330
|
+
const base = finalizeDistinctCounts(r, metrics);
|
|
331
|
+
const cumulative = {};
|
|
332
|
+
for (const spec of metrics) {
|
|
333
|
+
if (spec.op === 'distinctCount')
|
|
334
|
+
continue;
|
|
335
|
+
cumulative[`${spec.name}_cumulative`] =
|
|
336
|
+
r[`${spec.name}_cumulative`] ?? 0;
|
|
337
|
+
}
|
|
338
|
+
return { bucket: r._id.toISOString(), ...base, ...cumulative };
|
|
339
|
+
});
|
|
340
|
+
}
|
|
341
|
+
// ── Period-over-period comparison ────────────────────────────────────────
|
|
342
|
+
/**
|
|
343
|
+
* Computes `metrics` for the current preset period and the equivalent
|
|
344
|
+
* prior period, plus absolute and percentage change per metric.
|
|
345
|
+
* Ignores any .dateRange() already applied — the preset defines both windows.
|
|
346
|
+
*/
|
|
347
|
+
async compare(opts) {
|
|
348
|
+
const { dateField, metrics, preset } = opts;
|
|
349
|
+
const tz = this.options.timezone;
|
|
350
|
+
const zonedNow = (0, date_fns_tz_1.toZonedTime)(new Date(), tz);
|
|
351
|
+
const todayStr = (0, date_fns_1.format)(zonedNow, 'yyyy-MM-dd');
|
|
352
|
+
const rangeFor = (fromStr, toStr) => ({
|
|
353
|
+
start: (0, date_fns_tz_1.fromZonedTime)(`${fromStr}T00:00:00.000`, tz),
|
|
354
|
+
end: (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(toStr, 1)}T00:00:00.000`, tz),
|
|
355
|
+
});
|
|
356
|
+
let curFrom, curTo, prevFrom, prevTo;
|
|
357
|
+
switch (preset) {
|
|
358
|
+
case 'today':
|
|
359
|
+
curFrom = curTo = todayStr;
|
|
360
|
+
prevFrom = prevTo = shiftLocalDateString(todayStr, -1);
|
|
361
|
+
break;
|
|
362
|
+
case 'last7Days':
|
|
363
|
+
curFrom = shiftLocalDateString(todayStr, -6);
|
|
364
|
+
curTo = todayStr;
|
|
365
|
+
prevFrom = shiftLocalDateString(todayStr, -13);
|
|
366
|
+
prevTo = shiftLocalDateString(todayStr, -7);
|
|
367
|
+
break;
|
|
368
|
+
case 'last30Days':
|
|
369
|
+
curFrom = shiftLocalDateString(todayStr, -29);
|
|
370
|
+
curTo = todayStr;
|
|
371
|
+
prevFrom = shiftLocalDateString(todayStr, -59);
|
|
372
|
+
prevTo = shiftLocalDateString(todayStr, -30);
|
|
373
|
+
break;
|
|
374
|
+
case 'thisWeek': {
|
|
375
|
+
const weekStart = (0, date_fns_1.format)((0, date_fns_1.startOfWeek)(zonedNow, { weekStartsOn: this.options.weekStartsOn }), 'yyyy-MM-dd');
|
|
376
|
+
curFrom = weekStart;
|
|
377
|
+
curTo = todayStr;
|
|
378
|
+
const spanDays = Math.round((new Date(curTo).getTime() - new Date(curFrom).getTime()) /
|
|
379
|
+
86400000) + 1;
|
|
380
|
+
prevTo = shiftLocalDateString(weekStart, -1);
|
|
381
|
+
prevFrom = shiftLocalDateString(prevTo, -(spanDays - 1));
|
|
382
|
+
break;
|
|
383
|
+
}
|
|
384
|
+
case 'thisMonth': {
|
|
385
|
+
const monthStart = (0, date_fns_1.format)((0, date_fns_1.startOfMonth)(zonedNow), 'yyyy-MM-dd');
|
|
386
|
+
curFrom = monthStart;
|
|
387
|
+
curTo = todayStr;
|
|
388
|
+
const prevMonthEnd = shiftLocalDateString(monthStart, -1);
|
|
389
|
+
const spanDays = Math.round((new Date(curTo).getTime() - new Date(curFrom).getTime()) /
|
|
390
|
+
86400000) + 1;
|
|
391
|
+
prevTo = prevMonthEnd;
|
|
392
|
+
prevFrom = shiftLocalDateString(prevMonthEnd, -(spanDays - 1));
|
|
393
|
+
break;
|
|
394
|
+
}
|
|
395
|
+
default:
|
|
396
|
+
throw new QueryAnalyticsError(`Unknown compare preset: "${preset}"`);
|
|
397
|
+
}
|
|
398
|
+
const cur = rangeFor(curFrom, curTo);
|
|
399
|
+
const prev = rangeFor(prevFrom, prevTo);
|
|
400
|
+
const runFor = async (start, end) => {
|
|
401
|
+
const pipeline = [
|
|
402
|
+
{
|
|
403
|
+
$match: {
|
|
404
|
+
...this._serverConditions,
|
|
405
|
+
[dateField]: { $gte: start, $lt: end },
|
|
406
|
+
},
|
|
407
|
+
},
|
|
408
|
+
...this._extraStages,
|
|
409
|
+
{ $group: { _id: null, ...buildGroupExpr(metrics) } },
|
|
410
|
+
];
|
|
411
|
+
const [row] = await this.run(pipeline);
|
|
412
|
+
return finalizeDistinctCounts(row ?? {}, metrics);
|
|
413
|
+
};
|
|
414
|
+
const [current, previous] = await Promise.all([
|
|
415
|
+
runFor(cur.start, cur.end),
|
|
416
|
+
runFor(prev.start, prev.end),
|
|
417
|
+
]);
|
|
418
|
+
const change = {};
|
|
419
|
+
const changePct = {};
|
|
420
|
+
for (const spec of metrics) {
|
|
421
|
+
const c = current[spec.name] ?? 0;
|
|
422
|
+
const p = previous[spec.name] ?? 0;
|
|
423
|
+
change[spec.name] = c - p;
|
|
424
|
+
changePct[spec.name] =
|
|
425
|
+
p === 0 ? null : Number((((c - p) / p) * 100).toFixed(2));
|
|
426
|
+
}
|
|
427
|
+
return { current, previous, change, changePct };
|
|
428
|
+
}
|
|
429
|
+
// ── Breakdown / Top-N by dimension ───────────────────────────────────────
|
|
430
|
+
/** Groups by `field` and computes `metrics` per group, sorted and capped. */
|
|
431
|
+
async breakdown(field, metrics, opts = {}) {
|
|
432
|
+
const { limit = 10, sortDir = -1 } = opts;
|
|
433
|
+
const sortBy = opts.sortBy ?? metrics[0]?.name ?? '_id';
|
|
434
|
+
const pipeline = [
|
|
435
|
+
...this.basePipeline(),
|
|
436
|
+
{ $group: { _id: `$${field}`, ...buildGroupExpr(metrics) } },
|
|
437
|
+
{ $sort: { [sortBy]: sortDir } },
|
|
438
|
+
{ $limit: limit },
|
|
439
|
+
];
|
|
440
|
+
const rows = await this.run(pipeline);
|
|
441
|
+
return rows.map((r) => ({
|
|
442
|
+
key: r._id,
|
|
443
|
+
...finalizeDistinctCounts(r, metrics),
|
|
444
|
+
}));
|
|
445
|
+
}
|
|
446
|
+
/** Same as breakdown(), but adds a native dense-rank column (1-based) via $setWindowFields — no client-side re-sorting needed. */
|
|
447
|
+
async rankedBreakdown(field, metrics, opts = {}) {
|
|
448
|
+
const { limit = 10, sortDir = -1 } = opts;
|
|
449
|
+
const sortBy = opts.sortBy ?? metrics[0]?.name ?? '_id';
|
|
450
|
+
const pipeline = [
|
|
451
|
+
...this.basePipeline(),
|
|
452
|
+
{ $group: { _id: `$${field}`, ...buildGroupExpr(metrics) } },
|
|
453
|
+
{
|
|
454
|
+
$setWindowFields: {
|
|
455
|
+
sortBy: { [sortBy]: sortDir },
|
|
456
|
+
output: { __rank: { $denseRank: {} } },
|
|
457
|
+
},
|
|
458
|
+
},
|
|
459
|
+
{ $sort: { [sortBy]: sortDir } },
|
|
460
|
+
{ $limit: limit },
|
|
461
|
+
];
|
|
462
|
+
const rows = await this.run(pipeline);
|
|
463
|
+
return rows.map((r) => ({
|
|
464
|
+
key: r._id,
|
|
465
|
+
rank: r.__rank,
|
|
466
|
+
...finalizeDistinctCounts(r, metrics),
|
|
467
|
+
}));
|
|
468
|
+
}
|
|
469
|
+
/** Pivot table: groups by two dimensions at once, returning one row per (dimA, dimB) pair with metrics. */
|
|
470
|
+
async multiBreakdown(fields, metrics, opts = {}) {
|
|
471
|
+
const [f1, f2] = fields;
|
|
472
|
+
const pipeline = [
|
|
473
|
+
...this.basePipeline(),
|
|
474
|
+
{
|
|
475
|
+
$group: {
|
|
476
|
+
_id: { a: `$${f1}`, b: `$${f2}` },
|
|
477
|
+
...buildGroupExpr(metrics),
|
|
478
|
+
},
|
|
479
|
+
},
|
|
480
|
+
{ $sort: { '_id.a': 1, '_id.b': 1 } },
|
|
481
|
+
...(opts.limit ? [{ $limit: opts.limit }] : []),
|
|
482
|
+
];
|
|
483
|
+
const rows = await this.run(pipeline);
|
|
484
|
+
return rows.map((r) => {
|
|
485
|
+
const id = r._id;
|
|
486
|
+
return { key: id.a, key2: id.b, ...finalizeDistinctCounts(r, metrics) };
|
|
487
|
+
});
|
|
488
|
+
}
|
|
489
|
+
// ── Funnel ────────────────────────────────────────────────────────────────
|
|
490
|
+
/**
|
|
491
|
+
* Sequential funnel: each step's count is the number of base documents
|
|
492
|
+
* matching that step's `match` condition ANDed with the base filter.
|
|
493
|
+
* Steps are independent counts — pass cumulative conditions yourself if
|
|
494
|
+
* step N should imply step N-1.
|
|
495
|
+
*/
|
|
496
|
+
async funnel(steps) {
|
|
497
|
+
if (steps.length === 0)
|
|
498
|
+
return [];
|
|
499
|
+
const counts = await Promise.all(steps.map((step) => {
|
|
500
|
+
const pipeline = [
|
|
501
|
+
{ $match: { ...this._serverConditions, ...step.match } },
|
|
502
|
+
...this._extraStages,
|
|
503
|
+
{ $count: 'count' },
|
|
504
|
+
];
|
|
505
|
+
return this.run(pipeline).then((r) => r[0]?.count ?? 0);
|
|
506
|
+
}));
|
|
507
|
+
const startCount = counts[0] || 0;
|
|
508
|
+
return steps.map((step, i) => ({
|
|
509
|
+
name: step.name,
|
|
510
|
+
count: counts[i],
|
|
511
|
+
conversionFromPrevious: i === 0
|
|
512
|
+
? null
|
|
513
|
+
: counts[i - 1] === 0
|
|
514
|
+
? null
|
|
515
|
+
: Number(((counts[i] / counts[i - 1]) * 100).toFixed(2)),
|
|
516
|
+
conversionFromStart: i === 0
|
|
517
|
+
? null
|
|
518
|
+
: startCount === 0
|
|
519
|
+
? null
|
|
520
|
+
: Number(((counts[i] / startCount) * 100).toFixed(2)),
|
|
521
|
+
}));
|
|
522
|
+
}
|
|
523
|
+
// ── Cohort retention ──────────────────────────────────────────────────────
|
|
524
|
+
/**
|
|
525
|
+
* Buckets entities by their cohort period (first occurrence of
|
|
526
|
+
* `cohortDateField`) and, for each cohort, counts distinct `idField`s with
|
|
527
|
+
* an activity (`activityDateField`) in each subsequent period offset
|
|
528
|
+
* (0 = the cohort period itself). Good for classic "% of signups still
|
|
529
|
+
* active N weeks later" retention tables.
|
|
530
|
+
*/
|
|
531
|
+
async cohortRetention(opts) {
|
|
532
|
+
const { cohortDateField, activityDateField, idField, cohortInterval, periods, } = opts;
|
|
533
|
+
const tz = this.options.timezone;
|
|
534
|
+
const wso = this.options.weekStartsOn;
|
|
535
|
+
// Cohort assignment: bucket of cohortDateField per entity.
|
|
536
|
+
const cohortPipeline = [
|
|
537
|
+
...this.basePipeline(),
|
|
538
|
+
dateTruncStage(cohortDateField, cohortInterval, tz, wso, '__cohort'),
|
|
539
|
+
{ $group: { _id: `$${idField}`, cohort: { $min: '$__cohort' } } },
|
|
540
|
+
];
|
|
541
|
+
const cohortRows = await this.run(cohortPipeline);
|
|
542
|
+
const cohortById = new Map(cohortRows.map((r) => [String(r._id), r.cohort]));
|
|
543
|
+
// Activity bucket per entity per period.
|
|
544
|
+
const activityPipeline = [
|
|
545
|
+
...this.basePipeline(),
|
|
546
|
+
dateTruncStage(activityDateField, cohortInterval, tz, wso, '__activity'),
|
|
547
|
+
{ $group: { _id: { id: `$${idField}`, bucket: '$__activity' } } },
|
|
548
|
+
];
|
|
549
|
+
const activityRows = await this.run(activityPipeline);
|
|
550
|
+
const cohortSizes = new Map();
|
|
551
|
+
for (const [id, cohort] of cohortById) {
|
|
552
|
+
const key = cohort.toISOString();
|
|
553
|
+
if (!cohortSizes.has(key))
|
|
554
|
+
cohortSizes.set(key, new Set());
|
|
555
|
+
cohortSizes.get(key).add(id);
|
|
556
|
+
}
|
|
557
|
+
// retained[cohortKey][periodOffset] = Set of ids active in that offset
|
|
558
|
+
const retained = new Map();
|
|
559
|
+
for (const row of activityRows) {
|
|
560
|
+
const id = String(row._id.id);
|
|
561
|
+
const cohort = cohortById.get(id);
|
|
562
|
+
if (!cohort)
|
|
563
|
+
continue;
|
|
564
|
+
const offset = periodOffset(cohort, row._id.bucket, cohortInterval);
|
|
565
|
+
if (offset < 0 || offset > periods)
|
|
566
|
+
continue;
|
|
567
|
+
const cohortKey = cohort.toISOString();
|
|
568
|
+
if (!retained.has(cohortKey))
|
|
569
|
+
retained.set(cohortKey, new Map());
|
|
570
|
+
const byOffset = retained.get(cohortKey);
|
|
571
|
+
if (!byOffset.has(offset))
|
|
572
|
+
byOffset.set(offset, new Set());
|
|
573
|
+
byOffset.get(offset).add(id);
|
|
574
|
+
}
|
|
575
|
+
const cohortKeys = Array.from(cohortSizes.keys()).sort();
|
|
576
|
+
return cohortKeys.map((cohortKey) => {
|
|
577
|
+
const size = cohortSizes.get(cohortKey).size;
|
|
578
|
+
const byOffset = retained.get(cohortKey) ?? new Map();
|
|
579
|
+
const retention = [];
|
|
580
|
+
const retentionPct = [];
|
|
581
|
+
for (let offset = 0; offset <= periods; offset++) {
|
|
582
|
+
const count = byOffset.get(offset)?.size ?? (offset === 0 ? size : 0);
|
|
583
|
+
retention.push(count);
|
|
584
|
+
retentionPct.push(size === 0 ? null : Number(((count / size) * 100).toFixed(2)));
|
|
585
|
+
}
|
|
586
|
+
return { cohort: cohortKey, cohortSize: size, retention, retentionPct };
|
|
587
|
+
});
|
|
588
|
+
}
|
|
589
|
+
// ── Sessionization ────────────────────────────────────────────────────────
|
|
590
|
+
/**
|
|
591
|
+
* Groups per-user events into sessions using native $setWindowFields +
|
|
592
|
+
* $shift gap detection (a session breaks when the idle gap since the
|
|
593
|
+
* previous event exceeds `gapMinutes`), then summarizes each session.
|
|
594
|
+
*/
|
|
595
|
+
async sessionize(opts) {
|
|
596
|
+
const { userField, dateField, gapMinutes } = opts;
|
|
597
|
+
const gapMs = gapMinutes * 60 * 1000;
|
|
598
|
+
const pipeline = [
|
|
599
|
+
...this.basePipeline(),
|
|
600
|
+
{ $sort: { [userField]: 1, [dateField]: 1 } },
|
|
601
|
+
{
|
|
602
|
+
$setWindowFields: {
|
|
603
|
+
partitionBy: `$${userField}`,
|
|
604
|
+
sortBy: { [dateField]: 1 },
|
|
605
|
+
output: { __prevTs: { $shift: { output: `$${dateField}`, by: -1 } } },
|
|
606
|
+
},
|
|
607
|
+
},
|
|
608
|
+
{
|
|
609
|
+
$addFields: {
|
|
610
|
+
__newSession: {
|
|
611
|
+
$cond: [
|
|
612
|
+
{ $eq: ['$__prevTs', null] },
|
|
613
|
+
1,
|
|
614
|
+
{ $gt: [{ $subtract: [`$${dateField}`, '$__prevTs'] }, gapMs] },
|
|
615
|
+
],
|
|
616
|
+
},
|
|
617
|
+
},
|
|
618
|
+
},
|
|
619
|
+
{
|
|
620
|
+
$setWindowFields: {
|
|
621
|
+
partitionBy: `$${userField}`,
|
|
622
|
+
sortBy: { [dateField]: 1 },
|
|
623
|
+
output: {
|
|
624
|
+
__sessionIndex: {
|
|
625
|
+
$sum: { $cond: ['$__newSession', 1, 0] },
|
|
626
|
+
window: { documents: ['unbounded', 'current'] },
|
|
627
|
+
},
|
|
628
|
+
},
|
|
629
|
+
},
|
|
630
|
+
},
|
|
631
|
+
{
|
|
632
|
+
$group: {
|
|
633
|
+
_id: { user: `$${userField}`, session: '$__sessionIndex' },
|
|
634
|
+
sessionStart: { $min: `$${dateField}` },
|
|
635
|
+
sessionEnd: { $max: `$${dateField}` },
|
|
636
|
+
eventCount: { $sum: 1 },
|
|
637
|
+
},
|
|
638
|
+
},
|
|
639
|
+
{ $sort: { sessionStart: 1 } },
|
|
640
|
+
];
|
|
641
|
+
const rows = await this.run(pipeline);
|
|
642
|
+
return rows.map((r) => ({
|
|
643
|
+
userId: r._id.user,
|
|
644
|
+
sessionStart: r.sessionStart.toISOString(),
|
|
645
|
+
sessionEnd: r.sessionEnd.toISOString(),
|
|
646
|
+
eventCount: r.eventCount,
|
|
647
|
+
durationSeconds: Math.round((r.sessionEnd.getTime() - r.sessionStart.getTime()) / 1000),
|
|
648
|
+
}));
|
|
649
|
+
}
|
|
650
|
+
// ── Percentiles & outliers ────────────────────────────────────────────────
|
|
651
|
+
/** Computes percentiles (0-100) of `field` over the current filter, using native $percentile. */
|
|
652
|
+
async percentiles(field, ps) {
|
|
653
|
+
const pipeline = [
|
|
654
|
+
...this.basePipeline(),
|
|
655
|
+
{
|
|
656
|
+
$group: {
|
|
657
|
+
_id: null,
|
|
658
|
+
values: {
|
|
659
|
+
$percentile: {
|
|
660
|
+
input: `$${field}`,
|
|
661
|
+
p: ps.map((p) => p / 100),
|
|
662
|
+
method: 'approximate',
|
|
663
|
+
},
|
|
664
|
+
},
|
|
665
|
+
},
|
|
666
|
+
},
|
|
667
|
+
];
|
|
668
|
+
const [row] = await this.run(pipeline);
|
|
669
|
+
const out = {};
|
|
670
|
+
ps.forEach((p, i) => {
|
|
671
|
+
out[`p${p}`] = row?.values?.[i] ?? null;
|
|
672
|
+
});
|
|
673
|
+
return out;
|
|
674
|
+
}
|
|
675
|
+
/**
|
|
676
|
+
* Flags documents whose `field` value is more than `threshold` standard
|
|
677
|
+
* deviations from the mean (native $stdDevPop, single extra pass to fetch
|
|
678
|
+
* the flagged rows). Good for a quick "anomalies" widget.
|
|
679
|
+
*/
|
|
680
|
+
async stdDevOutliers(field, opts = {}) {
|
|
681
|
+
const threshold = opts.threshold ?? 3;
|
|
682
|
+
const limit = opts.limit ?? 50;
|
|
683
|
+
const [stats] = await this.run([
|
|
684
|
+
...this.basePipeline(),
|
|
685
|
+
{
|
|
686
|
+
$group: {
|
|
687
|
+
_id: null,
|
|
688
|
+
mean: { $avg: `$${field}` },
|
|
689
|
+
stdDev: { $stdDevPop: `$${field}` },
|
|
690
|
+
},
|
|
691
|
+
},
|
|
692
|
+
]);
|
|
693
|
+
if (!stats || !stats.stdDev)
|
|
694
|
+
return [];
|
|
695
|
+
const pipeline = [
|
|
696
|
+
...this.basePipeline(),
|
|
697
|
+
{
|
|
698
|
+
$addFields: {
|
|
699
|
+
__z: {
|
|
700
|
+
$divide: [{ $subtract: [`$${field}`, stats.mean] }, stats.stdDev],
|
|
701
|
+
},
|
|
702
|
+
},
|
|
703
|
+
},
|
|
704
|
+
{ $match: { __z: { $not: { $gte: -threshold, $lte: threshold } } } },
|
|
705
|
+
{ $sort: { __z: -1 } },
|
|
706
|
+
{ $limit: limit },
|
|
707
|
+
];
|
|
708
|
+
const rows = await this.run(pipeline);
|
|
709
|
+
return rows.map((r) => ({
|
|
710
|
+
_id: r._id,
|
|
711
|
+
value: r[field],
|
|
712
|
+
zScore: Number(r.__z.toFixed(3)),
|
|
713
|
+
...r,
|
|
714
|
+
}));
|
|
715
|
+
}
|
|
716
|
+
// ── One-shot multi-metric summary ─────────────────────────────────────────
|
|
717
|
+
/** Computes several independent StatSpec metrics in one aggregate call — cheaper than N separate calls for a KPI-strip widget. */
|
|
718
|
+
async metrics(specs) {
|
|
719
|
+
const pipeline = [
|
|
720
|
+
...this.basePipeline(),
|
|
721
|
+
{ $group: { _id: null, ...buildGroupExpr(specs) } },
|
|
722
|
+
];
|
|
723
|
+
const [row] = await this.run(pipeline);
|
|
724
|
+
return finalizeDistinctCounts(row ?? {}, specs);
|
|
725
|
+
}
|
|
726
|
+
// ── Moving average, trend, forecast (pure JS post-processing) ────────────
|
|
727
|
+
/** Adds a trailing moving average over an already-fetched time series. */
|
|
728
|
+
static movingAverage(series, metric, windowSize, outKey = `${metric}_ma`) {
|
|
729
|
+
if (windowSize < 1)
|
|
730
|
+
throw new QueryAnalyticsError('movingAverage: windowSize must be >= 1');
|
|
731
|
+
return series.map((point, i) => {
|
|
732
|
+
const start = Math.max(0, i - windowSize + 1);
|
|
733
|
+
const window = series.slice(start, i + 1);
|
|
734
|
+
const sum = window.reduce((acc, p) => acc + (Number(p[metric]) || 0), 0);
|
|
735
|
+
return { ...point, [outKey]: Number((sum / window.length).toFixed(4)) };
|
|
736
|
+
});
|
|
737
|
+
}
|
|
738
|
+
/** Simple up/down/flat trend classification comparing the average of the last `n` points to the `n` before that. */
|
|
739
|
+
static trend(series, metric, n = 3, flatThresholdPct = 2) {
|
|
740
|
+
if (series.length < n * 2)
|
|
741
|
+
return 'insufficient_data';
|
|
742
|
+
const recent = series.slice(-n);
|
|
743
|
+
const prior = series.slice(-2 * n, -n);
|
|
744
|
+
const avg = (arr) => arr.reduce((a, p) => a + (Number(p[metric]) || 0), 0) / arr.length;
|
|
745
|
+
const recentAvg = avg(recent);
|
|
746
|
+
const priorAvg = avg(prior);
|
|
747
|
+
if (priorAvg === 0)
|
|
748
|
+
return recentAvg === 0 ? 'flat' : 'up';
|
|
749
|
+
const pctChange = ((recentAvg - priorAvg) / priorAvg) * 100;
|
|
750
|
+
if (Math.abs(pctChange) < flatThresholdPct)
|
|
751
|
+
return 'flat';
|
|
752
|
+
return pctChange > 0 ? 'up' : 'down';
|
|
753
|
+
}
|
|
754
|
+
/** Simple linear-regression forecast for `periodsAhead` future buckets, based on the existing series' trend line. Good enough for a dashed projection line — not a substitute for real forecasting models. */
|
|
755
|
+
static forecast(series, metric, periodsAhead) {
|
|
756
|
+
const n = series.length;
|
|
757
|
+
if (n < 2)
|
|
758
|
+
return [];
|
|
759
|
+
const xs = series.map((_, i) => i);
|
|
760
|
+
const ys = series.map((p) => Number(p[metric]) || 0);
|
|
761
|
+
const xMean = xs.reduce((a, b) => a + b, 0) / n;
|
|
762
|
+
const yMean = ys.reduce((a, b) => a + b, 0) / n;
|
|
763
|
+
let num = 0;
|
|
764
|
+
let den = 0;
|
|
765
|
+
for (let i = 0; i < n; i++) {
|
|
766
|
+
num += (xs[i] - xMean) * (ys[i] - yMean);
|
|
767
|
+
den += (xs[i] - xMean) ** 2;
|
|
768
|
+
}
|
|
769
|
+
const slope = den === 0 ? 0 : num / den;
|
|
770
|
+
const intercept = yMean - slope * xMean;
|
|
771
|
+
const out = [];
|
|
772
|
+
for (let i = 1; i <= periodsAhead; i++) {
|
|
773
|
+
const x = n - 1 + i;
|
|
774
|
+
out.push({
|
|
775
|
+
index: x,
|
|
776
|
+
predicted: Number((slope * x + intercept).toFixed(4)),
|
|
777
|
+
});
|
|
778
|
+
}
|
|
779
|
+
return out;
|
|
780
|
+
}
|
|
781
|
+
// ── Heatmap (hour-of-day x day-of-week) ──────────────────────────────────
|
|
782
|
+
/** Counts (or sums `valueField`) by weekday (0=Sun..6=Sat, local tz) x hour-of-day (0-23, local tz). */
|
|
783
|
+
async heatmap(dateField, valueField) {
|
|
784
|
+
const tz = this.options.timezone;
|
|
785
|
+
const pipeline = [
|
|
786
|
+
...this.basePipeline(),
|
|
787
|
+
{
|
|
788
|
+
$addFields: {
|
|
789
|
+
__weekday: {
|
|
790
|
+
$subtract: [
|
|
791
|
+
{ $dayOfWeek: { date: `$${dateField}`, timezone: tz } },
|
|
792
|
+
1,
|
|
793
|
+
],
|
|
794
|
+
},
|
|
795
|
+
__hour: { $hour: { date: `$${dateField}`, timezone: tz } },
|
|
796
|
+
},
|
|
797
|
+
},
|
|
798
|
+
{
|
|
799
|
+
$group: {
|
|
800
|
+
_id: { weekday: '$__weekday', hour: '$__hour' },
|
|
801
|
+
value: valueField ? { $sum: `$${valueField}` } : { $sum: 1 },
|
|
802
|
+
},
|
|
803
|
+
},
|
|
804
|
+
{ $sort: { '_id.weekday': 1, '_id.hour': 1 } },
|
|
805
|
+
];
|
|
806
|
+
const rows = await this.run(pipeline);
|
|
807
|
+
return rows.map((r) => ({
|
|
808
|
+
weekday: r._id.weekday,
|
|
809
|
+
hour: r._id.hour,
|
|
810
|
+
value: r.value,
|
|
811
|
+
}));
|
|
812
|
+
}
|
|
813
|
+
// ── Live updates ──────────────────────────────────────────────────────────
|
|
814
|
+
/**
|
|
815
|
+
* Subscribes to a MongoDB change stream on this model's collection and
|
|
816
|
+
* invokes `onChange` for every insert/update/delete/replace matching the
|
|
817
|
+
* current .match() filter (translated to a $match on `fullDocument`
|
|
818
|
+
* fields). Returns the underlying ChangeStream so the caller can
|
|
819
|
+
* `.close()` it. Useful for pushing live dashboard updates over a
|
|
820
|
+
* websocket instead of polling.
|
|
821
|
+
*/
|
|
822
|
+
watch(onChange, opts = {}) {
|
|
823
|
+
const matchStage = {};
|
|
824
|
+
if (opts.operationTypes?.length)
|
|
825
|
+
matchStage.operationType = { $in: opts.operationTypes };
|
|
826
|
+
for (const [k, v] of Object.entries(this._serverConditions)) {
|
|
827
|
+
matchStage[`fullDocument.${k}`] = v;
|
|
828
|
+
}
|
|
829
|
+
// Model.watch()'s pipeline param is typed as Record<string, unknown>[] (unlike
|
|
830
|
+
// aggregate()'s PipelineStage[]) — pipeline already matches that shape as-is.
|
|
831
|
+
const pipeline = Object.keys(matchStage).length > 0 ? [{ $match: matchStage }] : [];
|
|
832
|
+
const stream = this.model.watch(pipeline, { fullDocument: 'updateLookup' });
|
|
833
|
+
stream.on('change', onChange);
|
|
834
|
+
return stream;
|
|
835
|
+
}
|
|
836
|
+
// ── Export ────────────────────────────────────────────────────────────────
|
|
837
|
+
/** Flattens an array of plain-object rows into a CSV string (handy for timeSeries/breakdown results). */
|
|
838
|
+
static toCSV(rows) {
|
|
839
|
+
if (rows.length === 0)
|
|
840
|
+
return '';
|
|
841
|
+
const headers = Array.from(rows.reduce((set, r) => {
|
|
842
|
+
Object.keys(r).forEach((k) => set.add(k));
|
|
843
|
+
return set;
|
|
844
|
+
}, new Set()));
|
|
845
|
+
const escape = (v) => {
|
|
846
|
+
const s = v === null || v === undefined ? '' : String(v);
|
|
847
|
+
return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
|
|
848
|
+
};
|
|
849
|
+
const lines = [
|
|
850
|
+
headers.join(','),
|
|
851
|
+
...rows.map((r) => headers.map((h) => escape(r[h])).join(',')),
|
|
852
|
+
];
|
|
853
|
+
return lines.join('\n');
|
|
854
|
+
}
|
|
855
|
+
/** Newline-delimited JSON export — friendlier than a giant JSON array for streaming large exports to disk/S3. */
|
|
856
|
+
static toNDJSON(rows) {
|
|
857
|
+
return rows.map((r) => JSON.stringify(r)).join('\n');
|
|
858
|
+
}
|
|
859
|
+
// ── Dashboard batch runner ────────────────────────────────────────────────
|
|
860
|
+
/**
|
|
861
|
+
* Runs several named analytics calls in parallel and returns them keyed by
|
|
862
|
+
* name — for building a whole dashboard in one round trip from the
|
|
863
|
+
* caller's perspective.
|
|
864
|
+
*/
|
|
865
|
+
static async dashboard(tasks) {
|
|
866
|
+
const keys = Object.keys(tasks);
|
|
867
|
+
const results = await Promise.all(keys.map((k) => tasks[k]()));
|
|
868
|
+
const out = {};
|
|
869
|
+
keys.forEach((k, i) => {
|
|
870
|
+
out[k] = results[i];
|
|
871
|
+
});
|
|
872
|
+
return out;
|
|
873
|
+
}
|
|
874
|
+
}
|
|
875
|
+
exports.QueryAnalytics = QueryAnalytics;
|
|
876
|
+
exports.default = QueryAnalytics;
|
|
877
|
+
//# sourceMappingURL=analytics.js.map
|