@classytic/mongokit 3.38.1 → 3.40.0

package/dist/PaginationEngine-Dvl8jcRY.mjs

@@ -0,0 +1,1198 @@
+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 { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./pagination/utils/limits.mjs";
+import mongoose from "mongoose";
+import { createHmac, timingSafeEqual } from "node:crypto";
+//#region src/pagination/utils/cursor-signing.ts
+/**
+* HMAC signing for pagination cursors.
+*
+* ## What this protects, and what it does not
+*
+* A cursor is a POSITION, and the server's own filters decide what a caller may
+* read — so a stolen or shared cursor cannot reach another tenant's rows, and
+* signing is not a substitute for scoping. What an unsigned cursor gives away
+* is the ability to MOVE the position: edit the encoded sort value, re-submit,
+* and the response says whether any row sorts past it. Repeat, and that is a
+* binary search over a column the caller can never read directly — "where do
+* salaries above X start", against a list that only ever showed them names.
+*
+* Signing closes that. It does NOT hide the cursor's contents: the payload is
+* still base64url JSON and still readable by anyone holding the token, field
+* names included. **Signing is integrity, not confidentiality.** A deployment
+* that must not reveal which column it sorts by needs encryption, which this is
+* not.
+*
+* ## The rules that make it worth having
+*
+* - **A configured secret makes a signature REQUIRED.** Accepting an unsigned
+*   token "for compatibility" means an attacker strips the signature and the
+*   protection evaporates while still looking enabled — the exact shape of a
+*   specific instruction defeated by a general default.
+* - **An unusable secret THROWS.** `cursorSecret: ''` (an unset env var read
+*   without a check) would otherwise mean "signing on, key guessable", and
+*   nothing would say so.
+* - **Comparison is timing-safe.** `===` on a signature leaks it byte by byte
+*   to anyone willing to time the responses.
+* - **Rotation takes a list.** Sign with the first, accept any — otherwise
+*   changing the key invalidates every cursor a client is holding.
+*/
+/**
+* Separator between payload and signature.
+*
+* `.` is not in the base64url alphabet, so it cannot appear inside either half
+* — the split is unambiguous without escaping, and the whole token stays
+* URL-safe.
+*/
+const SEPARATOR = ".";
+/**
+* A key shorter than this is not a key. Chosen to match the HMAC-SHA256 block
+* consideration loosely, but the real point is to reject `''`, `'secret'` and
+* `'changeme'` — the values that appear when an env var was never set.
+*/
+const MIN_SECRET_LENGTH = 16;
+/**
+* Normalise a configured secret into the keys that sign and verify.
+*
+* Throws rather than falling back: every failure mode here — an empty string, a
+* list of empty strings, a two-character placeholder — describes a deployment
+* that BELIEVES it is signing cursors. Returning "unsigned" quietly is how it
+* would keep believing that.
+*/
+function resolveCursorSecrets(secret) {
+	if (secret === void 0 || secret === null) return void 0;
+	const keys = (Array.isArray(secret) ? secret : [secret]).map((k) => String(k ?? ""));
+	if (keys.length === 0) throw new Error("cursorSecret: an empty list cannot sign anything — omit it, or supply a key");
+	const tooShort = keys.find((k) => k.trim().length < MIN_SECRET_LENGTH);
+	if (tooShort !== void 0) throw new Error(`cursorSecret: every key must be at least ${MIN_SECRET_LENGTH} characters (got one of length ${tooShort.trim().length}). An unset environment variable reads as an empty string, which would sign every cursor with a key anyone can guess.`);
+	return keys;
+}
+/** The raw HMAC of a payload under one key, base64url. */
+function sign(payload, key) {
+	return createHmac("sha256", key).update(payload, "utf8").digest("base64url");
+}
+/**
+* Append a signature to an encoded payload.
+*
+* Returns the payload unchanged when no secret is configured, so a deployment
+* that does not sign is byte-for-byte unaffected.
+*/
+function attachSignature(payload, secrets) {
+	if (!secrets) return payload;
+	return payload + SEPARATOR + sign(payload, secrets[0]);
+}
+/** Split a token into its payload and signature halves. */
+function split(token) {
+	const at = token.lastIndexOf(SEPARATOR);
+	if (at === -1) return {
+		payload: token,
+		signature: void 0
+	};
+	return {
+		payload: token.slice(0, at),
+		signature: token.slice(at + 1)
+	};
+}
+/** Constant-time equality. `timingSafeEqual` throws on a length mismatch, which is itself a leak-free "no". */
+function matches(a, b) {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	if (left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+}
+/**
+* Verify a token and return the payload to decode.
+*
+* - **No secret configured** → any signature present is stripped and ignored.
+*   Turning signing off must not reject the tokens issued while it was on, or
+*   a rollback breaks every client mid-page.
+* - **Secret configured** → a valid signature is mandatory. A missing one and a
+*   wrong one are reported differently ON PURPOSE: they mean different things to
+*   whoever is debugging (a config mismatch versus a rotated key or a tampered
+*   token), and neither message helps anyone forge one.
+*/
+function verifySignature(token, secrets) {
+	const { payload, signature } = split(token);
+	if (!secrets) return payload;
+	if (signature === void 0) throw new Error("Invalid cursor token: this deployment signs cursors and this one carries no signature");
+	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
+/**
+* The policy lives on `globalThis` under a registered symbol, NOT in a module
+* `let`.
+*
+* A module-level binding is per MODULE INSTANCE, and this package can appear
+* twice in one dependency graph — an engine pinning `^3.38` beside a host on
+* `^3.39`, a pnpm layout that duplicates on a peer, an ESM/CJS dual load. The
+* host would call `configurePaginationDefaults` on its copy while the
+* repositories an engine built read the other copy's empty object, and the
+* feature would silently do nothing in EXACTLY the composition it exists for:
+* a host that does not construct its own repositories.
+*
+* `Symbol.for` is the same mechanism, for the same reason, as arc's
+* `Symbol.for('arc.runtimeCapabilities')` / `ARC_EVENT_TRANSPORT`.
+*
+* Per realm, not per process: a `worker_threads` worker has its own
+* `globalThis`, so each worker configures itself at its own boot.
+*/
+const POLICY_SLOT = Symbol.for("classytic.mongokit.paginationDefaults");
+function policy() {
+	const holder = globalThis;
+	holder[POLICY_SLOT] ??= {};
+	return holder[POLICY_SLOT];
+}
+/**
+* Set the deployment's pagination policy. Merges into whatever is already set,
+* so two call sites configuring different keys do not clobber each other.
+*
+* Call it at boot, before composing modules. Ordering is not load-bearing —
+* repositories read this at query time, not construction time — but a call
+* made after traffic starts changes behaviour mid-flight, which is rarely what
+* anyone means.
+*/
+function configurePaginationDefaults(defaults) {
+	Object.assign(policy(), stripUndefined(defaults));
+}
+/**
+* The current deployment policy. Empty until something configures it.
+*
+* A COPY — `Readonly<T>` is erased at runtime, and handing out the live object
+* would let a caller mutate the policy through a getter that promised not to.
+*/
+function getPaginationDefaults() {
+	return { ...policy() };
+}
+/** Back to library defaults. For tests — a global that cannot be reset is a leak between them. */
+function resetPaginationDefaults() {
+	const current = policy();
+	for (const key of Object.keys(current)) delete current[key];
+}
+/**
+* An explicitly-passed `undefined` means "not specified", not "unset the
+* deployment policy" — `{ defaultMode: undefined }` built from an optional
+* host env var must not silently clear what another call configured.
+*/
+function stripUndefined(input) {
+	const out = {};
+	if (input.defaultCountStrategy !== void 0) out.defaultCountStrategy = input.defaultCountStrategy;
+	if (input.defaultCountLimit !== void 0) out.defaultCountLimit = input.defaultCountLimit;
+	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;
+	return out;
+}
+/**
+* Resolve one repository's config against the deployment policy.
+*
+* Returns an object whose policy keys are GETTERS, so a repository constructed
+* before `configurePaginationDefaults` still answers with the policy — and a
+* test that resets the policy does not have to rebuild its repositories. Keys
+* the repository set explicitly are plain values and never consult the policy.
+*/
+function bindPaginationDefaults(resolved, config) {
+	define(resolved, "defaultCountStrategy", config.defaultCountStrategy, "exact");
+	define(resolved, "defaultCountLimit", config.defaultCountLimit, 1e4);
+	define(resolved, "cursorSecret", config.cursorSecret, void 0);
+	define(resolved, "defaultMode", config.defaultMode, void 0);
+	define(resolved, "maxPage", config.maxPage, 1e4);
+	return resolved;
+}
+function define(target, key, explicit, fallback) {
+	Object.defineProperty(target, key, {
+		enumerable: true,
+		configurable: true,
+		get: () => explicit !== void 0 ? explicit : policy()[key] ?? fallback
+	});
+}
+//#endregion
+//#region src/pagination/utils/filter.ts
+/**
+* Combine the caller's filters with the keyset position predicate.
+*
+* NEVER by spreading. `{ ...baseFilters, $or: position }` REPLACES a caller's own
+* `$or`, and `{ ...baseFilters, _id: { $lt } }` replaces a caller's `_id: { $in }` —
+* so page 1 honoured the filter and page 2 silently widened past it. Nothing threw;
+* the second page simply had rows the first page's filter excluded.
+*
+* `$and` composes without collision whatever keys either side uses. The spread is
+* kept only when no key is shared, because a flat filter is what every existing
+* test, index hint and explain plan was written against.
+*/
+function combine(baseFilters, position) {
+	if (!Object.keys(position).some((key) => key in baseFilters)) return {
+		...baseFilters,
+		...position
+	};
+	return { $and: [baseFilters, position] };
+}
+/**
+* The "strictly after this value" predicates for ONE field of the cascade,
+* with the null boundary handled on BOTH sides rather than emitted.
+*
+* BSON orders `null` (and a missing field, which sorts with it) below every
+* typed value, and `$gt`/`$lt` never cross that line: `{ $lt: 0 }` does not
+* match null, `{ $gt: null }` matches nothing. So a walk that reached the
+* boundary simply ended — `hasMore: false`, every null-valued row unread, and
+* no error. Four positions, four answers:
+*
+*   asc,  typed v → `{ $gt: v }`            nulls sorted BEFORE v; already passed
+*   asc,  null    → `{ $ne: null }`         every typed value comes after null
+*   desc, typed v → `{ $lt: v }` OR `null`  nulls sort AFTER every typed value
+*   desc, null    → nothing                 nulls are last; nothing follows
+*
+* A position can therefore need two branches (desc, typed) or none (desc,
+* null), which is why this returns a list and the cascade emits one `$or`
+* branch per entry. `{ field: null }` matches null AND missing — exactly the
+* set that sorts at that position.
+*/
+function afterValue(operator, value) {
+	const isNull = value === null || value === void 0;
+	if (operator === "$gt") return isNull ? [{ $ne: null }] : [{ $gt: value }];
+	return isNull ? [] : [{ $lt: value }, null];
+}
+/**
+* Builds MongoDB filter for keyset pagination
+* Creates compound $or condition for proper cursor-based filtering
+*
+* Every field takes the operator from ITS OWN direction, so a mixed-direction
+* sort (`{ priority: 1, createdAt: -1 }`, the ESR-shaped index) paginates
+* correctly: "after (p, t)" is `p > p0 OR (p = p0 AND t < t0) OR (p = p0 AND
+* t = t0 AND _id < id0)`. The cascade is the tuple comparison; the directions
+* are per position in the tuple.
+*
+* @param baseFilters - Existing query filters
+* @param sort - Normalized sort specification (validated; `_id` present)
+* @param cursorValue - Primary field value from cursor
+* @param cursorId - _id value from cursor
+* @returns MongoDB filter with keyset condition
+*
+* @example
+* buildKeysetFilter(
+*   { status: 'active' },
+*   { createdAt: -1, _id: -1 },
+*   new Date('2024-01-01'),
+*   new ObjectId('...')
+* )
+* // Returns:
+* // {
+* //   status: 'active',
+* //   $or: [
+* //     { createdAt: { $lt: Date('2024-01-01') } },
+* //     { createdAt: Date('2024-01-01'), _id: { $lt: ObjectId('...') } }
+* //   ]
+* // }
+*/
+function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId, cursorValues) {
+	const sortFields = Object.keys(sort).filter((k) => k !== "_id");
+	const idOperator = (sort._id ?? sort[sortFields[0]] ?? -1) === 1 ? "$gt" : "$lt";
+	if (sortFields.length <= 1 && !cursorValues) {
+		const primaryField = sortFields[0] || "_id";
+		if (primaryField === "_id") return combine(baseFilters, { _id: { [idOperator]: cursorId } });
+		const ranges = afterValue(sort[primaryField] === 1 ? "$gt" : "$lt", cursorValue).map((r) => ({ [primaryField]: r }));
+		const tie = {
+			[primaryField]: cursorValue ?? null,
+			_id: { [idOperator]: cursorId }
+		};
+		return combine(baseFilters, ranges.length ? { $or: [...ranges, tie] } : tie);
+	}
+	const values = cursorValues || { [sortFields[0]]: cursorValue };
+	const allFields = [...sortFields, "_id"];
+	const allValues = {
+		...values,
+		_id: cursorId
+	};
+	const orConditions = [];
+	for (let i = 0; i < allFields.length; i++) {
+		const field = allFields[i];
+		const operator = field === "_id" ? idOperator : sort[field] === 1 ? "$gt" : "$lt";
+		const prefix = {};
+		for (let j = 0; j < i; j++) prefix[allFields[j]] = allValues[allFields[j]] ?? null;
+		const ranges = field === "_id" ? [{ [idOperator]: cursorId }] : afterValue(operator, allValues[field]);
+		for (const range of ranges) orConditions.push({
+			...prefix,
+			[field]: range
+		});
+	}
+	if (orConditions.length === 0) return combine(baseFilters, { _id: { $in: [] } });
+	return combine(baseFilters, { $or: orConditions });
+}
+//#endregion
+//#region src/pagination/utils/cursor.ts
+/**
+* Cursor Utilities
+*
+* Encoding and decoding of cursor tokens for keyset pagination.
+* Cursors are base64-encoded JSON containing position data and metadata.
+*/
+var cursor_exports = /* @__PURE__ */ __exportAll({
+	decodeCursor: () => decodeCursor,
+	encodeCursor: () => encodeCursor,
+	readSortValue: () => readSortValue,
+	resolveCursorFilter: () => resolveCursorFilter,
+	validateCursorSort: () => validateCursorSort,
+	validateCursorVersion: () => validateCursorVersion
+});
+/**
+* Encodes document values and sort metadata into a base64 cursor token
+*
+* @param doc - Document to extract cursor values from
+* @param primaryField - Primary sort field name
+* @param sort - Normalized sort specification
+* @param version - Cursor version for forward compatibility
+* @returns Base64-encoded cursor token
+*/
+function encodeCursor(doc, primaryField, sort, version = 1, secret) {
+	const primaryValue = readSortValue(doc, primaryField);
+	const idValue = doc._id;
+	const sortFields = Object.keys(sort).filter((k) => k !== "_id");
+	const vals = {};
+	const types = {};
+	for (const field of sortFields) {
+		const value = readSortValue(doc, field);
+		vals[field] = serializeValue(value);
+		types[field] = getValueType(value);
+	}
+	const payload = {
+		v: serializeValue(primaryValue),
+		t: getValueType(primaryValue),
+		id: serializeValue(idValue),
+		idType: getValueType(idValue),
+		sort,
+		ver: version,
+		...sortFields.length > 1 && {
+			vals,
+			types
+		}
+	};
+	/**
+	* `base64url`, not `base64`: a cursor rides in `?after=`, and standard base64
+	* puts `+` in it — which a query-string parser reads as a SPACE, so the token
+	* fails to decode unless every client remembers to percent-encode it. The
+	* URL-safe alphabet (`-` `_`, no padding) survives the round trip as-is, and
+	* matches what `@classytic/repo-core`'s codec emits.
+	*
+	* Decoding accepts BOTH alphabets (Node's decoder does), so a token issued
+	* before this change keeps working.
+	*/
+	return attachSignature(Buffer.from(JSON.stringify(payload)).toString("base64url"), resolveCursorSecrets(secret));
+}
+/**
+* Decodes a cursor token back into document values and sort metadata
+*
+* @param token - Base64-encoded cursor token
+* @returns Decoded cursor data
+* @throws Error if token is invalid or malformed
+*/
+function decodeCursor(token, secret) {
+	const verified = verifySignature(token, resolveCursorSecrets(secret));
+	let json;
+	try {
+		json = Buffer.from(verified, "base64").toString("utf-8");
+	} catch {
+		throw new Error("Invalid cursor token: not valid base64");
+	}
+	let payload;
+	try {
+		payload = JSON.parse(json);
+	} catch {
+		throw new Error("Invalid cursor token: not valid JSON");
+	}
+	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");
+	const VALID_TYPES = [
+		"date",
+		"objectid",
+		"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");
+	try {
+		let values;
+		if (payload.vals && payload.types) {
+			values = {};
+			for (const [field, serialized] of Object.entries(payload.vals)) values[field] = rehydrateValue(serialized, payload.types[field]);
+		}
+		return {
+			value: rehydrateValue(payload.v, payload.t),
+			id: rehydrateValue(payload.id, payload.idType),
+			sort: payload.sort,
+			version: payload.ver,
+			...values && { values }
+		};
+	} catch {
+		throw new Error("Invalid cursor token: failed to rehydrate values");
+	}
+}
+/**
+* Validates that cursor sort matches current query sort
+*
+* @param cursorSort - Sort specification from cursor
+* @param currentSort - Sort specification from query
+* @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");
+}
+/**
+* Validates cursor version against the server's expected range.
+*
+* - Cursors newer than `expectedVersion` are rejected (client ahead of server).
+* - Cursors older than `minVersion` are rejected (client cached a cursor from
+*   a pre-breaking-change deploy). Default `minVersion = 1` keeps the legacy
+*   "accept anything <= expected" behavior; bump it when you ship a breaking
+*   cursor format change so old clients restart pagination cleanly instead of
+*   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.`);
+}
+/**
+* Read a sort field off the last document of a page, following a dotted path.
+*
+* A sort key is a Mongo PATH (`metadata.progressPct`), and the query side has always
+* treated it as one: `buildKeysetFilter` emits `{ 'metadata.progressPct': { $lt } }`,
+* which Mongo resolves into the subdocument. The encode side read `doc[field]`, a
+* property named with a literal dot, which no document has. So a keyset sort on any
+* nested field encoded `v: null`, and page two came back through the null branch of
+* the filter: only rows whose sort field IS null, silently, with no error. Exported
+* for the unit test; not part of the public surface.
+*/
+function readSortValue(doc, field) {
+	if (!field.includes(".")) return doc[field];
+	let current = doc;
+	for (const segment of field.split(".")) {
+		if (current === null || typeof current !== "object") return void 0;
+		current = current[segment];
+	}
+	return current;
+}
+/**
+* Serializes a value for cursor storage
+*/
+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();
+	return value;
+}
+/**
+* Gets the type identifier for a value
+*/
+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 (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	if (typeof value === "string") return "string";
+	return "unknown";
+}
+/**
+* Rehydrates a serialized value back to its original type
+*/
+function rehydrateValue(serialized, type) {
+	if (type === "null" || serialized === null) return null;
+	switch (type) {
+		case "date": return new Date(serialized);
+		case "objectid": return new mongoose.Types.ObjectId(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
+*/
+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 }
+		};
+	}
+	const cursor = decodeCursor(after, secret);
+	validateCursorVersion(cursor.version, cursorVersion, minCursorVersion);
+	validateCursorSort(cursor.sort, sort);
+	return buildKeysetFilter(baseFilters, buildSort, cursor.value, cursor.id, cursor.values);
+}
+//#endregion
+//#region src/pagination/utils/index-hint.ts
+/**
+* The only operators that give the query planner a *bounded equality* it can
+* lead an index with. Everything else (`$ne`, `$nin`, `$gt(e)`, `$lt(e)`,
+* `$all`, `$elemMatch`, `$regex`, `$exists`, …) is a range predicate and, per ESR,
+* must come AFTER the sort keys — never in the leading prefix.
+*
+* `$all` is intentionally excluded: although it combines equality matches,
+* it targets multikey data, whose bounded index prefix cannot generally
+* provide a subsequent index sort. Treating it as residual avoids claiming
+* that a multikey-prefix compound index satisfies the sort.
+*/
+const EQUALITY_OPERATORS = /* @__PURE__ */ new Set(["$eq", "$in"]);
+/**
+* Is a top-level filter value a RANGE predicate (as opposed to equality)?
+*
+* Only a plain operator object — one whose own keys start with `$` — can be a
+* range. Scalars, `Date`, `ObjectId`, arrays, and embedded-doc equality
+* matches (`{ nested: { a: 1 } }`) are all equality for index-leading
+* purposes. An operator object is equality iff every `$`-operator it uses is
+* in {@link EQUALITY_OPERATORS}.
+*/
+function isRangePredicate(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const operatorKeys = Object.keys(value).filter((k) => k.startsWith("$"));
+	if (operatorKeys.length === 0) return false;
+	return operatorKeys.some((k) => !EQUALITY_OPERATORS.has(k));
+}
+/**
+* Split top-level filter fields into ESR equality vs range predicates.
+*
+* The keyset index check follows MongoDB's ESR rule (Equality → Sort →
+* Range). Only equality predicates belong in an index's leading prefix; a
+* range predicate placed there stops the planner from using any later key for
+* bounds OR for satisfying the sort. So the compatibility check and the
+* recommended-index shape must treat the two classes differently — a field
+* filtered by a range should TRAIL the sort keys, not lead them.
+*
+* `$`-prefixed top-level keys (`$and`/`$or`/…) are ignored (the caller decides
+* how to handle logical combinators).
+*/
+function classifyFilterFields(filters) {
+	const equality = [];
+	const range = [];
+	for (const [key, value] of Object.entries(filters)) {
+		if (key.startsWith("$")) continue;
+		if (isRangePredicate(value)) range.push(key);
+		else equality.push(key);
+	}
+	return {
+		equality,
+		range
+	};
+}
+/**
+* The ESR index to recommend for a keyset query: equality → sort (incl. the `_id`
+* tiebreaker) → range, each field ONCE. A filtered field that is also a sort key
+* takes its sort position — Mongo rejects an index naming a key twice.
+*/
+function recommendKeysetIndex(filters, sort) {
+	const { equality, range } = classifyFilterFields(filters);
+	const notSorted = (f) => !Object.hasOwn(sort, f);
+	return [
+		...equality.filter(notSorted).map((f) => [f, 1]),
+		...Object.entries(sort),
+		...range.filter(notSorted).map((f) => [f, 1])
+	];
+}
+/**
+* Read a Mongoose schema's declared indexes, defensively.
+* Returns an empty array on any introspection failure.
+*/
+function readSchemaIndexes(Model) {
+	try {
+		const schema = Model.schema;
+		if (!schema || typeof schema.indexes !== "function") return [];
+		const raw = schema.indexes();
+		return Array.isArray(raw) ? raw : [];
+	} catch {
+		return [];
+	}
+}
+/**
+* Does any schema-declared compound index satisfy ESR for the given
+* equality filter fields + sort?
+*
+* Rules:
+*   1. The first N keys of the index (N = filterFields.length) must be
+*      exactly the equality filter fields in any order (set equality).
+*   2. The next M keys (M = sortKeys.length) must match the sort keys in
+*      exact declared order.
+*   3. Directions must all match OR all be inverse (MongoDB can walk an
+*      index in reverse, but only if every sort field flips together).
+*   4. Indexes with more total keys than needed are still accepted when
+*      the above prefix holds — Mongo just ignores trailing fields.
+*
+* Notes:
+*   - Hashed / text / 2dsphere indexes are skipped (not usable for sort).
+*   - Unique, partial, sparse options don't affect compatibility.
+*   - When `filterFields` is empty, a sort-only prefix match is sufficient.
+*
+* @param indexes      Raw `[spec, options?]` tuples from `schema.indexes()`.
+* @param filterFields Top-level equality filter keys (already stripped of `$*`).
+* @param sort         Normalized sort spec `{ field: 1 | -1 }`.
+*/
+function hasCompatibleKeysetIndex(indexes, filterFields, sort) {
+	const sortKeys = Object.keys(sort);
+	if (sortKeys.length === 0) return true;
+	const prefixFields = filterFields.filter((f) => !Object.hasOwn(sort, f));
+	const filterSet = new Set(prefixFields);
+	const prefixLen = prefixFields.length;
+	for (const [spec] of indexes) {
+		if (!spec || typeof spec !== "object") continue;
+		const entries = Object.entries(spec);
+		if (entries.length < prefixLen + sortKeys.length) continue;
+		if (entries.some(([, dir]) => typeof dir !== "number")) continue;
+		const equalityPrefix = entries.slice(0, prefixLen).map(([k]) => k);
+		if (equalityPrefix.length !== prefixLen) continue;
+		if (!(equalityPrefix.every((k) => filterSet.has(k)) && new Set(equalityPrefix).size === prefixLen)) continue;
+		const sortSuffix = entries.slice(prefixLen, prefixLen + sortKeys.length);
+		if (sortSuffix.length !== sortKeys.length) continue;
+		let namesMatch = true;
+		for (let i = 0; i < sortKeys.length; i++) if (sortSuffix[i][0] !== sortKeys[i]) {
+			namesMatch = false;
+			break;
+		}
+		if (!namesMatch) continue;
+		const forward = sortKeys.every((k, i) => sortSuffix[i][1] === sort[k]);
+		const reverse = sortKeys.every((k, i) => sortSuffix[i][1] === -sort[k]);
+		if (forward || reverse) return true;
+	}
+	return false;
+}
+//#endregion
+//#region src/pagination/utils/sort.ts
+var sort_exports = /* @__PURE__ */ __exportAll({
+	getPrimaryField: () => getPrimaryField,
+	invertSort: () => invertSort,
+	normalizeSort: () => normalizeSort,
+	validateKeysetSort: () => validateKeysetSort
+});
+/**
+* Normalizes sort object to ensure stable key order
+* Primary fields first, _id last (not alphabetical)
+*
+* @param sort - Sort specification
+* @returns Normalized sort with stable key order
+*/
+function normalizeSort(sort) {
+	const normalized = {};
+	Object.keys(sort).forEach((key) => {
+		if (key !== "_id") normalized[key] = sort[key];
+	});
+	if (sort._id !== void 0) normalized._id = sort._id;
+	return normalized;
+}
+/**
+* Validates and normalizes sort for keyset pagination.
+* Auto-adds `_id` tie-breaker if needed; ensures `_id` direction matches the
+* primary field.
+*
+* **Known limitation (MongoDB mixed-type sort):** keyset pagination across a
+* field that can hold both typed values (Date, Number) and `null`/`undefined`
+* is lossy — `$lt/$gt` don't cross the type boundary in BSON comparison, so
+* some docs at the null/non-null boundary are unreachable. If your sort field
+* is nullable, either:
+*   - sort by `_id` alone (always safe), or
+*   - use `allowedPrimaryFields` to lock keyset sort to fields your schema
+*     guarantees non-null (see `PaginationConfig.strictKeysetSortFields`).
+*
+* @param sort - Sort specification
+* @param allowedPrimaryFields - Optional allowlist of primary (non-_id) sort
+*   field names. When set, rejects sorts whose primary field isn't listed.
+*   `_id` is always allowed.
+* @returns Validated and normalized sort
+* @throws Error if sort is invalid for keyset pagination
+*/
+function validateKeysetSort(sort, allowedPrimaryFields) {
+	const keys = Object.keys(sort);
+	if (keys.length === 0) throw new Error("Keyset pagination requires at least one sort field");
+	if (keys.length === 1 && keys[0] === "_id") return normalizeSort(sort);
+	for (const key of keys) if (sort[key] !== 1 && sort[key] !== -1) throw new Error(`Invalid sort direction for "${key}": must be 1 or -1, got ${sort[key]}`);
+	const nonIdKeys = keys.filter((k) => k !== "_id");
+	const primaryDirection = sort[nonIdKeys[0]];
+	if (allowedPrimaryFields && allowedPrimaryFields.length > 0) {
+		for (const key of nonIdKeys) if (!allowedPrimaryFields.includes(key)) throw new Error(`Keyset sort field "${key}" is not in the strictKeysetSortFields allowlist. Allowed: ${allowedPrimaryFields.join(", ")}. (See PaginationConfig.strictKeysetSortFields — protects against lossy null/non-null keyset boundaries.)`);
+	}
+	/**
+	* Mixed directions are allowed. `{ priority: 1, createdAt: -1 }` is the
+	* ESR-shaped compound index every planner guide recommends, and the keyset
+	* predicate is a tuple comparison whose operator is chosen PER POSITION
+	* (`buildKeysetFilter`), so nothing about it needs the directions to agree.
+	* Forbidding them pushed callers onto the offset path — `skip(n)` — which is
+	* the cost keyset exists to avoid.
+	*
+	* `_id` keeps whatever direction the caller gave it; when absent it follows
+	* the primary field, so a sort that never mentions `_id` behaves as before.
+	*/
+	if (!keys.includes("_id")) return normalizeSort({
+		...sort,
+		_id: primaryDirection
+	});
+	return normalizeSort(sort);
+}
+/**
+* Inverts sort directions (1 becomes -1, -1 becomes 1)
+*
+* @param sort - Sort specification
+* @returns Inverted sort
+*/
+function invertSort(sort) {
+	const inverted = {};
+	Object.keys(sort).forEach((key) => {
+		inverted[key] = sort[key] === 1 ? -1 : 1;
+	});
+	return inverted;
+}
+/**
+* Extracts primary sort field (first non-_id field)
+*
+* @param sort - Sort specification
+* @returns Primary field name
+*/
+function getPrimaryField(sort) {
+	return Object.keys(sort).find((k) => k !== "_id") || "_id";
+}
+//#endregion
+//#region src/pagination/PaginationEngine.ts
+/**
+* The sort fields a reader cares about, for MESSAGES only — never for deciding
+* whether an index is adequate.
+*
+* `_id` is appended to every keyset sort as the tiebreaker, and naming it in
+* the "sort [...]" half of a warning is noise, since the caller never wrote it.
+* Naming it in the RECOMMENDED INDEX is mandatory, which is why that half uses
+* the full sort.
+*
+* This used to strip `_id` before the compatibility CHECK too, on the stated
+* grounds that "an index covering the primary sort is still efficient — the
+* planner uses the index for ordering and only pays an in-memory tiebreak on
+* duplicate primary values". That is false, and measurably so: against 20k rows
+* with heavy ties on the sort field, an index without `_id` produced a BLOCKING
+* `SORT` stage examining all 20,000 documents to return 20, where the same
+* index with `_id` examined exactly 20. Not a tiebreak — a full sort of the
+* matching range, on every page. `tests/integration/keyset-index-explain.test.ts`
+* pins it with a real `explain('executionStats')`.
+*/
+function sortFieldsForMessage(sort) {
+	return Object.keys(sort).filter((k) => k !== "_id");
+}
+function ensureKeysetSelectIncludesCursorFields(select, sort) {
+	if (!select) return select;
+	const requiredFields = /* @__PURE__ */ new Set([...Object.keys(sort), "_id"]);
+	if (typeof select === "string") {
+		const fields = select.split(/[,\s]+/).map((field) => field.trim()).filter(Boolean);
+		if (fields.length > 0 && fields.every((field) => field.startsWith("-"))) return select;
+		const merged = new Set(fields);
+		for (const field of requiredFields) merged.add(field);
+		return Array.from(merged).join(" ");
+	}
+	if (Array.isArray(select)) {
+		const fields = select.map((field) => field.trim()).filter(Boolean);
+		if (fields.length > 0 && fields.every((field) => field.startsWith("-"))) return select;
+		const merged = new Set(fields);
+		for (const field of requiredFields) merged.add(field);
+		return Array.from(merged);
+	}
+	const projection = { ...select };
+	if (!Object.values(projection).some((value) => value === 1)) return select;
+	for (const field of requiredFields) projection[field] = 1;
+	return projection;
+}
+/** The library's ceiling when a deployment names none. GitHub shows `1000+`; Elasticsearch stops at 10000. */
+const DEFAULT_COUNT_LIMIT = 1e4;
+/**
+* A count ceiling must be a positive whole number.
+*
+* `0`, a negative, a fraction and `NaN` all reach `.limit()` as "no limit" in
+* one driver path or another — so an operator who set `COUNT_LIMIT=0` meaning
+* "never count" would instead get the unbounded scan the strategy exists to
+* prevent, and nothing would say so. Fall back to the library's own ceiling
+* rather than honouring a value that cannot mean what it says.
+*/
+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;
+	/**
+	* Lazily-cached schema index snapshot used by stream() to decide whether
+	* to emit the "missing compound index" warning. Computed on first use.
+	*/
+	_cachedSchemaIndexes = null;
+	/**
+	* Create a new pagination engine
+	*
+	* @param Model - Mongoose model to paginate
+	* @param config - Pagination configuration
+	*/
+	constructor(Model, config = {}) {
+		this.Model = Model;
+		/**
+		* `defaultCountStrategy`, `defaultCountLimit`, `defaultMode` and `maxPage`
+		* are NOT resolved
+		* here — `bindPaginationDefaults` installs them as getters that fall back
+		* to the deployment policy (`configurePaginationDefaults`). A kernel-built
+		* repository passes no config at all, so without that seam a host has no
+		* way to say "this deployment does not count rows" and inherits an
+		* O(matching rows) `countDocuments` on every page. Reading them through
+		* `this.config.*` is unchanged for every call site.
+		*/
+		this.config = bindPaginationDefaults({
+			defaultLimit: config.defaultLimit ?? 10,
+			maxLimit: config.maxLimit ?? 100,
+			deepPageThreshold: config.deepPageThreshold ?? 100,
+			cursorVersion: config.cursorVersion ?? 1,
+			minCursorVersion: config.minCursorVersion ?? 1,
+			strictKeysetSortFields: config.strictKeysetSortFields,
+			useEstimatedCount: config.useEstimatedCount ?? false
+		}, config);
+	}
+	/** Memoized schema index lookup — avoids re-walking schema on every stream(). */
+	_getSchemaIndexes() {
+		if (this._cachedSchemaIndexes !== null) return this._cachedSchemaIndexes;
+		this._cachedSchemaIndexes = readSchemaIndexes(this.Model);
+		return this._cachedSchemaIndexes;
+	}
+	/**
+	* Offset-based pagination using skip/limit
+	* Best for small datasets and when users need random page access
+	* O(n) performance - slower for deep pages
+	*
+	* @param options - Pagination options
+	* @returns Pagination result with total count
+	*
+	* @example
+	* const result = await engine.paginate({
+	*   filters: { status: 'active' },
+	*   sort: { createdAt: -1 },
+	*   page: 1,
+	*   limit: 20
+	* });
+	* 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 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);
+		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 (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;
+		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 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;
+		/**
+		* A CLAMPED limit is reported, not swallowed.
+		*
+		* `validateLimit` caps silently by design — an over-ask is benign and rejecting it
+		* would be worse (that contradiction cost a day: the querystring schema's `maximum`
+		* made the parser's documented clamp unreachable, so `?limit=200` 400'd and two UI
+		* callers rendered the failure as an empty list).
+		*
+		* But clamping quietly has its own cost. A caller asking for 1000 and receiving 100
+		* gets an arbitrary slice with no signal — which is exactly how a bank-account
+		* picker rendered "No accounts found" against 696 accounts, because the rows it
+		* wanted were outside the first page. `limit` in the response already carries the
+		* effective value; nobody compares it. A warning is the channel that is actually
+		* read.
+		*
+		* Deep-pagination takes precedence when both apply: it is the more actionable of
+		* the two, and stacking warnings turns a signal into noise.
+		*/
+		const requestedLimit = Number(limit);
+		const wasClamped = Number.isFinite(requestedLimit) && requestedLimit > sanitizedLimit;
+		const warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination (page ${sanitizedPage}). Consider getAll({ after, sort, limit }) for better performance.` : wasClamped ? `Requested limit ${Math.floor(requestedLimit)} exceeds this repository's cap; returning ${sanitizedLimit}. Filter server-side or sort deterministically — the returned page is otherwise an arbitrary slice.` : void 0;
+		return {
+			method: "offset",
+			data,
+			page: sanitizedPage,
+			limit: sanitizedLimit,
+			total,
+			pages: totalPages,
+			hasNext,
+			hasPrev: sanitizedPage > 1,
+			...totalIsLowerBound && { totalIsLowerBound },
+			...warning && { warning }
+		};
+	}
+	/**
+	* Keyset (cursor-based) pagination for high-performance streaming.
+	* Best for large datasets, infinite scroll, real-time feeds.
+	*
+	* **Constant cost per page — but ONLY with an index that covers the whole
+	* sort, tiebreaker included.** Keyset removes `skip(n)`; it does not by
+	* itself remove a sort. `validateKeysetSort` appends `_id` to every sort, so
+	* an index stopping at the primary field leaves Mongo to order the ties
+	* itself: a blocking `SORT` over every row the filter matches, paid again on
+	* every page. Measured at 20,000 documents examined to return 20, against 20
+	* with the tiebreaker in the index.
+	*
+	* The dev-time warning below names the index to declare. Read it as a
+	* correctness requirement for the performance claim, not as advice.
+	*
+	* @param options - Pagination options (sort is required)
+	* @returns Pagination result with next cursor
+	*
+	* @example
+	* // First page
+	* const page1 = await engine.stream({
+	*   sort: { createdAt: -1 },
+	*   limit: 20
+	* });
+	*
+	* // Next page using cursor
+	* const page2 = await engine.stream({
+	*   sort: { createdAt: -1 },
+	*   after: page1.next,
+	*   limit: 20
+	* });
+	*/
+	async stream(options) {
+		const { filters = {}, sort, after, before, limit = this.config.defaultLimit, select, populate = [], lean = true, session, hint, maxTimeMS, readPreference, collation } = 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);
+		const normalizedSort = validateKeysetSort(sort, this.config.strictKeysetSortFields);
+		const filterKeys = Object.keys(filters).filter((k) => !k.startsWith("$"));
+		const effectiveSortFields = sortFieldsForMessage(normalizedSort);
+		if (process.env.NODE_ENV !== "test" && filterKeys.length > 0 && effectiveSortFields.length > 0) {
+			const indexes = this._getSchemaIndexes();
+			const { equality } = classifyFilterFields(filters);
+			if (!(hasCompatibleKeysetIndex(indexes, filterKeys, normalizedSort) || equality.length !== filterKeys.length && hasCompatibleKeysetIndex(indexes, equality, normalizedSort))) {
+				const indexFields = recommendKeysetIndex(filters, normalizedSort).map(([f, dir]) => `${f}: ${dir}`);
+				warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${effectiveSortFields.join(", ")}] has no matching schema-declared compound index. Without one, the tiebreaker forces a BLOCKING SORT over every matching row, on every page. Declare: { ${indexFields.join(", ")} }. (Collection-level indexes created outside the schema are not visible here.)`);
+			}
+		}
+		/**
+		* Walking BACKWARDS is the forward walk with every direction inverted.
+		*
+		* `before: c` means "the page ending just before c", which is the same set
+		* as "the first `limit` rows after c in the opposite order" — so the query
+		* runs inverted and the rows are reversed back afterwards, leaving the
+		* caller with data in the order they asked for.
+		*
+		* The CURSOR is still validated against the caller's own sort (that is what
+		* it was minted under); only the QUERY is inverted.
+		*/
+		const backward = Boolean(before);
+		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 effectiveSelect = ensureKeysetSelectIncludesCursorFields(select, normalizedSort);
+		let mongoQuery = this.Model.find(query);
+		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);
+		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);
+		const data = await mongoQuery.exec();
+		const moreThatWay = data.length > sanitizedLimit;
+		if (moreThatWay) data.pop();
+		if (backward) data.reverse();
+		/**
+		* Which end of the walk the extra row spoke for.
+		*
+		* Forward, it says a next page exists. Backward, it says a page exists
+		* BEFORE this one — and a next page certainly exists, because we arrived
+		* from it. The mirror holds for the other edge: paging forward from a
+		* cursor proves a previous page exists.
+		*/
+		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;
+		return {
+			method: "keyset",
+			data,
+			limit: sanitizedLimit,
+			hasMore,
+			next: hasMore ? mint(data[data.length - 1]) : null,
+			prev: hasPrev ? mint(data[0]) : null,
+			hasPrev,
+			end: mint(data[data.length - 1])
+		};
+	}
+	/**
+	* Aggregate pipeline with pagination.
+	*
+	* Runs the page and the count as TWO pipelines, concurrently — not one
+	* `$facet`. `$facet` bundles every returned document and the count into a
+	* SINGLE output document, and no stage may exceed the 16MB BSON limit, so a
+	* page of large documents fails outright with `BSONObjectTooLarge` rather
+	* than paginating. `$facet` also cannot use an index for the stages inside
+	* it, so splitting is frequently the faster plan as well.
+	*
+	* The cost is that the two halves are separate reads and a concurrent write
+	* can land between them, so `total` may disagree with `data` by a document.
+	* That is already true of the offset path (`paginate` runs find and count
+	* through one `Promise.all`) — this makes aggregate consistent with it, and
+	* a count that is one row stale is a far smaller defect than a page that
+	* cannot be fetched at all. `countStrategy: 'none'` runs ONE pipeline.
+	*
+	* @param options - Aggregation options
+	* @returns Pagination result with total count
+	*
+	* @example
+	* const result = await engine.aggregatePaginate({
+	*   pipeline: [
+	*     { $match: { status: 'active' } },
+	*     { $group: { _id: '$category', count: { $sum: 1 } } },
+	*     { $sort: { count: -1 } }
+	*   ],
+	*   page: 1,
+	*   limit: 20
+	* });
+	*/
+	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 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;
+		/** 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);
+			return aggregation.exec();
+		};
+		/**
+		* `$limit` BEFORE `$count` is the aggregate ceiling — the stage stops
+		* pulling documents at the bound, so the count costs O(countLimit) instead
+		* of walking the whole pipeline output.
+		*
+		* `estimated` has no aggregate equivalent (`estimatedDocumentCount` reads
+		* collection metadata and cannot see a pipeline), so it stays exact here —
+		* documented on `AggregatePaginationOptions.countStrategy`.
+		*/
+		const countStages = countStrategy === "capped" ? [
+			...pipeline,
+			{ $limit: resolveCountLimit(countLimit) },
+			{ $count: "count" }
+		] : [...pipeline, { $count: "count" }];
+		const runData = () => run([
+			...pipeline,
+			{ $skip: skip },
+			{ $limit: fetchLimit }
+		]);
+		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 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 warning = shouldWarnDeepPagination(sanitizedPage, this.config.deepPageThreshold) ? `Deep pagination in aggregate (page ${sanitizedPage}). Uses $skip internally.` : void 0;
+		return {
+			method: "aggregate",
+			data,
+			page: sanitizedPage,
+			limit: sanitizedLimit,
+			total,
+			pages: totalPages,
+			hasNext,
+			hasPrev: sanitizedPage > 1,
+			...totalIsLowerBound && { totalIsLowerBound },
+			...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 };