@classytic/mongokit 3.38.1 → 3.39.0

package/dist/{method-registry.plugin-DblM7V6j.mjs → method-registry.plugin-C63pGn1d.mjs}

@@ -16,6 +16,58 @@ import { t as createError } from "./error-BuByZwKU.mjs";
 * // bulkWrite is what this plugin contributes.
 * await repo.bulkWrite([...ops]);
 */
+/**
+* Driver options `bulkWrite` forwards, and the only ones it forwards.
+*
+* The signature used to be `{ session?, ordered?, [key: string]: unknown }` and
+* the call forwarded exactly two of them. So `writeConcern: { w: 'majority' }`
+* on a money import was accepted by the type, dropped on the floor, and the
+* write went out under the default concern with nothing raised.
+*/
+const BULK_WRITE_OPTIONS = [
+	"ordered",
+	"session",
+	"writeConcern",
+	"bypassDocumentValidation",
+	"comment",
+	"let",
+	"ignoreUndefined"
+];
+/**
+* Driver options that EXIST but this method does not forward.
+*
+* The options bag is dual-purpose by design: it is spread into
+* `_buildContext`, so it also carries plugin context — `organizationId` for
+* multi-tenant scoping, and whatever else a host's plugins read off it.
+* Refusing every unrecognised key therefore breaks legitimate callers, which
+* is exactly how the first version of this fence failed: it rejected the
+* tenant id and took two passing tests with it.
+*
+* So the line sits where the caller's expectation is. If the DRIVER would
+* understand the option and we would silently not pass it on, refuse — that is
+* the case where someone believes they configured the write. A key the driver
+* does not know either is plugin context, and passes through untouched.
+*/
+const UNSUPPORTED_DRIVER_OPTIONS = /* @__PURE__ */ new Set([
+	"forceServerObjectId",
+	"timeoutMS",
+	"maxTimeMS",
+	"retryWrites",
+	"checkKeys",
+	"serializeFunctions",
+	"enableUtf8Validation",
+	"raw",
+	"explain"
+]);
+/** Narrow the bag to driver options, refusing the ones we would silently drop. */
+function pickBulkWriteOptions(options) {
+	const dropped = Object.keys(options).filter((k) => UNSUPPORTED_DRIVER_OPTIONS.has(k));
+	if (dropped.length > 0) throw createError(400, `bulkWrite: option(s) ${dropped.map((k) => `'${k}'`).join(", ")} are MongoDB driver options this method does not forward. Refused rather than ignored, because silently dropping one changes what the write does. Supported: ${BULK_WRITE_OPTIONS.join(", ")}.`);
+	const out = {};
+	for (const key of BULK_WRITE_OPTIONS) if (options[key] !== void 0) out[key] = options[key];
+	out.ordered = options.ordered ?? true;
+	return out;
+}
 function batchOperationsPlugin() {
 	return {
 		name: "batch-operations",
@@ -36,6 +88,7 @@ function batchOperationsPlugin() {
 			* ]);
 			*/
 			repo.registerMethod("bulkWrite", async function(operations, options = {}) {
+				const driverOptions = pickBulkWriteOptions(options);
 				const context = await this._buildContext("bulkWrite", {
 					operations,
 					...options
@@ -43,10 +96,7 @@ function batchOperationsPlugin() {
 				try {
 					const finalOps = context.operations || operations;
 					if (!finalOps || finalOps.length === 0) throw createError(400, "bulkWrite requires at least one operation");
-					const result = await this.Model.bulkWrite(finalOps, {
-						ordered: options.ordered ?? true,
-						session: options.session
-					});
+					const result = await this.Model.bulkWrite(finalOps, driverOptions);
 					const bulkResult = {
 						ok: result.ok,
 						insertedCount: result.insertedCount,

package/dist/{multi-tenant.plugin-BwSvTirB.d.mts → multi-tenant.plugin-B-tzNeYL.d.mts}

@@ -1,5 +1,5 @@
-import { i as ObjectId } from "./core-62oo3N1C.mjs";
-import { l as Plugin, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
+import { g as ObjectId } from "./pagination-BpIv2bdS.mjs";
+import { l as Plugin, p as RepositoryContext } from "./repository-ZbLtL7Nk.mjs";
 import mongoose, { Connection } from "mongoose";
 import { CacheAdapter as CacheAdapter$1, CacheOptions, RepositoryCacheHandle as RepositoryCacheHandle$1, RepositoryCachePluginOptions, cachePlugin } from "@classytic/repo-core/cache";
 import { TenantConfig } from "@classytic/repo-core/tenant";
@@ -312,7 +312,10 @@ interface SequentialIdOptions {
   prefix: string;
   /** Mongoose model — used to derive the counter key from model name */
   model: mongoose.Model<any>;
-  /** Number of digits to pad to (default: 4 → "0001") */
+  /**
+   * MINIMUM number of digits (default: 4 → "0001"). Never truncates —
+   * sequence 10000 under `padding: 4` renders as `INV-10000`.
+   */
   padding?: number;
   /** Separator between prefix and number (default: '-') */
   separator?: string;
@@ -346,10 +349,54 @@ interface DateSequentialIdOptions {
    * - 'daily'   → BILL-2026-02-20-0001, resets every day
    */
   partition?: 'yearly' | 'monthly' | 'daily';
-  /** Number of digits to pad to (default: 4) */
+  /**
+   * MINIMUM number of digits for the sequence (default: 4). `padStart` never
+   * truncates, so the 10,000th id of a period under `padding: 4` is
+   * `BILL-2026-10000` — it grows a digit rather than wrapping to `0000`.
+   * Lexical sort order therefore only holds while a period stays below
+   * 10^padding; size the padding for your peak period.
+   */
   padding?: number;
   /** Separator (default: '-') */
   separator?: string;
+  /**
+   * Counter scope.
+   * - `'global'` (default) — one counter per model + period, shared by
+   *   every tenant in the database. Ids are unique across the deployment.
+   * - `'tenant'` — one counter per tenant + model + period, keyed by
+   *   `context[tenantKey]`. Every tenant's numbering starts at 1 (Shopify-
+   *   style per-shop order numbers) and the write hot spot on the single
+   *   shared counter document splits per tenant. Ids are unique WITHIN a
+   *   tenant only — index the field compound with the tenant field.
+   *   Fails closed: a create with no tenant in context throws rather than
+   *   falling back to the global key, which would silently merge two
+   *   tenants' sequences.
+   */
+  scope?: 'global' | 'tenant';
+  /**
+   * Context key carrying the tenant id under `scope: 'tenant'` (default:
+   * `'organizationId'` — the same default as `multiTenantPlugin`'s
+   * `contextKey`, so `repo.create(data, { organizationId })` feeds both).
+   */
+  tenantKey?: string;
+  /**
+   * Which clock decides the period boundary.
+   *
+   * - `'local'` (default) — the server's `TZ`. Kept as the default because it
+   *   is what every existing deployment already generated: flipping it would
+   *   retroactively change which period an id near a month boundary belongs
+   *   to, and those ids are invoice and order numbers.
+   * - `'utc'` — **the correct choice for more than one replica.** Two replicas
+   *   with different `TZ` settings derive different counter keys for the same
+   *   logical month and each increments its own, so the same number is issued
+   *   twice inside one tenant-period. UTC is the one boundary every replica
+   *   agrees on. It also matches the ecosystem's other period key,
+   *   `usagePeriod()` in `@classytic/repo-core/usage`.
+   *
+   * Containers usually run UTC anyway, which is exactly why the difference
+   * stays invisible until one host is configured otherwise.
+   */
+  timezone?: 'local' | 'utc';
 }
 /**
  * Generator: Date-partitioned sequential counter.
@@ -371,6 +418,15 @@ interface DateSequentialIdOptions {
  *   }),
  * })
  * ```
+ *
+ * @example Per-tenant numbering in a shared database
+ * ```typescript
+ * customIdPlugin({
+ *   field: 'orderNumber',
+ *   generator: dateSequentialId({ prefix: 'ORD', model: OrderModel, scope: 'tenant' }),
+ * })
+ * // org-a: ORD-2026-02-0001, ORD-2026-02-0002 …   org-b: ORD-2026-02-0001 …
+ * ```
  */
 declare function dateSequentialId(options: DateSequentialIdOptions): IdGenerator;
 interface PrefixedIdOptions {

package/dist/{operations-DZodvjC-.d.mts → operations-CrRIoc8Z.d.mts}

@@ -1,5 +1,4 @@
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, o as ReadPreferenceType, s as SelectSpec } from "./core-62oo3N1C.mjs";
-import { r as CollationOptions } from "./pagination-jSUdrACK.mjs";
+import { _ as PopulateSpec, g as ObjectId, i as CountStrategy, r as CollationOptions, v as ReadPreferenceType, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
 import { DeleteManyResult, DeleteResult, LookupPopulateResult, UpdateManyResult } from "@classytic/repo-core/repository";
 import { PipelineStage, PopulateOptions } from "mongoose";
 import { Filter } from "@classytic/repo-core/filter";
@@ -383,9 +382,21 @@ interface WithTransactionOptions {
 }
 /** Create operation options */
 interface CreateOptions extends SessionOptions {
-  /** Keep insertion order on error (default: false).
-   * When false, all valid documents insert even if some fail (e.g. duplicates).
-   * Set to true to abort remaining inserts on first error. */
+  /**
+   * Keep insertion order on error. **Default `false`, which is the OPPOSITE of
+   * the MongoDB driver's own default** — a deliberate choice for import
+   * throughput, pinned by `tests/integration/createMany-partial-failure.test.ts`.
+   *
+   * The consequence is worth stating plainly, because it is the part that
+   * surprises: with `false`, a REJECTED `createMany` can still have written
+   * documents. Every valid document inserts and only the failures are reported,
+   * so a caller that treats the rejection as "nothing happened" and retries
+   * will double-insert everything that succeeded the first time.
+   *
+   * Retryable imports therefore need a unique index or an idempotency key —
+   * not a try/catch. Pass `ordered: true` when the batch is an all-or-nothing
+   * business operation, and a transaction when it must also be atomic.
+   */
   ordered?: boolean;
 }
 /** Update operation options */
@@ -485,14 +496,18 @@ interface LookupPopulateOptions<TBase = unknown> {
   page?: number;
   /** Cursor token for next page (keyset mode) */
   after?: string;
+  /** Cursor token for the PREVIOUS page (keyset mode). Mutually exclusive with `after`. */
+  before?: string;
   /** Number of documents per page */
   limit?: number;
   /** Fields to select */
   select?: SelectSpec;
   /** Collation for locale-aware string comparison */
   collation?: CollationOptions;
-  /** Count strategy for offset pagination */
-  countStrategy?: 'exact' | 'estimated' | 'none';
+  /** Count strategy for offset pagination. See {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'` (default 10000). */
+  countLimit?: number;
   /**
    * Transaction session. Typed `unknown` to match repo-core's
    * `RepositorySession` contract — mongokit narrows to `ClientSession`

package/dist/outbox/index.d.mts

@@ -1,4 +1,4 @@
-import { n as Repository } from "../Repository-BdSkQ8vc.mjs";
+import { n as Repository } from "../Repository-IxI983_m.mjs";
 import { Connection, Model } from "mongoose";
 //#region src/outbox/index.d.ts
 /** Delivery states. `dead_letter` is terminal and operator-visible. */

package/dist/outbox/index.mjs

@@ -1,5 +1,5 @@
-import { n as Repository } from "../Repository-Ck5x43wF.mjs";
-import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.mjs";
+import { n as Repository } from "../Repository-D7fDpyFx.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-C63pGn1d.mjs";
 import { Schema } from "mongoose";
 //#region src/outbox/index.ts
 /**

package/dist/pagination/PaginationEngine.d.mts

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-CBS1XGzp.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-D-P19Y9m.mjs";
 export { PaginationEngine };

package/dist/pagination/PaginationEngine.mjs

@@ -1,2 +1,2 @@
-import { t as PaginationEngine } from "../PaginationEngine-BX9o_-4R.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-DQ7beTCR.mjs";
 export { PaginationEngine };

package/dist/pagination/utils/limits.d.mts

@@ -1,4 +1,4 @@
-import { c as PaginationConfig } from "../../pagination-jSUdrACK.mjs";
+import { u as PaginationConfig } from "../../pagination-BpIv2bdS.mjs";
 //#region src/pagination/utils/limits.d.ts
 /**
  * Validates and sanitizes limit value

package/dist/pagination/utils/limits.mjs

@@ -1,3 +1,4 @@
+import { t as createError } from "../../error-BuByZwKU.mjs";
 //#region src/pagination/utils/limits.ts
 /**
 * Validates and sanitizes limit value
@@ -27,7 +28,27 @@ function validatePage(page, config) {
 	const parsed = Number(page);
 	if (!Number.isFinite(parsed) || parsed < 1) return 1;
 	const sanitized = Math.floor(parsed);
-	if (sanitized > (config.maxPage || 1e4)) throw new Error(`Page ${sanitized} exceeds maximum ${config.maxPage || 1e4}`);
+	const max = config.maxPage || 1e4;
+	if (sanitized > max)
+ /**
+	* 400, not a bare `Error`.
+	*
+	* The page number comes from the querystring, so this is the caller's
+	* mistake — a crawler walking past the end, a fuzzer, a stale deep link.
+	* A bare `Error` carries no status, so every framework above maps it to
+	* `internal_error` 500: the request is refused either way, but one of them
+	* pages an on-call engineer and burns an error budget over `?page=999999`.
+	*
+	* It matters more the lower `maxPage` is set, and a deployment that has
+	* tuned it down for the skip cost is exactly the one getting this traffic.
+	*/
+	throw createError(400, `Page ${sanitized} exceeds maximum ${max}`, {
+		code: "PAGE_OUT_OF_RANGE",
+		meta: {
+			page: sanitized,
+			maxPage: max
+		}
+	});
 	return sanitized;
 }
 /**

package/dist/pagination-BpIv2bdS.d.mts

@@ -0,0 +1,364 @@
+import { Document, Model, PipelineStage, PopulateOptions, Types } from "mongoose";
+//#region src/types/core.d.ts
+/**
+ * Core query/document primitives shared across every mongokit module —
+ * sort/select/populate/filter specs and the mongoose-facing aliases.
+ *
+ * Also the home of the `softRequired` Mongoose declaration merge (this file
+ * is loaded by every module, so the augmentation is always in the program).
+ */
+/**
+ * Global declaration merge: adds `softRequired` to Mongoose's SchemaTypeOptions
+ * so consumers can annotate paths type-safely without importing anything.
+ *
+ * A path with `softRequired: true` keeps its DB-level `required: true`
+ * invariant but is excluded from the auto-generated CRUD body `required[]`
+ * array (see buildCrudSchemasFromModel).
+ */
+declare module 'mongoose' {
+  interface SchemaTypeOptions<T, EnforcedDocType = any, THydratedDocumentType = HydratedDocument<EnforcedDocType>> {
+    /** mongokit: omit from auto-generated CRUD body `required` array. */
+    softRequired?: boolean;
+  }
+}
+/** Read Preference Type for replica sets */
+type ReadPreferenceType = 'primary' | 'primaryPreferred' | 'secondary' | 'secondaryPreferred' | 'nearest' | (string & {});
+/** Re-export mongoose ObjectId */
+type ObjectId = Types.ObjectId;
+/** Generic document type */
+type AnyDocument = Document & Record<string, unknown>;
+/** Generic model type */
+type AnyModel = Model<AnyDocument>;
+/** Sort direction */
+type SortDirection = 1 | -1;
+/** Sort specification for MongoDB queries */
+type SortSpec = Record<string, SortDirection>;
+/** Populate specification */
+type PopulateSpec = string | string[] | PopulateOptions | PopulateOptions[];
+/**
+ * Select specification. `readonly string[]` widens the legacy `string[]`
+ * form to also accept the immutable variant repo-core's contract uses
+ * (`LookupPopulateOptions.select: readonly string[] | Record<string, 0
+ * | 1>`), so `Repository<TDoc>` assigns to `StandardRepo<TDoc>` without
+ * TS2322 on the `select` field. Any existing mutable-array caller stays
+ * compatible — `string[]` is assignable to `readonly string[]`.
+ */
+type SelectSpec = string | readonly string[] | Record<string, 0 | 1>;
+/** Filter query type for MongoDB queries (compatible with Mongoose 8 & 9) */
+type FilterQuery<_T = unknown> = Record<string, unknown>;
+//#endregion
+//#region src/pagination/utils/cursor-signing.d.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.
+ */
+/** One key, or several during a rotation (the FIRST signs; all verify). */
+type CursorSecret = string | readonly string[];
+//#endregion
+//#region src/types/pagination.d.ts
+/**
+ * How an offset page learns how many rows sit behind it.
+ *
+ * | | cost | `total` reports |
+ * |---|---|---|
+ * | `exact` | O(matching index keys) — the whole range, every page | the truth |
+ * | `estimated` | O(1) collection metadata, but IGNORES filters, so it falls back to `exact` whenever any filter is present | the truth, or the collection size |
+ * | `capped` | O(countLimit) — the scan stops at the ceiling | the truth below the ceiling, else the ceiling, with `totalIsLowerBound: true` |
+ * | `none` | free — `limit + 1` is fetched instead | `0` |
+ *
+ * `exact` is the default and is right until a filter matches enough rows for
+ * the count to outgrow the find it runs beside. Past that it is the dominant
+ * cost of a page the user reads fifteen rows of, and it is paid again on every
+ * page.
+ *
+ * `capped` is what a product ships instead: the row count a list header shows
+ * is only actionable while it is small, so bound the work and say `10,000+`
+ * above the bound. Elasticsearch (`track_total_hits`), Odoo (`search_count`'s
+ * limit) and GitHub's `1000+` are all this strategy.
+ *
+ * Declared ONCE and referenced everywhere — this union was hand-copied to eight
+ * declarations, which is how the aggregate variant silently lost a member.
+ */
+type CountStrategy = 'exact' | 'estimated' | 'capped' | 'none';
+/**
+ * What mongokit adds to repo-core's offset envelope, via its reserved `TExtra`
+ * slot: `OffsetPaginationResult<TDoc, MongokitPageExtras>`.
+ *
+ * Both members are optional and absent on an ordinary page, so every existing
+ * consumer of `OffsetPaginationResult<TDoc>` stays assignable.
+ *
+ * A `type` and not an `interface`: repo-core constrains `TExtra` to
+ * `Record<string, unknown>`, and an interface has no implicit index signature.
+ */
+type MongokitPageExtras = {
+  /** Deep-page or clamped-limit advice. Human-readable; never branch on it. */
+  warning?: string;
+  /**
+   * `total` is a FLOOR, not a count — the scan stopped at `countLimit`. Render
+   * it as `10,000+`, and never compute a percentage or a last-page number from
+   * a total carrying this flag.
+   *
+   * A separate boolean rather than a sentinel `total` (`-1`, `null`): a total
+   * that lies in a field typed `number` is read as a number by every consumer
+   * that has not been taught otherwise, which is the failure this flag exists
+   * to make impossible to miss.
+   */
+  totalIsLowerBound?: boolean;
+};
+/** Pagination configuration */
+interface PaginationConfig {
+  /** Default number of documents per page (default: 10) */
+  defaultLimit?: number;
+  /** Maximum allowed limit (default: 100) */
+  maxLimit?: number;
+  /** Maximum allowed page number (default: 10000) */
+  maxPage?: number;
+  /** Page number that triggers performance warning (default: 100) */
+  deepPageThreshold?: number;
+  /** Cursor version for forward compatibility (default: 1) */
+  cursorVersion?: number;
+  /**
+   * Minimum cursor version accepted. Bump alongside `cursorVersion` when a
+   * breaking format change ships so stale client cursors are rejected with a
+   * clear error instead of silently paginating from the wrong position.
+   * Default: 1 (accept any cursor <= cursorVersion).
+   */
+  minCursorVersion?: number;
+  /**
+   * Allowlist of primary sort fields for keyset pagination. When set, any
+   * `getAll({ sort })` whose primary (non-_id) field is not in this list
+   * throws at validation time.
+   *
+   * Use this to lock down keyset pagination to fields that are structurally
+   * guaranteed non-null in your schema — keyset sort across null/non-null
+   * boundaries is lossy (MongoDB's `$lt/$gt` semantics leave a gap at the
+   * type boundary, so not every doc is reachable).
+   *
+   * `_id` is always allowed regardless of this list.
+   * Undefined (default) = no allowlist, any sort field accepted.
+   */
+  strictKeysetSortFields?: string[];
+  /** Use estimatedDocumentCount for faster counts on large collections */
+  useEstimatedCount?: boolean;
+  /**
+   * Repo-wide `countStrategy` for `getAll` / `lookupPopulate` /
+   * `aggregatePaginate` calls that don't set their own (default: 'exact' —
+   * a `countDocuments` round-trip per page). `'none'` suits list endpoints
+   * that only need `hasNext`: one query per page, `total` / `pages` report
+   * 0. A per-call `countStrategy` always wins.
+   */
+  defaultCountStrategy?: CountStrategy;
+  /**
+   * Ceiling for `countStrategy: 'capped'` when a call names none. Default 10000.
+   * See {@link OffsetPaginationOptions.countLimit}.
+   */
+  defaultCountLimit?: number;
+  /**
+   * HMAC key for cursor tokens. Absent (default) = cursors are unsigned, as
+   * before. A list rotates keys: the FIRST signs, all of them verify.
+   *
+   * Signing stops a caller EDITING a cursor to move the position — re-submit a
+   * tampered sort value and the response says whether any row sorts past it,
+   * which is a binary search over a column the caller may never read. It does
+   * NOT hide the token's contents: the payload stays readable base64url JSON.
+   * Integrity, not confidentiality.
+   *
+   * **Switching it on is a cutover.** Cursors already in flight carry no
+   * signature and will be refused — the client restarts from page one. That is
+   * deliberate: a "tolerate unsigned during rollout" flag is a permanent
+   * downgrade switch, and stripping the signature is the first thing an
+   * attacker tries.
+   *
+   * A key under 16 characters throws rather than being accepted, because an
+   * unset environment variable reads as `''` and would otherwise mean "signing
+   * on, key guessable" with nothing to say so.
+   */
+  cursorSecret?: CursorSecret;
+  /**
+   * Repo-wide pagination mode for a `getAll` call that carries no explicit
+   * `mode`, no `page` and no cursor (`after`) — the plain
+   * `getAll({ filters })` case, which otherwise picks offset (or keyset
+   * only when a non-default sort is given). `'keyset'` makes those calls
+   * cursor-paginated: no `skip`, O(1) deep pages. Explicit per-call
+   * signals still win — `page` → offset, `after` → keyset, `mode` → as
+   * given. Default: undefined (the sort-based auto-detection above).
+   */
+  defaultMode?: 'offset' | 'keyset';
+}
+/** MongoDB collation options for locale-aware string comparison */
+interface CollationOptions {
+  locale: string;
+  caseLevel?: boolean;
+  caseFirst?: 'upper' | 'lower' | 'off';
+  strength?: 1 | 2 | 3 | 4 | 5;
+  numericOrdering?: boolean;
+  alternate?: 'non-ignorable' | 'shifted';
+  maxVariable?: 'punct' | 'space';
+  backwards?: boolean;
+}
+/** Base pagination options */
+interface BasePaginationOptions {
+  /** Pagination mode (explicit override) */
+  mode?: 'offset' | 'keyset';
+  /** MongoDB query filters */
+  filters?: FilterQuery<AnyDocument>;
+  /** Sort specification */
+  sort?: SortSpec;
+  /** Number of documents per page */
+  limit?: number;
+  /** Fields to select */
+  select?: SelectSpec;
+  /** Fields to populate */
+  populate?: PopulateSpec;
+  /** Return plain JavaScript objects */
+  lean?: boolean;
+  /** MongoDB session for transactions */
+  session?: unknown;
+  /** Query hint (index name or document) */
+  hint?: string | Record<string, 1 | -1>;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+  /** Collation for locale-aware string comparison and case-insensitive sorting */
+  collation?: CollationOptions;
+}
+/** Offset pagination options */
+interface OffsetPaginationOptions extends BasePaginationOptions {
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Count strategy for filtered queries (default: 'exact'). See {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /**
+   * Ceiling for `countStrategy: 'capped'` (default: the repository's
+   * `defaultCountLimit`, else 10000). Ignored by every other strategy.
+   *
+   * A `total` that comes back EQUAL to this is a lower bound, not a count —
+   * `totalIsLowerBound` on the result says so, because `total === countLimit`
+   * is also what an exactly-full collection legitimately returns and the two
+   * are otherwise indistinguishable.
+   */
+  countLimit?: number;
+  /**
+   * Optional alternate filter used for the count query only. The primary
+   * `filters` is still used for `.find()`. Lets callers (Repository) run a
+   * sort-only query like `$near` for results while counting with a
+   * count-compatible rewrite (e.g. `$geoWithin: $centerSphere`) that
+   * returns the same document set but works with `countDocuments`.
+   */
+  countFilters?: FilterQuery<AnyDocument>;
+}
+/** Keyset (cursor) pagination options */
+interface KeysetPaginationOptions extends BasePaginationOptions {
+  /** Cursor token for next page */
+  after?: string;
+  /**
+   * Cursor token for the PREVIOUS page — the page ending just before this
+   * position. Mutually exclusive with `after`; passing both throws.
+   *
+   * Feed back the `prev` from a result. Rows come back in the sort order you
+   * asked for, not reversed: the query runs inverted internally and the page
+   * is turned back around before it is returned.
+   */
+  before?: string;
+  /** Sort is required for keyset pagination */
+  sort: SortSpec;
+}
+/** Aggregate pagination options */
+interface AggregatePaginationOptions {
+  /** Aggregation pipeline stages */
+  pipeline?: PipelineStage[];
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Number of documents per page */
+  limit?: number;
+  /** MongoDB session for transactions */
+  session?: unknown;
+  /** Query hint (index name or document) for aggregation */
+  hint?: string | Record<string, 1 | -1>;
+  /** Maximum execution time in milliseconds */
+  maxTimeMS?: number;
+  /** Count strategy (default: 'exact' via $facet).
+   * 'estimated' is accepted but treated as 'exact' in aggregation context
+   * since estimatedDocumentCount is not available inside pipelines.
+   * 'capped' bounds the count facet with a `$limit` — see {@link CountStrategy}. */
+  countStrategy?: CountStrategy;
+  /** Ceiling for `countStrategy: 'capped'`. See {@link OffsetPaginationOptions.countLimit}. */
+  countLimit?: number;
+  /**
+   * Let `$sort` / `$group` spill to disk past the server's 100MB per-stage
+   * memory limit. Off by default — spilling hides a missing index behind a
+   * slow success, and on MongoDB >= 6.0 the server's own
+   * `allowDiskUseByDefault` already decides this when a caller says nothing.
+   */
+  allowDiskUse?: boolean;
+  /** Pagination mode (reserved for API consistency) */
+  mode?: 'offset';
+  /** Read preference for replica sets (e.g. 'secondaryPreferred') */
+  readPreference?: ReadPreferenceType;
+}
+/** Value type identifier for cursor serialization */
+type ValueType = 'date' | 'objectid' | 'boolean' | 'number' | 'string' | 'null' | 'unknown';
+/** Cursor payload */
+interface CursorPayload {
+  /** Primary sort field value (legacy single-field) */
+  v: string | number | boolean | null;
+  /** Value type identifier (legacy single-field) */
+  t: ValueType;
+  /** Document ID */
+  id: string;
+  /** ID type identifier */
+  idType: ValueType;
+  /** Sort specification */
+  sort: SortSpec;
+  /** Cursor version */
+  ver: number;
+  /** Compound sort field values (multi-field keyset) */
+  vals?: Record<string, string | number | boolean | null>;
+  /** Compound sort value types */
+  types?: Record<string, ValueType>;
+}
+/** Decoded cursor */
+interface DecodedCursor {
+  /** Primary sort field value (rehydrated) — legacy compat */
+  value: unknown;
+  /** Document ID (rehydrated) */
+  id: ObjectId | string;
+  /** Sort specification */
+  sort: SortSpec;
+  /** Cursor version */
+  version: number;
+  /** All sort field values (rehydrated) — for compound sort */
+  values?: Record<string, unknown>;
+}
+//#endregion
+export { PopulateSpec as _, CursorPayload as a, SortDirection as b, MongokitPageExtras as c, ValueType as d, CursorSecret as f, ObjectId as g, FilterQuery as h, CountStrategy as i, OffsetPaginationOptions as l, AnyModel as m, BasePaginationOptions as n, DecodedCursor as o, AnyDocument as p, CollationOptions as r, KeysetPaginationOptions as s, AggregatePaginationOptions as t, PaginationConfig as u, ReadPreferenceType as v, SortSpec as x, SelectSpec as y };

package/dist/{plugin-options-DXnlKM3B.d.mts → plugin-options-BuvtOSZf.d.mts}

@@ -1,5 +1,5 @@
-import { a as PopulateSpec, i as ObjectId, l as SortSpec, s as SelectSpec } from "./core-62oo3N1C.mjs";
-import { h as RepositoryInstance, p as RepositoryContext } from "./repository-H_ffGgpE.mjs";
+import { _ as PopulateSpec, g as ObjectId, x as SortSpec, y as SelectSpec } from "./pagination-BpIv2bdS.mjs";
+import { h as RepositoryInstance, p as RepositoryContext } from "./repository-ZbLtL7Nk.mjs";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
 //#region src/types/plugin-options.d.ts
 /** Field preset configuration (field-filter plugin) */