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/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
- // Reserved keys stripped before building the filter
4
- const RESERVED_KEYS = ['page', 'sort', 'limit', 'fields', 'q'];
5
- // MongoDB comparison operators that need a `$` prefix
6
- const MONGO_OPERATORS_RE = /\b(eq|ne|gt|gte|lt|lte|in|nin)\b/g;
7
- // ─── Helpers ──────────────────────────────────────────────────────────────────
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
- * Recursively keep only plain, JSON-serializable values (string, number,
10
- * boolean, null, plain object, array). Drops anything that is a class
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
- function sanitize(value) {
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
- return value.map(sanitize).filter((v) => v !== undefined);
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 result = {};
117
+ const out = {};
28
118
  for (const [k, v] of Object.entries(value)) {
29
- const sanitized = sanitize(v);
30
- if (sanitized !== undefined) {
31
- result[k] = sanitized;
32
- }
119
+ const s = sanitize(v, depth + 1);
120
+ if (s !== undefined)
121
+ out[k] = s;
33
122
  }
34
- return result;
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
- * Coerce plain string booleans to real booleans so filters like
41
- * `?isActive=true` work correctly against boolean schema fields.
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 coerceBooleans(obj) {
44
- return Object.fromEntries(Object.entries(obj).map(([k, v]) => {
45
- if (v === 'true')
46
- return [k, true];
47
- if (v === 'false')
48
- return [k, false];
49
- return [k, v];
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
- // Field names (or suffixes) that should be treated as dates
53
- const DATE_FIELD_RE = /(^|\.)(createdAt|updatedAt|deletedAt|date|Date)$/;
169
+ // ─── Type coercion ────────────────────────────────────────────────────────────
54
170
  /**
55
- * Recursively walk the filter object and coerce any string value stored
56
- * under a date-like key into a proper `Date` instance.
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
- return Object.fromEntries(Object.entries(obj).map(([k, v]) => {
64
- const path = parentKey ? `${parentKey}.${k}` : k;
65
- // Recurse into nested operator objects (e.g. { $gte: '...' })
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
- const nested = coerceDates(v, path);
71
- return [k, nested];
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
- return [k, v];
78
- // If it's a plain date string (no time component), convert to a
79
- // $gte/$lt range so it matches all documents within that day.
80
- if (/^\d{4}-\d{2}-\d{2}$/.test(v)) {
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
- return [k, { $gte: start, $lt: end }];
217
+ out[k] = { $gte: start, $lt: end };
218
+ continue;
85
219
  }
86
- return [k, parsed];
220
+ out[k] = parsed;
221
+ continue;
87
222
  }
88
- return [k, v];
89
- }));
223
+ out[k] = v;
224
+ }
225
+ return out;
90
226
  }
227
+ // ─── Operator validation ──────────────────────────────────────────────────────
91
228
  /**
92
- * Parse the raw query string into a Mongoose-compatible filter object.
93
- * Strips reserved keys, sanitizes all values to plain JSON-safe types,
94
- * and rewrites bare operator names (gt → $gt, etc.).
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 buildFilterFromQueryString(raw) {
97
- // Strip reserved keys first
98
- const stripped = Object.fromEntries(Object.entries(raw).filter(([k]) => !RESERVED_KEYS.includes(k)));
99
- // Sanitize to plain values only — prevents circular JSON errors
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 names to MongoDB $ operators
102
- const withOperators = JSON.parse(JSON.stringify(safe).replace(MONGO_OPERATORS_RE, (m) => `$${m}`));
103
- return coerceDates(coerceBooleans(withOperators));
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
- * Parse a comma-separated sort string (e.g. `-createdAt,name`) into a
107
- * `{ field: 1 | -1 }` map.
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 parseSortString(sort) {
110
- return Object.fromEntries(sort.split(',').map((f) => (f.startsWith('-') ? [f.slice(1), -1] : [f, 1])));
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
- * Fluent query builder that progressively refines a Mongoose query,
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
- * const result = await new QueryFind(
124
- * UserModel.find({ linkedTo: req.self._id, role: { $in: ROLES } }),
125
- * req.query
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
- * .globalFilter(['name', 'email'])
334
+ * .globalSearch(['name', 'email'])
129
335
  * .sort()
130
- * .limitFields('-__v')
131
- * .populate('author')
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
- /** Accumulated Mongoose filter (populated by constructor, `filter()`, and `globalFilter()`). */
138
- this.filterQuery = {};
139
- /** Sort order applied in `paginate()`. */
140
- this.sortQuery = { createdAt: -1 };
141
- /** Projection string applied in `paginate()`. */
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.queryString = queryString;
147
- // so they are never lost when .filter() builds additional URL-param filters.
148
- const baseFilter = query.getFilter();
149
- if (baseFilter && Object.keys(baseFilter).length > 0) {
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
- // ── Builder methods ─────────────────────────────────────────────────────────
366
+ // ── Configuration ───────────────────────────────────────────────────────────
154
367
  /**
155
- * Parse the URL query string into a Mongoose filter and merge it on top
156
- * of any base query conditions set in the constructor.
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 = buildFilterFromQueryString(this.queryString);
160
- this.filterQuery = {
161
- ...this.filterQuery,
162
- ...parsed,
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
- * Add a case-insensitive `$or` regex search across the supplied fields
168
- * when the query string contains a `q` parameter.
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
- globalFilter(fields) {
171
- const search = this.queryString.q;
172
- if (search && fields.length > 0) {
173
- this.filterQuery.$or = fields.map((field) => ({
174
- [field]: { $regex: search, $options: 'i' },
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
- * Configure sort order from the `sort` query param.
181
- * Falls back to `{ createdAt: -1 }` when the param is absent.
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.queryString.sort) {
185
- this.sortQuery = parseSortString(this.queryString.sort);
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
- * Priority order:
193
- * 1. `?fields=` query param (always wins when present).
194
- * 2. `defaultFields` argument (used as fallback when no query param).
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 - Optional space- or comma-separated projection
198
- * string, e.g. `'-password -__v'`. Omit to rely solely on the
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.queryString.fields) {
203
- this.selectQuery = this.queryString.fields.split(',').join(' ');
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.selectQuery = defaultFields;
462
+ this._select = defaultFields;
207
463
  }
208
464
  return this;
209
465
  }
210
466
  /**
211
- * Register a populate directive. Can be called multiple times to 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
- * 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).
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
- const opt = { path };
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.populateOptions.push(path);
479
+ this._populates.push(path);
236
480
  }
237
481
  return this;
238
482
  }
239
- // ── Terminal method ─────────────────────────────────────────────────────────
483
+ // ── Terminal ────────────────────────────────────────────────────────────────
240
484
  /**
241
- * Execute the query and return a paginated result.
485
+ * Execute and return a paginated result.
242
486
  *
243
- * Two database round-trips are made:
244
- * 1. `countDocuments` with the current filter — O(index scan).
245
- * 2. `find` with filter, sort, skip, limit, projection, and any
246
- * registered populates.
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
- * If the requested page exceeds `totalPages` (e.g. after a deletion),
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 = Math.max(parseInt(this.queryString.page ?? '1', 10), 1);
253
- const limit = Math.max(parseInt(this.queryString.limit ?? '10', 10), 1);
254
- // ── 1. Count matching documents ────────────────────────────────────────
255
- const total = await this.model.countDocuments(this.filterQuery);
256
- const totalPages = Math.ceil(total / limit) || 1;
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
- const skip = (safePage - 1) * limit;
259
- // ── 2. Fetch the page ──────────────────────────────────────────────────
260
- const findQuery = this.model
261
- .find(this.filterQuery)
262
- .sort(this.sortQuery)
263
- .skip(skip)
264
- .limit(limit);
265
- if (this.selectQuery) {
266
- findQuery.select(this.selectQuery);
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
- // ── 3. Apply populates (if any) ────────────────────────────────────────
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: 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