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