mongoose-query-find 4.0.0 → 4.0.1
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 +477 -1342
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,1611 +1,746 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
- [
|
|
42
|
-
- [Constructor & Options](#constructor--options-1)
|
|
43
|
-
- [Timezone Handling](#timezone-handling)
|
|
44
|
-
- [Builder Methods](#builder-methods-1)
|
|
45
|
-
- [.allowFields()](#allowfieldsfields-string-1)
|
|
46
|
-
- [.dateFields()](#datefieldsfields-string)
|
|
47
|
-
- [.objectIdFields()](#objectidfieldsfields-string)
|
|
48
|
-
- [.filter()](#filter-1)
|
|
49
|
-
- [.where()](#whereconditions-1)
|
|
50
|
-
- [.range()](#rangefield-string-preset-rangepreset)
|
|
51
|
-
- [Custom Range Methods](#custom-range-methods)
|
|
52
|
-
- [.rangeCustomDay()](#rangecustomdayfield-string-date-string)
|
|
53
|
-
- [.rangeBetween()](#rangebetweenfield-string-custom-customdaterangeinput)
|
|
54
|
-
- [.rangeLastNDays()](#rangelastndaysfield-string-days-number)
|
|
55
|
-
- [.rangeLastNHours()](#rangelastnhoursfield-string-hours-number)
|
|
56
|
-
- [.rangeHours()](#rangehoursfield-string-custom-customhourrangeinput)
|
|
57
|
-
- [.rangeCustom()](#rangecustomfield-string-custom-customdatetimerangeinput)
|
|
58
|
-
- [.excludeSoftDeleted()](#excludesoftdeletedfield-deletedat)
|
|
59
|
-
- [.whereIf()](#whereifcondition-conditions)
|
|
60
|
-
- [.globalSearch()](#globalsearchfields-string-1)
|
|
61
|
-
- [.sort()](#sort-1)
|
|
62
|
-
- [.project()](#projectdefaultprojection-string--recordstring-0--1)
|
|
63
|
-
- [.lookup()](#lookupopts-lookupoptions)
|
|
64
|
-
- [.computeField()](#computefieldname-string-expression-unknown)
|
|
65
|
-
- [.addStage()](#addstagestage-pipelinestage)
|
|
66
|
-
- [Terminal & Utility Methods](#terminal--utility-methods)
|
|
67
|
-
- [.paginate()](#paginatecachedtotal-number)
|
|
68
|
-
- [.paginateCursor()](#paginatecursoropts-cursorpaginateoptions)
|
|
69
|
-
- [.count()](#count)
|
|
70
|
-
- [.distinct()](#distinctfield-string)
|
|
71
|
-
- [.stats()](#statsspecs-statspec)
|
|
72
|
-
- [.stream()](#stream)
|
|
73
|
-
- [.explain()](#explainverbosity)
|
|
74
|
-
- [.clone()](#clone)
|
|
75
|
-
- [.debugPipeline()](#debugpipeline)
|
|
76
|
-
- [Recipes](#recipes)
|
|
77
|
-
- [Pipeline Stage Ordering](#pipeline-stage-ordering)
|
|
78
|
-
- [Security](#security-1)
|
|
79
|
-
- [TypeScript Types](#typescript-types-1)
|
|
80
|
-
- [Links](#links-1)
|
|
81
|
-
- [License](#license-1)
|
|
82
|
-
|
|
83
|
-
**QueryAnalytics**
|
|
84
|
-
|
|
85
|
-
- [Overview](#queryanalytics-overview)
|
|
86
|
-
- [When to use QueryAnalytics](#when-to-use-queryanalytics)
|
|
87
|
-
- [Installation](#installation-2)
|
|
88
|
-
- [Quick Start](#quick-start-2)
|
|
89
|
-
- [Constructor & Options](#constructor--options-2)
|
|
90
|
-
- [Base Filter Methods](#base-filter-methods)
|
|
91
|
-
- [.match()](#matchconditions)
|
|
92
|
-
- [.dateRange()](#daterangefield-string-range--from-string-to-string-)
|
|
93
|
-
- [.addStage()](#addstagestage-pipelinestage-1)
|
|
94
|
-
- [.clone()](#clone-1)
|
|
95
|
-
- [Time Series](#time-series)
|
|
96
|
-
- [.timeSeries()](#timeseriesopts)
|
|
97
|
-
- [.cumulativeSeries()](#cumulativeseriesopts)
|
|
98
|
-
- [Comparisons & Breakdowns](#comparisons--breakdowns)
|
|
99
|
-
- [.compare()](#compareopts)
|
|
100
|
-
- [.breakdown()](#breakdownfield-metrics-opts)
|
|
101
|
-
- [.rankedBreakdown()](#rankedbreakdownfield-metrics-opts)
|
|
102
|
-
- [.multiBreakdown()](#multibreakdownfields-metrics-opts)
|
|
103
|
-
- [Funnels & Cohorts](#funnels--cohorts)
|
|
104
|
-
- [.funnel()](#funnelsteps)
|
|
105
|
-
- [.cohortRetention()](#cohortretentionopts)
|
|
106
|
-
- [.sessionize()](#sessionizeopts)
|
|
107
|
-
- [Statistics](#statistics)
|
|
108
|
-
- [.percentiles()](#percentilesfield-ps)
|
|
109
|
-
- [.stdDevOutliers()](#stddevoutliersfield-opts)
|
|
110
|
-
- [.metrics()](#metricsspecs)
|
|
111
|
-
- [Post-Processing Helpers (static)](#post-processing-helpers-static)
|
|
112
|
-
- [QueryAnalytics.movingAverage()](#queryanalyticsmovingaverage)
|
|
113
|
-
- [QueryAnalytics.trend()](#queryanalyticstrend)
|
|
114
|
-
- [QueryAnalytics.forecast()](#queryanalyticsforecast)
|
|
115
|
-
- [.heatmap()](#heatmapdatefield-valuefield)
|
|
116
|
-
- [Live Updates](#live-updates)
|
|
117
|
-
- [.watch()](#watchonchange-opts)
|
|
118
|
-
- [Export & Batch Helpers (static)](#export--batch-helpers-static)
|
|
119
|
-
- [QueryAnalytics.toCSV() / toNDJSON()](#queryanalyticstocsv--tondjson)
|
|
120
|
-
- [QueryAnalytics.dashboard()](#queryanalyticsdashboard)
|
|
121
|
-
- [QueryAnalytics.clearCache()](#queryanalyticsclearcache)
|
|
122
|
-
- [Recipes](#recipes-1)
|
|
123
|
-
- [Security](#security-2)
|
|
124
|
-
- [TypeScript Types](#typescript-types-2)
|
|
125
|
-
- [Links](#links-2)
|
|
126
|
-
- [License](#license-2)
|
|
127
|
-
|
|
128
|
-
---
|
|
1
|
+
# QueryAnalytics
|
|
2
|
+
|
|
3
|
+
A purpose-built analytics/reporting layer for Mongoose (`^8 || ^9`), sitting alongside `QueryFind` and `QueryAggregate`. Where `QueryAggregate` is a general-purpose, client-input-safe pipeline builder, `QueryAnalytics` is a **server-authored dashboard toolkit**: time series, cohort retention, funnels, sessionization, percentiles, and more, each backed by a native MongoDB 7.0+ operator instead of a hand-rolled pipeline.
|
|
4
|
+
|
|
5
|
+
## QueryAnalytics Overview
|
|
6
|
+
|
|
7
|
+
`QueryAnalytics` wraps `Model.aggregate()` with dashboard-shaped methods that return ready-to-chart data instead of raw pipeline rows:
|
|
8
|
+
|
|
9
|
+
- `timeSeries()` / `cumulativeSeries()` — bucketed metrics over time, gap-filled, with a native running total
|
|
10
|
+
- `compare()` — period-over-period totals and % change for preset windows (today, this week, last 30 days, ...)
|
|
11
|
+
- `breakdown()` / `rankedBreakdown()` / `multiBreakdown()` — top-N by one or two dimensions, with an optional native dense rank
|
|
12
|
+
- `funnel()` — step-by-step conversion counts
|
|
13
|
+
- `cohortRetention()` — a full cohort-by-cohort retention matrix
|
|
14
|
+
- `sessionize()` — gap-based event sessionization
|
|
15
|
+
- `percentiles()` / `stdDevOutliers()` — native `$percentile` / `$stdDevPop` statistics
|
|
16
|
+
- `metrics()` — several independent totals in a single round trip
|
|
17
|
+
- `heatmap()` — weekday × hour-of-day activity grid
|
|
18
|
+
- `movingAverage()` / `trend()` / `forecast()` — pure-JS post-processing on a series you already fetched
|
|
19
|
+
- `watch()` — a live change-stream feed for dashboards that update in real time
|
|
20
|
+
- `toCSV()` / `toNDJSON()` / `dashboard()` — export and batch helpers
|
|
21
|
+
|
|
22
|
+
It targets **MongoDB 7.0+** and uses `$setWindowFields`, `$denseRank`, `$shift`, `$stdDevPop`, and `$percentile` directly — there's no fallback path for older servers, so calling `cumulativeSeries()`, `rankedBreakdown()`, `sessionize()`, `percentiles()`, or `stdDevOutliers()` against a pre-7.0 deployment will fail at the server, not in this library.
|
|
23
|
+
|
|
24
|
+
## When to use QueryAnalytics
|
|
25
|
+
|
|
26
|
+
| Need | Use |
|
|
27
|
+
| ---------------------------------------------------------------- | ---------------- |
|
|
28
|
+
| Filtered/sorted/paginated list from client query params | `QueryFind` |
|
|
29
|
+
| Joins, grouping, or a client-driven filtered data page | `QueryAggregate` |
|
|
30
|
+
| A chart-ready time series with gaps filled in | `QueryAnalytics` |
|
|
31
|
+
| Week-over-week / month-over-month KPI comparisons | `QueryAnalytics` |
|
|
32
|
+
| Top-N breakdowns, ranked leaderboards, or a two-dimension pivot | `QueryAnalytics` |
|
|
33
|
+
| Signup → activation → purchase funnel counts | `QueryAnalytics` |
|
|
34
|
+
| "% of signups still active N weeks later" retention tables | `QueryAnalytics` |
|
|
35
|
+
| Turning a raw event stream into user sessions | `QueryAnalytics` |
|
|
36
|
+
| p50/p90/p99 latency or order-value percentiles | `QueryAnalytics` |
|
|
37
|
+
| Flagging statistical outliers for an anomalies widget | `QueryAnalytics` |
|
|
38
|
+
| A whole dashboard's worth of metrics in one call from your route | `QueryAnalytics` |
|
|
39
|
+
| Pushing live updates to a dashboard instead of polling | `QueryAnalytics` |
|
|
40
|
+
|
|
41
|
+
`QueryAnalytics` is **not** a client-input parser. Unlike `QueryFind`/`QueryAggregate`, it has no `.filter()`, no `.allowFields()`, and no operator-rejection pass over untrusted input — see [Security](#security-2) below.
|
|
129
42
|
|
|
130
43
|
## Installation
|
|
131
44
|
|
|
132
|
-
|
|
133
|
-
npm install mongoose-query-find
|
|
134
|
-
```
|
|
45
|
+
Ships from the same package as `QueryFind` and `QueryAggregate`:
|
|
135
46
|
|
|
136
47
|
```bash
|
|
137
|
-
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
pnpm add mongoose-query-find
|
|
48
|
+
npm install mongoose-query-find
|
|
142
49
|
```
|
|
143
50
|
|
|
144
|
-
> **Peer dependency:** requires `mongoose ^8` or `mongoose ^9` installed in your project.
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
51
|
## Quick Start
|
|
149
52
|
|
|
150
53
|
```ts
|
|
151
|
-
import {
|
|
152
|
-
import
|
|
153
|
-
|
|
154
|
-
const result = await queryFind(UserModel.find(), req.query)
|
|
155
|
-
.allowFields(['name', 'email', 'role', 'createdAt'])
|
|
156
|
-
.where({ deletedAt: null })
|
|
157
|
-
.filter()
|
|
158
|
-
.globalSearch(['name', 'email'])
|
|
159
|
-
.sort()
|
|
160
|
-
.limitFields('-password -__v')
|
|
161
|
-
.paginate();
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
`result` will look like:
|
|
165
|
-
|
|
166
|
-
```json
|
|
167
|
-
{
|
|
168
|
-
"data": [...],
|
|
169
|
-
"total": 84,
|
|
170
|
-
"page": 2,
|
|
171
|
-
"totalPages": 9,
|
|
172
|
-
"limit": 10,
|
|
173
|
-
"hasNextPage": true,
|
|
174
|
-
"hasPrevPage": true
|
|
175
|
-
}
|
|
176
|
-
```
|
|
54
|
+
import { QueryAnalytics } from 'mongoose-query-find';
|
|
55
|
+
import OrderModel from './models/order';
|
|
177
56
|
|
|
178
|
-
|
|
57
|
+
const qa = new QueryAnalytics(OrderModel, { timezone: 'Asia/Dhaka' })
|
|
58
|
+
.match({ branchId, status: { $ne: 'CANCELLED' } })
|
|
59
|
+
.dateRange('createdAt', { from: '2026-08-01', to: '2026-08-31' });
|
|
179
60
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
61
|
+
const series = await qa.timeSeries({
|
|
62
|
+
dateField: 'createdAt',
|
|
63
|
+
interval: 'day',
|
|
64
|
+
metrics: [
|
|
65
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
66
|
+
{ name: 'orders', op: 'count' },
|
|
67
|
+
],
|
|
68
|
+
});
|
|
186
69
|
```
|
|
187
70
|
|
|
188
|
-
|
|
189
|
-
| ------------- | ----------------------------------- | ----------------------------------------------------- |
|
|
190
|
-
| `query` | `Query<TRawDocType[], TRawDocType>` | A Mongoose query, e.g. `Model.find()` |
|
|
191
|
-
| `queryString` | `QueryParams` | The parsed URL query object, e.g. `req.query` |
|
|
192
|
-
| `options` | `QueryFindOptions` _(optional)_ | Configuration options (see [Options](#options) below) |
|
|
71
|
+
`series` is a gap-filled array ready to hand straight to a charting library:
|
|
193
72
|
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
| `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
|
|
201
|
-
| `lean` | `boolean` | `true` | Whether `.find()` calls `.lean()` for faster plain-object reads. |
|
|
202
|
-
| `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
|
|
203
|
-
| `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a client-supplied value. |
|
|
204
|
-
|
|
205
|
-
---
|
|
206
|
-
|
|
207
|
-
## Builder Methods
|
|
208
|
-
|
|
209
|
-
All builder methods return `this` and are fully chainable. The recommended call order is:
|
|
210
|
-
|
|
211
|
-
```
|
|
212
|
-
allowFields → where → filter → globalSearch → sort → limitFields → populate → paginate
|
|
73
|
+
```json
|
|
74
|
+
[
|
|
75
|
+
{ "bucket": "2026-08-01T00:00:00.000Z", "revenue": 4820, "orders": 61 },
|
|
76
|
+
{ "bucket": "2026-08-02T00:00:00.000Z", "revenue": 0, "orders": 0 },
|
|
77
|
+
{ "bucket": "2026-08-03T00:00:00.000Z", "revenue": 5310, "orders": 74 }
|
|
78
|
+
]
|
|
213
79
|
```
|
|
214
80
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
### `.allowFields(fields: string[])`
|
|
218
|
-
|
|
219
|
-
Declares which fields may appear in URL filters, sort parameters, and field projections. Acts as an allowlist — any field not listed is silently stripped from client input before it reaches MongoDB.
|
|
220
|
-
|
|
221
|
-
**Call this before `.filter()`, `.sort()`, and `.limitFields()`.**
|
|
81
|
+
## Constructor & Options
|
|
222
82
|
|
|
223
83
|
```ts
|
|
224
|
-
|
|
84
|
+
new QueryAnalytics<T>(model, options?);
|
|
225
85
|
```
|
|
226
86
|
|
|
227
|
-
|
|
87
|
+
| Parameter | Type | Description |
|
|
88
|
+
| --------- | ----------------------- | --------------------------- |
|
|
89
|
+
| `model` | `Model<T>` | A Mongoose model |
|
|
90
|
+
| `options` | `QueryAnalyticsOptions` | Configuration, all optional |
|
|
228
91
|
|
|
229
|
-
###
|
|
92
|
+
### `QueryAnalyticsOptions`
|
|
230
93
|
|
|
231
|
-
|
|
94
|
+
| Option | Type | Default | Description |
|
|
95
|
+
| -------------- | --------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
+
| `timezone` | `string` | `'Asia/Dhaka'` | IANA timezone for bucketing and range math. Invalid values are validated once at construction and silently fall back to the default. |
|
|
97
|
+
| `maxTimeMS` | `number` | `8000` | Max time MongoDB may spend per query. Higher than `QueryFind`/`QueryAggregate`'s default since analytics pipelines tend to be heavier. `0` disables. |
|
|
98
|
+
| `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` for large `$group`/`$setWindowFields` stages. |
|
|
99
|
+
| `weekStartsOn` | `0–6` | `6` (Saturday) | Used by weekly bucketing (`interval: 'week'`), `compare({ preset: 'thisWeek' })`, and `cohortRetention()`. |
|
|
100
|
+
| `cacheTTLMs` | `number` | `0` | TTL in ms for the built-in in-memory cache. `0` disables caching. **See note below.** |
|
|
232
101
|
|
|
233
|
-
-
|
|
234
|
-
- Converts comparison operator names to MongoDB `$` syntax (`gt` → `$gt`, `lte` → `$lte`, etc.)
|
|
235
|
-
- Recursively coerces string booleans to real booleans (`"true"` → `true`, `"false"` → `false`)
|
|
236
|
-
- Coerces date-like strings to `Date` instances for fields named `createdAt`, `updatedAt`, `deletedAt`, `date`, `birthDate`, or `expiresAt`
|
|
237
|
-
- Recursively validates and rejects banned operators (`$where`, `$expr`, `$function`, etc.)
|
|
102
|
+
> **Note on `cacheTTLMs`:** the class ships a small in-memory TTL cache (`cacheGet`/`cacheSet`) and a `QueryAnalytics.clearCache()` static, but as of this release none of the public methods (`timeSeries`, `breakdown`, `metrics`, etc.) pass a cache key into it — so setting `cacheTTLMs` doesn't yet cache anything on its own. Treat it as reserved for a future release; if you need caching today, memoize at the call site (e.g. wrap `dashboard()` calls in your own short-lived cache).
|
|
238
103
|
|
|
239
|
-
|
|
104
|
+
## Base Filter Methods
|
|
240
105
|
|
|
241
|
-
|
|
242
|
-
GET /users?age[gte]=18&isActive=true&role=admin
|
|
243
|
-
```
|
|
106
|
+
### `.match(conditions)`
|
|
244
107
|
|
|
245
|
-
|
|
246
|
-
.filter()
|
|
247
|
-
// → { age: { $gte: 18 }, isActive: true, role: 'admin' }
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
### `.where(conditions)`
|
|
253
|
-
|
|
254
|
-
Applies mandatory server-side conditions that the URL **cannot override**. Use this for multi-tenancy, soft-delete exclusion, and any security-critical constraints.
|
|
108
|
+
Merges hard, developer-authored conditions into the base `$match`. Call as many times as needed — later calls merge over earlier ones on the same key via `Object.assign`.
|
|
255
109
|
|
|
256
110
|
```ts
|
|
257
|
-
.
|
|
111
|
+
qa.match({ branchId, status: { $ne: 'CANCELLED' } });
|
|
258
112
|
```
|
|
259
113
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
---
|
|
114
|
+
Because `QueryAnalytics` has no `.filter()`, `match()` is the _only_ way conditions enter the pipeline besides `.dateRange()` and `.addStage()` — there's no allowlist because there's no untrusted input path. Don't pass raw `req.query` into it directly; validate/whitelist any client-influenced value yourself first (see [Security](#security-2)).
|
|
263
115
|
|
|
264
|
-
### `.
|
|
116
|
+
### `.dateRange(field: string, range: { from: string; to: string })`
|
|
265
117
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
Search terms are regex-escaped to prevent ReDoS attacks.
|
|
269
|
-
|
|
270
|
-
```
|
|
271
|
-
GET /users?q=john
|
|
272
|
-
```
|
|
118
|
+
Hard, inclusive local-date range condition on `field`, converted to a UTC `$gte`/`$lt` window using the instance's timezone.
|
|
273
119
|
|
|
274
120
|
```ts
|
|
275
|
-
.
|
|
276
|
-
// → { $or: [{ name: /john/i }, { email: /john/i }] }
|
|
121
|
+
qa.dateRange('createdAt', { from: '2026-08-01', to: '2026-08-31' });
|
|
277
122
|
```
|
|
278
123
|
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
---
|
|
282
|
-
|
|
283
|
-
### `.sort()`
|
|
124
|
+
Throws `QueryAnalyticsError` if `from`/`to` aren't `YYYY-MM-DD`.
|
|
284
125
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
```
|
|
288
|
-
GET /users?sort=-createdAt,name
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
```ts
|
|
292
|
-
.sort()
|
|
293
|
-
// → sorts by createdAt DESC, then name ASC
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
Defaults to `{ createdAt: -1 }` when the `sort` param is absent. Fields not in the allowlist are silently skipped.
|
|
297
|
-
|
|
298
|
-
---
|
|
299
|
-
|
|
300
|
-
### `.limitFields(defaultFields?: string)`
|
|
301
|
-
|
|
302
|
-
Controls which fields are returned (projection). Uses the `?fields=` query param when present, otherwise falls back to `defaultFields`.
|
|
303
|
-
|
|
304
|
-
Fields requested via `?fields=` are filtered against the allowlist — clients cannot project sensitive fields like `password` or `resetToken`.
|
|
305
|
-
|
|
306
|
-
**Priority order:**
|
|
307
|
-
|
|
308
|
-
1. `?fields=` query param — always wins when present (allowlist-filtered)
|
|
309
|
-
2. `defaultFields` argument — used as fallback when no query param
|
|
310
|
-
3. No projection when both are absent (all fields returned)
|
|
311
|
-
|
|
312
|
-
```
|
|
313
|
-
GET /users?fields=name,email,role
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
```ts
|
|
317
|
-
.limitFields('-password -__v')
|
|
318
|
-
// With ?fields=name,email,role → selects only name, email, role
|
|
319
|
-
// Without ?fields → excludes password and __v
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
### `.populate(path: string | PopulateOptions, select?: string)`
|
|
325
|
-
|
|
326
|
-
Registers a populate directive. Chainable — each call appends to the internal list. All registered populates are applied inside `paginate()`.
|
|
126
|
+
### `.addStage(stage: PipelineStage)`
|
|
327
127
|
|
|
328
|
-
|
|
128
|
+
Escape hatch for extra developer-authored stages, spliced in right after the base `$match`, before any analytics-specific stages. Blocks `$out`/`$merge` recursively, at any nesting depth.
|
|
329
129
|
|
|
330
130
|
```ts
|
|
331
|
-
|
|
332
|
-
.populate('author')
|
|
333
|
-
|
|
334
|
-
// Path + select string
|
|
335
|
-
.populate('author', 'name email')
|
|
336
|
-
|
|
337
|
-
// Full PopulateOptions object
|
|
338
|
-
.populate({ path: 'comments', select: 'text createdAt', match: { visible: true } })
|
|
339
|
-
|
|
340
|
-
// Multiple calls — fully chainable
|
|
341
|
-
.populate('author')
|
|
342
|
-
.populate({ path: 'comments', select: 'text createdAt' })
|
|
131
|
+
qa.addStage({ $addFields: { margin: { $subtract: ['$price', '$cost'] } } });
|
|
343
132
|
```
|
|
344
133
|
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
## Terminal Method
|
|
348
|
-
|
|
349
|
-
### `.paginate()`
|
|
134
|
+
### `.clone()`
|
|
350
135
|
|
|
351
|
-
|
|
136
|
+
Copies the current filter state (`match()`/`dateRange()` conditions and `addStage()` stages) into a new, independent `QueryAnalytics` instance sharing the same options. Handy for branching one filtered base into several analytics calls without rebuilding the filter each time — see [Recipes](#recipes-1).
|
|
352
137
|
|
|
353
|
-
|
|
354
|
-
- Uses `estimatedDocumentCount` as a fast-path when no filter is applied (O(1) vs O(n)).
|
|
355
|
-
- `.lean()` is applied for ~3–5× faster reads on plain object responses.
|
|
356
|
-
- `maxTimeMS` is applied to both count and find to prevent runaway collection scans.
|
|
357
|
-
- If the requested `page` exceeds `totalPages` (e.g. after a deletion), page `1` is returned automatically.
|
|
138
|
+
## Time Series
|
|
358
139
|
|
|
359
|
-
|
|
360
|
-
GET /users?page=2&limit=20
|
|
361
|
-
```
|
|
140
|
+
### `.timeSeries(opts)`
|
|
362
141
|
|
|
363
|
-
|
|
142
|
+
Buckets documents by `dateField` into timezone-aligned `interval` buckets (`'hour' | 'day' | 'week' | 'month'`) via `$dateTrunc`, computes `metrics` per bucket, and — by default — fills empty buckets with zero values so a chart never shows a broken line for a quiet day.
|
|
364
143
|
|
|
365
144
|
```ts
|
|
366
|
-
{
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
totalPages: number;
|
|
371
|
-
limit: number;
|
|
372
|
-
hasNextPage: boolean;
|
|
373
|
-
hasPrevPage: boolean;
|
|
145
|
+
interface StatSpec {
|
|
146
|
+
name: string;
|
|
147
|
+
op: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinctCount';
|
|
148
|
+
field?: string; // required for every op except 'count'
|
|
374
149
|
}
|
|
375
|
-
```
|
|
376
|
-
|
|
377
|
-
**Defaults:** `page=1`, `limit=10`, max `limit=100`.
|
|
378
|
-
|
|
379
|
-
---
|
|
380
|
-
|
|
381
|
-
## Query Parameter Reference
|
|
382
|
-
|
|
383
|
-
| Parameter | Example | Description |
|
|
384
|
-
| ----------- | ------------------------- | ------------------------------------------------------ |
|
|
385
|
-
| `page` | `?page=3` | Page number (default: `1`, min: `1`) |
|
|
386
|
-
| `limit` | `?limit=25` | Documents per page (default: `10`, max: `100`) |
|
|
387
|
-
| `sort` | `?sort=-createdAt,name` | Sort fields; prefix `-` for descending (max: 5 fields) |
|
|
388
|
-
| `fields` | `?fields=name,email` | Comma-separated fields to include in the response |
|
|
389
|
-
| `q` | `?q=john` | Global search term (max: 200 chars) |
|
|
390
|
-
| _(any key)_ | `?role=admin&age[gte]=18` | Field-level filters processed by `.filter()` |
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## Full Example (Express)
|
|
395
|
-
|
|
396
|
-
```ts
|
|
397
|
-
import { Request, Response } from 'express';
|
|
398
|
-
import { queryFind } from 'mongoose-query-find';
|
|
399
|
-
import UserModel from '../models/user';
|
|
400
|
-
|
|
401
|
-
export const getUsers = async (req: Request, res: Response) => {
|
|
402
|
-
const result = await queryFind(UserModel.find(), req.query)
|
|
403
|
-
.allowFields(['name', 'email', 'username', 'role', 'isActive', 'createdAt'])
|
|
404
|
-
.where({ orgId: req.user.orgId, deletedAt: null })
|
|
405
|
-
.filter()
|
|
406
|
-
.globalSearch(['name', 'email', 'username'])
|
|
407
|
-
.sort()
|
|
408
|
-
.limitFields('-password -__v')
|
|
409
|
-
.populate('role', 'name permissions')
|
|
410
|
-
.paginate();
|
|
411
|
-
|
|
412
|
-
res.json({ status: 'success', ...result });
|
|
413
|
-
};
|
|
414
|
-
```
|
|
415
|
-
|
|
416
|
-
**Example requests:**
|
|
417
|
-
|
|
418
|
-
```bash
|
|
419
|
-
# Page 2, 15 per page, only active admins sorted by name
|
|
420
|
-
GET /users?page=2&limit=15&role=admin&isActive=true&sort=name
|
|
421
|
-
|
|
422
|
-
# Search "alice" across name, email, and username
|
|
423
|
-
GET /users?q=alice
|
|
424
|
-
|
|
425
|
-
# Users older than 25, return only name and email
|
|
426
|
-
GET /users?age[gt]=25&fields=name,email
|
|
427
|
-
|
|
428
|
-
# Filter by exact date
|
|
429
|
-
GET /users?createdAt=2024-06-01
|
|
430
|
-
|
|
431
|
-
# Filter by date range
|
|
432
|
-
GET /users?createdAt[gte]=2024-01-01&createdAt[lte]=2024-12-31
|
|
433
|
-
|
|
434
|
-
# Combined: search + filter + sort + pagination
|
|
435
|
-
GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
---
|
|
439
|
-
|
|
440
|
-
## More Examples
|
|
441
|
-
|
|
442
|
-
**E-commerce product listing — nested price filters + category populate:**
|
|
443
150
|
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
.paginate();
|
|
455
|
-
|
|
456
|
-
res.json(result);
|
|
457
|
-
};
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
```bash
|
|
461
|
-
# Price between $20 and $100, in stock, sorted cheapest first
|
|
462
|
-
GET /products?price[gte]=20&price[lte]=100&inStock=true&sort=price
|
|
463
|
-
|
|
464
|
-
# Search "nike" across name and brand
|
|
465
|
-
GET /products?q=nike&sort=-createdAt
|
|
466
|
-
```
|
|
467
|
-
|
|
468
|
-
**Blog posts — multiple populates + logical operators:**
|
|
469
|
-
|
|
470
|
-
```ts
|
|
471
|
-
export const getPosts = async (req: Request, res: Response) => {
|
|
472
|
-
const result = await queryFind(PostModel.find(), req.query)
|
|
473
|
-
.allowFields(['title', 'status', 'authorId', 'tags', 'publishedAt'])
|
|
474
|
-
.where({ deletedAt: null })
|
|
475
|
-
.filter()
|
|
476
|
-
.globalSearch(['title'])
|
|
477
|
-
.sort()
|
|
478
|
-
.limitFields('title status publishedAt')
|
|
479
|
-
.populate('authorId', 'name avatar')
|
|
480
|
-
.populate({
|
|
481
|
-
path: 'comments',
|
|
482
|
-
select: 'text createdAt',
|
|
483
|
-
match: { visible: true },
|
|
484
|
-
})
|
|
485
|
-
.paginate();
|
|
486
|
-
|
|
487
|
-
res.json(result);
|
|
488
|
-
};
|
|
151
|
+
await qa.timeSeries({
|
|
152
|
+
dateField: 'createdAt',
|
|
153
|
+
interval: 'day',
|
|
154
|
+
metrics: [
|
|
155
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
156
|
+
{ name: 'orders', op: 'count' },
|
|
157
|
+
{ name: 'customers', op: 'distinctCount', field: 'customerId' },
|
|
158
|
+
],
|
|
159
|
+
fillGaps: true, // default
|
|
160
|
+
});
|
|
489
161
|
```
|
|
490
162
|
|
|
491
|
-
|
|
492
|
-
# Published OR featured posts, using the safe top-level $or
|
|
493
|
-
GET /posts?$or[0][status]=published&$or[1][featured]=true
|
|
163
|
+
`interval: 'week'` respects the constructor's `weekStartsOn`. Set `fillGaps: false` to get back only buckets that actually had data.
|
|
494
164
|
|
|
495
|
-
|
|
496
|
-
GET /posts?tags=typescript&publishedAt[gte]=2026-01-01
|
|
497
|
-
```
|
|
165
|
+
### `.cumulativeSeries(opts)`
|
|
498
166
|
|
|
499
|
-
|
|
167
|
+
Same bucketing as `timeSeries()`, plus a native running-total column per metric (`${name}_cumulative`), computed server-side via `$setWindowFields` — no client-side accumulation pass.
|
|
500
168
|
|
|
501
169
|
```ts
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
.limitFields('-password -passwordResetToken -__v') // client's ?fields= can never override this
|
|
509
|
-
.paginate();
|
|
510
|
-
|
|
511
|
-
res.json(result);
|
|
512
|
-
};
|
|
170
|
+
await qa.cumulativeSeries({
|
|
171
|
+
dateField: 'createdAt',
|
|
172
|
+
interval: 'day',
|
|
173
|
+
metrics: [{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
174
|
+
});
|
|
175
|
+
// [{ bucket: '...', revenue: 420, revenue_cumulative: 420 }, { bucket: '...', revenue: 310, revenue_cumulative: 730 }, ...]
|
|
513
176
|
```
|
|
514
177
|
|
|
515
|
-
|
|
516
|
-
# Even if a client tries ?fields=password, it's stripped — not in allowFields()
|
|
517
|
-
GET /admin/users?fields=password,email&role=admin
|
|
518
|
-
```
|
|
178
|
+
`distinctCount` metrics are skipped for the cumulative column — a running distinct-count isn't a well-defined windowed sum. Unlike `timeSeries()`, this method has no `fillGaps` option.
|
|
519
179
|
|
|
520
|
-
|
|
180
|
+
## Comparisons & Breakdowns
|
|
521
181
|
|
|
522
|
-
|
|
523
|
-
export const getNotifications = async (req: Request, res: Response) => {
|
|
524
|
-
const builder = queryFind(NotificationModel.find(), req.query)
|
|
525
|
-
.allowFields(['userId', 'read', 'createdAt'])
|
|
526
|
-
.where({ userId: req.user.id })
|
|
527
|
-
.filter()
|
|
528
|
-
.sort();
|
|
529
|
-
|
|
530
|
-
// First request from the client includes no cachedTotal
|
|
531
|
-
const cachedTotal = req.query.cachedTotal
|
|
532
|
-
? Number(req.query.cachedTotal)
|
|
533
|
-
: undefined;
|
|
534
|
-
const result = await builder.paginate(cachedTotal);
|
|
535
|
-
|
|
536
|
-
res.json(result); // client stores result.total and sends it back as ?cachedTotal= on the next page
|
|
537
|
-
};
|
|
538
|
-
```
|
|
182
|
+
### `.compare(opts)`
|
|
539
183
|
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
## TypeScript Types
|
|
543
|
-
|
|
544
|
-
All types are exported:
|
|
184
|
+
Computes `metrics` for a preset current period and the equivalent prior period, plus absolute and percentage change.
|
|
545
185
|
|
|
546
186
|
```ts
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
QueryFindOptions,
|
|
553
|
-
QueryFindError,
|
|
554
|
-
QueryFindValidationError,
|
|
555
|
-
SlowQueryInfo,
|
|
556
|
-
} from 'mongoose-query-find';
|
|
557
|
-
```
|
|
558
|
-
|
|
559
|
-
```ts
|
|
560
|
-
interface QueryParams {
|
|
561
|
-
page?: string;
|
|
562
|
-
limit?: string;
|
|
563
|
-
sort?: string;
|
|
564
|
-
fields?: string;
|
|
565
|
-
q?: string;
|
|
566
|
-
[key: string]: unknown;
|
|
567
|
-
}
|
|
568
|
-
|
|
569
|
-
interface PaginatedResult<T> {
|
|
570
|
-
data: T[];
|
|
571
|
-
total: number;
|
|
572
|
-
page: number;
|
|
573
|
-
totalPages: number;
|
|
574
|
-
limit: number;
|
|
575
|
-
hasNextPage: boolean;
|
|
576
|
-
hasPrevPage: boolean;
|
|
187
|
+
interface CompareResult {
|
|
188
|
+
current: Record<string, number>;
|
|
189
|
+
previous: Record<string, number>;
|
|
190
|
+
change: Record<string, number>; // absolute delta
|
|
191
|
+
changePct: Record<string, number | null>; // null when previous was 0
|
|
577
192
|
}
|
|
578
193
|
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
onSlowQuery?: (info: SlowQueryInfo) => void;
|
|
585
|
-
onSanitizeDrop?: (path: string, value: unknown) => void;
|
|
586
|
-
}
|
|
587
|
-
|
|
588
|
-
interface SlowQueryInfo {
|
|
589
|
-
elapsedMs: number;
|
|
590
|
-
filter: Record<string, unknown>;
|
|
591
|
-
sort: Record<string, 1 | -1>;
|
|
592
|
-
page: number;
|
|
593
|
-
limit: number;
|
|
594
|
-
}
|
|
595
|
-
```
|
|
596
|
-
|
|
597
|
-
---
|
|
598
|
-
|
|
599
|
-
## Security
|
|
600
|
-
|
|
601
|
-
| Protection | Detail |
|
|
602
|
-
| --------------------------- | ---------------------------------------------------------------------------------------- |
|
|
603
|
-
| **NoSQL injection** | Allowlist enforced on filters, sort, and projection via `.allowFields()` |
|
|
604
|
-
| **Banned operators** | `$where`, `$expr`, `$function`, and others are rejected recursively at any nesting depth |
|
|
605
|
-
| **ReDoS** | Search terms are regex-escaped before compilation |
|
|
606
|
-
| **Oversized search** | `?q=` capped at 200 characters |
|
|
607
|
-
| **Deep nesting DoS** | Filter object nesting capped at depth 5 |
|
|
608
|
-
| **Page size DoS** | `limit` hard-capped at 100 |
|
|
609
|
-
| **Sort abuse** | Sort fields hard-capped at 5 |
|
|
610
|
-
| **Runaway queries** | `maxTimeMS` applied to both count and find (default: 5s) |
|
|
611
|
-
| **Sensitive field leakage** | `?fields=` projection stripped against allowlist |
|
|
612
|
-
|
|
613
|
-
---
|
|
614
|
-
|
|
615
|
-
## Links
|
|
616
|
-
|
|
617
|
-
- [npm](https://www.npmjs.com/package/mongoose-query-find)
|
|
618
|
-
- [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
|
|
619
|
-
- [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
|
|
620
|
-
|
|
621
|
-
---
|
|
622
|
-
|
|
623
|
-
## License
|
|
624
|
-
|
|
625
|
-
ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
|
|
626
|
-
|
|
627
|
-
<br>
|
|
628
|
-
<br>
|
|
629
|
-
|
|
630
|
-
---
|
|
631
|
-
|
|
632
|
-
---
|
|
633
|
-
|
|
634
|
-
# QueryAggregate
|
|
635
|
-
|
|
636
|
-
A fluent, allowlisted **aggregation-pipeline** builder for Mongoose (`^8 || ^9`), built on `Model.aggregate()`. It mirrors the same safety model as `QueryFind` — allowlisted filter fields, sanitized/rejected operators, capped pagination — but adds `$lookup` joins, `$group`, timezone-aware date filtering, custom date/hour ranges, keyset pagination, and one-round-trip dashboard stats.
|
|
637
|
-
|
|
638
|
-
## QueryAggregate Overview
|
|
639
|
-
|
|
640
|
-
`QueryFind` is built on `Model.find()` and can't express joins or grouping. `QueryAggregate` solves that while keeping the same guardrails, plus a lot more:
|
|
641
|
-
|
|
642
|
-
- Allowlisted filter/sort/projection fields
|
|
643
|
-
- Recursive sanitization of client input (drops class instances, functions, over-deep nesting)
|
|
644
|
-
- Banned-operator rejection (`$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`)
|
|
645
|
-
- Capped pagination (`limit`, `page`)
|
|
646
|
-
- Timezone-aware date coercion, `$lookup` joins, arbitrary developer-authored pipeline stages via `.addStage()`
|
|
647
|
-
- Single-round-trip pagination via `$facet`
|
|
648
|
-
- **New:** six custom date-range methods (arbitrary day, arbitrary span, rolling N-days/N-hours, hour-of-day windows, absolute datetime windows)
|
|
649
|
-
- **New:** `count()`, `distinct()`, and `stats()` for cheap metrics without fetching a data page
|
|
650
|
-
- **New:** `stream()` for memory-safe large exports, and `paginateCursor()` for keyset pagination on huge collections
|
|
651
|
-
- **New:** `explain()`, `debugPipeline()`, and `clone()` for debugging and query reuse
|
|
652
|
-
|
|
653
|
-
## When to use QueryAggregate vs QueryFind
|
|
654
|
-
|
|
655
|
-
| Need | Use |
|
|
656
|
-
| -------------------------------------------------------------- | ---------------- |
|
|
657
|
-
| Simple filter/sort/paginate on one collection | `QueryFind` |
|
|
658
|
-
| Joining another collection (`$lookup`) | `QueryAggregate` |
|
|
659
|
-
| Grouping / rollups / computed fields (`$group`, `$addFields`) | `QueryAggregate` |
|
|
660
|
-
| Client filters need to respect the caller's local timezone | `QueryAggregate` |
|
|
661
|
-
| A custom day / date span / rolling window / hour-of-day filter | `QueryAggregate` |
|
|
662
|
-
| Dashboard totals (sum/avg/count) without fetching a page | `QueryAggregate` |
|
|
663
|
-
| Very large collections where `$skip` pagination gets slow | `QueryAggregate` |
|
|
664
|
-
| Streaming a large export without buffering it in memory | `QueryAggregate` |
|
|
665
|
-
| You need a custom developer-defined pipeline stage | `QueryAggregate` |
|
|
666
|
-
|
|
667
|
-
## Installation
|
|
668
|
-
|
|
669
|
-
Ships from the same package as `QueryFind`:
|
|
670
|
-
|
|
671
|
-
```bash
|
|
672
|
-
npm install mongoose-query-find
|
|
673
|
-
```
|
|
674
|
-
|
|
675
|
-
## Quick Start
|
|
676
|
-
|
|
677
|
-
```ts
|
|
678
|
-
import { QueryAggregate } from 'mongoose-query-find';
|
|
679
|
-
import CategoryModel from './models/category';
|
|
680
|
-
|
|
681
|
-
const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
|
|
682
|
-
|
|
683
|
-
const result = await new QueryAggregate(CategoryModel, req.query, { timezone })
|
|
684
|
-
.allowFields(['name', 'status', 'createdAt'])
|
|
685
|
-
.dateFields(['createdAt'])
|
|
686
|
-
.where({ branchId: req.self.linkedTo, status: { $ne: 'ARCHIVED' } })
|
|
687
|
-
.filter()
|
|
688
|
-
.globalSearch(['name'])
|
|
689
|
-
.sort()
|
|
690
|
-
.project('name status createdAt updatedAt')
|
|
691
|
-
.paginate();
|
|
692
|
-
```
|
|
693
|
-
|
|
694
|
-
`result` shape is identical to `QueryFind`'s `PaginatedResult<T>`:
|
|
695
|
-
|
|
696
|
-
```json
|
|
697
|
-
{
|
|
698
|
-
"data": [...],
|
|
699
|
-
"total": 84,
|
|
700
|
-
"page": 2,
|
|
701
|
-
"totalPages": 9,
|
|
702
|
-
"limit": 10,
|
|
703
|
-
"hasNextPage": true,
|
|
704
|
-
"hasPrevPage": true
|
|
705
|
-
}
|
|
706
|
-
```
|
|
707
|
-
|
|
708
|
-
## Constructor & Options
|
|
709
|
-
|
|
710
|
-
```ts
|
|
711
|
-
new QueryAggregate<T>(model, queryString, options?);
|
|
712
|
-
```
|
|
713
|
-
|
|
714
|
-
| Parameter | Type | Description |
|
|
715
|
-
| ------------- | ----------------------- | ----------------------------------------------- |
|
|
716
|
-
| `model` | `Model<T>` | A Mongoose model |
|
|
717
|
-
| `queryString` | `QueryParams` | Parsed URL query object, e.g. `req.query` |
|
|
718
|
-
| `options` | `QueryAggregateOptions` | Configuration options (see below), all optional |
|
|
719
|
-
|
|
720
|
-
### `QueryAggregateOptions`
|
|
721
|
-
|
|
722
|
-
| Option | Type | Default | Description |
|
|
723
|
-
| ---------------------- | ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
724
|
-
| `timezone` | `string` | `'Asia/Dhaka'` | IANA timezone for interpreting client-supplied local dates. Invalid values fall back to the default (validated once at construction, never throws mid-query). |
|
|
725
|
-
| `maxTimeMS` | `number` | `5000` | Max time MongoDB may spend per query. `0` disables. |
|
|
726
|
-
| `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
|
|
727
|
-
| `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
|
|
728
|
-
| `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` — enable for large sort/group pipelines. |
|
|
729
|
-
| `weekStartsOn` | `0–6` | `6` (Saturday) | Used by `.range('thisWeek')`. |
|
|
730
|
-
| `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
|
|
731
|
-
| `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a value (bad nesting, non-plain value). |
|
|
732
|
-
|
|
733
|
-
## Timezone Handling
|
|
734
|
-
|
|
735
|
-
MongoDB always stores/compares dates in UTC. Clients think and filter in local time — `?createdAt=2026-09-01` means "Sept 1st in the caller's timezone," not UTC midnight.
|
|
736
|
-
|
|
737
|
-
- `fromZonedTime(localString, tz)` → exact UTC instant for a wall-clock time in `tz`. Used to turn a client-supplied local date into the correct `$gte`/`$lt` UTC range in `$match`.
|
|
738
|
-
- `toZonedTime(utcDate, tz)` → wall-clock `Date` for `tz`. Used to compute "what day is it right now, in the caller's timezone" for `.range()` presets and the rolling-N-days custom range.
|
|
739
|
-
|
|
740
|
-
The timezone is a **per-request** value, typically sourced from a header:
|
|
741
|
-
|
|
742
|
-
```ts
|
|
743
|
-
const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
|
|
194
|
+
const result = await qa.compare({
|
|
195
|
+
dateField: 'createdAt',
|
|
196
|
+
metrics: [{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
197
|
+
preset: 'last7Days',
|
|
198
|
+
});
|
|
744
199
|
```
|
|
745
200
|
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
Plain `YYYY-MM-DD` filter values are expanded into a `$gte`/`$lt` range spanning that local day; values with an explicit offset (`Z`, `+06:00`) are treated as absolute instants and passed through as-is. Every custom range method below applies the same timezone-aware logic.
|
|
749
|
-
|
|
750
|
-
## Builder Methods
|
|
751
|
-
|
|
752
|
-
All builder methods return `this` and are fully chainable. Recommended call order:
|
|
201
|
+
**Presets:** `'today' | 'thisWeek' | 'thisMonth' | 'last7Days' | 'last30Days'`. `'thisWeek'`/`'thisMonth'` compare against a prior period of the same length (e.g. 12 days into this month vs. the last 12 days of last month), and `'thisWeek'` respects `weekStartsOn`.
|
|
753
202
|
|
|
754
|
-
|
|
755
|
-
allowFields → dateFields/objectIdFields → where → range/rangeXxx → filter → globalSearch → sort → project → lookup/addStage/computeField → paginate/paginateCursor/count/distinct/stats/stream
|
|
756
|
-
```
|
|
757
|
-
|
|
758
|
-
---
|
|
203
|
+
> Any `.dateRange()` you've already applied on the instance is **ignored** here — the preset defines both windows on its own, independent of the instance's filter state. `.match()` conditions still apply to both windows.
|
|
759
204
|
|
|
760
|
-
### `.
|
|
205
|
+
### `.breakdown(field, metrics, opts)`
|
|
761
206
|
|
|
762
|
-
|
|
207
|
+
Groups by `field`, computes `metrics` per group, sorted and capped.
|
|
763
208
|
|
|
764
209
|
```ts
|
|
765
|
-
.
|
|
210
|
+
await qa.breakdown(
|
|
211
|
+
'category',
|
|
212
|
+
[{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
213
|
+
{
|
|
214
|
+
limit: 10, // default 10
|
|
215
|
+
sortBy: 'revenue', // default: metrics[0].name
|
|
216
|
+
sortDir: -1, // default -1
|
|
217
|
+
},
|
|
218
|
+
);
|
|
219
|
+
// [{ key: 'Electronics', revenue: 18400 }, { key: 'Home', revenue: 9210 }, ...]
|
|
766
220
|
```
|
|
767
221
|
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
### `.dateFields(fields: string[])`
|
|
222
|
+
### `.rankedBreakdown(field, metrics, opts)`
|
|
771
223
|
|
|
772
|
-
|
|
224
|
+
Same as `breakdown()`, but adds a native 1-based dense-rank column via `$setWindowFields`/`$denseRank` — no client-side re-sorting needed for a leaderboard UI.
|
|
773
225
|
|
|
774
226
|
```ts
|
|
775
|
-
.
|
|
227
|
+
await qa.rankedBreakdown('salesRepId', [
|
|
228
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
229
|
+
]);
|
|
230
|
+
// [{ key: 'rep_1', rank: 1, revenue: 18400 }, { key: 'rep_2', rank: 2, revenue: 18400 }, { key: 'rep_3', rank: 4, revenue: 9210 }, ...]
|
|
776
231
|
```
|
|
777
232
|
|
|
778
|
-
|
|
233
|
+
Ties share a rank and the next distinct value skips ahead (standard dense-rank semantics), so two reps tied for first both show `rank: 1` and the next lowest gets `rank: 2`.
|
|
779
234
|
|
|
780
|
-
### `.
|
|
235
|
+
### `.multiBreakdown(fields, metrics, opts)`
|
|
781
236
|
|
|
782
|
-
|
|
237
|
+
Pivot table: groups by two dimensions at once, one row per `(dimA, dimB)` pair.
|
|
783
238
|
|
|
784
239
|
```ts
|
|
785
|
-
.
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
1. Strips reserved keys (`page`, `sort`, `limit`, `fields`, `q`)
|
|
795
|
-
2. `sanitize()` — recursively drops non-plain values (class instances, functions), capped at nesting depth 5
|
|
796
|
-
3. `coerceAll()` — timezone-aware date coercion + ObjectId coercion + boolean coercion + numeric coercion + operator-name coercion (`gt` → `$gt`, etc.)
|
|
797
|
-
4. `enforceAllowlist()` — strips any non-operator key not in `.allowFields()`
|
|
798
|
-
5. `rejectDisallowedOperators()` — throws `QueryAggregateValidationError` on `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`, or any unexpected top-level `$` operator
|
|
799
|
-
|
|
800
|
-
```
|
|
801
|
-
GET /categories?createdAt=2026-09-01&status=ACTIVE
|
|
240
|
+
await qa.multiBreakdown(
|
|
241
|
+
['branchId', 'status'],
|
|
242
|
+
[{ name: 'orders', op: 'count' }],
|
|
243
|
+
{
|
|
244
|
+
limit: 200, // optional; no cap by default
|
|
245
|
+
},
|
|
246
|
+
);
|
|
247
|
+
// [{ key: 'branch_a', key2: 'PAID', orders: 40 }, { key: 'branch_a', key2: 'REFUNDED', orders: 3 }, ...]
|
|
802
248
|
```
|
|
803
249
|
|
|
804
|
-
|
|
805
|
-
.filter()
|
|
806
|
-
// → { createdAt: { $gte: <UTC midnight in tz>, $lt: <next UTC midnight in tz> }, status: 'ACTIVE' }
|
|
807
|
-
```
|
|
250
|
+
Rows are sorted by `key` then `key2` ascending. There's no default `limit` — pass one for large dimension combinations.
|
|
808
251
|
|
|
809
|
-
|
|
252
|
+
## Funnels & Cohorts
|
|
810
253
|
|
|
811
|
-
### `.
|
|
254
|
+
### `.funnel(steps)`
|
|
812
255
|
|
|
813
|
-
|
|
256
|
+
Counts how many base documents match each step's condition, independently, in parallel.
|
|
814
257
|
|
|
815
258
|
```ts
|
|
816
|
-
|
|
259
|
+
const result = await qa.funnel([
|
|
260
|
+
{ name: 'Visited', match: {} },
|
|
261
|
+
{ name: 'Signed up', match: { signedUpAt: { $ne: null } } },
|
|
262
|
+
{ name: 'Purchased', match: { firstOrderAt: { $ne: null } } },
|
|
263
|
+
]);
|
|
817
264
|
```
|
|
818
265
|
|
|
819
|
-
---
|
|
820
|
-
|
|
821
|
-
### `.range(field: string, preset: RangePreset)`
|
|
822
|
-
|
|
823
|
-
Adds a hard, server-defined UTC date range on `field`, computed in this instance's timezone. Not client-overridable (goes into `_serverConditions`, same as `.where()`).
|
|
824
|
-
|
|
825
|
-
**Presets:** `'today'`, `'yesterday'`, `'last7Days'`, `'last30Days'`, `'thisWeek'`, `'thisMonth'`
|
|
826
|
-
|
|
827
266
|
```ts
|
|
828
|
-
|
|
267
|
+
interface FunnelResult {
|
|
268
|
+
name: string;
|
|
269
|
+
count: number;
|
|
270
|
+
conversionFromPrevious: number | null; // %
|
|
271
|
+
conversionFromStart: number | null; // %
|
|
272
|
+
}
|
|
829
273
|
```
|
|
830
274
|
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
---
|
|
834
|
-
|
|
835
|
-
## Custom Range Methods
|
|
275
|
+
Each step's `match` is ANDed with the instance's base filter — steps are **independent counts**, not automatically cumulative. If step 3 should imply step 2, include that condition in step 3's `match` yourself. `conversionFromPrevious`/`conversionFromStart` are `null` for the first step, and `null` (instead of `Infinity`/`NaN`) whenever the denominator is 0.
|
|
836
276
|
|
|
837
|
-
|
|
277
|
+
### `.cohortRetention(opts)`
|
|
838
278
|
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
### `.rangeCustomDay(field: string, date: string)`
|
|
842
|
-
|
|
843
|
-
A single arbitrary local calendar date (`YYYY-MM-DD`) — for "show me everything from this specific day" rather than a relative preset.
|
|
279
|
+
Buckets entities into cohorts by the first occurrence of `cohortDateField`, then measures how many of each cohort had activity (`activityDateField`) in each subsequent period.
|
|
844
280
|
|
|
845
281
|
```ts
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
```ts
|
|
854
|
-
.rangeBetween('createdAt', { from: '2026-01-01', to: '2026-01-31' })
|
|
855
|
-
```
|
|
856
|
-
|
|
857
|
-
### `.rangeLastNDays(field: string, days: number)`
|
|
858
|
-
|
|
859
|
-
A rolling window of the last N whole calendar days, inclusive of today — a parametrized version of the built-in `last7Days`/`last30Days` presets.
|
|
282
|
+
interface CohortRetentionOptions {
|
|
283
|
+
cohortDateField: string; // e.g. signup date
|
|
284
|
+
activityDateField: string; // e.g. any return-visit date (can equal cohortDateField)
|
|
285
|
+
idField: string; // e.g. userId
|
|
286
|
+
cohortInterval: 'hour' | 'day' | 'week' | 'month';
|
|
287
|
+
periods: number; // how many periods forward to measure
|
|
288
|
+
}
|
|
860
289
|
|
|
861
|
-
|
|
862
|
-
|
|
290
|
+
const table = await qa.cohortRetention({
|
|
291
|
+
cohortDateField: 'signupAt',
|
|
292
|
+
activityDateField: 'lastActiveAt',
|
|
293
|
+
idField: 'userId',
|
|
294
|
+
cohortInterval: 'week',
|
|
295
|
+
periods: 8,
|
|
296
|
+
});
|
|
863
297
|
```
|
|
864
298
|
|
|
865
|
-
### `.rangeLastNHours(field: string, hours: number)`
|
|
866
|
-
|
|
867
|
-
A rolling window of the last N hours, ending at the exact moment the query runs. Unlike the day-based methods, this uses raw UTC instants with no calendar-day snapping — ideal for "recent activity" widgets.
|
|
868
|
-
|
|
869
299
|
```ts
|
|
870
|
-
|
|
300
|
+
interface CohortRow {
|
|
301
|
+
cohort: string; // ISO bucket start
|
|
302
|
+
cohortSize: number;
|
|
303
|
+
retention: (number | null)[]; // index 0 = period 0
|
|
304
|
+
retentionPct: (number | null)[];
|
|
305
|
+
}
|
|
871
306
|
```
|
|
872
307
|
|
|
873
|
-
|
|
308
|
+
Two aggregate calls run first (cohort assignment, then distinct activity buckets), and the retention matrix itself is assembled in JS afterward. Notes:
|
|
874
309
|
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
```ts
|
|
878
|
-
.rangeHours('createdAt', { date: '2026-03-14', fromHour: 9, toHour: 17 })
|
|
879
|
-
// toHour is exclusive; pass 24 for "through end of day"
|
|
880
|
-
```
|
|
310
|
+
- `retention[0]` (period 0) falls back to the full `cohortSize` when there's no explicit activity row recorded at offset 0 — useful when the cohort event and the first activity event are the same document, but worth checking if your two date fields can genuinely diverge at period 0.
|
|
311
|
+
- For `cohortInterval: 'month'`, offsets are computed against an approximate 30-day month for period-bucketing math; the cohort buckets themselves are exact (via `$dateTrunc`), only the offset-from-cohort calculation is approximate.
|
|
881
312
|
|
|
882
|
-
### `.
|
|
313
|
+
### `.sessionize(opts)`
|
|
883
314
|
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
- `"YYYY-MM-DD"` → local midnight in this instance's timezone
|
|
887
|
-
- `"YYYY-MM-DDTHH:mm:ss[.sss]"` → local wall-clock time in this instance's timezone
|
|
888
|
-
- an offset-bearing ISO string (`...Z`, `...+06:00`) → treated as an absolute instant
|
|
315
|
+
Groups per-user events into sessions using native `$setWindowFields` + `$shift` gap detection — no self-lookup or JS grouping pass.
|
|
889
316
|
|
|
890
317
|
```ts
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
318
|
+
interface SessionizeOptions {
|
|
319
|
+
userField: string;
|
|
320
|
+
dateField: string;
|
|
321
|
+
gapMinutes: number; // idle gap after which a new session starts
|
|
322
|
+
}
|
|
895
323
|
|
|
896
|
-
|
|
897
|
-
|
|
324
|
+
const sessions = await qa.sessionize({
|
|
325
|
+
userField: 'userId',
|
|
326
|
+
dateField: 'eventAt',
|
|
327
|
+
gapMinutes: 30,
|
|
328
|
+
});
|
|
898
329
|
```
|
|
899
330
|
|
|
900
|
-
---
|
|
901
|
-
|
|
902
|
-
### `.excludeSoftDeleted(field = 'deletedAt')`
|
|
903
|
-
|
|
904
|
-
Convenience server-side condition excluding soft-deleted documents. Matches both `null` and a genuinely missing field, per MongoDB's equality semantics. Not client-overridable.
|
|
905
|
-
|
|
906
331
|
```ts
|
|
907
|
-
|
|
908
|
-
|
|
332
|
+
interface SessionSummary {
|
|
333
|
+
userId: unknown;
|
|
334
|
+
sessionStart: string;
|
|
335
|
+
sessionEnd: string;
|
|
336
|
+
eventCount: number;
|
|
337
|
+
durationSeconds: number;
|
|
338
|
+
}
|
|
909
339
|
```
|
|
910
340
|
|
|
911
|
-
|
|
341
|
+
## Statistics
|
|
912
342
|
|
|
913
|
-
### `.
|
|
343
|
+
### `.percentiles(field, ps)`
|
|
914
344
|
|
|
915
|
-
|
|
345
|
+
Percentiles (0–100) of `field` over the current filter, via native `$percentile` (`method: 'approximate'`).
|
|
916
346
|
|
|
917
347
|
```ts
|
|
918
|
-
.
|
|
919
|
-
|
|
348
|
+
await qa.percentiles('total', [50, 90, 99]);
|
|
349
|
+
// { p50: 42, p90: 118, p99: 340 }
|
|
920
350
|
```
|
|
921
351
|
|
|
922
|
-
|
|
352
|
+
Values are `null` when there's no matching data.
|
|
923
353
|
|
|
924
|
-
### `.
|
|
354
|
+
### `.stdDevOutliers(field, opts)`
|
|
925
355
|
|
|
926
|
-
|
|
356
|
+
Flags documents whose `field` value is more than `threshold` standard deviations from the mean, using native `$stdDevPop`.
|
|
927
357
|
|
|
928
358
|
```ts
|
|
929
|
-
.
|
|
359
|
+
await qa.stdDevOutliers('total', { threshold: 3, limit: 50 }); // defaults shown
|
|
930
360
|
```
|
|
931
361
|
|
|
932
|
-
---
|
|
933
|
-
|
|
934
|
-
### `.sort()`
|
|
935
|
-
|
|
936
|
-
Parses `?sort=` (e.g. `-createdAt,name`), capped at 5 fields, dropping any field not in the allowlist. Falls back to `{ createdAt: -1 }` when absent.
|
|
937
|
-
|
|
938
362
|
```ts
|
|
939
|
-
|
|
363
|
+
interface OutlierRow {
|
|
364
|
+
_id: unknown;
|
|
365
|
+
value: number;
|
|
366
|
+
zScore: number;
|
|
367
|
+
[key: string]: unknown; // full source document is spread in
|
|
368
|
+
}
|
|
940
369
|
```
|
|
941
370
|
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
---
|
|
371
|
+
Two round trips: one to compute `mean`/`stdDev` over the full filtered set, one to fetch flagged rows. Returns `[]` if there's no data or the standard deviation is 0 (constant field).
|
|
945
372
|
|
|
946
|
-
|
|
373
|
+
> **Caveat:** rows are sorted by `zScore` descending before `limit` is applied, so with a tight `limit` on a field that has outliers on both tails, strongly _positive_ outliers can crowd out strongly _negative_ ones. Raise `limit` (or drop the `$limit` and sort by `Math.abs(zScore)` yourself) if you need both tails represented fairly.
|
|
947
374
|
|
|
948
|
-
|
|
375
|
+
### `.metrics(specs)`
|
|
949
376
|
|
|
950
|
-
|
|
951
|
-
- If **every** requested field is blocked, falls back to `defaultProjection` rather than silently returning everything.
|
|
952
|
-
- `_id` and `__v` are always allowed through even if not in `allowFields()`.
|
|
377
|
+
Several independent `StatSpec` metrics in one round trip — cheaper than N separate calls for a KPI-strip widget.
|
|
953
378
|
|
|
954
379
|
```ts
|
|
955
|
-
.
|
|
380
|
+
await qa.metrics([
|
|
381
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
382
|
+
{ name: 'avgOrder', op: 'avg', field: 'total' },
|
|
383
|
+
{ name: 'orders', op: 'count' },
|
|
384
|
+
]);
|
|
385
|
+
// { revenue: 48213, avgOrder: 62.1, orders: 776 }
|
|
956
386
|
```
|
|
957
387
|
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
---
|
|
388
|
+
## Post-Processing Helpers (static)
|
|
961
389
|
|
|
962
|
-
|
|
390
|
+
These run entirely in JS against a series you've already fetched — no database call.
|
|
963
391
|
|
|
964
|
-
|
|
392
|
+
### `QueryAnalytics.movingAverage()`
|
|
965
393
|
|
|
966
|
-
|
|
967
|
-
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
968
|
-
| `from` | `string` | Collection name (not the model name) to join against. |
|
|
969
|
-
| `as` | `string` | Output array field name. |
|
|
970
|
-
| `localField` | `string?` | Local join field. |
|
|
971
|
-
| `foreignField` | `string?` | Foreign join field. |
|
|
972
|
-
| `pipeline` | `PipelineStage[]?` | Sub-pipeline form of `$lookup`, for complex/correlated joins. Cannot contain `$out`/`$merge`. |
|
|
973
|
-
| `single` | `boolean?` | When `true`, `$unwind`s the joined array (`preserveNullAndEmptyArrays: true`) so `as` becomes a single object instead of an array. |
|
|
394
|
+
Adds a trailing moving-average field to an existing time series.
|
|
974
395
|
|
|
975
396
|
```ts
|
|
976
|
-
.
|
|
977
|
-
from: 'branches',
|
|
978
|
-
as: 'branch',
|
|
979
|
-
localField: 'branchId',
|
|
980
|
-
foreignField: '_id',
|
|
981
|
-
single: true,
|
|
982
|
-
})
|
|
397
|
+
QueryAnalytics.movingAverage(series, 'revenue', 7); // adds `revenue_ma`
|
|
983
398
|
```
|
|
984
399
|
|
|
985
|
-
|
|
400
|
+
The window shrinks near the start of the series rather than looking backward past index 0 (so the first point's average is just itself, the second is the average of the first two, and so on). Throws `QueryAnalyticsError` if `windowSize < 1`.
|
|
986
401
|
|
|
987
|
-
###
|
|
402
|
+
### `QueryAnalytics.trend()`
|
|
988
403
|
|
|
989
|
-
|
|
404
|
+
Simple up/down/flat classification, comparing the average of the last `n` points to the `n` before that.
|
|
990
405
|
|
|
991
406
|
```ts
|
|
992
|
-
.
|
|
993
|
-
//
|
|
407
|
+
QueryAnalytics.trend(series, 'revenue', 3, 2); // n=3, flatThresholdPct=2 (defaults)
|
|
408
|
+
// 'up' | 'down' | 'flat' | 'insufficient_data'
|
|
994
409
|
```
|
|
995
410
|
|
|
996
|
-
|
|
411
|
+
Returns `'insufficient_data'` when the series has fewer than `2 * n` points.
|
|
997
412
|
|
|
998
|
-
###
|
|
413
|
+
### `QueryAnalytics.forecast()`
|
|
999
414
|
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
- Blocks **only** `$out` / `$merge` (destructive stages).
|
|
1003
|
-
- **Does not** run the client-input sanitizer/allowlist/operator-rejection — that only applies to `.filter()`/`.where()`, which parse untrusted `req.query`/`req.body` values.
|
|
1004
|
-
- **Never pass raw client input directly into `.addStage()`.** It's for stages _you_ author server-side. If you need a client-supplied value inside a custom stage, validate/whitelist it yourself first.
|
|
415
|
+
A simple linear-regression projection for `periodsAhead` future buckets, based on the series' existing trend line.
|
|
1005
416
|
|
|
1006
417
|
```ts
|
|
1007
|
-
.
|
|
1008
|
-
|
|
1009
|
-
_id: '$status',
|
|
1010
|
-
count: { $sum: 1 },
|
|
1011
|
-
totalAmount: { $sum: '$amount' },
|
|
1012
|
-
},
|
|
1013
|
-
})
|
|
418
|
+
QueryAnalytics.forecast(series, 'revenue', 7);
|
|
419
|
+
// [{ index: 30, predicted: 512.4 }, { index: 31, predicted: 518.9 }, ...]
|
|
1014
420
|
```
|
|
1015
421
|
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
### `.paginate(cachedTotal?: number)`
|
|
422
|
+
Good enough for a dashed projection line on a chart — not a substitute for a real forecasting model. Returns `[]` for series shorter than 2 points.
|
|
1019
423
|
|
|
1020
|
-
|
|
424
|
+
## `.heatmap(dateField, valueField?)`
|
|
1021
425
|
|
|
1022
|
-
|
|
1023
|
-
- Pass a prior page-1 `total` as `cachedTotal` on later pages to **skip the count stage entirely**.
|
|
1024
|
-
- `maxTimeMS` / `allowDiskUse` from constructor options are applied to the aggregation.
|
|
1025
|
-
- If the requested `page` exceeds `totalPages`, page `1` is returned automatically (with the real `total`/`totalPages` still reported).
|
|
1026
|
-
- `onSlowQuery` (if configured) fires with `{ elapsedMs, pipeline, sort, page, limit }` when the query exceeds `slowQueryThresholdMS`.
|
|
1027
|
-
|
|
1028
|
-
> **Note:** `$facet` buffers both branches in memory per query. For very large collections with expensive pre-facet stages (heavy `$lookup`/`$group` before pagination), pass `cachedTotal` on subsequent pages, use `.paginateCursor()` instead, or run `.count()`/data as two separate calls.
|
|
426
|
+
Counts (or sums `valueField`, if given) by weekday (0=Sun..6=Sat, local timezone) × hour-of-day (0–23, local timezone).
|
|
1029
427
|
|
|
1030
428
|
```ts
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
```
|
|
1034
|
-
|
|
1035
|
-
---
|
|
429
|
+
await qa.heatmap('createdAt');
|
|
430
|
+
// [{ weekday: 0, hour: 0, value: 4 }, { weekday: 0, hour: 1, value: 1 }, ...]
|
|
1036
431
|
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
Keyset ("seek") pagination — scales far better than `.paginate()`'s `$skip` on deep pages of large collections, at the cost of not supporting "jump to page N". Seeks on whatever field `.sort()` resolved to (falls back to `createdAt` if `.sort()` wasn't called), using `_id` as a stable tiebreaker.
|
|
1040
|
-
|
|
1041
|
-
```ts
|
|
1042
|
-
interface CursorPaginateOptions {
|
|
1043
|
-
cursor?: string; // opaque cursor from a previous page's nextCursor
|
|
1044
|
-
limit?: number; // overrides ?limit=, still capped by maxLimit
|
|
1045
|
-
}
|
|
1046
|
-
|
|
1047
|
-
interface CursorPaginatedResult<T> {
|
|
1048
|
-
data: T[];
|
|
1049
|
-
limit: number;
|
|
1050
|
-
nextCursor: string | null; // pass this back in as `cursor` for the next page
|
|
1051
|
-
hasNextPage: boolean;
|
|
1052
|
-
}
|
|
432
|
+
await qa.heatmap('createdAt', 'total'); // sum revenue instead of counting docs
|
|
1053
433
|
```
|
|
1054
434
|
|
|
1055
|
-
|
|
1056
|
-
const p1 = await builder.sort().paginateCursor({ limit: 20 });
|
|
1057
|
-
const p2 = await builder.paginateCursor({ cursor: p1.nextCursor!, limit: 20 });
|
|
1058
|
-
// hasNextPage: false / nextCursor: null means you've reached the end
|
|
1059
|
-
```
|
|
1060
|
-
|
|
1061
|
-
Great fit for infinite-scroll feeds and large-export pagination; not a drop-in replacement where the UI needs page numbers.
|
|
435
|
+
Returns a flat array (one row per `weekday`/`hour` combination that occurred), not a pre-filled 7×24 matrix — fill in the zero cells client-side if your chart needs a dense grid.
|
|
1062
436
|
|
|
1063
|
-
|
|
437
|
+
## Live Updates
|
|
1064
438
|
|
|
1065
|
-
### `.
|
|
439
|
+
### `.watch(onChange, opts)`
|
|
1066
440
|
|
|
1067
|
-
|
|
441
|
+
Subscribes to a MongoDB change stream on the model's collection and invokes `onChange` for every matching insert/update/delete/replace — handy for pushing live dashboard updates over a websocket instead of polling.
|
|
1068
442
|
|
|
1069
443
|
```ts
|
|
1070
|
-
const
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
### `.distinct(field: string)`
|
|
444
|
+
const stream = qa.watch(
|
|
445
|
+
(change) => io.emit('order:change', change),
|
|
446
|
+
{ operationTypes: ['insert', 'update'] }, // optional; all types by default
|
|
447
|
+
);
|
|
1076
448
|
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
```ts
|
|
1080
|
-
const statuses = await builder.distinct('status');
|
|
1081
|
-
// e.g. ['PENDING', 'PAID', 'CANCELLED']
|
|
449
|
+
// later
|
|
450
|
+
stream.close();
|
|
1082
451
|
```
|
|
1083
452
|
|
|
1084
|
-
|
|
453
|
+
Returns the underlying `ChangeStream` — the caller owns its lifecycle and must `.close()` it. `fullDocument: 'updateLookup'` is set so update events include the full document.
|
|
1085
454
|
|
|
1086
|
-
|
|
455
|
+
Two things worth knowing:
|
|
1087
456
|
|
|
1088
|
-
|
|
457
|
+
- Only conditions set via `.match()`/`.dateRange()` are translated onto the stream (as `fullDocument.<field>` equality conditions) — stages added via `.addStage()` aren't part of the change-stream pipeline.
|
|
458
|
+
- Change streams require a MongoDB replica set or Atlas cluster; they don't work against a standalone `mongod`.
|
|
1089
459
|
|
|
1090
|
-
|
|
1091
|
-
interface StatSpec {
|
|
1092
|
-
name: string;
|
|
1093
|
-
op: 'sum' | 'avg' | 'min' | 'max' | 'count';
|
|
1094
|
-
field?: string; // required for every op except 'count'
|
|
1095
|
-
}
|
|
1096
|
-
```
|
|
460
|
+
## Export & Batch Helpers (static)
|
|
1097
461
|
|
|
1098
|
-
|
|
1099
|
-
const totals = await builder.stats([
|
|
1100
|
-
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
1101
|
-
{ name: 'avgOrder', op: 'avg', field: 'total' },
|
|
1102
|
-
{ name: 'orders', op: 'count' },
|
|
1103
|
-
]);
|
|
1104
|
-
// { revenue: 48213, avgOrder: 62.1, orders: 776 }
|
|
1105
|
-
```
|
|
1106
|
-
|
|
1107
|
-
---
|
|
462
|
+
### `QueryAnalytics.toCSV()` / `toNDJSON()`
|
|
1108
463
|
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
Returns a Mongoose `AggregationCursor` — async-iterable, no buffering of the full result set in memory. Use for large exports (CSV generation, bulk processing).
|
|
464
|
+
Flatten an array of plain-object rows (e.g. the output of `timeSeries()`/`breakdown()`) into CSV or newline-delimited JSON.
|
|
1112
465
|
|
|
1113
466
|
```ts
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
}
|
|
467
|
+
QueryAnalytics.toCSV(rows); // header row inferred from the union of all row keys; values with , " or \n are quoted
|
|
468
|
+
QueryAnalytics.toNDJSON(rows); // one JSON.stringify(row) per line — friendlier for streaming large exports
|
|
1117
469
|
```
|
|
1118
470
|
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
---
|
|
471
|
+
### `QueryAnalytics.dashboard()`
|
|
1122
472
|
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
Runs the built pipeline through Mongoose's `.explain()` — for debugging slow queries and verifying index usage. `verbosity` is `'queryPlanner'` (default), `'executionStats'`, or `'allPlansExecution'`.
|
|
473
|
+
Runs several named analytics calls in parallel and returns them keyed by name — one round trip from the caller's perspective (though each named task is still its own aggregate call under the hood).
|
|
1126
474
|
|
|
1127
475
|
```ts
|
|
1128
|
-
const
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
const base = builder.filter().sort().project('name total createdAt');
|
|
1141
|
-
|
|
1142
|
-
const [page, totals] = await Promise.all([
|
|
1143
|
-
base.clone().paginate(),
|
|
1144
|
-
base.clone().stats([{ name: 'revenue', op: 'sum', field: 'total' }]),
|
|
1145
|
-
]);
|
|
476
|
+
const data = await QueryAnalytics.dashboard({
|
|
477
|
+
revenue: () =>
|
|
478
|
+
qa.timeSeries({
|
|
479
|
+
dateField: 'createdAt',
|
|
480
|
+
interval: 'day',
|
|
481
|
+
metrics: [{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
482
|
+
}),
|
|
483
|
+
topCategories: () =>
|
|
484
|
+
qa.breakdown('category', [{ name: 'revenue', op: 'sum', field: 'total' }]),
|
|
485
|
+
totals: () => qa.metrics([{ name: 'orders', op: 'count' }]),
|
|
486
|
+
});
|
|
487
|
+
// { revenue: [...], topCategories: [...], totals: { orders: 776 } }
|
|
1146
488
|
```
|
|
1147
489
|
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
### `.debugPipeline()`
|
|
490
|
+
### `QueryAnalytics.clearCache()`
|
|
1151
491
|
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
```ts
|
|
1155
|
-
console.log(builder.debugPipeline());
|
|
1156
|
-
```
|
|
492
|
+
Clears the shared in-memory cache. **Process-wide** — not scoped to one instance or one model. (See the caching note under [Constructor & Options](#constructor--options-2): as of this release, nothing populates the cache yet via the public API.)
|
|
1157
493
|
|
|
1158
494
|
## Recipes
|
|
1159
495
|
|
|
1160
|
-
**
|
|
496
|
+
**Branch dashboard in one round trip:**
|
|
1161
497
|
|
|
1162
498
|
```ts
|
|
1163
|
-
const
|
|
1164
|
-
.
|
|
1165
|
-
.
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
as: 'customer',
|
|
1170
|
-
localField: 'customerId',
|
|
1171
|
-
foreignField: '_id',
|
|
1172
|
-
single: true,
|
|
1173
|
-
})
|
|
1174
|
-
.addStage({ $match: { 'customer.vip': true } }) // server-defined, not client-controlled
|
|
1175
|
-
.addStage({
|
|
1176
|
-
$group: {
|
|
1177
|
-
_id: '$customer._id',
|
|
1178
|
-
customerName: { $first: '$customer.name' },
|
|
1179
|
-
orderCount: { $sum: 1 },
|
|
1180
|
-
},
|
|
1181
|
-
})
|
|
1182
|
-
.sort()
|
|
1183
|
-
.paginate();
|
|
1184
|
-
```
|
|
1185
|
-
|
|
1186
|
-
**Relative date range preset (server-enforced, not client-overridable):**
|
|
1187
|
-
|
|
1188
|
-
```ts
|
|
1189
|
-
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1190
|
-
.allowFields(['status'])
|
|
1191
|
-
.where({ branchId: req.self.linkedTo })
|
|
1192
|
-
.range('createdAt', 'last30Days')
|
|
1193
|
-
.filter()
|
|
1194
|
-
.sort()
|
|
1195
|
-
.paginate();
|
|
1196
|
-
```
|
|
1197
|
-
|
|
1198
|
-
**Custom hour-of-day window (business hours report):**
|
|
1199
|
-
|
|
1200
|
-
```ts
|
|
1201
|
-
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1202
|
-
.allowFields(['status'])
|
|
1203
|
-
.where({ branchId: req.self.linkedTo })
|
|
1204
|
-
.rangeHours('createdAt', {
|
|
1205
|
-
date: req.query.day as string,
|
|
1206
|
-
fromHour: 9,
|
|
1207
|
-
toHour: 21,
|
|
1208
|
-
})
|
|
1209
|
-
.filter()
|
|
1210
|
-
.sort()
|
|
1211
|
-
.paginate();
|
|
1212
|
-
```
|
|
1213
|
-
|
|
1214
|
-
**Dashboard: page + totals in parallel, off one shared base:**
|
|
1215
|
-
|
|
1216
|
-
```ts
|
|
1217
|
-
const base = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1218
|
-
.allowFields(['status', 'branchId', 'createdAt', 'total'])
|
|
1219
|
-
.dateFields(['createdAt'])
|
|
1220
|
-
.where({ branchId: req.self.linkedTo })
|
|
1221
|
-
.excludeSoftDeleted()
|
|
1222
|
-
.filter()
|
|
1223
|
-
.sort()
|
|
1224
|
-
.project('status createdAt total');
|
|
1225
|
-
|
|
1226
|
-
const [page, totals] = await Promise.all([
|
|
1227
|
-
base.clone().paginate(),
|
|
1228
|
-
base.clone().stats([
|
|
1229
|
-
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
1230
|
-
{ name: 'orders', op: 'count' },
|
|
1231
|
-
]),
|
|
1232
|
-
]);
|
|
1233
|
-
```
|
|
1234
|
-
|
|
1235
|
-
**Infinite scroll with keyset pagination:**
|
|
499
|
+
const qa = new QueryAnalytics(OrderModel, { timezone })
|
|
500
|
+
.match({ branchId: req.self.linkedTo, status: { $ne: 'CANCELLED' } })
|
|
501
|
+
.dateRange('createdAt', {
|
|
502
|
+
from: req.query.from as string,
|
|
503
|
+
to: req.query.to as string,
|
|
504
|
+
});
|
|
1236
505
|
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
506
|
+
const dashboard = await QueryAnalytics.dashboard({
|
|
507
|
+
series: () =>
|
|
508
|
+
qa.timeSeries({
|
|
509
|
+
dateField: 'createdAt',
|
|
510
|
+
interval: 'day',
|
|
511
|
+
metrics: [
|
|
512
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
513
|
+
{ name: 'orders', op: 'count' },
|
|
514
|
+
],
|
|
515
|
+
}),
|
|
516
|
+
topProducts: () =>
|
|
517
|
+
qa.breakdown(
|
|
518
|
+
'productId',
|
|
519
|
+
[{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
520
|
+
{ limit: 5 },
|
|
521
|
+
),
|
|
522
|
+
kpis: () =>
|
|
523
|
+
qa.metrics([
|
|
524
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
525
|
+
{ name: 'orders', op: 'count' },
|
|
526
|
+
]),
|
|
1247
527
|
});
|
|
1248
|
-
```
|
|
1249
|
-
|
|
1250
|
-
**Streaming a large CSV export:**
|
|
1251
528
|
|
|
1252
|
-
|
|
1253
|
-
const builder = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1254
|
-
.allowFields(['status', 'createdAt'])
|
|
1255
|
-
.where({ branchId: req.self.linkedTo })
|
|
1256
|
-
.range('createdAt', 'thisMonth')
|
|
1257
|
-
.filter()
|
|
1258
|
-
.project('status createdAt total');
|
|
1259
|
-
|
|
1260
|
-
res.setHeader('Content-Type', 'text/csv');
|
|
1261
|
-
for await (const row of builder.stream()) {
|
|
1262
|
-
res.write(`${row.status},${row.createdAt.toISOString()},${row.total}\n`);
|
|
1263
|
-
}
|
|
1264
|
-
res.end();
|
|
529
|
+
res.json(dashboard);
|
|
1265
530
|
```
|
|
1266
531
|
|
|
1267
|
-
**
|
|
1268
|
-
|
|
1269
|
-
```
|
|
1270
|
-
GET /orders?branchId=64f1a2b3c4d5e6f7a8b9c0d1&categoryId=64f1a2b3c4d5e6f7a8b9c0d2
|
|
1271
|
-
```
|
|
532
|
+
**Week-over-week KPI strip:**
|
|
1272
533
|
|
|
1273
534
|
```ts
|
|
1274
|
-
const
|
|
1275
|
-
.
|
|
1276
|
-
.
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
```ts
|
|
1285
|
-
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1286
|
-
.allowFields(['status', 'branchId', 'createdAt'])
|
|
1287
|
-
.excludeSoftDeleted() // deletedAt: null, always applied
|
|
1288
|
-
.whereIf(req.self.role !== 'admin', { branchId: req.self.linkedTo }) // branch staff see only their branch
|
|
1289
|
-
.whereIf(req.query.vip === 'true', { tier: 'vip' })
|
|
1290
|
-
.filter()
|
|
1291
|
-
.sort()
|
|
1292
|
-
.paginate();
|
|
1293
|
-
```
|
|
1294
|
-
|
|
1295
|
-
**Populating a filter UI — distinct values + count, no data fetch:**
|
|
535
|
+
const wow = await new QueryAnalytics(OrderModel, { timezone })
|
|
536
|
+
.match({ branchId: req.self.linkedTo })
|
|
537
|
+
.compare({
|
|
538
|
+
dateField: 'createdAt',
|
|
539
|
+
preset: 'thisWeek',
|
|
540
|
+
metrics: [
|
|
541
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
542
|
+
{ name: 'orders', op: 'count' },
|
|
543
|
+
],
|
|
544
|
+
});
|
|
1296
545
|
|
|
1297
|
-
|
|
1298
|
-
const builder = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1299
|
-
.allowFields(['status', 'branchId'])
|
|
1300
|
-
.where({ branchId: req.self.linkedTo })
|
|
1301
|
-
.filter();
|
|
1302
|
-
|
|
1303
|
-
const [statuses, total] = await Promise.all([
|
|
1304
|
-
builder.clone().distinct('status'), // populate a <select> of possible statuses
|
|
1305
|
-
builder.clone().count(), // "X results" label
|
|
1306
|
-
]);
|
|
546
|
+
res.json(wow); // { current, previous, change, changePct }
|
|
1307
547
|
```
|
|
1308
548
|
|
|
1309
|
-
**
|
|
549
|
+
**Signup retention curve, branched off one base filter:**
|
|
1310
550
|
|
|
1311
551
|
```ts
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
.allowFields(['status', 'createdAt'])
|
|
1315
|
-
.where({ branchId: req.self.linkedTo })
|
|
1316
|
-
.range('createdAt', 'last7Days')
|
|
1317
|
-
.filter()
|
|
1318
|
-
.sort();
|
|
1319
|
-
|
|
1320
|
-
res.json({
|
|
1321
|
-
pipeline: builder.debugPipeline(),
|
|
1322
|
-
explain: await builder.explain('executionStats'),
|
|
1323
|
-
});
|
|
552
|
+
const base = new QueryAnalytics(UserModel, { timezone }).match({
|
|
553
|
+
orgId: req.user.orgId,
|
|
1324
554
|
});
|
|
1325
|
-
```
|
|
1326
|
-
|
|
1327
|
-
**Cursor pagination on a non-default sort field:**
|
|
1328
555
|
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipelines. For that case, drop to `.addStage()` directly:
|
|
1344
|
-
|
|
1345
|
-
```ts
|
|
1346
|
-
.addStage({
|
|
1347
|
-
$lookup: {
|
|
1348
|
-
from: 'orderItems',
|
|
1349
|
-
let: { orderId: '$_id' },
|
|
1350
|
-
pipeline: [
|
|
1351
|
-
{ $match: { $expr: { $eq: ['$orderId', '$$orderId'] } } },
|
|
1352
|
-
{ $project: { name: 1, qty: 1 } },
|
|
1353
|
-
],
|
|
1354
|
-
as: 'items',
|
|
1355
|
-
},
|
|
1356
|
-
})
|
|
556
|
+
const [retention, funnel] = await Promise.all([
|
|
557
|
+
base.clone().cohortRetention({
|
|
558
|
+
cohortDateField: 'signupAt',
|
|
559
|
+
activityDateField: 'lastActiveAt',
|
|
560
|
+
idField: '_id',
|
|
561
|
+
cohortInterval: 'week',
|
|
562
|
+
periods: 8,
|
|
563
|
+
}),
|
|
564
|
+
base.clone().funnel([
|
|
565
|
+
{ name: 'Signed up', match: {} },
|
|
566
|
+
{ name: 'Activated', match: { activatedAt: { $ne: null } } },
|
|
567
|
+
{ name: 'Subscribed', match: { subscribedAt: { $ne: null } } },
|
|
568
|
+
]),
|
|
569
|
+
]);
|
|
1357
570
|
```
|
|
1358
571
|
|
|
1359
|
-
**
|
|
572
|
+
**Anomalies widget with a projected trend line:**
|
|
1360
573
|
|
|
1361
574
|
```ts
|
|
1362
|
-
const
|
|
1363
|
-
|
|
1364
|
-
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1365
|
-
.allowFields(['branchId', 'status'])
|
|
1366
|
-
.where({ status: 'PAID' })
|
|
1367
|
-
.rangeLastNDays('createdAt', 30) // rolling 30-day window, client can't override
|
|
1368
|
-
.filter()
|
|
1369
|
-
.lookup({
|
|
1370
|
-
from: 'branches',
|
|
1371
|
-
as: 'branch',
|
|
1372
|
-
localField: 'branchId',
|
|
1373
|
-
foreignField: '_id',
|
|
1374
|
-
single: true,
|
|
1375
|
-
})
|
|
1376
|
-
.addStage({
|
|
1377
|
-
$group: {
|
|
1378
|
-
_id: '$branchId',
|
|
1379
|
-
branchName: { $first: '$branch.name' },
|
|
1380
|
-
revenue: { $sum: '$total' },
|
|
1381
|
-
orders: { $sum: 1 },
|
|
1382
|
-
avgOrderValue: { $avg: '$total' },
|
|
1383
|
-
},
|
|
1384
|
-
})
|
|
1385
|
-
.addStage({ $sort: { revenue: -1 } })
|
|
1386
|
-
.paginate();
|
|
1387
|
-
```
|
|
1388
|
-
|
|
1389
|
-
**Notification feed — lookup + unwind a single related document per row:**
|
|
575
|
+
const qa = new QueryAnalytics(OrderModel, { timezone }).match({ branchId });
|
|
1390
576
|
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
}
|
|
1395
|
-
|
|
1396
|
-
.dateFields(['createdAt'])
|
|
1397
|
-
.where({ userId: req.user.id })
|
|
1398
|
-
.filter()
|
|
1399
|
-
.lookup({
|
|
1400
|
-
from: 'users',
|
|
1401
|
-
as: 'actor',
|
|
1402
|
-
localField: 'actorId',
|
|
1403
|
-
foreignField: '_id',
|
|
1404
|
-
single: true, // unwinds so `actor` is a single object, not an array
|
|
1405
|
-
})
|
|
1406
|
-
.sort()
|
|
1407
|
-
.project('type read createdAt actor.name actor.avatar')
|
|
1408
|
-
.paginate();
|
|
1409
|
-
```
|
|
577
|
+
const series = await qa.timeSeries({
|
|
578
|
+
dateField: 'createdAt',
|
|
579
|
+
interval: 'day',
|
|
580
|
+
metrics: [{ name: 'revenue', op: 'sum', field: 'total' }],
|
|
581
|
+
});
|
|
1410
582
|
|
|
1411
|
-
|
|
583
|
+
const withMA = QueryAnalytics.movingAverage(series, 'revenue', 7);
|
|
584
|
+
const trend = QueryAnalytics.trend(series, 'revenue');
|
|
585
|
+
const projection = QueryAnalytics.forecast(series, 'revenue', 7);
|
|
586
|
+
const outliers = await qa.stdDevOutliers('total', { threshold: 3 });
|
|
1412
587
|
|
|
1413
|
-
|
|
1414
|
-
const result = await new QueryAggregate(AuditLogModel, req.query, { timezone })
|
|
1415
|
-
.allowFields(['action', 'actorId', 'createdAt'])
|
|
1416
|
-
.dateFields(['createdAt'])
|
|
1417
|
-
.where({ orgId: req.user.orgId })
|
|
1418
|
-
.rangeCustom('createdAt', {
|
|
1419
|
-
from: (req.query.from as string) ?? '2026-01-01T00:00:00',
|
|
1420
|
-
to: (req.query.to as string) ?? new Date().toISOString(),
|
|
1421
|
-
})
|
|
1422
|
-
.filter()
|
|
1423
|
-
.globalSearch(['action'])
|
|
1424
|
-
.sort()
|
|
1425
|
-
.project('action actorId createdAt')
|
|
1426
|
-
.paginate();
|
|
588
|
+
res.json({ series: withMA, trend, projection, outliers });
|
|
1427
589
|
```
|
|
1428
590
|
|
|
1429
|
-
**
|
|
591
|
+
**Live order feed alongside a polled summary:**
|
|
1430
592
|
|
|
1431
593
|
```ts
|
|
1432
|
-
const
|
|
1433
|
-
.allowFields(['branchId', 'category', 'stock', 'price'])
|
|
1434
|
-
.objectIdFields(['branchId'])
|
|
1435
|
-
.where({ deletedAt: null })
|
|
1436
|
-
.filter()
|
|
1437
|
-
.computeField('stockValue', { $multiply: ['$stock', '$price'] })
|
|
1438
|
-
.sort()
|
|
1439
|
-
.project('branchId category stock price stockValue');
|
|
1440
|
-
|
|
1441
|
-
const [page, totals] = await Promise.all([
|
|
1442
|
-
base.clone().paginate(),
|
|
1443
|
-
base.clone().stats([
|
|
1444
|
-
{ name: 'totalStockValue', op: 'sum', field: 'stockValue' },
|
|
1445
|
-
{ name: 'lowStockAvg', op: 'avg', field: 'stock' },
|
|
1446
|
-
{ name: 'skuCount', op: 'count' },
|
|
1447
|
-
]),
|
|
1448
|
-
]);
|
|
594
|
+
const qa = new QueryAnalytics(OrderModel, { timezone }).match({ branchId });
|
|
1449
595
|
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
596
|
+
const stream = qa.watch(
|
|
597
|
+
(change) => io.to(`branch:${branchId}`).emit('order:change', change),
|
|
598
|
+
{
|
|
599
|
+
operationTypes: ['insert'],
|
|
600
|
+
},
|
|
601
|
+
);
|
|
1456
602
|
|
|
603
|
+
req.on('close', () => stream.close());
|
|
1457
604
|
```
|
|
1458
|
-
$match (from .where() + .filter() + .range()/rangeXxx() + .globalSearch(), merged via $and)
|
|
1459
|
-
↓
|
|
1460
|
-
[.lookup() / .addStage() / .computeField() calls, in the order you called them]
|
|
1461
|
-
↓
|
|
1462
|
-
$project (from .project(), if set)
|
|
1463
|
-
↓
|
|
1464
|
-
$sort (from .sort())
|
|
1465
|
-
↓
|
|
1466
|
-
[terminal stage: $skip/$limit, $facet, keyset $match + $limit, or $count/$group — added internally by the method you call]
|
|
1467
|
-
```
|
|
1468
|
-
|
|
1469
|
-
Implications:
|
|
1470
|
-
|
|
1471
|
-
- Anything added via `.addStage()`/`.computeField()` runs **after** the base filter match and **before** projection/sort.
|
|
1472
|
-
- If you `$group`/reshape documents, do it before `.project()` — or skip `.project()` and use `.addStage({ $project: {...} })` for full control over the new shape.
|
|
1473
|
-
- If you add your own `$sort` via `.addStage()` _and_ also call `.sort()`, both stages are included (the builder's `.sort()` stage is always appended last in the base pipeline) — harmless but redundant. Prefer one or the other.
|
|
1474
|
-
- `.count()`, `.distinct()`, and `.stats()` intentionally skip `$project`/`$sort` — they only need `$match` + your `.lookup()`/`.addStage()` stages before their own terminal `$count`/`$group`.
|
|
1475
|
-
- `.paginateCursor()` builds its own `$match`/`$sort`/`$limit` tail (the keyset condition), separate from `.paginate()`'s `$facet` tail.
|
|
1476
605
|
|
|
1477
606
|
## Security
|
|
1478
607
|
|
|
1479
|
-
| Protection
|
|
1480
|
-
|
|
|
1481
|
-
| **
|
|
1482
|
-
| **
|
|
1483
|
-
| **
|
|
1484
|
-
| **
|
|
1485
|
-
| **
|
|
1486
|
-
| **
|
|
1487
|
-
| **
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
| **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query |
|
|
1491
|
-
| **Bad custom-range input** | `rangeCustomDay`/`rangeBetween`/`rangeLastNDays`/`rangeLastNHours`/`rangeHours`/`rangeCustom` all throw `QueryAggregateValidationError` on malformed dates, non-positive counts, or invalid hour bounds — never silently produce a wrong range |
|
|
1492
|
-
| **Server condition override** | `.where()` / `.range()` / every custom range method are merged last via `$and` — URL params can never override them |
|
|
1493
|
-
| **Tampered cursors** | `.paginateCursor()` cursors are opaque base64url-encoded JSON; a malformed cursor throws `QueryAggregateValidationError` rather than silently misbehaving |
|
|
1494
|
-
| **Untrusted `.addStage()` input** | Not sanitized/allowlisted by design — documented as a trusted, developer-authored-only escape hatch |
|
|
1495
|
-
|
|
1496
|
-
> **Important:** `.addStage()` and the `pipeline` option in `.lookup()` are for **server-defined stages only**. They skip the sanitizer/allowlist/operator-rejection that protects `.filter()`/`.where()`. Never interpolate raw `req.query`/`req.body` values into an `.addStage()` call without validating them yourself first.
|
|
608
|
+
| Protection | Detail |
|
|
609
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
610
|
+
| **No client-input path** | `QueryAnalytics` has no `.filter()`/`.allowFields()` — every condition comes from `.match()`, `.dateRange()`, or `.addStage()`, all developer-authored. Don't pass raw `req.query`/`req.body` into any of them without validating it yourself first. |
|
|
611
|
+
| **Destructive stages** | `$out`/`$merge` are rejected recursively, at any nesting depth, in `.addStage()`. |
|
|
612
|
+
| **Strict date parsing** | `.dateRange()` requires `YYYY-MM-DD` and throws `QueryAnalyticsError` on anything else — no silent misinterpretation of ambiguous date strings. |
|
|
613
|
+
| **Runaway queries** | `maxTimeMS` (default `8000`) is applied to every aggregation. |
|
|
614
|
+
| **Bad timezone input** | An invalid IANA timezone is validated once at construction and silently falls back to the default, rather than throwing mid-query. |
|
|
615
|
+
| **MongoDB version requirement** | `cumulativeSeries()`, `rankedBreakdown()`, `sessionize()`, `percentiles()`, and `stdDevOutliers()` require MongoDB 7.0+; there's no feature-detection or fallback, so calling them against an older server surfaces as a server-side aggregation error. |
|
|
616
|
+
| **Change-stream requirements** | `.watch()` requires a replica set or Atlas cluster and only forwards `.match()`/`.dateRange()` conditions onto the stream, not `.addStage()` stages. |
|
|
617
|
+
|
|
618
|
+
> **Important:** because there's no allowlist here, field names passed to `breakdown()`, `multiBreakdown()`, `heatmap()`, etc. should come from your own code or a whitelist you maintain — not directly from a query string — the same way you'd treat any other server-authored aggregation field.
|
|
1497
619
|
|
|
1498
620
|
## TypeScript Types
|
|
1499
621
|
|
|
1500
622
|
```ts
|
|
1501
623
|
import {
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
RangePreset,
|
|
1508
|
-
SlowQueryInfo,
|
|
1509
|
-
QueryParams,
|
|
1510
|
-
PaginatedResult,
|
|
1511
|
-
CustomDayInput,
|
|
1512
|
-
CustomDateRangeInput,
|
|
1513
|
-
CustomHourRangeInput,
|
|
1514
|
-
CustomDateTimeRangeInput,
|
|
1515
|
-
CursorPaginateOptions,
|
|
1516
|
-
CursorPaginatedResult,
|
|
624
|
+
QueryAnalytics,
|
|
625
|
+
QueryAnalyticsOptions,
|
|
626
|
+
QueryAnalyticsError,
|
|
627
|
+
Interval,
|
|
628
|
+
ComparePreset,
|
|
1517
629
|
StatSpec,
|
|
630
|
+
TimeSeriesPoint,
|
|
631
|
+
CompareResult,
|
|
632
|
+
BreakdownRow,
|
|
633
|
+
RankedBreakdownRow,
|
|
634
|
+
FunnelStep,
|
|
635
|
+
FunnelResult,
|
|
636
|
+
CohortRetentionOptions,
|
|
637
|
+
CohortRow,
|
|
638
|
+
SessionizeOptions,
|
|
639
|
+
SessionSummary,
|
|
640
|
+
OutlierRow,
|
|
1518
641
|
} from 'mongoose-query-find';
|
|
1519
642
|
```
|
|
1520
643
|
|
|
1521
644
|
```ts
|
|
1522
|
-
|
|
645
|
+
type Interval = 'hour' | 'day' | 'week' | 'month';
|
|
646
|
+
|
|
647
|
+
type ComparePreset =
|
|
648
|
+
| 'today'
|
|
649
|
+
| 'thisWeek'
|
|
650
|
+
| 'thisMonth'
|
|
651
|
+
| 'last7Days'
|
|
652
|
+
| 'last30Days';
|
|
653
|
+
|
|
654
|
+
interface StatSpec {
|
|
655
|
+
name: string;
|
|
656
|
+
op: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinctCount';
|
|
657
|
+
field?: string; // required for every op except 'count'
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
interface QueryAnalyticsOptions {
|
|
1523
661
|
timezone?: string;
|
|
1524
662
|
maxTimeMS?: number;
|
|
1525
|
-
slowQueryThresholdMS?: number;
|
|
1526
|
-
maxLimit?: number;
|
|
1527
663
|
allowDiskUse?: boolean;
|
|
1528
664
|
weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
|
|
1529
|
-
|
|
1530
|
-
onSanitizeDrop?: (path: string, value: unknown) => void;
|
|
665
|
+
cacheTTLMs?: number;
|
|
1531
666
|
}
|
|
1532
667
|
|
|
1533
|
-
interface
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
localField?: string;
|
|
1537
|
-
foreignField?: string;
|
|
1538
|
-
pipeline?: PipelineStage[];
|
|
1539
|
-
single?: boolean;
|
|
668
|
+
interface TimeSeriesPoint {
|
|
669
|
+
bucket: string; // ISO string, local-boundary-aligned
|
|
670
|
+
[metric: string]: number | string;
|
|
1540
671
|
}
|
|
1541
672
|
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
|
1547
|
-
| 'thisWeek'
|
|
1548
|
-
| 'thisMonth';
|
|
1549
|
-
|
|
1550
|
-
interface SlowQueryInfo {
|
|
1551
|
-
elapsedMs: number;
|
|
1552
|
-
pipeline: PipelineStage[];
|
|
1553
|
-
sort: Record<string, 1 | -1>;
|
|
1554
|
-
page: number;
|
|
1555
|
-
limit: number;
|
|
673
|
+
interface CompareResult {
|
|
674
|
+
current: Record<string, number>;
|
|
675
|
+
previous: Record<string, number>;
|
|
676
|
+
change: Record<string, number>;
|
|
677
|
+
changePct: Record<string, number | null>;
|
|
1556
678
|
}
|
|
1557
679
|
|
|
1558
|
-
|
|
680
|
+
interface BreakdownRow {
|
|
681
|
+
key: unknown;
|
|
682
|
+
[metric: string]: unknown;
|
|
683
|
+
}
|
|
1559
684
|
|
|
1560
|
-
|
|
685
|
+
interface RankedBreakdownRow extends BreakdownRow {
|
|
686
|
+
rank: number;
|
|
687
|
+
}
|
|
1561
688
|
|
|
1562
|
-
interface
|
|
1563
|
-
|
|
1564
|
-
|
|
689
|
+
interface FunnelStep {
|
|
690
|
+
name: string;
|
|
691
|
+
match: Record<string, unknown>;
|
|
1565
692
|
}
|
|
1566
693
|
|
|
1567
|
-
interface
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
694
|
+
interface FunnelResult {
|
|
695
|
+
name: string;
|
|
696
|
+
count: number;
|
|
697
|
+
conversionFromPrevious: number | null;
|
|
698
|
+
conversionFromStart: number | null;
|
|
1571
699
|
}
|
|
1572
700
|
|
|
1573
|
-
interface
|
|
1574
|
-
|
|
1575
|
-
|
|
701
|
+
interface CohortRetentionOptions {
|
|
702
|
+
cohortDateField: string;
|
|
703
|
+
activityDateField: string;
|
|
704
|
+
idField: string;
|
|
705
|
+
cohortInterval: Interval;
|
|
706
|
+
periods: number;
|
|
1576
707
|
}
|
|
1577
708
|
|
|
1578
|
-
|
|
709
|
+
interface CohortRow {
|
|
710
|
+
cohort: string;
|
|
711
|
+
cohortSize: number;
|
|
712
|
+
retention: (number | null)[];
|
|
713
|
+
retentionPct: (number | null)[];
|
|
714
|
+
}
|
|
1579
715
|
|
|
1580
|
-
interface
|
|
1581
|
-
|
|
1582
|
-
|
|
716
|
+
interface SessionizeOptions {
|
|
717
|
+
userField: string;
|
|
718
|
+
dateField: string;
|
|
719
|
+
gapMinutes: number;
|
|
1583
720
|
}
|
|
1584
721
|
|
|
1585
|
-
interface
|
|
1586
|
-
|
|
1587
|
-
|
|
1588
|
-
|
|
1589
|
-
|
|
722
|
+
interface SessionSummary {
|
|
723
|
+
userId: unknown;
|
|
724
|
+
sessionStart: string;
|
|
725
|
+
sessionEnd: string;
|
|
726
|
+
eventCount: number;
|
|
727
|
+
durationSeconds: number;
|
|
1590
728
|
}
|
|
1591
729
|
|
|
1592
|
-
interface
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
730
|
+
interface OutlierRow {
|
|
731
|
+
_id: unknown;
|
|
732
|
+
value: number;
|
|
733
|
+
zScore: number;
|
|
734
|
+
[key: string]: unknown;
|
|
1596
735
|
}
|
|
1597
736
|
```
|
|
1598
737
|
|
|
1599
|
-
---
|
|
1600
|
-
|
|
1601
738
|
## Links
|
|
1602
739
|
|
|
1603
740
|
- [npm](https://www.npmjs.com/package/mongoose-query-find)
|
|
1604
741
|
- [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
|
|
1605
742
|
- [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
|
|
1606
743
|
|
|
1607
|
-
---
|
|
1608
|
-
|
|
1609
744
|
## License
|
|
1610
745
|
|
|
1611
746
|
ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
|