@classytic/mongokit 3.40.0 → 3.41.0

package/dist/{PaginationEngine-Dvl8jcRY.mjs → PaginationEngine-DZnkbSrr.mjs}

@@ -1,9 +1,12 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
+import { i as applyToQuery, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-BxUcSOoF.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./pagination/utils/limits.mjs";
 import mongoose from "mongoose";
-import { createHmac, timingSafeEqual } from "node:crypto";
+import { createTtlMemo } from "@classytic/repo-core/cache";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { CURSOR_ERROR_CODES } from "@classytic/repo-core/pagination";
 //#region src/pagination/utils/cursor-signing.ts
 /**
 * HMAC signing for pagination cursors.
@@ -119,14 +122,6 @@ function verifySignature(token, secrets) {
 	for (const key of secrets) if (matches(signature, sign(payload, key))) return payload;
 	throw new Error("Invalid cursor token: signature does not verify (tampered, or issued under a retired key)");
 }
-/**
-* Whether cursor signing is switched on. Callers use it to refuse the shapes
-* that BYPASS signing rather than break it — a bare ObjectId is a perfectly
-* valid position that carries no signature at all.
-*/
-function signingRequired(secrets) {
-	return secrets !== void 0;
-}
 //#endregion
 //#region src/pagination/defaults.ts
 /**
@@ -191,6 +186,8 @@ function stripUndefined(input) {
 	if (input.cursorSecret !== void 0) out.cursorSecret = input.cursorSecret;
 	if (input.defaultMode !== void 0) out.defaultMode = input.defaultMode;
 	if (input.maxPage !== void 0) out.maxPage = input.maxPage;
+	if (input.maxOffset !== void 0) out.maxOffset = input.maxOffset;
+	if (input.countCacheTtlMs !== void 0) out.countCacheTtlMs = input.countCacheTtlMs;
 	return out;
 }
 /**
@@ -207,6 +204,8 @@ function bindPaginationDefaults(resolved, config) {
 	define(resolved, "cursorSecret", config.cursorSecret, void 0);
 	define(resolved, "defaultMode", config.defaultMode, void 0);
 	define(resolved, "maxPage", config.maxPage, 1e4);
+	define(resolved, "maxOffset", config.maxOffset, 1e5);
+	define(resolved, "countCacheTtlMs", config.countCacheTtlMs, 3e4);
 	return resolved;
 }
 function define(target, key, explicit, fallback) {
@@ -329,6 +328,125 @@ function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId, cursorValue
 	return combine(baseFilters, { $or: orConditions });
 }
 //#endregion
+//#region src/pagination/utils/guards.ts
+/**
+* Pagination guards shared by every paged read: the deep-offset refusal, the unique `_id`
+* tiebreaker that makes a sort a total order, and the cursor SCOPE fingerprint — a hash of
+* (collection, post-policy filter, collation) carried in every cursor, so a cursor replayed
+* against another collection, tenant, filter or collation is refused, never re-anchored.
+*/
+const PAGINATION_ERROR_CODES = {
+	OFFSET_TOO_DEEP: "mongokit.pagination.offset_too_deep",
+	/** repo-core's shared cursor vocabulary (one code set across kits and merged cursors). */
+	CURSOR_INVALID: CURSOR_ERROR_CODES.INVALID,
+	CURSOR_SCOPE_MISMATCH: CURSOR_ERROR_CODES.SCOPE_MISMATCH
+};
+/** Refuse an offset page whose skip exceeds the cap: the scan cost grows with the skip. */
+function assertOffsetWithinCap(skip, maxOffset) {
+	if (skip > maxOffset) throw createError(400, `Offset ${skip} exceeds the deepest allowed offset (${maxOffset}); page with keyset (sort + after) instead`, {
+		code: PAGINATION_ERROR_CODES.OFFSET_TOO_DEEP,
+		meta: {
+			skip,
+			maxOffset
+		}
+	});
+}
+/** Append `_id` (in the last key's direction) unless the sort already ends on it. */
+function withIdTiebreak(sort) {
+	const keys = Object.keys(sort);
+	if (keys.length === 0 || keys.includes("_id")) return sort;
+	return {
+		...sort,
+		_id: sort[keys[keys.length - 1]] ?? 1
+	};
+}
+/** Append each group key (ascending) that the sort does not already name: IR rows are unique per group. */
+function withGroupTiebreak(sort, groupKeys) {
+	const out = { ...sort };
+	for (const key of groupKeys) if (!(key in out)) out[key] = 1;
+	return out;
+}
+function invalidCursor(message) {
+	return createError(400, `Invalid cursor: ${message}`, { code: PAGINATION_ERROR_CODES.CURSOR_INVALID });
+}
+function cursorScopeMismatch() {
+	return createError(400, "Invalid cursor: it was issued for a different collection, tenant, filter or collation", { code: PAGINATION_ERROR_CODES.CURSOR_SCOPE_MISMATCH });
+}
+function canonical(value) {
+	if (value === null || value === void 0) return null;
+	if (value instanceof Date) return { $date: value.toISOString() };
+	if (value instanceof RegExp) return { $regex: value.toString() };
+	if (Array.isArray(value)) return value.map(canonical);
+	if (typeof value === "object") {
+		const hex = value.toHexString;
+		if (typeof hex === "function") return { $oid: hex.call(value) };
+		const bsontype = value._bsontype;
+		if (bsontype) return { [`$${bsontype}`]: String(value) };
+		return Object.fromEntries(Object.keys(value).sort().map((k) => [k, canonical(value[k])]));
+	}
+	return value;
+}
+/** 16-hex fingerprint of what a cursor's position is relative to. */
+function cursorScope(collection, filters, collation) {
+	return createHash("sha256").update(JSON.stringify([
+		collection,
+		canonical(filters),
+		canonical(collation)
+	])).digest("hex").slice(0, 16);
+}
+/** Stages after which `_id` no longer identifies one output row (or no longer exists as given). */
+const IDENTITY_CHANGING = /* @__PURE__ */ new Set([
+	"$unwind",
+	"$group",
+	"$replaceRoot",
+	"$replaceWith",
+	"$unionWith",
+	"$bucket",
+	"$bucketAuto",
+	"$sortByCount",
+	"$facet",
+	"$densify",
+	"$fill",
+	"$documents"
+]);
+function rewritesId(stage) {
+	for (const op of [
+		"$project",
+		"$addFields",
+		"$set"
+	]) {
+		const body = stage[op];
+		if (body && typeof body === "object" && "_id" in body) return true;
+	}
+	return stage.$unset === "_id" || Array.isArray(stage.$unset) && stage.$unset.includes("_id");
+}
+/**
+* Whether an offset page over `pipeline` is PROVABLY totally ordered: its last `$sort` contains
+* `_id`, and no stage before that sort changes what `_id` identifies. A heuristic: a sort can be
+* total by domain knowledge (`{ date, entry, line }`), which only the caller can state.
+*/
+function pipelineSortIsTotal(pipeline) {
+	let lastSort = -1;
+	pipeline.forEach((s, i) => {
+		if (s && typeof s === "object" && "$sort" in s) lastSort = i;
+	});
+	if (lastSort === -1) return false;
+	if (!("_id" in pipeline[lastSort].$sort)) return false;
+	return pipeline.slice(0, lastSort).every((s) => {
+		const stage = s ?? {};
+		return !Object.keys(stage).some((k) => IDENTITY_CHANGING.has(k)) && !rewritesId(stage);
+	});
+}
+const warnedSortSites = /* @__PURE__ */ new Set();
+/** Warn once per call site (model + pipeline shape) that an offset aggregate page may repeat or skip rows. */
+function warnIfSortNotTotal(model, pipeline, warnFn) {
+	if (pipelineSortIsTotal(pipeline)) return;
+	const site = `${model}:${JSON.stringify(pipeline.map((s) => s && typeof s === "object" ? Object.keys(s) : s))}:${JSON.stringify(pipeline.filter((s) => s && typeof s === "object" && "$sort" in s))}`;
+	if (warnedSortSites.has(site)) return;
+	warnedSortSites.add(site);
+	warnFn(`[mongokit] aggregatePipelinePaginate on '${model}': the page sort is not provably total, so rows that tie can repeat or be skipped across pages. End the \$sort on a key unique per output row, then pass \`sortIsTotal: true\` (or sort on _id with no \$unwind/\$group/_id rewrite before the sort).`);
+}
+//#endregion
 //#region src/pagination/utils/cursor.ts
 /**
 * Cursor Utilities
@@ -353,7 +471,7 @@ var cursor_exports = /* @__PURE__ */ __exportAll({
 * @param version - Cursor version for forward compatibility
 * @returns Base64-encoded cursor token
 */
-function encodeCursor(doc, primaryField, sort, version = 1, secret) {
+function encodeCursor(doc, primaryField, sort, version, scope, secret) {
 	const primaryValue = readSortValue(doc, primaryField);
 	const idValue = doc._id;
 	const sortFields = Object.keys(sort).filter((k) => k !== "_id");
@@ -371,6 +489,7 @@ function encodeCursor(doc, primaryField, sort, version = 1, secret) {
 		idType: getValueType(idValue),
 		sort,
 		ver: version,
+		fp: scope,
 		...sortFields.length > 1 && {
 			vals,
 			types
@@ -396,30 +515,30 @@ function encodeCursor(doc, primaryField, sort, version = 1, secret) {
 * @throws Error if token is invalid or malformed
 */
 function decodeCursor(token, secret) {
-	const verified = verifySignature(token, resolveCursorSecrets(secret));
-	let json;
+	let verified;
 	try {
-		json = Buffer.from(verified, "base64").toString("utf-8");
-	} catch {
-		throw new Error("Invalid cursor token: not valid base64");
+		verified = verifySignature(token, resolveCursorSecrets(secret));
+	} catch (err) {
+		throw invalidCursor(err instanceof Error ? err.message : "signature check failed");
 	}
 	let payload;
 	try {
-		payload = JSON.parse(json);
+		payload = JSON.parse(Buffer.from(verified, "base64").toString("utf-8"));
 	} catch {
-		throw new Error("Invalid cursor token: not valid JSON");
+		throw invalidCursor("not a cursor token");
 	}
-	if (!payload || typeof payload !== "object" || !("v" in payload) || !("t" in payload) || !("id" in payload) || !("idType" in payload) || !payload.sort || typeof payload.sort !== "object" || typeof payload.ver !== "number") throw new Error("Invalid cursor token: malformed payload structure");
+	if (!payload || typeof payload !== "object" || !("v" in payload) || !("t" in payload) || !("id" in payload) || !("idType" in payload) || !payload.sort || typeof payload.sort !== "object" || typeof payload.ver !== "number" || typeof payload.fp !== "string") throw invalidCursor("malformed payload");
 	const VALID_TYPES = [
 		"date",
 		"objectid",
+		"decimal",
 		"boolean",
 		"number",
 		"string",
 		"null",
 		"unknown"
 	];
-	if (!VALID_TYPES.includes(payload.t) || !VALID_TYPES.includes(payload.idType)) throw new Error("Invalid cursor token: unrecognized value type");
+	if (!VALID_TYPES.includes(payload.t) || !VALID_TYPES.includes(payload.idType)) throw invalidCursor("unrecognized value type");
 	try {
 		let values;
 		if (payload.vals && payload.types) {
@@ -431,10 +550,11 @@ function decodeCursor(token, secret) {
 			id: rehydrateValue(payload.id, payload.idType),
 			sort: payload.sort,
 			version: payload.ver,
+			scope: payload.fp,
 			...values && { values }
 		};
 	} catch {
-		throw new Error("Invalid cursor token: failed to rehydrate values");
+		throw invalidCursor("failed to rehydrate values");
 	}
 }
 /**
@@ -445,7 +565,7 @@ function decodeCursor(token, secret) {
 * @throws Error if sorts don't match
 */
 function validateCursorSort(cursorSort, currentSort) {
-	if (JSON.stringify(cursorSort) !== JSON.stringify(currentSort)) throw new Error("Cursor sort does not match current query sort");
+	if (JSON.stringify(cursorSort) !== JSON.stringify(currentSort)) throw invalidCursor("its sort does not match the query sort");
 }
 /**
 * Validates cursor version against the server's expected range.
@@ -458,8 +578,8 @@ function validateCursorSort(cursorSort, currentSort) {
 *   silently paginating from the wrong position.
 */
 function validateCursorVersion(cursorVersion, expectedVersion, minVersion = 1) {
-	if (cursorVersion > expectedVersion) throw new Error(`Cursor version ${cursorVersion} is newer than expected version ${expectedVersion}. Please upgrade.`);
-	if (cursorVersion < minVersion) throw new Error(`Cursor version ${cursorVersion} is older than minimum supported ${minVersion}. Pagination must restart.`);
+	if (cursorVersion > expectedVersion) throw invalidCursor(`version ${cursorVersion} is newer than expected version ${expectedVersion}`);
+	if (cursorVersion < minVersion) throw invalidCursor(`version ${cursorVersion} is older than minimum supported ${minVersion}; restart pagination`);
 }
 /**
 * Read a sort field off the last document of a page, following a dotted path.
@@ -481,6 +601,10 @@ function readSortValue(doc, field) {
 	}
 	return current;
 }
+/** A BSON Decimal128 from any driver copy (lean reads return the driver's own class). */
+function isDecimal(value) {
+	return value instanceof mongoose.Types.Decimal128 || typeof value === "object" && value !== null && value._bsontype === "Decimal128";
+}
 /**
 * Serializes a value for cursor storage
 */
@@ -488,6 +612,7 @@ function serializeValue(value) {
 	if (value === null || value === void 0) return null;
 	if (value instanceof Date) return value.toISOString();
 	if (value instanceof mongoose.Types.ObjectId) return value.toString();
+	if (isDecimal(value)) return value.toString();
 	return value;
 }
 /**
@@ -497,6 +622,7 @@ function getValueType(value) {
 	if (value === null || value === void 0) return "null";
 	if (value instanceof Date) return "date";
 	if (value instanceof mongoose.Types.ObjectId) return "objectid";
+	if (isDecimal(value)) return "decimal";
 	if (typeof value === "boolean") return "boolean";
 	if (typeof value === "number") return "number";
 	if (typeof value === "string") return "string";
@@ -510,38 +636,21 @@ function rehydrateValue(serialized, type) {
 	switch (type) {
 		case "date": return new Date(serialized);
 		case "objectid": return new mongoose.Types.ObjectId(serialized);
+		case "decimal": return mongoose.Types.Decimal128.fromString(serialized);
 		case "boolean": return serialized === true || serialized === "true";
 		case "number": return Number(serialized);
 		default: return serialized;
 	}
 }
 /**
-* Resolves cursor token into MongoDB query filters.
-* Shared by PaginationEngine.stream() and Repository.lookupPopulate() keyset path.
-*
-* Handles:
-* - Plain 24-char hex ObjectId strings (fallback cursor)
-* - Base64-encoded cursor tokens (standard cursor)
-* - Cursor version and sort validation
+* Resolve a cursor token into the keyset query filter. Shared by `PaginationEngine.stream()` and
+* `Repository.lookupPopulate()`. The token must carry the SAME scope fingerprint as this call
+* (`cursorScope`), else it is refused: a position is only meaningful within the collection,
+* filter and collation that produced it. Every refusal is a 400 with a closed code.
 */
-function resolveCursorFilter(after, sort, cursorVersion, baseFilters = {}, minCursorVersion = 1, buildSort = sort, secret) {
-	const secrets = resolveCursorSecrets(secret);
-	if (/^[a-f0-9]{24}$/i.test(after)) {
-		/**
-		* The bare-ObjectId fallback is an UNSIGNED position by construction, so a
-		* deployment that signs must refuse it — otherwise the signature
-		* requirement ships with a documented bypass: send a raw id instead of a
-		* token and skip verification entirely.
-		*/
-		if (signingRequired(secrets)) throw new Error("Invalid cursor token: this deployment signs cursors, so a bare ObjectId is not accepted as one");
-		const objectId = new mongoose.Types.ObjectId(after);
-		const idOperator = (buildSort._id || -1) === 1 ? "$gt" : "$lt";
-		return {
-			...baseFilters,
-			_id: { [idOperator]: objectId }
-		};
-	}
+function resolveCursorFilter(after, sort, cursorVersion, baseFilters, minCursorVersion, buildSort, scope, secret) {
 	const cursor = decodeCursor(after, secret);
+	if (cursor.scope !== scope) throw cursorScopeMismatch();
 	validateCursorVersion(cursor.version, cursorVersion, minCursorVersion);
 	validateCursorSort(cursor.sort, sort);
 	return buildKeysetFilter(baseFilters, buildSort, cursor.value, cursor.id, cursor.values);
@@ -776,6 +885,30 @@ function getPrimaryField(sort) {
 //#endregion
 //#region src/pagination/PaginationEngine.ts
 /**
+* Pagination Engine
+*
+* Production-grade pagination for MongoDB with support for:
+* - Offset pagination (page-based) - Best for small datasets, random page access
+* - Keyset pagination (cursor-based) - Best for large datasets, infinite scroll
+* - Aggregate pagination - Best for complex queries requiring aggregation
+*
+* @example
+* ```typescript
+* const engine = new PaginationEngine(UserModel, {
+*   defaultLimit: 20,
+*   maxLimit: 100,
+*   useEstimatedCount: true
+* });
+*
+* // Offset pagination
+* const page1 = await engine.paginate({ page: 1, limit: 20 });
+*
+* // Keyset pagination (better for large datasets)
+* const stream1 = await engine.stream({ sort: { createdAt: -1 }, limit: 20 });
+* const stream2 = await engine.stream({ sort: { createdAt: -1 }, after: stream1.next });
+* ```
+*/
+/**
 * The sort fields a reader cares about, for MESSAGES only — never for deciding
 * whether an index is adequate.
 *
@@ -833,10 +966,6 @@ const DEFAULT_COUNT_LIMIT = 1e4;
 function resolveCountLimit(value) {
 	return Number.isInteger(value) && value > 0 ? value : DEFAULT_COUNT_LIMIT;
 }
-/**
-* Production-grade pagination engine for MongoDB
-* Supports offset, keyset (cursor), and aggregate pagination
-*/
 var PaginationEngine = class {
 	Model;
 	config;
@@ -851,6 +980,23 @@ var PaginationEngine = class {
 	* @param Model - Mongoose model to paginate
 	* @param config - Pagination configuration
 	*/
+	/** Memoised capped counts for `countStrategy: 'cached'`, rebuilt when the TTL changes. */
+	_memo;
+	/** The `cached` count memo (repo-core `createTtlMemo`: single flight, a failed count caches nothing). */
+	_countMemo() {
+		const ttl = this.config.countCacheTtlMs;
+		if (!this._memo || this._memo.ttl !== ttl) this._memo = {
+			ttl,
+			memo: createTtlMemo(async (k) => ({
+				total: await k.run(),
+				countedAt: /* @__PURE__ */ new Date()
+			}), {
+				ttlMs: ttl,
+				keyOf: (k) => k.key
+			})
+		};
+		return this._memo.memo;
+	}
 	constructor(Model, config = {}) {
 		this.Model = Model;
 		/**
@@ -897,75 +1043,67 @@ var PaginationEngine = class {
 	* console.log(result.data, result.total, result.hasNext);
 	*/
 	async paginate(options = {}) {
-		const { filters = {}, sort, countFilters, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, countStrategy = this.config.defaultCountStrategy, countLimit = this.config.defaultCountLimit, readPreference, collation } = options;
+		const { filters = {}, sort, countFilters, page = 1, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, countStrategy = this.config.defaultCountStrategy, countLimit = this.config.defaultCountLimit, collation } = options;
+		const qo = options.queryOptions ?? resolveQueryOptions("read", options);
 		const sanitizedPage = validatePage(page, this.config);
 		const sanitizedLimit = validateLimit(limit, this.config);
 		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-		/**
-		* Fetch limit+1 whenever the count cannot answer `hasNext`.
-		*
-		* `none` never counts. `capped` counts only to the ceiling, so once `total`
-		* sits AT the ceiling it no longer knows whether a further page exists —
-		* deriving `hasNext` from `page < pages` there reports "no more results" in
-		* the middle of a collection, which is a wrong answer that looks like a
-		* right one. One extra document is the whole cost of avoiding it.
-		*/
-		const countBounded = countStrategy === "none" || countStrategy === "capped";
-		const fetchLimit = countBounded ? sanitizedLimit + 1 : sanitizedLimit;
-		let query = this.Model.find(filters);
+		assertOffsetWithinCap(skip, this.config.maxOffset);
+		let query = this.Model.find(filters).lean(lean);
 		if (select) query = query.select(select);
 		if (populate && (Array.isArray(populate) ? populate.length : populate)) query = query.populate(populate);
-		if (sort) query = query.sort(sort);
-		query = query.skip(skip).limit(fetchLimit).lean(lean);
+		if (sort) query = query.sort(withIdTiebreak(sort));
+		query = query.skip(skip).limit(sanitizedLimit + 1);
 		if (collation) query = query.collation(collation);
 		if (session) query = query.session(session);
 		if (hint) query = query.hint(hint);
-		if (maxTimeMS) query = query.maxTimeMS(maxTimeMS);
-		if (readPreference) query = query.read(readPreference);
-		const hasFilters = Object.keys(filters).length > 0;
-		const useEstimated = this.config.useEstimatedCount && !hasFilters;
+		applyToQuery(query, qo);
+		const countTarget = countFilters ?? filters;
+		const hasFilters = Object.keys(countTarget).length > 0;
+		const ceiling = resolveCountLimit(countLimit);
+		const countQuery = (bounded) => {
+			const q = this.Model.countDocuments(countTarget).session(session ?? null);
+			if (bounded) q.limit(ceiling);
+			if (collation) q.collation(collation);
+			if (hint) q.hint(hint);
+			applyToQuery(q, qo);
+			return q.exec();
+		};
 		let runCount;
-		if ((countStrategy === "estimated" || useEstimated) && !hasFilters && !session) runCount = () => Promise.resolve(this.Model.estimatedDocumentCount());
-		else if (countStrategy === "none") runCount = () => Promise.resolve(0);
-		else if (countStrategy === "capped") {
-			/**
-			* `.limit(n)` on a count is MongoDB's own ceiling — the server stops
-			* scanning at n and returns n, so the work is O(n) rather than O(matching
-			* rows). Below the ceiling it returns the exact figure, so a small
-			* collection is unaffected by the strategy being on.
-			*/
-			const cappedTarget = countFilters ?? filters;
-			const cappedQuery = this.Model.countDocuments(cappedTarget).limit(resolveCountLimit(countLimit)).session(session ?? null);
-			if (collation) cappedQuery.collation(collation);
-			if (hint) cappedQuery.hint(hint);
-			if (maxTimeMS) cappedQuery.maxTimeMS(maxTimeMS);
-			if (readPreference) cappedQuery.read(readPreference);
-			runCount = () => cappedQuery.exec();
-		} else {
-			const countTarget = countFilters ?? filters;
-			const countQuery = this.Model.countDocuments(countTarget).session(session ?? null);
-			if (collation) countQuery.collation(collation);
-			if (hint) countQuery.hint(hint);
-			if (maxTimeMS) countQuery.maxTimeMS(maxTimeMS);
-			if (readPreference) countQuery.read(readPreference);
-			runCount = () => countQuery.exec();
-		}
-		const [data, total] = session ? [await query.exec(), await runCount()] : await Promise.all([query.exec(), runCount()]);
+		const at = (total, totalIsEstimate) => ({
+			total,
+			totalIsEstimate,
+			countedAt: /* @__PURE__ */ new Date()
+		});
+		if ((countStrategy === "estimated" || this.config.useEstimatedCount) && !hasFilters && !session) runCount = async () => at(await this.Model.estimatedDocumentCount(), true);
+		else if (countStrategy === "none") runCount = async () => ({
+			total: 0,
+			totalIsEstimate: true,
+			countedAt: null
+		});
+		else if (countStrategy === "capped" || countStrategy === "cached" && session) runCount = async () => {
+			const total = await countQuery(true);
+			return at(total, total >= ceiling);
+		};
+		else if (countStrategy === "cached") {
+			const key = cursorScope(this.Model.collection.collectionName, [
+				countTarget,
+				ceiling,
+				hint ?? null
+			], collation);
+			runCount = async () => ({
+				...await this._countMemo().get({
+					key,
+					run: () => countQuery(true)
+				}),
+				totalIsEstimate: true
+			});
+		} else runCount = async () => at(await countQuery(false), false);
+		const [data, counted] = session ? [await query.exec(), await runCount()] : await Promise.all([query.exec(), runCount()]);
+		const { total, totalIsEstimate, countedAt } = counted;
 		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
-		/**
-		* A capped count that came back AT its ceiling is a floor, not a total.
-		*
-		* Reported rather than inferred: `total === countLimit` is also what a
-		* collection of exactly that size legitimately returns, so a consumer
-		* cannot tell the two apart, and one that guesses renders `10,000+` over an
-		* exact 10,000 forever.
-		*/
-		const totalIsLowerBound = countStrategy === "capped" && total >= resolveCountLimit(countLimit);
-		let hasNext;
-		if (countBounded) {
-			hasNext = data.length > sanitizedLimit;
-			if (hasNext) data.pop();
-		} else hasNext = sanitizedPage < totalPages;
+		const hasNext = data.length > sanitizedLimit;
+		if (hasNext) data.pop();
 		/**
 		* A CLAMPED limit is reported, not swallowed.
 		*
@@ -996,7 +1134,8 @@ var PaginationEngine = class {
 			pages: totalPages,
 			hasNext,
 			hasPrev: sanitizedPage > 1,
-			...totalIsLowerBound && { totalIsLowerBound },
+			totalIsEstimate,
+			countedAt,
 			...warning && { warning }
 		};
 	}
@@ -1033,7 +1172,8 @@ var PaginationEngine = class {
 	* });
 	*/
 	async stream(options) {
-		const { filters = {}, sort, after, before, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, readPreference, collation } = options;
+		const { filters = {}, sort, after, before, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, collation } = options;
+		const qo = options.queryOptions ?? resolveQueryOptions("read", options);
 		if (!sort) throw createError(400, "sort is required for keyset pagination");
 		if (after && before) throw createError(400, "Pass `after` or `before`, not both");
 		const sanitizedLimit = validateLimit(limit, this.config);
@@ -1063,17 +1203,17 @@ var PaginationEngine = class {
 		const querySort = backward ? invertSort(normalizedSort) : normalizedSort;
 		const cursor = backward ? before : after;
 		let query = { ...filters };
-		if (cursor) query = resolveCursorFilter(cursor, normalizedSort, this.config.cursorVersion, query, this.config.minCursorVersion, querySort, this.config.cursorSecret);
+		const scope = cursorScope(this.Model.collection.collectionName, filters, collation);
+		if (cursor) query = resolveCursorFilter(cursor, normalizedSort, this.config.cursorVersion, query, this.config.minCursorVersion, querySort, scope, this.config.cursorSecret);
 		const effectiveSelect = ensureKeysetSelectIncludesCursorFields(select, normalizedSort);
-		let mongoQuery = this.Model.find(query);
+		let mongoQuery = this.Model.find(query).lean(lean);
 		if (effectiveSelect) mongoQuery = mongoQuery.select(effectiveSelect);
 		if (populate && (Array.isArray(populate) ? populate.length : populate)) mongoQuery = mongoQuery.populate(populate);
-		mongoQuery = mongoQuery.sort(querySort).limit(sanitizedLimit + 1).lean(lean);
+		mongoQuery = mongoQuery.sort(querySort).limit(sanitizedLimit + 1);
 		if (collation) mongoQuery = mongoQuery.collation(collation);
 		if (session) mongoQuery = mongoQuery.session(session);
 		if (hint) mongoQuery = mongoQuery.hint(hint);
-		if (maxTimeMS) mongoQuery = mongoQuery.maxTimeMS(maxTimeMS);
-		if (readPreference) mongoQuery = mongoQuery.read(readPreference);
+		applyToQuery(mongoQuery, qo);
 		const data = await mongoQuery.exec();
 		const moreThatWay = data.length > sanitizedLimit;
 		if (moreThatWay) data.pop();
@@ -1089,7 +1229,7 @@ var PaginationEngine = class {
 		const hasMore = backward ? true : moreThatWay;
 		const hasPrev = backward ? moreThatWay : Boolean(after);
 		const primaryField = getPrimaryField(normalizedSort);
-		const mint = (doc) => doc ? encodeCursor(doc, primaryField, normalizedSort, this.config.cursorVersion, this.config.cursorSecret) : null;
+		const mint = (doc) => doc ? encodeCursor(doc, primaryField, normalizedSort, this.config.cursorVersion, scope, this.config.cursorSecret) : null;
 		return {
 			method: "keyset",
 			data,
@@ -1133,20 +1273,18 @@ var PaginationEngine = class {
 	* });
 	*/
 	async aggregatePaginate(options = {}) {
-		const { pipeline = [], page = 1, limit = this.config.defaultLimit, session, hint, maxTimeMS, countStrategy = this.config.defaultCountStrategy, countLimit = this.config.defaultCountLimit, readPreference, allowDiskUse } = options;
+		const { pipeline = [], page = 1, limit = this.config.defaultLimit, session, countStrategy = this.config.defaultCountStrategy, countLimit = this.config.defaultCountLimit } = options;
+		const qo = options.queryOptions ?? resolveQueryOptions("aggregate", options);
+		if (!options.sortIsTotal) warnIfSortNotTotal(this.Model.modelName, pipeline, warn);
 		const sanitizedPage = validatePage(page, this.config);
 		const sanitizedLimit = validateLimit(limit, this.config);
 		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-		const countBounded = countStrategy === "none" || countStrategy === "capped";
-		const fetchLimit = countBounded ? sanitizedLimit + 1 : sanitizedLimit;
+		assertOffsetWithinCap(skip, this.config.maxOffset);
 		/** Every execution option both pipelines must carry identically. */
 		const run = (stages) => {
 			const aggregation = this.Model.aggregate(stages);
 			if (session) aggregation.session(session);
-			if (hint) aggregation.hint(hint);
-			if (maxTimeMS) aggregation.option({ maxTimeMS });
-			if (readPreference) aggregation.read(readPreference);
-			if (allowDiskUse) aggregation.allowDiskUse(true);
+			applyToAggregate(aggregation, qo);
 			return aggregation.exec();
 		};
 		/**
@@ -1158,27 +1296,47 @@ var PaginationEngine = class {
 		* collection metadata and cannot see a pipeline), so it stays exact here —
 		* documented on `AggregatePaginationOptions.countStrategy`.
 		*/
-		const countStages = countStrategy === "capped" ? [
+		const ceiling = resolveCountLimit(countLimit);
+		const bounded = countStrategy === "capped" || countStrategy === "cached";
+		const countStages = bounded ? [
 			...pipeline,
-			{ $limit: resolveCountLimit(countLimit) },
+			{ $limit: ceiling },
 			{ $count: "count" }
 		] : [...pipeline, { $count: "count" }];
+		const countOnce = async () => (await run(countStages))[0]?.count ?? 0;
 		const runData = () => run([
 			...pipeline,
 			{ $skip: skip },
-			{ $limit: fetchLimit }
+			{ $limit: sanitizedLimit + 1 }
 		]);
-		const runCount = () => countStrategy === "none" ? Promise.resolve([]) : run(countStages);
-		const [dataRows, countRows] = session ? [await runData(), await runCount()] : await Promise.all([runData(), runCount()]);
-		const data = dataRows;
-		const total = countRows[0]?.count || 0;
+		const runCount = async () => {
+			if (countStrategy === "none") return {
+				total: 0,
+				totalIsEstimate: true,
+				countedAt: null
+			};
+			if (countStrategy === "cached" && !session) {
+				const key = cursorScope(this.Model.collection.collectionName, [pipeline, ceiling], null);
+				return {
+					...await this._countMemo().get({
+						key,
+						run: countOnce
+					}),
+					totalIsEstimate: true
+				};
+			}
+			const total = await countOnce();
+			return {
+				total,
+				totalIsEstimate: bounded && total >= ceiling,
+				countedAt: /* @__PURE__ */ new Date()
+			};
+		};
+		const [data, counted] = session ? [await runData(), await runCount()] : await Promise.all([runData(), runCount()]);
+		const { total, totalIsEstimate, countedAt } = counted;
 		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
-		const totalIsLowerBound = countStrategy === "capped" && total >= resolveCountLimit(countLimit);
-		let hasNext;
-		if (countBounded) {
-			hasNext = data.length > sanitizedLimit;
-			if (hasNext) data.pop();
-		} else hasNext = sanitizedPage < totalPages;
+		const hasNext = data.length > sanitizedLimit;
+		if (hasNext) data.pop();
 		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination in aggregate (page ${sanitizedPage}). Uses $skip internally.` : void 0;
 		return {
 			method: "aggregate",
@@ -1189,10 +1347,11 @@ var PaginationEngine = class {
 			pages: totalPages,
 			hasNext,
 			hasPrev: sanitizedPage > 1,
-			...totalIsLowerBound && { totalIsLowerBound },
+			totalIsEstimate,
+			countedAt,
 			...warning && { warning }
 		};
 	}
 };
 //#endregion
-export { getPaginationDefaults as a, resolveCursorSecrets as c, configurePaginationDefaults as i, verifySignature as l, sort_exports as n, resetPaginationDefaults as o, cursor_exports as r, attachSignature as s, PaginationEngine as t };
+export { resolveCursorSecrets as _, cursor_exports as a, PAGINATION_ERROR_CODES as c, withGroupTiebreak as d, withIdTiebreak as f, attachSignature as g, resetPaginationDefaults as h, validateKeysetSort as i, assertOffsetWithinCap as l, getPaginationDefaults as m, getPrimaryField as n, encodeCursor as o, configurePaginationDefaults as p, sort_exports as r, resolveCursorFilter as s, PaginationEngine as t, cursorScope as u, verifySignature as v };