@classytic/mongokit 3.38.1 → 3.39.0

package/dist/PaginationEngine-BX9o_-4R.mjs

@@ -1,735 +0,0 @@
-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";
-//#region src/pagination/utils/filter.ts
-/**
-* Builds MongoDB filter for keyset pagination
-* Creates compound $or condition for proper cursor-based filtering
-*
-* @param baseFilters - Existing query filters
-* @param sort - Normalized sort specification
-* @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");
-	if (sortFields.length <= 1 && !cursorValues) {
-		const primaryField = sortFields[0] || "_id";
-		const direction = sort[primaryField];
-		const operator = direction === 1 ? "$gt" : "$lt";
-		if (cursorValue === null || cursorValue === void 0) {
-			if (direction === 1) return {
-				...baseFilters,
-				$or: [{
-					[primaryField]: null,
-					_id: { $gt: cursorId }
-				}, { [primaryField]: { $ne: null } }]
-			};
-			else return {
-				...baseFilters,
-				[primaryField]: null,
-				_id: { $lt: cursorId }
-			};
-		}
-		return {
-			...baseFilters,
-			$or: [{ [primaryField]: { [operator]: cursorValue } }, {
-				[primaryField]: cursorValue,
-				_id: { [operator]: cursorId }
-			}]
-		};
-	}
-	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 = (sort[field] ?? sort[sortFields[0]]) === 1 ? "$gt" : "$lt";
-		const condition = {};
-		for (let j = 0; j < i; j++) condition[allFields[j]] = allValues[allFields[j]];
-		condition[field] = { [operator]: allValues[field] };
-		orConditions.push(condition);
-	}
-	return {
-		...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,
-	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) {
-	const primaryValue = doc[primaryField];
-	const idValue = doc._id;
-	const sortFields = Object.keys(sort).filter((k) => k !== "_id");
-	const vals = {};
-	const types = {};
-	for (const field of sortFields) {
-		vals[field] = serializeValue(doc[field]);
-		types[field] = getValueType(doc[field]);
-	}
-	const payload = {
-		v: serializeValue(primaryValue),
-		t: getValueType(primaryValue),
-		id: serializeValue(idValue),
-		idType: getValueType(idValue),
-		sort,
-		ver: version,
-		...sortFields.length > 1 && {
-			vals,
-			types
-		}
-	};
-	return Buffer.from(JSON.stringify(payload)).toString("base64");
-}
-/**
-* 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) {
-	let json;
-	try {
-		json = Buffer.from(token, "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.`);
-}
-/**
-* 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) {
-	if (/^[a-f0-9]{24}$/i.test(after)) {
-		const objectId = new mongoose.Types.ObjectId(after);
-		const idOperator = (sort._id || -1) === 1 ? "$gt" : "$lt";
-		return {
-			...baseFilters,
-			_id: { [idOperator]: objectId }
-		};
-	}
-	const cursor = decodeCursor(after);
-	validateCursorVersion(cursor.version, cursorVersion, minCursorVersion);
-	validateCursorSort(cursor.sort, sort);
-	return buildKeysetFilter(baseFilters, sort, 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
-	};
-}
-/**
-* 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 filterSet = new Set(filterFields);
-	const prefixLen = filterFields.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,
-	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.)`);
-	}
-	for (const key of nonIdKeys) if (sort[key] !== primaryDirection) throw new Error("All sort fields must share the same direction for keyset pagination");
-	if (keys.includes("_id") && sort._id !== primaryDirection) throw new Error("_id direction must match primary field direction");
-	if (!keys.includes("_id")) return normalizeSort({
-		...sort,
-		_id: primaryDirection
-	});
-	return normalizeSort(sort);
-}
-/**
-* 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
-/**
-* Strip a trailing `_id` tiebreaker from a normalized sort spec.
-*
-* `validateKeysetSort` always appends `_id` to the end of the sort object as
-* a stable-order guarantee. For index-compatibility matching we only care
-* about the primary ordering fields — an index covering those is efficient
-* even without `_id` in the index itself.
-*
-* Returns the sort unchanged if `_id` is the only field (degenerate case).
-*/
-function stripTrailingIdTiebreaker(sort) {
-	const keys = Object.keys(sort);
-	if (keys.length <= 1) return sort;
-	if (keys[keys.length - 1] !== "_id") return sort;
-	const out = {};
-	for (let i = 0; i < keys.length - 1; i++) out[keys[i]] = sort[keys[i]];
-	return out;
-}
-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;
-}
-/**
-* 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;
-		this.config = {
-			defaultLimit: config.defaultLimit ?? 10,
-			maxLimit: config.maxLimit ?? 100,
-			maxPage: config.maxPage ?? 1e4,
-			deepPageThreshold: config.deepPageThreshold ?? 100,
-			cursorVersion: config.cursorVersion ?? 1,
-			minCursorVersion: config.minCursorVersion ?? 1,
-			strictKeysetSortFields: config.strictKeysetSortFields,
-			useEstimatedCount: config.useEstimatedCount ?? false
-		};
-	}
-	/** 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 = "exact", readPreference, collation } = options;
-		const sanitizedPage = validatePage(page, this.config);
-		const sanitizedLimit = validateLimit(limit, this.config);
-		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-		const fetchLimit = countStrategy === "none" ? 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 countPromise;
-		if ((countStrategy === "estimated" || useEstimated) && !hasFilters) countPromise = this.Model.estimatedDocumentCount();
-		else if (countStrategy === "none") countPromise = Promise.resolve(0);
-		else {
-			const countTarget = countFilters ?? filters;
-			const countQuery = this.Model.countDocuments(countTarget).session(session ?? null);
-			if (hint) countQuery.hint(hint);
-			if (maxTimeMS) countQuery.maxTimeMS(maxTimeMS);
-			if (readPreference) countQuery.read(readPreference);
-			countPromise = countQuery.exec();
-		}
-		const [data, total] = await Promise.all([query.exec(), countPromise]);
-		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
-		let hasNext;
-		if (countStrategy === "none") {
-			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,
-			...warning && { warning }
-		};
-	}
-	/**
-	* Keyset (cursor-based) pagination for high-performance streaming
-	* Best for large datasets, infinite scroll, real-time feeds
-	* O(1) performance - consistent speed regardless of position
-	*
-	* @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, 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");
-		const sanitizedLimit = validateLimit(limit, this.config);
-		const normalizedSort = validateKeysetSort(sort, this.config.strictKeysetSortFields);
-		const sortWithoutIdTail = stripTrailingIdTiebreaker(normalizedSort);
-		const filterKeys = Object.keys(filters).filter((k) => !k.startsWith("$"));
-		const effectiveSortFields = Object.keys(sortWithoutIdTail);
-		if (process.env.NODE_ENV !== "test" && filterKeys.length > 0 && effectiveSortFields.length > 0) {
-			const indexes = this._getSchemaIndexes();
-			const { equality, range } = classifyFilterFields(filters);
-			if (!(hasCompatibleKeysetIndex(indexes, filterKeys, sortWithoutIdTail) || equality.length !== filterKeys.length && hasCompatibleKeysetIndex(indexes, equality, sortWithoutIdTail))) {
-				const indexFields = [
-					...equality.map((f) => `${f}: 1`),
-					...effectiveSortFields.map((f) => `${f}: ${sortWithoutIdTail[f]}`),
-					...range.map((f) => `${f}: 1`)
-				];
-				warn(`[mongokit] Keyset pagination with filters [${filterKeys.join(", ")}] and sort [${effectiveSortFields.join(", ")}] has no matching schema-declared compound index. For O(1) performance, declare: { ${indexFields.join(", ")} }. (Collection-level indexes created outside the schema are not visible here.)`);
-			}
-		}
-		let query = { ...filters };
-		if (after) query = resolveCursorFilter(after, normalizedSort, this.config.cursorVersion, query, this.config.minCursorVersion);
-		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(normalizedSort).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 hasMore = data.length > sanitizedLimit;
-		if (hasMore) data.pop();
-		const primaryField = getPrimaryField(normalizedSort);
-		return {
-			method: "keyset",
-			data,
-			limit: sanitizedLimit,
-			hasMore,
-			next: hasMore && data.length > 0 ? encodeCursor(data[data.length - 1], primaryField, normalizedSort, this.config.cursorVersion) : null
-		};
-	}
-	/**
-	* Aggregate pipeline with pagination
-	* Best for complex queries requiring aggregation stages
-	* Uses $facet to combine results and count in single query
-	*
-	* @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 = "exact", readPreference } = options;
-		const sanitizedPage = validatePage(page, this.config);
-		const sanitizedLimit = validateLimit(limit, this.config);
-		const skip = calculateSkip(sanitizedPage, sanitizedLimit);
-		const fetchLimit = countStrategy === "none" ? sanitizedLimit + 1 : sanitizedLimit;
-		const facetStages = { data: [{ $skip: skip }, { $limit: fetchLimit }] };
-		if (countStrategy !== "none") facetStages.total = [{ $count: "count" }];
-		const facetPipeline = [...pipeline, { $facet: facetStages }];
-		const aggregation = this.Model.aggregate(facetPipeline);
-		if (session) aggregation.session(session);
-		if (hint) aggregation.hint(hint);
-		if (maxTimeMS) aggregation.option({ maxTimeMS });
-		if (readPreference) aggregation.read(readPreference);
-		const [result] = await aggregation.exec();
-		const data = result.data;
-		const total = result.total?.[0]?.count || 0;
-		const totalPages = countStrategy === "none" ? 0 : calculateTotalPages(total, sanitizedLimit);
-		let hasNext;
-		if (countStrategy === "none") {
-			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,
-			...warning && { warning }
-		};
-	}
-};
-//#endregion
-export { sort_exports as n, cursor_exports as r, PaginationEngine as t };