mongoose-query-find 3.2.0 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +425 -89
- package/dist/analytics.d.ts +267 -0
- package/dist/analytics.d.ts.map +1 -0
- package/dist/analytics.js +877 -0
- package/dist/analytics.js.map +1 -0
- package/dist/index.d.ts +8 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -3
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://github.com/jsdev-robin/mongoose-query-find/blob/main/LICENSE)
|
|
5
5
|
[](https://mongoosejs.com)
|
|
6
6
|
|
|
7
|
-
|
|
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>`
|
|
143
|
-
| `queryString` | `QueryParams`
|
|
144
|
-
| `options` | `QueryFindOptions` _(optional)_
|
|
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
|
|
149
|
-
|
|
|
150
|
-
| `maxTimeMS`
|
|
151
|
-
| `slowQueryThresholdMS`
|
|
152
|
-
| `maxLimit`
|
|
153
|
-
| `lean`
|
|
154
|
-
| `onSlowQuery`
|
|
155
|
-
| `onSanitizeDrop`
|
|
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`
|
|
338
|
-
| `limit` | `?limit=25`
|
|
339
|
-
| `sort` | `?sort=-createdAt,name`
|
|
340
|
-
| `fields` | `?fields=name,email`
|
|
341
|
-
| `q` | `?q=john`
|
|
342
|
-
| _(any key)_ | `?role=admin&age[gte]=18`
|
|
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;
|
|
431
|
-
slowQueryThresholdMS?: number;
|
|
432
|
-
maxLimit?: number;
|
|
433
|
-
lean?: boolean;
|
|
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**
|
|
454
|
-
| **Banned operators**
|
|
455
|
-
| **ReDoS**
|
|
456
|
-
| **Oversized search**
|
|
457
|
-
| **Deep nesting DoS**
|
|
458
|
-
| **Page size DoS**
|
|
459
|
-
| **Sort abuse**
|
|
460
|
-
| **Runaway queries**
|
|
461
|
-
| **Sensitive field leakage**
|
|
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
|
|
506
|
-
|
|
|
507
|
-
| Simple filter/sort/paginate on one collection
|
|
508
|
-
| Joining another collection (`$lookup`)
|
|
509
|
-
| Grouping / rollups / computed fields (`$group`, `$addFields`)
|
|
510
|
-
| Client filters need to respect the caller's local timezone
|
|
511
|
-
| A custom day / date span / rolling window / hour-of-day filter
|
|
512
|
-
| Dashboard totals (sum/avg/count) without fetching a page
|
|
513
|
-
| Very large collections where `$skip` pagination gets slow
|
|
514
|
-
| Streaming a large export without buffering it in memory
|
|
515
|
-
| You need a custom developer-defined pipeline stage
|
|
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>`
|
|
567
|
-
| `queryString` | `QueryParams`
|
|
568
|
-
| `options` | `QueryAggregateOptions`
|
|
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`
|
|
575
|
-
| `maxTimeMS`
|
|
576
|
-
| `slowQueryThresholdMS`
|
|
577
|
-
| `maxLimit`
|
|
578
|
-
| `allowDiskUse`
|
|
579
|
-
| `weekStartsOn`
|
|
580
|
-
| `onSlowQuery`
|
|
581
|
-
| `onSanitizeDrop`
|
|
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`
|
|
819
|
-
| `as` | `string`
|
|
820
|
-
| `localField` | `string?`
|
|
821
|
-
| `foreignField` | `string?`
|
|
822
|
-
| `pipeline` | `PipelineStage[]?`
|
|
823
|
-
| `single` | `boolean?`
|
|
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;
|
|
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', {
|
|
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**
|
|
1160
|
-
| **Banned operators**
|
|
1161
|
-
| **Destructive stages**
|
|
1162
|
-
| **ReDoS**
|
|
1163
|
-
| **Oversized search**
|
|
1164
|
-
| **Deep nesting DoS**
|
|
1165
|
-
| **Page size DoS**
|
|
1166
|
-
| **Sort abuse**
|
|
1167
|
-
| **Runaway queries**
|
|
1168
|
-
| **Bad timezone input**
|
|
1169
|
-
| **Bad custom-range input**
|
|
1170
|
-
| **Server condition override**
|
|
1171
|
-
| **Tampered cursors**
|
|
1172
|
-
| **Untrusted `.addStage()` input**
|
|
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;
|
|
1564
|
+
to: string; // "YYYY-MM-DD"
|
|
1243
1565
|
}
|
|
1244
1566
|
|
|
1245
1567
|
interface CustomHourRangeInput {
|
|
1246
|
-
date: string;
|
|
1568
|
+
date: string; // "YYYY-MM-DD"
|
|
1247
1569
|
fromHour: number; // 0–24
|
|
1248
|
-
toHour: number;
|
|
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)
|