@classytic/mongokit 3.38.1 → 3.40.0

package/dist/{PaginationEngine-CBS1XGzp.d.mts → PaginationEngine-D-P19Y9m.d.mts}

@@ -1,5 +1,4 @@
-import { t as AnyDocument } from "./core-62oo3N1C.mjs";
-import { c as PaginationConfig, o as KeysetPaginationOptions, s as OffsetPaginationOptions, t as AggregatePaginationOptions } from "./pagination-jSUdrACK.mjs";
+import { c as MongokitPageExtras, f as CursorSecret, i as CountStrategy, l as OffsetPaginationOptions, p as AnyDocument, s as KeysetPaginationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-BpIv2bdS.mjs";
 import { Model } from "mongoose";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 //#region src/pagination/PaginationEngine.d.ts
@@ -15,6 +14,10 @@ interface ResolvedPaginationConfig {
   minCursorVersion: number;
   strictKeysetSortFields: string[] | undefined;
   useEstimatedCount: boolean;
+  defaultCountStrategy: CountStrategy;
+  defaultCountLimit: number;
+  cursorSecret: CursorSecret | undefined;
+  defaultMode: 'offset' | 'keyset' | undefined;
 }
 /**
  * Production-grade pagination engine for MongoDB
@@ -54,11 +57,21 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    * });
    * console.log(result.data, result.total, result.hasNext);
    */
-  paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc>>;
+  paginate(options?: OffsetPaginationOptions): Promise<OffsetPaginationResult<TDoc, MongokitPageExtras>>;
   /**
-   * 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
+   * Keyset (cursor-based) pagination for high-performance streaming.
+   * Best for large datasets, infinite scroll, real-time feeds.
+   *
+   * **Constant cost per page — but ONLY with an index that covers the whole
+   * sort, tiebreaker included.** Keyset removes `skip(n)`; it does not by
+   * itself remove a sort. `validateKeysetSort` appends `_id` to every sort, so
+   * an index stopping at the primary field leaves Mongo to order the ties
+   * itself: a blocking `SORT` over every row the filter matches, paid again on
+   * every page. Measured at 20,000 documents examined to return 20, against 20
+   * with the tiebreaker in the index.
+   *
+   * The dev-time warning below names the index to declare. Read it as a
+   * correctness requirement for the performance claim, not as advice.
    *
    * @param options - Pagination options (sort is required)
    * @returns Pagination result with next cursor
@@ -79,9 +92,21 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    */
   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
+   * Aggregate pipeline with pagination.
+   *
+   * Runs the page and the count as TWO pipelines, concurrently — not one
+   * `$facet`. `$facet` bundles every returned document and the count into a
+   * SINGLE output document, and no stage may exceed the 16MB BSON limit, so a
+   * page of large documents fails outright with `BSONObjectTooLarge` rather
+   * than paginating. `$facet` also cannot use an index for the stages inside
+   * it, so splitting is frequently the faster plan as well.
+   *
+   * The cost is that the two halves are separate reads and a concurrent write
+   * can land between them, so `total` may disagree with `data` by a document.
+   * That is already true of the offset path (`paginate` runs find and count
+   * through one `Promise.all`) — this makes aggregate consistent with it, and
+   * a count that is one row stale is a far smaller defect than a page that
+   * cannot be fetched at all. `countStrategy: 'none'` runs ONE pipeline.
    *
    * @param options - Aggregation options
    * @returns Pagination result with total count