mongoose-query-find 4.0.1 → 4.0.2

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 +1619 -0
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,3 +1,1622 @@
1
+ # mongoose-query-find
2
+
3
+ [![npm version](https://img.shields.io/npm/v/mongoose-query-find)](https://www.npmjs.com/package/mongoose-query-find)
4
+ [![license](https://img.shields.io/npm/l/mongoose-query-find)](https://github.com/jsdev-robin/mongoose-query-find/blob/main/LICENSE)
5
+ [![mongoose peer](https://img.shields.io/badge/mongoose-%5E8%20%7C%7C%20%5E9-brightgreen)](https://mongoosejs.com)
6
+
7
+ Three fluent, chainable, allowlisted query builders for Mongoose — **`QueryFind`** for simple `Model.find()` queries, **`QueryAggregate`** for anything that needs joins, grouping, timezone-aware date filtering, or advanced pagination, and **`QueryAnalytics`** for dashboards and reporting (time series, cohorts, funnels, sessionization, and more). All three are driven directly from URL query parameters with zero boilerplate.
8
+
9
+ ---
10
+
11
+ ## Table of Contents
12
+
13
+ **QueryFind**
14
+
15
+ - [Installation](#installation)
16
+ - [Quick Start](#quick-start)
17
+ - [Constructor](#constructor)
18
+ - [Builder Methods](#builder-methods)
19
+ - [.allowFields()](#allowfieldsfields-string)
20
+ - [.filter()](#filter)
21
+ - [.where()](#whereconditions)
22
+ - [.globalSearch()](#globalsearchfields-string)
23
+ - [.sort()](#sort)
24
+ - [.limitFields()](#limitfieldsdefaultfields-string)
25
+ - [.populate()](#populatepath-string--populateoptions-select-string)
26
+ - [Terminal Method](#terminal-method)
27
+ - [.paginate()](#paginate)
28
+ - [Query Parameter Reference](#query-parameter-reference)
29
+ - [Full Example (Express)](#full-example-express)
30
+ - [More Examples](#more-examples)
31
+ - [TypeScript Types](#typescript-types)
32
+ - [Security](#security)
33
+ - [Links](#links)
34
+ - [License](#license)
35
+
36
+ **QueryAggregate**
37
+
38
+ - [Overview](#queryaggregate-overview)
39
+ - [When to use QueryAggregate vs QueryFind](#when-to-use-queryaggregate-vs-queryfind)
40
+ - [Installation](#installation-1)
41
+ - [Quick Start](#quick-start-1)
42
+ - [Constructor & Options](#constructor--options-1)
43
+ - [Timezone Handling](#timezone-handling)
44
+ - [Builder Methods](#builder-methods-1)
45
+ - [.allowFields()](#allowfieldsfields-string-1)
46
+ - [.dateFields()](#datefieldsfields-string)
47
+ - [.objectIdFields()](#objectidfieldsfields-string)
48
+ - [.filter()](#filter-1)
49
+ - [.where()](#whereconditions-1)
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)
60
+ - [.globalSearch()](#globalsearchfields-string-1)
61
+ - [.sort()](#sort-1)
62
+ - [.project()](#projectdefaultprojection-string--recordstring-0--1)
63
+ - [.lookup()](#lookupopts-lookupoptions)
64
+ - [.computeField()](#computefieldname-string-expression-unknown)
65
+ - [.addStage()](#addstagestage-pipelinestage)
66
+ - [Terminal & Utility Methods](#terminal--utility-methods)
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)
76
+ - [Recipes](#recipes)
77
+ - [Pipeline Stage Ordering](#pipeline-stage-ordering)
78
+ - [Security](#security-1)
79
+ - [TypeScript Types](#typescript-types-1)
80
+ - [Links](#links-1)
81
+ - [License](#license-1)
82
+
83
+ **QueryAnalytics**
84
+
85
+ - [Overview](#queryanalytics-overview)
86
+ - [When to use QueryAnalytics](#when-to-use-queryanalytics)
87
+ - [Installation](#installation-2)
88
+ - [Quick Start](#quick-start-2)
89
+ - [Constructor & Options](#constructor--options-2)
90
+ - [Base Filter Methods](#base-filter-methods)
91
+ - [.match()](#matchconditions)
92
+ - [.dateRange()](#daterangefield-string-range--from-string-to-string-)
93
+ - [.addStage()](#addstagestage-pipelinestage-1)
94
+ - [.clone()](#clone-1)
95
+ - [Time Series](#time-series)
96
+ - [.timeSeries()](#timeseriesopts)
97
+ - [.cumulativeSeries()](#cumulativeseriesopts)
98
+ - [Comparisons & Breakdowns](#comparisons--breakdowns)
99
+ - [.compare()](#compareopts)
100
+ - [.breakdown()](#breakdownfield-metrics-opts)
101
+ - [.rankedBreakdown()](#rankedbreakdownfield-metrics-opts)
102
+ - [.multiBreakdown()](#multibreakdownfields-metrics-opts)
103
+ - [Funnels & Cohorts](#funnels--cohorts)
104
+ - [.funnel()](#funnelsteps)
105
+ - [.cohortRetention()](#cohortretentionopts)
106
+ - [.sessionize()](#sessionizeopts)
107
+ - [Statistics](#statistics)
108
+ - [.percentiles()](#percentilesfield-ps)
109
+ - [.stdDevOutliers()](#stddevoutliersfield-opts)
110
+ - [.metrics()](#metricsspecs)
111
+ - [Post-Processing Helpers (static)](#post-processing-helpers-static)
112
+ - [QueryAnalytics.movingAverage()](#queryanalyticsmovingaverage)
113
+ - [QueryAnalytics.trend()](#queryanalyticstrend)
114
+ - [QueryAnalytics.forecast()](#queryanalyticsforecast)
115
+ - [.heatmap()](#heatmapdatefield-valuefield)
116
+ - [Live Updates](#live-updates)
117
+ - [.watch()](#watchonchange-opts)
118
+ - [Export & Batch Helpers (static)](#export--batch-helpers-static)
119
+ - [QueryAnalytics.toCSV() / toNDJSON()](#queryanalyticstocsv--tondjson)
120
+ - [QueryAnalytics.dashboard()](#queryanalyticsdashboard)
121
+ - [QueryAnalytics.clearCache()](#queryanalyticsclearcache)
122
+ - [Recipes](#recipes-1)
123
+ - [Security](#security-2)
124
+ - [TypeScript Types](#typescript-types-2)
125
+ - [Links](#links-2)
126
+ - [License](#license-2)
127
+
128
+ ---
129
+
130
+ ## Installation
131
+
132
+ ```bash
133
+ npm install mongoose-query-find
134
+ ```
135
+
136
+ ```bash
137
+ yarn add mongoose-query-find
138
+ ```
139
+
140
+ ```bash
141
+ pnpm add mongoose-query-find
142
+ ```
143
+
144
+ > **Peer dependency:** requires `mongoose ^8` or `mongoose ^9` installed in your project.
145
+
146
+ ---
147
+
148
+ ## Quick Start
149
+
150
+ ```ts
151
+ import { queryFind } from 'mongoose-query-find';
152
+ import UserModel from './models/user';
153
+
154
+ const result = await queryFind(UserModel.find(), req.query)
155
+ .allowFields(['name', 'email', 'role', 'createdAt'])
156
+ .where({ deletedAt: null })
157
+ .filter()
158
+ .globalSearch(['name', 'email'])
159
+ .sort()
160
+ .limitFields('-password -__v')
161
+ .paginate();
162
+ ```
163
+
164
+ `result` will look like:
165
+
166
+ ```json
167
+ {
168
+ "data": [...],
169
+ "total": 84,
170
+ "page": 2,
171
+ "totalPages": 9,
172
+ "limit": 10,
173
+ "hasNextPage": true,
174
+ "hasPrevPage": true
175
+ }
176
+ ```
177
+
178
+ ---
179
+
180
+ ## Constructor
181
+
182
+ ```ts
183
+ new QueryFind(query, queryString, options?);
184
+ // or use the factory function (recommended):
185
+ queryFind(query, queryString, options?);
186
+ ```
187
+
188
+ | Parameter | Type | Description |
189
+ | ------------- | ----------------------------------- | ----------------------------------------------------- |
190
+ | `query` | `Query<TRawDocType[], TRawDocType>` | A Mongoose query, e.g. `Model.find()` |
191
+ | `queryString` | `QueryParams` | The parsed URL query object, e.g. `req.query` |
192
+ | `options` | `QueryFindOptions` _(optional)_ | Configuration options (see [Options](#options) below) |
193
+
194
+ ### Options
195
+
196
+ | Option | Type | Default | Description |
197
+ | ---------------------- | ---------------------------------------- | ----------- | ---------------------------------------------------------------------- |
198
+ | `maxTimeMS` | `number` | `5000` | Max milliseconds MongoDB may spend on each query. Pass `0` to disable. |
199
+ | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
200
+ | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
201
+ | `lean` | `boolean` | `true` | Whether `.find()` calls `.lean()` for faster plain-object reads. |
202
+ | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
203
+ | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a client-supplied value. |
204
+
205
+ ---
206
+
207
+ ## Builder Methods
208
+
209
+ All builder methods return `this` and are fully chainable. The recommended call order is:
210
+
211
+ ```
212
+ allowFields → where → filter → globalSearch → sort → limitFields → populate → paginate
213
+ ```
214
+
215
+ ---
216
+
217
+ ### `.allowFields(fields: string[])`
218
+
219
+ Declares which fields may appear in URL filters, sort parameters, and field projections. Acts as an allowlist — any field not listed is silently stripped from client input before it reaches MongoDB.
220
+
221
+ **Call this before `.filter()`, `.sort()`, and `.limitFields()`.**
222
+
223
+ ```ts
224
+ .allowFields(['name', 'email', 'role', 'createdAt'])
225
+ ```
226
+
227
+ ---
228
+
229
+ ### `.filter()`
230
+
231
+ Parses the URL query string into a Mongoose filter. Automatically:
232
+
233
+ - Strips reserved keys (`page`, `limit`, `sort`, `fields`, `q`)
234
+ - Converts comparison operator names to MongoDB `$` syntax (`gt` → `$gt`, `lte` → `$lte`, etc.)
235
+ - Recursively coerces string booleans to real booleans (`"true"` → `true`, `"false"` → `false`)
236
+ - Coerces date-like strings to `Date` instances for fields named `createdAt`, `updatedAt`, `deletedAt`, `date`, `birthDate`, or `expiresAt`
237
+ - Recursively validates and rejects banned operators (`$where`, `$expr`, `$function`, etc.)
238
+
239
+ **Supported operators:** `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`
240
+
241
+ ```
242
+ GET /users?age[gte]=18&isActive=true&role=admin
243
+ ```
244
+
245
+ ```ts
246
+ .filter()
247
+ // → { age: { $gte: 18 }, isActive: true, role: 'admin' }
248
+ ```
249
+
250
+ ---
251
+
252
+ ### `.where(conditions)`
253
+
254
+ Applies mandatory server-side conditions that the URL **cannot override**. Use this for multi-tenancy, soft-delete exclusion, and any security-critical constraints.
255
+
256
+ ```ts
257
+ .where({ orgId: req.user.orgId, deletedAt: null })
258
+ ```
259
+
260
+ > `.where()` always wins — conditions are merged after `.filter()` and will overwrite any conflicting URL params.
261
+
262
+ ---
263
+
264
+ ### `.globalSearch(fields: string[])`
265
+
266
+ Adds a case-insensitive `$or` regex search across the specified fields when the `?q=` query parameter is present. If `q` is absent or exceeds 200 characters, this method is a no-op.
267
+
268
+ Search terms are regex-escaped to prevent ReDoS attacks.
269
+
270
+ ```
271
+ GET /users?q=john
272
+ ```
273
+
274
+ ```ts
275
+ .globalSearch(['name', 'email'])
276
+ // → { $or: [{ name: /john/i }, { email: /john/i }] }
277
+ ```
278
+
279
+ If a `$or` clause already exists in the filter (e.g. from `.filter()`), both are safely merged under `$and`.
280
+
281
+ ---
282
+
283
+ ### `.sort()`
284
+
285
+ Applies sort order from the `?sort=` query parameter. Prefix a field with `-` for descending order. Multiple fields are comma-separated, capped at 5 fields.
286
+
287
+ ```
288
+ GET /users?sort=-createdAt,name
289
+ ```
290
+
291
+ ```ts
292
+ .sort()
293
+ // → sorts by createdAt DESC, then name ASC
294
+ ```
295
+
296
+ Defaults to `{ createdAt: -1 }` when the `sort` param is absent. Fields not in the allowlist are silently skipped.
297
+
298
+ ---
299
+
300
+ ### `.limitFields(defaultFields?: string)`
301
+
302
+ Controls which fields are returned (projection). Uses the `?fields=` query param when present, otherwise falls back to `defaultFields`.
303
+
304
+ Fields requested via `?fields=` are filtered against the allowlist — clients cannot project sensitive fields like `password` or `resetToken`.
305
+
306
+ **Priority order:**
307
+
308
+ 1. `?fields=` query param — always wins when present (allowlist-filtered)
309
+ 2. `defaultFields` argument — used as fallback when no query param
310
+ 3. No projection when both are absent (all fields returned)
311
+
312
+ ```
313
+ GET /users?fields=name,email,role
314
+ ```
315
+
316
+ ```ts
317
+ .limitFields('-password -__v')
318
+ // With ?fields=name,email,role → selects only name, email, role
319
+ // Without ?fields → excludes password and __v
320
+ ```
321
+
322
+ ---
323
+
324
+ ### `.populate(path: string | PopulateOptions, select?: string)`
325
+
326
+ Registers a populate directive. Chainable — each call appends to the internal list. All registered populates are applied inside `paginate()`.
327
+
328
+ Accepts the same arguments as Mongoose's own `.populate()`:
329
+
330
+ ```ts
331
+ // Plain path string
332
+ .populate('author')
333
+
334
+ // Path + select string
335
+ .populate('author', 'name email')
336
+
337
+ // Full PopulateOptions object
338
+ .populate({ path: 'comments', select: 'text createdAt', match: { visible: true } })
339
+
340
+ // Multiple calls — fully chainable
341
+ .populate('author')
342
+ .populate({ path: 'comments', select: 'text createdAt' })
343
+ ```
344
+
345
+ ---
346
+
347
+ ## Terminal Method
348
+
349
+ ### `.paginate()`
350
+
351
+ Executes the query and returns a `Promise<PaginatedResult<T>>`.
352
+
353
+ - `countDocuments` and `find` run **in parallel** via `Promise.all` (saves one network round-trip).
354
+ - Uses `estimatedDocumentCount` as a fast-path when no filter is applied (O(1) vs O(n)).
355
+ - `.lean()` is applied for ~3–5× faster reads on plain object responses.
356
+ - `maxTimeMS` is applied to both count and find to prevent runaway collection scans.
357
+ - If the requested `page` exceeds `totalPages` (e.g. after a deletion), page `1` is returned automatically.
358
+
359
+ ```
360
+ GET /users?page=2&limit=20
361
+ ```
362
+
363
+ **Returns:**
364
+
365
+ ```ts
366
+ {
367
+ data: T[];
368
+ total: number; // Total matching documents across all pages
369
+ page: number; // Current page (auto-corrects to 1 if out of range)
370
+ totalPages: number;
371
+ limit: number;
372
+ hasNextPage: boolean;
373
+ hasPrevPage: boolean;
374
+ }
375
+ ```
376
+
377
+ **Defaults:** `page=1`, `limit=10`, max `limit=100`.
378
+
379
+ ---
380
+
381
+ ## Query Parameter Reference
382
+
383
+ | Parameter | Example | Description |
384
+ | ----------- | ------------------------- | ------------------------------------------------------ |
385
+ | `page` | `?page=3` | Page number (default: `1`, min: `1`) |
386
+ | `limit` | `?limit=25` | Documents per page (default: `10`, max: `100`) |
387
+ | `sort` | `?sort=-createdAt,name` | Sort fields; prefix `-` for descending (max: 5 fields) |
388
+ | `fields` | `?fields=name,email` | Comma-separated fields to include in the response |
389
+ | `q` | `?q=john` | Global search term (max: 200 chars) |
390
+ | _(any key)_ | `?role=admin&age[gte]=18` | Field-level filters processed by `.filter()` |
391
+
392
+ ---
393
+
394
+ ## Full Example (Express)
395
+
396
+ ```ts
397
+ import { Request, Response } from 'express';
398
+ import { queryFind } from 'mongoose-query-find';
399
+ import UserModel from '../models/user';
400
+
401
+ export const getUsers = async (req: Request, res: Response) => {
402
+ const result = await queryFind(UserModel.find(), req.query)
403
+ .allowFields(['name', 'email', 'username', 'role', 'isActive', 'createdAt'])
404
+ .where({ orgId: req.user.orgId, deletedAt: null })
405
+ .filter()
406
+ .globalSearch(['name', 'email', 'username'])
407
+ .sort()
408
+ .limitFields('-password -__v')
409
+ .populate('role', 'name permissions')
410
+ .paginate();
411
+
412
+ res.json({ status: 'success', ...result });
413
+ };
414
+ ```
415
+
416
+ **Example requests:**
417
+
418
+ ```bash
419
+ # Page 2, 15 per page, only active admins sorted by name
420
+ GET /users?page=2&limit=15&role=admin&isActive=true&sort=name
421
+
422
+ # Search "alice" across name, email, and username
423
+ GET /users?q=alice
424
+
425
+ # Users older than 25, return only name and email
426
+ GET /users?age[gt]=25&fields=name,email
427
+
428
+ # Filter by exact date
429
+ GET /users?createdAt=2024-06-01
430
+
431
+ # Filter by date range
432
+ GET /users?createdAt[gte]=2024-01-01&createdAt[lte]=2024-12-31
433
+
434
+ # Combined: search + filter + sort + pagination
435
+ GET /users?q=john&role=editor&sort=-createdAt&page=1&limit=5
436
+ ```
437
+
438
+ ---
439
+
440
+ ## More Examples
441
+
442
+ **E-commerce product listing — nested price filters + category populate:**
443
+
444
+ ```ts
445
+ export const getProducts = async (req: Request, res: Response) => {
446
+ const result = await queryFind(ProductModel.find(), req.query)
447
+ .allowFields(['name', 'price', 'category', 'inStock', 'brand', 'createdAt'])
448
+ .where({ deletedAt: null, published: true })
449
+ .filter()
450
+ .globalSearch(['name', 'brand'])
451
+ .sort()
452
+ .limitFields('name price inStock brand')
453
+ .populate('category', 'name slug')
454
+ .paginate();
455
+
456
+ res.json(result);
457
+ };
458
+ ```
459
+
460
+ ```bash
461
+ # Price between $20 and $100, in stock, sorted cheapest first
462
+ GET /products?price[gte]=20&price[lte]=100&inStock=true&sort=price
463
+
464
+ # Search "nike" across name and brand
465
+ GET /products?q=nike&sort=-createdAt
466
+ ```
467
+
468
+ **Blog posts — multiple populates + logical operators:**
469
+
470
+ ```ts
471
+ export const getPosts = async (req: Request, res: Response) => {
472
+ const result = await queryFind(PostModel.find(), req.query)
473
+ .allowFields(['title', 'status', 'authorId', 'tags', 'publishedAt'])
474
+ .where({ deletedAt: null })
475
+ .filter()
476
+ .globalSearch(['title'])
477
+ .sort()
478
+ .limitFields('title status publishedAt')
479
+ .populate('authorId', 'name avatar')
480
+ .populate({
481
+ path: 'comments',
482
+ select: 'text createdAt',
483
+ match: { visible: true },
484
+ })
485
+ .paginate();
486
+
487
+ res.json(result);
488
+ };
489
+ ```
490
+
491
+ ```bash
492
+ # Published OR featured posts, using the safe top-level $or
493
+ GET /posts?$or[0][status]=published&$or[1][featured]=true
494
+
495
+ # Posts tagged "typescript" published this year
496
+ GET /posts?tags=typescript&publishedAt[gte]=2026-01-01
497
+ ```
498
+
499
+ **Admin panel — strict field allowlist, sensitive fields never leak:**
500
+
501
+ ```ts
502
+ export const adminListUsers = async (req: Request, res: Response) => {
503
+ const result = await queryFind(UserModel.find(), req.query, { maxLimit: 250 })
504
+ .allowFields(['name', 'email', 'role', 'isActive', 'lastLoginAt'])
505
+ .where({ orgId: req.user.orgId })
506
+ .filter()
507
+ .sort()
508
+ .limitFields('-password -passwordResetToken -__v') // client's ?fields= can never override this
509
+ .paginate();
510
+
511
+ res.json(result);
512
+ };
513
+ ```
514
+
515
+ ```bash
516
+ # Even if a client tries ?fields=password, it's stripped — not in allowFields()
517
+ GET /admin/users?fields=password,email&role=admin
518
+ ```
519
+
520
+ **Cached count pattern — skip re-counting on subsequent pages:**
521
+
522
+ ```ts
523
+ export const getNotifications = async (req: Request, res: Response) => {
524
+ const builder = queryFind(NotificationModel.find(), req.query)
525
+ .allowFields(['userId', 'read', 'createdAt'])
526
+ .where({ userId: req.user.id })
527
+ .filter()
528
+ .sort();
529
+
530
+ // First request from the client includes no cachedTotal
531
+ const cachedTotal = req.query.cachedTotal
532
+ ? Number(req.query.cachedTotal)
533
+ : undefined;
534
+ const result = await builder.paginate(cachedTotal);
535
+
536
+ res.json(result); // client stores result.total and sends it back as ?cachedTotal= on the next page
537
+ };
538
+ ```
539
+
540
+ ---
541
+
542
+ ## TypeScript Types
543
+
544
+ All types are exported:
545
+
546
+ ```ts
547
+ import {
548
+ queryFind,
549
+ QueryFind,
550
+ QueryParams,
551
+ PaginatedResult,
552
+ QueryFindOptions,
553
+ QueryFindError,
554
+ QueryFindValidationError,
555
+ SlowQueryInfo,
556
+ } from 'mongoose-query-find';
557
+ ```
558
+
559
+ ```ts
560
+ interface QueryParams {
561
+ page?: string;
562
+ limit?: string;
563
+ sort?: string;
564
+ fields?: string;
565
+ q?: string;
566
+ [key: string]: unknown;
567
+ }
568
+
569
+ interface PaginatedResult<T> {
570
+ data: T[];
571
+ total: number;
572
+ page: number;
573
+ totalPages: number;
574
+ limit: number;
575
+ hasNextPage: boolean;
576
+ hasPrevPage: boolean;
577
+ }
578
+
579
+ interface QueryFindOptions {
580
+ maxTimeMS?: number; // default: 5000
581
+ slowQueryThresholdMS?: number; // default: maxTimeMS
582
+ maxLimit?: number; // default: 100
583
+ lean?: boolean; // default: true
584
+ onSlowQuery?: (info: SlowQueryInfo) => void;
585
+ onSanitizeDrop?: (path: string, value: unknown) => void;
586
+ }
587
+
588
+ interface SlowQueryInfo {
589
+ elapsedMs: number;
590
+ filter: Record<string, unknown>;
591
+ sort: Record<string, 1 | -1>;
592
+ page: number;
593
+ limit: number;
594
+ }
595
+ ```
596
+
597
+ ---
598
+
599
+ ## Security
600
+
601
+ | Protection | Detail |
602
+ | --------------------------- | ---------------------------------------------------------------------------------------- |
603
+ | **NoSQL injection** | Allowlist enforced on filters, sort, and projection via `.allowFields()` |
604
+ | **Banned operators** | `$where`, `$expr`, `$function`, and others are rejected recursively at any nesting depth |
605
+ | **ReDoS** | Search terms are regex-escaped before compilation |
606
+ | **Oversized search** | `?q=` capped at 200 characters |
607
+ | **Deep nesting DoS** | Filter object nesting capped at depth 5 |
608
+ | **Page size DoS** | `limit` hard-capped at 100 |
609
+ | **Sort abuse** | Sort fields hard-capped at 5 |
610
+ | **Runaway queries** | `maxTimeMS` applied to both count and find (default: 5s) |
611
+ | **Sensitive field leakage** | `?fields=` projection stripped against allowlist |
612
+
613
+ ---
614
+
615
+ ## Links
616
+
617
+ - [npm](https://www.npmjs.com/package/mongoose-query-find)
618
+ - [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
619
+ - [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
620
+
621
+ ---
622
+
623
+ ## License
624
+
625
+ ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
626
+
627
+ <br>
628
+ <br>
629
+
630
+ ---
631
+
632
+ ---
633
+
634
+ # QueryAggregate
635
+
636
+ 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.
637
+
638
+ ## QueryAggregate Overview
639
+
640
+ `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:
641
+
642
+ - Allowlisted filter/sort/projection fields
643
+ - Recursive sanitization of client input (drops class instances, functions, over-deep nesting)
644
+ - Banned-operator rejection (`$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`)
645
+ - Capped pagination (`limit`, `page`)
646
+ - Timezone-aware date coercion, `$lookup` joins, arbitrary developer-authored pipeline stages via `.addStage()`
647
+ - Single-round-trip pagination via `$facet`
648
+ - **New:** six custom date-range methods (arbitrary day, arbitrary span, rolling N-days/N-hours, hour-of-day windows, absolute datetime windows)
649
+ - **New:** `count()`, `distinct()`, and `stats()` for cheap metrics without fetching a data page
650
+ - **New:** `stream()` for memory-safe large exports, and `paginateCursor()` for keyset pagination on huge collections
651
+ - **New:** `explain()`, `debugPipeline()`, and `clone()` for debugging and query reuse
652
+
653
+ ## When to use QueryAggregate vs QueryFind
654
+
655
+ | Need | Use |
656
+ | -------------------------------------------------------------- | ---------------- |
657
+ | Simple filter/sort/paginate on one collection | `QueryFind` |
658
+ | Joining another collection (`$lookup`) | `QueryAggregate` |
659
+ | Grouping / rollups / computed fields (`$group`, `$addFields`) | `QueryAggregate` |
660
+ | Client filters need to respect the caller's local timezone | `QueryAggregate` |
661
+ | A custom day / date span / rolling window / hour-of-day filter | `QueryAggregate` |
662
+ | Dashboard totals (sum/avg/count) without fetching a page | `QueryAggregate` |
663
+ | Very large collections where `$skip` pagination gets slow | `QueryAggregate` |
664
+ | Streaming a large export without buffering it in memory | `QueryAggregate` |
665
+ | You need a custom developer-defined pipeline stage | `QueryAggregate` |
666
+
667
+ ## Installation
668
+
669
+ Ships from the same package as `QueryFind`:
670
+
671
+ ```bash
672
+ npm install mongoose-query-find
673
+ ```
674
+
675
+ ## Quick Start
676
+
677
+ ```ts
678
+ import { QueryAggregate } from 'mongoose-query-find';
679
+ import CategoryModel from './models/category';
680
+
681
+ const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
682
+
683
+ const result = await new QueryAggregate(CategoryModel, req.query, { timezone })
684
+ .allowFields(['name', 'status', 'createdAt'])
685
+ .dateFields(['createdAt'])
686
+ .where({ branchId: req.self.linkedTo, status: { $ne: 'ARCHIVED' } })
687
+ .filter()
688
+ .globalSearch(['name'])
689
+ .sort()
690
+ .project('name status createdAt updatedAt')
691
+ .paginate();
692
+ ```
693
+
694
+ `result` shape is identical to `QueryFind`'s `PaginatedResult<T>`:
695
+
696
+ ```json
697
+ {
698
+ "data": [...],
699
+ "total": 84,
700
+ "page": 2,
701
+ "totalPages": 9,
702
+ "limit": 10,
703
+ "hasNextPage": true,
704
+ "hasPrevPage": true
705
+ }
706
+ ```
707
+
708
+ ## Constructor & Options
709
+
710
+ ```ts
711
+ new QueryAggregate<T>(model, queryString, options?);
712
+ ```
713
+
714
+ | Parameter | Type | Description |
715
+ | ------------- | ----------------------- | ----------------------------------------------- |
716
+ | `model` | `Model<T>` | A Mongoose model |
717
+ | `queryString` | `QueryParams` | Parsed URL query object, e.g. `req.query` |
718
+ | `options` | `QueryAggregateOptions` | Configuration options (see below), all optional |
719
+
720
+ ### `QueryAggregateOptions`
721
+
722
+ | Option | Type | Default | Description |
723
+ | ---------------------- | ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
724
+ | `timezone` | `string` | `'Asia/Dhaka'` | IANA timezone for interpreting client-supplied local dates. Invalid values fall back to the default (validated once at construction, never throws mid-query). |
725
+ | `maxTimeMS` | `number` | `5000` | Max time MongoDB may spend per query. `0` disables. |
726
+ | `slowQueryThresholdMS` | `number` | `maxTimeMS` | Threshold above which `onSlowQuery` fires. |
727
+ | `maxLimit` | `number` | `100` | Hard cap on `?limit=`. |
728
+ | `allowDiskUse` | `boolean` | `false` | Forwarded to `.allowDiskUse()` — enable for large sort/group pipelines. |
729
+ | `weekStartsOn` | `0–6` | `6` (Saturday) | Used by `.range('thisWeek')`. |
730
+ | `onSlowQuery` | `(info: SlowQueryInfo) => void` | — | Callback fired when a query exceeds `slowQueryThresholdMS`. |
731
+ | `onSanitizeDrop` | `(path: string, value: unknown) => void` | — | Callback fired whenever sanitization drops a value (bad nesting, non-plain value). |
732
+
733
+ ## Timezone Handling
734
+
735
+ 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.
736
+
737
+ - `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`.
738
+ - `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.
739
+
740
+ The timezone is a **per-request** value, typically sourced from a header:
741
+
742
+ ```ts
743
+ const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
744
+ ```
745
+
746
+ 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.
747
+
748
+ 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.
749
+
750
+ ## Builder Methods
751
+
752
+ All builder methods return `this` and are fully chainable. Recommended call order:
753
+
754
+ ```
755
+ allowFields → dateFields/objectIdFields → where → range/rangeXxx → filter → globalSearch → sort → project → lookup/addStage/computeField → paginate/paginateCursor/count/distinct/stats/stream
756
+ ```
757
+
758
+ ---
759
+
760
+ ### `.allowFields(fields: string[])`
761
+
762
+ Same role as in `QueryFind`: declares which fields the client may filter, sort, and project. Case-insensitive. Call before `.filter()`, `.sort()`, `.project()`.
763
+
764
+ ```ts
765
+ .allowFields(['name', 'status', 'createdAt'])
766
+ ```
767
+
768
+ ---
769
+
770
+ ### `.dateFields(fields: string[])`
771
+
772
+ Explicit list of fields treated as dates for timezone-aware coercion. When omitted, falls back to a name heuristic matching `createdAt`, `updatedAt`, `deletedAt`, `archivedAt`, `expiresAt`, `date`, `birthDate` (only when that word is the _last_ path segment, e.g. `user.updatedAt` matches, `updatedAtSomething` doesn't).
773
+
774
+ ```ts
775
+ .dateFields(['createdAt', 'updatedAt'])
776
+ ```
777
+
778
+ ---
779
+
780
+ ### `.objectIdFields(fields: string[])`
781
+
782
+ 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`).
783
+
784
+ ```ts
785
+ .objectIdFields(['branchId', 'categoryId'])
786
+ ```
787
+
788
+ ---
789
+
790
+ ### `.filter()`
791
+
792
+ Parses `req.query` into the aggregation `$match` stage's client-derived portion. Runs, in order:
793
+
794
+ 1. Strips reserved keys (`page`, `sort`, `limit`, `fields`, `q`)
795
+ 2. `sanitize()` — recursively drops non-plain values (class instances, functions), capped at nesting depth 5
796
+ 3. `coerceAll()` — timezone-aware date coercion + ObjectId coercion + boolean coercion + numeric coercion + operator-name coercion (`gt` → `$gt`, etc.)
797
+ 4. `enforceAllowlist()` — strips any non-operator key not in `.allowFields()`
798
+ 5. `rejectDisallowedOperators()` — throws `QueryAggregateValidationError` on `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter`, or any unexpected top-level `$` operator
799
+
800
+ ```
801
+ GET /categories?createdAt=2026-09-01&status=ACTIVE
802
+ ```
803
+
804
+ ```ts
805
+ .filter()
806
+ // → { createdAt: { $gte: <UTC midnight in tz>, $lt: <next UTC midnight in tz> }, status: 'ACTIVE' }
807
+ ```
808
+
809
+ ---
810
+
811
+ ### `.where(conditions)`
812
+
813
+ Mandatory server-side conditions the client **cannot override** — kept in a separate internal bucket (`_serverConditions`) and merged last via `$and`, so URL params can never win against it.
814
+
815
+ ```ts
816
+ .where({ branchId: req.self.linkedTo, status: { $ne: 'ARCHIVED' } })
817
+ ```
818
+
819
+ ---
820
+
821
+ ### `.range(field: string, preset: RangePreset)`
822
+
823
+ Adds a hard, server-defined UTC date range on `field`, computed in this instance's timezone. Not client-overridable (goes into `_serverConditions`, same as `.where()`).
824
+
825
+ **Presets:** `'today'`, `'yesterday'`, `'last7Days'`, `'last30Days'`, `'thisWeek'`, `'thisMonth'`
826
+
827
+ ```ts
828
+ .range('createdAt', 'last7Days')
829
+ ```
830
+
831
+ `.range('thisWeek')` respects the `weekStartsOn` constructor option (defaults to Saturday).
832
+
833
+ ---
834
+
835
+ ## Custom Range Methods
836
+
837
+ 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.
838
+
839
+ > ⚠️ 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.
840
+
841
+ ### `.rangeCustomDay(field: string, date: string)`
842
+
843
+ A single arbitrary local calendar date (`YYYY-MM-DD`) — for "show me everything from this specific day" rather than a relative preset.
844
+
845
+ ```ts
846
+ .rangeCustomDay('createdAt', '2026-03-14')
847
+ ```
848
+
849
+ ### `.rangeBetween(field: string, custom: CustomDateRangeInput)`
850
+
851
+ An arbitrary inclusive local-date span — the classic "from / to" date-picker filter.
852
+
853
+ ```ts
854
+ .rangeBetween('createdAt', { from: '2026-01-01', to: '2026-01-31' })
855
+ ```
856
+
857
+ ### `.rangeLastNDays(field: string, days: number)`
858
+
859
+ A rolling window of the last N whole calendar days, inclusive of today — a parametrized version of the built-in `last7Days`/`last30Days` presets.
860
+
861
+ ```ts
862
+ .rangeLastNDays('createdAt', 14) // last 14 calendar days
863
+ ```
864
+
865
+ ### `.rangeLastNHours(field: string, hours: number)`
866
+
867
+ 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.
868
+
869
+ ```ts
870
+ .rangeLastNHours('createdAt', 6) // activity in the last 6 hours
871
+ ```
872
+
873
+ ### `.rangeHours(field: string, custom: CustomHourRangeInput)`
874
+
875
+ An explicit hour-of-day window on a specific local date — e.g. filtering orders placed during business hours.
876
+
877
+ ```ts
878
+ .rangeHours('createdAt', { date: '2026-03-14', fromHour: 9, toHour: 17 })
879
+ // toHour is exclusive; pass 24 for "through end of day"
880
+ ```
881
+
882
+ ### `.rangeCustom(field: string, custom: CustomDateTimeRangeInput)`
883
+
884
+ The most flexible option — an explicit absolute datetime window. Each of `from`/`to` accepts:
885
+
886
+ - `"YYYY-MM-DD"` → local midnight in this instance's timezone
887
+ - `"YYYY-MM-DDTHH:mm:ss[.sss]"` → local wall-clock time in this instance's timezone
888
+ - an offset-bearing ISO string (`...Z`, `...+06:00`) → treated as an absolute instant
889
+
890
+ ```ts
891
+ .rangeCustom('createdAt', {
892
+ from: '2026-03-14T09:30:00', // local wall-clock
893
+ to: '2026-03-14T18:45:00',
894
+ })
895
+
896
+ // or mixed with an explicit UTC instant:
897
+ .rangeCustom('createdAt', { from: '2026-03-14T00:00:00Z', to: '2026-03-15T00:00:00Z' })
898
+ ```
899
+
900
+ ---
901
+
902
+ ### `.excludeSoftDeleted(field = 'deletedAt')`
903
+
904
+ Convenience server-side condition excluding soft-deleted documents. Matches both `null` and a genuinely missing field, per MongoDB's equality semantics. Not client-overridable.
905
+
906
+ ```ts
907
+ .excludeSoftDeleted() // defaults to 'deletedAt'
908
+ .excludeSoftDeleted('removedAt') // or a custom field name
909
+ ```
910
+
911
+ ---
912
+
913
+ ### `.whereIf(condition, conditions)`
914
+
915
+ Applies `.where(conditions)` only when `condition` is truthy — avoids scattering `if` statements around a chained builder call.
916
+
917
+ ```ts
918
+ .whereIf(req.query.vip === 'true', { tier: 'vip' })
919
+ .whereIf(req.self.role !== 'admin', { branchId: req.self.linkedTo })
920
+ ```
921
+
922
+ ---
923
+
924
+ ### `.globalSearch(fields: string[])`
925
+
926
+ 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.
927
+
928
+ ```ts
929
+ .globalSearch(['name'])
930
+ ```
931
+
932
+ ---
933
+
934
+ ### `.sort()`
935
+
936
+ Parses `?sort=` (e.g. `-createdAt,name`), capped at 5 fields, dropping any field not in the allowlist. Falls back to `{ createdAt: -1 }` when absent.
937
+
938
+ ```ts
939
+ .sort()
940
+ ```
941
+
942
+ > `.paginateCursor()` (below) seeks on this same sort configuration, so call `.sort()` before it if you need a field other than the default `createdAt`.
943
+
944
+ ---
945
+
946
+ ### `.project(defaultProjection?: string | Record<string, 0 | 1>)`
947
+
948
+ Controls the `$project` stage. Accepts a space-separated string (`"name status -_id"`) or a raw `{ field: 0 | 1 }` object.
949
+
950
+ - `?fields=` (when present) is parsed and filtered through the allowlist.
951
+ - If **every** requested field is blocked, falls back to `defaultProjection` rather than silently returning everything.
952
+ - `_id` and `__v` are always allowed through even if not in `allowFields()`.
953
+
954
+ ```ts
955
+ .project('name status createdAt updatedAt')
956
+ ```
957
+
958
+ > ⚠️ If a preceding `.addStage()` (e.g. `$group`) reshapes documents, `.project()`'s allowlist still only knows about the fields passed to `.allowFields()` — new computed fields may be silently dropped. Use `.addStage({ $project: {...} })` instead when you need full control post-reshape.
959
+
960
+ ---
961
+
962
+ ### `.lookup(opts: LookupOptions)`
963
+
964
+ Adds a `$lookup` (join) stage, optionally followed by `$unwind`.
965
+
966
+ | Field | Type | Description |
967
+ | -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
968
+ | `from` | `string` | Collection name (not the model name) to join against. |
969
+ | `as` | `string` | Output array field name. |
970
+ | `localField` | `string?` | Local join field. |
971
+ | `foreignField` | `string?` | Foreign join field. |
972
+ | `pipeline` | `PipelineStage[]?` | Sub-pipeline form of `$lookup`, for complex/correlated joins. Cannot contain `$out`/`$merge`. |
973
+ | `single` | `boolean?` | When `true`, `$unwind`s the joined array (`preserveNullAndEmptyArrays: true`) so `as` becomes a single object instead of an array. |
974
+
975
+ ```ts
976
+ .lookup({
977
+ from: 'branches',
978
+ as: 'branch',
979
+ localField: 'branchId',
980
+ foreignField: '_id',
981
+ single: true,
982
+ })
983
+ ```
984
+
985
+ ---
986
+
987
+ ### `.computeField(name: string, expression: unknown)`
988
+
989
+ Convenience wrapper over `.addStage()` for a single computed `$addFields` entry.
990
+
991
+ ```ts
992
+ .computeField('margin', { $subtract: ['$price', '$cost'] })
993
+ // equivalent to: .addStage({ $addFields: { margin: { $subtract: ['$price', '$cost'] } } })
994
+ ```
995
+
996
+ ---
997
+
998
+ ### `.addStage(stage: PipelineStage)`
999
+
1000
+ Escape hatch for any other developer-authored stage: `$addFields`, `$group`, a post-join `$match`, a custom `$sort`, etc.
1001
+
1002
+ - Blocks **only** `$out` / `$merge` (destructive stages).
1003
+ - **Does not** run the client-input sanitizer/allowlist/operator-rejection — that only applies to `.filter()`/`.where()`, which parse untrusted `req.query`/`req.body` values.
1004
+ - **Never pass raw client input directly into `.addStage()`.** It's for stages _you_ author server-side. If you need a client-supplied value inside a custom stage, validate/whitelist it yourself first.
1005
+
1006
+ ```ts
1007
+ .addStage({
1008
+ $group: {
1009
+ _id: '$status',
1010
+ count: { $sum: 1 },
1011
+ totalAmount: { $sum: '$amount' },
1012
+ },
1013
+ })
1014
+ ```
1015
+
1016
+ ## Terminal & Utility Methods
1017
+
1018
+ ### `.paginate(cachedTotal?: number)`
1019
+
1020
+ Executes the pipeline and returns `Promise<PaginatedResult<T>>`.
1021
+
1022
+ - Uses `$facet` to fetch the data page and total count in a **single round trip**.
1023
+ - Pass a prior page-1 `total` as `cachedTotal` on later pages to **skip the count stage entirely**.
1024
+ - `maxTimeMS` / `allowDiskUse` from constructor options are applied to the aggregation.
1025
+ - If the requested `page` exceeds `totalPages`, page `1` is returned automatically (with the real `total`/`totalPages` still reported).
1026
+ - `onSlowQuery` (if configured) fires with `{ elapsedMs, pipeline, sort, page, limit }` when the query exceeds `slowQueryThresholdMS`.
1027
+
1028
+ > **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.
1029
+
1030
+ ```ts
1031
+ const page1 = await builder.paginate();
1032
+ const page2 = await builder.paginate(page1.total); // skips re-counting
1033
+ ```
1034
+
1035
+ ---
1036
+
1037
+ ### `.paginateCursor(opts?: CursorPaginateOptions)`
1038
+
1039
+ 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.
1040
+
1041
+ ```ts
1042
+ interface CursorPaginateOptions {
1043
+ cursor?: string; // opaque cursor from a previous page's nextCursor
1044
+ limit?: number; // overrides ?limit=, still capped by maxLimit
1045
+ }
1046
+
1047
+ interface CursorPaginatedResult<T> {
1048
+ data: T[];
1049
+ limit: number;
1050
+ nextCursor: string | null; // pass this back in as `cursor` for the next page
1051
+ hasNextPage: boolean;
1052
+ }
1053
+ ```
1054
+
1055
+ ```ts
1056
+ const p1 = await builder.sort().paginateCursor({ limit: 20 });
1057
+ const p2 = await builder.paginateCursor({ cursor: p1.nextCursor!, limit: 20 });
1058
+ // hasNextPage: false / nextCursor: null means you've reached the end
1059
+ ```
1060
+
1061
+ Great fit for infinite-scroll feeds and large-export pagination; not a drop-in replacement where the UI needs page numbers.
1062
+
1063
+ ---
1064
+
1065
+ ### `.count()`
1066
+
1067
+ Returns just the matching document count — cheaper than `.paginate()` when you don't need the data page. Ignores `.project()`/`.sort()`.
1068
+
1069
+ ```ts
1070
+ const total = await builder.count();
1071
+ ```
1072
+
1073
+ ---
1074
+
1075
+ ### `.distinct(field: string)`
1076
+
1077
+ Returns the distinct values of `field` under the current `.filter()`/`.where()`/range conditions.
1078
+
1079
+ ```ts
1080
+ const statuses = await builder.distinct('status');
1081
+ // e.g. ['PENDING', 'PAID', 'CANCELLED']
1082
+ ```
1083
+
1084
+ ---
1085
+
1086
+ ### `.stats(specs: StatSpec[])`
1087
+
1088
+ Computes one or more aggregate metrics — `sum`, `avg`, `min`, `max`, `count` — in a **single round trip**. Ideal for dashboard totals. Ignores `.project()`/`.sort()`/pagination.
1089
+
1090
+ ```ts
1091
+ interface StatSpec {
1092
+ name: string;
1093
+ op: 'sum' | 'avg' | 'min' | 'max' | 'count';
1094
+ field?: string; // required for every op except 'count'
1095
+ }
1096
+ ```
1097
+
1098
+ ```ts
1099
+ const totals = await builder.stats([
1100
+ { name: 'revenue', op: 'sum', field: 'total' },
1101
+ { name: 'avgOrder', op: 'avg', field: 'total' },
1102
+ { name: 'orders', op: 'count' },
1103
+ ]);
1104
+ // { revenue: 48213, avgOrder: 62.1, orders: 776 }
1105
+ ```
1106
+
1107
+ ---
1108
+
1109
+ ### `.stream()`
1110
+
1111
+ Returns a Mongoose `AggregationCursor` — async-iterable, no buffering of the full result set in memory. Use for large exports (CSV generation, bulk processing).
1112
+
1113
+ ```ts
1114
+ for await (const doc of builder.stream()) {
1115
+ csvWriter.write(doc);
1116
+ }
1117
+ ```
1118
+
1119
+ Ignores `page`/`limit`; add your own `$limit` via `.addStage()` if you want a hard cap.
1120
+
1121
+ ---
1122
+
1123
+ ### `.explain(verbosity?)`
1124
+
1125
+ Runs the built pipeline through Mongoose's `.explain()` — for debugging slow queries and verifying index usage. `verbosity` is `'queryPlanner'` (default), `'executionStats'`, or `'allPlansExecution'`.
1126
+
1127
+ ```ts
1128
+ const plan = await builder.explain('executionStats');
1129
+ ```
1130
+
1131
+ > Development/ops tool only — never call this in a production request path.
1132
+
1133
+ ---
1134
+
1135
+ ### `.clone()`
1136
+
1137
+ 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.
1138
+
1139
+ ```ts
1140
+ const base = builder.filter().sort().project('name total createdAt');
1141
+
1142
+ const [page, totals] = await Promise.all([
1143
+ base.clone().paginate(),
1144
+ base.clone().stats([{ name: 'revenue', op: 'sum', field: 'total' }]),
1145
+ ]);
1146
+ ```
1147
+
1148
+ ---
1149
+
1150
+ ### `.debugPipeline()`
1151
+
1152
+ Returns the fully-built pipeline (`PipelineStage[]`) without executing it — for logging, snapshot tests, or sanity-checking what will actually run.
1153
+
1154
+ ```ts
1155
+ console.log(builder.debugPipeline());
1156
+ ```
1157
+
1158
+ ## Recipes
1159
+
1160
+ **Join + post-join filter + group + paginate:**
1161
+
1162
+ ```ts
1163
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1164
+ .allowFields(['status', 'createdAt'])
1165
+ .dateFields(['createdAt'])
1166
+ .filter()
1167
+ .lookup({
1168
+ from: 'customers',
1169
+ as: 'customer',
1170
+ localField: 'customerId',
1171
+ foreignField: '_id',
1172
+ single: true,
1173
+ })
1174
+ .addStage({ $match: { 'customer.vip': true } }) // server-defined, not client-controlled
1175
+ .addStage({
1176
+ $group: {
1177
+ _id: '$customer._id',
1178
+ customerName: { $first: '$customer.name' },
1179
+ orderCount: { $sum: 1 },
1180
+ },
1181
+ })
1182
+ .sort()
1183
+ .paginate();
1184
+ ```
1185
+
1186
+ **Relative date range preset (server-enforced, not client-overridable):**
1187
+
1188
+ ```ts
1189
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1190
+ .allowFields(['status'])
1191
+ .where({ branchId: req.self.linkedTo })
1192
+ .range('createdAt', 'last30Days')
1193
+ .filter()
1194
+ .sort()
1195
+ .paginate();
1196
+ ```
1197
+
1198
+ **Custom hour-of-day window (business hours report):**
1199
+
1200
+ ```ts
1201
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1202
+ .allowFields(['status'])
1203
+ .where({ branchId: req.self.linkedTo })
1204
+ .rangeHours('createdAt', {
1205
+ date: req.query.day as string,
1206
+ fromHour: 9,
1207
+ toHour: 21,
1208
+ })
1209
+ .filter()
1210
+ .sort()
1211
+ .paginate();
1212
+ ```
1213
+
1214
+ **Dashboard: page + totals in parallel, off one shared base:**
1215
+
1216
+ ```ts
1217
+ const base = new QueryAggregate(OrderModel, req.query, { timezone })
1218
+ .allowFields(['status', 'branchId', 'createdAt', 'total'])
1219
+ .dateFields(['createdAt'])
1220
+ .where({ branchId: req.self.linkedTo })
1221
+ .excludeSoftDeleted()
1222
+ .filter()
1223
+ .sort()
1224
+ .project('status createdAt total');
1225
+
1226
+ const [page, totals] = await Promise.all([
1227
+ base.clone().paginate(),
1228
+ base.clone().stats([
1229
+ { name: 'revenue', op: 'sum', field: 'total' },
1230
+ { name: 'orders', op: 'count' },
1231
+ ]),
1232
+ ]);
1233
+ ```
1234
+
1235
+ **Infinite scroll with keyset pagination:**
1236
+
1237
+ ```ts
1238
+ const builder = new QueryAggregate(PostModel, req.query, { timezone })
1239
+ .allowFields(['authorId', 'createdAt'])
1240
+ .where({ published: true })
1241
+ .filter()
1242
+ .sort();
1243
+
1244
+ const page = await builder.paginateCursor({
1245
+ cursor: req.query.cursor as string | undefined,
1246
+ limit: 20,
1247
+ });
1248
+ ```
1249
+
1250
+ **Streaming a large CSV export:**
1251
+
1252
+ ```ts
1253
+ const builder = new QueryAggregate(OrderModel, req.query, { timezone })
1254
+ .allowFields(['status', 'createdAt'])
1255
+ .where({ branchId: req.self.linkedTo })
1256
+ .range('createdAt', 'thisMonth')
1257
+ .filter()
1258
+ .project('status createdAt total');
1259
+
1260
+ res.setHeader('Content-Type', 'text/csv');
1261
+ for await (const row of builder.stream()) {
1262
+ res.write(`${row.status},${row.createdAt.toISOString()},${row.total}\n`);
1263
+ }
1264
+ res.end();
1265
+ ```
1266
+
1267
+ **ObjectId filter fields (ref lookups by hex ID from the URL):**
1268
+
1269
+ ```
1270
+ GET /orders?branchId=64f1a2b3c4d5e6f7a8b9c0d1&categoryId=64f1a2b3c4d5e6f7a8b9c0d2
1271
+ ```
1272
+
1273
+ ```ts
1274
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1275
+ .allowFields(['branchId', 'categoryId', 'status'])
1276
+ .objectIdFields(['branchId', 'categoryId']) // coerces hex strings -> Types.ObjectId
1277
+ .filter()
1278
+ .sort()
1279
+ .paginate();
1280
+ ```
1281
+
1282
+ **Role-based server conditions with `.whereIf()` + `.excludeSoftDeleted()`:**
1283
+
1284
+ ```ts
1285
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1286
+ .allowFields(['status', 'branchId', 'createdAt'])
1287
+ .excludeSoftDeleted() // deletedAt: null, always applied
1288
+ .whereIf(req.self.role !== 'admin', { branchId: req.self.linkedTo }) // branch staff see only their branch
1289
+ .whereIf(req.query.vip === 'true', { tier: 'vip' })
1290
+ .filter()
1291
+ .sort()
1292
+ .paginate();
1293
+ ```
1294
+
1295
+ **Populating a filter UI — distinct values + count, no data fetch:**
1296
+
1297
+ ```ts
1298
+ const builder = new QueryAggregate(OrderModel, req.query, { timezone })
1299
+ .allowFields(['status', 'branchId'])
1300
+ .where({ branchId: req.self.linkedTo })
1301
+ .filter();
1302
+
1303
+ const [statuses, total] = await Promise.all([
1304
+ builder.clone().distinct('status'), // populate a <select> of possible statuses
1305
+ builder.clone().count(), // "X results" label
1306
+ ]);
1307
+ ```
1308
+
1309
+ **Debug route — inspect the built pipeline / query plan without exposing it to normal users:**
1310
+
1311
+ ```ts
1312
+ router.get('/orders/_debug', requireAdmin, async (req, res) => {
1313
+ const builder = new QueryAggregate(OrderModel, req.query, { timezone })
1314
+ .allowFields(['status', 'createdAt'])
1315
+ .where({ branchId: req.self.linkedTo })
1316
+ .range('createdAt', 'last7Days')
1317
+ .filter()
1318
+ .sort();
1319
+
1320
+ res.json({
1321
+ pipeline: builder.debugPipeline(),
1322
+ explain: await builder.explain('executionStats'),
1323
+ });
1324
+ });
1325
+ ```
1326
+
1327
+ **Cursor pagination on a non-default sort field:**
1328
+
1329
+ ```ts
1330
+ const result = await new QueryAggregate(ProductModel, req.query, { timezone })
1331
+ .allowFields(['price', 'name'])
1332
+ .where({ inStock: true })
1333
+ .filter()
1334
+ .sort() // resolves ?sort=price into { price: 1 } — paginateCursor() will seek on "price"
1335
+ .paginateCursor({
1336
+ cursor: req.query.cursor as string | undefined,
1337
+ limit: 24,
1338
+ });
1339
+ ```
1340
+
1341
+ **Correlated sub-pipeline `$lookup` (needs `let`):**
1342
+
1343
+ The built-in `LookupOptions` type doesn't expose `let` for correlated sub-pipelines. For that case, drop to `.addStage()` directly:
1344
+
1345
+ ```ts
1346
+ .addStage({
1347
+ $lookup: {
1348
+ from: 'orderItems',
1349
+ let: { orderId: '$_id' },
1350
+ pipeline: [
1351
+ { $match: { $expr: { $eq: ['$orderId', '$$orderId'] } } },
1352
+ { $project: { name: 1, qty: 1 } },
1353
+ ],
1354
+ as: 'items',
1355
+ },
1356
+ })
1357
+ ```
1358
+
1359
+ **Sales analytics dashboard — join, group, and rolling window in one pipeline:**
1360
+
1361
+ ```ts
1362
+ const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
1363
+
1364
+ const result = await new QueryAggregate(OrderModel, req.query, { timezone })
1365
+ .allowFields(['branchId', 'status'])
1366
+ .where({ status: 'PAID' })
1367
+ .rangeLastNDays('createdAt', 30) // rolling 30-day window, client can't override
1368
+ .filter()
1369
+ .lookup({
1370
+ from: 'branches',
1371
+ as: 'branch',
1372
+ localField: 'branchId',
1373
+ foreignField: '_id',
1374
+ single: true,
1375
+ })
1376
+ .addStage({
1377
+ $group: {
1378
+ _id: '$branchId',
1379
+ branchName: { $first: '$branch.name' },
1380
+ revenue: { $sum: '$total' },
1381
+ orders: { $sum: 1 },
1382
+ avgOrderValue: { $avg: '$total' },
1383
+ },
1384
+ })
1385
+ .addStage({ $sort: { revenue: -1 } })
1386
+ .paginate();
1387
+ ```
1388
+
1389
+ **Notification feed — lookup + unwind a single related document per row:**
1390
+
1391
+ ```ts
1392
+ const result = await new QueryAggregate(NotificationModel, req.query, {
1393
+ timezone,
1394
+ })
1395
+ .allowFields(['read', 'type', 'createdAt'])
1396
+ .dateFields(['createdAt'])
1397
+ .where({ userId: req.user.id })
1398
+ .filter()
1399
+ .lookup({
1400
+ from: 'users',
1401
+ as: 'actor',
1402
+ localField: 'actorId',
1403
+ foreignField: '_id',
1404
+ single: true, // unwinds so `actor` is a single object, not an array
1405
+ })
1406
+ .sort()
1407
+ .project('type read createdAt actor.name actor.avatar')
1408
+ .paginate();
1409
+ ```
1410
+
1411
+ **Audit log search — global search + a bounded absolute datetime window:**
1412
+
1413
+ ```ts
1414
+ const result = await new QueryAggregate(AuditLogModel, req.query, { timezone })
1415
+ .allowFields(['action', 'actorId', 'createdAt'])
1416
+ .dateFields(['createdAt'])
1417
+ .where({ orgId: req.user.orgId })
1418
+ .rangeCustom('createdAt', {
1419
+ from: (req.query.from as string) ?? '2026-01-01T00:00:00',
1420
+ to: (req.query.to as string) ?? new Date().toISOString(),
1421
+ })
1422
+ .filter()
1423
+ .globalSearch(['action'])
1424
+ .sort()
1425
+ .project('action actorId createdAt')
1426
+ .paginate();
1427
+ ```
1428
+
1429
+ **Multi-branch inventory report — objectIdFields + computeField + stats side by side:**
1430
+
1431
+ ```ts
1432
+ const base = new QueryAggregate(ProductModel, req.query, { timezone })
1433
+ .allowFields(['branchId', 'category', 'stock', 'price'])
1434
+ .objectIdFields(['branchId'])
1435
+ .where({ deletedAt: null })
1436
+ .filter()
1437
+ .computeField('stockValue', { $multiply: ['$stock', '$price'] })
1438
+ .sort()
1439
+ .project('branchId category stock price stockValue');
1440
+
1441
+ const [page, totals] = await Promise.all([
1442
+ base.clone().paginate(),
1443
+ base.clone().stats([
1444
+ { name: 'totalStockValue', op: 'sum', field: 'stockValue' },
1445
+ { name: 'lowStockAvg', op: 'avg', field: 'stock' },
1446
+ { name: 'skuCount', op: 'count' },
1447
+ ]),
1448
+ ]);
1449
+
1450
+ res.json({ ...page, totals });
1451
+ ```
1452
+
1453
+ ## Pipeline Stage Ordering
1454
+
1455
+ The final pipeline is always assembled in this fixed order:
1456
+
1457
+ ```
1458
+ $match (from .where() + .filter() + .range()/rangeXxx() + .globalSearch(), merged via $and)
1459
+ ↓
1460
+ [.lookup() / .addStage() / .computeField() calls, in the order you called them]
1461
+ ↓
1462
+ $project (from .project(), if set)
1463
+ ↓
1464
+ $sort (from .sort())
1465
+ ↓
1466
+ [terminal stage: $skip/$limit, $facet, keyset $match + $limit, or $count/$group — added internally by the method you call]
1467
+ ```
1468
+
1469
+ Implications:
1470
+
1471
+ - Anything added via `.addStage()`/`.computeField()` runs **after** the base filter match and **before** projection/sort.
1472
+ - If you `$group`/reshape documents, do it before `.project()` — or skip `.project()` and use `.addStage({ $project: {...} })` for full control over the new shape.
1473
+ - 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.
1474
+ - `.count()`, `.distinct()`, and `.stats()` intentionally skip `$project`/`$sort` — they only need `$match` + your `.lookup()`/`.addStage()` stages before their own terminal `$count`/`$group`.
1475
+ - `.paginateCursor()` builds its own `$match`/`$sort`/`$limit` tail (the keyset condition), separate from `.paginate()`'s `$facet` tail.
1476
+
1477
+ ## Security
1478
+
1479
+ | Protection | Detail |
1480
+ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1481
+ | **NoSQL injection** | Allowlist enforced on `.filter()`/`.sort()`/`.project()` via `.allowFields()` |
1482
+ | **Banned operators** | `$where`, `$expr`, `$function`, `$accumulator`, `$map`, `$reduce`, `$filter` rejected recursively, any depth, in client input |
1483
+ | **Destructive stages** | `$out` / `$merge` rejected in `.addStage()` / `.lookup()` sub-pipelines |
1484
+ | **ReDoS** | `.globalSearch()` terms are regex-escaped before compilation |
1485
+ | **Oversized search** | `?q=` capped at 200 characters |
1486
+ | **Deep nesting DoS** | Client filter object nesting capped at depth 5 (`sanitize()`) |
1487
+ | **Page size DoS** | `limit` hard-capped at `maxLimit` (default 100), including in `.paginateCursor()` |
1488
+ | **Sort abuse** | Sort fields hard-capped at 5 |
1489
+ | **Runaway queries** | `maxTimeMS` applied to the aggregation; `onSlowQuery` for observability |
1490
+ | **Bad timezone input** | Invalid IANA zone validated once at construction, falls back to default, never throws mid-query |
1491
+ | **Bad custom-range input** | `rangeCustomDay`/`rangeBetween`/`rangeLastNDays`/`rangeLastNHours`/`rangeHours`/`rangeCustom` all throw `QueryAggregateValidationError` on malformed dates, non-positive counts, or invalid hour bounds — never silently produce a wrong range |
1492
+ | **Server condition override** | `.where()` / `.range()` / every custom range method are merged last via `$and` — URL params can never override them |
1493
+ | **Tampered cursors** | `.paginateCursor()` cursors are opaque base64url-encoded JSON; a malformed cursor throws `QueryAggregateValidationError` rather than silently misbehaving |
1494
+ | **Untrusted `.addStage()` input** | Not sanitized/allowlisted by design — documented as a trusted, developer-authored-only escape hatch |
1495
+
1496
+ > **Important:** `.addStage()` and the `pipeline` option in `.lookup()` are for **server-defined stages only**. They skip the sanitizer/allowlist/operator-rejection that protects `.filter()`/`.where()`. Never interpolate raw `req.query`/`req.body` values into an `.addStage()` call without validating them yourself first.
1497
+
1498
+ ## TypeScript Types
1499
+
1500
+ ```ts
1501
+ import {
1502
+ QueryAggregate,
1503
+ QueryAggregateOptions,
1504
+ QueryAggregateError,
1505
+ QueryAggregateValidationError,
1506
+ LookupOptions,
1507
+ RangePreset,
1508
+ SlowQueryInfo,
1509
+ QueryParams,
1510
+ PaginatedResult,
1511
+ CustomDayInput,
1512
+ CustomDateRangeInput,
1513
+ CustomHourRangeInput,
1514
+ CustomDateTimeRangeInput,
1515
+ CursorPaginateOptions,
1516
+ CursorPaginatedResult,
1517
+ StatSpec,
1518
+ } from 'mongoose-query-find';
1519
+ ```
1520
+
1521
+ ```ts
1522
+ interface QueryAggregateOptions {
1523
+ timezone?: string;
1524
+ maxTimeMS?: number;
1525
+ slowQueryThresholdMS?: number;
1526
+ maxLimit?: number;
1527
+ allowDiskUse?: boolean;
1528
+ weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
1529
+ onSlowQuery?: (info: SlowQueryInfo) => void;
1530
+ onSanitizeDrop?: (path: string, value: unknown) => void;
1531
+ }
1532
+
1533
+ interface LookupOptions {
1534
+ from: string;
1535
+ as: string;
1536
+ localField?: string;
1537
+ foreignField?: string;
1538
+ pipeline?: PipelineStage[];
1539
+ single?: boolean;
1540
+ }
1541
+
1542
+ type RangePreset =
1543
+ | 'today'
1544
+ | 'yesterday'
1545
+ | 'last7Days'
1546
+ | 'last30Days'
1547
+ | 'thisWeek'
1548
+ | 'thisMonth';
1549
+
1550
+ interface SlowQueryInfo {
1551
+ elapsedMs: number;
1552
+ pipeline: PipelineStage[];
1553
+ sort: Record<string, 1 | -1>;
1554
+ page: number;
1555
+ limit: number;
1556
+ }
1557
+
1558
+ // ── Custom range types ──────────────────────────────────────────────────────
1559
+
1560
+ type CustomDayInput = string; // "YYYY-MM-DD"
1561
+
1562
+ interface CustomDateRangeInput {
1563
+ from: string; // "YYYY-MM-DD"
1564
+ to: string; // "YYYY-MM-DD"
1565
+ }
1566
+
1567
+ interface CustomHourRangeInput {
1568
+ date: string; // "YYYY-MM-DD"
1569
+ fromHour: number; // 0–24
1570
+ toHour: number; // 0–24, exclusive, must be > fromHour
1571
+ }
1572
+
1573
+ interface CustomDateTimeRangeInput {
1574
+ from: string; // "YYYY-MM-DD" | "YYYY-MM-DDTHH:mm:ss[.sss]" | offset-bearing ISO string
1575
+ to: string;
1576
+ }
1577
+
1578
+ // ── Advanced-feature types ──────────────────────────────────────────────────
1579
+
1580
+ interface CursorPaginateOptions {
1581
+ cursor?: string;
1582
+ limit?: number;
1583
+ }
1584
+
1585
+ interface CursorPaginatedResult<T> {
1586
+ data: T[];
1587
+ limit: number;
1588
+ nextCursor: string | null;
1589
+ hasNextPage: boolean;
1590
+ }
1591
+
1592
+ interface StatSpec {
1593
+ name: string;
1594
+ op: 'sum' | 'avg' | 'min' | 'max' | 'count';
1595
+ field?: string;
1596
+ }
1597
+ ```
1598
+
1599
+ ---
1600
+
1601
+ ## Links
1602
+
1603
+ - [npm](https://www.npmjs.com/package/mongoose-query-find)
1604
+ - [GitHub](https://github.com/jsdev-robin/mongoose-query-find)
1605
+ - [Issues](https://github.com/jsdev-robin/mongoose-query-find/issues)
1606
+
1607
+ ---
1608
+
1609
+ ## License
1610
+
1611
+ ISC © [jsdev.robin@gmail.com](mailto:jsdev.robin@gmail.com)
1612
+
1613
+ <br>
1614
+ <br>
1615
+
1616
+ ---
1617
+
1618
+ ---
1619
+
1
1620
  # QueryAnalytics
2
1621
 
3
1622
  A purpose-built analytics/reporting layer for Mongoose (`^8 || ^9`), sitting alongside `QueryFind` and `QueryAggregate`. Where `QueryAggregate` is a general-purpose, client-input-safe pipeline builder, `QueryAnalytics` is a **server-authored dashboard toolkit**: time series, cohort retention, funnels, sessionization, percentiles, and more, each backed by a native MongoDB 7.0+ operator instead of a hand-rolled pipeline.