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.d.ts +76 -32
- package/dist/aggregate.d.ts.map +1 -1
- package/dist/aggregate.js +889 -318
- package/dist/aggregate.js.map +1 -1
- package/dist/find.d.ts +71 -49
- package/dist/find.d.ts.map +1 -1
- package/dist/find.js +370 -173
- package/dist/find.js.map +1 -1
- package/package.json +1 -1
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
|
|
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()
|
|
80
|
-
//
|
|
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") —
|
|
88
|
-
// .objectIdFields()
|
|
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
|
|
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', '
|
|
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
|
-
|
|
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
|
|
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 ??
|
|
142
|
-
if (
|
|
143
|
-
return
|
|
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()
|
|
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(
|
|
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
|
-
/**
|
|
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
|
|
165
|
-
|
|
166
|
-
return
|
|
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
|
|
223
|
+
/** Parses a single date/datetime string to a scalar UTC Date. */
|
|
175
224
|
function coerceDateScalar(value, timezone) {
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
|
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
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
195
|
-
|
|
248
|
+
// ─── Sanitization ─────────────────────────────────────────────────────────────
|
|
249
|
+
function isPlainObject(v) {
|
|
250
|
+
if (v === null || typeof v !== 'object' || Array.isArray(v))
|
|
196
251
|
return false;
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
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 (
|
|
283
|
+
if (isPlainObject(value)) {
|
|
234
284
|
const src = value;
|
|
235
285
|
const out = {};
|
|
236
|
-
for (const k
|
|
237
|
-
if (
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
304
|
-
function
|
|
305
|
-
if (value
|
|
306
|
-
return
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
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
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
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 (
|
|
349
|
-
const coerced = coerceAll(
|
|
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
|
|
358
|
-
if (
|
|
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
|
-
|
|
465
|
+
}
|
|
361
466
|
const isOp = k.startsWith('$') || COERCIBLE_OPS.has(k);
|
|
362
|
-
|
|
363
|
-
|
|
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
|
-
/**
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
|
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,
|
|
548
|
+
function buildFilter(raw, allowedLookup, canonicalMap, ctx, onDrop) {
|
|
408
549
|
const stripped = {};
|
|
409
|
-
for (const k
|
|
410
|
-
if (
|
|
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,
|
|
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
|
|
614
|
+
const inc = {};
|
|
615
|
+
const exc = {};
|
|
469
616
|
for (const token of projection.split(/\s+/).filter(Boolean)) {
|
|
470
|
-
|
|
471
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
832
|
+
maxTimeMS,
|
|
503
833
|
slowQueryThresholdMS: options.slowQueryThresholdMS ??
|
|
504
|
-
|
|
505
|
-
|
|
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
|
|
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.
|
|
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
|
-
/**
|
|
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
|
-
|
|
548
|
-
|
|
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.
|
|
934
|
+
this.pushRange(field, start, end);
|
|
555
935
|
return this;
|
|
556
936
|
}
|
|
557
|
-
// ── Custom range methods
|
|
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 (!
|
|
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.
|
|
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 (!
|
|
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.
|
|
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
|
|
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.
|
|
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
|
-
|
|
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 (!
|
|
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 =
|
|
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.
|
|
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.
|
|
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
|
-
|
|
665
|
-
|
|
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
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
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
|
-
|
|
683
|
-
|
|
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
|
-
|
|
690
|
-
|
|
691
|
-
|
|
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
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
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
|
-
|
|
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
|
-
/**
|
|
787
|
-
|
|
788
|
-
const
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
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
|
-
|
|
796
|
-
|
|
797
|
-
|
|
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
|
|
800
|
-
return
|
|
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
|
-
/**
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
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
|
-
|
|
812
|
-
|
|
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
|
|
1255
|
+
return pipeline;
|
|
820
1256
|
}
|
|
821
|
-
/**
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
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
|
|
1284
|
+
const { onSlowQuery, slowQueryThresholdMS } = this.options;
|
|
843
1285
|
if (!onSlowQuery)
|
|
844
1286
|
return fn();
|
|
845
1287
|
const start = Date.now();
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
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
|
-
|
|
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
|
|
856
|
-
*
|
|
857
|
-
*
|
|
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
|
|
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
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
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
|
|
899
|
-
// Requested page doesn't exist for this filter —
|
|
900
|
-
// than
|
|
901
|
-
const
|
|
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:
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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".
|
|
995
|
-
*
|
|
996
|
-
*
|
|
997
|
-
*
|
|
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
|
|
1001
|
-
|
|
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
|
|
1004
|
-
|
|
1005
|
-
|
|
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
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1478
|
+
pipeline.push({
|
|
1479
|
+
$sort: sortField === '_id'
|
|
1480
|
+
? { _id: sortDir }
|
|
1481
|
+
: { [sortField]: sortDir, _id: sortDir },
|
|
1482
|
+
});
|
|
1024
1483
|
pipeline.push({ $limit: limit + 1 });
|
|
1025
|
-
|
|
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
|
|
1028
|
-
const nextCursor = hasNextPage
|
|
1029
|
-
? this.encodeCursor(
|
|
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
|
-
|
|
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]
|
|
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 =
|
|
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;
|