@classytic/mongokit 3.18.0 → 3.20.0

package/README.md

@@ -351,6 +351,72 @@ npm run build
 
 The test suite uses `mongodb-memory-server` by default. Set `MONGODB_URI` to run against an external MongoDB deployment.
 
+## Test Harness — `@classytic/mongokit/testkit`
+
+A batteries-included harness for testing your own repositories. Spins an ephemeral MongoDB (standalone, or a single-node replica set for transactions), opens an **isolated** connection, and gives you a live mongokit `Repository` in one call.
+
+`mongodb-memory-server` is an **optional peer** — install it where you use the testkit; it is never a production dependency and is dynamically imported, so it never enters your app bundle:
+
+```bash
+npm i -D mongodb-memory-server
+```
+
+```ts
+import { createTestRepository } from '@classytic/mongokit/testkit';
+
+const t = await createTestRepository({
+  name: 'Order',
+  schema: orderSchema,
+  config: { softDelete: true, timestamps: true }, // full CreateRepositoryConfig
+});
+
+await t.repository.create({ total: 10 });
+await t.clear();   // empty the collection between tests
+await t.close();   // close connection + stop server (idempotent)
+```
+
+### Run against your own local or cloud DB
+
+Pass a `uri` (or set `MONGODB_URI`) and **no in-memory server starts** — the testkit connects to your real database and `close()`/`stop()` become no-ops, so it never drops it:
+
+```ts
+const t = await createTestRepository({
+  name: 'Order', schema: orderSchema,
+  uri: process.env.ATLAS_TEST_URI ?? 'mongodb://localhost:27017/myapp-test',
+});
+```
+
+```bash
+# or for the whole suite, no code change:
+MONGODB_URI="mongodb+srv://…/myapp-test" vitest run
+```
+
+> ⚠️ `clear()` empties **every collection** on the connection. Against a real database, always point at a **dedicated test DB** — never production.
+
+### Testing indexes
+
+`createTestRepository` runs `model.init()`, so declared indexes are really built — unique-constraint enforcement (`E11000`), TTL, compound, text, and geo indexes all behave for real on the in-memory server. Use the exposed `model` for runtime index work:
+
+```ts
+await t.model.syncIndexes();
+await t.model.collection.indexes();          // inspect
+await t.model.collection.dropIndex('tag_1'); // drop
+```
+
+Atlas **`$search` / `$vectorSearch`** indexes are Atlas-only and don't exist on any non-Atlas server — test those by pointing `uri` at a real Atlas test cluster.
+
+### Helpers
+
+| Helper | Use |
+| --- | --- |
+| `createTestRepository` | server + connection + live `Repository` in one call |
+| `createTestConnection` | isolated connection + `clear()` / `close()` |
+| `withMongoMemory(fn)` | scoped setup → run → teardown (`finally`) |
+| `createMongoMemory` | raw server lifecycle (`uri` + `stop`) |
+| `mongoMemoryBackend()` | a `TestBackend` seam for `@classytic/arc-testkit` |
+
+All accept `{ replset?, dbName?, uri? }`.
+
 ## License
 
 MIT

package/dist/{PaginationEngine-BcvaXBQ-.mjs → PaginationEngine-BT1ywu9k.mjs}

@@ -1,7 +1,258 @@
-import { n as warn } from "./logger-B8wf-Mtb.mjs";
-import { t as createError } from "./error-BTeepSNL.mjs";
-import { n as encodeCursor, r as resolveCursorFilter } from "./cursor-_SbWVAn-.mjs";
-import { r as validateKeysetSort, t as getPrimaryField } from "./sort-Ca1BPfvE.mjs";
+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 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
 /**
 * Read a Mongoose schema's declared indexes, defensively.
@@ -131,6 +382,76 @@ function calculateTotalPages(total, limit) {
 	return Math.ceil(total / limit);
 }
 //#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.
@@ -152,7 +473,7 @@ function stripTrailingIdTiebreaker(sort) {
 }
 function ensureKeysetSelectIncludesCursorFields(select, sort) {
 	if (!select) return select;
-	const requiredFields = new Set([...Object.keys(sort), "_id"]);
+	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;
@@ -390,4 +711,4 @@ var PaginationEngine = class {
 	}
 };
 //#endregion
-export { PaginationEngine as t };
+export { sort_exports as n, cursor_exports as r, PaginationEngine as t };

package/dist/PaginationEngine-DYpOD2wY.d.mts

@@ -0,0 +1,102 @@
+import { A as KeysetPaginationOptions, U as PaginationConfig, V as OffsetPaginationOptions, i as AnyDocument, n as AggregatePaginationOptions } from "./types-DNFMofHy.mjs";
+import { Model } from "mongoose";
+import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
+//#region src/pagination/PaginationEngine.d.ts
+/**
+ * Internal pagination config with required values
+ */
+interface ResolvedPaginationConfig {
+  defaultLimit: number;
+  maxLimit: number;
+  maxPage: number;
+  deepPageThreshold: number;
+  cursorVersion: number;
+  minCursorVersion: number;
+  strictKeysetSortFields: string[] | undefined;
+  useEstimatedCount: boolean;
+}
+/**
+ * Production-grade pagination engine for MongoDB
+ * Supports offset, keyset (cursor), and aggregate pagination
+ */
+declare class PaginationEngine<TDoc = AnyDocument> {
+  readonly Model: Model<TDoc>;
+  readonly config: ResolvedPaginationConfig;
+  /**
+   * Lazily-cached schema index snapshot used by stream() to decide whether
+   * to emit the "missing compound index" warning. Computed on first use.
+   */
+  private _cachedSchemaIndexes;
+  /**
+   * Create a new pagination engine
+   *
+   * @param Model - Mongoose model to paginate
+   * @param config - Pagination configuration
+   */
+  constructor(Model: Model<TDoc, any, any, any>, config?: PaginationConfig);
+  /** Memoized schema index lookup — avoids re-walking schema on every stream(). */
+  private _getSchemaIndexes;
+  /**
+   * 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);
+   */
+  paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc>>;
+  /**
+   * 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
+   * });
+   */
+  stream(options: KeysetPaginationOptions): Promise<KeysetPaginationResult<TDoc>>;
+  /**
+   * 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
+   * });
+   */
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+}
+//#endregion
+export { PaginationEngine as t };

package/dist/{Repository-B01VW_fU.mjs → Repository-dbbgOGjK.mjs}

@@ -1,10 +1,10 @@
-import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-CnN0YA8t.mjs";
-import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-CvCMv5Cl.mjs";
-import { n as warn } from "./logger-B8wf-Mtb.mjs";
-import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BTeepSNL.mjs";
-import { t as PaginationEngine } from "./PaginationEngine-BcvaXBQ-.mjs";
+import { i as isValidIdForType, t as getSchemaIdType } from "./id-resolution-P2OzcyRl.mjs";
+import { a as count, b as LookupBuilder, c as getByQuery, d as deleteById, f as deleteByQuery, h as createMany, l as getOrCreate, m as create, n as update, o as exists, r as updateByQuery, s as getById, t as findOneAndUpdate, x as compileFilterToMongo, y as distinct } from "./update-1Lq9OMD2.mjs";
+import { n as warn } from "./logger-K7dPmu2U.mjs";
+import { n as isDuplicateKeyError, r as parseDuplicateKeyError, t as createError } from "./error-BuByZwKU.mjs";
+import { t as PaginationEngine } from "./PaginationEngine-BT1ywu9k.mjs";
 import { hasNearOperator, rewriteNearForCount } from "./query/primitives/geo.mjs";
-import { RepositoryBase, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
+import { RepositoryBase, runChunkedArchive, runChunkedPurge, throwIfAborted, validatePluginOrder, withRetry } from "@classytic/repo-core/repository";
 import mongoose from "mongoose";
 import { isFilter } from "@classytic/repo-core/filter";
 import { HOOK_PRIORITY } from "@classytic/repo-core/hooks";
@@ -97,6 +97,7 @@ const MONGOKIT_CAPABILITIES = {
 	getOrCreate: true,
 	countAndExists: true,
 	purgeByField: true,
+	archiveByFilter: true,
 	arrayOperators: true,
 	regexFilter: true,
 	changeStreams: true,
@@ -617,7 +618,7 @@ function validateTopN(topN, groupCols, bucketAliases, measures) {
 	if (!Number.isInteger(topN.limit) || topN.limit <= 0) throw new Error(`mongokit/aggregate: topN.limit must be a positive integer — got ${String(topN.limit)}`);
 	if (!topN.sortBy || Object.keys(topN.sortBy).length === 0) throw new Error("mongokit/aggregate: topN.sortBy must declare at least one ranking field");
 	const partitionList = Array.isArray(topN.partitionBy) ? topN.partitionBy : [topN.partitionBy];
-	const validKeys = new Set([
+	const validKeys = /* @__PURE__ */ new Set([
 		...groupCols,
 		...bucketAliases,
 		...Object.keys(measures)
@@ -913,6 +914,30 @@ function buildKeysetPredicate(sort, cursor) {
 	return { $match: branches.length === 1 ? branches[0] : { $or: branches } };
 }
 //#endregion
+//#region src/actions/archive.ts
+/**
+* Build an `ArchivePort` bound to a repository + a pre-compiled Mongo
+* filter (the repository compiles Filter IR before calling this).
+*/
+function createMongoArchivePort(repo, filter, session) {
+	return {
+		async readChunk(limit) {
+			return await repo.Model.find(filter).sort({ _id: 1 }).limit(limit).session(session ?? null).lean().exec();
+		},
+		async deleteChunk(docs) {
+			const ids = docs.map((doc) => doc._id);
+			return (await repo.deleteMany({
+				...filter,
+				_id: { $in: ids }
+			}, {
+				session,
+				bypassTenant: true,
+				mode: "hard"
+			})).deletedCount;
+		}
+	};
+}
+//#endregion
 //#region src/query/AggregationBuilder.ts
 /**
 * Normalize SortSpec to MongoDB's strict format (1 | -1)
@@ -1831,7 +1856,7 @@ var Repository = class extends RepositoryBase {
 	_wireStrictQueryStripDiagnostic(enabled) {
 		if (!enabled) return;
 		const schema = this.Model.schema;
-		const declaredPaths = new Set(["_id"]);
+		const declaredPaths = /* @__PURE__ */ new Set(["_id"]);
 		for (const path of Object.keys(schema.paths)) {
 			declaredPaths.add(path);
 			const segments = path.split(".");
@@ -2090,6 +2115,40 @@ var Repository = class extends RepositoryBase {
 		});
 	}
 	/**
+	* Batch point-read — the `$in` counterpart to {@link getById}. Fetches every
+	* doc whose id (the repo's `idField`, default `_id`) is in `ids` in ONE query,
+	* routed through `findAll` so tenant + soft-delete scoping and hooks apply
+	* exactly as a single read would. Returns a Map keyed by the stringified id;
+	* ids are de-duplicated and ids with no matching doc are simply absent (no
+	* throw — mirrors `getById(..., { throwOnNotFound: false })`). Structurally
+	* INVALID ids (wrong ObjectId shape, non-numeric for a Number id field, ...)
+	* are dropped the same way — an id that cannot exist in the collection is
+	* unambiguously a miss, and one malformed id must never poison the rest of
+	* the batch. Lean by default (findAll semantics) — pass `{ lean: false }`
+	* for hydrated docs.
+	*
+	* The N+1 killer for hosts that resolve many ids in one tick (order-line
+	* snapshotting, availability matrices, dashboard row enrichment):
+	*
+	* @example
+	* const byId = await repo.getByIds(offerIds, ctx);
+	* const doc = byId.get(offerId); // O(1); undefined if not found
+	*
+	* Sizing: there is no library-imposed cap — the bounds are MongoDB's (the
+	* `$in` array must fit the 16 MB query document; `$in` on an indexed field
+	* is n point-lookups). Keep batches ≤ ~10k ids per call and chunk beyond
+	* that. Don't exclude the id field via `select` — result keys derive from
+	* it.
+	*/
+	async getByIds(ids, options = {}) {
+		const field = options.idField ?? this.idField;
+		const idType = getSchemaIdType(this.Model.schema, field);
+		const unique = [...new Set(ids.map((id) => String(id)))].filter((id) => isValidIdForType(id, idType));
+		if (unique.length === 0) return /* @__PURE__ */ new Map();
+		const docs = await this.findAll({ [field]: { $in: unique } }, options);
+		return new Map(docs.map((d) => [String(d[field]), d]));
+	}
+	/**
 	* Get single document by query
 	*/
 	async getByQuery(query, options = {}) {
@@ -3246,6 +3305,21 @@ var Repository = class extends RepositoryBase {
 		return runChunkedPurge(strategy, options, createMongoPurgePort(this, field, value, options.session));
 	}
 	/**
+	* Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
+	* for the cross-kit contract (write-before-delete, at-least-once,
+	* duplicate-tolerant sinks). Mongokit composes the kit-agnostic
+	* `runChunkedArchive` orchestrator with `createMongoArchivePort`
+	* (`_id`-ordered lean reads + plugin-routed deleteMany removal). See
+	* [actions/archive.ts](./actions/archive.ts) for the port.
+	*
+	* Accepts Filter IR or a Mongo-shaped filter record — compiled once via
+	* `compileFilterToMongo`, same dual-dialect rule as every other verb.
+	*/
+	async archiveByFilter(filter, sink, options = {}) {
+		const compiled = compileFilterToMongo(filter);
+		return runChunkedArchive(options, sink, createMongoArchivePort(this, compiled, options.session));
+	}
+	/**
 	* Kit-native aggregation pipeline — takes a MongoDB stage array and
 	* returns the raw pipeline output. Use this for `$lookup`, `$unwind`,
 	* `$facet`, `$graphLookup`, and any other mongo-specific power
@@ -3614,9 +3688,9 @@ var Repository = class extends RepositoryBase {
 				};
 				if (isKeyset && sort) {
 					const parsedSort = this._parseSort(sort);
-					const { validateKeysetSort } = await import("./sort-Ca1BPfvE.mjs").then((n) => n.n);
-					const { encodeCursor, resolveCursorFilter } = await import("./cursor-_SbWVAn-.mjs").then((n) => n.t);
-					const { getPrimaryField } = await import("./sort-Ca1BPfvE.mjs").then((n) => n.n);
+					const { validateKeysetSort } = await import("./PaginationEngine-BT1ywu9k.mjs").then((n) => n.n);
+					const { encodeCursor, resolveCursorFilter } = await import("./PaginationEngine-BT1ywu9k.mjs").then((n) => n.r);
+					const { getPrimaryField } = await import("./PaginationEngine-BT1ywu9k.mjs").then((n) => n.n);
 					const normalizedSort = validateKeysetSort(parsedSort, this._pagination.config.strictKeysetSortFields);
 					const cursorVersion = this._pagination.config.cursorVersion ?? 1;
 					const minCursorVersion = this._pagination.config.minCursorVersion ?? 1;

package/dist/actions/index.d.mts

@@ -1,2 +1,2 @@
-import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-fi91ycQc.mjs";
+import { a as create_d_exports, i as delete_d_exports, n as update_d_exports, o as aggregate_d_exports, r as read_d_exports } from "../index-Cg3SWugF.mjs";
 export { aggregate_d_exports as aggregate, create_d_exports as create, delete_d_exports as deleteActions, read_d_exports as read, update_d_exports as update };