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.
Files changed (2) hide show
  1. package/README.md +379 -88
  2. 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>` | A Mongoose query, e.g. `Model.find()` |
143
- | `queryString` | `QueryParams` | The parsed URL query object, e.g. `req.query` |
144
- | `options` | `QueryFindOptions` _(optional)_ | Configuration options (see [Options](#options) below) |
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 | Description |
149
- | ----------------------- | ----------------------------------------- | ------- | -------------------------------------------------------------------------- |
150
- | `maxTimeMS` | `number` | `5000` | Max milliseconds MongoDB may spend on each query. Pass `0` to disable. |
151
- | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
152
- | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
153
- | `lean` | `boolean` | `true` | Whether `.find()` calls `.lean()` for faster plain-object reads. |
154
- | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
155
- | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a client-supplied value. |
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` | Page number (default: `1`, min: `1`) |
338
- | `limit` | `?limit=25` | Documents per page (default: `10`, max: `100`) |
339
- | `sort` | `?sort=-createdAt,name` | Sort fields; prefix `-` for descending (max: 5 fields) |
340
- | `fields` | `?fields=name,email` | Comma-separated fields to include in the response |
341
- | `q` | `?q=john` | Global search term (max: 200 chars) |
342
- | _(any key)_ | `?role=admin&age[gte]=18` | Field-level filters processed by `.filter()` |
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; // default: 5000
431
- slowQueryThresholdMS?: number; // default: maxTimeMS
432
- maxLimit?: number; // default: 100
433
- lean?: boolean; // default: true
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** | Allowlist enforced on filters, sort, and projection via `.allowFields()` |
454
- | **Banned operators** | `$where`, `$expr`, `$function`, and others are rejected recursively at any nesting depth |
455
- | **ReDoS** | Search terms are regex-escaped before compilation |
456
- | **Oversized search** | `?q=` capped at 200 characters |
457
- | **Deep nesting DoS** | Filter object nesting capped at depth 5 |
458
- | **Page size DoS** | `limit` hard-capped at 100 |
459
- | **Sort abuse** | Sort fields hard-capped at 5 |
460
- | **Runaway queries** | `maxTimeMS` applied to both count and find (default: 5s) |
461
- | **Sensitive field leakage** | `?fields=` projection stripped against allowlist |
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 | Use |
506
- | ---------------------------------------------------------------- | ------------------ |
507
- | Simple filter/sort/paginate on one collection | `QueryFind` |
508
- | Joining another collection (`$lookup`) | `QueryAggregate` |
509
- | Grouping / rollups / computed fields (`$group`, `$addFields`) | `QueryAggregate` |
510
- | Client filters need to respect the caller's local timezone | `QueryAggregate` |
511
- | A custom day / date span / rolling window / hour-of-day filter | `QueryAggregate` |
512
- | Dashboard totals (sum/avg/count) without fetching a page | `QueryAggregate` |
513
- | Very large collections where `$skip` pagination gets slow | `QueryAggregate` |
514
- | Streaming a large export without buffering it in memory | `QueryAggregate` |
515
- | You need a custom developer-defined pipeline stage | `QueryAggregate` |
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>` | A Mongoose model |
567
- | `queryString` | `QueryParams` | Parsed URL query object, e.g. `req.query` |
568
- | `options` | `QueryAggregateOptions` | Configuration options (see below), all optional |
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` | `string` | `'Asia/Dhaka'` | IANA timezone for interpreting client-supplied local dates. Invalid values fall back to the default (validated once at construction, never throws mid-query). |
575
- | `maxTimeMS` | `number` | `5000` | Max time MongoDB may spend per query. `0` disables. |
576
- | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
577
- | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
578
- | `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` — enable for large sort/group pipelines. |
579
- | `weekStartsOn` | `0–6` | `6` (Saturday) | Used by `.range('thisWeek')`. |
580
- | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
581
- | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a value (bad nesting, non-plain value). |
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` | Collection name (not the model name) to join against. |
819
- | `as` | `string` | Output array field name. |
820
- | `localField` | `string?` | Local join field. |
821
- | `foreignField` | `string?` | Foreign join field. |
822
- | `pipeline` | `PipelineStage[]?` | Sub-pipeline form of `$lookup`, for complex/correlated joins. Cannot contain `$out`/`$merge`. |
823
- | `single` | `boolean?` | When `true`, `$unwind`s the joined array (`preserveNullAndEmptyArrays: true`) so `as` becomes a single object instead of an array. |
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; // overrides ?limit=, still capped by maxLimit
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', { date: req.query.day as string, fromHour: 9, toHour: 21 })
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** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()` |
1160
- | **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input |
1161
- | **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines |
1162
- | **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation |
1163
- | **Oversized search** | `?q=` capped at 200 characters |
1164
- | **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`) |
1165
- | **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100), including in `.paginateCursor()` |
1166
- | **Sort abuse** | Sort fields hard-capped at 5 |
1167
- | **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability |
1168
- | **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query |
1169
- | **Bad custom-range input** | `rangeCustomDay`/`rangeBetween`/`rangeLastNDays`/`rangeLastNHours`/`rangeHours`/`rangeCustom` all throw `QueryAggregateValidationError` on malformed dates, non-positive counts, or invalid hour bounds — never silently produce a wrong range |
1170
- | **Server condition override** | `.where()` / `.range()` / every custom range method are merged last via `$and` — URL params can never override them |
1171
- | **Tampered cursors** | `.paginateCursor()` cursors are opaque base64url-encoded JSON; a malformed cursor throws `QueryAggregateValidationError` rather than silently misbehaving |
1172
- | **Untrusted `.addStage()` input** | Not sanitized/allowlisted by design — documented as a trusted, developer-authored-only escape hatch |
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; // "YYYY-MM-DD"
1519
+ to: string; // "YYYY-MM-DD"
1243
1520
  }
1244
1521
 
1245
1522
  interface CustomHourRangeInput {
1246
- date: string; // "YYYY-MM-DD"
1523
+ date: string; // "YYYY-MM-DD"
1247
1524
  fromHour: number; // 0–24
1248
- toHour: number; // 0–24, exclusive, must be > fromHour
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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mongoose-query-find",
3
- "version": "3.2.0",
3
+ "version": "3.3.0",
4
4
  "private": false,
5
5
  "license": "MIT",
6
6
  "files": [