mongoose-query-find 3.0.6 → 3.0.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +468 -0
- package/dist/aggregate.d.ts +177 -0
- package/dist/aggregate.d.ts.map +1 -0
- package/dist/aggregate.js +733 -0
- package/dist/aggregate.js.map +1 -0
- package/dist/find.d.ts +243 -0
- package/dist/find.d.ts.map +1 -0
- package/dist/find.js +740 -0
- package/dist/find.js.map +1 -0
- package/dist/index.d.ts +7 -242
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +13 -737
- package/dist/index.js.map +1 -1
- package/package.json +78 -65
|
@@ -0,0 +1,733 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* QueryAggregate - Fluent, allowlisted aggregation-pipeline builder for Mongoose (v8/v9)
|
|
4
|
+
*
|
|
5
|
+
* `QueryFind` (mongoose-query-find) is built on `Model.find()` and can't express
|
|
6
|
+
* `$lookup` joins, `$group`, or other pipeline-only stages. QueryAggregate mirrors
|
|
7
|
+
* the same safety model (allowlisted filter fields, sanitized operators, capped
|
|
8
|
+
* pagination) but is built on `Model.aggregate()`.
|
|
9
|
+
*
|
|
10
|
+
* ── Timezone handling ───────────────────────────────────────────────────────
|
|
11
|
+
* MongoDB always stores/compares dates in UTC. Clients think and filter in local
|
|
12
|
+
* time (e.g. ?createdAt=2026-09-01 means "Sept 1st in the caller's timezone",
|
|
13
|
+
* not UTC midnight). This builder resolves that with `date-fns-tz`:
|
|
14
|
+
*
|
|
15
|
+
* - fromZonedTime(localString, tz) -> the exact UTC instant for a wall-clock
|
|
16
|
+
* time in `tz`. Used to turn a client-supplied local date into the correct
|
|
17
|
+
* $gte/$lt UTC range for the pipeline's $match stage.
|
|
18
|
+
* - toZonedTime(utcDate, tz) -> the wall-clock Date for `tz`. Used to
|
|
19
|
+
* work out "what day is it right now, in the caller's timezone" for
|
|
20
|
+
* relative presets like .range('today').
|
|
21
|
+
*
|
|
22
|
+
* The timezone itself is a per-request value, passed in via constructor
|
|
23
|
+
* options rather than hardcoded, typically sourced from a header:
|
|
24
|
+
*
|
|
25
|
+
* const timezone = (req.headers['x-timezone'] as string) ?? 'Asia/Dhaka';
|
|
26
|
+
*
|
|
27
|
+
* const result = await new QueryAggregate(CategoryModel, req.query, { timezone })
|
|
28
|
+
* .allowFields(['name', 'status', 'createdAt'])
|
|
29
|
+
* .dateFields(['createdAt', 'updatedAt'])
|
|
30
|
+
* .where({ branchId: req.self.linkedTo, status: { $ne: CategoryStatus.ARCHIVED } })
|
|
31
|
+
* .filter()
|
|
32
|
+
* .globalSearch(['name'])
|
|
33
|
+
* .sort()
|
|
34
|
+
* .project('name status createdAt updatedAt')
|
|
35
|
+
* .paginate();
|
|
36
|
+
*
|
|
37
|
+
* An invalid/unknown IANA timezone string (bad header, typo, etc.) never
|
|
38
|
+
* throws mid-query — it's validated once at construction time and falls back
|
|
39
|
+
* to the default.
|
|
40
|
+
*
|
|
41
|
+
* ── Joins ────────────────────────────────────────────────────────────────────
|
|
42
|
+
* Use .lookup() for $lookup (+ optional $unwind), or .addStage() to inject any
|
|
43
|
+
* other developer-authored stage. .addStage() is for trusted, server-defined
|
|
44
|
+
* stages — it only blocks destructive stage types ($out/$merge). It does NOT
|
|
45
|
+
* run the client-input sanitizer; that only applies to .filter()/.where(),
|
|
46
|
+
* which parse untrusted req.query / req.body values.
|
|
47
|
+
*/
|
|
48
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
49
|
+
exports.QueryAggregate = exports.QueryAggregateValidationError = exports.QueryAggregateError = void 0;
|
|
50
|
+
const date_fns_1 = require("date-fns");
|
|
51
|
+
const date_fns_tz_1 = require("date-fns-tz");
|
|
52
|
+
// ─── Constants ────────────────────────────────────────────────────────────────
|
|
53
|
+
const RESERVED_KEYS = new Set(['page', 'sort', 'limit', 'fields', 'q']);
|
|
54
|
+
const DEFAULT_MAX_LIMIT = 100;
|
|
55
|
+
const MAX_NESTING_DEPTH = 5;
|
|
56
|
+
const MAX_SEARCH_LENGTH = 200;
|
|
57
|
+
const MAX_SORT_FIELDS = 5;
|
|
58
|
+
const DEFAULT_MAX_TIME_MS = 5000;
|
|
59
|
+
const DEFAULT_TIMEZONE = 'Asia/Dhaka';
|
|
60
|
+
// Matches only when the date-word is the LAST path segment (e.g. "createdAt",
|
|
61
|
+
// "user.updatedAt") — used as a fallback heuristic when .dateFields() isn't
|
|
62
|
+
// called explicitly.
|
|
63
|
+
const DATE_FIELD_RE = /(^|\.)(createdAt|updatedAt|deletedAt|archivedAt|expiresAt|date|birthDate)$/i;
|
|
64
|
+
const PLAIN_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
65
|
+
// A string that already carries its own UTC offset ("Z" or "+06:00") is
|
|
66
|
+
// treated as an absolute instant rather than a local wall-clock time.
|
|
67
|
+
const HAS_OFFSET_RE = /([Zz]|[+-]\d{2}:?\d{2})$/;
|
|
68
|
+
const COERCIBLE_OPS = new Set([
|
|
69
|
+
'eq',
|
|
70
|
+
'ne',
|
|
71
|
+
'gt',
|
|
72
|
+
'gte',
|
|
73
|
+
'lt',
|
|
74
|
+
'lte',
|
|
75
|
+
'in',
|
|
76
|
+
'nin',
|
|
77
|
+
]);
|
|
78
|
+
const IN_LIKE_OPS = new Set(['in', '$in', 'nin', '$nin']);
|
|
79
|
+
const DEFAULT_SORT = { createdAt: -1 };
|
|
80
|
+
const ALLOWED_TOP_LEVEL_OPS = new Set(['$and', '$or', '$nor', '$not']);
|
|
81
|
+
// Rejected anywhere inside client-supplied filter/search/populate-match input.
|
|
82
|
+
const BANNED_OPERATORS = new Set([
|
|
83
|
+
'$where',
|
|
84
|
+
'$expr',
|
|
85
|
+
'$function',
|
|
86
|
+
'$accumulator',
|
|
87
|
+
'$map',
|
|
88
|
+
'$reduce',
|
|
89
|
+
'$filter',
|
|
90
|
+
]);
|
|
91
|
+
// Rejected in developer-authored pipeline stages added via addStage()/lookup()
|
|
92
|
+
// pipelines — these can mutate or drop data and have no place in a query builder.
|
|
93
|
+
const BANNED_STAGE_OPERATORS = new Set(['$out', '$merge']);
|
|
94
|
+
// ─── Errors ───────────────────────────────────────────────────────────────────
|
|
95
|
+
class QueryAggregateError extends Error {
|
|
96
|
+
constructor(message) {
|
|
97
|
+
super(message);
|
|
98
|
+
this.name = 'QueryAggregateError';
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
exports.QueryAggregateError = QueryAggregateError;
|
|
102
|
+
class QueryAggregateValidationError extends QueryAggregateError {
|
|
103
|
+
constructor(message) {
|
|
104
|
+
super(message);
|
|
105
|
+
this.name = 'QueryAggregateValidationError';
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
exports.QueryAggregateValidationError = QueryAggregateValidationError;
|
|
109
|
+
// ─── Input parsing ────────────────────────────────────────────────────────────
|
|
110
|
+
function parsePage(raw) {
|
|
111
|
+
const n = parseInt(raw ?? '1', 10);
|
|
112
|
+
return isNaN(n) || n < 1 ? 1 : n;
|
|
113
|
+
}
|
|
114
|
+
function parseLimit(raw, maxLimit = DEFAULT_MAX_LIMIT) {
|
|
115
|
+
const n = parseInt(raw ?? '10', 10);
|
|
116
|
+
if (isNaN(n) || n < 1)
|
|
117
|
+
return 10;
|
|
118
|
+
return Math.min(n, maxLimit);
|
|
119
|
+
}
|
|
120
|
+
function resolveTimezone(tz) {
|
|
121
|
+
const candidate = tz && tz.trim() ? tz.trim() : DEFAULT_TIMEZONE;
|
|
122
|
+
try {
|
|
123
|
+
// Throws RangeError on an invalid IANA zone — cheapest available validator.
|
|
124
|
+
Intl.DateTimeFormat(undefined, { timeZone: candidate });
|
|
125
|
+
return candidate;
|
|
126
|
+
}
|
|
127
|
+
catch {
|
|
128
|
+
if (process.env.NODE_ENV !== 'production') {
|
|
129
|
+
console.warn(`[query-aggregate] Invalid timezone "${candidate}", falling back to "${DEFAULT_TIMEZONE}"`);
|
|
130
|
+
}
|
|
131
|
+
return DEFAULT_TIMEZONE;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
// ─── Timezone-aware date helpers ───────────────────────────────────────────────
|
|
135
|
+
/** Shifts a "YYYY-MM-DD" string by N calendar days (pure date math, DST-safe via a noon-UTC anchor). */
|
|
136
|
+
function shiftLocalDateString(dateStr, days) {
|
|
137
|
+
const [y, m, d] = dateStr.split('-').map(Number);
|
|
138
|
+
const anchor = new Date(Date.UTC(y, m - 1, d, 12, 0, 0));
|
|
139
|
+
const shifted = (0, date_fns_1.addDays)(anchor, days);
|
|
140
|
+
return shifted.toISOString().slice(0, 10);
|
|
141
|
+
}
|
|
142
|
+
/** [start, end) UTC instants for a single local calendar date in `timezone`. */
|
|
143
|
+
function plainDateToUtcRange(dateStr, timezone) {
|
|
144
|
+
const start = (0, date_fns_tz_1.fromZonedTime)(`${dateStr}T00:00:00.000`, timezone);
|
|
145
|
+
const end = (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(dateStr, 1)}T00:00:00.000`, timezone);
|
|
146
|
+
return { start, end };
|
|
147
|
+
}
|
|
148
|
+
/** Parses a single date/datetime string to a scalar UTC Date (used for $in/$nin, where a range object isn't valid). */
|
|
149
|
+
function coerceDateScalar(value, timezone) {
|
|
150
|
+
const raw = PLAIN_DATE_RE.test(value) ? `${value}T00:00:00.000` : value;
|
|
151
|
+
const parsed = HAS_OFFSET_RE.test(value)
|
|
152
|
+
? new Date(value)
|
|
153
|
+
: (0, date_fns_tz_1.fromZonedTime)(raw, timezone);
|
|
154
|
+
return isNaN(parsed.getTime()) ? undefined : parsed;
|
|
155
|
+
}
|
|
156
|
+
function isDateField(path, explicit) {
|
|
157
|
+
if (!path)
|
|
158
|
+
return false;
|
|
159
|
+
const lc = path.toLowerCase();
|
|
160
|
+
if (explicit && explicit.size > 0) {
|
|
161
|
+
if (explicit.has(lc))
|
|
162
|
+
return true;
|
|
163
|
+
const lastSeg = lc.split('.').pop() ?? lc;
|
|
164
|
+
return explicit.has(lastSeg);
|
|
165
|
+
}
|
|
166
|
+
return DATE_FIELD_RE.test(path);
|
|
167
|
+
}
|
|
168
|
+
// ─── Sanitization ─────────────────────────────────────────────────────────────
|
|
169
|
+
/** Recursively strips non-plain values (class instances, functions) from client input. */
|
|
170
|
+
function sanitize(value, depth = 0, path = '', onDrop) {
|
|
171
|
+
if (depth >= MAX_NESTING_DEPTH) {
|
|
172
|
+
if (onDrop)
|
|
173
|
+
onDrop(path, value);
|
|
174
|
+
else if (process.env.NODE_ENV !== 'production') {
|
|
175
|
+
console.warn(`[query-aggregate] Max nesting depth exceeded at "${path}":`, value);
|
|
176
|
+
}
|
|
177
|
+
return undefined;
|
|
178
|
+
}
|
|
179
|
+
if (value === null)
|
|
180
|
+
return null;
|
|
181
|
+
const t = typeof value;
|
|
182
|
+
if (t === 'string' || t === 'number' || t === 'boolean')
|
|
183
|
+
return value;
|
|
184
|
+
if (value instanceof Date)
|
|
185
|
+
return value;
|
|
186
|
+
if (Array.isArray(value)) {
|
|
187
|
+
const out = [];
|
|
188
|
+
for (let i = 0; i < value.length; i++) {
|
|
189
|
+
const s = sanitize(value[i], depth + 1, `${path}[${i}]`, onDrop);
|
|
190
|
+
if (s !== undefined)
|
|
191
|
+
out.push(s);
|
|
192
|
+
}
|
|
193
|
+
return out;
|
|
194
|
+
}
|
|
195
|
+
if (t === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
|
|
196
|
+
const src = value;
|
|
197
|
+
const out = {};
|
|
198
|
+
for (const k in src) {
|
|
199
|
+
if (Object.prototype.hasOwnProperty.call(src, k)) {
|
|
200
|
+
const childPath = path ? `${path}.${k}` : k;
|
|
201
|
+
const s = sanitize(src[k], depth + 1, childPath, onDrop);
|
|
202
|
+
if (s !== undefined)
|
|
203
|
+
out[k] = s;
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
return out;
|
|
207
|
+
}
|
|
208
|
+
if (onDrop)
|
|
209
|
+
onDrop(path, value);
|
|
210
|
+
else if (process.env.NODE_ENV !== 'production') {
|
|
211
|
+
console.warn(`[query-aggregate] Dropped non-plain value at "${path}":`, value);
|
|
212
|
+
}
|
|
213
|
+
return undefined;
|
|
214
|
+
}
|
|
215
|
+
// ─── Allowlist ─────────────────────────────────────────────────────────────────
|
|
216
|
+
function buildAllowedStructures(allowedFields) {
|
|
217
|
+
const lookup = new Set();
|
|
218
|
+
const canonical = new Map();
|
|
219
|
+
for (const f of allowedFields) {
|
|
220
|
+
const lc = f.toLowerCase();
|
|
221
|
+
lookup.add(lc);
|
|
222
|
+
canonical.set(lc, f);
|
|
223
|
+
}
|
|
224
|
+
return { lookup, canonical };
|
|
225
|
+
}
|
|
226
|
+
function isFieldAllowed(field, allowedLookup) {
|
|
227
|
+
return allowedLookup.has(field.toLowerCase());
|
|
228
|
+
}
|
|
229
|
+
function isPlainObject(v) {
|
|
230
|
+
return (v !== null &&
|
|
231
|
+
typeof v === 'object' &&
|
|
232
|
+
!Array.isArray(v) &&
|
|
233
|
+
!(v instanceof Date) &&
|
|
234
|
+
Object.getPrototypeOf(v) === Object.prototype);
|
|
235
|
+
}
|
|
236
|
+
/** Strips any non-operator key not present in the allowlist; recurses into logical operators. */
|
|
237
|
+
function enforceAllowlist(filter, allowedLookup, canonicalMap) {
|
|
238
|
+
if (allowedLookup.size === 0)
|
|
239
|
+
return filter;
|
|
240
|
+
const out = {};
|
|
241
|
+
for (const k in filter) {
|
|
242
|
+
if (!Object.prototype.hasOwnProperty.call(filter, k))
|
|
243
|
+
continue;
|
|
244
|
+
const v = filter[k];
|
|
245
|
+
if (k.startsWith('$')) {
|
|
246
|
+
if (Array.isArray(v)) {
|
|
247
|
+
out[k] = v.map((item) => isPlainObject(item)
|
|
248
|
+
? enforceAllowlist(item, allowedLookup, canonicalMap)
|
|
249
|
+
: item);
|
|
250
|
+
}
|
|
251
|
+
else if (isPlainObject(v)) {
|
|
252
|
+
out[k] = enforceAllowlist(v, allowedLookup, canonicalMap);
|
|
253
|
+
}
|
|
254
|
+
else {
|
|
255
|
+
out[k] = v;
|
|
256
|
+
}
|
|
257
|
+
continue;
|
|
258
|
+
}
|
|
259
|
+
const lc = k.toLowerCase();
|
|
260
|
+
if (allowedLookup.has(lc))
|
|
261
|
+
out[canonicalMap.get(lc) ?? k] = v;
|
|
262
|
+
}
|
|
263
|
+
return out;
|
|
264
|
+
}
|
|
265
|
+
// ─── Fused coercion pass (timezone-aware) ──────────────────────────────────────
|
|
266
|
+
function coerceAll(value, timezone, dateFieldsLookup, parentKey = '', parentOp) {
|
|
267
|
+
if (value === null)
|
|
268
|
+
return null;
|
|
269
|
+
if (typeof value === 'string') {
|
|
270
|
+
if (value === 'true')
|
|
271
|
+
return true;
|
|
272
|
+
if (value === 'false')
|
|
273
|
+
return false;
|
|
274
|
+
if (isDateField(parentKey, dateFieldsLookup)) {
|
|
275
|
+
if (parentOp && IN_LIKE_OPS.has(parentOp)) {
|
|
276
|
+
return coerceDateScalar(value, timezone) ?? value;
|
|
277
|
+
}
|
|
278
|
+
if (PLAIN_DATE_RE.test(value)) {
|
|
279
|
+
const { start, end } = plainDateToUtcRange(value, timezone);
|
|
280
|
+
return { $gte: start, $lt: end };
|
|
281
|
+
}
|
|
282
|
+
return coerceDateScalar(value, timezone) ?? value;
|
|
283
|
+
}
|
|
284
|
+
return value;
|
|
285
|
+
}
|
|
286
|
+
if (typeof value !== 'object' || value instanceof Date)
|
|
287
|
+
return value;
|
|
288
|
+
if (Array.isArray(value)) {
|
|
289
|
+
const out = [];
|
|
290
|
+
for (let i = 0; i < value.length; i++) {
|
|
291
|
+
const coerced = coerceAll(value[i], timezone, dateFieldsLookup, parentKey, parentOp);
|
|
292
|
+
if (coerced !== undefined)
|
|
293
|
+
out.push(coerced);
|
|
294
|
+
}
|
|
295
|
+
return out;
|
|
296
|
+
}
|
|
297
|
+
const src = value;
|
|
298
|
+
const out = {};
|
|
299
|
+
for (const k in src) {
|
|
300
|
+
if (!Object.prototype.hasOwnProperty.call(src, k))
|
|
301
|
+
continue;
|
|
302
|
+
const newKey = COERCIBLE_OPS.has(k) ? `$${k}` : k;
|
|
303
|
+
const isOp = k.startsWith('$') || COERCIBLE_OPS.has(k);
|
|
304
|
+
const childPath = isOp ? parentKey : parentKey ? `${parentKey}.${k}` : k;
|
|
305
|
+
out[newKey] = coerceAll(src[k], timezone, dateFieldsLookup, childPath, isOp ? k : undefined);
|
|
306
|
+
}
|
|
307
|
+
return out;
|
|
308
|
+
}
|
|
309
|
+
// ─── Operator validation ────────────────────────────────────────────────────────
|
|
310
|
+
/** Throws on any BANNED_OPERATORS key at any depth, and on any top-level $ key not in ALLOWED_TOP_LEVEL_OPS. */
|
|
311
|
+
function rejectDisallowedOperators(filter, depth = 0) {
|
|
312
|
+
for (const k in filter) {
|
|
313
|
+
if (!Object.prototype.hasOwnProperty.call(filter, k))
|
|
314
|
+
continue;
|
|
315
|
+
if (BANNED_OPERATORS.has(k)) {
|
|
316
|
+
throw new QueryAggregateValidationError(`Disallowed operator in query: "${k}"`);
|
|
317
|
+
}
|
|
318
|
+
if (depth === 0 && k.startsWith('$') && !ALLOWED_TOP_LEVEL_OPS.has(k)) {
|
|
319
|
+
throw new QueryAggregateValidationError(`Disallowed top-level operator in query string: "${k}"`);
|
|
320
|
+
}
|
|
321
|
+
const v = filter[k];
|
|
322
|
+
if (Array.isArray(v)) {
|
|
323
|
+
for (const item of v) {
|
|
324
|
+
if (isPlainObject(item))
|
|
325
|
+
rejectDisallowedOperators(item, depth + 1);
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
else if (isPlainObject(v)) {
|
|
329
|
+
rejectDisallowedOperators(v, depth + 1);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
/** Scans a developer-authored pipeline stage for destructive stage types ($out/$merge). */
|
|
334
|
+
function rejectBannedStages(stage) {
|
|
335
|
+
if (Array.isArray(stage)) {
|
|
336
|
+
stage.forEach(rejectBannedStages);
|
|
337
|
+
return;
|
|
338
|
+
}
|
|
339
|
+
if (!isPlainObject(stage))
|
|
340
|
+
return;
|
|
341
|
+
for (const k in stage) {
|
|
342
|
+
if (BANNED_STAGE_OPERATORS.has(k)) {
|
|
343
|
+
throw new QueryAggregateValidationError(`Disallowed pipeline stage: "${k}"`);
|
|
344
|
+
}
|
|
345
|
+
rejectBannedStages(stage[k]);
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
// ─── Filter builder ───────────────────────────────────────────────────────────
|
|
349
|
+
function buildFilter(raw, allowedLookup, canonicalMap, timezone, dateFieldsLookup, onDrop) {
|
|
350
|
+
const stripped = {};
|
|
351
|
+
for (const k in raw) {
|
|
352
|
+
if (Object.prototype.hasOwnProperty.call(raw, k) && !RESERVED_KEYS.has(k)) {
|
|
353
|
+
stripped[k] = raw[k];
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
const safe = sanitize(stripped, 0, '', onDrop);
|
|
357
|
+
const coerced = coerceAll(safe, timezone, dateFieldsLookup);
|
|
358
|
+
const allowed = enforceAllowlist(coerced, allowedLookup, canonicalMap);
|
|
359
|
+
rejectDisallowedOperators(allowed);
|
|
360
|
+
return allowed;
|
|
361
|
+
}
|
|
362
|
+
// ─── Sort parser ──────────────────────────────────────────────────────────────
|
|
363
|
+
function parseSort(sort, allowedLookup, canonicalMap) {
|
|
364
|
+
const out = {};
|
|
365
|
+
let count = 0;
|
|
366
|
+
for (const token of sort.split(',')) {
|
|
367
|
+
if (count >= MAX_SORT_FIELDS)
|
|
368
|
+
break;
|
|
369
|
+
const trimmed = token.trim();
|
|
370
|
+
if (!trimmed || trimmed === '-')
|
|
371
|
+
continue;
|
|
372
|
+
const desc = trimmed.startsWith('-');
|
|
373
|
+
const field = desc ? trimmed.slice(1).trim() : trimmed;
|
|
374
|
+
if (!field)
|
|
375
|
+
continue;
|
|
376
|
+
if (allowedLookup.size > 0) {
|
|
377
|
+
if (!isFieldAllowed(field, allowedLookup))
|
|
378
|
+
continue;
|
|
379
|
+
out[canonicalMap.get(field.toLowerCase()) ?? field] = desc ? -1 : 1;
|
|
380
|
+
}
|
|
381
|
+
else {
|
|
382
|
+
out[field] = desc ? -1 : 1;
|
|
383
|
+
}
|
|
384
|
+
count++;
|
|
385
|
+
}
|
|
386
|
+
return Object.keys(out).length > 0 ? out : { ...DEFAULT_SORT };
|
|
387
|
+
}
|
|
388
|
+
// ─── Projection ───────────────────────────────────────────────────────────────
|
|
389
|
+
function sanitizeProjectionString(projection, allowedLookup, canonicalMap) {
|
|
390
|
+
if (allowedLookup.size === 0)
|
|
391
|
+
return projection;
|
|
392
|
+
return projection
|
|
393
|
+
.split(/\s+/)
|
|
394
|
+
.filter(Boolean)
|
|
395
|
+
.filter((token) => {
|
|
396
|
+
const field = token.startsWith('-') ? token.slice(1) : token;
|
|
397
|
+
return (field === '__v' ||
|
|
398
|
+
field === '_id' ||
|
|
399
|
+
isFieldAllowed(field, allowedLookup));
|
|
400
|
+
})
|
|
401
|
+
.map((token) => {
|
|
402
|
+
const isNeg = token.startsWith('-');
|
|
403
|
+
const field = isNeg ? token.slice(1) : token;
|
|
404
|
+
const canonical = canonicalMap.get(field.toLowerCase()) ?? field;
|
|
405
|
+
return isNeg ? `-${canonical}` : canonical;
|
|
406
|
+
})
|
|
407
|
+
.join(' ');
|
|
408
|
+
}
|
|
409
|
+
function projectionStringToObject(projection) {
|
|
410
|
+
const out = {};
|
|
411
|
+
for (const token of projection.split(/\s+/).filter(Boolean)) {
|
|
412
|
+
if (token.startsWith('-'))
|
|
413
|
+
out[token.slice(1)] = 0;
|
|
414
|
+
else
|
|
415
|
+
out[token] = 1;
|
|
416
|
+
}
|
|
417
|
+
return out;
|
|
418
|
+
}
|
|
419
|
+
// ─── QueryAggregate ─────────────────────────────────────────────────────────────
|
|
420
|
+
/**
|
|
421
|
+
* Fluent aggregation-pipeline builder / paginator for Mongoose 8/9, with
|
|
422
|
+
* timezone-aware date filtering.
|
|
423
|
+
*/
|
|
424
|
+
class QueryAggregate {
|
|
425
|
+
constructor(model, queryString, options = {}) {
|
|
426
|
+
this._allowedLookup = new Set();
|
|
427
|
+
this._canonicalMap = new Map();
|
|
428
|
+
this._dateFieldsLookup = null;
|
|
429
|
+
/** URL-derived filter and server conditions are kept separate so server
|
|
430
|
+
* conditions (merged last) can never be overridden by URL params. */
|
|
431
|
+
this._urlFilter = {};
|
|
432
|
+
this._serverConditions = {};
|
|
433
|
+
this._searchOr = [];
|
|
434
|
+
this._sort = { ...DEFAULT_SORT };
|
|
435
|
+
this._projection = null;
|
|
436
|
+
this._defaultProjection = null;
|
|
437
|
+
/** $lookup/$unwind/addStage() stages, in call order, spliced in after the base $match. */
|
|
438
|
+
this._stages = [];
|
|
439
|
+
this.model = model;
|
|
440
|
+
this.qs = Object.freeze({ ...queryString });
|
|
441
|
+
this.options = {
|
|
442
|
+
timezone: resolveTimezone(options.timezone),
|
|
443
|
+
maxTimeMS: options.maxTimeMS ?? DEFAULT_MAX_TIME_MS,
|
|
444
|
+
slowQueryThresholdMS: options.slowQueryThresholdMS ??
|
|
445
|
+
options.maxTimeMS ??
|
|
446
|
+
DEFAULT_MAX_TIME_MS,
|
|
447
|
+
maxLimit: options.maxLimit ?? DEFAULT_MAX_LIMIT,
|
|
448
|
+
allowDiskUse: options.allowDiskUse ?? false,
|
|
449
|
+
weekStartsOn: options.weekStartsOn ?? 6,
|
|
450
|
+
onSlowQuery: options.onSlowQuery,
|
|
451
|
+
onSanitizeDrop: options.onSanitizeDrop,
|
|
452
|
+
};
|
|
453
|
+
this._page = parsePage(this.qs.page);
|
|
454
|
+
this._limit = parseLimit(this.qs.limit, this.options.maxLimit);
|
|
455
|
+
}
|
|
456
|
+
/** The resolved (validated) timezone this instance is using. */
|
|
457
|
+
get timezone() {
|
|
458
|
+
return this.options.timezone;
|
|
459
|
+
}
|
|
460
|
+
// ── Configuration ─────────────────────────────────────────────────────────
|
|
461
|
+
/** Fields the client may filter, sort, and project. Case-insensitive. Call before filter()/sort()/project(). */
|
|
462
|
+
allowFields(fields) {
|
|
463
|
+
const { lookup, canonical } = buildAllowedStructures(new Set(fields));
|
|
464
|
+
this._allowedLookup = lookup;
|
|
465
|
+
this._canonicalMap = canonical;
|
|
466
|
+
return this;
|
|
467
|
+
}
|
|
468
|
+
/** Explicit list of fields treated as dates for timezone-aware coercion. Falls back to a name heuristic (createdAt/updatedAt/...) when omitted. */
|
|
469
|
+
dateFields(fields) {
|
|
470
|
+
this._dateFieldsLookup = new Set(fields.map((f) => f.toLowerCase()));
|
|
471
|
+
return this;
|
|
472
|
+
}
|
|
473
|
+
// ── Builder methods ───────────────────────────────────────────────────────
|
|
474
|
+
/** Parses URL query params (req.query) into a Mongoose filter. Only allowlisted fields pass through. */
|
|
475
|
+
filter() {
|
|
476
|
+
const parsed = buildFilter(this.qs, this._allowedLookup, this._canonicalMap, this.options.timezone, this._dateFieldsLookup, this.options.onSanitizeDrop);
|
|
477
|
+
Object.assign(this._urlFilter, parsed);
|
|
478
|
+
return this;
|
|
479
|
+
}
|
|
480
|
+
/** Mandatory server-side conditions the client cannot override — merged into the final $match last. */
|
|
481
|
+
where(conditions) {
|
|
482
|
+
const asRecord = conditions;
|
|
483
|
+
rejectDisallowedOperators(asRecord);
|
|
484
|
+
Object.assign(this._serverConditions, asRecord);
|
|
485
|
+
return this;
|
|
486
|
+
}
|
|
487
|
+
/** Adds a hard, server-defined UTC date range (in this instance's timezone) on `field`. Not client-overridable. */
|
|
488
|
+
range(field, preset) {
|
|
489
|
+
const { start, end } = this.resolveRangePreset(preset);
|
|
490
|
+
this._serverConditions[field] = { $gte: start, $lt: end };
|
|
491
|
+
return this;
|
|
492
|
+
}
|
|
493
|
+
/** Case-insensitive full-text search across the given fields when ?q= is present. */
|
|
494
|
+
globalSearch(fields) {
|
|
495
|
+
const raw = this.qs.q?.trim();
|
|
496
|
+
if (!raw || raw.length > MAX_SEARCH_LENGTH || fields.length === 0)
|
|
497
|
+
return this;
|
|
498
|
+
const safeFields = this._allowedLookup.size > 0
|
|
499
|
+
? fields.filter((f) => isFieldAllowed(f, this._allowedLookup))
|
|
500
|
+
: fields;
|
|
501
|
+
if (safeFields.length === 0)
|
|
502
|
+
return this;
|
|
503
|
+
const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
504
|
+
const regex = new RegExp(escaped, 'i');
|
|
505
|
+
for (const field of safeFields)
|
|
506
|
+
this._searchOr.push({ [field]: regex });
|
|
507
|
+
return this;
|
|
508
|
+
}
|
|
509
|
+
/** Parses ?sort= (e.g. "-createdAt,name"). Fields not in allowFields() are dropped; falls back to DEFAULT_SORT. */
|
|
510
|
+
sort() {
|
|
511
|
+
if (this.qs.sort) {
|
|
512
|
+
this._sort = parseSort(this.qs.sort, this._allowedLookup, this._canonicalMap);
|
|
513
|
+
}
|
|
514
|
+
return this;
|
|
515
|
+
}
|
|
516
|
+
/**
|
|
517
|
+
* Controls the $project stage. Accepts a space-separated string ("name status -_id")
|
|
518
|
+
* or a raw { field: 0|1 } object. When ?fields= is present it's parsed and
|
|
519
|
+
* filtered through the allowlist; if every requested field is blocked, falls
|
|
520
|
+
* back to `defaultProjection` instead of silently selecting everything.
|
|
521
|
+
*/
|
|
522
|
+
project(defaultProjection) {
|
|
523
|
+
if (defaultProjection) {
|
|
524
|
+
this._defaultProjection =
|
|
525
|
+
typeof defaultProjection === 'string'
|
|
526
|
+
? projectionStringToObject(defaultProjection)
|
|
527
|
+
: defaultProjection;
|
|
528
|
+
}
|
|
529
|
+
if (this.qs.fields) {
|
|
530
|
+
const raw = this.qs.fields
|
|
531
|
+
.split(',')
|
|
532
|
+
.map((f) => f.trim())
|
|
533
|
+
.filter(Boolean)
|
|
534
|
+
.join(' ');
|
|
535
|
+
const sanitized = sanitizeProjectionString(raw, this._allowedLookup, this._canonicalMap);
|
|
536
|
+
this._projection = sanitized
|
|
537
|
+
? projectionStringToObject(sanitized)
|
|
538
|
+
: this._defaultProjection;
|
|
539
|
+
}
|
|
540
|
+
else {
|
|
541
|
+
this._projection = this._defaultProjection;
|
|
542
|
+
}
|
|
543
|
+
return this;
|
|
544
|
+
}
|
|
545
|
+
/** Adds a $lookup (join) stage, optionally followed by $unwind when `single` is true. */
|
|
546
|
+
lookup(opts) {
|
|
547
|
+
const lookupStage = {
|
|
548
|
+
$lookup: {
|
|
549
|
+
from: opts.from,
|
|
550
|
+
as: opts.as,
|
|
551
|
+
...(opts.pipeline ? { pipeline: opts.pipeline } : {}),
|
|
552
|
+
...(opts.localField ? { localField: opts.localField } : {}),
|
|
553
|
+
...(opts.foreignField ? { foreignField: opts.foreignField } : {}),
|
|
554
|
+
},
|
|
555
|
+
};
|
|
556
|
+
this._stages.push(lookupStage);
|
|
557
|
+
if (opts.single) {
|
|
558
|
+
this._stages.push({
|
|
559
|
+
$unwind: { path: `$${opts.as}`, preserveNullAndEmptyArrays: true },
|
|
560
|
+
});
|
|
561
|
+
}
|
|
562
|
+
return this;
|
|
563
|
+
}
|
|
564
|
+
/** 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. */
|
|
565
|
+
addStage(stage) {
|
|
566
|
+
rejectBannedStages(stage);
|
|
567
|
+
this._stages.push(stage);
|
|
568
|
+
return this;
|
|
569
|
+
}
|
|
570
|
+
// ── Private helpers ───────────────────────────────────────────────────────
|
|
571
|
+
resolveRangePreset(preset) {
|
|
572
|
+
const tz = this.options.timezone;
|
|
573
|
+
const zonedNow = (0, date_fns_tz_1.toZonedTime)(new Date(), tz);
|
|
574
|
+
const todayStr = (0, date_fns_1.format)(zonedNow, 'yyyy-MM-dd');
|
|
575
|
+
switch (preset) {
|
|
576
|
+
case 'today':
|
|
577
|
+
return this.utcRangeForLocalDates(todayStr, todayStr);
|
|
578
|
+
case 'yesterday': {
|
|
579
|
+
const y = shiftLocalDateString(todayStr, -1);
|
|
580
|
+
return this.utcRangeForLocalDates(y, y);
|
|
581
|
+
}
|
|
582
|
+
case 'last7Days':
|
|
583
|
+
return this.utcRangeForLocalDates(shiftLocalDateString(todayStr, -6), todayStr);
|
|
584
|
+
case 'last30Days':
|
|
585
|
+
return this.utcRangeForLocalDates(shiftLocalDateString(todayStr, -29), todayStr);
|
|
586
|
+
case 'thisWeek': {
|
|
587
|
+
const weekStartStr = (0, date_fns_1.format)((0, date_fns_1.startOfWeek)(zonedNow, { weekStartsOn: this.options.weekStartsOn }), 'yyyy-MM-dd');
|
|
588
|
+
return this.utcRangeForLocalDates(weekStartStr, todayStr);
|
|
589
|
+
}
|
|
590
|
+
case 'thisMonth': {
|
|
591
|
+
const monthStartStr = (0, date_fns_1.format)((0, date_fns_1.startOfMonth)(zonedNow), 'yyyy-MM-dd');
|
|
592
|
+
return this.utcRangeForLocalDates(monthStartStr, todayStr);
|
|
593
|
+
}
|
|
594
|
+
default:
|
|
595
|
+
throw new QueryAggregateValidationError(`Unknown range preset: "${preset}"`);
|
|
596
|
+
}
|
|
597
|
+
}
|
|
598
|
+
/** [start of fromStr, start of (toStr + 1 day)) in this instance's timezone — an inclusive local-date range. */
|
|
599
|
+
utcRangeForLocalDates(fromStr, toStr) {
|
|
600
|
+
const tz = this.options.timezone;
|
|
601
|
+
const start = (0, date_fns_tz_1.fromZonedTime)(`${fromStr}T00:00:00.000`, tz);
|
|
602
|
+
const end = (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(toStr, 1)}T00:00:00.000`, tz);
|
|
603
|
+
return { start, end };
|
|
604
|
+
}
|
|
605
|
+
buildMatchStage() {
|
|
606
|
+
let base;
|
|
607
|
+
const hasUrlFilter = Object.keys(this._urlFilter).length > 0;
|
|
608
|
+
if (this._searchOr.length > 0) {
|
|
609
|
+
base = hasUrlFilter
|
|
610
|
+
? { $and: [this._urlFilter, { $or: this._searchOr }] }
|
|
611
|
+
: { $or: this._searchOr };
|
|
612
|
+
}
|
|
613
|
+
else {
|
|
614
|
+
base = hasUrlFilter ? this._urlFilter : {};
|
|
615
|
+
}
|
|
616
|
+
const hasServer = Object.keys(this._serverConditions).length > 0;
|
|
617
|
+
const finalFilter = Object.keys(base).length > 0 && hasServer
|
|
618
|
+
? { $and: [base, this._serverConditions] }
|
|
619
|
+
: hasServer
|
|
620
|
+
? this._serverConditions
|
|
621
|
+
: base;
|
|
622
|
+
return Object.keys(finalFilter).length > 0 ? { $match: finalFilter } : null;
|
|
623
|
+
}
|
|
624
|
+
/** Base pipeline shared by every execution path: match -> lookups/custom stages -> project -> sort. */
|
|
625
|
+
buildBasePipeline() {
|
|
626
|
+
const pipeline = [];
|
|
627
|
+
const matchStage = this.buildMatchStage();
|
|
628
|
+
if (matchStage)
|
|
629
|
+
pipeline.push(matchStage);
|
|
630
|
+
pipeline.push(...this._stages);
|
|
631
|
+
if (this._projection)
|
|
632
|
+
pipeline.push({ $project: this._projection });
|
|
633
|
+
pipeline.push({ $sort: this._sort });
|
|
634
|
+
return pipeline;
|
|
635
|
+
}
|
|
636
|
+
execAggregate(pipeline) {
|
|
637
|
+
const agg = this.model.aggregate(pipeline);
|
|
638
|
+
if (this.options.maxTimeMS > 0)
|
|
639
|
+
agg.option({ maxTimeMS: this.options.maxTimeMS });
|
|
640
|
+
if (this.options.allowDiskUse)
|
|
641
|
+
agg.allowDiskUse(true);
|
|
642
|
+
return agg.exec();
|
|
643
|
+
}
|
|
644
|
+
async wrapTimed(fn, page, limit, pipeline) {
|
|
645
|
+
const { onSlowQuery, slowQueryThresholdMS, maxTimeMS } = this.options;
|
|
646
|
+
if (!onSlowQuery)
|
|
647
|
+
return fn();
|
|
648
|
+
const start = Date.now();
|
|
649
|
+
const result = await fn();
|
|
650
|
+
const elapsedMs = Date.now() - start;
|
|
651
|
+
if (elapsedMs >= (slowQueryThresholdMS ?? maxTimeMS)) {
|
|
652
|
+
onSlowQuery({ elapsedMs, pipeline, sort: this._sort, page, limit });
|
|
653
|
+
}
|
|
654
|
+
return result;
|
|
655
|
+
}
|
|
656
|
+
// ── Terminal ───────────────────────────────────────────────────────────────
|
|
657
|
+
/**
|
|
658
|
+
* Executes the pipeline and returns a paginated result via $facet (single
|
|
659
|
+
* round trip: data page + total count together). Pass a prior page-1
|
|
660
|
+
* `total` as `cachedTotal` on later pages to skip the count entirely.
|
|
661
|
+
*
|
|
662
|
+
* Note: $facet buffers both branches in memory per query — for very large
|
|
663
|
+
* collections with expensive pre-facet stages, consider passing
|
|
664
|
+
* `cachedTotal` on subsequent pages, or run count/data as two calls.
|
|
665
|
+
*/
|
|
666
|
+
async paginate(cachedTotal) {
|
|
667
|
+
const page = this._page;
|
|
668
|
+
const limit = this._limit;
|
|
669
|
+
const basePipeline = this.buildBasePipeline();
|
|
670
|
+
if (cachedTotal !== undefined) {
|
|
671
|
+
const totalPages = Math.max(Math.ceil(cachedTotal / limit), 1);
|
|
672
|
+
const safePage = page > totalPages ? 1 : page;
|
|
673
|
+
const dataPipeline = [
|
|
674
|
+
...basePipeline,
|
|
675
|
+
{ $skip: (safePage - 1) * limit },
|
|
676
|
+
{ $limit: limit },
|
|
677
|
+
];
|
|
678
|
+
const data = await this.wrapTimed(() => this.execAggregate(dataPipeline), safePage, limit, dataPipeline);
|
|
679
|
+
return {
|
|
680
|
+
data,
|
|
681
|
+
total: cachedTotal,
|
|
682
|
+
page: safePage,
|
|
683
|
+
totalPages,
|
|
684
|
+
limit,
|
|
685
|
+
hasNextPage: safePage < totalPages,
|
|
686
|
+
hasPrevPage: safePage > 1,
|
|
687
|
+
};
|
|
688
|
+
}
|
|
689
|
+
const facetPipeline = [
|
|
690
|
+
...basePipeline,
|
|
691
|
+
{
|
|
692
|
+
$facet: {
|
|
693
|
+
data: [{ $skip: (page - 1) * limit }, { $limit: limit }],
|
|
694
|
+
totalCount: [{ $count: 'count' }],
|
|
695
|
+
},
|
|
696
|
+
},
|
|
697
|
+
];
|
|
698
|
+
const [facetResult] = await this.wrapTimed(() => this.execAggregate(facetPipeline), page, limit, facetPipeline);
|
|
699
|
+
const total = facetResult?.totalCount?.[0]?.count ?? 0;
|
|
700
|
+
const totalPages = Math.max(Math.ceil(total / limit), 1);
|
|
701
|
+
if (page > totalPages && page !== 1) {
|
|
702
|
+
// Requested page doesn't exist for this filter — refetch page 1 rather
|
|
703
|
+
// than returning an empty page silently.
|
|
704
|
+
const fallbackPipeline = [
|
|
705
|
+
...basePipeline,
|
|
706
|
+
{ $skip: 0 },
|
|
707
|
+
{ $limit: limit },
|
|
708
|
+
];
|
|
709
|
+
const data = await this.execAggregate(fallbackPipeline);
|
|
710
|
+
return {
|
|
711
|
+
data,
|
|
712
|
+
total,
|
|
713
|
+
page: 1,
|
|
714
|
+
totalPages,
|
|
715
|
+
limit,
|
|
716
|
+
hasNextPage: 1 < totalPages,
|
|
717
|
+
hasPrevPage: false,
|
|
718
|
+
};
|
|
719
|
+
}
|
|
720
|
+
return {
|
|
721
|
+
data: facetResult?.data ?? [],
|
|
722
|
+
total,
|
|
723
|
+
page,
|
|
724
|
+
totalPages,
|
|
725
|
+
limit,
|
|
726
|
+
hasNextPage: page < totalPages,
|
|
727
|
+
hasPrevPage: page > 1,
|
|
728
|
+
};
|
|
729
|
+
}
|
|
730
|
+
}
|
|
731
|
+
exports.QueryAggregate = QueryAggregate;
|
|
732
|
+
exports.default = QueryAggregate;
|
|
733
|
+
//# sourceMappingURL=aggregate.js.map
|