mongoose-query-find 4.0.2 → 5.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/aggregate.js CHANGED
@@ -45,12 +45,17 @@
45
45
  * run the client-input sanitizer; that only applies to .filter()/.where(),
46
46
  * which parse untrusted req.query / req.body values.
47
47
  *
48
+ * Conditions (URL filter, search, where/range) that reference a joined field
49
+ * (a `.lookup()` `as` alias that is not a real schema path, e.g. "category.name")
50
+ * are automatically placed in a $match *after* the join; everything else stays
51
+ * in the first $match so indexes can be used.
52
+ *
48
53
  * ── Custom ranges ────────────────────────────────────────────────────────────
49
54
  * `.range(field, preset)` covers the fixed RangePreset values (today,
50
55
  * yesterday, last7Days, last30Days, thisWeek, thisMonth). For anything more
51
56
  * specific — a single arbitrary day, an arbitrary date span, a rolling
52
57
  * window of N days/hours, an explicit hour-of-day window, or an explicit
53
- * absolute datetime window — use the new custom range methods below:
58
+ * absolute datetime window — use the custom range methods below:
54
59
  *
55
60
  * .rangeCustomDay(field, '2026-03-14')
56
61
  * .rangeBetween(field, { from: '2026-01-01', to: '2026-01-31' })
@@ -60,7 +65,8 @@
60
65
  * .rangeCustom(field, { from: '2026-03-14T09:00:00', to: '2026-03-15T00:00:00' })
61
66
  *
62
67
  * All of these behave like .range(): they set a hard, server-side condition
63
- * that the client cannot override via query params.
68
+ * that the client cannot override via query params. Multiple server-side
69
+ * conditions on the same field are AND-ed together (never silently overwritten).
64
70
  */
65
71
  Object.defineProperty(exports, "__esModule", { value: true });
66
72
  exports.QueryAggregate = exports.QueryAggregateValidationError = exports.QueryAggregateError = void 0;
@@ -70,27 +76,38 @@ const mongoose_1 = require("mongoose");
70
76
  // ─── Constants ────────────────────────────────────────────────────────────────
71
77
  const RESERVED_KEYS = new Set(['page', 'sort', 'limit', 'fields', 'q']);
72
78
  const DEFAULT_MAX_LIMIT = 100;
79
+ const DEFAULT_LIMIT = 10;
80
+ const MAX_PAGE = 1000000000;
73
81
  const MAX_NESTING_DEPTH = 5;
74
82
  const MAX_SEARCH_LENGTH = 200;
75
83
  const MAX_SORT_FIELDS = 5;
84
+ const MAX_CURSOR_LENGTH = 1024;
76
85
  const DEFAULT_MAX_TIME_MS = 5000;
77
86
  const DEFAULT_TIMEZONE = 'Asia/Dhaka';
78
87
  // Matches only when the date-word is the LAST path segment (e.g. "createdAt",
79
- // "user.updatedAt") — used as a fallback heuristic when .dateFields() isn't
80
- // called explicitly.
88
+ // "user.updatedAt") — used as a fallback heuristic when neither .dateFields()
89
+ // nor the model schema identifies the field type.
81
90
  const DATE_FIELD_RE = /(^|\.)(createdAt|updatedAt|deletedAt|archivedAt|expiresAt|date|birthDate)$/i;
82
91
  const PLAIN_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
83
92
  // A string that already carries its own UTC offset ("Z" or "+06:00") is
84
93
  // treated as an absolute instant rather than a local wall-clock time.
85
94
  const HAS_OFFSET_RE = /([Zz]|[+-]\d{2}:?\d{2})$/;
86
95
  // Matches only when the id-word is the LAST path segment (e.g. "_id",
87
- // "categoryId", "basicInfo.brandId") — used as a fallback heuristic when
88
- // .objectIdFields() isn't called explicitly. Mirrors DATE_FIELD_RE's approach.
96
+ // "categoryId", "basicInfo.brandId") — fallback heuristic when neither
97
+ // .objectIdFields() nor the model schema identifies the field type.
89
98
  const OBJECTID_FIELD_RE = /(^|\.)(_id|[a-zA-Z0-9]*Id)$/;
90
- // A 24-char lowercase/uppercase hex string — the only shape isValidObjectId()
91
- // should be trusted to interpret as "meant to be an ObjectId" rather than a
92
- // 12-byte-length string that happens to also pass Mongoose's looser check.
99
+ // A 24-char hex string — the only shape trusted as "meant to be an ObjectId".
93
100
  const HEX24_RE = /^[a-fA-F0-9]{24}$/;
101
+ // Plain decimal numbers only (no hex, exponent, Infinity, or leading zeros
102
+ // such as phone numbers "0171...").
103
+ const NUMERIC_RE = /^-?(0|[1-9]\d*)(\.\d+)?$/;
104
+ const FIELD_PATH_RE = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z0-9_]+)*$/;
105
+ const METRIC_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
106
+ const DANGEROUS_KEYS = new Set([
107
+ '__proto__',
108
+ 'constructor',
109
+ 'prototype',
110
+ ]);
94
111
  const COERCIBLE_OPS = new Set([
95
112
  'eq',
96
113
  'ne',
@@ -101,9 +118,11 @@ const COERCIBLE_OPS = new Set([
101
118
  'in',
102
119
  'nin',
103
120
  ]);
104
- const IN_LIKE_OPS = new Set(['in', '$in', 'nin', '$nin']);
121
+ const IN_LIKE_OPS = new Set(['in', 'nin']);
122
+ const STAT_OPS = new Set(['sum', 'avg', 'min', 'max', 'count']);
105
123
  const DEFAULT_SORT = { createdAt: -1 };
106
- const ALLOWED_TOP_LEVEL_OPS = new Set(['$and', '$or', '$nor', '$not']);
124
+ // NOTE: `$not` is not a valid top-level query operator in MongoDB, so it is not allowed here.
125
+ const ALLOWED_TOP_LEVEL_OPS = new Set(['$and', '$or', '$nor']);
107
126
  // Rejected anywhere inside client-supplied filter/search/populate-match input.
108
127
  const BANNED_OPERATORS = new Set([
109
128
  '$where',
@@ -113,6 +132,9 @@ const BANNED_OPERATORS = new Set([
113
132
  '$map',
114
133
  '$reduce',
115
134
  '$filter',
135
+ // Not valid inside aggregation $match — would fail at runtime.
136
+ '$near',
137
+ '$nearSphere',
116
138
  ]);
117
139
  // Rejected in developer-authored pipeline stages added via addStage()/lookup()
118
140
  // pipelines — these can mutate or drop data and have no place in a query builder.
@@ -132,22 +154,39 @@ class QueryAggregateValidationError extends QueryAggregateError {
132
154
  }
133
155
  }
134
156
  exports.QueryAggregateValidationError = QueryAggregateValidationError;
157
+ const SCHEMA_KIND_MAP = {
158
+ String: 'string',
159
+ Number: 'number',
160
+ Boolean: 'boolean',
161
+ Date: 'date',
162
+ ObjectId: 'objectid',
163
+ ObjectID: 'objectid',
164
+ };
135
165
  // ─── Input parsing ────────────────────────────────────────────────────────────
166
+ function asString(v) {
167
+ return typeof v === 'string' ? v : undefined;
168
+ }
136
169
  function parsePage(raw) {
137
- const n = parseInt(raw ?? '1', 10);
138
- return isNaN(n) || n < 1 ? 1 : n;
170
+ const n = parseInt(asString(raw) ?? '1', 10);
171
+ return !Number.isSafeInteger(n) || n < 1 || n > MAX_PAGE ? 1 : n;
139
172
  }
140
173
  function parseLimit(raw, maxLimit = DEFAULT_MAX_LIMIT) {
141
- const n = parseInt(raw ?? '10', 10);
142
- if (isNaN(n) || n < 1)
143
- return 10;
174
+ const n = parseInt(asString(raw) ?? String(DEFAULT_LIMIT), 10);
175
+ if (!Number.isFinite(n) || n < 1)
176
+ return Math.min(DEFAULT_LIMIT, maxLimit);
144
177
  return Math.min(n, maxLimit);
145
178
  }
179
+ const validTimezones = new Set();
146
180
  function resolveTimezone(tz) {
147
- const candidate = tz && tz.trim() ? tz.trim() : DEFAULT_TIMEZONE;
181
+ const candidate = typeof tz === 'string' && tz.trim() && tz.length <= 64
182
+ ? tz.trim()
183
+ : DEFAULT_TIMEZONE;
184
+ if (validTimezones.has(candidate))
185
+ return candidate;
148
186
  try {
149
187
  // Throws RangeError on an invalid IANA zone — cheapest available validator.
150
- Intl.DateTimeFormat(undefined, { timeZone: candidate });
188
+ new Intl.DateTimeFormat('en-US', { timeZone: candidate });
189
+ validTimezones.add(candidate);
151
190
  return candidate;
152
191
  }
153
192
  catch {
@@ -158,12 +197,22 @@ function resolveTimezone(tz) {
158
197
  }
159
198
  }
160
199
  // ─── Timezone-aware date helpers ───────────────────────────────────────────────
161
- /** Shifts a "YYYY-MM-DD" string by N calendar days (pure date math, DST-safe via a noon-UTC anchor). */
200
+ /** True only for a real calendar date in strict "YYYY-MM-DD" form (rejects "2026-02-31"). */
201
+ function isRealPlainDate(s) {
202
+ if (!PLAIN_DATE_RE.test(s))
203
+ return false;
204
+ const [y, m, d] = s.split('-').map(Number);
205
+ const dt = new Date(Date.UTC(y, m - 1, d));
206
+ return (dt.getUTCFullYear() === y &&
207
+ dt.getUTCMonth() === m - 1 &&
208
+ dt.getUTCDate() === d);
209
+ }
210
+ /** Shifts a "YYYY-MM-DD" string by N calendar days (pure UTC date math — DST-proof). */
162
211
  function shiftLocalDateString(dateStr, days) {
163
212
  const [y, m, d] = dateStr.split('-').map(Number);
164
- const anchor = new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
165
- const shifted = (0, date_fns_1.addDays)(anchor, days);
166
- return shifted.toISOString().slice(0, 10);
213
+ const dt = new Date(Date.UTC(y, m - 1, d));
214
+ dt.setUTCDate(dt.getUTCDate() + days);
215
+ return dt.toISOString().slice(0, 10);
167
216
  }
168
217
  /** [start, end) UTC instants for a single local calendar date in `timezone`. */
169
218
  function plainDateToUtcRange(dateStr, timezone) {
@@ -171,39 +220,40 @@ function plainDateToUtcRange(dateStr, timezone) {
171
220
  const end = (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(dateStr, 1)}T00:00:00.000`, timezone);
172
221
  return { start, end };
173
222
  }
174
- /** Parses a single date/datetime string to a scalar UTC Date (used for $in/$nin, where a range object isn't valid). */
223
+ /** Parses a single date/datetime string to a scalar UTC Date. */
175
224
  function coerceDateScalar(value, timezone) {
176
- const raw = PLAIN_DATE_RE.test(value) ? `${value}T00:00:00.000` : value;
177
- const parsed = HAS_OFFSET_RE.test(value)
178
- ? new Date(value)
179
- : (0, date_fns_tz_1.fromZonedTime)(raw, timezone);
225
+ let parsed;
226
+ if (PLAIN_DATE_RE.test(value)) {
227
+ if (!isRealPlainDate(value))
228
+ return undefined;
229
+ parsed = (0, date_fns_tz_1.fromZonedTime)(`${value}T00:00:00.000`, timezone);
230
+ }
231
+ else if (HAS_OFFSET_RE.test(value)) {
232
+ parsed = new Date(value);
233
+ }
234
+ else {
235
+ parsed = (0, date_fns_tz_1.fromZonedTime)(value, timezone);
236
+ }
180
237
  return isNaN(parsed.getTime()) ? undefined : parsed;
181
238
  }
182
- function isDateField(path, explicit) {
183
- if (!path)
239
+ function explicitHas(path, explicit) {
240
+ if (!explicit || explicit.size === 0 || !path)
184
241
  return false;
185
242
  const lc = path.toLowerCase();
186
- if (explicit && explicit.size > 0) {
187
- if (explicit.has(lc))
188
- return true;
189
- const lastSeg = lc.split('.').pop() ?? lc;
190
- return explicit.has(lastSeg);
191
- }
192
- return DATE_FIELD_RE.test(path);
243
+ if (explicit.has(lc))
244
+ return true;
245
+ const lastSeg = lc.split('.').pop() ?? lc;
246
+ return explicit.has(lastSeg);
193
247
  }
194
- function isObjectIdField(path, explicit) {
195
- if (!path)
248
+ // ─── Sanitization ─────────────────────────────────────────────────────────────
249
+ function isPlainObject(v) {
250
+ if (v === null || typeof v !== 'object' || Array.isArray(v))
196
251
  return false;
197
- const lc = path.toLowerCase();
198
- if (explicit && explicit.size > 0) {
199
- if (explicit.has(lc))
200
- return true;
201
- const lastSeg = lc.split('.').pop() ?? lc;
202
- return explicit.has(lastSeg);
203
- }
204
- return OBJECTID_FIELD_RE.test(path);
252
+ if (v instanceof Date)
253
+ return false;
254
+ const proto = Object.getPrototypeOf(v);
255
+ return proto === Object.prototype || proto === null;
205
256
  }
206
- // ─── Sanitization ─────────────────────────────────────────────────────────────
207
257
  /** Recursively strips non-plain values (class instances, functions) from client input. */
208
258
  function sanitize(value, depth = 0, path = '', onDrop) {
209
259
  if (depth >= MAX_NESTING_DEPTH) {
@@ -230,16 +280,16 @@ function sanitize(value, depth = 0, path = '', onDrop) {
230
280
  }
231
281
  return out;
232
282
  }
233
- if (t === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
283
+ if (isPlainObject(value)) {
234
284
  const src = value;
235
285
  const out = {};
236
- for (const k in src) {
237
- if (Object.prototype.hasOwnProperty.call(src, k)) {
238
- const childPath = path ? `${path}.${k}` : k;
239
- const s = sanitize(src[k], depth + 1, childPath, onDrop);
240
- if (s !== undefined)
241
- out[k] = s;
242
- }
286
+ for (const k of Object.keys(src)) {
287
+ if (DANGEROUS_KEYS.has(k))
288
+ continue;
289
+ const childPath = path ? `${path}.${k}` : k;
290
+ const s = sanitize(src[k], depth + 1, childPath, onDrop);
291
+ if (s !== undefined)
292
+ out[k] = s;
243
293
  }
244
294
  return out;
245
295
  }
@@ -264,27 +314,24 @@ function buildAllowedStructures(allowedFields) {
264
314
  function isFieldAllowed(field, allowedLookup) {
265
315
  return allowedLookup.has(field.toLowerCase());
266
316
  }
267
- function isPlainObject(v) {
268
- return (v !== null &&
269
- typeof v === 'object' &&
270
- !Array.isArray(v) &&
271
- !(v instanceof Date) &&
272
- Object.getPrototypeOf(v) === Object.prototype);
273
- }
274
317
  /** Strips any non-operator key not present in the allowlist; recurses into logical operators. */
275
318
  function enforceAllowlist(filter, allowedLookup, canonicalMap) {
276
319
  if (allowedLookup.size === 0)
277
320
  return filter;
278
321
  const out = {};
279
- for (const k in filter) {
280
- if (!Object.prototype.hasOwnProperty.call(filter, k))
281
- continue;
322
+ for (const k of Object.keys(filter)) {
282
323
  const v = filter[k];
283
324
  if (k.startsWith('$')) {
284
325
  if (Array.isArray(v)) {
285
- out[k] = v.map((item) => isPlainObject(item)
326
+ // Clauses that were fully stripped are dropped (an empty clause would
327
+ // otherwise match everything inside $or).
328
+ const items = v
329
+ .map((item) => isPlainObject(item)
286
330
  ? enforceAllowlist(item, allowedLookup, canonicalMap)
287
- : item);
331
+ : item)
332
+ .filter((item) => !(isPlainObject(item) && Object.keys(item).length === 0));
333
+ if (items.length > 0)
334
+ out[k] = items;
288
335
  }
289
336
  else if (isPlainObject(v)) {
290
337
  out[k] = enforceAllowlist(v, allowedLookup, canonicalMap);
@@ -300,53 +347,105 @@ function enforceAllowlist(filter, allowedLookup, canonicalMap) {
300
347
  }
301
348
  return out;
302
349
  }
303
- // ─── Fused coercion pass (timezone-aware) ──────────────────────────────────────
304
- function coerceAll(value, timezone, dateFieldsLookup, objectIdFieldsLookup, parentKey = '', parentOp) {
305
- if (value === null)
306
- return null;
307
- if (typeof value === 'string') {
308
- if (value === 'true')
309
- return true;
310
- if (value === 'false')
311
- return false;
312
- if (isDateField(parentKey, dateFieldsLookup)) {
313
- if (parentOp && IN_LIKE_OPS.has(parentOp)) {
314
- return coerceDateScalar(value, timezone) ?? value;
315
- }
316
- if (PLAIN_DATE_RE.test(value)) {
317
- const { start, end } = plainDateToUtcRange(value, timezone);
350
+ // ─── Fused coercion pass (timezone + schema aware) ─────────────────────────────
351
+ function parseNumeric(value) {
352
+ if (!NUMERIC_RE.test(value))
353
+ return undefined;
354
+ const n = Number(value);
355
+ if (!Number.isFinite(n))
356
+ return undefined;
357
+ if (Number.isInteger(n) && !Number.isSafeInteger(n))
358
+ return undefined;
359
+ return n;
360
+ }
361
+ function resolveKind(path, ctx) {
362
+ if (!path)
363
+ return { strict: false };
364
+ if (explicitHas(path, ctx.dateExplicit))
365
+ return { kind: 'date', strict: true };
366
+ if (explicitHas(path, ctx.oidExplicit))
367
+ return { kind: 'objectid', strict: true };
368
+ const st = ctx.typeOf(path);
369
+ if (st)
370
+ return { kind: st, strict: true };
371
+ if (!(ctx.dateExplicit && ctx.dateExplicit.size > 0) &&
372
+ DATE_FIELD_RE.test(path))
373
+ return { kind: 'date', strict: false };
374
+ if (!(ctx.oidExplicit && ctx.oidExplicit.size > 0) &&
375
+ OBJECTID_FIELD_RE.test(path))
376
+ return { kind: 'objectid', strict: false };
377
+ return { strict: false };
378
+ }
379
+ function coerceDateValue(value, op, timezone) {
380
+ if (op && IN_LIKE_OPS.has(op)) {
381
+ return coerceDateScalar(value, timezone) ?? value;
382
+ }
383
+ if (isRealPlainDate(value)) {
384
+ const { start, end } = plainDateToUtcRange(value, timezone);
385
+ if (isNaN(start.getTime()) || isNaN(end.getTime()))
386
+ return value;
387
+ switch (op) {
388
+ case undefined:
318
389
  return { $gte: start, $lt: end };
319
- }
320
- return coerceDateScalar(value, timezone) ?? value;
321
- }
322
- // ObjectId coercion — applies to bare equality values ("?categoryId=...")
323
- // as well as values nested under comparison/membership operators
324
- // ("?categoryId[in]=...,..."), since a plain string never matches an
325
- // ObjectId-typed field in MongoDB (different BSON types). Gated on the
326
- // field heuristic/explicit list AND a strict 24-char hex shape so we
327
- // never misinterpret a coincidentally-24-char plain string field.
328
- if (isObjectIdField(parentKey, objectIdFieldsLookup) &&
329
- HEX24_RE.test(value) &&
330
- (0, mongoose_1.isValidObjectId)(value)) {
331
- return new mongoose_1.Types.ObjectId(value);
332
- }
333
- // Numeric coercion for comparison/membership operators (eq/ne/gt/gte/lt/lte/in/nin).
334
- // Without this, a string like "50" under { $lte: "50" } never matches a
335
- // Number field in MongoDB, since comparison operators are type-sensitive.
336
- if (parentOp &&
337
- COERCIBLE_OPS.has(parentOp) &&
338
- value.trim() !== '' &&
339
- !isNaN(Number(value))) {
340
- return Number(value);
390
+ case 'gt':
391
+ // "after the whole day" -> $gt (end - 1ms), so a doc stamped exactly at
392
+ // next-day 00:00:00.000 is included (returning `end` would drop it).
393
+ return new Date(end.getTime() - 1);
394
+ case 'lte':
395
+ return new Date(end.getTime() - 1);
396
+ default: // gte / lt / eq / ne (eq/ne are normally intercepted earlier)
397
+ return start;
341
398
  }
399
+ }
400
+ return coerceDateScalar(value, timezone) ?? value;
401
+ }
402
+ function coerceString(value, path, op, ctx) {
403
+ const { kind, strict } = resolveKind(path, ctx);
404
+ if (kind === 'string')
342
405
  return value;
406
+ if (kind === 'date')
407
+ return coerceDateValue(value, op, ctx.timezone);
408
+ if (kind === 'objectid') {
409
+ if (HEX24_RE.test(value))
410
+ return new mongoose_1.Types.ObjectId(value);
411
+ if (strict)
412
+ return value;
413
+ }
414
+ else if (kind === 'number') {
415
+ return parseNumeric(value) ?? value;
416
+ }
417
+ else if (kind === 'boolean') {
418
+ return value === 'true' ? true : value === 'false' ? false : value;
419
+ }
420
+ // Unknown field type (e.g. joined/computed field) — conservative heuristics.
421
+ if (value === 'true')
422
+ return true;
423
+ if (value === 'false')
424
+ return false;
425
+ if (op && COERCIBLE_OPS.has(op)) {
426
+ const n = parseNumeric(value);
427
+ if (n !== undefined)
428
+ return n;
429
+ }
430
+ return value;
431
+ }
432
+ /**
433
+ * `inFilter` is true at the root of a filter and inside logical operators
434
+ * ($and/$or/$nor), where keys are field names; false inside a field's value,
435
+ * where keys are comparison operators or sub-paths.
436
+ */
437
+ function coerceAll(value, ctx, path = '', op, inFilter = true) {
438
+ if (value === null)
439
+ return null;
440
+ if (typeof value === 'string') {
441
+ return path ? coerceString(value, path, op, ctx) : value;
343
442
  }
344
443
  if (typeof value !== 'object' || value instanceof Date)
345
444
  return value;
346
445
  if (Array.isArray(value)) {
347
446
  const out = [];
348
- for (let i = 0; i < value.length; i++) {
349
- const coerced = coerceAll(value[i], timezone, dateFieldsLookup, objectIdFieldsLookup, parentKey, parentOp);
447
+ for (const item of value) {
448
+ const coerced = coerceAll(item, ctx, path, op, inFilter);
350
449
  if (coerced !== undefined)
351
450
  out.push(coerced);
352
451
  }
@@ -354,37 +453,79 @@ function coerceAll(value, timezone, dateFieldsLookup, objectIdFieldsLookup, pare
354
453
  }
355
454
  const src = value;
356
455
  const out = {};
357
- for (const k in src) {
358
- if (!Object.prototype.hasOwnProperty.call(src, k))
456
+ for (const k of Object.keys(src)) {
457
+ if (DANGEROUS_KEYS.has(k))
458
+ continue;
459
+ const v = src[k];
460
+ if (inFilter) {
461
+ out[k] = k.startsWith('$')
462
+ ? coerceAll(v, ctx, '', undefined, true)
463
+ : coerceAll(v, ctx, k, undefined, false);
359
464
  continue;
360
- const newKey = COERCIBLE_OPS.has(k) ? `$${k}` : k;
465
+ }
361
466
  const isOp = k.startsWith('$') || COERCIBLE_OPS.has(k);
362
- const childPath = isOp ? parentKey : parentKey ? `${parentKey}.${k}` : k;
363
- out[newKey] = coerceAll(src[k], timezone, dateFieldsLookup, objectIdFieldsLookup, childPath, isOp ? k : undefined);
467
+ if (!isOp) {
468
+ out[k] = coerceAll(v, ctx, path ? `${path}.${k}` : k, undefined, false);
469
+ continue;
470
+ }
471
+ const bare = k.startsWith('$') ? k.slice(1) : k;
472
+ const outKey = k.startsWith('$') ? k : `$${k}`;
473
+ // ?field[eq]=2026-09-01 / [ne]= on a date field -> whole-day range semantics.
474
+ if ((bare === 'eq' || bare === 'ne') &&
475
+ typeof v === 'string' &&
476
+ isRealPlainDate(v) &&
477
+ resolveKind(path, ctx).kind === 'date') {
478
+ const { start, end } = plainDateToUtcRange(v, ctx.timezone);
479
+ if (!isNaN(start.getTime()) && !isNaN(end.getTime())) {
480
+ if (bare === 'eq') {
481
+ out.$gte = start;
482
+ out.$lt = end;
483
+ }
484
+ else {
485
+ out.$not = { $gte: start, $lt: end };
486
+ }
487
+ continue;
488
+ }
489
+ }
490
+ // ?field[in]=a,b,c -> ['a','b','c']
491
+ const child = IN_LIKE_OPS.has(bare) && typeof v === 'string'
492
+ ? v
493
+ .split(',')
494
+ .map((s) => s.trim())
495
+ .filter(Boolean)
496
+ : v;
497
+ out[outKey] = coerceAll(child, ctx, path, bare, false);
364
498
  }
365
499
  return out;
366
500
  }
367
501
  // ─── Operator validation ────────────────────────────────────────────────────────
368
- /** Throws on any BANNED_OPERATORS key at any depth, and on any top-level $ key not in ALLOWED_TOP_LEVEL_OPS. */
369
- function rejectDisallowedOperators(filter, depth = 0) {
370
- for (const k in filter) {
371
- if (!Object.prototype.hasOwnProperty.call(filter, k))
372
- continue;
502
+ /**
503
+ * Throws on any BANNED_OPERATORS key at any depth. When `topLevelCheck` is true
504
+ * (client input) it also throws on any top-level $ key not in ALLOWED_TOP_LEVEL_OPS
505
+ * and requires logical operators to hold a non-empty array of plain objects.
506
+ */
507
+ function rejectDisallowedOperators(filter, depth = 0, topLevelCheck = true) {
508
+ for (const k of Object.keys(filter)) {
373
509
  if (BANNED_OPERATORS.has(k)) {
374
510
  throw new QueryAggregateValidationError(`Disallowed operator in query: "${k}"`);
375
511
  }
376
- if (depth === 0 && k.startsWith('$') && !ALLOWED_TOP_LEVEL_OPS.has(k)) {
377
- throw new QueryAggregateValidationError(`Disallowed top-level operator in query string: "${k}"`);
378
- }
379
512
  const v = filter[k];
513
+ if (topLevelCheck && depth === 0 && k.startsWith('$')) {
514
+ if (!ALLOWED_TOP_LEVEL_OPS.has(k)) {
515
+ throw new QueryAggregateValidationError(`Disallowed top-level operator in query string: "${k}"`);
516
+ }
517
+ if (!Array.isArray(v) || v.length === 0 || !v.every(isPlainObject)) {
518
+ throw new QueryAggregateValidationError(`Operator "${k}" requires a non-empty array of conditions`);
519
+ }
520
+ }
380
521
  if (Array.isArray(v)) {
381
522
  for (const item of v) {
382
523
  if (isPlainObject(item))
383
- rejectDisallowedOperators(item, depth + 1);
524
+ rejectDisallowedOperators(item, depth + 1, topLevelCheck);
384
525
  }
385
526
  }
386
527
  else if (isPlainObject(v)) {
387
- rejectDisallowedOperators(v, depth + 1);
528
+ rejectDisallowedOperators(v, depth + 1, topLevelCheck);
388
529
  }
389
530
  }
390
531
  }
@@ -396,7 +537,7 @@ function rejectBannedStages(stage) {
396
537
  }
397
538
  if (!isPlainObject(stage))
398
539
  return;
399
- for (const k in stage) {
540
+ for (const k of Object.keys(stage)) {
400
541
  if (BANNED_STAGE_OPERATORS.has(k)) {
401
542
  throw new QueryAggregateValidationError(`Disallowed pipeline stage: "${k}"`);
402
543
  }
@@ -404,15 +545,14 @@ function rejectBannedStages(stage) {
404
545
  }
405
546
  }
406
547
  // ─── Filter builder ───────────────────────────────────────────────────────────
407
- function buildFilter(raw, allowedLookup, canonicalMap, timezone, dateFieldsLookup, objectIdFieldsLookup, onDrop) {
548
+ function buildFilter(raw, allowedLookup, canonicalMap, ctx, onDrop) {
408
549
  const stripped = {};
409
- for (const k in raw) {
410
- if (Object.prototype.hasOwnProperty.call(raw, k) && !RESERVED_KEYS.has(k)) {
550
+ for (const k of Object.keys(raw)) {
551
+ if (!RESERVED_KEYS.has(k) && !DANGEROUS_KEYS.has(k))
411
552
  stripped[k] = raw[k];
412
- }
413
553
  }
414
554
  const safe = sanitize(stripped, 0, '', onDrop);
415
- const coerced = coerceAll(safe, timezone, dateFieldsLookup, objectIdFieldsLookup);
555
+ const coerced = coerceAll(safe, ctx);
416
556
  const allowed = enforceAllowlist(coerced, allowedLookup, canonicalMap);
417
557
  rejectDisallowedOperators(allowed);
418
558
  return allowed;
@@ -429,7 +569,7 @@ function parseSort(sort, allowedLookup, canonicalMap) {
429
569
  continue;
430
570
  const desc = trimmed.startsWith('-');
431
571
  const field = desc ? trimmed.slice(1).trim() : trimmed;
432
- if (!field)
572
+ if (!field || field.startsWith('$') || DANGEROUS_KEYS.has(field))
433
573
  continue;
434
574
  if (allowedLookup.size > 0) {
435
575
  if (!isFieldAllowed(field, allowedLookup))
@@ -464,16 +604,182 @@ function sanitizeProjectionString(projection, allowedLookup, canonicalMap) {
464
604
  })
465
605
  .join(' ');
466
606
  }
607
+ /**
608
+ * Converts "a b -c" to { a: 1, b: 1, c: 0 }. Tokens with `$`/empty names are
609
+ * ignored. MongoDB forbids mixing inclusion and exclusion (other than `_id`),
610
+ * so when both appear the inclusion fields win and exclusions (except `_id`)
611
+ * are dropped.
612
+ */
467
613
  function projectionStringToObject(projection) {
468
- const out = {};
614
+ const inc = {};
615
+ const exc = {};
469
616
  for (const token of projection.split(/\s+/).filter(Boolean)) {
470
- if (token.startsWith('-'))
471
- out[token.slice(1)] = 0;
617
+ const neg = token.startsWith('-');
618
+ const field = neg ? token.slice(1) : token;
619
+ if (!field || field.includes('$') || DANGEROUS_KEYS.has(field))
620
+ continue;
621
+ if (neg)
622
+ exc[field] = 0;
472
623
  else
473
- out[token] = 1;
624
+ inc[field] = 1;
474
625
  }
626
+ return normalizeProjection(inc, exc);
627
+ }
628
+ function normalizeProjection(inc, exc) {
629
+ if (Object.keys(inc).length === 0)
630
+ return exc;
631
+ const out = { ...inc };
632
+ if (exc._id === 0)
633
+ out._id = 0;
475
634
  return out;
476
635
  }
636
+ function normalizeProjectionObject(p) {
637
+ const inc = {};
638
+ const exc = {};
639
+ for (const k of Object.keys(p)) {
640
+ if (!k || k.includes('$') || DANGEROUS_KEYS.has(k))
641
+ continue;
642
+ if (p[k] === 0)
643
+ exc[k] = 0;
644
+ else
645
+ inc[k] = 1;
646
+ }
647
+ const hasIncNonId = Object.keys(inc).some((k) => k !== '_id');
648
+ if (!hasIncNonId) {
649
+ // Pure exclusion (an `_id: 1` alone is just the default).
650
+ delete inc._id;
651
+ return Object.keys(inc).length === 0 && Object.keys(exc).length === 0
652
+ ? {}
653
+ : exc;
654
+ }
655
+ return normalizeProjection(inc, exc);
656
+ }
657
+ /**
658
+ * Applies a client-requested exclusion-only projection ("-name") ON TOP of the
659
+ * developer's default projection instead of replacing it. Without this, a
660
+ * client sending ?fields=-name would turn the projection into { name: 0 },
661
+ * which returns every other field — including fields that are not allowlisted
662
+ * and fields the default projection deliberately hid.
663
+ */
664
+ function applyClientExclusions(clientExc, defaultProj) {
665
+ if (!defaultProj)
666
+ return clientExc;
667
+ const defaultIsInclusion = Object.keys(defaultProj).some((k) => k !== '_id' && defaultProj[k] === 1);
668
+ if (!defaultIsInclusion) {
669
+ // Default is itself exclusion-only: union of both exclusion sets.
670
+ return { ...defaultProj, ...clientExc };
671
+ }
672
+ const out = { ...defaultProj };
673
+ for (const ex of Object.keys(clientExc)) {
674
+ if (ex === '_id') {
675
+ out._id = 0;
676
+ continue;
677
+ }
678
+ for (const k of Object.keys(out)) {
679
+ if (k === ex || k.startsWith(`${ex}.`))
680
+ delete out[k];
681
+ }
682
+ }
683
+ // If nothing is left to include, never degrade into an exclusion-only
684
+ // projection (that would return every field) — keep the default instead.
685
+ const stillInclusion = Object.keys(out).some((k) => k !== '_id' && out[k] === 1);
686
+ return stillInclusion ? out : { ...defaultProj };
687
+ }
688
+ // ─── Misc helpers ─────────────────────────────────────────────────────────────
689
+ function getByPath(obj, path) {
690
+ let cur = obj;
691
+ for (const part of path.split('.')) {
692
+ if (cur === null || typeof cur !== 'object')
693
+ return undefined;
694
+ cur = cur[part];
695
+ }
696
+ return cur;
697
+ }
698
+ /** Deletes a dotted path and removes parent objects left empty by the deletion. */
699
+ function deletePath(obj, path) {
700
+ const parts = path.split('.');
701
+ const parents = [];
702
+ let cur = obj;
703
+ for (let i = 0; i < parts.length - 1; i++) {
704
+ const next = cur[parts[i]];
705
+ if (!isPlainObject(next))
706
+ return;
707
+ parents.push(cur);
708
+ cur = next;
709
+ }
710
+ delete cur[parts[parts.length - 1]];
711
+ for (let i = parts.length - 2; i >= 0; i--) {
712
+ if (Object.keys(cur).length !== 0)
713
+ break;
714
+ const parent = parents[i];
715
+ delete parent[parts[i]];
716
+ cur = parent;
717
+ }
718
+ }
719
+ /** Converts 24-hex strings to ObjectIds (recursing through arrays / operator objects). */
720
+ function castObjectIds(value) {
721
+ if (typeof value === 'string')
722
+ return HEX24_RE.test(value) ? new mongoose_1.Types.ObjectId(value) : value;
723
+ if (Array.isArray(value))
724
+ return value.map(castObjectIds);
725
+ if (isPlainObject(value)) {
726
+ const out = {};
727
+ for (const k of Object.keys(value))
728
+ out[k] = castObjectIds(value[k]);
729
+ return out;
730
+ }
731
+ return value;
732
+ }
733
+ function assertFieldPath(field, label) {
734
+ if (typeof field !== 'string' || !FIELD_PATH_RE.test(field)) {
735
+ throw new QueryAggregateValidationError(`${label}: invalid field path "${String(field)}"`);
736
+ }
737
+ }
738
+ function encodeTyped(raw) {
739
+ if (raw === undefined || raw === null)
740
+ return { t: 'raw', v: null };
741
+ if (raw instanceof Date) {
742
+ return isNaN(raw.getTime())
743
+ ? { t: 'raw', v: null }
744
+ : { t: 'date', v: raw.toISOString() };
745
+ }
746
+ if (raw instanceof mongoose_1.Types.ObjectId)
747
+ return { t: 'oid', v: raw.toHexString() };
748
+ if (typeof raw === 'string' ||
749
+ typeof raw === 'number' ||
750
+ typeof raw === 'boolean') {
751
+ return { t: 'raw', v: raw };
752
+ }
753
+ throw new QueryAggregateValidationError('paginateCursor: the sort field must hold a scalar value (string, number, boolean, Date or ObjectId)');
754
+ }
755
+ function decodeTyped(x) {
756
+ const bad = () => new QueryAggregateValidationError('paginateCursor: invalid cursor');
757
+ if (!isPlainObject(x))
758
+ throw bad();
759
+ const { t, v } = x;
760
+ if (t === 'date') {
761
+ if (typeof v !== 'string')
762
+ throw bad();
763
+ const d = new Date(v);
764
+ if (isNaN(d.getTime()))
765
+ throw bad();
766
+ return d;
767
+ }
768
+ if (t === 'oid') {
769
+ if (typeof v !== 'string' || !HEX24_RE.test(v))
770
+ throw bad();
771
+ return new mongoose_1.Types.ObjectId(v);
772
+ }
773
+ if (t === 'raw') {
774
+ if (v === null ||
775
+ typeof v === 'string' ||
776
+ typeof v === 'number' ||
777
+ typeof v === 'boolean') {
778
+ return v;
779
+ }
780
+ }
781
+ throw bad();
782
+ }
477
783
  // ─── QueryAggregate ─────────────────────────────────────────────────────────────
478
784
  /**
479
785
  * Fluent aggregation-pipeline builder / paginator for Mongoose 8/9, with
@@ -486,26 +792,49 @@ class QueryAggregate {
486
792
  this._dateFieldsLookup = null;
487
793
  this._objectIdFieldsLookup = null;
488
794
  /** URL-derived filter and server conditions are kept separate so server
489
- * conditions (merged last) can never be overridden by URL params. */
795
+ * conditions can never be overridden by URL params. Server conditions are a
796
+ * list (AND-ed together) so repeated conditions on one field never overwrite
797
+ * each other. */
490
798
  this._urlFilter = {};
491
- this._serverConditions = {};
799
+ this._serverConditions = [];
492
800
  this._searchOr = [];
493
801
  this._sort = { ...DEFAULT_SORT };
494
802
  this._projection = null;
495
803
  this._defaultProjection = null;
496
804
  /** $lookup/$unwind/addStage() stages, in call order, spliced in after the base $match. */
497
805
  this._stages = [];
806
+ /** Root names of `as` aliases created by lookups; conditions on them run post-join. */
807
+ this._joinAliases = new Set();
808
+ /** Index in `_stages` right after the last $lookup — where the post-join $match goes. */
809
+ this._postJoinIndex = 0;
810
+ this._kindCache = new Map();
811
+ this._pathExistsCache = new Map();
498
812
  this.model = model;
499
813
  this.qs = Object.freeze({ ...queryString });
814
+ const maxLimit = typeof options.maxLimit === 'number' &&
815
+ Number.isFinite(options.maxLimit) &&
816
+ options.maxLimit >= 1
817
+ ? Math.floor(options.maxLimit)
818
+ : DEFAULT_MAX_LIMIT;
819
+ const maxTimeMS = typeof options.maxTimeMS === 'number' &&
820
+ Number.isFinite(options.maxTimeMS) &&
821
+ options.maxTimeMS >= 0
822
+ ? options.maxTimeMS
823
+ : DEFAULT_MAX_TIME_MS;
824
+ const weekStartsOn = typeof options.weekStartsOn === 'number' &&
825
+ Number.isInteger(options.weekStartsOn) &&
826
+ options.weekStartsOn >= 0 &&
827
+ options.weekStartsOn <= 6
828
+ ? options.weekStartsOn
829
+ : 6;
500
830
  this.options = {
501
831
  timezone: resolveTimezone(options.timezone),
502
- maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
832
+ maxTimeMS,
503
833
  slowQueryThresholdMS: options.slowQueryThresholdMS ??
504
- options.maxTimeMS ??
505
- DEFAULT_MAX_TIME_MS,
506
- maxLimit: options.maxLimit ?? DEFAULT_MAX_LIMIT,
834
+ (maxTimeMS > 0 ? maxTimeMS : DEFAULT_MAX_TIME_MS),
835
+ maxLimit,
507
836
  allowDiskUse: options.allowDiskUse ?? false,
508
- weekStartsOn: options.weekStartsOn ?? 6,
837
+ weekStartsOn,
509
838
  onSlowQuery: options.onSlowQuery,
510
839
  onSanitizeDrop: options.onSanitizeDrop,
511
840
  };
@@ -516,6 +845,45 @@ class QueryAggregate {
516
845
  get timezone() {
517
846
  return this.options.timezone;
518
847
  }
848
+ // ── Schema helpers ────────────────────────────────────────────────────────
849
+ schemaType(path) {
850
+ try {
851
+ const schema = this.model.schema;
852
+ return schema?.path(path) ?? undefined;
853
+ }
854
+ catch {
855
+ return undefined;
856
+ }
857
+ }
858
+ /** Field type from the model schema, when known (undefined for joined/computed/unknown paths). */
859
+ schemaKind(path) {
860
+ if (this._kindCache.has(path))
861
+ return this._kindCache.get(path);
862
+ const st = this.schemaType(path);
863
+ let instance = st?.instance;
864
+ if (instance === 'Array') {
865
+ instance = st?.embeddedSchemaType?.instance ?? st?.caster?.instance;
866
+ }
867
+ const kind = instance ? SCHEMA_KIND_MAP[instance] : undefined;
868
+ this._kindCache.set(path, kind);
869
+ return kind;
870
+ }
871
+ schemaHasPath(path) {
872
+ const cached = this._pathExistsCache.get(path);
873
+ if (cached !== undefined)
874
+ return cached;
875
+ const exists = this.schemaType(path) !== undefined;
876
+ this._pathExistsCache.set(path, exists);
877
+ return exists;
878
+ }
879
+ coerceCtx() {
880
+ return {
881
+ timezone: this.options.timezone,
882
+ dateExplicit: this._dateFieldsLookup,
883
+ oidExplicit: this._objectIdFieldsLookup,
884
+ typeOf: (p) => this.schemaKind(p),
885
+ };
886
+ }
519
887
  // ── Configuration ─────────────────────────────────────────────────────────
520
888
  /** Fields the client may filter, sort, and project. Case-insensitive. Call before filter()/sort()/project(). */
521
889
  allowFields(fields) {
@@ -524,12 +892,12 @@ class QueryAggregate {
524
892
  this._canonicalMap = canonical;
525
893
  return this;
526
894
  }
527
- /** Explicit list of fields treated as dates for timezone-aware coercion. Falls back to a name heuristic (createdAt/updatedAt/...) when omitted. */
895
+ /** Explicit list of fields treated as dates for timezone-aware coercion. Falls back to the model schema / a name heuristic (createdAt/updatedAt/...) when omitted. */
528
896
  dateFields(fields) {
529
897
  this._dateFieldsLookup = new Set(fields.map((f) => f.toLowerCase()));
530
898
  return this;
531
899
  }
532
- /** Explicit list of fields treated as ObjectId refs for coercion (client-supplied hex strings -> Types.ObjectId). Falls back to a name heuristic (_id/*Id) when omitted. */
900
+ /** Explicit list of fields treated as ObjectId refs for coercion (client-supplied hex strings -> Types.ObjectId). Falls back to the model schema / a name heuristic (_id/*Id) when omitted. */
533
901
  objectIdFields(fields) {
534
902
  this._objectIdFieldsLookup = new Set(fields.map((f) => f.toLowerCase()));
535
903
  return this;
@@ -537,44 +905,56 @@ class QueryAggregate {
537
905
  // ── Builder methods ───────────────────────────────────────────────────────
538
906
  /** Parses URL query params (req.query) into a Mongoose filter. Only allowlisted fields pass through. */
539
907
  filter() {
540
- const parsed = buildFilter(this.qs, this._allowedLookup, this._canonicalMap, this.options.timezone, this._dateFieldsLookup, this._objectIdFieldsLookup, this.options.onSanitizeDrop);
908
+ const parsed = buildFilter(this.qs, this._allowedLookup, this._canonicalMap, this.coerceCtx(), this.options.onSanitizeDrop);
541
909
  Object.assign(this._urlFilter, parsed);
542
910
  return this;
543
911
  }
544
- /** Mandatory server-side conditions the client cannot override — merged into the final $match last. */
912
+ /**
913
+ * Mandatory server-side conditions the client cannot override. Repeated
914
+ * calls (and range*() calls) are AND-ed together, never overwritten.
915
+ * Strings that are 24-hex ObjectIds on ObjectId schema paths are cast
916
+ * automatically (aggregate() does not auto-cast like find() does).
917
+ */
545
918
  where(conditions) {
546
919
  const asRecord = conditions;
547
- rejectDisallowedOperators(asRecord);
548
- Object.assign(this._serverConditions, asRecord);
920
+ for (const k of Object.keys(asRecord)) {
921
+ if (asRecord[k] === undefined) {
922
+ throw new QueryAggregateValidationError(`where: condition for "${k}" is undefined`);
923
+ }
924
+ }
925
+ rejectDisallowedOperators(asRecord, 0, false);
926
+ if (Object.keys(asRecord).length === 0)
927
+ return this;
928
+ this._serverConditions.push(this.castServerConditions(asRecord));
549
929
  return this;
550
930
  }
551
931
  /** Adds a hard, server-defined UTC date range (in this instance's timezone) on `field`. Not client-overridable. */
552
932
  range(field, preset) {
553
933
  const { start, end } = this.resolveRangePreset(preset);
554
- this._serverConditions[field] = { $gte: start, $lt: end };
934
+ this.pushRange(field, start, end);
555
935
  return this;
556
936
  }
557
- // ── Custom range methods (additive — RangePreset/.range() above is
558
- // untouched; these cover custom day / custom range / custom N-days /
559
- // custom N-hours / custom hour-of-day window / custom absolute datetime
560
- // window use cases) ─────────────────────────────────────────────────────
937
+ // ── Custom range methods ──────────────────────────────────────────────────
561
938
  /** Hard server-side condition for a single arbitrary local calendar date (e.g. "2026-03-14"), in this instance's timezone. Not client-overridable. */
562
939
  rangeCustomDay(field, date) {
563
- if (!PLAIN_DATE_RE.test(date)) {
564
- throw new QueryAggregateValidationError(`rangeCustomDay: "date" must be in YYYY-MM-DD format, got "${date}"`);
940
+ if (!isRealPlainDate(date)) {
941
+ throw new QueryAggregateValidationError(`rangeCustomDay: "date" must be a valid date in YYYY-MM-DD format, got "${date}"`);
565
942
  }
566
943
  const { start, end } = this.utcRangeForLocalDates(date, date);
567
- this._serverConditions[field] = { $gte: start, $lt: end };
944
+ this.pushRange(field, start, end);
568
945
  return this;
569
946
  }
570
947
  /** Hard server-side condition for an arbitrary inclusive local-date span (e.g. { from: "2026-01-01", to: "2026-01-31" }), in this instance's timezone. Not client-overridable. */
571
948
  rangeBetween(field, custom) {
572
949
  const { from, to } = custom;
573
- if (!PLAIN_DATE_RE.test(from) || !PLAIN_DATE_RE.test(to)) {
574
- throw new QueryAggregateValidationError(`rangeBetween: "from"/"to" must be in YYYY-MM-DD format, got "${from}" / "${to}"`);
950
+ if (!isRealPlainDate(from) || !isRealPlainDate(to)) {
951
+ throw new QueryAggregateValidationError(`rangeBetween: "from"/"to" must be valid dates in YYYY-MM-DD format, got "${from}" / "${to}"`);
952
+ }
953
+ if (from > to) {
954
+ throw new QueryAggregateValidationError(`rangeBetween: "from" (${from}) must not be after "to" (${to})`);
575
955
  }
576
956
  const { start, end } = this.utcRangeForLocalDates(from, to);
577
- this._serverConditions[field] = { $gte: start, $lt: end };
957
+ this.pushRange(field, start, end);
578
958
  return this;
579
959
  }
580
960
  /** Hard server-side condition for a rolling window of the last N whole calendar days (inclusive of today), in this instance's timezone. Not client-overridable. */
@@ -582,12 +962,10 @@ class QueryAggregate {
582
962
  if (!Number.isInteger(days) || days < 1) {
583
963
  throw new QueryAggregateValidationError(`rangeLastNDays: "days" must be a positive integer, got ${days}`);
584
964
  }
585
- const tz = this.options.timezone;
586
- const zonedNow = (0, date_fns_tz_1.toZonedTime)(new Date(), tz);
587
- const todayStr = (0, date_fns_1.format)(zonedNow, 'yyyy-MM-dd');
965
+ const todayStr = this.todayLocal();
588
966
  const fromStr = shiftLocalDateString(todayStr, -(days - 1));
589
967
  const { start, end } = this.utcRangeForLocalDates(fromStr, todayStr);
590
- this._serverConditions[field] = { $gte: start, $lt: end };
968
+ this.pushRange(field, start, end);
591
969
  return this;
592
970
  }
593
971
  /** Hard server-side condition for a rolling window of the last N hours, ending at the moment this is called (exact UTC instants — no calendar-date snapping). Not client-overridable. */
@@ -597,14 +975,17 @@ class QueryAggregate {
597
975
  }
598
976
  const end = new Date();
599
977
  const start = new Date(end.getTime() - hours * 60 * 60 * 1000);
600
- this._serverConditions[field] = { $gte: start, $lt: end };
978
+ if (isNaN(start.getTime())) {
979
+ throw new QueryAggregateValidationError(`rangeLastNHours: "hours" is too large, got ${hours}`);
980
+ }
981
+ this.pushRange(field, start, end);
601
982
  return this;
602
983
  }
603
984
  /** Hard server-side condition for an explicit hour-of-day window on a given local date (e.g. 09:00–17:00 on "2026-03-14"), in this instance's timezone. `toHour` is exclusive; pass 24 for "through end of day". Not client-overridable. */
604
985
  rangeHours(field, custom) {
605
986
  const { date, fromHour, toHour } = custom;
606
- if (!PLAIN_DATE_RE.test(date)) {
607
- throw new QueryAggregateValidationError(`rangeHours: "date" must be in YYYY-MM-DD format, got "${date}"`);
987
+ if (!isRealPlainDate(date)) {
988
+ throw new QueryAggregateValidationError(`rangeHours: "date" must be a valid date in YYYY-MM-DD format, got "${date}"`);
608
989
  }
609
990
  if (!Number.isInteger(fromHour) ||
610
991
  !Number.isInteger(toHour) ||
@@ -617,11 +998,13 @@ class QueryAggregate {
617
998
  }
618
999
  const tz = this.options.timezone;
619
1000
  const pad = (n) => String(n).padStart(2, '0');
620
- const start = (0, date_fns_tz_1.fromZonedTime)(`${date}T${pad(fromHour)}:00:00.000`, tz);
1001
+ const start = fromHour === 24
1002
+ ? (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(date, 1)}T00:00:00.000`, tz)
1003
+ : (0, date_fns_tz_1.fromZonedTime)(`${date}T${pad(fromHour)}:00:00.000`, tz);
621
1004
  const end = toHour === 24
622
1005
  ? (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(date, 1)}T00:00:00.000`, tz)
623
1006
  : (0, date_fns_tz_1.fromZonedTime)(`${date}T${pad(toHour)}:00:00.000`, tz);
624
- this._serverConditions[field] = { $gte: start, $lt: end };
1007
+ this.pushRange(field, start, end);
625
1008
  return this;
626
1009
  }
627
1010
  /**
@@ -640,12 +1023,12 @@ class QueryAggregate {
640
1023
  if (end <= start) {
641
1024
  throw new QueryAggregateValidationError(`rangeCustom: "to" (${custom.to}) must be after "from" (${custom.from})`);
642
1025
  }
643
- this._serverConditions[field] = { $gte: start, $lt: end };
1026
+ this.pushRange(field, start, end);
644
1027
  return this;
645
1028
  }
646
1029
  /** Case-insensitive full-text search across the given fields when ?q= is present. */
647
1030
  globalSearch(fields) {
648
- const raw = this.qs.q?.trim();
1031
+ const raw = asString(this.qs.q)?.trim();
649
1032
  if (!raw || raw.length > MAX_SEARCH_LENGTH || fields.length === 0)
650
1033
  return this;
651
1034
  const safeFields = this._allowedLookup.size > 0
@@ -661,8 +1044,9 @@ class QueryAggregate {
661
1044
  }
662
1045
  /** Parses ?sort= (e.g. "-createdAt,name"). Fields not in allowFields() are dropped; falls back to DEFAULT_SORT. */
663
1046
  sort() {
664
- if (this.qs.sort) {
665
- this._sort = parseSort(this.qs.sort, this._allowedLookup, this._canonicalMap);
1047
+ const raw = asString(this.qs.sort);
1048
+ if (raw) {
1049
+ this._sort = parseSort(raw, this._allowedLookup, this._canonicalMap);
666
1050
  }
667
1051
  return this;
668
1052
  }
@@ -674,21 +1058,28 @@ class QueryAggregate {
674
1058
  */
675
1059
  project(defaultProjection) {
676
1060
  if (defaultProjection) {
677
- this._defaultProjection =
678
- typeof defaultProjection === 'string'
679
- ? projectionStringToObject(defaultProjection)
680
- : defaultProjection;
1061
+ const obj = typeof defaultProjection === 'string'
1062
+ ? projectionStringToObject(defaultProjection)
1063
+ : normalizeProjectionObject(defaultProjection);
1064
+ this._defaultProjection = Object.keys(obj).length > 0 ? obj : null;
681
1065
  }
682
- if (this.qs.fields) {
683
- const raw = this.qs.fields
1066
+ const fieldsRaw = asString(this.qs.fields);
1067
+ if (fieldsRaw) {
1068
+ const raw = fieldsRaw
684
1069
  .split(',')
685
1070
  .map((f) => f.trim())
686
1071
  .filter(Boolean)
687
1072
  .join(' ');
688
1073
  const sanitized = sanitizeProjectionString(raw, this._allowedLookup, this._canonicalMap);
689
- this._projection = sanitized
690
- ? projectionStringToObject(sanitized)
691
- : this._defaultProjection;
1074
+ const obj = sanitized ? projectionStringToObject(sanitized) : {};
1075
+ const keys = Object.keys(obj);
1076
+ const isExclusionOnly = keys.length > 0 && keys.every((k) => obj[k] === 0);
1077
+ this._projection =
1078
+ keys.length === 0
1079
+ ? this._defaultProjection
1080
+ : isExclusionOnly
1081
+ ? applyClientExclusions(obj, this._defaultProjection)
1082
+ : obj;
692
1083
  }
693
1084
  else {
694
1085
  this._projection = this._defaultProjection;
@@ -697,6 +1088,12 @@ class QueryAggregate {
697
1088
  }
698
1089
  /** Adds a $lookup (join) stage, optionally followed by $unwind when `single` is true. */
699
1090
  lookup(opts) {
1091
+ const hasLocalForeign = Boolean(opts.localField && opts.foreignField);
1092
+ if (!hasLocalForeign && !opts.pipeline) {
1093
+ throw new QueryAggregateValidationError('lookup: provide either localField + foreignField or a pipeline');
1094
+ }
1095
+ if (opts.pipeline)
1096
+ rejectBannedStages(opts.pipeline);
700
1097
  const lookupStage = {
701
1098
  $lookup: {
702
1099
  from: opts.from,
@@ -712,15 +1109,48 @@ class QueryAggregate {
712
1109
  $unwind: { path: `$${opts.as}`, preserveNullAndEmptyArrays: true },
713
1110
  });
714
1111
  }
1112
+ this.registerJoin(opts.as);
715
1113
  return this;
716
1114
  }
717
1115
  /** Escape hatch for any other developer-authored stage ($addFields, $group, post-join $match, ...). Blocks $out/$merge only — this path is for trusted, server-defined stages, not client input. */
718
1116
  addStage(stage) {
719
1117
  rejectBannedStages(stage);
720
1118
  this._stages.push(stage);
1119
+ if ('$lookup' in stage) {
1120
+ const as = stage.$lookup.as;
1121
+ if (typeof as === 'string')
1122
+ this.registerJoin(as);
1123
+ }
721
1124
  return this;
722
1125
  }
723
1126
  // ── Private helpers ───────────────────────────────────────────────────────
1127
+ registerJoin(as) {
1128
+ this._joinAliases.add(as.split('.')[0]);
1129
+ this._postJoinIndex = this._stages.length;
1130
+ }
1131
+ pushRange(field, start, end) {
1132
+ if (isNaN(start.getTime()) || isNaN(end.getTime())) {
1133
+ throw new QueryAggregateValidationError(`Invalid date range for "${field}"`);
1134
+ }
1135
+ this._serverConditions.push({ [field]: { $gte: start, $lt: end } });
1136
+ }
1137
+ todayLocal() {
1138
+ return (0, date_fns_1.format)((0, date_fns_tz_1.toZonedTime)(new Date(), this.options.timezone), 'yyyy-MM-dd');
1139
+ }
1140
+ castServerConditions(cond) {
1141
+ const out = {};
1142
+ for (const k of Object.keys(cond)) {
1143
+ const v = cond[k];
1144
+ if (k.startsWith('$')) {
1145
+ out[k] = Array.isArray(v)
1146
+ ? v.map((i) => (isPlainObject(i) ? this.castServerConditions(i) : i))
1147
+ : v;
1148
+ continue;
1149
+ }
1150
+ out[k] = this.schemaKind(k) === 'objectid' ? castObjectIds(v) : v;
1151
+ }
1152
+ return out;
1153
+ }
724
1154
  resolveRangePreset(preset) {
725
1155
  const tz = this.options.timezone;
726
1156
  const zonedNow = (0, date_fns_tz_1.toZonedTime)(new Date(), tz);
@@ -745,7 +1175,7 @@ class QueryAggregate {
745
1175
  return this.utcRangeForLocalDates(monthStartStr, todayStr);
746
1176
  }
747
1177
  default:
748
- throw new QueryAggregateValidationError(`Unknown range preset: "${preset}"`);
1178
+ throw new QueryAggregateValidationError(`Unknown range preset: "${String(preset)}"`);
749
1179
  }
750
1180
  }
751
1181
  /** [start of fromStr, start of (toStr + 1 day)) in this instance's timezone — an inclusive local-date range. */
@@ -755,79 +1185,91 @@ class QueryAggregate {
755
1185
  const end = (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(toStr, 1)}T00:00:00.000`, tz);
756
1186
  return { start, end };
757
1187
  }
758
- buildMatchStage() {
759
- let base;
760
- const hasUrlFilter = Object.keys(this._urlFilter).length > 0;
761
- if (this._searchOr.length > 0) {
762
- base = hasUrlFilter
763
- ? { $and: [this._urlFilter, { $or: this._searchOr }] }
764
- : { $or: this._searchOr };
765
- }
766
- else {
767
- base = hasUrlFilter ? this._urlFilter : {};
1188
+ /** Effective sort: the requested sort plus `_id` as a stable tiebreaker (prevents duplicate/missing rows across pages). */
1189
+ effectiveSort() {
1190
+ if ('_id' in this._sort)
1191
+ return { ...this._sort };
1192
+ const dir = Object.values(this._sort)[0] ?? -1;
1193
+ return { ...this._sort, _id: dir };
1194
+ }
1195
+ // A key is "joined" when it lives under a lookup alias and is not a real schema path.
1196
+ isJoinedKey(key) {
1197
+ if (this._joinAliases.size === 0)
1198
+ return false;
1199
+ if (this.schemaHasPath(key))
1200
+ return false;
1201
+ return this._joinAliases.has(key.split('.')[0]);
1202
+ }
1203
+ referencesJoined(key, value) {
1204
+ if (!key.startsWith('$'))
1205
+ return this.isJoinedKey(key);
1206
+ const items = Array.isArray(value) ? value : [value];
1207
+ return items.some((it) => isPlainObject(it) &&
1208
+ Object.keys(it).some((k) => this.referencesJoined(k, it[k])));
1209
+ }
1210
+ splitConditions(cond) {
1211
+ const pre = {};
1212
+ const post = {};
1213
+ for (const k of Object.keys(cond)) {
1214
+ (this.referencesJoined(k, cond[k]) ? post : pre)[k] = cond[k];
768
1215
  }
769
- const hasServer = Object.keys(this._serverConditions).length > 0;
770
- const finalFilter = Object.keys(base).length > 0 && hasServer
771
- ? { $and: [base, this._serverConditions] }
772
- : hasServer
773
- ? this._serverConditions
774
- : base;
775
- return Object.keys(finalFilter).length > 0 ? { $match: finalFilter } : null;
776
- }
777
- /** Match + lookups/custom stages only, no $project/$sort — shared by count()/distinct()/stats(), which don't need either. */
778
- buildMatchAndStagesPipeline() {
779
- const pipeline = [];
780
- const matchStage = this.buildMatchStage();
781
- if (matchStage)
782
- pipeline.push(matchStage);
783
- pipeline.push(...this._stages);
784
- return pipeline;
1216
+ return { pre, post };
785
1217
  }
786
- /** Encodes a keyset cursor from a result row: the current sort field's value plus `_id` as a stable tiebreaker. */
787
- encodeCursor(doc, sortField) {
788
- const raw = doc[sortField];
789
- let v = raw;
790
- let t = 'other';
791
- if (raw instanceof Date) {
792
- v = raw.toISOString();
793
- t = 'date';
1218
+ /** Builds the pre-join $match (index-friendly) and the post-join $match (conditions on joined fields). */
1219
+ buildMatchStages() {
1220
+ const preClauses = [];
1221
+ const postClauses = [];
1222
+ const add = (arr, c) => {
1223
+ if (Object.keys(c).length > 0)
1224
+ arr.push(c);
1225
+ };
1226
+ const url = this.splitConditions(this._urlFilter);
1227
+ add(preClauses, url.pre);
1228
+ add(postClauses, url.post);
1229
+ if (this._searchOr.length > 0) {
1230
+ const clause = { $or: this._searchOr };
1231
+ const joined = this._searchOr.some((o) => Object.keys(o).some((k) => this.isJoinedKey(k)));
1232
+ (joined ? postClauses : preClauses).push(clause);
794
1233
  }
795
- else if (raw instanceof mongoose_1.Types.ObjectId) {
796
- v = raw.toString();
797
- t = 'objectid';
1234
+ for (const cond of this._serverConditions) {
1235
+ const s = this.splitConditions(cond);
1236
+ add(preClauses, s.pre);
1237
+ add(postClauses, s.post);
798
1238
  }
799
- const id = doc._id;
800
- return Buffer.from(JSON.stringify({ v, t, id: String(id) })).toString('base64url');
1239
+ const mk = (c) => c.length === 0 ? null : { $match: c.length === 1 ? c[0] : { $and: c } };
1240
+ return { pre: mk(preClauses), post: mk(postClauses) };
801
1241
  }
802
- /** Decodes a cursor produced by encodeCursor(), restoring Date/ObjectId typing so comparisons stay type-correct. */
803
- decodeCursor(cursor) {
804
- let parsed;
805
- try {
806
- parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
807
- }
808
- catch {
809
- throw new QueryAggregateValidationError('paginateCursor: invalid cursor');
1242
+ /** Match + lookups/custom stages only, no $project/$sort — shared by count()/distinct()/stats()/paginateCursor(). */
1243
+ buildHeadPipeline() {
1244
+ const { pre, post } = this.buildMatchStages();
1245
+ const pipeline = [];
1246
+ if (pre)
1247
+ pipeline.push(pre);
1248
+ if (post) {
1249
+ const idx = Math.min(this._postJoinIndex, this._stages.length);
1250
+ pipeline.push(...this._stages.slice(0, idx), post, ...this._stages.slice(idx));
810
1251
  }
811
- let v = parsed.v;
812
- if (parsed.t === 'date' && typeof v === 'string')
813
- v = new Date(v);
814
- if (parsed.t === 'objectid' &&
815
- typeof v === 'string' &&
816
- (0, mongoose_1.isValidObjectId)(v)) {
817
- v = new mongoose_1.Types.ObjectId(v);
1252
+ else {
1253
+ pipeline.push(...this._stages);
818
1254
  }
819
- return { v, id: parsed.id };
1255
+ return pipeline;
820
1256
  }
821
- /** Base pipeline shared by every execution path: match -> lookups/custom stages -> project -> sort. */
822
- buildBasePipeline() {
823
- const pipeline = [];
824
- const matchStage = this.buildMatchStage();
825
- if (matchStage)
826
- pipeline.push(matchStage);
827
- pipeline.push(...this._stages);
1257
+ /**
1258
+ * Base pipeline shared by every execution path:
1259
+ * match -> lookups/custom stages -> sort -> [skip/limit] -> project.
1260
+ * $project runs last so it can never drop a field that sorting needs,
1261
+ * and only touches the documents that survive skip/limit.
1262
+ */
1263
+ buildBasePipeline(range) {
1264
+ const pipeline = this.buildHeadPipeline();
1265
+ pipeline.push({ $sort: this.effectiveSort() });
1266
+ if (range) {
1267
+ if (range.skip > 0)
1268
+ pipeline.push({ $skip: range.skip });
1269
+ pipeline.push({ $limit: range.limit });
1270
+ }
828
1271
  if (this._projection)
829
1272
  pipeline.push({ $project: this._projection });
830
- pipeline.push({ $sort: this._sort });
831
1273
  return pipeline;
832
1274
  }
833
1275
  execAggregate(pipeline) {
@@ -839,40 +1281,63 @@ class QueryAggregate {
839
1281
  return agg.exec();
840
1282
  }
841
1283
  async wrapTimed(fn, page, limit, pipeline) {
842
- const { onSlowQuery, slowQueryThresholdMS, maxTimeMS } = this.options;
1284
+ const { onSlowQuery, slowQueryThresholdMS } = this.options;
843
1285
  if (!onSlowQuery)
844
1286
  return fn();
845
1287
  const start = Date.now();
846
- const result = await fn();
847
- const elapsedMs = Date.now() - start;
848
- if (elapsedMs >= (slowQueryThresholdMS ?? maxTimeMS)) {
849
- onSlowQuery({ elapsedMs, pipeline, sort: this._sort, page, limit });
1288
+ try {
1289
+ return await fn();
1290
+ }
1291
+ finally {
1292
+ const elapsedMs = Date.now() - start;
1293
+ if (elapsedMs >= slowQueryThresholdMS) {
1294
+ try {
1295
+ onSlowQuery({
1296
+ elapsedMs,
1297
+ pipeline,
1298
+ sort: this.effectiveSort(),
1299
+ page,
1300
+ limit,
1301
+ });
1302
+ }
1303
+ catch {
1304
+ // A faulty logging callback must never break the query.
1305
+ }
1306
+ }
850
1307
  }
851
- return result;
1308
+ }
1309
+ fetchPage(page, limit) {
1310
+ const pipeline = this.buildBasePipeline({
1311
+ skip: (page - 1) * limit,
1312
+ limit,
1313
+ });
1314
+ return this.wrapTimed(() => this.execAggregate(pipeline), page, limit, pipeline);
1315
+ }
1316
+ async runCount(page, limit) {
1317
+ const pipeline = [
1318
+ ...this.buildHeadPipeline(),
1319
+ { $count: 'count' },
1320
+ ];
1321
+ const [row] = await this.wrapTimed(() => this.execAggregate(pipeline), page, limit, pipeline);
1322
+ return row?.count ?? 0;
852
1323
  }
853
1324
  // ── Terminal ───────────────────────────────────────────────────────────────
854
1325
  /**
855
- * Executes the pipeline and returns a paginated result via $facet (single
856
- * round trip: data page + total count together). Pass a prior page-1
857
- * `total` as `cachedTotal` on later pages to skip the count entirely.
858
- *
859
- * Note: $facet buffers both branches in memory per query — for very large
860
- * collections with expensive pre-facet stages, consider passing
861
- * `cachedTotal` on subsequent pages, or run count/data as two calls.
1326
+ * Executes the pipeline and returns a paginated result. The data page
1327
+ * (sort + skip + limit, so MongoDB can use top-k / index sorting) and the
1328
+ * total count run in parallel. Pass a prior page-1 `total` as `cachedTotal`
1329
+ * on later pages to skip the count entirely.
862
1330
  */
863
1331
  async paginate(cachedTotal) {
864
1332
  const page = this._page;
865
1333
  const limit = this._limit;
866
- const basePipeline = this.buildBasePipeline();
867
1334
  if (cachedTotal !== undefined) {
1335
+ if (!Number.isInteger(cachedTotal) || cachedTotal < 0) {
1336
+ throw new QueryAggregateValidationError(`paginate: "cachedTotal" must be a non-negative integer, got ${cachedTotal}`);
1337
+ }
868
1338
  const totalPages = Math.max(Math.ceil(cachedTotal / limit), 1);
869
1339
  const safePage = page > totalPages ? 1 : page;
870
- const dataPipeline = [
871
- ...basePipeline,
872
- { $skip: (safePage - 1) * limit },
873
- { $limit: limit },
874
- ];
875
- const data = await this.wrapTimed(() => this.execAggregate(dataPipeline), safePage, limit, dataPipeline);
1340
+ const data = await this.fetchPage(safePage, limit);
876
1341
  return {
877
1342
  data,
878
1343
  total: cachedTotal,
@@ -883,27 +1348,15 @@ class QueryAggregate {
883
1348
  hasPrevPage: safePage > 1,
884
1349
  };
885
1350
  }
886
- const facetPipeline = [
887
- ...basePipeline,
888
- {
889
- $facet: {
890
- data: [{ $skip: (page - 1) * limit }, { $limit: limit }],
891
- totalCount: [{ $count: 'count' }],
892
- },
893
- },
894
- ];
895
- const [facetResult] = await this.wrapTimed(() => this.execAggregate(facetPipeline), page, limit, facetPipeline);
896
- const total = facetResult?.totalCount?.[0]?.count ?? 0;
1351
+ const [pageData, total] = await Promise.all([
1352
+ this.fetchPage(page, limit),
1353
+ this.runCount(page, limit),
1354
+ ]);
897
1355
  const totalPages = Math.max(Math.ceil(total / limit), 1);
898
- if (page > totalPages && page !== 1) {
899
- // Requested page doesn't exist for this filter — refetch page 1 rather
900
- // than returning an empty page silently.
901
- const fallbackPipeline = [
902
- ...basePipeline,
903
- { $skip: 0 },
904
- { $limit: limit },
905
- ];
906
- const data = await this.execAggregate(fallbackPipeline);
1356
+ if (page > totalPages) {
1357
+ // Requested page doesn't exist for this filter — return page 1 rather
1358
+ // than an empty page silently.
1359
+ const data = await this.fetchPage(1, limit);
907
1360
  return {
908
1361
  data,
909
1362
  total,
@@ -915,7 +1368,7 @@ class QueryAggregate {
915
1368
  };
916
1369
  }
917
1370
  return {
918
- data: facetResult?.data ?? [],
1371
+ data: pageData,
919
1372
  total,
920
1373
  page,
921
1374
  totalPages,
@@ -924,12 +1377,11 @@ class QueryAggregate {
924
1377
  hasPrevPage: page > 1,
925
1378
  };
926
1379
  }
927
- // ── Advanced terminal & utility methods (additive — paginate() above is
928
- // untouched) ─────────────────────────────────────────────────────────────
1380
+ // ── Advanced terminal & utility methods ───────────────────────────────────
929
1381
  /** Returns just the matching document count — cheaper than paginate() when you don't need the data page. Ignores $project/$sort. */
930
1382
  async count() {
931
1383
  const pipeline = [
932
- ...this.buildMatchAndStagesPipeline(),
1384
+ ...this.buildHeadPipeline(),
933
1385
  { $count: 'count' },
934
1386
  ];
935
1387
  const [row] = await this.execAggregate(pipeline);
@@ -937,8 +1389,9 @@ class QueryAggregate {
937
1389
  }
938
1390
  /** Returns the distinct values of `field` for the current filter/where/range conditions. */
939
1391
  async distinct(field) {
1392
+ assertFieldPath(field, 'distinct');
940
1393
  const pipeline = [
941
- ...this.buildMatchAndStagesPipeline(),
1394
+ ...this.buildHeadPipeline(),
942
1395
  { $group: { _id: `$${field}` } },
943
1396
  ];
944
1397
  const rows = await this.execAggregate(pipeline);
@@ -953,6 +1406,14 @@ class QueryAggregate {
953
1406
  async stats(specs) {
954
1407
  const group = { _id: null };
955
1408
  for (const spec of specs) {
1409
+ if (!METRIC_NAME_RE.test(spec.name) ||
1410
+ spec.name === '_id' ||
1411
+ DANGEROUS_KEYS.has(spec.name)) {
1412
+ throw new QueryAggregateValidationError(`stats: invalid metric name "${spec.name}"`);
1413
+ }
1414
+ if (!STAT_OPS.has(spec.op)) {
1415
+ throw new QueryAggregateValidationError(`stats: unsupported op "${String(spec.op)}" for metric "${spec.name}"`);
1416
+ }
956
1417
  if (spec.op === 'count') {
957
1418
  group[spec.name] = { $sum: 1 };
958
1419
  }
@@ -960,11 +1421,12 @@ class QueryAggregate {
960
1421
  if (!spec.field) {
961
1422
  throw new QueryAggregateValidationError(`stats: metric "${spec.name}" needs a "field" for op "${spec.op}"`);
962
1423
  }
1424
+ assertFieldPath(spec.field, `stats(${spec.name})`);
963
1425
  group[spec.name] = { [`$${spec.op}`]: `$${spec.field}` };
964
1426
  }
965
1427
  }
966
1428
  const pipeline = [
967
- ...this.buildMatchAndStagesPipeline(),
1429
+ ...this.buildHeadPipeline(),
968
1430
  { $group: group },
969
1431
  ];
970
1432
  const [row] = await this.execAggregate(pipeline);
@@ -991,44 +1453,54 @@ class QueryAggregate {
991
1453
  /**
992
1454
  * Keyset ("seek") pagination — scales far better than .paginate()'s
993
1455
  * $skip on deep pages of large collections, at the cost of not supporting
994
- * "jump to page N". Requires .sort() to have been called with exactly the
995
- * field you want to seek on (falls back to DEFAULT_SORT's `createdAt`
996
- * otherwise). Pass the previous page's `nextCursor` back in as `cursor`
997
- * to continue; a `hasNextPage: false` / `nextCursor: null` page is the end.
1456
+ * "jump to page N". Seeks on the FIRST field of .sort() (falls back to
1457
+ * DEFAULT_SORT's `createdAt`) with `_id` as a stable tiebreaker. Pass the
1458
+ * previous page's `nextCursor` back in as `cursor` to continue; a
1459
+ * `hasNextPage: false` / `nextCursor: null` page is the end. A cursor is
1460
+ * bound to the sort field/direction it was created with.
998
1461
  */
999
1462
  async paginateCursor(opts = {}) {
1000
- const limit = opts.limit && opts.limit > 0
1001
- ? Math.min(opts.limit, this.options.maxLimit)
1463
+ const limit = typeof opts.limit === 'number' &&
1464
+ Number.isFinite(opts.limit) &&
1465
+ opts.limit >= 1
1466
+ ? Math.min(Math.floor(opts.limit), this.options.maxLimit)
1002
1467
  : this._limit;
1003
- const [sortField, sortDir] = Object.entries(this._sort)[0] ?? [
1004
- 'createdAt',
1005
- -1,
1006
- ];
1007
- const pipeline = this.buildMatchAndStagesPipeline();
1468
+ const first = Object.entries(this._sort)[0] ?? ['createdAt', -1];
1469
+ const sortField = first[0];
1470
+ const sortDir = first[1] === 1 ? 1 : -1;
1471
+ const pipeline = this.buildHeadPipeline();
1008
1472
  if (opts.cursor) {
1009
- const { v, id } = this.decodeCursor(opts.cursor);
1010
- const cmp = sortDir === -1 ? '$lt' : '$gt';
1011
- const idValue = (0, mongoose_1.isValidObjectId)(id) ? new mongoose_1.Types.ObjectId(id) : id;
1473
+ const { v, id } = this.decodeCursor(opts.cursor, sortField, sortDir);
1012
1474
  pipeline.push({
1013
- $match: {
1014
- $or: [
1015
- { [sortField]: { [cmp]: v } },
1016
- { [sortField]: v, _id: { [cmp]: idValue } },
1017
- ],
1018
- },
1475
+ $match: this.buildCursorMatch(sortField, sortDir, v, id),
1019
1476
  });
1020
1477
  }
1021
- if (this._projection)
1022
- pipeline.push({ $project: this._projection });
1023
- pipeline.push({ $sort: { [sortField]: sortDir, _id: sortDir } });
1478
+ pipeline.push({
1479
+ $sort: sortField === '_id'
1480
+ ? { _id: sortDir }
1481
+ : { [sortField]: sortDir, _id: sortDir },
1482
+ });
1024
1483
  pipeline.push({ $limit: limit + 1 });
1025
- const rows = await this.execAggregate(pipeline);
1484
+ // Projection goes last; the sort field and `_id` are force-included for
1485
+ // cursor creation and stripped again from the returned rows.
1486
+ const { projection, injectId, injectSort } = this.buildCursorProjection(sortField);
1487
+ if (projection)
1488
+ pipeline.push({ $project: projection });
1489
+ const rows = await this.wrapTimed(() => this.execAggregate(pipeline), 1, limit, pipeline);
1026
1490
  const hasNextPage = rows.length > limit;
1027
- const data = (hasNextPage ? rows.slice(0, limit) : rows);
1028
- const nextCursor = hasNextPage
1029
- ? this.encodeCursor(data[data.length - 1], sortField)
1491
+ const pageRows = hasNextPage ? rows.slice(0, limit) : rows;
1492
+ const nextCursor = hasNextPage && pageRows.length > 0
1493
+ ? this.encodeCursor(pageRows[pageRows.length - 1], sortField, sortDir)
1030
1494
  : null;
1031
- return { data, limit, nextCursor, hasNextPage };
1495
+ if (injectId || injectSort) {
1496
+ for (const row of pageRows) {
1497
+ if (injectId)
1498
+ delete row._id;
1499
+ if (injectSort)
1500
+ deletePath(row, sortField);
1501
+ }
1502
+ }
1503
+ return { data: pageRows, limit, nextCursor, hasNextPage };
1032
1504
  }
1033
1505
  /**
1034
1506
  * Runs the built pipeline through Mongoose's .explain() for debugging
@@ -1041,13 +1513,14 @@ class QueryAggregate {
1041
1513
  }
1042
1514
  /** Convenience wrapper over addStage() for a computed $addFields entry, e.g. .computeField('margin', { $subtract: ['$price', '$cost'] }). */
1043
1515
  computeField(name, expression) {
1516
+ assertFieldPath(name, 'computeField');
1044
1517
  return this.addStage({
1045
1518
  $addFields: { [name]: expression },
1046
1519
  });
1047
1520
  }
1048
1521
  /** Convenience server-side condition excluding soft-deleted docs (matches both `null` and a missing field, per MongoDB equality semantics). Not client-overridable. */
1049
1522
  excludeSoftDeleted(field = 'deletedAt') {
1050
- this._serverConditions[field] = null;
1523
+ this._serverConditions.push({ [field]: null });
1051
1524
  return this;
1052
1525
  }
1053
1526
  /** Applies .where(conditions) only when `condition` is truthy — avoids scattering if-statements around chained builder calls. */
@@ -1068,7 +1541,7 @@ class QueryAggregate {
1068
1541
  ? new Set(this._objectIdFieldsLookup)
1069
1542
  : null;
1070
1543
  copy._urlFilter = { ...this._urlFilter };
1071
- copy._serverConditions = { ...this._serverConditions };
1544
+ copy._serverConditions = [...this._serverConditions];
1072
1545
  copy._searchOr = [...this._searchOr];
1073
1546
  copy._sort = { ...this._sort };
1074
1547
  copy._projection = this._projection ? { ...this._projection } : null;
@@ -1076,12 +1549,110 @@ class QueryAggregate {
1076
1549
  ? { ...this._defaultProjection }
1077
1550
  : null;
1078
1551
  copy._stages = [...this._stages];
1552
+ copy._joinAliases = new Set(this._joinAliases);
1553
+ copy._postJoinIndex = this._postJoinIndex;
1079
1554
  return copy;
1080
1555
  }
1081
1556
  /** Returns the fully-built pipeline without executing it — for logging, snapshot tests, or sanity-checking what will actually run. */
1082
1557
  debugPipeline() {
1083
1558
  return this.buildBasePipeline();
1084
1559
  }
1560
+ // ── Cursor internals ──────────────────────────────────────────────────────
1561
+ buildCursorProjection(sortField) {
1562
+ const proj = this._projection;
1563
+ if (!proj)
1564
+ return { projection: null, injectId: false, injectSort: false };
1565
+ const p = { ...proj };
1566
+ let injectId = false;
1567
+ let injectSort = false;
1568
+ const needSort = sortField !== '_id';
1569
+ const isInclusion = Object.keys(p).some((k) => k !== '_id' && p[k] === 1);
1570
+ const conflict = () => new QueryAggregateValidationError(`paginateCursor: projection conflicts with sort field "${sortField}" (a parent/child path of it is projected)`);
1571
+ if (p._id === 0) {
1572
+ delete p._id;
1573
+ injectId = true;
1574
+ }
1575
+ if (needSort) {
1576
+ if (isInclusion) {
1577
+ const covered = Object.keys(p).some((k) => p[k] === 1 && (k === sortField || sortField.startsWith(`${k}.`)));
1578
+ if (!covered) {
1579
+ if (Object.keys(p).some((k) => k.startsWith(`${sortField}.`)))
1580
+ throw conflict();
1581
+ p[sortField] = 1;
1582
+ injectSort = true;
1583
+ }
1584
+ }
1585
+ else {
1586
+ if (p[sortField] === 0) {
1587
+ delete p[sortField];
1588
+ injectSort = true;
1589
+ }
1590
+ else if (Object.keys(p).some((k) => sortField.startsWith(`${k}.`))) {
1591
+ throw conflict();
1592
+ }
1593
+ }
1594
+ }
1595
+ return {
1596
+ projection: Object.keys(p).length > 0 ? p : null,
1597
+ injectId,
1598
+ injectSort,
1599
+ };
1600
+ }
1601
+ /** Encodes a keyset cursor from a result row: the sort field's value plus `_id` as a stable tiebreaker. */
1602
+ encodeCursor(doc, sortField, sortDir) {
1603
+ const payload = {
1604
+ f: sortField,
1605
+ d: sortDir,
1606
+ v: encodeTyped(getByPath(doc, sortField)),
1607
+ id: encodeTyped(doc._id),
1608
+ };
1609
+ return Buffer.from(JSON.stringify(payload)).toString('base64url');
1610
+ }
1611
+ /** Decodes and strictly validates a cursor, restoring Date/ObjectId typing so comparisons stay type-correct. */
1612
+ decodeCursor(cursor, sortField, sortDir) {
1613
+ const bad = () => new QueryAggregateValidationError('paginateCursor: invalid cursor');
1614
+ if (typeof cursor !== 'string' || cursor.length > MAX_CURSOR_LENGTH)
1615
+ throw bad();
1616
+ let parsed;
1617
+ try {
1618
+ parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
1619
+ }
1620
+ catch {
1621
+ throw bad();
1622
+ }
1623
+ if (!isPlainObject(parsed))
1624
+ throw bad();
1625
+ const c = parsed;
1626
+ if (c.f !== sortField || c.d !== sortDir) {
1627
+ throw new QueryAggregateValidationError('paginateCursor: cursor does not match the current sort');
1628
+ }
1629
+ return { v: decodeTyped(c.v), id: decodeTyped(c.id) };
1630
+ }
1631
+ /** $match selecting every row strictly after the cursor row in (sortField, _id) order — null/missing-safe. */
1632
+ buildCursorMatch(sortField, sortDir, v, id) {
1633
+ const cmp = sortDir === -1 ? '$lt' : '$gt';
1634
+ const tie = { _id: { [cmp]: id } };
1635
+ if (sortField === '_id')
1636
+ return { _id: { [cmp]: id } };
1637
+ // MongoDB sorts null/missing first ascending, last descending.
1638
+ if (v === null) {
1639
+ return sortDir === 1
1640
+ ? {
1641
+ $or: [
1642
+ { [sortField]: { $ne: null } },
1643
+ { [sortField]: null, ...tie },
1644
+ ],
1645
+ }
1646
+ : { [sortField]: null, ...tie };
1647
+ }
1648
+ const or = [
1649
+ { [sortField]: { [cmp]: v } },
1650
+ { [sortField]: v, ...tie },
1651
+ ];
1652
+ if (sortDir === -1)
1653
+ or.push({ [sortField]: null });
1654
+ return { $or: or };
1655
+ }
1085
1656
  }
1086
1657
  exports.QueryAggregate = QueryAggregate;
1087
1658
  exports.default = QueryAggregate;