@classytic/mongokit 3.40.0 → 3.41.0

package/README.md

@@ -170,6 +170,18 @@ const next = await repo.getAll({
 });
 ```
 
+Every sort gets a unique `_id` tiebreaker and `hasNext` comes from a limit+1 fetch. Offset pages
+report `{ total, totalIsEstimate, countedAt }` under every `countStrategy` (`exact`, `capped`,
+`estimated`, `none`, `cached`); a `skip` past `maxOffset` (default 100,000) is refused with
+`mongokit.pagination.offset_too_deep`. A cursor is bound to its collection, filter (tenant
+included) and collation: replayed elsewhere it is `repo.cursor.scope_mismatch` (repo-core `CURSOR_ERROR_CODES`); set
+`cursorSecret` so tampering is detected too.
+
+```ts
+// Boot: the deployment's list policy.
+configurePaginationDefaults({ defaultCountStrategy: 'capped', cursorSecret, maxOffset: 50_000 });
+```
+
 ### Transactions
 
 ```ts
@@ -189,6 +201,55 @@ await orderRepo.withTransaction(async (txRepo) => {
 });
 ```
 
+### Time Bounds And Concerns (`queryDefaults`)
+
+```ts
+// Boot: every command is bounded; the boot check fails without it (and without CSOT timeoutMS).
+await mongoose.connect(uri, { timeoutMS: 30_000 });
+configureQueryDefaults({ maxTimeMS: 5_000, writeConcern: { w: 'majority' } });
+configureAggregateDefaults({ maxTimeMs: 15_000 });
+assertQueryDefaultsConfigured(mongoose.connection);
+
+// Per repository, and per call (per call always wins):
+const repo = new Repository(Order, plugins, {}, { queryDefaults: { comment: 'orders' } });
+await repo.findAll(filter, { maxTimeMS: 500 });
+```
+
+### Joins Are Scoped
+
+A `$lookup` / `$unionWith` / `$graphLookup` reads the joined collection under its own repository's
+tenant and soft-delete scope. Take `from` from `Model.collection.name`: a name no model owns throws
+`mongokit.join.unknown_collection`, a collection no repository governs throws
+`mongokit.join.ungoverned_collection` (list a company-wide one in `unscopedJoins`).
+
+### Batch Reads (`getByIds`)
+
+```ts
+const byId = await repo.getByIds(ids, { select: 'name sku' });              // Map, chunked $in
+const rows = await repo.getByIds(ids, { preserveOrder: true, chunkSize: 5_000 }); // aligned, undefined = miss
+```
+
+### Read Models (`bulkUpsert`, `@classytic/mongokit/read-model`)
+
+```ts
+const res = await totals.bulkUpsert(rows, { key: ['period', 'rate'], inc: ['tax'], organizationId });
+// res.results[i].outcome: 'inserted' | 'updated' | 'unchanged' | 'failed' (+ code). Needs MongoDB 8.0.
+
+import { applyIncrements, rebuildInto, reconcile } from '@classytic/mongokit/read-model';
+await applyIncrements(totals, grains, { session, ledger, organizationId }); // inside the posting transaction
+await rebuildInto(facts, totals, { pipeline, on: ['organizationId', 'period', 'rate'], scope: { organizationId } });
+const { drift } = await reconcile(facts, totals, { pipeline, on, measures: ['tax'], scope: { organizationId } });
+```
+
+### Resumable Sweeps (`iterate`)
+
+```ts
+for await (const { docs, checkpoint } of repo.iterate(filter, { batchSize: 1_000, after: saved, organizationId })) {
+  await process(docs);
+  await saveCheckpoint(checkpoint); // resume later with { after: checkpoint }
+}
+```
+
 ### Change Streams
 
 ```ts
@@ -430,6 +491,16 @@ Atlas **`$search` / `$vectorSearch`** indexes are Atlas-only and don't exist on
 
 All accept `{ replset?, dbName?, uri? }`.
 
+### Query-plan gate
+
+```ts
+import { assertQueryPlan } from '@classytic/mongokit/testkit';
+// The connection must be opened with { monitorCommands: true }.
+await assertQueryPlan(() => repo.getAll({ filters: { status: 'open' }, sort: { at: -1 } }), {
+  connection, minDocs: 1_000, leadingKeys: ['status', 'at'],   // fails on COLLSCAN / unindexed SORT
+});
+```
+
 ## Kernel Conformance — `@classytic/mongokit/kernel-conformance`
 
 An **executable contract suite** for domain kernels built on `defineModels()`. A kernel that

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

@@ -1,5 +1,6 @@
-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 { D as AnyDocument, c as MongokitPageExtras, f as CursorSecret, i as CountStrategy, l as OffsetPaginationOptions, s as KeysetPaginationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-D6psses0.mjs";
 import { Model } from "mongoose";
+import { TtlMemo } from "@classytic/repo-core/cache";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult } from "@classytic/repo-core/pagination";
 //#region src/pagination/PaginationEngine.d.ts
 /**
@@ -18,11 +19,17 @@ interface ResolvedPaginationConfig {
   defaultCountLimit: number;
   cursorSecret: CursorSecret | undefined;
   defaultMode: 'offset' | 'keyset' | undefined;
+  maxOffset: number;
+  countCacheTtlMs: number;
 }
 /**
  * Production-grade pagination engine for MongoDB
  * Supports offset, keyset (cursor), and aggregate pagination
  */
+interface CountMemoKey {
+  key: string;
+  run: () => Promise<number>;
+}
 declare class PaginationEngine<TDoc = AnyDocument> {
   readonly Model: Model<TDoc>;
   readonly config: ResolvedPaginationConfig;
@@ -37,6 +44,13 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    * @param Model - Mongoose model to paginate
    * @param config - Pagination configuration
    */
+  /** Memoised capped counts for `countStrategy: 'cached'`, rebuilt when the TTL changes. */
+  private _memo;
+  /** The `cached` count memo (repo-core `createTtlMemo`: single flight, a failed count caches nothing). */
+  _countMemo(): TtlMemo<CountMemoKey, {
+    total: number;
+    countedAt: Date;
+  }>;
   constructor(Model: Model<TDoc, any, any, any>, config?: PaginationConfig);
   /** Memoized schema index lookup — avoids re-walking schema on every stream(). */
   private _getSchemaIndexes;
@@ -122,7 +136,7 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    *   limit: 20
    * });
    */
-  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc>>;
+  aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc, MongokitPageExtras>>;
 }
 //#endregion
-export { PaginationEngine as t };
+export { PaginationEngine as n, CountMemoKey as t };