mongoose-query-find 3.1.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 +730 -39
- package/dist/aggregate.d.ts +127 -0
- package/dist/aggregate.d.ts.map +1 -1
- package/dist/aggregate.js +308 -0
- package/dist/aggregate.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
|
+
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.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
@@ -27,6 +27,7 @@ A fluent, chainable query builder for Mongoose that handles filtering, global se
|
|
|
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)
|
|
@@ -43,20 +44,41 @@ A fluent, chainable query builder for Mongoose that handles filtering, global se
|
|
|
43
44
|
- [Builder Methods](#builder-methods-1)
|
|
44
45
|
- [.allowFields()](#allowfieldsfields-string-1)
|
|
45
46
|
- [.dateFields()](#datefieldsfields-string)
|
|
47
|
+
- [.objectIdFields()](#objectidfieldsfields-string)
|
|
46
48
|
- [.filter()](#filter-1)
|
|
47
49
|
- [.where()](#whereconditions-1)
|
|
48
50
|
- [.range()](#rangefield-string-preset-rangepreset)
|
|
51
|
+
- [Custom Range Methods](#custom-range-methods)
|
|
52
|
+
- [.rangeCustomDay()](#rangecustomdayfield-string-date-string)
|
|
53
|
+
- [.rangeBetween()](#rangebetweenfield-string-custom-customdaterangeinput)
|
|
54
|
+
- [.rangeLastNDays()](#rangelastndaysfield-string-days-number)
|
|
55
|
+
- [.rangeLastNHours()](#rangelastnhoursfield-string-hours-number)
|
|
56
|
+
- [.rangeHours()](#rangehoursfield-string-custom-customhourrangeinput)
|
|
57
|
+
- [.rangeCustom()](#rangecustomfield-string-custom-customdatetimerangeinput)
|
|
58
|
+
- [.excludeSoftDeleted()](#excludesoftdeletedfield-deletedat)
|
|
59
|
+
- [.whereIf()](#whereifcondition-conditions)
|
|
49
60
|
- [.globalSearch()](#globalsearchfields-string-1)
|
|
50
61
|
- [.sort()](#sort-1)
|
|
51
62
|
- [.project()](#projectdefaultprojection-string--recordstring-0--1)
|
|
52
63
|
- [.lookup()](#lookupopts-lookupoptions)
|
|
64
|
+
- [.computeField()](#computefieldname-string-expression-unknown)
|
|
53
65
|
- [.addStage()](#addstagestage-pipelinestage)
|
|
54
|
-
- [Terminal
|
|
66
|
+
- [Terminal & Utility Methods](#terminal--utility-methods)
|
|
55
67
|
- [.paginate()](#paginatecachedtotal-number)
|
|
68
|
+
- [.paginateCursor()](#paginatecursoropts-cursorpaginateoptions)
|
|
69
|
+
- [.count()](#count)
|
|
70
|
+
- [.distinct()](#distinctfield-string)
|
|
71
|
+
- [.stats()](#statsspecs-statspec)
|
|
72
|
+
- [.stream()](#stream)
|
|
73
|
+
- [.explain()](#explainverbosity)
|
|
74
|
+
- [.clone()](#clone)
|
|
75
|
+
- [.debugPipeline()](#debugpipeline)
|
|
56
76
|
- [Recipes](#recipes)
|
|
57
77
|
- [Pipeline Stage Ordering](#pipeline-stage-ordering)
|
|
58
78
|
- [Security](#security-1)
|
|
59
79
|
- [TypeScript Types](#typescript-types-1)
|
|
80
|
+
- [Links](#links-1)
|
|
81
|
+
- [License](#license-1)
|
|
60
82
|
|
|
61
83
|
---
|
|
62
84
|
|
|
@@ -126,9 +148,14 @@ queryFind(query, queryString, options?);
|
|
|
126
148
|
|
|
127
149
|
### Options
|
|
128
150
|
|
|
129
|
-
| Option
|
|
130
|
-
|
|
|
131
|
-
| `maxTimeMS`
|
|
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. |
|
|
132
159
|
|
|
133
160
|
---
|
|
134
161
|
|
|
@@ -365,6 +392,108 @@ GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5
|
|
|
365
392
|
|
|
366
393
|
---
|
|
367
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
|
+
|
|
368
497
|
## TypeScript Types
|
|
369
498
|
|
|
370
499
|
All types are exported:
|
|
@@ -376,6 +505,9 @@ import {
|
|
|
376
505
|
QueryParams,
|
|
377
506
|
PaginatedResult,
|
|
378
507
|
QueryFindOptions,
|
|
508
|
+
QueryFindError,
|
|
509
|
+
QueryFindValidationError,
|
|
510
|
+
SlowQueryInfo,
|
|
379
511
|
} from 'mongoose-query-find';
|
|
380
512
|
```
|
|
381
513
|
|
|
@@ -401,6 +533,19 @@ interface PaginatedResult<T> {
|
|
|
401
533
|
|
|
402
534
|
interface QueryFindOptions {
|
|
403
535
|
maxTimeMS?: number; // default: 5000
|
|
536
|
+
slowQueryThresholdMS?: number; // default: maxTimeMS
|
|
537
|
+
maxLimit?: number; // default: 100
|
|
538
|
+
lean?: boolean; // default: true
|
|
539
|
+
onSlowQuery?: (info: SlowQueryInfo) => void;
|
|
540
|
+
onSanitizeDrop?: (path: string, value: unknown) => void;
|
|
541
|
+
}
|
|
542
|
+
|
|
543
|
+
interface SlowQueryInfo {
|
|
544
|
+
elapsedMs: number;
|
|
545
|
+
filter: Record<string, unknown>;
|
|
546
|
+
sort: Record<string, 1 | -1>;
|
|
547
|
+
page: number;
|
|
548
|
+
limit: number;
|
|
404
549
|
}
|
|
405
550
|
```
|
|
406
551
|
|
|
@@ -443,27 +588,36 @@ ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
|
|
|
443
588
|
|
|
444
589
|
# QueryAggregate
|
|
445
590
|
|
|
446
|
-
A fluent, allowlisted **aggregation-pipeline** builder for Mongoose (`^8 || ^9`), built on `Model.aggregate()`. It mirrors the same safety model as `QueryFind` — allowlisted filter fields, sanitized/rejected operators, capped pagination — but adds `$lookup` joins, `$group`,
|
|
591
|
+
A fluent, allowlisted **aggregation-pipeline** builder for Mongoose (`^8 || ^9`), built on `Model.aggregate()`. It mirrors the same safety model as `QueryFind` — allowlisted filter fields, sanitized/rejected operators, capped pagination — but adds `$lookup` joins, `$group`, timezone-aware date filtering, custom date/hour ranges, keyset pagination, and one-round-trip dashboard stats.
|
|
447
592
|
|
|
448
593
|
## QueryAggregate Overview
|
|
449
594
|
|
|
450
|
-
`QueryFind` is built on `Model.find()` and can't express joins or grouping. `QueryAggregate` solves that while keeping the same guardrails:
|
|
595
|
+
`QueryFind` is built on `Model.find()` and can't express joins or grouping. `QueryAggregate` solves that while keeping the same guardrails, plus a lot more:
|
|
451
596
|
|
|
452
597
|
- Allowlisted filter/sort/projection fields
|
|
453
598
|
- Recursive sanitization of client input (drops class instances, functions, over-deep nesting)
|
|
454
599
|
- Banned-operator rejection (`$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`)
|
|
455
600
|
- Capped pagination (`limit`, `page`)
|
|
456
|
-
-
|
|
601
|
+
- Timezone-aware date coercion, `$lookup` joins, arbitrary developer-authored pipeline stages via `.addStage()`
|
|
602
|
+
- Single-round-trip pagination via `$facet`
|
|
603
|
+
- **New:** six custom date-range methods (arbitrary day, arbitrary span, rolling N-days/N-hours, hour-of-day windows, absolute datetime windows)
|
|
604
|
+
- **New:** `count()`, `distinct()`, and `stats()` for cheap metrics without fetching a data page
|
|
605
|
+
- **New:** `stream()` for memory-safe large exports, and `paginateCursor()` for keyset pagination on huge collections
|
|
606
|
+
- **New:** `explain()`, `debugPipeline()`, and `clone()` for debugging and query reuse
|
|
457
607
|
|
|
458
608
|
## When to use QueryAggregate vs QueryFind
|
|
459
609
|
|
|
460
|
-
| Need
|
|
461
|
-
|
|
|
462
|
-
| Simple filter/sort/paginate on one collection
|
|
463
|
-
| Joining another collection (`$lookup`)
|
|
464
|
-
| Grouping / rollups / computed fields (`$group`, `$addFields`)
|
|
465
|
-
| Client filters need to respect the caller's local timezone
|
|
466
|
-
|
|
|
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` |
|
|
467
621
|
|
|
468
622
|
## Installation
|
|
469
623
|
|
|
@@ -536,7 +690,7 @@ new QueryAggregate<T>(model, queryString, options?);
|
|
|
536
690
|
MongoDB always stores/compares dates in UTC. Clients think and filter in local time — `?createdAt=2026-09-01` means "Sept 1st in the caller's timezone," not UTC midnight.
|
|
537
691
|
|
|
538
692
|
- `fromZonedTime(localString, tz)` → exact UTC instant for a wall-clock time in `tz`. Used to turn a client-supplied local date into the correct `$gte`/`$lt` UTC range in `$match`.
|
|
539
|
-
- `toZonedTime(utcDate, tz)` → wall-clock `Date` for `tz`. Used to compute "what day is it right now, in the caller's timezone" for `.range()` presets.
|
|
693
|
+
- `toZonedTime(utcDate, tz)` → wall-clock `Date` for `tz`. Used to compute "what day is it right now, in the caller's timezone" for `.range()` presets and the rolling-N-days custom range.
|
|
540
694
|
|
|
541
695
|
The timezone is a **per-request** value, typically sourced from a header:
|
|
542
696
|
|
|
@@ -546,14 +700,14 @@ const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
|
|
|
546
700
|
|
|
547
701
|
An invalid/unknown IANA timezone string (bad header, typo) never throws — it's validated once at construction (`resolveTimezone`) and silently falls back to the default.
|
|
548
702
|
|
|
549
|
-
Plain `YYYY-MM-DD` filter values are expanded into a `$gte`/`$lt` range spanning that local day; values with an explicit offset (`Z`, `+06:00`) are treated as absolute instants and passed through as-is.
|
|
703
|
+
Plain `YYYY-MM-DD` filter values are expanded into a `$gte`/`$lt` range spanning that local day; values with an explicit offset (`Z`, `+06:00`) are treated as absolute instants and passed through as-is. Every custom range method below applies the same timezone-aware logic.
|
|
550
704
|
|
|
551
705
|
## Builder Methods
|
|
552
706
|
|
|
553
707
|
All builder methods return `this` and are fully chainable. Recommended call order:
|
|
554
708
|
|
|
555
709
|
```
|
|
556
|
-
allowFields → dateFields → where → range → filter → globalSearch → sort → project → lookup/addStage → paginate
|
|
710
|
+
allowFields → dateFields/objectIdFields → where → range/rangeXxx → filter → globalSearch → sort → project → lookup/addStage/computeField → paginate/paginateCursor/count/distinct/stats/stream
|
|
557
711
|
```
|
|
558
712
|
|
|
559
713
|
---
|
|
@@ -578,13 +732,23 @@ Explicit list of fields treated as dates for timezone-aware coercion. When omitt
|
|
|
578
732
|
|
|
579
733
|
---
|
|
580
734
|
|
|
735
|
+
### `.objectIdFields(fields: string[])`
|
|
736
|
+
|
|
737
|
+
Explicit list of fields treated as ObjectId references, so a client-supplied 24-char hex string (`?categoryId=...`) is coerced to `Types.ObjectId` instead of being compared as a plain string (which would never match, since it's a different BSON type). When omitted, falls back to a name heuristic matching `_id` or any field ending in `Id` (e.g. `categoryId`, `basicInfo.brandId`).
|
|
738
|
+
|
|
739
|
+
```ts
|
|
740
|
+
.objectIdFields(['branchId', 'categoryId'])
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
---
|
|
744
|
+
|
|
581
745
|
### `.filter()`
|
|
582
746
|
|
|
583
747
|
Parses `req.query` into the aggregation `$match` stage's client-derived portion. Runs, in order:
|
|
584
748
|
|
|
585
749
|
1. Strips reserved keys (`page`, `sort`, `limit`, `fields`, `q`)
|
|
586
750
|
2. `sanitize()` — recursively drops non-plain values (class instances, functions), capped at nesting depth 5
|
|
587
|
-
3. `coerceAll()` — timezone-aware date coercion + boolean coercion + operator-name coercion (`gt` → `$gt`, etc.)
|
|
751
|
+
3. `coerceAll()` — timezone-aware date coercion + ObjectId coercion + boolean coercion + numeric coercion + operator-name coercion (`gt` → `$gt`, etc.)
|
|
588
752
|
4. `enforceAllowlist()` — strips any non-operator key not in `.allowFields()`
|
|
589
753
|
5. `rejectDisallowedOperators()` — throws `QueryAggregateValidationError` on `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`, or any unexpected top-level `$` operator
|
|
590
754
|
|
|
@@ -623,6 +787,95 @@ Adds a hard, server-defined UTC date range on `field`, computed in this instance
|
|
|
623
787
|
|
|
624
788
|
---
|
|
625
789
|
|
|
790
|
+
## Custom Range Methods
|
|
791
|
+
|
|
792
|
+
Beyond the fixed `RangePreset` values above, six additional methods cover any custom day, span, rolling window, or hour-based filter — without touching `.range()`'s own logic. All of them behave exactly like `.range()`: they write a hard, non-client-overridable condition into `_serverConditions`, in this instance's timezone, and throw `QueryAggregateValidationError` on bad input.
|
|
793
|
+
|
|
794
|
+
> ⚠️ Only call **one** range method per field. If you call two on the same field (e.g. `.range()` then `.rangeCustom()` on `createdAt`), the later call simply overwrites the earlier one.
|
|
795
|
+
|
|
796
|
+
### `.rangeCustomDay(field: string, date: string)`
|
|
797
|
+
|
|
798
|
+
A single arbitrary local calendar date (`YYYY-MM-DD`) — for "show me everything from this specific day" rather than a relative preset.
|
|
799
|
+
|
|
800
|
+
```ts
|
|
801
|
+
.rangeCustomDay('createdAt', '2026-03-14')
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
### `.rangeBetween(field: string, custom: CustomDateRangeInput)`
|
|
805
|
+
|
|
806
|
+
An arbitrary inclusive local-date span — the classic "from / to" date-picker filter.
|
|
807
|
+
|
|
808
|
+
```ts
|
|
809
|
+
.rangeBetween('createdAt', { from: '2026-01-01', to: '2026-01-31' })
|
|
810
|
+
```
|
|
811
|
+
|
|
812
|
+
### `.rangeLastNDays(field: string, days: number)`
|
|
813
|
+
|
|
814
|
+
A rolling window of the last N whole calendar days, inclusive of today — a parametrized version of the built-in `last7Days`/`last30Days` presets.
|
|
815
|
+
|
|
816
|
+
```ts
|
|
817
|
+
.rangeLastNDays('createdAt', 14) // last 14 calendar days
|
|
818
|
+
```
|
|
819
|
+
|
|
820
|
+
### `.rangeLastNHours(field: string, hours: number)`
|
|
821
|
+
|
|
822
|
+
A rolling window of the last N hours, ending at the exact moment the query runs. Unlike the day-based methods, this uses raw UTC instants with no calendar-day snapping — ideal for "recent activity" widgets.
|
|
823
|
+
|
|
824
|
+
```ts
|
|
825
|
+
.rangeLastNHours('createdAt', 6) // activity in the last 6 hours
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
### `.rangeHours(field: string, custom: CustomHourRangeInput)`
|
|
829
|
+
|
|
830
|
+
An explicit hour-of-day window on a specific local date — e.g. filtering orders placed during business hours.
|
|
831
|
+
|
|
832
|
+
```ts
|
|
833
|
+
.rangeHours('createdAt', { date: '2026-03-14', fromHour: 9, toHour: 17 })
|
|
834
|
+
// toHour is exclusive; pass 24 for "through end of day"
|
|
835
|
+
```
|
|
836
|
+
|
|
837
|
+
### `.rangeCustom(field: string, custom: CustomDateTimeRangeInput)`
|
|
838
|
+
|
|
839
|
+
The most flexible option — an explicit absolute datetime window. Each of `from`/`to` accepts:
|
|
840
|
+
|
|
841
|
+
- `"YYYY-MM-DD"` → local midnight in this instance's timezone
|
|
842
|
+
- `"YYYY-MM-DDTHH:mm:ss[.sss]"` → local wall-clock time in this instance's timezone
|
|
843
|
+
- an offset-bearing ISO string (`...Z`, `...+06:00`) → treated as an absolute instant
|
|
844
|
+
|
|
845
|
+
```ts
|
|
846
|
+
.rangeCustom('createdAt', {
|
|
847
|
+
from: '2026-03-14T09:30:00', // local wall-clock
|
|
848
|
+
to: '2026-03-14T18:45:00',
|
|
849
|
+
})
|
|
850
|
+
|
|
851
|
+
// or mixed with an explicit UTC instant:
|
|
852
|
+
.rangeCustom('createdAt', { from: '2026-03-14T00:00:00Z', to: '2026-03-15T00:00:00Z' })
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
---
|
|
856
|
+
|
|
857
|
+
### `.excludeSoftDeleted(field = 'deletedAt')`
|
|
858
|
+
|
|
859
|
+
Convenience server-side condition excluding soft-deleted documents. Matches both `null` and a genuinely missing field, per MongoDB's equality semantics. Not client-overridable.
|
|
860
|
+
|
|
861
|
+
```ts
|
|
862
|
+
.excludeSoftDeleted() // defaults to 'deletedAt'
|
|
863
|
+
.excludeSoftDeleted('removedAt') // or a custom field name
|
|
864
|
+
```
|
|
865
|
+
|
|
866
|
+
---
|
|
867
|
+
|
|
868
|
+
### `.whereIf(condition, conditions)`
|
|
869
|
+
|
|
870
|
+
Applies `.where(conditions)` only when `condition` is truthy — avoids scattering `if` statements around a chained builder call.
|
|
871
|
+
|
|
872
|
+
```ts
|
|
873
|
+
.whereIf(req.query.vip === 'true', { tier: 'vip' })
|
|
874
|
+
.whereIf(req.self.role !== 'admin', { branchId: req.self.linkedTo })
|
|
875
|
+
```
|
|
876
|
+
|
|
877
|
+
---
|
|
878
|
+
|
|
626
879
|
### `.globalSearch(fields: string[])`
|
|
627
880
|
|
|
628
881
|
Identical behavior to `QueryFind`: case-insensitive `$or` regex search across the given fields when `?q=` is present (max 200 chars). Regex-escaped to prevent ReDoS. Fields are filtered against the allowlist first.
|
|
@@ -641,6 +894,8 @@ Parses `?sort=` (e.g. `-createdAt,name`), capped at 5 fields, dropping any field
|
|
|
641
894
|
.sort()
|
|
642
895
|
```
|
|
643
896
|
|
|
897
|
+
> `.paginateCursor()` (below) seeks on this same sort configuration, so call `.sort()` before it if you need a field other than the default `createdAt`.
|
|
898
|
+
|
|
644
899
|
---
|
|
645
900
|
|
|
646
901
|
### `.project(defaultProjection?: string | Record<string, 0 | 1>)`
|
|
@@ -684,6 +939,17 @@ Adds a `$lookup` (join) stage, optionally followed by `$unwind`.
|
|
|
684
939
|
|
|
685
940
|
---
|
|
686
941
|
|
|
942
|
+
### `.computeField(name: string, expression: unknown)`
|
|
943
|
+
|
|
944
|
+
Convenience wrapper over `.addStage()` for a single computed `$addFields` entry.
|
|
945
|
+
|
|
946
|
+
```ts
|
|
947
|
+
.computeField('margin', { $subtract: ['$price', '$cost'] })
|
|
948
|
+
// equivalent to: .addStage({ $addFields: { margin: { $subtract: ['$price', '$cost'] } } })
|
|
949
|
+
```
|
|
950
|
+
|
|
951
|
+
---
|
|
952
|
+
|
|
687
953
|
### `.addStage(stage: PipelineStage)`
|
|
688
954
|
|
|
689
955
|
Escape hatch for any other developer-authored stage: `$addFields`, `$group`, a post-join `$match`, a custom `$sort`, etc.
|
|
@@ -702,7 +968,7 @@ Escape hatch for any other developer-authored stage: `$addFields`, `$group`, a p
|
|
|
702
968
|
})
|
|
703
969
|
```
|
|
704
970
|
|
|
705
|
-
## Terminal
|
|
971
|
+
## Terminal & Utility Methods
|
|
706
972
|
|
|
707
973
|
### `.paginate(cachedTotal?: number)`
|
|
708
974
|
|
|
@@ -714,13 +980,136 @@ Executes the pipeline and returns `Promise<PaginatedResult<T>>`.
|
|
|
714
980
|
- If the requested `page` exceeds `totalPages`, page `1` is returned automatically (with the real `total`/`totalPages` still reported).
|
|
715
981
|
- `onSlowQuery` (if configured) fires with `{ elapsedMs, pipeline, sort, page, limit }` when the query exceeds `slowQueryThresholdMS`.
|
|
716
982
|
|
|
717
|
-
> **Note:** `$facet` buffers both branches in memory per query. For very large collections with expensive pre-facet stages (heavy `$lookup`/`$group` before pagination), pass `cachedTotal` on subsequent pages, or run count
|
|
983
|
+
> **Note:** `$facet` buffers both branches in memory per query. For very large collections with expensive pre-facet stages (heavy `$lookup`/`$group` before pagination), pass `cachedTotal` on subsequent pages, use `.paginateCursor()` instead, or run `.count()`/data as two separate calls.
|
|
718
984
|
|
|
719
985
|
```ts
|
|
720
986
|
const page1 = await builder.paginate();
|
|
721
987
|
const page2 = await builder.paginate(page1.total); // skips re-counting
|
|
722
988
|
```
|
|
723
989
|
|
|
990
|
+
---
|
|
991
|
+
|
|
992
|
+
### `.paginateCursor(opts?: CursorPaginateOptions)`
|
|
993
|
+
|
|
994
|
+
Keyset ("seek") pagination — scales far better than `.paginate()`'s `$skip` on deep pages of large collections, at the cost of not supporting "jump to page N". Seeks on whatever field `.sort()` resolved to (falls back to `createdAt` if `.sort()` wasn't called), using `_id` as a stable tiebreaker.
|
|
995
|
+
|
|
996
|
+
```ts
|
|
997
|
+
interface CursorPaginateOptions {
|
|
998
|
+
cursor?: string; // opaque cursor from a previous page's nextCursor
|
|
999
|
+
limit?: number; // overrides ?limit=, still capped by maxLimit
|
|
1000
|
+
}
|
|
1001
|
+
|
|
1002
|
+
interface CursorPaginatedResult<T> {
|
|
1003
|
+
data: T[];
|
|
1004
|
+
limit: number;
|
|
1005
|
+
nextCursor: string | null; // pass this back in as `cursor` for the next page
|
|
1006
|
+
hasNextPage: boolean;
|
|
1007
|
+
}
|
|
1008
|
+
```
|
|
1009
|
+
|
|
1010
|
+
```ts
|
|
1011
|
+
const p1 = await builder.sort().paginateCursor({ limit: 20 });
|
|
1012
|
+
const p2 = await builder.paginateCursor({ cursor: p1.nextCursor!, limit: 20 });
|
|
1013
|
+
// hasNextPage: false / nextCursor: null means you've reached the end
|
|
1014
|
+
```
|
|
1015
|
+
|
|
1016
|
+
Great fit for infinite-scroll feeds and large-export pagination; not a drop-in replacement where the UI needs page numbers.
|
|
1017
|
+
|
|
1018
|
+
---
|
|
1019
|
+
|
|
1020
|
+
### `.count()`
|
|
1021
|
+
|
|
1022
|
+
Returns just the matching document count — cheaper than `.paginate()` when you don't need the data page. Ignores `.project()`/`.sort()`.
|
|
1023
|
+
|
|
1024
|
+
```ts
|
|
1025
|
+
const total = await builder.count();
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
---
|
|
1029
|
+
|
|
1030
|
+
### `.distinct(field: string)`
|
|
1031
|
+
|
|
1032
|
+
Returns the distinct values of `field` under the current `.filter()`/`.where()`/range conditions.
|
|
1033
|
+
|
|
1034
|
+
```ts
|
|
1035
|
+
const statuses = await builder.distinct('status');
|
|
1036
|
+
// e.g. ['PENDING', 'PAID', 'CANCELLED']
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
---
|
|
1040
|
+
|
|
1041
|
+
### `.stats(specs: StatSpec[])`
|
|
1042
|
+
|
|
1043
|
+
Computes one or more aggregate metrics — `sum`, `avg`, `min`, `max`, `count` — in a **single round trip**. Ideal for dashboard totals. Ignores `.project()`/`.sort()`/pagination.
|
|
1044
|
+
|
|
1045
|
+
```ts
|
|
1046
|
+
interface StatSpec {
|
|
1047
|
+
name: string;
|
|
1048
|
+
op: 'sum' | 'avg' | 'min' | 'max' | 'count';
|
|
1049
|
+
field?: string; // required for every op except 'count'
|
|
1050
|
+
}
|
|
1051
|
+
```
|
|
1052
|
+
|
|
1053
|
+
```ts
|
|
1054
|
+
const totals = await builder.stats([
|
|
1055
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
1056
|
+
{ name: 'avgOrder', op: 'avg', field: 'total' },
|
|
1057
|
+
{ name: 'orders', op: 'count' },
|
|
1058
|
+
]);
|
|
1059
|
+
// { revenue: 48213, avgOrder: 62.1, orders: 776 }
|
|
1060
|
+
```
|
|
1061
|
+
|
|
1062
|
+
---
|
|
1063
|
+
|
|
1064
|
+
### `.stream()`
|
|
1065
|
+
|
|
1066
|
+
Returns a Mongoose `AggregationCursor` — async-iterable, no buffering of the full result set in memory. Use for large exports (CSV generation, bulk processing).
|
|
1067
|
+
|
|
1068
|
+
```ts
|
|
1069
|
+
for await (const doc of builder.stream()) {
|
|
1070
|
+
csvWriter.write(doc);
|
|
1071
|
+
}
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
Ignores `page`/`limit`; add your own `$limit` via `.addStage()` if you want a hard cap.
|
|
1075
|
+
|
|
1076
|
+
---
|
|
1077
|
+
|
|
1078
|
+
### `.explain(verbosity?)`
|
|
1079
|
+
|
|
1080
|
+
Runs the built pipeline through Mongoose's `.explain()` — for debugging slow queries and verifying index usage. `verbosity` is `'queryPlanner'` (default), `'executionStats'`, or `'allPlansExecution'`.
|
|
1081
|
+
|
|
1082
|
+
```ts
|
|
1083
|
+
const plan = await builder.explain('executionStats');
|
|
1084
|
+
```
|
|
1085
|
+
|
|
1086
|
+
> Development/ops tool only — never call this in a production request path.
|
|
1087
|
+
|
|
1088
|
+
---
|
|
1089
|
+
|
|
1090
|
+
### `.clone()`
|
|
1091
|
+
|
|
1092
|
+
Deep-copies the current builder state (filters, sort, projection, stages) into a new, independent `QueryAggregate` instance. Handy for branching one shared base query into e.g. both `.paginate()` and `.stats()` without rebuilding the filters twice.
|
|
1093
|
+
|
|
1094
|
+
```ts
|
|
1095
|
+
const base = builder.filter().sort().project('name total createdAt');
|
|
1096
|
+
|
|
1097
|
+
const [page, totals] = await Promise.all([
|
|
1098
|
+
base.clone().paginate(),
|
|
1099
|
+
base.clone().stats([{ name: 'revenue', op: 'sum', field: 'total' }]),
|
|
1100
|
+
]);
|
|
1101
|
+
```
|
|
1102
|
+
|
|
1103
|
+
---
|
|
1104
|
+
|
|
1105
|
+
### `.debugPipeline()`
|
|
1106
|
+
|
|
1107
|
+
Returns the fully-built pipeline (`PipelineStage[]`) without executing it — for logging, snapshot tests, or sanity-checking what will actually run.
|
|
1108
|
+
|
|
1109
|
+
```ts
|
|
1110
|
+
console.log(builder.debugPipeline());
|
|
1111
|
+
```
|
|
1112
|
+
|
|
724
1113
|
## Recipes
|
|
725
1114
|
|
|
726
1115
|
**Join + post-join filter + group + paginate:**
|
|
@@ -761,6 +1150,149 @@ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
|
761
1150
|
.paginate();
|
|
762
1151
|
```
|
|
763
1152
|
|
|
1153
|
+
**Custom hour-of-day window (business hours report):**
|
|
1154
|
+
|
|
1155
|
+
```ts
|
|
1156
|
+
const result = await new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1157
|
+
.allowFields(['status'])
|
|
1158
|
+
.where({ branchId: req.self.linkedTo })
|
|
1159
|
+
.rangeHours('createdAt', {
|
|
1160
|
+
date: req.query.day as string,
|
|
1161
|
+
fromHour: 9,
|
|
1162
|
+
toHour: 21,
|
|
1163
|
+
})
|
|
1164
|
+
.filter()
|
|
1165
|
+
.sort()
|
|
1166
|
+
.paginate();
|
|
1167
|
+
```
|
|
1168
|
+
|
|
1169
|
+
**Dashboard: page + totals in parallel, off one shared base:**
|
|
1170
|
+
|
|
1171
|
+
```ts
|
|
1172
|
+
const base = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1173
|
+
.allowFields(['status', 'branchId', 'createdAt', 'total'])
|
|
1174
|
+
.dateFields(['createdAt'])
|
|
1175
|
+
.where({ branchId: req.self.linkedTo })
|
|
1176
|
+
.excludeSoftDeleted()
|
|
1177
|
+
.filter()
|
|
1178
|
+
.sort()
|
|
1179
|
+
.project('status createdAt total');
|
|
1180
|
+
|
|
1181
|
+
const [page, totals] = await Promise.all([
|
|
1182
|
+
base.clone().paginate(),
|
|
1183
|
+
base.clone().stats([
|
|
1184
|
+
{ name: 'revenue', op: 'sum', field: 'total' },
|
|
1185
|
+
{ name: 'orders', op: 'count' },
|
|
1186
|
+
]),
|
|
1187
|
+
]);
|
|
1188
|
+
```
|
|
1189
|
+
|
|
1190
|
+
**Infinite scroll with keyset pagination:**
|
|
1191
|
+
|
|
1192
|
+
```ts
|
|
1193
|
+
const builder = new QueryAggregate(PostModel, req.query, { timezone })
|
|
1194
|
+
.allowFields(['authorId', 'createdAt'])
|
|
1195
|
+
.where({ published: true })
|
|
1196
|
+
.filter()
|
|
1197
|
+
.sort();
|
|
1198
|
+
|
|
1199
|
+
const page = await builder.paginateCursor({
|
|
1200
|
+
cursor: req.query.cursor as string | undefined,
|
|
1201
|
+
limit: 20,
|
|
1202
|
+
});
|
|
1203
|
+
```
|
|
1204
|
+
|
|
1205
|
+
**Streaming a large CSV export:**
|
|
1206
|
+
|
|
1207
|
+
```ts
|
|
1208
|
+
const builder = new QueryAggregate(OrderModel, req.query, { timezone })
|
|
1209
|
+
.allowFields(['status', 'createdAt'])
|
|
1210
|
+
.where({ branchId: req.self.linkedTo })
|
|
1211
|
+
.range('createdAt', 'thisMonth')
|
|
1212
|
+
.filter()
|
|
1213
|
+
.project('status createdAt total');
|
|
1214
|
+
|
|
1215
|
+
res.setHeader('Content-Type', 'text/csv');
|
|
1216
|
+
for await (const row of builder.stream()) {
|
|
1217
|
+
res.write(`${row.status},${row.createdAt.toISOString()},${row.total}\n`);
|
|
1218
|
+
}
|
|
1219
|
+
res.end();
|
|
1220
|
+
```
|
|
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
|
+
|
|
764
1296
|
**Correlated sub-pipeline `$lookup` (needs `let`):**
|
|
765
1297
|
|
|
766
1298
|
The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipelines. For that case, drop to `.addStage()` directly:
|
|
@@ -779,44 +1311,142 @@ The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipeli
|
|
|
779
1311
|
})
|
|
780
1312
|
```
|
|
781
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
|
+
|
|
782
1408
|
## Pipeline Stage Ordering
|
|
783
1409
|
|
|
784
1410
|
The final pipeline is always assembled in this fixed order:
|
|
785
1411
|
|
|
786
1412
|
```
|
|
787
|
-
$match (from .where() + .filter() + .range() + .globalSearch(), merged via $and)
|
|
1413
|
+
$match (from .where() + .filter() + .range()/rangeXxx() + .globalSearch(), merged via $and)
|
|
788
1414
|
↓
|
|
789
|
-
[.lookup() / .addStage() calls, in the order you called them]
|
|
1415
|
+
[.lookup() / .addStage() / .computeField() calls, in the order you called them]
|
|
790
1416
|
↓
|
|
791
1417
|
$project (from .project(), if set)
|
|
792
1418
|
↓
|
|
793
1419
|
$sort (from .sort())
|
|
794
1420
|
↓
|
|
795
|
-
[
|
|
1421
|
+
[terminal stage: $skip/$limit, $facet, keyset $match + $limit, or $count/$group — added internally by the method you call]
|
|
796
1422
|
```
|
|
797
1423
|
|
|
798
1424
|
Implications:
|
|
799
1425
|
|
|
800
|
-
- Anything added via `.addStage()` runs **after** the base filter match and **before** projection/sort.
|
|
1426
|
+
- Anything added via `.addStage()`/`.computeField()` runs **after** the base filter match and **before** projection/sort.
|
|
801
1427
|
- If you `$group`/reshape documents, do it before `.project()` — or skip `.project()` and use `.addStage({ $project: {...} })` for full control over the new shape.
|
|
802
1428
|
- If you add your own `$sort` via `.addStage()` _and_ also call `.sort()`, both stages are included (the builder's `.sort()` stage is always appended last in the base pipeline) — harmless but redundant. Prefer one or the other.
|
|
1429
|
+
- `.count()`, `.distinct()`, and `.stats()` intentionally skip `$project`/`$sort` — they only need `$match` + your `.lookup()`/`.addStage()` stages before their own terminal `$count`/`$group`.
|
|
1430
|
+
- `.paginateCursor()` builds its own `$match`/`$sort`/`$limit` tail (the keyset condition), separate from `.paginate()`'s `$facet` tail.
|
|
803
1431
|
|
|
804
1432
|
## Security
|
|
805
1433
|
|
|
806
|
-
| Protection | Detail
|
|
807
|
-
| --------------------------------- |
|
|
808
|
-
| **NoSQL injection** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()`
|
|
809
|
-
| **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input
|
|
810
|
-
| **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines
|
|
811
|
-
| **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation
|
|
812
|
-
| **Oversized search** | `?q=` capped at 200 characters
|
|
813
|
-
| **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`)
|
|
814
|
-
| **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100)
|
|
815
|
-
| **Sort abuse** | Sort fields hard-capped at 5
|
|
816
|
-
| **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability
|
|
817
|
-
| **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query
|
|
818
|
-
| **
|
|
819
|
-
| **
|
|
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 |
|
|
820
1450
|
|
|
821
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.
|
|
822
1452
|
|
|
@@ -833,6 +1463,13 @@ import {
|
|
|
833
1463
|
SlowQueryInfo,
|
|
834
1464
|
QueryParams,
|
|
835
1465
|
PaginatedResult,
|
|
1466
|
+
CustomDayInput,
|
|
1467
|
+
CustomDateRangeInput,
|
|
1468
|
+
CustomHourRangeInput,
|
|
1469
|
+
CustomDateTimeRangeInput,
|
|
1470
|
+
CursorPaginateOptions,
|
|
1471
|
+
CursorPaginatedResult,
|
|
1472
|
+
StatSpec,
|
|
836
1473
|
} from 'mongoose-query-find';
|
|
837
1474
|
```
|
|
838
1475
|
|
|
@@ -872,4 +1509,58 @@ interface SlowQueryInfo {
|
|
|
872
1509
|
page: number;
|
|
873
1510
|
limit: number;
|
|
874
1511
|
}
|
|
1512
|
+
|
|
1513
|
+
// ── Custom range types ──────────────────────────────────────────────────────
|
|
1514
|
+
|
|
1515
|
+
type CustomDayInput = string; // "YYYY-MM-DD"
|
|
1516
|
+
|
|
1517
|
+
interface CustomDateRangeInput {
|
|
1518
|
+
from: string; // "YYYY-MM-DD"
|
|
1519
|
+
to: string; // "YYYY-MM-DD"
|
|
1520
|
+
}
|
|
1521
|
+
|
|
1522
|
+
interface CustomHourRangeInput {
|
|
1523
|
+
date: string; // "YYYY-MM-DD"
|
|
1524
|
+
fromHour: number; // 0–24
|
|
1525
|
+
toHour: number; // 0–24, exclusive, must be > fromHour
|
|
1526
|
+
}
|
|
1527
|
+
|
|
1528
|
+
interface CustomDateTimeRangeInput {
|
|
1529
|
+
from: string; // "YYYY-MM-DD" | "YYYY-MM-DDTHH:mm:ss[.sss]" | offset-bearing ISO string
|
|
1530
|
+
to: string;
|
|
1531
|
+
}
|
|
1532
|
+
|
|
1533
|
+
// ── Advanced-feature types ──────────────────────────────────────────────────
|
|
1534
|
+
|
|
1535
|
+
interface CursorPaginateOptions {
|
|
1536
|
+
cursor?: string;
|
|
1537
|
+
limit?: number;
|
|
1538
|
+
}
|
|
1539
|
+
|
|
1540
|
+
interface CursorPaginatedResult<T> {
|
|
1541
|
+
data: T[];
|
|
1542
|
+
limit: number;
|
|
1543
|
+
nextCursor: string | null;
|
|
1544
|
+
hasNextPage: boolean;
|
|
1545
|
+
}
|
|
1546
|
+
|
|
1547
|
+
interface StatSpec {
|
|
1548
|
+
name: string;
|
|
1549
|
+
op: 'sum' | 'avg' | 'min' | 'max' | 'count';
|
|
1550
|
+
field?: string;
|
|
1551
|
+
}
|
|
875
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)
|