mongoose-query-find 3.3.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.
@@ -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