mongoose-query-find 3.1.0 → 3.2.0

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.
@@ -43,6 +43,23 @@
43
43
  * stages — it only blocks destructive stage types ($out/$merge). It does NOT
44
44
  * run the client-input sanitizer; that only applies to .filter()/.where(),
45
45
  * which parse untrusted req.query / req.body values.
46
+ *
47
+ * ── Custom ranges ────────────────────────────────────────────────────────────
48
+ * `.range(field, preset)` covers the fixed RangePreset values (today,
49
+ * yesterday, last7Days, last30Days, thisWeek, thisMonth). For anything more
50
+ * specific — a single arbitrary day, an arbitrary date span, a rolling
51
+ * window of N days/hours, an explicit hour-of-day window, or an explicit
52
+ * absolute datetime window — use the new custom range methods below:
53
+ *
54
+ * .rangeCustomDay(field, '2026-03-14')
55
+ * .rangeBetween(field, { from: '2026-01-01', to: '2026-01-31' })
56
+ * .rangeLastNDays(field, 14)
57
+ * .rangeLastNHours(field, 6)
58
+ * .rangeHours(field, { date: '2026-03-14', fromHour: 9, toHour: 17 })
59
+ * .rangeCustom(field, { from: '2026-03-14T09:00:00', to: '2026-03-15T00:00:00' })
60
+ *
61
+ * All of these behave like .range(): they set a hard, server-side condition
62
+ * that the client cannot override via query params.
46
63
  */
47
64
  import { Model, PipelineStage } from 'mongoose';
48
65
  export interface QueryParams {
@@ -70,6 +87,50 @@ export interface SlowQueryInfo {
70
87
  limit: number;
71
88
  }
72
89
  export type RangePreset = 'today' | 'yesterday' | 'last7Days' | 'last30Days' | 'thisWeek' | 'thisMonth';
90
+ /** A single arbitrary local calendar date, e.g. "2026-03-14". */
91
+ export type CustomDayInput = string;
92
+ /** An inclusive local-date span, e.g. { from: '2026-01-01', to: '2026-01-31' }. */
93
+ export interface CustomDateRangeInput {
94
+ from: string;
95
+ to: string;
96
+ }
97
+ /** An explicit hour-of-day window on a given local date (0–24, `toHour` exclusive; pass 24 for "through end of day"). */
98
+ export interface CustomHourRangeInput {
99
+ date: string;
100
+ fromHour: number;
101
+ toHour: number;
102
+ }
103
+ /**
104
+ * An explicit absolute datetime window. Each of `from`/`to` accepts:
105
+ * - "YYYY-MM-DD" -> local midnight in this instance's timezone
106
+ * - "YYYY-MM-DDTHH:mm:ss[.sss]" -> local wall-clock time in this instance's timezone
107
+ * - an offset-bearing ISO string ("...Z" / "...+06:00") -> absolute instant
108
+ */
109
+ export interface CustomDateTimeRangeInput {
110
+ from: string;
111
+ to: string;
112
+ }
113
+ /** Options for .paginateCursor() — keyset/seek pagination, better than skip/limit on large collections. */
114
+ export interface CursorPaginateOptions {
115
+ /** Opaque cursor from a previous page's `nextCursor`. Omit for the first page. */
116
+ cursor?: string;
117
+ /** Overrides the instance's parsed ?limit=, capped by maxLimit like normal pagination. */
118
+ limit?: number;
119
+ }
120
+ export interface CursorPaginatedResult<T> {
121
+ data: T[];
122
+ limit: number;
123
+ /** Pass this back as `cursor` to fetch the next page; null when there are no more results. */
124
+ nextCursor: string | null;
125
+ hasNextPage: boolean;
126
+ }
127
+ /** One aggregate metric for .stats() — e.g. { name: 'revenue', op: 'sum', field: 'total' }. */
128
+ export interface StatSpec {
129
+ name: string;
130
+ op: 'sum' | 'avg' | 'min' | 'max' | 'count';
131
+ /** Required for every op except 'count'. */
132
+ field?: string;
133
+ }
73
134
  export interface LookupOptions {
74
135
  /** Collection name (not the model name) to join against. */
75
136
  from: string;
@@ -142,6 +203,23 @@ export declare class QueryAggregate<T> {
142
203
  where(conditions: Partial<Record<keyof T, unknown>>): this;
143
204
  /** Adds a hard, server-defined UTC date range (in this instance's timezone) on `field`. Not client-overridable. */
144
205
  range(field: string, preset: RangePreset): this;
206
+ /** Hard server-side condition for a single arbitrary local calendar date (e.g. "2026-03-14"), in this instance's timezone. Not client-overridable. */
207
+ rangeCustomDay(field: string, date: CustomDayInput): this;
208
+ /** 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. */
209
+ rangeBetween(field: string, custom: CustomDateRangeInput): this;
210
+ /** 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. */
211
+ rangeLastNDays(field: string, days: number): this;
212
+ /** 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. */
213
+ rangeLastNHours(field: string, hours: number): this;
214
+ /** 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. */
215
+ rangeHours(field: string, custom: CustomHourRangeInput): this;
216
+ /**
217
+ * Hard server-side condition for an explicit absolute datetime window.
218
+ * Accepts "YYYY-MM-DD" (local midnight), "YYYY-MM-DDTHH:mm:ss" (local
219
+ * wall-clock), or an offset-bearing ISO string (absolute instant) for
220
+ * both `from` and `to`. Not client-overridable.
221
+ */
222
+ rangeCustom(field: string, custom: CustomDateTimeRangeInput): this;
145
223
  /** Case-insensitive full-text search across the given fields when ?q= is present. */
146
224
  globalSearch(fields: string[]): this;
147
225
  /** Parses ?sort= (e.g. "-createdAt,name"). Fields not in allowFields() are dropped; falls back to DEFAULT_SORT. */
@@ -161,6 +239,12 @@ export declare class QueryAggregate<T> {
161
239
  /** [start of fromStr, start of (toStr + 1 day)) in this instance's timezone — an inclusive local-date range. */
162
240
  private utcRangeForLocalDates;
163
241
  private buildMatchStage;
242
+ /** Match + lookups/custom stages only, no $project/$sort — shared by count()/distinct()/stats(), which don't need either. */
243
+ private buildMatchAndStagesPipeline;
244
+ /** Encodes a keyset cursor from a result row: the current sort field's value plus `_id` as a stable tiebreaker. */
245
+ private encodeCursor;
246
+ /** Decodes a cursor produced by encodeCursor(), restoring Date/ObjectId typing so comparisons stay type-correct. */
247
+ private decodeCursor;
164
248
  /** Base pipeline shared by every execution path: match -> lookups/custom stages -> project -> sort. */
165
249
  private buildBasePipeline;
166
250
  private execAggregate;
@@ -175,6 +259,49 @@ export declare class QueryAggregate<T> {
175
259
  * `cachedTotal` on subsequent pages, or run count/data as two calls.
176
260
  */
177
261
  paginate(cachedTotal?: number): Promise<PaginatedResult<T>>;
262
+ /** Returns just the matching document count — cheaper than paginate() when you don't need the data page. Ignores $project/$sort. */
263
+ count(): Promise<number>;
264
+ /** Returns the distinct values of `field` for the current filter/where/range conditions. */
265
+ distinct<V = unknown>(field: string): Promise<V[]>;
266
+ /**
267
+ * Computes one or more aggregate metrics (sum/avg/min/max/count) over the
268
+ * current filter/where/range conditions in a single round trip — handy for
269
+ * dashboard totals ("revenue", "avgOrderValue", "orderCount", ...).
270
+ * Ignores $project/$sort/pagination.
271
+ */
272
+ stats(specs: StatSpec[]): Promise<Record<string, number>>;
273
+ /**
274
+ * Streams results as an async-iterable cursor instead of buffering the
275
+ * whole page in memory — use for large exports (CSV generation, bulk
276
+ * processing) with `for await (const doc of qa.stream())`. Ignores
277
+ * page/limit; add your own $limit via .addStage() if you want a cap.
278
+ */
279
+ stream(): ReturnType<ReturnType<Model<T>['aggregate']>['cursor']>;
280
+ /**
281
+ * Keyset ("seek") pagination — scales far better than .paginate()'s
282
+ * $skip on deep pages of large collections, at the cost of not supporting
283
+ * "jump to page N". Requires .sort() to have been called with exactly the
284
+ * field you want to seek on (falls back to DEFAULT_SORT's `createdAt`
285
+ * otherwise). Pass the previous page's `nextCursor` back in as `cursor`
286
+ * to continue; a `hasNextPage: false` / `nextCursor: null` page is the end.
287
+ */
288
+ paginateCursor(opts?: CursorPaginateOptions): Promise<CursorPaginatedResult<T>>;
289
+ /**
290
+ * Runs the built pipeline through Mongoose's .explain() for debugging
291
+ * slow queries / verifying index usage. Never use in a hot request path —
292
+ * this is a development/ops tool.
293
+ */
294
+ explain(verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution'): Promise<unknown>;
295
+ /** Convenience wrapper over addStage() for a computed $addFields entry, e.g. .computeField('margin', { $subtract: ['$price', '$cost'] }). */
296
+ computeField(name: string, expression: unknown): this;
297
+ /** Convenience server-side condition excluding soft-deleted docs (matches both `null` and a missing field, per MongoDB equality semantics). Not client-overridable. */
298
+ excludeSoftDeleted(field?: string): this;
299
+ /** Applies .where(conditions) only when `condition` is truthy — avoids scattering if-statements around chained builder calls. */
300
+ whereIf(condition: unknown, conditions: Partial<Record<keyof T, unknown>>): this;
301
+ /** Deep-copies the current builder state (filters, sort, projection, stages) into a new independent instance — handy for branching one shared base query into e.g. both .paginate() and .stats() without rebuilding it twice. */
302
+ clone(): QueryAggregate<T>;
303
+ /** Returns the fully-built pipeline without executing it — for logging, snapshot tests, or sanity-checking what will actually run. */
304
+ debugPipeline(): PipelineStage[];
178
305
  }
179
306
  export default QueryAggregate;
180
307
  //# sourceMappingURL=aggregate.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"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"}
package/dist/aggregate.js CHANGED
@@ -44,6 +44,23 @@
44
44
  * stages — it only blocks destructive stage types ($out/$merge). It does NOT
45
45
  * run the client-input sanitizer; that only applies to .filter()/.where(),
46
46
  * which parse untrusted req.query / req.body values.
47
+ *
48
+ * ── Custom ranges ────────────────────────────────────────────────────────────
49
+ * `.range(field, preset)` covers the fixed RangePreset values (today,
50
+ * yesterday, last7Days, last30Days, thisWeek, thisMonth). For anything more
51
+ * specific — a single arbitrary day, an arbitrary date span, a rolling
52
+ * window of N days/hours, an explicit hour-of-day window, or an explicit
53
+ * absolute datetime window — use the new custom range methods below:
54
+ *
55
+ * .rangeCustomDay(field, '2026-03-14')
56
+ * .rangeBetween(field, { from: '2026-01-01', to: '2026-01-31' })
57
+ * .rangeLastNDays(field, 14)
58
+ * .rangeLastNHours(field, 6)
59
+ * .rangeHours(field, { date: '2026-03-14', fromHour: 9, toHour: 17 })
60
+ * .rangeCustom(field, { from: '2026-03-14T09:00:00', to: '2026-03-15T00:00:00' })
61
+ *
62
+ * All of these behave like .range(): they set a hard, server-side condition
63
+ * that the client cannot override via query params.
47
64
  */
48
65
  Object.defineProperty(exports, "__esModule", { value: true });
49
66
  exports.QueryAggregate = exports.QueryAggregateValidationError = exports.QueryAggregateError = void 0;
@@ -537,6 +554,95 @@ class QueryAggregate {
537
554
  this._serverConditions[field] = { $gte: start, $lt: end };
538
555
  return this;
539
556
  }
557
+ // ── Custom range methods (additive — RangePreset/.range() above is
558
+ // untouched; these cover custom day / custom range / custom N-days /
559
+ // custom N-hours / custom hour-of-day window / custom absolute datetime
560
+ // window use cases) ─────────────────────────────────────────────────────
561
+ /** 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
+ rangeCustomDay(field, date) {
563
+ if (!PLAIN_DATE_RE.test(date)) {
564
+ throw new QueryAggregateValidationError(`rangeCustomDay: "date" must be in YYYY-MM-DD format, got "${date}"`);
565
+ }
566
+ const { start, end } = this.utcRangeForLocalDates(date, date);
567
+ this._serverConditions[field] = { $gte: start, $lt: end };
568
+ return this;
569
+ }
570
+ /** 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
+ rangeBetween(field, custom) {
572
+ const { from, to } = custom;
573
+ if (!PLAIN_DATE_RE.test(from) || !PLAIN_DATE_RE.test(to)) {
574
+ throw new QueryAggregateValidationError(`rangeBetween: "from"/"to" must be in YYYY-MM-DD format, got "${from}" / "${to}"`);
575
+ }
576
+ const { start, end } = this.utcRangeForLocalDates(from, to);
577
+ this._serverConditions[field] = { $gte: start, $lt: end };
578
+ return this;
579
+ }
580
+ /** 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. */
581
+ rangeLastNDays(field, days) {
582
+ if (!Number.isInteger(days) || days < 1) {
583
+ throw new QueryAggregateValidationError(`rangeLastNDays: "days" must be a positive integer, got ${days}`);
584
+ }
585
+ const tz = this.options.timezone;
586
+ const zonedNow = (0, date_fns_tz_1.toZonedTime)(new Date(), tz);
587
+ const todayStr = (0, date_fns_1.format)(zonedNow, 'yyyy-MM-dd');
588
+ const fromStr = shiftLocalDateString(todayStr, -(days - 1));
589
+ const { start, end } = this.utcRangeForLocalDates(fromStr, todayStr);
590
+ this._serverConditions[field] = { $gte: start, $lt: end };
591
+ return this;
592
+ }
593
+ /** 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. */
594
+ rangeLastNHours(field, hours) {
595
+ if (!Number.isInteger(hours) || hours < 1) {
596
+ throw new QueryAggregateValidationError(`rangeLastNHours: "hours" must be a positive integer, got ${hours}`);
597
+ }
598
+ const end = new Date();
599
+ const start = new Date(end.getTime() - hours * 60 * 60 * 1000);
600
+ this._serverConditions[field] = { $gte: start, $lt: end };
601
+ return this;
602
+ }
603
+ /** 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
+ rangeHours(field, custom) {
605
+ const { date, fromHour, toHour } = custom;
606
+ if (!PLAIN_DATE_RE.test(date)) {
607
+ throw new QueryAggregateValidationError(`rangeHours: "date" must be in YYYY-MM-DD format, got "${date}"`);
608
+ }
609
+ if (!Number.isInteger(fromHour) ||
610
+ !Number.isInteger(toHour) ||
611
+ fromHour < 0 ||
612
+ fromHour > 24 ||
613
+ toHour < 0 ||
614
+ toHour > 24 ||
615
+ toHour <= fromHour) {
616
+ throw new QueryAggregateValidationError(`rangeHours: "fromHour"/"toHour" must be integers 0–24 with toHour > fromHour, got ${fromHour} / ${toHour}`);
617
+ }
618
+ const tz = this.options.timezone;
619
+ const pad = (n) => String(n).padStart(2, '0');
620
+ const start = (0, date_fns_tz_1.fromZonedTime)(`${date}T${pad(fromHour)}:00:00.000`, tz);
621
+ const end = toHour === 24
622
+ ? (0, date_fns_tz_1.fromZonedTime)(`${shiftLocalDateString(date, 1)}T00:00:00.000`, tz)
623
+ : (0, date_fns_tz_1.fromZonedTime)(`${date}T${pad(toHour)}:00:00.000`, tz);
624
+ this._serverConditions[field] = { $gte: start, $lt: end };
625
+ return this;
626
+ }
627
+ /**
628
+ * Hard server-side condition for an explicit absolute datetime window.
629
+ * Accepts "YYYY-MM-DD" (local midnight), "YYYY-MM-DDTHH:mm:ss" (local
630
+ * wall-clock), or an offset-bearing ISO string (absolute instant) for
631
+ * both `from` and `to`. Not client-overridable.
632
+ */
633
+ rangeCustom(field, custom) {
634
+ const tz = this.options.timezone;
635
+ const start = coerceDateScalar(custom.from, tz);
636
+ const end = coerceDateScalar(custom.to, tz);
637
+ if (!start || !end) {
638
+ throw new QueryAggregateValidationError(`rangeCustom: could not parse "from"/"to" — got "${custom.from}" / "${custom.to}"`);
639
+ }
640
+ if (end <= start) {
641
+ throw new QueryAggregateValidationError(`rangeCustom: "to" (${custom.to}) must be after "from" (${custom.from})`);
642
+ }
643
+ this._serverConditions[field] = { $gte: start, $lt: end };
644
+ return this;
645
+ }
540
646
  /** Case-insensitive full-text search across the given fields when ?q= is present. */
541
647
  globalSearch(fields) {
542
648
  const raw = this.qs.q?.trim();
@@ -668,6 +774,50 @@ class QueryAggregate {
668
774
  : base;
669
775
  return Object.keys(finalFilter).length > 0 ? { $match: finalFilter } : null;
670
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;
785
+ }
786
+ /** Encodes a keyset cursor from a result row: the current sort field's value plus `_id` as a stable tiebreaker. */
787
+ encodeCursor(doc, sortField) {
788
+ const raw = doc[sortField];
789
+ let v = raw;
790
+ let t = 'other';
791
+ if (raw instanceof Date) {
792
+ v = raw.toISOString();
793
+ t = 'date';
794
+ }
795
+ else if (raw instanceof mongoose_1.Types.ObjectId) {
796
+ v = raw.toString();
797
+ t = 'objectid';
798
+ }
799
+ const id = doc._id;
800
+ return Buffer.from(JSON.stringify({ v, t, id: String(id) })).toString('base64url');
801
+ }
802
+ /** Decodes a cursor produced by encodeCursor(), restoring Date/ObjectId typing so comparisons stay type-correct. */
803
+ decodeCursor(cursor) {
804
+ let parsed;
805
+ try {
806
+ parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
807
+ }
808
+ catch {
809
+ throw new QueryAggregateValidationError('paginateCursor: invalid cursor');
810
+ }
811
+ let v = parsed.v;
812
+ if (parsed.t === 'date' && typeof v === 'string')
813
+ v = new Date(v);
814
+ if (parsed.t === 'objectid' &&
815
+ typeof v === 'string' &&
816
+ (0, mongoose_1.isValidObjectId)(v)) {
817
+ v = new mongoose_1.Types.ObjectId(v);
818
+ }
819
+ return { v, id: parsed.id };
820
+ }
671
821
  /** Base pipeline shared by every execution path: match -> lookups/custom stages -> project -> sort. */
672
822
  buildBasePipeline() {
673
823
  const pipeline = [];
@@ -774,6 +924,164 @@ class QueryAggregate {
774
924
  hasPrevPage: page > 1,
775
925
  };
776
926
  }
927
+ // ── Advanced terminal & utility methods (additive — paginate() above is
928
+ // untouched) ─────────────────────────────────────────────────────────────
929
+ /** Returns just the matching document count — cheaper than paginate() when you don't need the data page. Ignores $project/$sort. */
930
+ async count() {
931
+ const pipeline = [
932
+ ...this.buildMatchAndStagesPipeline(),
933
+ { $count: 'count' },
934
+ ];
935
+ const [row] = await this.execAggregate(pipeline);
936
+ return row?.count ?? 0;
937
+ }
938
+ /** Returns the distinct values of `field` for the current filter/where/range conditions. */
939
+ async distinct(field) {
940
+ const pipeline = [
941
+ ...this.buildMatchAndStagesPipeline(),
942
+ { $group: { _id: `$${field}` } },
943
+ ];
944
+ const rows = await this.execAggregate(pipeline);
945
+ return rows.map((r) => r._id);
946
+ }
947
+ /**
948
+ * Computes one or more aggregate metrics (sum/avg/min/max/count) over the
949
+ * current filter/where/range conditions in a single round trip — handy for
950
+ * dashboard totals ("revenue", "avgOrderValue", "orderCount", ...).
951
+ * Ignores $project/$sort/pagination.
952
+ */
953
+ async stats(specs) {
954
+ const group = { _id: null };
955
+ for (const spec of specs) {
956
+ if (spec.op === 'count') {
957
+ group[spec.name] = { $sum: 1 };
958
+ }
959
+ else {
960
+ if (!spec.field) {
961
+ throw new QueryAggregateValidationError(`stats: metric "${spec.name}" needs a "field" for op "${spec.op}"`);
962
+ }
963
+ group[spec.name] = { [`$${spec.op}`]: `$${spec.field}` };
964
+ }
965
+ }
966
+ const pipeline = [
967
+ ...this.buildMatchAndStagesPipeline(),
968
+ { $group: group },
969
+ ];
970
+ const [row] = await this.execAggregate(pipeline);
971
+ const out = {};
972
+ for (const spec of specs)
973
+ out[spec.name] = row?.[spec.name] ?? 0;
974
+ return out;
975
+ }
976
+ /**
977
+ * Streams results as an async-iterable cursor instead of buffering the
978
+ * whole page in memory — use for large exports (CSV generation, bulk
979
+ * processing) with `for await (const doc of qa.stream())`. Ignores
980
+ * page/limit; add your own $limit via .addStage() if you want a cap.
981
+ */
982
+ stream() {
983
+ const pipeline = this.buildBasePipeline();
984
+ const agg = this.model.aggregate(pipeline);
985
+ if (this.options.maxTimeMS > 0)
986
+ agg.option({ maxTimeMS: this.options.maxTimeMS });
987
+ if (this.options.allowDiskUse)
988
+ agg.allowDiskUse(true);
989
+ return agg.cursor();
990
+ }
991
+ /**
992
+ * Keyset ("seek") pagination — scales far better than .paginate()'s
993
+ * $skip on deep pages of large collections, at the cost of not supporting
994
+ * "jump to page N". Requires .sort() to have been called with exactly the
995
+ * field you want to seek on (falls back to DEFAULT_SORT's `createdAt`
996
+ * otherwise). Pass the previous page's `nextCursor` back in as `cursor`
997
+ * to continue; a `hasNextPage: false` / `nextCursor: null` page is the end.
998
+ */
999
+ async paginateCursor(opts = {}) {
1000
+ const limit = opts.limit && opts.limit > 0
1001
+ ? Math.min(opts.limit, this.options.maxLimit)
1002
+ : this._limit;
1003
+ const [sortField, sortDir] = Object.entries(this._sort)[0] ?? [
1004
+ 'createdAt',
1005
+ -1,
1006
+ ];
1007
+ const pipeline = this.buildMatchAndStagesPipeline();
1008
+ 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;
1012
+ pipeline.push({
1013
+ $match: {
1014
+ $or: [
1015
+ { [sortField]: { [cmp]: v } },
1016
+ { [sortField]: v, _id: { [cmp]: idValue } },
1017
+ ],
1018
+ },
1019
+ });
1020
+ }
1021
+ if (this._projection)
1022
+ pipeline.push({ $project: this._projection });
1023
+ pipeline.push({ $sort: { [sortField]: sortDir, _id: sortDir } });
1024
+ pipeline.push({ $limit: limit + 1 });
1025
+ const rows = await this.execAggregate(pipeline);
1026
+ const hasNextPage = rows.length > limit;
1027
+ const data = (hasNextPage ? rows.slice(0, limit) : rows);
1028
+ const nextCursor = hasNextPage
1029
+ ? this.encodeCursor(data[data.length - 1], sortField)
1030
+ : null;
1031
+ return { data, limit, nextCursor, hasNextPage };
1032
+ }
1033
+ /**
1034
+ * Runs the built pipeline through Mongoose's .explain() for debugging
1035
+ * slow queries / verifying index usage. Never use in a hot request path —
1036
+ * this is a development/ops tool.
1037
+ */
1038
+ async explain(verbosity = 'queryPlanner') {
1039
+ const pipeline = this.buildBasePipeline();
1040
+ return this.model.aggregate(pipeline).explain(verbosity);
1041
+ }
1042
+ /** Convenience wrapper over addStage() for a computed $addFields entry, e.g. .computeField('margin', { $subtract: ['$price', '$cost'] }). */
1043
+ computeField(name, expression) {
1044
+ return this.addStage({
1045
+ $addFields: { [name]: expression },
1046
+ });
1047
+ }
1048
+ /** Convenience server-side condition excluding soft-deleted docs (matches both `null` and a missing field, per MongoDB equality semantics). Not client-overridable. */
1049
+ excludeSoftDeleted(field = 'deletedAt') {
1050
+ this._serverConditions[field] = null;
1051
+ return this;
1052
+ }
1053
+ /** Applies .where(conditions) only when `condition` is truthy — avoids scattering if-statements around chained builder calls. */
1054
+ whereIf(condition, conditions) {
1055
+ if (condition)
1056
+ this.where(conditions);
1057
+ return this;
1058
+ }
1059
+ /** Deep-copies the current builder state (filters, sort, projection, stages) into a new independent instance — handy for branching one shared base query into e.g. both .paginate() and .stats() without rebuilding it twice. */
1060
+ clone() {
1061
+ const copy = new QueryAggregate(this.model, this.qs, this.options);
1062
+ copy._allowedLookup = new Set(this._allowedLookup);
1063
+ copy._canonicalMap = new Map(this._canonicalMap);
1064
+ copy._dateFieldsLookup = this._dateFieldsLookup
1065
+ ? new Set(this._dateFieldsLookup)
1066
+ : null;
1067
+ copy._objectIdFieldsLookup = this._objectIdFieldsLookup
1068
+ ? new Set(this._objectIdFieldsLookup)
1069
+ : null;
1070
+ copy._urlFilter = { ...this._urlFilter };
1071
+ copy._serverConditions = { ...this._serverConditions };
1072
+ copy._searchOr = [...this._searchOr];
1073
+ copy._sort = { ...this._sort };
1074
+ copy._projection = this._projection ? { ...this._projection } : null;
1075
+ copy._defaultProjection = this._defaultProjection
1076
+ ? { ...this._defaultProjection }
1077
+ : null;
1078
+ copy._stages = [...this._stages];
1079
+ return copy;
1080
+ }
1081
+ /** Returns the fully-built pipeline without executing it — for logging, snapshot tests, or sanity-checking what will actually run. */
1082
+ debugPipeline() {
1083
+ return this.buildBasePipeline();
1084
+ }
777
1085
  }
778
1086
  exports.QueryAggregate = QueryAggregate;
779
1087
  exports.default = QueryAggregate;