mongoose-query-find 3.2.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![license](https://img.shields.io/npm/l/mongoose-query-find)](https://github.com/jsdev-robin/mongoose-query-find/blob/main/LICENSE)
5
5
  [![mongoose peer](https://img.shields.io/badge/mongoose-%5E8%20%7C%7C%20%5E9-brightgreen)](https://mongoosejs.com)
6
6
 
7
- Two fluent, chainable, allowlisted query builders for Mongoose — **`QueryFind`** for simple `Model.find()` queries, and **`QueryAggregate`** for anything that needs joins, grouping, timezone-aware date filtering, or advanced pagination. Both are driven directly from URL query parameters with zero boilerplate.
7
+ Three fluent, chainable, allowlisted query builders for Mongoose — **`QueryFind`** for simple `Model.find()` queries, **`QueryAggregate`** for anything that needs joins, grouping, timezone-aware date filtering, or advanced pagination, and **`QueryAnalytics`** for dashboards and reporting (time series, cohorts, funnels, sessionization, and more). All three are driven directly from URL query parameters with zero boilerplate.
8
8
 
9
9
  ---
10
10
 
@@ -27,6 +27,7 @@ Two fluent, chainable, allowlisted query builders for Mongoose — **`QueryFind`
27
27
  - [.paginate()](#paginate)
28
28
  - [Query Parameter Reference](#query-parameter-reference)
29
29
  - [Full Example (Express)](#full-example-express)
30
+ - [More Examples](#more-examples)
30
31
  - [TypeScript Types](#typescript-types)
31
32
  - [Security](#security)
32
33
  - [Links](#links)
@@ -76,6 +77,53 @@ Two fluent, chainable, allowlisted query builders for Mongoose — **`QueryFind`
76
77
  - [Pipeline Stage Ordering](#pipeline-stage-ordering)
77
78
  - [Security](#security-1)
78
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)
79
127
 
80
128
  ---
81
129
 
@@ -138,21 +186,21 @@ queryFind(query, queryString, options?);
138
186
  ```
139
187
 
140
188
  | Parameter | Type | Description |
141
- | ------------- | ------------------------------------ | ------------------------------------------------------ |
142
- | `query` | `Query<TRawDocType[], TRawDocType>` | A Mongoose query, e.g. `Model.find()` |
143
- | `queryString` | `QueryParams` | The parsed URL query object, e.g. `req.query` |
144
- | `options` | `QueryFindOptions` _(optional)_ | Configuration options (see [Options](#options) below) |
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) |
145
193
 
146
194
  ### Options
147
195
 
148
- | Option | Type | Default | Description |
149
- | ----------------------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------- |
150
- | `maxTimeMS` | `number` | `5000` | Max milliseconds MongoDB may spend on each query. Pass `0` to disable. |
151
- | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
152
- | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
153
- | `lean` | `boolean` | `true` | Whether `.find()` calls `.lean()` for faster plain-object reads. |
154
- | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
155
- | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a client-supplied value. |
196
+ | Option | Type | Default | Description |
197
+ | ---------------------- | ---------------------------------------- | ----------- | ---------------------------------------------------------------------- |
198
+ | `maxTimeMS` | `number` | `5000` | Max milliseconds MongoDB may spend on each query. Pass `0` to disable. |
199
+ | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
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. |
156
204
 
157
205
  ---
158
206
 
@@ -333,13 +381,13 @@ GET /users?page=2&limit=20
333
381
  ## Query Parameter Reference
334
382
 
335
383
  | Parameter | Example | Description |
336
- | ----------- | -------------------------- | -------------------------------------------------------- |
337
- | `page` | `?page=3` | Page number (default: `1`, min: `1`) |
338
- | `limit` | `?limit=25` | Documents per page (default: `10`, max: `100`) |
339
- | `sort` | `?sort=-createdAt,name` | Sort fields; prefix `-` for descending (max: 5 fields) |
340
- | `fields` | `?fields=name,email` | Comma-separated fields to include in the response |
341
- | `q` | `?q=john` | Global search term (max: 200 chars) |
342
- | _(any key)_ | `?role=admin&age[gte]=18` | Field-level filters processed by `.filter()` |
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()` |
343
391
 
344
392
  ---
345
393
 
@@ -389,6 +437,108 @@ GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5
389
437
 
390
438
  ---
391
439
 
440
+ ## More Examples
441
+
442
+ **E-commerce product listing — nested price filters + category populate:**
443
+
444
+ ```ts
445
+ export const getProducts = async (req: Request, res: Response) => {
446
+ const result = await queryFind(ProductModel.find(), req.query)
447
+ .allowFields(['name', 'price', 'category', 'inStock', 'brand', 'createdAt'])
448
+ .where({ deletedAt: null, published: true })
449
+ .filter()
450
+ .globalSearch(['name', 'brand'])
451
+ .sort()
452
+ .limitFields('name price inStock brand')
453
+ .populate('category', 'name slug')
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
+ };
489
+ ```
490
+
491
+ ```bash
492
+ # Published OR featured posts, using the safe top-level $or
493
+ GET /posts?$or[0][status]=published&$or[1][featured]=true
494
+
495
+ # Posts tagged "typescript" published this year
496
+ GET /posts?tags=typescript&publishedAt[gte]=2026-01-01
497
+ ```
498
+
499
+ **Admin panel — strict field allowlist, sensitive fields never leak:**
500
+
501
+ ```ts
502
+ export const adminListUsers = async (req: Request, res: Response) => {
503
+ const result = await queryFind(UserModel.find(), req.query, { maxLimit: 250 })
504
+ .allowFields(['name', 'email', 'role', 'isActive', 'lastLoginAt'])
505
+ .where({ orgId: req.user.orgId })
506
+ .filter()
507
+ .sort()
508
+ .limitFields('-password -passwordResetToken -__v') // client's ?fields= can never override this
509
+ .paginate();
510
+
511
+ res.json(result);
512
+ };
513
+ ```
514
+
515
+ ```bash
516
+ # Even if a client tries ?fields=password, it's stripped — not in allowFields()
517
+ GET /admin/users?fields=password,email&role=admin
518
+ ```
519
+
520
+ **Cached count pattern — skip re-counting on subsequent pages:**
521
+
522
+ ```ts
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
+ ```
539
+
540
+ ---
541
+
392
542
  ## TypeScript Types
393
543
 
394
544
  All types are exported:
@@ -427,10 +577,10 @@ interface PaginatedResult<T> {
427
577
  }
428
578
 
429
579
  interface QueryFindOptions {
430
- maxTimeMS?: number; // default: 5000
431
- slowQueryThresholdMS?: number; // default: maxTimeMS
432
- maxLimit?: number; // default: 100
433
- lean?: boolean; // default: true
580
+ maxTimeMS?: number; // default: 5000
581
+ slowQueryThresholdMS?: number; // default: maxTimeMS
582
+ maxLimit?: number; // default: 100
583
+ lean?: boolean; // default: true
434
584
  onSlowQuery?: (info: SlowQueryInfo) => void;
435
585
  onSanitizeDrop?: (path: string, value: unknown) => void;
436
586
  }
@@ -448,17 +598,17 @@ interface SlowQueryInfo {
448
598
 
449
599
  ## Security
450
600
 
451
- | Protection | Detail |
452
- | ---------------------------- | -------------------------------------------------------------------------------------------- |
453
- | **NoSQL injection** | Allowlist enforced on filters, sort, and projection via `.allowFields()` |
454
- | **Banned operators** | `$where`, `$expr`, `$function`, and others are rejected recursively at any nesting depth |
455
- | **ReDoS** | Search terms are regex-escaped before compilation |
456
- | **Oversized search** | `?q=` capped at 200 characters |
457
- | **Deep nesting DoS** | Filter object nesting capped at depth 5 |
458
- | **Page size DoS** | `limit` hard-capped at 100 |
459
- | **Sort abuse** | Sort fields hard-capped at 5 |
460
- | **Runaway queries** | `maxTimeMS` applied to both count and find (default: 5s) |
461
- | **Sensitive field leakage** | `?fields=` projection stripped against allowlist |
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 |
462
612
 
463
613
  ---
464
614
 
@@ -502,17 +652,17 @@ A fluent, allowlisted **aggregation-pipeline** builder for Mongoose (`^8 || ^9`)
502
652
 
503
653
  ## When to use QueryAggregate vs QueryFind
504
654
 
505
- | Need | Use |
506
- | ---------------------------------------------------------------- | ------------------ |
507
- | Simple filter/sort/paginate on one collection | `QueryFind` |
508
- | Joining another collection (`$lookup`) | `QueryAggregate` |
509
- | Grouping / rollups / computed fields (`$group`, `$addFields`) | `QueryAggregate` |
510
- | Client filters need to respect the caller's local timezone | `QueryAggregate` |
511
- | A custom day / date span / rolling window / hour-of-day filter | `QueryAggregate` |
512
- | Dashboard totals (sum/avg/count) without fetching a page | `QueryAggregate` |
513
- | Very large collections where `$skip` pagination gets slow | `QueryAggregate` |
514
- | Streaming a large export without buffering it in memory | `QueryAggregate` |
515
- | You need a custom developer-defined pipeline stage | `QueryAggregate` |
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` |
516
666
 
517
667
  ## Installation
518
668
 
@@ -562,23 +712,23 @@ new QueryAggregate<T>(model, queryString, options?);
562
712
  ```
563
713
 
564
714
  | Parameter | Type | Description |
565
- | ------------- | ------------------------ | -------------------------------------------------- |
566
- | `model` | `Model<T>` | A Mongoose model |
567
- | `queryString` | `QueryParams` | Parsed URL query object, e.g. `req.query` |
568
- | `options` | `QueryAggregateOptions` | Configuration options (see below), all optional |
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 |
569
719
 
570
720
  ### `QueryAggregateOptions`
571
721
 
572
- | Option | Type | Default | Description |
573
- | ------------------------ | ------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
574
- | `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). |
575
- | `maxTimeMS` | `number` | `5000` | Max time MongoDB may spend per query. `0` disables. |
576
- | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
577
- | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
578
- | `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` — enable for large sort/group pipelines. |
579
- | `weekStartsOn` | `0–6` | `6` (Saturday) | Used by `.range('thisWeek')`. |
580
- | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
581
- | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a value (bad nesting, non-plain value). |
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). |
582
732
 
583
733
  ## Timezone Handling
584
734
 
@@ -813,14 +963,14 @@ Controls the `$project` stage. Accepts a space-separated string (`"name status -
813
963
 
814
964
  Adds a `$lookup` (join) stage, optionally followed by `$unwind`.
815
965
 
816
- | Field | Type | Description |
817
- | -------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
818
- | `from` | `string` | Collection name (not the model name) to join against. |
819
- | `as` | `string` | Output array field name. |
820
- | `localField` | `string?` | Local join field. |
821
- | `foreignField` | `string?` | Foreign join field. |
822
- | `pipeline` | `PipelineStage[]?` | Sub-pipeline form of `$lookup`, for complex/correlated joins. Cannot contain `$out`/`$merge`. |
823
- | `single` | `boolean?` | When `true`, `$unwind`s the joined array (`preserveNullAndEmptyArrays: true`) so `as` becomes a single object instead of an array. |
966
+ | Field | Type | Description |
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. |
824
974
 
825
975
  ```ts
826
976
  .lookup({
@@ -891,7 +1041,7 @@ Keyset ("seek") pagination — scales far better than `.paginate()`'s `$skip` on
891
1041
  ```ts
892
1042
  interface CursorPaginateOptions {
893
1043
  cursor?: string; // opaque cursor from a previous page's nextCursor
894
- limit?: number; // overrides ?limit=, still capped by maxLimit
1044
+ limit?: number; // overrides ?limit=, still capped by maxLimit
895
1045
  }
896
1046
 
897
1047
  interface CursorPaginatedResult<T> {
@@ -1051,7 +1201,11 @@ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1051
1201
  const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1052
1202
  .allowFields(['status'])
1053
1203
  .where({ branchId: req.self.linkedTo })
1054
- .rangeHours('createdAt', { date: req.query.day as string, fromHour: 9, toHour: 21 })
1204
+ .rangeHours('createdAt', {
1205
+ date: req.query.day as string,
1206
+ fromHour: 9,
1207
+ toHour: 21,
1208
+ })
1055
1209
  .filter()
1056
1210
  .sort()
1057
1211
  .paginate();
@@ -1110,6 +1264,80 @@ for await (const row of builder.stream()) {
1110
1264
  res.end();
1111
1265
  ```
1112
1266
 
1267
+ **ObjectId filter fields (ref lookups by hex ID from the URL):**
1268
+
1269
+ ```
1270
+ GET /orders?branchId=64f1a2b3c4d5e6f7a8b9c0d1&categoryId=64f1a2b3c4d5e6f7a8b9c0d2
1271
+ ```
1272
+
1273
+ ```ts
1274
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1275
+ .allowFields(['branchId', 'categoryId', 'status'])
1276
+ .objectIdFields(['branchId', 'categoryId']) // coerces hex strings -> Types.ObjectId
1277
+ .filter()
1278
+ .sort()
1279
+ .paginate();
1280
+ ```
1281
+
1282
+ **Role-based server conditions with `.whereIf()` + `.excludeSoftDeleted()`:**
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:**
1296
+
1297
+ ```ts
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
+ ]);
1307
+ ```
1308
+
1309
+ **Debug route — inspect the built pipeline / query plan without exposing it to normal users:**
1310
+
1311
+ ```ts
1312
+ router.get('/orders/_debug', requireAdmin, async (req, res) => {
1313
+ const builder = new QueryAggregate(OrderModel, req.query, { timezone })
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
+ });
1324
+ });
1325
+ ```
1326
+
1327
+ **Cursor pagination on a non-default sort field:**
1328
+
1329
+ ```ts
1330
+ const result = await new QueryAggregate(ProductModel, req.query, { timezone })
1331
+ .allowFields(['price', 'name'])
1332
+ .where({ inStock: true })
1333
+ .filter()
1334
+ .sort() // resolves ?sort=price into { price: 1 } — paginateCursor() will seek on "price"
1335
+ .paginateCursor({
1336
+ cursor: req.query.cursor as string | undefined,
1337
+ limit: 24,
1338
+ });
1339
+ ```
1340
+
1113
1341
  **Correlated sub-pipeline `$lookup` (needs `let`):**
1114
1342
 
1115
1343
  The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipelines. For that case, drop to `.addStage()` directly:
@@ -1128,6 +1356,100 @@ The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipeli
1128
1356
  })
1129
1357
  ```
1130
1358
 
1359
+ **Sales analytics dashboard — join, group, and rolling window in one pipeline:**
1360
+
1361
+ ```ts
1362
+ const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
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:**
1390
+
1391
+ ```ts
1392
+ const result = await new QueryAggregate(NotificationModel, req.query, {
1393
+ timezone,
1394
+ })
1395
+ .allowFields(['read', 'type', 'createdAt'])
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
+ ```
1410
+
1411
+ **Audit log search — global search + a bounded absolute datetime window:**
1412
+
1413
+ ```ts
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();
1427
+ ```
1428
+
1429
+ **Multi-branch inventory report — objectIdFields + computeField + stats side by side:**
1430
+
1431
+ ```ts
1432
+ const base = new QueryAggregate(ProductModel, req.query, { timezone })
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
+ ]);
1449
+
1450
+ res.json({ ...page, totals });
1451
+ ```
1452
+
1131
1453
  ## Pipeline Stage Ordering
1132
1454
 
1133
1455
  The final pipeline is always assembled in this fixed order:
@@ -1154,22 +1476,22 @@ Implications:
1154
1476
 
1155
1477
  ## Security
1156
1478
 
1157
- | Protection | Detail |
1158
- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
1159
- | **NoSQL injection** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()` |
1160
- | **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input |
1161
- | **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines |
1162
- | **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation |
1163
- | **Oversized search** | `?q=` capped at 200 characters |
1164
- | **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`) |
1165
- | **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100), including in `.paginateCursor()` |
1166
- | **Sort abuse** | Sort fields hard-capped at 5 |
1167
- | **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability |
1168
- | **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query |
1169
- | **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 |
1170
- | **Server condition override** | `.where()` / `.range()` / every custom range method are merged last via `$and` — URL params can never override them |
1171
- | **Tampered cursors** | `.paginateCursor()` cursors are opaque base64url-encoded JSON; a malformed cursor throws `QueryAggregateValidationError` rather than silently misbehaving |
1172
- | **Untrusted `.addStage()` input** | Not sanitized/allowlisted by design — documented as a trusted, developer-authored-only escape hatch |
1479
+ | Protection | Detail |
1480
+ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1481
+ | **NoSQL injection** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()` |
1482
+ | **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input |
1483
+ | **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines |
1484
+ | **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation |
1485
+ | **Oversized search** | `?q=` capped at 200 characters |
1486
+ | **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`) |
1487
+ | **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100), including in `.paginateCursor()` |
1488
+ | **Sort abuse** | Sort fields hard-capped at 5 |
1489
+ | **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability |
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 |
1173
1495
 
1174
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.
1175
1497
 
@@ -1239,13 +1561,13 @@ type CustomDayInput = string; // "YYYY-MM-DD"
1239
1561
 
1240
1562
  interface CustomDateRangeInput {
1241
1563
  from: string; // "YYYY-MM-DD"
1242
- to: string; // "YYYY-MM-DD"
1564
+ to: string; // "YYYY-MM-DD"
1243
1565
  }
1244
1566
 
1245
1567
  interface CustomHourRangeInput {
1246
- date: string; // "YYYY-MM-DD"
1568
+ date: string; // "YYYY-MM-DD"
1247
1569
  fromHour: number; // 0–24
1248
- toHour: number; // 0–24, exclusive, must be > fromHour
1570
+ toHour: number; // 0–24, exclusive, must be > fromHour
1249
1571
  }
1250
1572
 
1251
1573
  interface CustomDateTimeRangeInput {
@@ -1273,3 +1595,17 @@ interface StatSpec {
1273
1595
  field?: string;
1274
1596
  }
1275
1597
  ```
1598
+
1599
+ ---
1600
+
1601
+ ## Links
1602
+
1603
+ - [npm](https://www.npmjs.com/package/mongoose-query-find)
1604
+ - [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
1605
+ - [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
1606
+
1607
+ ---
1608
+
1609
+ ## License
1610
+
1611
+ ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)