@classytic/mongokit 3.36.0 → 3.39.0

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-BArvU32x.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-GdyX29tE.mjs";
+import { t as PaginationEngine } from "../PaginationEngine-DQ7beTCR.mjs";
 export { PaginationEngine };

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

@@ -0,0 +1,47 @@
+import { u as PaginationConfig } from "../../pagination-BpIv2bdS.mjs";
+//#region src/pagination/utils/limits.d.ts
+/**
+ * Validates and sanitizes limit value
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param limit - Requested limit
+ * @param config - Pagination configuration
+ * @returns Sanitized limit between 1 and maxLimit
+ */
+declare function validateLimit(limit: number | string, config: PaginationConfig): number;
+/**
+ * Validates and sanitizes page number
+ * Parses strings to numbers and prevents NaN bugs
+ *
+ * @param page - Requested page (1-indexed)
+ * @param config - Pagination configuration
+ * @returns Sanitized page number >= 1
+ * @throws Error if page exceeds maxPage
+ */
+declare function validatePage(page: number | string, config: PaginationConfig): number;
+/**
+ * Checks if page number should trigger deep pagination warning
+ *
+ * @param page - Current page number
+ * @param threshold - Warning threshold
+ * @returns True if warning should be shown
+ */
+declare function shouldWarnDeepPagination(page: number, threshold: number): boolean;
+/**
+ * Calculates number of documents to skip for offset pagination
+ *
+ * @param page - Page number (1-indexed)
+ * @param limit - Documents per page
+ * @returns Number of documents to skip
+ */
+declare function calculateSkip(page: number, limit: number): number;
+/**
+ * Calculates total number of pages
+ *
+ * @param total - Total document count
+ * @param limit - Documents per page
+ * @returns Total number of pages
+ */
+declare function calculateTotalPages(total: number, limit: number): number;
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

package/dist/pagination/utils/limits.mjs

@@ -0,0 +1,85 @@
+import { t as createError } from "../../error-BuByZwKU.mjs";
+//#region src/pagination/utils/limits.ts
+/**
+* Validates and sanitizes limit value
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param limit - Requested limit
+* @param config - Pagination configuration
+* @returns Sanitized limit between 1 and maxLimit
+*/
+function validateLimit(limit, config) {
+	const parsed = Number(limit);
+	if (!Number.isFinite(parsed) || parsed < 1) return config.defaultLimit ?? 10;
+	const max = config.maxLimit ?? 100;
+	if (max === 0) return Math.floor(parsed);
+	return Math.min(Math.floor(parsed), max);
+}
+/**
+* Validates and sanitizes page number
+* Parses strings to numbers and prevents NaN bugs
+*
+* @param page - Requested page (1-indexed)
+* @param config - Pagination configuration
+* @returns Sanitized page number >= 1
+* @throws Error if page exceeds maxPage
+*/
+function validatePage(page, config) {
+	const parsed = Number(page);
+	if (!Number.isFinite(parsed) || parsed < 1) return 1;
+	const sanitized = Math.floor(parsed);
+	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;
+}
+/**
+* Checks if page number should trigger deep pagination warning
+*
+* @param page - Current page number
+* @param threshold - Warning threshold
+* @returns True if warning should be shown
+*/
+function shouldWarnDeepPagination(page, threshold) {
+	return page > threshold;
+}
+/**
+* Calculates number of documents to skip for offset pagination
+*
+* @param page - Page number (1-indexed)
+* @param limit - Documents per page
+* @returns Number of documents to skip
+*/
+function calculateSkip(page, limit) {
+	return (page - 1) * limit;
+}
+/**
+* Calculates total number of pages
+*
+* @param total - Total document count
+* @param limit - Documents per page
+* @returns Total number of pages
+*/
+function calculateTotalPages(total, limit) {
+	return Math.ceil(total / limit);
+}
+//#endregion
+export { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage };

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) */

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
-import { S as RepositoryPluginName, b as MONGOKIT_PLUGIN_NAMES, l as Plugin, x as MongoKitPluginName } from "../repository-H_ffGgpE.mjs";
-import { A as ensureAuditTrailReady, C as AuditTrailMethods, D as AuditTrailQueryOptions, E as AuditTrailQuery, O as EnsureAuditTrailReadyOptions, S as AuditQueryResult, T as AuditTrailOptions, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, k as auditTrailPlugin, l as customIdPlugin, m as CacheAdapter, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailMode, x as AuditQueryOptions, y as AuditEntry } from "../multi-tenant.plugin-BwSvTirB.mjs";
-import { A as IdempotencyStoreMethods, B as auditLogPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, H as appendOnlyPlugin, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, S as methodRegistryPlugin, T as leasePlugin, U as AggregateHelpersMethods, V as AppendOnlyPluginOptions, W as aggregateHelpersPlugin, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, x as MethodRegistryRepository, y as MongoOperationsMethods, z as batchOperationsPlugin } from "../validation-chain.plugin-yQRob3Av.mjs";
+import { S as RepositoryPluginName, b as MONGOKIT_PLUGIN_NAMES, l as Plugin, x as MongoKitPluginName } from "../repository-ZbLtL7Nk.mjs";
+import { A as ensureAuditTrailReady, C as AuditTrailMethods, D as AuditTrailQueryOptions, E as AuditTrailQuery, O as EnsureAuditTrailReadyOptions, S as AuditQueryResult, T as AuditTrailOptions, _ as RepositoryCachePluginOptions, a as DateSequentialIdOptions, b as AuditOperation, c as SequentialIdOptions, d as getNextSequence, f as prefixedId, g as RepositoryCacheHandle, h as CacheOptions, i as CustomIdOptions, k as auditTrailPlugin, l as customIdPlugin, m as CacheAdapter, o as IdGenerator, p as sequentialId, r as multiTenantPlugin, s as PrefixedIdOptions, t as MultiTenantOptions, u as dateSequentialId, v as cachePlugin, w as AuditTrailMode, x as AuditQueryOptions, y as AuditEntry } from "../multi-tenant.plugin-B-tzNeYL.mjs";
+import { A as IdempotencyStoreMethods, B as auditLogPlugin, C as LeaseMethods, D as ImmutableStatesPluginOptions, E as ImmutableClaimView, F as elasticSearchPlugin, H as appendOnlyPlugin, I as cascadePlugin, L as BatchOperationsMethods, M as idempotencyStorePlugin, N as fieldFilterPlugin, O as immutableStatesPlugin, P as ElasticSearchOptions, S as methodRegistryPlugin, T as leasePlugin, U as AggregateHelpersMethods, V as AppendOnlyPluginOptions, W as aggregateHelpersPlugin, _ as OperationMetric, a as requireField, b as mongoOperationsPlugin, c as timestampPlugin, d as createTenantContext, f as SubdocumentMethods, g as ObservabilityOptions, h as softDeletePlugin, i as immutableField, j as IdempotencyStorePluginOptions, k as IdempotencyClaim, l as TenantContext, m as SoftDeleteMethods, n as autoInject, o as uniqueField, p as subdocumentPlugin, r as blockIf, s as validationChainPlugin, t as OperationType, u as TenantStore, v as observabilityPlugin, w as LeasePluginOptions, x as MethodRegistryRepository, y as MongoOperationsMethods, z as batchOperationsPlugin } from "../validation-chain.plugin-DvrLJIbJ.mjs";
 import { ChangeLogStore } from "@classytic/repo-core/sync";
 //#region src/plugins/change-log.plugin.d.ts
 interface ChangeLogPluginOptions {

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
-import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-BEc6TANm.mjs";
-import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-DblM7V6j.mjs";
-import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-CyK1s9Ze.mjs";
+import { a as customIdPlugin, c as prefixedId, d as AuditTrailQuery, f as auditTrailPlugin, i as multiTenantPlugin, l as sequentialId, m as auditLogPlugin, n as softDeletePlugin, o as dateSequentialId, p as ensureAuditTrailReady, s as getNextSequence, t as timestampPlugin, u as cachePlugin } from "../timestamp.plugin-B5eiaItQ.mjs";
+import { n as batchOperationsPlugin, t as methodRegistryPlugin } from "../method-registry.plugin-C63pGn1d.mjs";
+import { _ as cascadePlugin, a as uniqueField, c as subdocumentPlugin, d as mongoOperationsPlugin, f as leasePlugin, g as elasticSearchPlugin, h as fieldFilterPlugin, i as requireField, l as observabilityPlugin, m as idempotencyStorePlugin, n as blockIf, o as validationChainPlugin, p as immutableStatesPlugin, r as immutableField, s as createTenantContext, t as autoInject, u as MONGOKIT_PLUGIN_NAMES, v as appendOnlyPlugin, y as aggregateHelpersPlugin } from "../validation-chain.plugin-Bju1D1Sn.mjs";
 //#region src/plugins/change-log.plugin.ts
 const PLUGIN_NAME = "changeLog";
 function isSkipped(context) {