@classytic/mongokit 3.18.0 → 3.20.0

package/dist/cursor-_SbWVAn-.mjs

@@ -1,254 +0,0 @@
-import { t as __exportAll } from "./chunk-CfYAbeIz.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
-export { encodeCursor as n, resolveCursorFilter as r, cursor_exports as t };

package/dist/sort-Ca1BPfvE.mjs

@@ -1,72 +0,0 @@
-import { t as __exportAll } from "./chunk-CfYAbeIz.mjs";
-//#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
-export { sort_exports as n, validateKeysetSort as r, getPrimaryField as t };