mongoose-query-find 2.1.1 → 3.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +136 -50
- package/dist/index.d.ts +116 -61
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +460 -173
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -1,18 +1,102 @@
|
|
|
1
1
|
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* @file query-find.ts
|
|
4
|
+
* @description Production-grade fluent query builder for Mongoose 8.x / 9.x.
|
|
5
|
+
* @requires mongoose ^8.0.0 || ^9.0.0
|
|
6
|
+
*
|
|
7
|
+
* Features:
|
|
8
|
+
* - URL query string → Mongoose filter (sanitized, validated, coerced)
|
|
9
|
+
* - Global full-text search via $or regex
|
|
10
|
+
* - Flexible sort, field projection, and populate
|
|
11
|
+
* - count + find run fully in parallel (Promise.all)
|
|
12
|
+
* - Hard limits on page size, sort fields, search length, nesting depth (DoS protection)
|
|
13
|
+
* - Allowlist-based field filtering on filters, sort, AND projection (NoSQL injection prevention)
|
|
14
|
+
* - Deep recursive operator validation (catches nested $where, $expr, etc.)
|
|
15
|
+
* - Deep recursive boolean coercion (handles nested query objects)
|
|
16
|
+
* - Deep recursive operator-key coercion (eq/ne/gt/... → $eq/$ne/$gt/...), applied
|
|
17
|
+
* ONLY to object keys — never to string values (fixes JSON-string regex bug)
|
|
18
|
+
* - estimatedDocumentCount fast-path when no filter is applied
|
|
19
|
+
* - Query timeout via maxTimeMS (prevents runaway queries)
|
|
20
|
+
* - Structured error types for clean upstream handling
|
|
21
|
+
* - Zero external runtime dependencies beyond mongoose
|
|
22
|
+
*/
|
|
2
23
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
24
|
+
exports.queryFind = exports.QueryFind = exports.QueryFindValidationError = exports.QueryFindError = void 0;
|
|
25
|
+
// ─── Constants ────────────────────────────────────────────────────────────────
|
|
26
|
+
const RESERVED_KEYS = new Set(['page', 'sort', 'limit', 'fields', 'q']);
|
|
27
|
+
/** Hard cap — prevents clients from dumping the whole collection. */
|
|
28
|
+
const MAX_LIMIT = 100;
|
|
29
|
+
/** Hard cap — prevents DoS via ?a[b][c][d][e][f]=1 */
|
|
30
|
+
const MAX_NESTING_DEPTH = 5;
|
|
31
|
+
/** Hard cap — prevents compiling huge regexes from ?q= */
|
|
32
|
+
const MAX_SEARCH_LENGTH = 200;
|
|
33
|
+
/** Hard cap — prevents abuse via ?sort=a,b,c,d,e,f,... */
|
|
34
|
+
const MAX_SORT_FIELDS = 5;
|
|
35
|
+
/** Default query timeout in milliseconds — prevents runaway scans on unindexed fields. */
|
|
36
|
+
const DEFAULT_MAX_TIME_MS = 5000;
|
|
37
|
+
const DATE_FIELD_RE = /(^|\.)(createdAt|updatedAt|deletedAt|date|birthDate|expiresAt)$/i;
|
|
38
|
+
const PLAIN_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
39
|
+
/**
|
|
40
|
+
* Mongo comparison/array operator names accepted WITHOUT a leading "$" in
|
|
41
|
+
* the URL query string (e.g. `?age[gte]=18` → `{ age: { $gte: 18 } }`).
|
|
42
|
+
* Only ever applied to OBJECT KEYS during the recursive coercion pass —
|
|
43
|
+
* never to string values — so a value like `?name=eq` is left untouched.
|
|
44
|
+
*/
|
|
45
|
+
const COERCIBLE_OPS = new Set([
|
|
46
|
+
'eq',
|
|
47
|
+
'ne',
|
|
48
|
+
'gt',
|
|
49
|
+
'gte',
|
|
50
|
+
'lt',
|
|
51
|
+
'lte',
|
|
52
|
+
'in',
|
|
53
|
+
'nin',
|
|
54
|
+
]);
|
|
55
|
+
const DEFAULT_SORT = Object.freeze({ createdAt: -1 });
|
|
56
|
+
const ALLOWED_TOP_LEVEL_OPS = new Set(['$and', '$or', '$nor', '$not']);
|
|
8
57
|
/**
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
* instance, function, symbol, or undefined — which prevents circular-
|
|
12
|
-
* reference errors when req.query accidentally contains Mongoose/Express
|
|
13
|
-
* internal objects.
|
|
58
|
+
* Operators that are never permitted anywhere in a client-supplied filter,
|
|
59
|
+
* regardless of nesting depth. Catches $where, $expr, $function, etc.
|
|
14
60
|
*/
|
|
15
|
-
|
|
61
|
+
const BANNED_OPERATORS = new Set([
|
|
62
|
+
'$where',
|
|
63
|
+
'$expr',
|
|
64
|
+
'$function',
|
|
65
|
+
'$accumulator',
|
|
66
|
+
'$map',
|
|
67
|
+
'$reduce',
|
|
68
|
+
'$filter',
|
|
69
|
+
]);
|
|
70
|
+
// ─── Errors ───────────────────────────────────────────────────────────────────
|
|
71
|
+
class QueryFindError extends Error {
|
|
72
|
+
constructor(message) {
|
|
73
|
+
super(message);
|
|
74
|
+
this.name = 'QueryFindError';
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
exports.QueryFindError = QueryFindError;
|
|
78
|
+
class QueryFindValidationError extends QueryFindError {
|
|
79
|
+
constructor(message) {
|
|
80
|
+
super(message);
|
|
81
|
+
this.name = 'QueryFindValidationError';
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
exports.QueryFindValidationError = QueryFindValidationError;
|
|
85
|
+
// ─── Input parsing ────────────────────────────────────────────────────────────
|
|
86
|
+
function parsePage(raw) {
|
|
87
|
+
const n = parseInt(raw ?? '1', 10);
|
|
88
|
+
return isNaN(n) || n < 1 ? 1 : n;
|
|
89
|
+
}
|
|
90
|
+
function parseLimit(raw) {
|
|
91
|
+
const n = parseInt(raw ?? '10', 10);
|
|
92
|
+
if (isNaN(n) || n < 1)
|
|
93
|
+
return 10;
|
|
94
|
+
return Math.min(n, MAX_LIMIT);
|
|
95
|
+
}
|
|
96
|
+
// ─── Sanitization ─────────────────────────────────────────────────────────────
|
|
97
|
+
function sanitize(value, depth = 0) {
|
|
98
|
+
if (depth > MAX_NESTING_DEPTH)
|
|
99
|
+
return undefined;
|
|
16
100
|
if (value === null ||
|
|
17
101
|
typeof value === 'string' ||
|
|
18
102
|
typeof value === 'number' ||
|
|
@@ -20,264 +104,467 @@ function sanitize(value) {
|
|
|
20
104
|
return value;
|
|
21
105
|
}
|
|
22
106
|
if (Array.isArray(value)) {
|
|
23
|
-
|
|
107
|
+
const out = [];
|
|
108
|
+
for (const item of value) {
|
|
109
|
+
const s = sanitize(item, depth + 1);
|
|
110
|
+
if (s !== undefined)
|
|
111
|
+
out.push(s);
|
|
112
|
+
}
|
|
113
|
+
return out;
|
|
24
114
|
}
|
|
25
115
|
if (typeof value === 'object' &&
|
|
26
116
|
Object.getPrototypeOf(value) === Object.prototype) {
|
|
27
|
-
const
|
|
117
|
+
const out = {};
|
|
28
118
|
for (const [k, v] of Object.entries(value)) {
|
|
29
|
-
const
|
|
30
|
-
if (
|
|
31
|
-
|
|
32
|
-
}
|
|
119
|
+
const s = sanitize(v, depth + 1);
|
|
120
|
+
if (s !== undefined)
|
|
121
|
+
out[k] = s;
|
|
33
122
|
}
|
|
34
|
-
return
|
|
123
|
+
return out;
|
|
35
124
|
}
|
|
36
|
-
// Drop class instances, functions, symbols, undefined, etc.
|
|
37
125
|
return undefined;
|
|
38
126
|
}
|
|
127
|
+
// ─── Allowlist ────────────────────────────────────────────────────────────────
|
|
128
|
+
function enforceAllowlist(filter, allowedFields) {
|
|
129
|
+
if (allowedFields.size === 0)
|
|
130
|
+
return filter;
|
|
131
|
+
const out = {};
|
|
132
|
+
for (const [k, v] of Object.entries(filter)) {
|
|
133
|
+
if (k.startsWith('$') || allowedFields.has(k))
|
|
134
|
+
out[k] = v;
|
|
135
|
+
}
|
|
136
|
+
return out;
|
|
137
|
+
}
|
|
138
|
+
// ─── Operator-key coercion ────────────────────────────────────────────────────
|
|
39
139
|
/**
|
|
40
|
-
*
|
|
41
|
-
*
|
|
140
|
+
* Recursively walks a parsed (sanitized) object/array tree and rewrites
|
|
141
|
+
* plain operator-like KEYS (eq, ne, gt, gte, lt, lte, in, nin) to their
|
|
142
|
+
* "$"-prefixed Mongo equivalents (e.g. `{ age: { gte: 18 } }` →
|
|
143
|
+
* `{ age: { $gte: 18 } }`).
|
|
144
|
+
*
|
|
145
|
+
* This replaces the previous implementation, which ran a regex over the
|
|
146
|
+
* JSON-stringified filter and rewrote ANY occurrence of these words —
|
|
147
|
+
* including inside string VALUES (e.g. `?name=eq` or `?status=in`),
|
|
148
|
+
* silently corrupting user data into Mongo operators. By operating on the
|
|
149
|
+
* parsed object tree and only ever touching object KEYS, string values are
|
|
150
|
+
* never inspected or mutated.
|
|
42
151
|
*/
|
|
43
|
-
function
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
152
|
+
function coerceOperatorKeys(value) {
|
|
153
|
+
if (Array.isArray(value)) {
|
|
154
|
+
return value.map((item) => coerceOperatorKeys(item));
|
|
155
|
+
}
|
|
156
|
+
if (value !== null &&
|
|
157
|
+
typeof value === 'object' &&
|
|
158
|
+
!(value instanceof Date) &&
|
|
159
|
+
Object.getPrototypeOf(value) === Object.prototype) {
|
|
160
|
+
const out = {};
|
|
161
|
+
for (const [k, v] of Object.entries(value)) {
|
|
162
|
+
const newKey = COERCIBLE_OPS.has(k) ? `$${k}` : k;
|
|
163
|
+
out[newKey] = coerceOperatorKeys(v);
|
|
164
|
+
}
|
|
165
|
+
return out;
|
|
166
|
+
}
|
|
167
|
+
return value;
|
|
51
168
|
}
|
|
52
|
-
//
|
|
53
|
-
const DATE_FIELD_RE = /(^|\.)(createdAt|updatedAt|deletedAt|date|Date)$/;
|
|
169
|
+
// ─── Type coercion ────────────────────────────────────────────────────────────
|
|
54
170
|
/**
|
|
55
|
-
* Recursively
|
|
56
|
-
*
|
|
57
|
-
*
|
|
58
|
-
* Handles both plain strings and MongoDB operator objects, e.g.:
|
|
59
|
-
* ?createdAt=2024-01-01 → { createdAt: { $gte: Date, $lt: Date } }
|
|
60
|
-
* ?createdAt[$gte]=2024-01-01 → { createdAt: { $gte: Date } }
|
|
171
|
+
* Recursively coerces string 'true'/'false' to booleans at any nesting depth.
|
|
172
|
+
* Fixes the original shallow-only implementation.
|
|
61
173
|
*/
|
|
174
|
+
function coerceBooleans(value) {
|
|
175
|
+
if (value === 'true')
|
|
176
|
+
return true;
|
|
177
|
+
if (value === 'false')
|
|
178
|
+
return false;
|
|
179
|
+
if (Array.isArray(value)) {
|
|
180
|
+
return value.map((item) => coerceBooleans(item));
|
|
181
|
+
}
|
|
182
|
+
if (value !== null &&
|
|
183
|
+
typeof value === 'object' &&
|
|
184
|
+
!(value instanceof Date) &&
|
|
185
|
+
Object.getPrototypeOf(value) === Object.prototype) {
|
|
186
|
+
const out = {};
|
|
187
|
+
for (const [k, v] of Object.entries(value)) {
|
|
188
|
+
out[k] = coerceBooleans(v);
|
|
189
|
+
}
|
|
190
|
+
return out;
|
|
191
|
+
}
|
|
192
|
+
return value;
|
|
193
|
+
}
|
|
62
194
|
function coerceDates(obj, parentKey = '') {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
195
|
+
const out = {};
|
|
196
|
+
for (const [k, v] of Object.entries(obj)) {
|
|
197
|
+
const isOp = k.startsWith('$');
|
|
198
|
+
const path = isOp ? parentKey : parentKey ? `${parentKey}.${k}` : k;
|
|
66
199
|
if (v !== null &&
|
|
67
200
|
typeof v === 'object' &&
|
|
68
201
|
!Array.isArray(v) &&
|
|
69
202
|
!(v instanceof Date)) {
|
|
70
|
-
|
|
71
|
-
|
|
203
|
+
out[k] = coerceDates(v, path);
|
|
204
|
+
continue;
|
|
72
205
|
}
|
|
73
|
-
// Coerce string → Date when key matches a date field pattern
|
|
74
206
|
if (typeof v === 'string' && DATE_FIELD_RE.test(path)) {
|
|
75
207
|
const parsed = new Date(v);
|
|
76
|
-
if (isNaN(parsed.getTime()))
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
208
|
+
if (isNaN(parsed.getTime())) {
|
|
209
|
+
// Leave unparseable strings as-is; Mongoose CastError → 400 upstream.
|
|
210
|
+
out[k] = v;
|
|
211
|
+
continue;
|
|
212
|
+
}
|
|
213
|
+
if (PLAIN_DATE_RE.test(v)) {
|
|
81
214
|
const start = new Date(v);
|
|
82
215
|
const end = new Date(start);
|
|
83
216
|
end.setUTCDate(end.getUTCDate() + 1);
|
|
84
|
-
|
|
217
|
+
out[k] = { $gte: start, $lt: end };
|
|
218
|
+
continue;
|
|
85
219
|
}
|
|
86
|
-
|
|
220
|
+
out[k] = parsed;
|
|
221
|
+
continue;
|
|
87
222
|
}
|
|
88
|
-
|
|
89
|
-
}
|
|
223
|
+
out[k] = v;
|
|
224
|
+
}
|
|
225
|
+
return out;
|
|
90
226
|
}
|
|
227
|
+
// ─── Operator validation ──────────────────────────────────────────────────────
|
|
91
228
|
/**
|
|
92
|
-
*
|
|
93
|
-
*
|
|
94
|
-
*
|
|
229
|
+
* Recursively walks the entire filter tree and throws on:
|
|
230
|
+
* 1. Banned operators at any depth ($where, $expr, $function, etc.)
|
|
231
|
+
* 2. Unknown top-level $ operators (only $and/$or/$nor/$not allowed at root)
|
|
232
|
+
*
|
|
233
|
+
* Fixes the original shallow-only check.
|
|
95
234
|
*/
|
|
96
|
-
function
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
235
|
+
function rejectDisallowedOperators(filter, depth = 0) {
|
|
236
|
+
for (const [k, v] of Object.entries(filter)) {
|
|
237
|
+
// Always banned at any depth
|
|
238
|
+
if (BANNED_OPERATORS.has(k)) {
|
|
239
|
+
throw new QueryFindValidationError(`Disallowed operator in query: "${k}"`);
|
|
240
|
+
}
|
|
241
|
+
// Top-level unknown $ operators
|
|
242
|
+
if (depth === 0 && k.startsWith('$') && !ALLOWED_TOP_LEVEL_OPS.has(k)) {
|
|
243
|
+
throw new QueryFindValidationError(`Disallowed top-level operator in query string: "${k}"`);
|
|
244
|
+
}
|
|
245
|
+
// Recurse into nested objects
|
|
246
|
+
if (Array.isArray(v)) {
|
|
247
|
+
for (const item of v) {
|
|
248
|
+
if (item !== null &&
|
|
249
|
+
typeof item === 'object' &&
|
|
250
|
+
!Array.isArray(item) &&
|
|
251
|
+
!(item instanceof Date)) {
|
|
252
|
+
rejectDisallowedOperators(item, depth + 1);
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
else if (v !== null &&
|
|
257
|
+
typeof v === 'object' &&
|
|
258
|
+
!(v instanceof Date) &&
|
|
259
|
+
Object.getPrototypeOf(v) === Object.prototype) {
|
|
260
|
+
rejectDisallowedOperators(v, depth + 1);
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
// ─── Filter builder ───────────────────────────────────────────────────────────
|
|
265
|
+
function buildFilter(raw, allowedFields) {
|
|
266
|
+
const stripped = {};
|
|
267
|
+
for (const [k, v] of Object.entries(raw)) {
|
|
268
|
+
if (!RESERVED_KEYS.has(k))
|
|
269
|
+
stripped[k] = v;
|
|
270
|
+
}
|
|
100
271
|
const safe = sanitize(stripped);
|
|
101
|
-
// Rewrite bare operator
|
|
102
|
-
|
|
103
|
-
|
|
272
|
+
// Rewrite bare operator keys (eq/ne/gt/...) to "$"-prefixed Mongo
|
|
273
|
+
// operators. Operates on parsed object KEYS only — string values
|
|
274
|
+
// (e.g. ?status=in, ?name=eq) are never touched.
|
|
275
|
+
const withOps = coerceOperatorKeys(safe);
|
|
276
|
+
const coerced = coerceDates(coerceBooleans(withOps));
|
|
277
|
+
const allowed = enforceAllowlist(coerced, allowedFields);
|
|
278
|
+
rejectDisallowedOperators(allowed);
|
|
279
|
+
return allowed;
|
|
104
280
|
}
|
|
281
|
+
// ─── Sort parser ──────────────────────────────────────────────────────────────
|
|
282
|
+
function parseSort(sort, allowedFields) {
|
|
283
|
+
const out = {};
|
|
284
|
+
let count = 0;
|
|
285
|
+
for (const token of sort.split(',')) {
|
|
286
|
+
if (count >= MAX_SORT_FIELDS)
|
|
287
|
+
break;
|
|
288
|
+
const trimmed = token.trim();
|
|
289
|
+
if (!trimmed || trimmed === '-')
|
|
290
|
+
continue;
|
|
291
|
+
const desc = trimmed.startsWith('-');
|
|
292
|
+
const field = desc ? trimmed.slice(1).trim() : trimmed;
|
|
293
|
+
if (!field)
|
|
294
|
+
continue;
|
|
295
|
+
if (allowedFields.size > 0 && !allowedFields.has(field))
|
|
296
|
+
continue;
|
|
297
|
+
out[field] = desc ? -1 : 1;
|
|
298
|
+
count++;
|
|
299
|
+
}
|
|
300
|
+
return out;
|
|
301
|
+
}
|
|
302
|
+
// ─── Projection sanitizer ─────────────────────────────────────────────────────
|
|
105
303
|
/**
|
|
106
|
-
*
|
|
107
|
-
*
|
|
304
|
+
* Strips fields from a client-supplied projection that are not in the allowlist.
|
|
305
|
+
* Handles both inclusion ("name email") and exclusion ("-password -__v") syntax.
|
|
306
|
+
* Always permits _id and __v in exclusion projections.
|
|
307
|
+
* When allowedFields is empty, returns the projection unchanged.
|
|
108
308
|
*/
|
|
109
|
-
function
|
|
110
|
-
|
|
309
|
+
function sanitizeProjection(projection, allowedFields) {
|
|
310
|
+
if (allowedFields.size === 0)
|
|
311
|
+
return projection;
|
|
312
|
+
return projection
|
|
313
|
+
.split(/\s+/)
|
|
314
|
+
.filter((token) => {
|
|
315
|
+
if (!token)
|
|
316
|
+
return false;
|
|
317
|
+
const field = token.startsWith('-') ? token.slice(1) : token;
|
|
318
|
+
if (field === '__v' || field === '_id')
|
|
319
|
+
return true;
|
|
320
|
+
return allowedFields.has(field);
|
|
321
|
+
})
|
|
322
|
+
.join(' ');
|
|
111
323
|
}
|
|
112
324
|
// ─── QueryFind ────────────────────────────────────────────────────────────────
|
|
113
325
|
/**
|
|
114
|
-
*
|
|
115
|
-
* then paginates the result using two native `countDocuments` + `find` calls
|
|
116
|
-
* (no aggregation pipeline required).
|
|
117
|
-
*
|
|
118
|
-
* Base query conditions passed to the constructor (e.g. `Model.find({ role: 'admin' })`)
|
|
119
|
-
* are automatically preserved and merged with any additional filters applied
|
|
120
|
-
* via `.filter()` or `.globalFilter()`.
|
|
326
|
+
* Production-grade fluent query builder / paginator for Mongoose 8/9.
|
|
121
327
|
*
|
|
122
328
|
* @example
|
|
123
|
-
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
* )
|
|
329
|
+
* ```ts
|
|
330
|
+
* const result = await queryFind(User.find(), req.query)
|
|
331
|
+
* .allowFields(['name', 'email', 'role', 'createdAt'])
|
|
332
|
+
* .where({ orgId: req.user.orgId, deletedAt: null })
|
|
127
333
|
* .filter()
|
|
128
|
-
* .
|
|
334
|
+
* .globalSearch(['name', 'email'])
|
|
129
335
|
* .sort()
|
|
130
|
-
* .limitFields('-__v')
|
|
131
|
-
* .populate('
|
|
132
|
-
* .populate({ path: 'comments', select: 'text createdAt' })
|
|
336
|
+
* .limitFields('-password -__v')
|
|
337
|
+
* .populate('department', 'name')
|
|
133
338
|
* .paginate();
|
|
339
|
+
* ```
|
|
340
|
+
*
|
|
341
|
+
* Security notes:
|
|
342
|
+
* - `.allowFields()` before `.filter()` restricts which URL params reach Mongo.
|
|
343
|
+
* - `.where()` conditions are hard — URL cannot override them.
|
|
344
|
+
* - Unknown/banned $ operators throw QueryFindValidationError (checked recursively).
|
|
345
|
+
* - Nesting depth capped at 5; page size capped at 100; sort fields capped at 5.
|
|
346
|
+
* - Search terms are regex-escaped (ReDoS prevention) and length-capped at 200 chars.
|
|
347
|
+
* - ?fields= projection is allowlist-filtered to prevent sensitive field leakage.
|
|
348
|
+
* - Operator-key coercion (eq/gte/in/...) only touches object KEYS, never string
|
|
349
|
+
* VALUES — a search like ?name=eq or ?status=in cannot be corrupted into a
|
|
350
|
+
* Mongo operator.
|
|
351
|
+
* - All queries run with maxTimeMS to prevent runaway collection scans.
|
|
134
352
|
*/
|
|
135
353
|
class QueryFind {
|
|
136
|
-
constructor(query, queryString) {
|
|
137
|
-
|
|
138
|
-
this.
|
|
139
|
-
|
|
140
|
-
this.
|
|
141
|
-
|
|
142
|
-
this.selectQuery = null;
|
|
143
|
-
/** Accumulated populate options — each call to `populate()` appends here. */
|
|
144
|
-
this.populateOptions = [];
|
|
354
|
+
constructor(query, queryString, options = {}) {
|
|
355
|
+
this._allowedFields = new Set();
|
|
356
|
+
this._filter = {};
|
|
357
|
+
this._sort = { ...DEFAULT_SORT };
|
|
358
|
+
this._select = null;
|
|
359
|
+
this._populates = [];
|
|
145
360
|
this.model = query.model;
|
|
146
|
-
this.
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
this.filterQuery = { ...baseFilter };
|
|
151
|
-
}
|
|
361
|
+
this.qs = Object.freeze({ ...queryString });
|
|
362
|
+
this.options = {
|
|
363
|
+
maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
|
|
364
|
+
};
|
|
152
365
|
}
|
|
153
|
-
// ──
|
|
366
|
+
// ── Configuration ───────────────────────────────────────────────────────────
|
|
154
367
|
/**
|
|
155
|
-
*
|
|
156
|
-
*
|
|
368
|
+
* Declare which fields may appear in URL filters, sort, and projection.
|
|
369
|
+
* Call before `.filter()`, `.sort()`, and `.limitFields()`.
|
|
157
370
|
*/
|
|
371
|
+
allowFields(fields) {
|
|
372
|
+
this._allowedFields = new Set(fields);
|
|
373
|
+
return this;
|
|
374
|
+
}
|
|
375
|
+
// ── Builder methods ─────────────────────────────────────────────────────────
|
|
376
|
+
/** Parse URL query params into a Mongoose filter (respects allowlist). */
|
|
158
377
|
filter() {
|
|
159
|
-
const parsed =
|
|
160
|
-
this.
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
378
|
+
const parsed = buildFilter(this.qs, this._allowedFields);
|
|
379
|
+
Object.assign(this._filter, parsed);
|
|
380
|
+
return this;
|
|
381
|
+
}
|
|
382
|
+
/**
|
|
383
|
+
* Apply mandatory server-side conditions the URL cannot override.
|
|
384
|
+
* Use for multi-tenancy, soft-delete exclusion, etc.
|
|
385
|
+
*
|
|
386
|
+
* @example .where({ orgId: req.user.orgId, deletedAt: null })
|
|
387
|
+
*/
|
|
388
|
+
where(conditions) {
|
|
389
|
+
Object.assign(this._filter, conditions);
|
|
164
390
|
return this;
|
|
165
391
|
}
|
|
166
392
|
/**
|
|
167
|
-
*
|
|
168
|
-
*
|
|
393
|
+
* Case-insensitive full-text search across `fields` when `?q=` is present.
|
|
394
|
+
* Search term is regex-escaped (ReDoS prevention) and capped at 200 chars.
|
|
395
|
+
* Preserves any existing `$or` by lifting both into `$and`.
|
|
169
396
|
*/
|
|
170
|
-
|
|
171
|
-
const
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
397
|
+
globalSearch(fields) {
|
|
398
|
+
const raw = this.qs.q?.trim();
|
|
399
|
+
// Guard: missing, empty, or oversized search term
|
|
400
|
+
if (!raw || raw.length > MAX_SEARCH_LENGTH || fields.length === 0) {
|
|
401
|
+
return this;
|
|
402
|
+
}
|
|
403
|
+
const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
404
|
+
const searchOr = fields.map((field) => ({
|
|
405
|
+
[field]: { $regex: escaped, $options: 'i' },
|
|
406
|
+
}));
|
|
407
|
+
// Always AND the search clause with whatever conditions are already
|
|
408
|
+
// present (top-level fields from .where()/.filter(), or existing
|
|
409
|
+
// $or/$and). This avoids the bug where a top-level field that
|
|
410
|
+
// happens to also be one of the `fields` passed here (e.g.
|
|
411
|
+
// ?status=active combined with .globalSearch(['status','name']))
|
|
412
|
+
// would sit alongside $or and be implicitly ANDed with it — making
|
|
413
|
+
// the search match only documents where `status` is BOTH exactly
|
|
414
|
+
// "active" AND matches the regex, silently excluding matches on
|
|
415
|
+
// `name`. Wrapping the existing filter as one branch of $and
|
|
416
|
+
// preserves all prior conditions intact while ORing across the
|
|
417
|
+
// search fields independently.
|
|
418
|
+
if (Object.keys(this._filter).length > 0) {
|
|
419
|
+
this._filter = {
|
|
420
|
+
$and: [this._filter, { $or: searchOr }],
|
|
421
|
+
};
|
|
422
|
+
}
|
|
423
|
+
else {
|
|
424
|
+
this._filter = { $or: searchOr };
|
|
176
425
|
}
|
|
177
426
|
return this;
|
|
178
427
|
}
|
|
179
428
|
/**
|
|
180
|
-
*
|
|
181
|
-
*
|
|
429
|
+
* Apply sort from `?sort=`. Falls back to `{ createdAt: -1 }`.
|
|
430
|
+
* Fields not in the allowlist are silently skipped.
|
|
431
|
+
* Capped at MAX_SORT_FIELDS (5) fields.
|
|
182
432
|
*/
|
|
183
433
|
sort() {
|
|
184
|
-
if (this.
|
|
185
|
-
|
|
434
|
+
if (this.qs.sort) {
|
|
435
|
+
const parsed = parseSort(this.qs.sort, this._allowedFields);
|
|
436
|
+
this._sort =
|
|
437
|
+
Object.keys(parsed).length > 0 ? parsed : { ...DEFAULT_SORT };
|
|
186
438
|
}
|
|
187
439
|
return this;
|
|
188
440
|
}
|
|
189
441
|
/**
|
|
190
442
|
* Configure field projection.
|
|
443
|
+
* Priority: `?fields=` query param > `defaultFields` argument > no projection.
|
|
191
444
|
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
* 3. No projection at all when both are absent (all fields returned).
|
|
445
|
+
* When `allowFields()` has been called, any field in `?fields=` that is not
|
|
446
|
+
* in the allowlist is stripped — preventing clients from projecting sensitive
|
|
447
|
+
* fields like `password` or `resetToken`.
|
|
196
448
|
*
|
|
197
|
-
* @param defaultFields -
|
|
198
|
-
*
|
|
199
|
-
* `?fields=` query param.
|
|
449
|
+
* @param defaultFields e.g. `'-password -__v'` — always excluded when the
|
|
450
|
+
* client does not supply `?fields=`.
|
|
200
451
|
*/
|
|
201
452
|
limitFields(defaultFields) {
|
|
202
|
-
if (this.
|
|
203
|
-
|
|
453
|
+
if (this.qs.fields) {
|
|
454
|
+
const raw = this.qs.fields
|
|
455
|
+
.split(',')
|
|
456
|
+
.map((f) => f.trim())
|
|
457
|
+
.filter(Boolean)
|
|
458
|
+
.join(' ');
|
|
459
|
+
this._select = sanitizeProjection(raw, this._allowedFields);
|
|
204
460
|
}
|
|
205
461
|
else if (defaultFields) {
|
|
206
|
-
this.
|
|
462
|
+
this._select = defaultFields;
|
|
207
463
|
}
|
|
208
464
|
return this;
|
|
209
465
|
}
|
|
210
466
|
/**
|
|
211
|
-
* Register a populate
|
|
212
|
-
* multiple paths — each call appends to the internal list.
|
|
213
|
-
*
|
|
214
|
-
* Accepts the same arguments as Mongoose's own `.populate()`:
|
|
215
|
-
* - A plain path string: `.populate('author')`
|
|
216
|
-
* - A path + select string: `.populate('author', 'name email')`
|
|
217
|
-
* - A full `PopulateOptions` object: `.populate({ path: 'comments', select: 'text', match: { visible: true } })`
|
|
467
|
+
* Register a populate path. Chainable; all entries applied in `paginate()`.
|
|
218
468
|
*
|
|
219
|
-
*
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
* @param path - Field path to populate, or a full `PopulateOptions` object.
|
|
224
|
-
* @param select - Optional field projection for the populated documents
|
|
225
|
-
* (only used when `path` is a plain string).
|
|
469
|
+
* @example
|
|
470
|
+
* .populate('author')
|
|
471
|
+
* .populate('author', 'name avatar')
|
|
472
|
+
* .populate({ path: 'comments', select: 'text', match: { visible: true } })
|
|
226
473
|
*/
|
|
227
474
|
populate(path, select) {
|
|
228
475
|
if (typeof path === 'string') {
|
|
229
|
-
|
|
230
|
-
if (select)
|
|
231
|
-
opt.select = select;
|
|
232
|
-
this.populateOptions.push(opt);
|
|
476
|
+
this._populates.push(select ? { path, select } : { path });
|
|
233
477
|
}
|
|
234
478
|
else {
|
|
235
|
-
this.
|
|
479
|
+
this._populates.push(path);
|
|
236
480
|
}
|
|
237
481
|
return this;
|
|
238
482
|
}
|
|
239
|
-
// ── Terminal
|
|
483
|
+
// ── Terminal ────────────────────────────────────────────────────────────────
|
|
240
484
|
/**
|
|
241
|
-
* Execute
|
|
485
|
+
* Execute and return a paginated result.
|
|
242
486
|
*
|
|
243
|
-
*
|
|
244
|
-
*
|
|
245
|
-
*
|
|
246
|
-
*
|
|
487
|
+
* - count + find run fully in parallel via Promise.all (saves one round-trip).
|
|
488
|
+
* - Uses estimatedDocumentCount fast-path when no filter is applied (O(1)).
|
|
489
|
+
* - .lean() returns plain objects (~3-5× faster for read-only responses).
|
|
490
|
+
* - maxTimeMS applied to both count and find (prevents runaway scans).
|
|
491
|
+
* - page is clamped to 1 if it exceeds totalPages (safe mid-delete behavior).
|
|
247
492
|
*
|
|
248
|
-
*
|
|
249
|
-
* page 1 is returned instead so the caller always receives valid data.
|
|
493
|
+
* @throws {QueryFindValidationError} on disallowed $ operators in the URL.
|
|
250
494
|
*/
|
|
251
495
|
async paginate() {
|
|
252
|
-
const page =
|
|
253
|
-
const limit =
|
|
254
|
-
|
|
255
|
-
const
|
|
256
|
-
const
|
|
496
|
+
const page = parsePage(this.qs.page);
|
|
497
|
+
const limit = parseLimit(this.qs.limit);
|
|
498
|
+
const mongoFilter = this._filter;
|
|
499
|
+
const hasFilter = Object.keys(this._filter).length > 0;
|
|
500
|
+
const { maxTimeMS } = this.options;
|
|
501
|
+
const buildFind = (skip) => {
|
|
502
|
+
const q = this.model
|
|
503
|
+
.find(mongoFilter)
|
|
504
|
+
.sort(this._sort)
|
|
505
|
+
.skip(skip)
|
|
506
|
+
.limit(limit)
|
|
507
|
+
.lean();
|
|
508
|
+
if (this._select)
|
|
509
|
+
q.select(this._select);
|
|
510
|
+
for (const opt of this._populates)
|
|
511
|
+
q.populate(opt);
|
|
512
|
+
if (maxTimeMS > 0)
|
|
513
|
+
q.maxTimeMS(maxTimeMS);
|
|
514
|
+
return q.exec();
|
|
515
|
+
};
|
|
516
|
+
const countQuery = hasFilter
|
|
517
|
+
? this.model
|
|
518
|
+
.countDocuments(mongoFilter)
|
|
519
|
+
.maxTimeMS(maxTimeMS)
|
|
520
|
+
: this.model.estimatedDocumentCount();
|
|
521
|
+
const [total, firstPageData] = await Promise.all([
|
|
522
|
+
countQuery,
|
|
523
|
+
buildFind(0),
|
|
524
|
+
]);
|
|
525
|
+
const totalPages = Math.max(Math.ceil(total / limit), 1);
|
|
257
526
|
const safePage = page > totalPages ? 1 : page;
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
527
|
+
if (safePage === 1) {
|
|
528
|
+
return {
|
|
529
|
+
data: firstPageData,
|
|
530
|
+
total,
|
|
531
|
+
page: 1,
|
|
532
|
+
totalPages,
|
|
533
|
+
limit,
|
|
534
|
+
hasNextPage: 1 < totalPages,
|
|
535
|
+
hasPrevPage: false,
|
|
536
|
+
};
|
|
267
537
|
}
|
|
268
|
-
|
|
269
|
-
for (const opt of this.populateOptions) {
|
|
270
|
-
findQuery.populate(opt);
|
|
271
|
-
}
|
|
272
|
-
const data = await findQuery.exec();
|
|
538
|
+
const data = await buildFind((safePage - 1) * limit);
|
|
273
539
|
return {
|
|
274
|
-
data
|
|
540
|
+
data,
|
|
275
541
|
total,
|
|
276
542
|
page: safePage,
|
|
277
543
|
totalPages,
|
|
278
544
|
limit,
|
|
545
|
+
hasNextPage: safePage < totalPages,
|
|
546
|
+
hasPrevPage: safePage > 1,
|
|
279
547
|
};
|
|
280
548
|
}
|
|
281
549
|
}
|
|
550
|
+
exports.QueryFind = QueryFind;
|
|
551
|
+
// ─── Factory ──────────────────────────────────────────────────────────────────
|
|
552
|
+
/**
|
|
553
|
+
* Convenience factory — avoids `new` at the call site.
|
|
554
|
+
*
|
|
555
|
+
* @example
|
|
556
|
+
* const result = await queryFind(User.find(), req.query, { maxTimeMS: 3000 })
|
|
557
|
+
* .allowFields(['name', 'email', 'createdAt'])
|
|
558
|
+
* .where({ deletedAt: null })
|
|
559
|
+
* .filter()
|
|
560
|
+
* .globalSearch(['name', 'email'])
|
|
561
|
+
* .sort()
|
|
562
|
+
* .limitFields('-password -__v')
|
|
563
|
+
* .paginate();
|
|
564
|
+
*/
|
|
565
|
+
function queryFind(query, queryString, options) {
|
|
566
|
+
return new QueryFind(query, queryString, options);
|
|
567
|
+
}
|
|
568
|
+
exports.queryFind = queryFind;
|
|
282
569
|
exports.default = QueryFind;
|
|
283
570
|
//# sourceMappingURL=index.js.map
|