mongoose-query-find 3.2.0 → 3.3.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 +379 -88
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -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,8 @@ 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)
|
|
79
82
|
|
|
80
83
|
---
|
|
81
84
|
|
|
@@ -138,21 +141,21 @@ queryFind(query, queryString, options?);
|
|
|
138
141
|
```
|
|
139
142
|
|
|
140
143
|
| Parameter | Type | Description |
|
|
141
|
-
| ------------- |
|
|
142
|
-
| `query` | `Query<TRawDocType[], TRawDocType>`
|
|
143
|
-
| `queryString` | `QueryParams`
|
|
144
|
-
| `options` | `QueryFindOptions` _(optional)_
|
|
144
|
+
| ------------- | ----------------------------------- | ----------------------------------------------------- |
|
|
145
|
+
| `query` | `Query<TRawDocType[], TRawDocType>` | A Mongoose query, e.g. `Model.find()` |
|
|
146
|
+
| `queryString` | `QueryParams` | The parsed URL query object, e.g. `req.query` |
|
|
147
|
+
| `options` | `QueryFindOptions` _(optional)_ | Configuration options (see [Options](#options) below) |
|
|
145
148
|
|
|
146
149
|
### Options
|
|
147
150
|
|
|
148
|
-
| Option | Type | Default
|
|
149
|
-
|
|
|
150
|
-
| `maxTimeMS`
|
|
151
|
-
| `slowQueryThresholdMS`
|
|
152
|
-
| `maxLimit`
|
|
153
|
-
| `lean`
|
|
154
|
-
| `onSlowQuery`
|
|
155
|
-
| `onSanitizeDrop`
|
|
151
|
+
| Option | Type | Default | Description |
|
|
152
|
+
| ---------------------- | ---------------------------------------- | ----------- | ---------------------------------------------------------------------- |
|
|
153
|
+
| `maxTimeMS` | `number` | `5000` | Max milliseconds MongoDB may spend on each query. Pass `0` to disable. |
|
|
154
|
+
| `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
|
|
155
|
+
| `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
|
|
156
|
+
| `lean` | `boolean` | `true` | Whether `.find()` calls `.lean()` for faster plain-object reads. |
|
|
157
|
+
| `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
|
|
158
|
+
| `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a client-supplied value. |
|
|
156
159
|
|
|
157
160
|
---
|
|
158
161
|
|
|
@@ -333,13 +336,13 @@ GET /users?page=2&limit=20
|
|
|
333
336
|
## Query Parameter Reference
|
|
334
337
|
|
|
335
338
|
| 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`
|
|
339
|
+
| ----------- | ------------------------- | ------------------------------------------------------ |
|
|
340
|
+
| `page` | `?page=3` | Page number (default: `1`, min: `1`) |
|
|
341
|
+
| `limit` | `?limit=25` | Documents per page (default: `10`, max: `100`) |
|
|
342
|
+
| `sort` | `?sort=-createdAt,name` | Sort fields; prefix `-` for descending (max: 5 fields) |
|
|
343
|
+
| `fields` | `?fields=name,email` | Comma-separated fields to include in the response |
|
|
344
|
+
| `q` | `?q=john` | Global search term (max: 200 chars) |
|
|
345
|
+
| _(any key)_ | `?role=admin&age[gte]=18` | Field-level filters processed by `.filter()` |
|
|
343
346
|
|
|
344
347
|
---
|
|
345
348
|
|
|
@@ -389,6 +392,108 @@ GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5
|
|
|
389
392
|
|
|
390
393
|
---
|
|
391
394
|
|
|
395
|
+
## More Examples
|
|
396
|
+
|
|
397
|
+
**E-commerce product listing — nested price filters + category populate:**
|
|
398
|
+
|
|
399
|
+
```ts
|
|
400
|
+
export const getProducts = async (req: Request, res: Response) => {
|
|
401
|
+
const result = await queryFind(ProductModel.find(), req.query)
|
|
402
|
+
.allowFields(['name', 'price', 'category', 'inStock', 'brand', 'createdAt'])
|
|
403
|
+
.where({ deletedAt: null, published: true })
|
|
404
|
+
.filter()
|
|
405
|
+
.globalSearch(['name', 'brand'])
|
|
406
|
+
.sort()
|
|
407
|
+
.limitFields('name price inStock brand')
|
|
408
|
+
.populate('category', 'name slug')
|
|
409
|
+
.paginate();
|
|
410
|
+
|
|
411
|
+
res.json(result);
|
|
412
|
+
};
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
```bash
|
|
416
|
+
# Price between $20 and $100, in stock, sorted cheapest first
|
|
417
|
+
GET /products?price[gte]=20&price[lte]=100&inStock=true&sort=price
|
|
418
|
+
|
|
419
|
+
# Search "nike" across name and brand
|
|
420
|
+
GET /products?q=nike&sort=-createdAt
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
**Blog posts — multiple populates + logical operators:**
|
|
424
|
+
|
|
425
|
+
```ts
|
|
426
|
+
export const getPosts = async (req: Request, res: Response) => {
|
|
427
|
+
const result = await queryFind(PostModel.find(), req.query)
|
|
428
|
+
.allowFields(['title', 'status', 'authorId', 'tags', 'publishedAt'])
|
|
429
|
+
.where({ deletedAt: null })
|
|
430
|
+
.filter()
|
|
431
|
+
.globalSearch(['title'])
|
|
432
|
+
.sort()
|
|
433
|
+
.limitFields('title status publishedAt')
|
|
434
|
+
.populate('authorId', 'name avatar')
|
|
435
|
+
.populate({
|
|
436
|
+
path: 'comments',
|
|
437
|
+
select: 'text createdAt',
|
|
438
|
+
match: { visible: true },
|
|
439
|
+
})
|
|
440
|
+
.paginate();
|
|
441
|
+
|
|
442
|
+
res.json(result);
|
|
443
|
+
};
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
```bash
|
|
447
|
+
# Published OR featured posts, using the safe top-level $or
|
|
448
|
+
GET /posts?$or[0][status]=published&$or[1][featured]=true
|
|
449
|
+
|
|
450
|
+
# Posts tagged "typescript" published this year
|
|
451
|
+
GET /posts?tags=typescript&publishedAt[gte]=2026-01-01
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
**Admin panel — strict field allowlist, sensitive fields never leak:**
|
|
455
|
+
|
|
456
|
+
```ts
|
|
457
|
+
export const adminListUsers = async (req: Request, res: Response) => {
|
|
458
|
+
const result = await queryFind(UserModel.find(), req.query, { maxLimit: 250 })
|
|
459
|
+
.allowFields(['name', 'email', 'role', 'isActive', 'lastLoginAt'])
|
|
460
|
+
.where({ orgId: req.user.orgId })
|
|
461
|
+
.filter()
|
|
462
|
+
.sort()
|
|
463
|
+
.limitFields('-password -passwordResetToken -__v') // client's ?fields= can never override this
|
|
464
|
+
.paginate();
|
|
465
|
+
|
|
466
|
+
res.json(result);
|
|
467
|
+
};
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
```bash
|
|
471
|
+
# Even if a client tries ?fields=password, it's stripped — not in allowFields()
|
|
472
|
+
GET /admin/users?fields=password,email&role=admin
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
**Cached count pattern — skip re-counting on subsequent pages:**
|
|
476
|
+
|
|
477
|
+
```ts
|
|
478
|
+
export const getNotifications = async (req: Request, res: Response) => {
|
|
479
|
+
const builder = queryFind(NotificationModel.find(), req.query)
|
|
480
|
+
.allowFields(['userId', 'read', 'createdAt'])
|
|
481
|
+
.where({ userId: req.user.id })
|
|
482
|
+
.filter()
|
|
483
|
+
.sort();
|
|
484
|
+
|
|
485
|
+
// First request from the client includes no cachedTotal
|
|
486
|
+
const cachedTotal = req.query.cachedTotal
|
|
487
|
+
? Number(req.query.cachedTotal)
|
|
488
|
+
: undefined;
|
|
489
|
+
const result = await builder.paginate(cachedTotal);
|
|
490
|
+
|
|
491
|
+
res.json(result); // client stores result.total and sends it back as ?cachedTotal= on the next page
|
|
492
|
+
};
|
|
493
|
+
```
|
|
494
|
+
|
|
495
|
+
---
|
|
496
|
+
|
|
392
497
|
## TypeScript Types
|
|
393
498
|
|
|
394
499
|
All types are exported:
|
|
@@ -427,10 +532,10 @@ interface PaginatedResult<T> {
|
|
|
427
532
|
}
|
|
428
533
|
|
|
429
534
|
interface QueryFindOptions {
|
|
430
|
-
maxTimeMS?: number;
|
|
431
|
-
slowQueryThresholdMS?: number;
|
|
432
|
-
maxLimit?: number;
|
|
433
|
-
lean?: boolean;
|
|
535
|
+
maxTimeMS?: number; // default: 5000
|
|
536
|
+
slowQueryThresholdMS?: number; // default: maxTimeMS
|
|
537
|
+
maxLimit?: number; // default: 100
|
|
538
|
+
lean?: boolean; // default: true
|
|
434
539
|
onSlowQuery?: (info: SlowQueryInfo) => void;
|
|
435
540
|
onSanitizeDrop?: (path: string, value: unknown) => void;
|
|
436
541
|
}
|
|
@@ -448,17 +553,17 @@ interface SlowQueryInfo {
|
|
|
448
553
|
|
|
449
554
|
## Security
|
|
450
555
|
|
|
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**
|
|
556
|
+
| Protection | Detail |
|
|
557
|
+
| --------------------------- | ---------------------------------------------------------------------------------------- |
|
|
558
|
+
| **NoSQL injection** | Allowlist enforced on filters, sort, and projection via `.allowFields()` |
|
|
559
|
+
| **Banned operators** | `$where`, `$expr`, `$function`, and others are rejected recursively at any nesting depth |
|
|
560
|
+
| **ReDoS** | Search terms are regex-escaped before compilation |
|
|
561
|
+
| **Oversized search** | `?q=` capped at 200 characters |
|
|
562
|
+
| **Deep nesting DoS** | Filter object nesting capped at depth 5 |
|
|
563
|
+
| **Page size DoS** | `limit` hard-capped at 100 |
|
|
564
|
+
| **Sort abuse** | Sort fields hard-capped at 5 |
|
|
565
|
+
| **Runaway queries** | `maxTimeMS` applied to both count and find (default: 5s) |
|
|
566
|
+
| **Sensitive field leakage** | `?fields=` projection stripped against allowlist |
|
|
462
567
|
|
|
463
568
|
---
|
|
464
569
|
|
|
@@ -502,17 +607,17 @@ A fluent, allowlisted **aggregation-pipeline** builder for Mongoose (`^8 || ^9`)
|
|
|
502
607
|
|
|
503
608
|
## When to use QueryAggregate vs QueryFind
|
|
504
609
|
|
|
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
|
|
610
|
+
| Need | Use |
|
|
611
|
+
| -------------------------------------------------------------- | ---------------- |
|
|
612
|
+
| Simple filter/sort/paginate on one collection | `QueryFind` |
|
|
613
|
+
| Joining another collection (`$lookup`) | `QueryAggregate` |
|
|
614
|
+
| Grouping / rollups / computed fields (`$group`, `$addFields`) | `QueryAggregate` |
|
|
615
|
+
| Client filters need to respect the caller's local timezone | `QueryAggregate` |
|
|
616
|
+
| A custom day / date span / rolling window / hour-of-day filter | `QueryAggregate` |
|
|
617
|
+
| Dashboard totals (sum/avg/count) without fetching a page | `QueryAggregate` |
|
|
618
|
+
| Very large collections where `$skip` pagination gets slow | `QueryAggregate` |
|
|
619
|
+
| Streaming a large export without buffering it in memory | `QueryAggregate` |
|
|
620
|
+
| You need a custom developer-defined pipeline stage | `QueryAggregate` |
|
|
516
621
|
|
|
517
622
|
## Installation
|
|
518
623
|
|
|
@@ -562,23 +667,23 @@ new QueryAggregate<T>(model, queryString, options?);
|
|
|
562
667
|
```
|
|
563
668
|
|
|
564
669
|
| Parameter | Type | Description |
|
|
565
|
-
| ------------- |
|
|
566
|
-
| `model` | `Model<T>`
|
|
567
|
-
| `queryString` | `QueryParams`
|
|
568
|
-
| `options` | `QueryAggregateOptions`
|
|
670
|
+
| ------------- | ----------------------- | ----------------------------------------------- |
|
|
671
|
+
| `model` | `Model<T>` | A Mongoose model |
|
|
672
|
+
| `queryString` | `QueryParams` | Parsed URL query object, e.g. `req.query` |
|
|
673
|
+
| `options` | `QueryAggregateOptions` | Configuration options (see below), all optional |
|
|
569
674
|
|
|
570
675
|
### `QueryAggregateOptions`
|
|
571
676
|
|
|
572
|
-
| Option | Type | Default | Description
|
|
573
|
-
|
|
|
574
|
-
| `timezone`
|
|
575
|
-
| `maxTimeMS`
|
|
576
|
-
| `slowQueryThresholdMS`
|
|
577
|
-
| `maxLimit`
|
|
578
|
-
| `allowDiskUse`
|
|
579
|
-
| `weekStartsOn`
|
|
580
|
-
| `onSlowQuery`
|
|
581
|
-
| `onSanitizeDrop`
|
|
677
|
+
| Option | Type | Default | Description |
|
|
678
|
+
| ---------------------- | ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
679
|
+
| `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). |
|
|
680
|
+
| `maxTimeMS` | `number` | `5000` | Max time MongoDB may spend per query. `0` disables. |
|
|
681
|
+
| `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
|
|
682
|
+
| `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
|
|
683
|
+
| `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` — enable for large sort/group pipelines. |
|
|
684
|
+
| `weekStartsOn` | `0–6` | `6` (Saturday) | Used by `.range('thisWeek')`. |
|
|
685
|
+
| `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
|
|
686
|
+
| `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a value (bad nesting, non-plain value). |
|
|
582
687
|
|
|
583
688
|
## Timezone Handling
|
|
584
689
|
|
|
@@ -813,14 +918,14 @@ Controls the `$project` stage. Accepts a space-separated string (`"name status -
|
|
|
813
918
|
|
|
814
919
|
Adds a `$lookup` (join) stage, optionally followed by `$unwind`.
|
|
815
920
|
|
|
816
|
-
| Field | Type | Description
|
|
817
|
-
| -------------- |
|
|
818
|
-
| `from` | `string`
|
|
819
|
-
| `as` | `string`
|
|
820
|
-
| `localField` | `string?`
|
|
821
|
-
| `foreignField` | `string?`
|
|
822
|
-
| `pipeline` | `PipelineStage[]?`
|
|
823
|
-
| `single` | `boolean?`
|
|
921
|
+
| Field | Type | Description |
|
|
922
|
+
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
923
|
+
| `from` | `string` | Collection name (not the model name) to join against. |
|
|
924
|
+
| `as` | `string` | Output array field name. |
|
|
925
|
+
| `localField` | `string?` | Local join field. |
|
|
926
|
+
| `foreignField` | `string?` | Foreign join field. |
|
|
927
|
+
| `pipeline` | `PipelineStage[]?` | Sub-pipeline form of `$lookup`, for complex/correlated joins. Cannot contain `$out`/`$merge`. |
|
|
928
|
+
| `single` | `boolean?` | When `true`, `$unwind`s the joined array (`preserveNullAndEmptyArrays: true`) so `as` becomes a single object instead of an array. |
|
|
824
929
|
|
|
825
930
|
```ts
|
|
826
931
|
.lookup({
|
|
@@ -891,7 +996,7 @@ Keyset ("seek") pagination — scales far better than `.paginate()`'s `$skip` on
|
|
|
891
996
|
```ts
|
|
892
997
|
interface CursorPaginateOptions {
|
|
893
998
|
cursor?: string; // opaque cursor from a previous page's nextCursor
|
|
894
|
-
limit?: number;
|
|
999
|
+
limit?: number; // overrides ?limit=, still capped by maxLimit
|
|
895
1000
|
}
|
|
896
1001
|
|
|
897
1002
|
interface CursorPaginatedResult<T> {
|
|
@@ -1051,7 +1156,11 @@ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
|
1051
1156
|
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1052
1157
|
.allowFields(['status'])
|
|
1053
1158
|
.where({ branchId: req.self.linkedTo })
|
|
1054
|
-
.rangeHours('createdAt', {
|
|
1159
|
+
.rangeHours('createdAt', {
|
|
1160
|
+
date: req.query.day as string,
|
|
1161
|
+
fromHour: 9,
|
|
1162
|
+
toHour: 21,
|
|
1163
|
+
})
|
|
1055
1164
|
.filter()
|
|
1056
1165
|
.sort()
|
|
1057
1166
|
.paginate();
|
|
@@ -1110,6 +1219,80 @@ for await (const row of builder.stream()) {
|
|
|
1110
1219
|
res.end();
|
|
1111
1220
|
```
|
|
1112
1221
|
|
|
1222
|
+
**ObjectId filter fields (ref lookups by hex ID from the URL):**
|
|
1223
|
+
|
|
1224
|
+
```
|
|
1225
|
+
GET /orders?branchId=64f1a2b3c4d5e6f7a8b9c0d1&categoryId=64f1a2b3c4d5e6f7a8b9c0d2
|
|
1226
|
+
```
|
|
1227
|
+
|
|
1228
|
+
```ts
|
|
1229
|
+
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1230
|
+
.allowFields(['branchId', 'categoryId', 'status'])
|
|
1231
|
+
.objectIdFields(['branchId', 'categoryId']) // coerces hex strings -> Types.ObjectId
|
|
1232
|
+
.filter()
|
|
1233
|
+
.sort()
|
|
1234
|
+
.paginate();
|
|
1235
|
+
```
|
|
1236
|
+
|
|
1237
|
+
**Role-based server conditions with `.whereIf()` + `.excludeSoftDeleted()`:**
|
|
1238
|
+
|
|
1239
|
+
```ts
|
|
1240
|
+
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1241
|
+
.allowFields(['status', 'branchId', 'createdAt'])
|
|
1242
|
+
.excludeSoftDeleted() // deletedAt: null, always applied
|
|
1243
|
+
.whereIf(req.self.role !== 'admin', { branchId: req.self.linkedTo }) // branch staff see only their branch
|
|
1244
|
+
.whereIf(req.query.vip === 'true', { tier: 'vip' })
|
|
1245
|
+
.filter()
|
|
1246
|
+
.sort()
|
|
1247
|
+
.paginate();
|
|
1248
|
+
```
|
|
1249
|
+
|
|
1250
|
+
**Populating a filter UI — distinct values + count, no data fetch:**
|
|
1251
|
+
|
|
1252
|
+
```ts
|
|
1253
|
+
const builder = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1254
|
+
.allowFields(['status', 'branchId'])
|
|
1255
|
+
.where({ branchId: req.self.linkedTo })
|
|
1256
|
+
.filter();
|
|
1257
|
+
|
|
1258
|
+
const [statuses, total] = await Promise.all([
|
|
1259
|
+
builder.clone().distinct('status'), // populate a <select> of possible statuses
|
|
1260
|
+
builder.clone().count(), // "X results" label
|
|
1261
|
+
]);
|
|
1262
|
+
```
|
|
1263
|
+
|
|
1264
|
+
**Debug route — inspect the built pipeline / query plan without exposing it to normal users:**
|
|
1265
|
+
|
|
1266
|
+
```ts
|
|
1267
|
+
router.get('/orders/_debug', requireAdmin, async (req, res) => {
|
|
1268
|
+
const builder = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1269
|
+
.allowFields(['status', 'createdAt'])
|
|
1270
|
+
.where({ branchId: req.self.linkedTo })
|
|
1271
|
+
.range('createdAt', 'last7Days')
|
|
1272
|
+
.filter()
|
|
1273
|
+
.sort();
|
|
1274
|
+
|
|
1275
|
+
res.json({
|
|
1276
|
+
pipeline: builder.debugPipeline(),
|
|
1277
|
+
explain: await builder.explain('executionStats'),
|
|
1278
|
+
});
|
|
1279
|
+
});
|
|
1280
|
+
```
|
|
1281
|
+
|
|
1282
|
+
**Cursor pagination on a non-default sort field:**
|
|
1283
|
+
|
|
1284
|
+
```ts
|
|
1285
|
+
const result = await new QueryAggregate(ProductModel, req.query, { timezone })
|
|
1286
|
+
.allowFields(['price', 'name'])
|
|
1287
|
+
.where({ inStock: true })
|
|
1288
|
+
.filter()
|
|
1289
|
+
.sort() // resolves ?sort=price into { price: 1 } — paginateCursor() will seek on "price"
|
|
1290
|
+
.paginateCursor({
|
|
1291
|
+
cursor: req.query.cursor as string | undefined,
|
|
1292
|
+
limit: 24,
|
|
1293
|
+
});
|
|
1294
|
+
```
|
|
1295
|
+
|
|
1113
1296
|
**Correlated sub-pipeline `$lookup` (needs `let`):**
|
|
1114
1297
|
|
|
1115
1298
|
The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipelines. For that case, drop to `.addStage()` directly:
|
|
@@ -1128,6 +1311,100 @@ The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipeli
|
|
|
1128
1311
|
})
|
|
1129
1312
|
```
|
|
1130
1313
|
|
|
1314
|
+
**Sales analytics dashboard — join, group, and rolling window in one pipeline:**
|
|
1315
|
+
|
|
1316
|
+
```ts
|
|
1317
|
+
const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
|
|
1318
|
+
|
|
1319
|
+
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1320
|
+
.allowFields(['branchId', 'status'])
|
|
1321
|
+
.where({ status: 'PAID' })
|
|
1322
|
+
.rangeLastNDays('createdAt', 30) // rolling 30-day window, client can't override
|
|
1323
|
+
.filter()
|
|
1324
|
+
.lookup({
|
|
1325
|
+
from: 'branches',
|
|
1326
|
+
as: 'branch',
|
|
1327
|
+
localField: 'branchId',
|
|
1328
|
+
foreignField: '_id',
|
|
1329
|
+
single: true,
|
|
1330
|
+
})
|
|
1331
|
+
.addStage({
|
|
1332
|
+
$group: {
|
|
1333
|
+
_id: '$branchId',
|
|
1334
|
+
branchName: { $first: '$branch.name' },
|
|
1335
|
+
revenue: { $sum: '$total' },
|
|
1336
|
+
orders: { $sum: 1 },
|
|
1337
|
+
avgOrderValue: { $avg: '$total' },
|
|
1338
|
+
},
|
|
1339
|
+
})
|
|
1340
|
+
.addStage({ $sort: { revenue: -1 } })
|
|
1341
|
+
.paginate();
|
|
1342
|
+
```
|
|
1343
|
+
|
|
1344
|
+
**Notification feed — lookup + unwind a single related document per row:**
|
|
1345
|
+
|
|
1346
|
+
```ts
|
|
1347
|
+
const result = await new QueryAggregate(NotificationModel, req.query, {
|
|
1348
|
+
timezone,
|
|
1349
|
+
})
|
|
1350
|
+
.allowFields(['read', 'type', 'createdAt'])
|
|
1351
|
+
.dateFields(['createdAt'])
|
|
1352
|
+
.where({ userId: req.user.id })
|
|
1353
|
+
.filter()
|
|
1354
|
+
.lookup({
|
|
1355
|
+
from: 'users',
|
|
1356
|
+
as: 'actor',
|
|
1357
|
+
localField: 'actorId',
|
|
1358
|
+
foreignField: '_id',
|
|
1359
|
+
single: true, // unwinds so `actor` is a single object, not an array
|
|
1360
|
+
})
|
|
1361
|
+
.sort()
|
|
1362
|
+
.project('type read createdAt actor.name actor.avatar')
|
|
1363
|
+
.paginate();
|
|
1364
|
+
```
|
|
1365
|
+
|
|
1366
|
+
**Audit log search — global search + a bounded absolute datetime window:**
|
|
1367
|
+
|
|
1368
|
+
```ts
|
|
1369
|
+
const result = await new QueryAggregate(AuditLogModel, req.query, { timezone })
|
|
1370
|
+
.allowFields(['action', 'actorId', 'createdAt'])
|
|
1371
|
+
.dateFields(['createdAt'])
|
|
1372
|
+
.where({ orgId: req.user.orgId })
|
|
1373
|
+
.rangeCustom('createdAt', {
|
|
1374
|
+
from: (req.query.from as string) ?? '2026-01-01T00:00:00',
|
|
1375
|
+
to: (req.query.to as string) ?? new Date().toISOString(),
|
|
1376
|
+
})
|
|
1377
|
+
.filter()
|
|
1378
|
+
.globalSearch(['action'])
|
|
1379
|
+
.sort()
|
|
1380
|
+
.project('action actorId createdAt')
|
|
1381
|
+
.paginate();
|
|
1382
|
+
```
|
|
1383
|
+
|
|
1384
|
+
**Multi-branch inventory report — objectIdFields + computeField + stats side by side:**
|
|
1385
|
+
|
|
1386
|
+
```ts
|
|
1387
|
+
const base = new QueryAggregate(ProductModel, req.query, { timezone })
|
|
1388
|
+
.allowFields(['branchId', 'category', 'stock', 'price'])
|
|
1389
|
+
.objectIdFields(['branchId'])
|
|
1390
|
+
.where({ deletedAt: null })
|
|
1391
|
+
.filter()
|
|
1392
|
+
.computeField('stockValue', { $multiply: ['$stock', '$price'] })
|
|
1393
|
+
.sort()
|
|
1394
|
+
.project('branchId category stock price stockValue');
|
|
1395
|
+
|
|
1396
|
+
const [page, totals] = await Promise.all([
|
|
1397
|
+
base.clone().paginate(),
|
|
1398
|
+
base.clone().stats([
|
|
1399
|
+
{ name: 'totalStockValue', op: 'sum', field: 'stockValue' },
|
|
1400
|
+
{ name: 'lowStockAvg', op: 'avg', field: 'stock' },
|
|
1401
|
+
{ name: 'skuCount', op: 'count' },
|
|
1402
|
+
]),
|
|
1403
|
+
]);
|
|
1404
|
+
|
|
1405
|
+
res.json({ ...page, totals });
|
|
1406
|
+
```
|
|
1407
|
+
|
|
1131
1408
|
## Pipeline Stage Ordering
|
|
1132
1409
|
|
|
1133
1410
|
The final pipeline is always assembled in this fixed order:
|
|
@@ -1154,22 +1431,22 @@ Implications:
|
|
|
1154
1431
|
|
|
1155
1432
|
## Security
|
|
1156
1433
|
|
|
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**
|
|
1434
|
+
| Protection | Detail |
|
|
1435
|
+
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1436
|
+
| **NoSQL injection** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()` |
|
|
1437
|
+
| **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input |
|
|
1438
|
+
| **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines |
|
|
1439
|
+
| **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation |
|
|
1440
|
+
| **Oversized search** | `?q=` capped at 200 characters |
|
|
1441
|
+
| **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`) |
|
|
1442
|
+
| **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100), including in `.paginateCursor()` |
|
|
1443
|
+
| **Sort abuse** | Sort fields hard-capped at 5 |
|
|
1444
|
+
| **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability |
|
|
1445
|
+
| **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query |
|
|
1446
|
+
| **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 |
|
|
1447
|
+
| **Server condition override** | `.where()` / `.range()` / every custom range method are merged last via `$and` — URL params can never override them |
|
|
1448
|
+
| **Tampered cursors** | `.paginateCursor()` cursors are opaque base64url-encoded JSON; a malformed cursor throws `QueryAggregateValidationError` rather than silently misbehaving |
|
|
1449
|
+
| **Untrusted `.addStage()` input** | Not sanitized/allowlisted by design — documented as a trusted, developer-authored-only escape hatch |
|
|
1173
1450
|
|
|
1174
1451
|
> **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
1452
|
|
|
@@ -1239,13 +1516,13 @@ type CustomDayInput = string; // "YYYY-MM-DD"
|
|
|
1239
1516
|
|
|
1240
1517
|
interface CustomDateRangeInput {
|
|
1241
1518
|
from: string; // "YYYY-MM-DD"
|
|
1242
|
-
to: string;
|
|
1519
|
+
to: string; // "YYYY-MM-DD"
|
|
1243
1520
|
}
|
|
1244
1521
|
|
|
1245
1522
|
interface CustomHourRangeInput {
|
|
1246
|
-
date: string;
|
|
1523
|
+
date: string; // "YYYY-MM-DD"
|
|
1247
1524
|
fromHour: number; // 0–24
|
|
1248
|
-
toHour: number;
|
|
1525
|
+
toHour: number; // 0–24, exclusive, must be > fromHour
|
|
1249
1526
|
}
|
|
1250
1527
|
|
|
1251
1528
|
interface CustomDateTimeRangeInput {
|
|
@@ -1273,3 +1550,17 @@ interface StatSpec {
|
|
|
1273
1550
|
field?: string;
|
|
1274
1551
|
}
|
|
1275
1552
|
```
|
|
1553
|
+
|
|
1554
|
+
---
|
|
1555
|
+
|
|
1556
|
+
## Links
|
|
1557
|
+
|
|
1558
|
+
- [npm](https://www.npmjs.com/package/mongoose-query-find)
|
|
1559
|
+
- [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
|
|
1560
|
+
- [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
|
|
1561
|
+
|
|
1562
|
+
---
|
|
1563
|
+
|
|
1564
|
+
## License
|
|
1565
|
+
|
|
1566
|
+
ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
|