mongoose-query-find 3.0.5 → 3.0.7
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 +468 -0
- package/dist/aggregate.d.ts +177 -0
- package/dist/aggregate.d.ts.map +1 -0
- package/dist/aggregate.js +733 -0
- package/dist/aggregate.js.map +1 -0
- package/dist/find.d.ts +243 -0
- package/dist/find.d.ts.map +1 -0
- package/dist/find.js +740 -0
- package/dist/find.js.map +1 -0
- package/dist/index.d.ts +2 -247
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -701
- package/dist/index.js.map +1 -1
- package/package.json +78 -65
package/dist/index.js
CHANGED
|
@@ -1,704 +1,8 @@
|
|
|
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) — no wasted round-trips
|
|
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
|
-
* - Case-insensitive allowlist matching (e.g. allowFields(['Name']) matches ?name=, ?NAME=, ?Name=)
|
|
15
|
-
* - Deep recursive operator validation (catches nested $where, $expr, etc.)
|
|
16
|
-
* - Deep recursive boolean coercion (handles nested query objects)
|
|
17
|
-
* - Deep recursive operator-key coercion (eq/ne/gt/... → $eq/$ne/$gt/...), applied
|
|
18
|
-
* ONLY to object keys — never to string values
|
|
19
|
-
* - estimatedDocumentCount fast-path when no filter is applied
|
|
20
|
-
* - Query timeout via maxTimeMS (prevents runaway queries)
|
|
21
|
-
* - Structured error types for clean upstream handling
|
|
22
|
-
* - Optional cached total for skipping re-count on page > 1
|
|
23
|
-
* - Optional slow-query hook for observability
|
|
24
|
-
* - Zero external runtime dependencies beyond mongoose
|
|
25
|
-
*/
|
|
26
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
27
|
-
exports.
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
const MAX_SEARCH_LENGTH = 200;
|
|
33
|
-
const MAX_SORT_FIELDS = 5;
|
|
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
|
-
const COERCIBLE_OPS = new Set([
|
|
38
|
-
'eq',
|
|
39
|
-
'ne',
|
|
40
|
-
'gt',
|
|
41
|
-
'gte',
|
|
42
|
-
'lt',
|
|
43
|
-
'lte',
|
|
44
|
-
'in',
|
|
45
|
-
'nin',
|
|
46
|
-
]);
|
|
47
|
-
// Never mutated in place — spread into a new object wherever a mutable copy is needed.
|
|
48
|
-
const DEFAULT_SORT = { createdAt: -1 };
|
|
49
|
-
const ALLOWED_TOP_LEVEL_OPS = new Set(['$and', '$or', '$nor', '$not']);
|
|
50
|
-
const BANNED_OPERATORS = new Set([
|
|
51
|
-
'$where',
|
|
52
|
-
'$expr',
|
|
53
|
-
'$function',
|
|
54
|
-
'$accumulator',
|
|
55
|
-
'$map',
|
|
56
|
-
'$reduce',
|
|
57
|
-
'$filter',
|
|
58
|
-
]);
|
|
59
|
-
// ─── Errors ───────────────────────────────────────────────────────────────────
|
|
60
|
-
class QueryFindError extends Error {
|
|
61
|
-
constructor(message) {
|
|
62
|
-
super(message);
|
|
63
|
-
this.name = 'QueryFindError';
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
exports.QueryFindError = QueryFindError;
|
|
67
|
-
class QueryFindValidationError extends QueryFindError {
|
|
68
|
-
constructor(message) {
|
|
69
|
-
super(message);
|
|
70
|
-
this.name = 'QueryFindValidationError';
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
exports.QueryFindValidationError = QueryFindValidationError;
|
|
74
|
-
// ─── Input parsing ────────────────────────────────────────────────────────────
|
|
75
|
-
function parsePage(raw) {
|
|
76
|
-
const n = parseInt(raw ?? '1', 10);
|
|
77
|
-
return isNaN(n) || n < 1 ? 1 : n;
|
|
78
|
-
}
|
|
79
|
-
function parseLimit(raw) {
|
|
80
|
-
const n = parseInt(raw ?? '10', 10);
|
|
81
|
-
if (isNaN(n) || n < 1)
|
|
82
|
-
return 10;
|
|
83
|
-
return Math.min(n, MAX_LIMIT);
|
|
84
|
-
}
|
|
85
|
-
// ─── Sanitization ─────────────────────────────────────────────────────────────
|
|
86
|
-
/**
|
|
87
|
-
* Recursively strips non-plain values (class instances, functions, Dates) from
|
|
88
|
-
* an arbitrary object so only JSON-safe primitives and plain objects reach the
|
|
89
|
-
* query pipeline. Notifies the caller via onDrop when values are removed.
|
|
90
|
-
*/
|
|
91
|
-
function sanitize(value, depth = 0, path = '', onDrop) {
|
|
92
|
-
if (depth > MAX_NESTING_DEPTH) {
|
|
93
|
-
if (onDrop) {
|
|
94
|
-
onDrop(path, value);
|
|
95
|
-
}
|
|
96
|
-
else if (process.env.NODE_ENV !== 'production') {
|
|
97
|
-
console.warn(`[query-find] sanitize() dropped value exceeding max nesting depth at path "${path}":`, value);
|
|
98
|
-
}
|
|
99
|
-
return undefined;
|
|
100
|
-
}
|
|
101
|
-
if (value === null)
|
|
102
|
-
return null;
|
|
103
|
-
const t = typeof value;
|
|
104
|
-
if (t === 'string' || t === 'number' || t === 'boolean')
|
|
105
|
-
return value;
|
|
106
|
-
if (Array.isArray(value)) {
|
|
107
|
-
const out = [];
|
|
108
|
-
for (let i = 0; i < value.length; i++) {
|
|
109
|
-
const s = sanitize(value[i], depth + 1, `${path}[${i}]`, onDrop);
|
|
110
|
-
if (s !== undefined)
|
|
111
|
-
out.push(s);
|
|
112
|
-
}
|
|
113
|
-
return out;
|
|
114
|
-
}
|
|
115
|
-
if (t === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
|
|
116
|
-
const src = value;
|
|
117
|
-
const out = {};
|
|
118
|
-
for (const k in src) {
|
|
119
|
-
if (Object.prototype.hasOwnProperty.call(src, k)) {
|
|
120
|
-
const childPath = path ? `${path}.${k}` : k;
|
|
121
|
-
const s = sanitize(src[k], depth + 1, childPath, onDrop);
|
|
122
|
-
if (s !== undefined)
|
|
123
|
-
out[k] = s;
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
return out;
|
|
127
|
-
}
|
|
128
|
-
if (onDrop) {
|
|
129
|
-
onDrop(path, value);
|
|
130
|
-
}
|
|
131
|
-
else if (process.env.NODE_ENV !== 'production') {
|
|
132
|
-
console.warn(`[query-find] sanitize() dropped non-plain value at path "${path}":`, value);
|
|
133
|
-
}
|
|
134
|
-
return undefined;
|
|
135
|
-
}
|
|
136
|
-
// ─── Allowlist ────────────────────────────────────────────────────────────────
|
|
137
|
-
/**
|
|
138
|
-
* Pre-computes a lowercase lookup set and a canonical-case map from the caller's
|
|
139
|
-
* allowlist. Built once per allowFields() call and reused across all methods.
|
|
140
|
-
*/
|
|
141
|
-
function buildAllowedStructures(allowedFields) {
|
|
142
|
-
const lookup = new Set();
|
|
143
|
-
const canonical = new Map();
|
|
144
|
-
for (const f of allowedFields) {
|
|
145
|
-
const lc = f.toLowerCase();
|
|
146
|
-
lookup.add(lc);
|
|
147
|
-
canonical.set(lc, f);
|
|
148
|
-
}
|
|
149
|
-
return { lookup, canonical };
|
|
150
|
-
}
|
|
151
|
-
function isFieldAllowed(field, allowedLookup) {
|
|
152
|
-
return allowedLookup.has(field.toLowerCase());
|
|
153
|
-
}
|
|
154
|
-
/**
|
|
155
|
-
* Removes any non-operator key from `filter` that is not present in the
|
|
156
|
-
* allowlist. Operator keys (starting with $) are passed through unchanged
|
|
157
|
-
* because they are validated separately by rejectDisallowedOperators().
|
|
158
|
-
*/
|
|
159
|
-
function enforceAllowlist(filter, allowedLookup, canonicalMap) {
|
|
160
|
-
if (allowedLookup.size === 0)
|
|
161
|
-
return filter;
|
|
162
|
-
const out = {};
|
|
163
|
-
for (const k in filter) {
|
|
164
|
-
if (!Object.prototype.hasOwnProperty.call(filter, k))
|
|
165
|
-
continue;
|
|
166
|
-
if (k.startsWith('$')) {
|
|
167
|
-
out[k] = filter[k];
|
|
168
|
-
continue;
|
|
169
|
-
}
|
|
170
|
-
const lc = k.toLowerCase();
|
|
171
|
-
if (allowedLookup.has(lc)) {
|
|
172
|
-
out[canonicalMap.get(lc) ?? k] = filter[k];
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
return out;
|
|
176
|
-
}
|
|
177
|
-
// ─── Fused coercion pass ──────────────────────────────────────────────────────
|
|
178
|
-
/**
|
|
179
|
-
* Single-pass coercion that handles:
|
|
180
|
-
* - 'true' / 'false' strings → booleans
|
|
181
|
-
* - Date-field strings → Date objects (or $gte/$lt range for plain YYYY-MM-DD)
|
|
182
|
-
* - Shorthand operator keys (eq, ne, gt, …) → prefixed form ($eq, $ne, $gt, …)
|
|
183
|
-
*
|
|
184
|
-
* Operator-key coercion is applied only to object keys, never to string values,
|
|
185
|
-
* preventing accidental rewriting of user-supplied string data.
|
|
186
|
-
*/
|
|
187
|
-
function coerceAll(value, parentKey = '') {
|
|
188
|
-
if (value === null)
|
|
189
|
-
return null;
|
|
190
|
-
if (typeof value === 'string') {
|
|
191
|
-
if (value === 'true')
|
|
192
|
-
return true;
|
|
193
|
-
if (value === 'false')
|
|
194
|
-
return false;
|
|
195
|
-
if (DATE_FIELD_RE.test(parentKey)) {
|
|
196
|
-
const parsed = new Date(value);
|
|
197
|
-
if (!isNaN(parsed.getTime())) {
|
|
198
|
-
if (PLAIN_DATE_RE.test(value)) {
|
|
199
|
-
const start = new Date(value);
|
|
200
|
-
const end = new Date(start);
|
|
201
|
-
end.setUTCDate(end.getUTCDate() + 1);
|
|
202
|
-
return { $gte: start, $lt: end };
|
|
203
|
-
}
|
|
204
|
-
return parsed;
|
|
205
|
-
}
|
|
206
|
-
}
|
|
207
|
-
return value;
|
|
208
|
-
}
|
|
209
|
-
if (typeof value !== 'object')
|
|
210
|
-
return value;
|
|
211
|
-
if (Array.isArray(value)) {
|
|
212
|
-
return value.map((item) => coerceAll(item, parentKey));
|
|
213
|
-
}
|
|
214
|
-
if (value instanceof Date)
|
|
215
|
-
return value;
|
|
216
|
-
const src = value;
|
|
217
|
-
const out = {};
|
|
218
|
-
for (const k in src) {
|
|
219
|
-
if (!Object.prototype.hasOwnProperty.call(src, k))
|
|
220
|
-
continue;
|
|
221
|
-
const newKey = COERCIBLE_OPS.has(k) ? `$${k}` : k;
|
|
222
|
-
const isOp = k.startsWith('$') || COERCIBLE_OPS.has(k);
|
|
223
|
-
const childPath = isOp ? parentKey : parentKey ? `${parentKey}.${k}` : k;
|
|
224
|
-
out[newKey] = coerceAll(src[k], childPath);
|
|
225
|
-
}
|
|
226
|
-
return out;
|
|
227
|
-
}
|
|
228
|
-
// ─── Operator validation ──────────────────────────────────────────────────────
|
|
229
|
-
/**
|
|
230
|
-
* Recursively walks a filter object and throws QueryFindValidationError on:
|
|
231
|
-
* - Any key present in BANNED_OPERATORS (e.g. $where, $expr)
|
|
232
|
-
* - Any top-level $ key that is not in ALLOWED_TOP_LEVEL_OPS
|
|
233
|
-
*
|
|
234
|
-
* Applied after coercion so shorthand operators have already been prefixed.
|
|
235
|
-
*/
|
|
236
|
-
function rejectDisallowedOperators(filter, depth = 0) {
|
|
237
|
-
for (const k in filter) {
|
|
238
|
-
if (!Object.prototype.hasOwnProperty.call(filter, k))
|
|
239
|
-
continue;
|
|
240
|
-
if (BANNED_OPERATORS.has(k)) {
|
|
241
|
-
throw new QueryFindValidationError(`Disallowed operator in query: "${k}"`);
|
|
242
|
-
}
|
|
243
|
-
if (depth === 0 && k.startsWith('$') && !ALLOWED_TOP_LEVEL_OPS.has(k)) {
|
|
244
|
-
throw new QueryFindValidationError(`Disallowed top-level operator in query string: "${k}"`);
|
|
245
|
-
}
|
|
246
|
-
const v = filter[k];
|
|
247
|
-
if (Array.isArray(v)) {
|
|
248
|
-
for (const item of v) {
|
|
249
|
-
if (item !== null &&
|
|
250
|
-
typeof item === 'object' &&
|
|
251
|
-
!Array.isArray(item) &&
|
|
252
|
-
!(item instanceof Date) &&
|
|
253
|
-
Object.getPrototypeOf(item) === Object.prototype) {
|
|
254
|
-
rejectDisallowedOperators(item, depth + 1);
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
|
-
}
|
|
258
|
-
else if (v !== null &&
|
|
259
|
-
typeof v === 'object' &&
|
|
260
|
-
!(v instanceof Date) &&
|
|
261
|
-
Object.getPrototypeOf(v) === Object.prototype) {
|
|
262
|
-
rejectDisallowedOperators(v, depth + 1);
|
|
263
|
-
}
|
|
264
|
-
}
|
|
265
|
-
}
|
|
266
|
-
// ─── Filter builder ───────────────────────────────────────────────────────────
|
|
267
|
-
/**
|
|
268
|
-
* Converts raw URL query params into a safe Mongoose filter by running the
|
|
269
|
-
* full pipeline: strip reserved keys → sanitize → coerce → allowlist → validate.
|
|
270
|
-
*/
|
|
271
|
-
function buildFilter(raw, allowedLookup, canonicalMap, onDrop) {
|
|
272
|
-
const stripped = {};
|
|
273
|
-
for (const k in raw) {
|
|
274
|
-
if (Object.prototype.hasOwnProperty.call(raw, k) && !RESERVED_KEYS.has(k)) {
|
|
275
|
-
stripped[k] = raw[k];
|
|
276
|
-
}
|
|
277
|
-
}
|
|
278
|
-
const safe = sanitize(stripped, 0, '', onDrop);
|
|
279
|
-
const coerced = coerceAll(safe);
|
|
280
|
-
const allowed = enforceAllowlist(coerced, allowedLookup, canonicalMap);
|
|
281
|
-
rejectDisallowedOperators(allowed);
|
|
282
|
-
return allowed;
|
|
283
|
-
}
|
|
284
|
-
// ─── Sort parser ──────────────────────────────────────────────────────────────
|
|
285
|
-
/**
|
|
286
|
-
* Parses a comma-separated sort string (e.g. "-createdAt,name") into a
|
|
287
|
-
* Mongoose sort object. Fields not present in the allowlist are silently
|
|
288
|
-
* skipped. Capped at MAX_SORT_FIELDS to prevent DoS via large sort lists.
|
|
289
|
-
*/
|
|
290
|
-
function parseSort(sort, allowedLookup, canonicalMap) {
|
|
291
|
-
const out = {};
|
|
292
|
-
let count = 0;
|
|
293
|
-
for (const token of sort.split(',')) {
|
|
294
|
-
if (count >= MAX_SORT_FIELDS)
|
|
295
|
-
break;
|
|
296
|
-
const trimmed = token.trim();
|
|
297
|
-
if (!trimmed || trimmed === '-')
|
|
298
|
-
continue;
|
|
299
|
-
const desc = trimmed.startsWith('-');
|
|
300
|
-
const field = desc ? trimmed.slice(1).trim() : trimmed;
|
|
301
|
-
if (!field)
|
|
302
|
-
continue;
|
|
303
|
-
if (allowedLookup.size > 0) {
|
|
304
|
-
if (!isFieldAllowed(field, allowedLookup))
|
|
305
|
-
continue;
|
|
306
|
-
const canonical = canonicalMap.get(field.toLowerCase()) ?? field;
|
|
307
|
-
out[canonical] = desc ? -1 : 1;
|
|
308
|
-
}
|
|
309
|
-
else {
|
|
310
|
-
out[field] = desc ? -1 : 1;
|
|
311
|
-
}
|
|
312
|
-
count++;
|
|
313
|
-
}
|
|
314
|
-
return out;
|
|
315
|
-
}
|
|
316
|
-
// ─── Projection sanitizer ─────────────────────────────────────────────────────
|
|
317
|
-
/**
|
|
318
|
-
* Filters a space-separated projection string against the allowlist.
|
|
319
|
-
* _id and __v are always permitted regardless of the allowlist.
|
|
320
|
-
* Returns an empty string when every token is blocked — callers must handle
|
|
321
|
-
* this case explicitly to avoid accidentally omitting the select() call.
|
|
322
|
-
*/
|
|
323
|
-
function sanitizeProjection(projection, allowedLookup) {
|
|
324
|
-
if (allowedLookup.size === 0)
|
|
325
|
-
return projection;
|
|
326
|
-
return projection
|
|
327
|
-
.split(/\s+/)
|
|
328
|
-
.filter((token) => {
|
|
329
|
-
if (!token)
|
|
330
|
-
return false;
|
|
331
|
-
const field = token.startsWith('-') ? token.slice(1) : token;
|
|
332
|
-
if (field === '__v' || field === '_id')
|
|
333
|
-
return true;
|
|
334
|
-
return isFieldAllowed(field, allowedLookup);
|
|
335
|
-
})
|
|
336
|
-
.join(' ');
|
|
337
|
-
}
|
|
338
|
-
// ─── QueryFind ────────────────────────────────────────────────────────────────
|
|
339
|
-
/**
|
|
340
|
-
* Production-grade fluent query builder / paginator for Mongoose 8/9.
|
|
341
|
-
*
|
|
342
|
-
* @example
|
|
343
|
-
* ```ts
|
|
344
|
-
* const result = await new QueryFind(User.find(), req.query)
|
|
345
|
-
* .allowFields(['name', 'email', 'role', 'createdAt'])
|
|
346
|
-
* .where({ orgId: req.user.orgId, deletedAt: null })
|
|
347
|
-
* .filter()
|
|
348
|
-
* .globalSearch(['name', 'email'])
|
|
349
|
-
* .sort()
|
|
350
|
-
* .limitFields('-password -__v')
|
|
351
|
-
* .populate('department', 'name')
|
|
352
|
-
* .paginate();
|
|
353
|
-
* ```
|
|
354
|
-
*/
|
|
355
|
-
class QueryFind {
|
|
356
|
-
constructor(query, queryString, options = {}) {
|
|
357
|
-
this._allowedFields = new Set();
|
|
358
|
-
this._allowedLookup = new Set();
|
|
359
|
-
this._canonicalMap = new Map();
|
|
360
|
-
/**
|
|
361
|
-
* URL-derived filter and server-side conditions are kept separate so that
|
|
362
|
-
* server conditions merged last in paginate() can never be overwritten by
|
|
363
|
-
* URL params, regardless of the order in which where() and filter() are called.
|
|
364
|
-
*/
|
|
365
|
-
this._urlFilter = {};
|
|
366
|
-
this._serverConditions = {};
|
|
367
|
-
/**
|
|
368
|
-
* $or clauses from globalSearch() are collected here and assembled once
|
|
369
|
-
* inside buildFinalFilter(). This prevents double-call from re-wrapping the
|
|
370
|
-
* entire filter in nested $and.
|
|
371
|
-
*/
|
|
372
|
-
this._searchOr = [];
|
|
373
|
-
this._sort = { ...DEFAULT_SORT };
|
|
374
|
-
this._select = null;
|
|
375
|
-
this._populates = [];
|
|
376
|
-
/** Stored so limitFields() can fall back to it when ?fields= is fully blocked. */
|
|
377
|
-
this._defaultFields = null;
|
|
378
|
-
this.model = query.model;
|
|
379
|
-
this.qs = Object.freeze({ ...queryString });
|
|
380
|
-
this.options = {
|
|
381
|
-
maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
|
|
382
|
-
slowQueryThresholdMS: options.slowQueryThresholdMS ??
|
|
383
|
-
options.maxTimeMS ??
|
|
384
|
-
DEFAULT_MAX_TIME_MS,
|
|
385
|
-
lean: options.lean ?? true,
|
|
386
|
-
onSlowQuery: options.onSlowQuery,
|
|
387
|
-
onSanitizeDrop: options.onSanitizeDrop,
|
|
388
|
-
};
|
|
389
|
-
this._page = parsePage(this.qs.page);
|
|
390
|
-
this._limit = parseLimit(this.qs.limit);
|
|
391
|
-
}
|
|
392
|
-
// ── Configuration ───────────────────────────────────────────────────────────
|
|
393
|
-
/**
|
|
394
|
-
* Declares which fields the client is permitted to filter, sort, and select.
|
|
395
|
-
* Must be called before filter(), sort(), and limitFields() to take effect.
|
|
396
|
-
* Matching is case-insensitive: allowFields(['Name']) accepts ?name=, ?NAME=.
|
|
397
|
-
*
|
|
398
|
-
* @example .allowFields(['basicInfo.name', 'pricing.base', 'status'])
|
|
399
|
-
*/
|
|
400
|
-
allowFields(fields) {
|
|
401
|
-
this._allowedFields = new Set(fields);
|
|
402
|
-
const { lookup, canonical } = buildAllowedStructures(this._allowedFields);
|
|
403
|
-
this._allowedLookup = lookup;
|
|
404
|
-
this._canonicalMap = canonical;
|
|
405
|
-
return this;
|
|
406
|
-
}
|
|
407
|
-
// ── Builder methods ─────────────────────────────────────────────────────────
|
|
408
|
-
/**
|
|
409
|
-
* Parses URL query params into a Mongoose filter and merges them into the
|
|
410
|
-
* URL-derived filter store. Only fields present in allowFields() pass through.
|
|
411
|
-
* Reserved keys (page, sort, limit, fields, q) are always stripped first.
|
|
412
|
-
*/
|
|
413
|
-
filter() {
|
|
414
|
-
const parsed = buildFilter(this.qs, this._allowedLookup, this._canonicalMap, this.options.onSanitizeDrop);
|
|
415
|
-
Object.assign(this._urlFilter, parsed);
|
|
416
|
-
return this;
|
|
417
|
-
}
|
|
418
|
-
/**
|
|
419
|
-
* Applies mandatory server-side conditions that the client cannot override.
|
|
420
|
-
* Conditions are merged into the final filter after URL-derived values, so
|
|
421
|
-
* they always win regardless of what the client sends.
|
|
422
|
-
*
|
|
423
|
-
* Unlike filter(), values here are not sanitized — ObjectIds, Dates, and
|
|
424
|
-
* other non-plain types are valid. Banned $ operators are still rejected.
|
|
425
|
-
*
|
|
426
|
-
* @example .where({ linkedTo: req.user.orgId, deletedAt: null })
|
|
427
|
-
*/
|
|
428
|
-
where(conditions) {
|
|
429
|
-
const asRecord = conditions;
|
|
430
|
-
rejectDisallowedOperators(asRecord);
|
|
431
|
-
Object.assign(this._serverConditions, asRecord);
|
|
432
|
-
return this;
|
|
433
|
-
}
|
|
434
|
-
/**
|
|
435
|
-
* Enables case-insensitive full-text search across the given fields when
|
|
436
|
-
* ?q= is present in the query string. Fields not in allowFields() are
|
|
437
|
-
* silently skipped. Safe to call multiple times — subsequent calls extend
|
|
438
|
-
* the $or clause list rather than re-wrapping the filter.
|
|
439
|
-
*
|
|
440
|
-
* @example .globalSearch(['basicInfo.name', 'basicInfo.sku'])
|
|
441
|
-
*/
|
|
442
|
-
globalSearch(fields) {
|
|
443
|
-
const raw = this.qs.q?.trim();
|
|
444
|
-
if (!raw || raw.length > MAX_SEARCH_LENGTH || fields.length === 0) {
|
|
445
|
-
return this;
|
|
446
|
-
}
|
|
447
|
-
const safeFields = this._allowedLookup.size > 0
|
|
448
|
-
? fields.filter((f) => isFieldAllowed(f, this._allowedLookup))
|
|
449
|
-
: fields;
|
|
450
|
-
if (safeFields.length === 0)
|
|
451
|
-
return this;
|
|
452
|
-
const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
453
|
-
const regex = new RegExp(escaped, 'i');
|
|
454
|
-
for (const field of safeFields) {
|
|
455
|
-
this._searchOr.push({ [field]: regex });
|
|
456
|
-
}
|
|
457
|
-
return this;
|
|
458
|
-
}
|
|
459
|
-
/**
|
|
460
|
-
* Parses the ?sort= query param into a Mongoose sort object. Fields not in
|
|
461
|
-
* allowFields() are silently dropped. Falls back to DEFAULT_SORT when the
|
|
462
|
-
* parsed result is empty. Capped at MAX_SORT_FIELDS entries.
|
|
463
|
-
*
|
|
464
|
-
* Prefix a field with - for descending order: ?sort=-createdAt,name
|
|
465
|
-
*/
|
|
466
|
-
sort() {
|
|
467
|
-
if (this.qs.sort) {
|
|
468
|
-
const parsed = parseSort(this.qs.sort, this._allowedLookup, this._canonicalMap);
|
|
469
|
-
this._sort =
|
|
470
|
-
Object.keys(parsed).length > 0 ? parsed : { ...DEFAULT_SORT };
|
|
471
|
-
}
|
|
472
|
-
return this;
|
|
473
|
-
}
|
|
474
|
-
/**
|
|
475
|
-
* Controls which fields are returned by the query.
|
|
476
|
-
*
|
|
477
|
-
* When ?fields= is present in the URL, the value is parsed as a
|
|
478
|
-
* comma-separated list and filtered through the allowlist. Only fields
|
|
479
|
-
* declared in allowFields() will be included in the projection.
|
|
480
|
-
*
|
|
481
|
-
* When ?fields= is absent, `defaultFields` is used as-is (no allowlist
|
|
482
|
-
* filtering) — this is the server-controlled default projection.
|
|
483
|
-
*
|
|
484
|
-
* When ?fields= is present but every requested field is blocked by the
|
|
485
|
-
* allowlist, the projection falls back to `defaultFields` rather than
|
|
486
|
-
* omitting select() entirely (which would return all fields).
|
|
487
|
-
*
|
|
488
|
-
* @param defaultFields - Space-separated Mongoose projection string used
|
|
489
|
-
* when the client does not specify ?fields=.
|
|
490
|
-
* Example: 'basicInfo.name pricing.base status -__v'
|
|
491
|
-
*/
|
|
492
|
-
limitFields(defaultFields) {
|
|
493
|
-
if (defaultFields) {
|
|
494
|
-
this._defaultFields = defaultFields;
|
|
495
|
-
}
|
|
496
|
-
if (this.qs.fields) {
|
|
497
|
-
const raw = this.qs.fields
|
|
498
|
-
.split(',')
|
|
499
|
-
.map((f) => f.trim())
|
|
500
|
-
.filter(Boolean)
|
|
501
|
-
.join(' ');
|
|
502
|
-
const sanitized = sanitizeProjection(raw, this._allowedLookup);
|
|
503
|
-
// sanitizeProjection returns an empty string when every requested field
|
|
504
|
-
// is blocked. An empty string is falsy — passing it to select() would
|
|
505
|
-
// silently skip the call and return all fields. Fall back to the
|
|
506
|
-
// server-supplied default projection to prevent unintended field exposure.
|
|
507
|
-
this._select = sanitized || this._defaultFields || null;
|
|
508
|
-
}
|
|
509
|
-
else if (defaultFields) {
|
|
510
|
-
this._select = defaultFields;
|
|
511
|
-
}
|
|
512
|
-
return this;
|
|
513
|
-
}
|
|
514
|
-
/**
|
|
515
|
-
* Registers a populate path to be applied on the find query.
|
|
516
|
-
* populate.match conditions are sanitized and validated like any other filter.
|
|
517
|
-
*
|
|
518
|
-
* @example
|
|
519
|
-
* .populate('author')
|
|
520
|
-
* .populate('author', 'name avatar')
|
|
521
|
-
* .populate({ path: 'comments', select: 'text', match: { visible: true } })
|
|
522
|
-
*/
|
|
523
|
-
populate(path, select) {
|
|
524
|
-
if (typeof path === 'string') {
|
|
525
|
-
this._populates.push(select ? { path, select } : { path });
|
|
526
|
-
}
|
|
527
|
-
else {
|
|
528
|
-
if (path.match != null) {
|
|
529
|
-
const rawMatch = path.match;
|
|
530
|
-
const safeMatch = sanitize(rawMatch, 0, 'populate.match', this.options.onSanitizeDrop);
|
|
531
|
-
rejectDisallowedOperators(safeMatch);
|
|
532
|
-
this._populates.push({ ...path, match: safeMatch });
|
|
533
|
-
}
|
|
534
|
-
else {
|
|
535
|
-
this._populates.push(path);
|
|
536
|
-
}
|
|
537
|
-
}
|
|
538
|
-
return this;
|
|
539
|
-
}
|
|
540
|
-
// ── Private helpers ─────────────────────────────────────────────────────────
|
|
541
|
-
/**
|
|
542
|
-
* Assembles the final Mongoose filter from three sources in priority order:
|
|
543
|
-
* 1. URL-derived filter (lowest priority — client controlled)
|
|
544
|
-
* 2. Global search $or clause
|
|
545
|
-
* 3. Server conditions (highest priority — cannot be overridden by client)
|
|
546
|
-
*/
|
|
547
|
-
buildFinalFilter() {
|
|
548
|
-
let base = { ...this._urlFilter };
|
|
549
|
-
if (this._searchOr.length > 0) {
|
|
550
|
-
if (Object.keys(base).length > 0) {
|
|
551
|
-
base = { $and: [base, { $or: this._searchOr }] };
|
|
552
|
-
}
|
|
553
|
-
else {
|
|
554
|
-
base = { $or: this._searchOr };
|
|
555
|
-
}
|
|
556
|
-
}
|
|
557
|
-
return { ...base, ...this._serverConditions };
|
|
558
|
-
}
|
|
559
|
-
execFind(mongoFilter, skip) {
|
|
560
|
-
const { maxTimeMS, lean } = this.options;
|
|
561
|
-
const q = this.model
|
|
562
|
-
.find(mongoFilter)
|
|
563
|
-
.sort(this._sort)
|
|
564
|
-
.skip(skip)
|
|
565
|
-
.limit(this._limit);
|
|
566
|
-
if (lean)
|
|
567
|
-
q.lean();
|
|
568
|
-
if (this._select)
|
|
569
|
-
q.select(this._select);
|
|
570
|
-
for (const opt of this._populates)
|
|
571
|
-
q.populate(opt);
|
|
572
|
-
if (maxTimeMS > 0)
|
|
573
|
-
q.maxTimeMS(maxTimeMS);
|
|
574
|
-
return q.exec();
|
|
575
|
-
}
|
|
576
|
-
/**
|
|
577
|
-
* Uses estimatedDocumentCount when no filter is active for a fast O(1) count.
|
|
578
|
-
* Falls back to countDocuments when a filter is present.
|
|
579
|
-
*/
|
|
580
|
-
async execCount(mongoFilter, hasFilter) {
|
|
581
|
-
const { maxTimeMS } = this.options;
|
|
582
|
-
if (!hasFilter) {
|
|
583
|
-
return (await this.model
|
|
584
|
-
.estimatedDocumentCount()
|
|
585
|
-
.maxTimeMS(maxTimeMS)
|
|
586
|
-
.exec());
|
|
587
|
-
}
|
|
588
|
-
return (await this.model
|
|
589
|
-
.countDocuments(mongoFilter)
|
|
590
|
-
.maxTimeMS(maxTimeMS)
|
|
591
|
-
.exec());
|
|
592
|
-
}
|
|
593
|
-
/**
|
|
594
|
-
* Wraps an async operation with slow-query detection. When onSlowQuery is
|
|
595
|
-
* provided and the operation exceeds slowQueryThresholdMS, the hook is called
|
|
596
|
-
* with timing and query metadata for observability.
|
|
597
|
-
*/
|
|
598
|
-
async wrapTimed(fn, page, limit, filter) {
|
|
599
|
-
const { onSlowQuery, slowQueryThresholdMS, maxTimeMS } = this.options;
|
|
600
|
-
if (!onSlowQuery)
|
|
601
|
-
return fn();
|
|
602
|
-
const start = Date.now();
|
|
603
|
-
const result = await fn();
|
|
604
|
-
const elapsedMs = Date.now() - start;
|
|
605
|
-
if (elapsedMs >= (slowQueryThresholdMS ?? maxTimeMS)) {
|
|
606
|
-
onSlowQuery({ elapsedMs, filter, sort: this._sort, page, limit });
|
|
607
|
-
}
|
|
608
|
-
return result;
|
|
609
|
-
}
|
|
610
|
-
// ── Terminal ────────────────────────────────────────────────────────────────
|
|
611
|
-
/**
|
|
612
|
-
* Executes the query and returns a paginated result.
|
|
613
|
-
*
|
|
614
|
-
* On page 1, count and find run in parallel via Promise.all.
|
|
615
|
-
* On subsequent pages, pass the previously returned `total` as `cachedTotal`
|
|
616
|
-
* to skip the count query entirely.
|
|
617
|
-
*
|
|
618
|
-
* @param cachedTotal - Total document count from a prior page-1 response.
|
|
619
|
-
* When provided, the countDocuments call is skipped for this request.
|
|
620
|
-
*
|
|
621
|
-
* @throws {QueryFindValidationError} when the URL contains a disallowed $ operator.
|
|
622
|
-
*/
|
|
623
|
-
async paginate(cachedTotal) {
|
|
624
|
-
const page = this._page;
|
|
625
|
-
const limit = this._limit;
|
|
626
|
-
const finalFilter = this.buildFinalFilter();
|
|
627
|
-
const mongoFilter = finalFilter;
|
|
628
|
-
const hasFilter = Object.keys(finalFilter).length > 0;
|
|
629
|
-
// ── Page 1: count + find in parallel ─────────────────────────────────────
|
|
630
|
-
if (page === 1) {
|
|
631
|
-
const [total, data] = await this.wrapTimed(() => Promise.all([
|
|
632
|
-
this.execCount(mongoFilter, hasFilter),
|
|
633
|
-
this.execFind(mongoFilter, 0),
|
|
634
|
-
]), page, limit, finalFilter);
|
|
635
|
-
const totalPages = Math.max(Math.ceil(total / limit), 1);
|
|
636
|
-
return {
|
|
637
|
-
data,
|
|
638
|
-
total,
|
|
639
|
-
page: 1,
|
|
640
|
-
totalPages,
|
|
641
|
-
limit,
|
|
642
|
-
hasNextPage: 1 < totalPages,
|
|
643
|
-
hasPrevPage: false,
|
|
644
|
-
};
|
|
645
|
-
}
|
|
646
|
-
// ── Page > 1 with cached total: skip count ────────────────────────────────
|
|
647
|
-
if (cachedTotal !== undefined) {
|
|
648
|
-
const totalPages = Math.max(Math.ceil(cachedTotal / limit), 1);
|
|
649
|
-
const safePage = page > totalPages ? 1 : page;
|
|
650
|
-
const data = await this.wrapTimed(() => this.execFind(mongoFilter, (safePage - 1) * limit), safePage, limit, finalFilter);
|
|
651
|
-
return {
|
|
652
|
-
data,
|
|
653
|
-
total: cachedTotal,
|
|
654
|
-
page: safePage,
|
|
655
|
-
totalPages,
|
|
656
|
-
limit,
|
|
657
|
-
hasNextPage: safePage < totalPages,
|
|
658
|
-
hasPrevPage: safePage > 1,
|
|
659
|
-
};
|
|
660
|
-
}
|
|
661
|
-
// ── Page > 1 without cached total: count + find, both timed ──────────────
|
|
662
|
-
const result = { total: 0, data: [], safePage: page, totalPages: 1 };
|
|
663
|
-
await this.wrapTimed(async () => {
|
|
664
|
-
const total = await this.execCount(mongoFilter, hasFilter);
|
|
665
|
-
const totalPages = Math.max(Math.ceil(total / limit), 1);
|
|
666
|
-
const safePage = page > totalPages ? 1 : page;
|
|
667
|
-
const data = await this.execFind(mongoFilter, (safePage - 1) * limit);
|
|
668
|
-
result.total = total;
|
|
669
|
-
result.data = data;
|
|
670
|
-
result.safePage = safePage;
|
|
671
|
-
result.totalPages = totalPages;
|
|
672
|
-
}, page, limit, finalFilter);
|
|
673
|
-
return {
|
|
674
|
-
data: result.data,
|
|
675
|
-
total: result.total,
|
|
676
|
-
page: result.safePage,
|
|
677
|
-
totalPages: result.totalPages,
|
|
678
|
-
limit,
|
|
679
|
-
hasNextPage: result.safePage < result.totalPages,
|
|
680
|
-
hasPrevPage: result.safePage > 1,
|
|
681
|
-
};
|
|
682
|
-
}
|
|
683
|
-
}
|
|
684
|
-
exports.QueryFind = QueryFind;
|
|
685
|
-
// ─── Factory ──────────────────────────────────────────────────────────────────
|
|
686
|
-
/**
|
|
687
|
-
* Convenience factory — avoids `new` at the call site.
|
|
688
|
-
*
|
|
689
|
-
* @example
|
|
690
|
-
* const result = await queryFind(User.find(), req.query, { maxTimeMS: 3000 })
|
|
691
|
-
* .allowFields(['name', 'email', 'createdAt'])
|
|
692
|
-
* .where({ deletedAt: null })
|
|
693
|
-
* .filter()
|
|
694
|
-
* .globalSearch(['name', 'email'])
|
|
695
|
-
* .sort()
|
|
696
|
-
* .limitFields('-password -__v')
|
|
697
|
-
* .paginate();
|
|
698
|
-
*/
|
|
699
|
-
function queryFind(query, queryString, options) {
|
|
700
|
-
return new QueryFind(query, queryString, options);
|
|
701
|
-
}
|
|
702
|
-
exports.queryFind = queryFind;
|
|
703
|
-
exports.default = QueryFind;
|
|
3
|
+
exports.QueryFind = exports.QueryAggregate = void 0;
|
|
4
|
+
var aggregate_1 = require("./aggregate");
|
|
5
|
+
Object.defineProperty(exports, "QueryAggregate", { enumerable: true, get: function () { return aggregate_1.QueryAggregate; } });
|
|
6
|
+
var find_1 = require("./find");
|
|
7
|
+
Object.defineProperty(exports, "QueryFind", { enumerable: true, get: function () { return find_1.QueryFind; } });
|
|
704
8
|
//# sourceMappingURL=index.js.map
|