mongoose-query-find 2.1.0 → 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 +113 -53
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +415 -161
- 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,249 +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;
|
|
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;
|
|
104
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).
|
|
280
|
+
* Production-grade fluent query builder / paginator for Mongoose 8/9.
|
|
117
281
|
*
|
|
118
282
|
* @example
|
|
119
|
-
*
|
|
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 })
|
|
120
287
|
* .filter()
|
|
121
|
-
* .
|
|
288
|
+
* .globalSearch(['name', 'email'])
|
|
122
289
|
* .sort()
|
|
123
|
-
* .limitFields('-__v')
|
|
124
|
-
* .populate('
|
|
125
|
-
* .populate({ path: 'comments', select: 'text createdAt' })
|
|
290
|
+
* .limitFields('-password -__v')
|
|
291
|
+
* .populate('department', 'name')
|
|
126
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.
|
|
127
303
|
*/
|
|
128
304
|
class QueryFind {
|
|
129
|
-
constructor(query, queryString) {
|
|
130
|
-
|
|
131
|
-
this.
|
|
132
|
-
|
|
133
|
-
this.
|
|
134
|
-
|
|
135
|
-
this.selectQuery = null;
|
|
136
|
-
/** Accumulated populate options — each call to `populate()` appends here. */
|
|
137
|
-
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 = [];
|
|
138
311
|
this.model = query.model;
|
|
139
|
-
this.
|
|
312
|
+
this.qs = Object.freeze({ ...queryString });
|
|
313
|
+
this.options = {
|
|
314
|
+
maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
// ── Configuration ───────────────────────────────────────────────────────────
|
|
318
|
+
/**
|
|
319
|
+
* Declare which fields may appear in URL filters, sort, and projection.
|
|
320
|
+
* Call before `.filter()`, `.sort()`, and `.limitFields()`.
|
|
321
|
+
*/
|
|
322
|
+
allowFields(fields) {
|
|
323
|
+
this._allowedFields = new Set(fields);
|
|
324
|
+
return this;
|
|
140
325
|
}
|
|
141
326
|
// ── Builder methods ─────────────────────────────────────────────────────────
|
|
142
|
-
/** Parse
|
|
327
|
+
/** Parse URL query params into a Mongoose filter (respects allowlist). */
|
|
143
328
|
filter() {
|
|
144
|
-
const parsed =
|
|
145
|
-
this.
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
329
|
+
const parsed = buildFilter(this.qs, this._allowedFields);
|
|
330
|
+
Object.assign(this._filter, parsed);
|
|
331
|
+
return this;
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
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 })
|
|
338
|
+
*/
|
|
339
|
+
where(conditions) {
|
|
340
|
+
Object.assign(this._filter, conditions);
|
|
149
341
|
return this;
|
|
150
342
|
}
|
|
151
343
|
/**
|
|
152
|
-
*
|
|
153
|
-
*
|
|
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`.
|
|
154
347
|
*/
|
|
155
|
-
|
|
156
|
-
const
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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;
|
|
161
370
|
}
|
|
162
371
|
return this;
|
|
163
372
|
}
|
|
164
373
|
/**
|
|
165
|
-
*
|
|
166
|
-
*
|
|
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.
|
|
167
377
|
*/
|
|
168
378
|
sort() {
|
|
169
|
-
if (this.
|
|
170
|
-
|
|
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 };
|
|
171
383
|
}
|
|
172
384
|
return this;
|
|
173
385
|
}
|
|
174
386
|
/**
|
|
175
387
|
* Configure field projection.
|
|
388
|
+
* Priority: `?fields=` query param > `defaultFields` argument > no projection.
|
|
176
389
|
*
|
|
177
|
-
*
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
* 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`.
|
|
181
393
|
*
|
|
182
|
-
* @param defaultFields -
|
|
183
|
-
*
|
|
184
|
-
* `?fields=` query param.
|
|
394
|
+
* @param defaultFields e.g. `'-password -__v'` — always excluded when the
|
|
395
|
+
* client does not supply `?fields=`.
|
|
185
396
|
*/
|
|
186
397
|
limitFields(defaultFields) {
|
|
187
|
-
if (this.
|
|
188
|
-
|
|
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);
|
|
189
405
|
}
|
|
190
406
|
else if (defaultFields) {
|
|
191
|
-
this.
|
|
407
|
+
this._select = defaultFields;
|
|
192
408
|
}
|
|
193
409
|
return this;
|
|
194
410
|
}
|
|
195
411
|
/**
|
|
196
|
-
* Register a populate
|
|
197
|
-
* multiple paths — each call appends to the internal list.
|
|
412
|
+
* Register a populate path. Chainable; all entries applied in `paginate()`.
|
|
198
413
|
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* All registered populates are applied inside `paginate()` after the
|
|
205
|
-
* `find` query is built — core filter / sort / pagination logic is
|
|
206
|
-
* completely untouched.
|
|
207
|
-
*
|
|
208
|
-
* @param path - Field path to populate, or a full `PopulateOptions` object.
|
|
209
|
-
* @param select - Optional field projection for the populated documents
|
|
210
|
-
* (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 } })
|
|
211
418
|
*/
|
|
212
419
|
populate(path, select) {
|
|
213
420
|
if (typeof path === 'string') {
|
|
214
|
-
|
|
215
|
-
if (select)
|
|
216
|
-
opt.select = select;
|
|
217
|
-
this.populateOptions.push(opt);
|
|
421
|
+
this._populates.push(select ? { path, select } : { path });
|
|
218
422
|
}
|
|
219
423
|
else {
|
|
220
|
-
this.
|
|
424
|
+
this._populates.push(path);
|
|
221
425
|
}
|
|
222
426
|
return this;
|
|
223
427
|
}
|
|
224
|
-
// ── Terminal
|
|
428
|
+
// ── Terminal ────────────────────────────────────────────────────────────────
|
|
225
429
|
/**
|
|
226
|
-
* Execute
|
|
430
|
+
* Execute and return a paginated result.
|
|
227
431
|
*
|
|
228
|
-
*
|
|
229
|
-
*
|
|
230
|
-
*
|
|
231
|
-
*
|
|
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).
|
|
232
437
|
*
|
|
233
|
-
*
|
|
234
|
-
* page 1 is returned instead so the caller always receives valid data.
|
|
438
|
+
* @throws {QueryFindValidationError} on disallowed $ operators in the URL.
|
|
235
439
|
*/
|
|
236
440
|
async paginate() {
|
|
237
|
-
const page =
|
|
238
|
-
const limit =
|
|
239
|
-
|
|
240
|
-
const
|
|
241
|
-
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);
|
|
242
476
|
const safePage = page > totalPages ? 1 : page;
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
for (const opt of this.populateOptions) {
|
|
255
|
-
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
|
+
};
|
|
256
488
|
}
|
|
257
|
-
|
|
489
|
+
// Otherwise fetch the correct page (skip already known)
|
|
490
|
+
const data = await buildFind((safePage - 1) * limit);
|
|
258
491
|
return {
|
|
259
|
-
data
|
|
492
|
+
data,
|
|
260
493
|
total,
|
|
261
494
|
page: safePage,
|
|
262
495
|
totalPages,
|
|
263
496
|
limit,
|
|
497
|
+
hasNextPage: safePage < totalPages,
|
|
498
|
+
hasPrevPage: safePage > 1,
|
|
264
499
|
};
|
|
265
500
|
}
|
|
266
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;
|
|
267
521
|
exports.default = QueryFind;
|
|
268
522
|
//# sourceMappingURL=index.js.map
|