@classytic/mongokit 3.43.1 → 3.44.0

package/README.md

@@ -201,6 +201,8 @@ await orderRepo.withTransaction(async (txRepo) => {
 });
 ```
 
+To serialise writers on a row, the write must change it. An update that sets a field to the value it already has is a no-op: it takes no write lock, so two transactions doing it at the same instant never conflict. Write something that changes (for example `$inc: { writes: 1 }` on a gate or lease row).
+
 ### Time Bounds And Concerns (`queryDefaults`)
 
 ```ts
@@ -529,6 +531,18 @@ await assertQueryPlan(() => repo.getAll({ filters: { status: 'open' }, sort: { a
 });
 ```
 
+Reads are gated by default; pass `commands: ['findAndModify', 'update', 'delete']` to gate a write's match too.
+`explainCommands(run, { connection, commands?, collections?, verbosity? })` returns the raw explain of every
+command `run` sent (writes are explained, never re-run), for a plugin-built query such as a `leasePlugin` claim:
+
+```ts
+import { explainCommands } from '@classytic/mongokit/testkit';
+const { explains } = await explainCommands(() => jobs.lease({ leaseFor: 30_000, leasedBy }), {
+  connection, commands: ['findAndModify'], collections: ['jobs'],
+});
+explains[0].explain.executionStats; // what the claim examined
+```
+
 ## Kernel Conformance — `@classytic/mongokit/kernel-conformance`
 
 An **executable contract suite** for domain kernels built on `defineModels()`. A kernel that

package/dist/{PaginationEngine-DZnkbSrr.mjs → PaginationEngine-C9iS0U5l.mjs}

@@ -1,13 +1,13 @@
-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 { i as applyToQuery, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-BxUcSOoF.mjs";
+import { t as __exportAll } from "./rolldown-runtime-D8jQpDG7.mjs";
+import { i as applyToQuery, r as applyToAggregate, u as resolveQueryOptions } from "./query-defaults-aUoKlEbh.mjs";
+import { t as createError } from "./error-DjdmPLWO.mjs";
+import { n as warn } from "./logger-hbWOlj_X.mjs";
 import { calculateSkip, calculateTotalPages, shouldWarnDeepPagination, validateLimit, validatePage } from "./pagination/utils/limits.mjs";
 import mongoose from "mongoose";
 import { createTtlMemo } from "@classytic/repo-core/cache";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import { CURSOR_ERROR_CODES } from "@classytic/repo-core/pagination";
-//#region src/pagination/utils/cursor-signing.ts
+// src/pagination/utils/cursor-signing.ts
 /**
 * HMAC signing for pagination cursors.
 *
@@ -122,8 +122,7 @@ function verifySignature(token, secrets) {
 	for (const key of secrets) if (matches(signature, sign(payload, key))) return payload;
 	throw new Error("Invalid cursor token: signature does not verify (tampered, or issued under a retired key)");
 }
-//#endregion
-//#region src/pagination/defaults.ts
+// src/pagination/defaults.ts
 /**
 * The policy lives on `globalThis` under a registered symbol, NOT in a module
 * `let`.
@@ -215,8 +214,7 @@ function define(target, key, explicit, fallback) {
 		get: () => explicit !== void 0 ? explicit : policy()[key] ?? fallback
 	});
 }
-//#endregion
-//#region src/pagination/utils/filter.ts
+// src/pagination/utils/filter.ts
 /**
 * Combine the caller's filters with the keyset position predicate.
 *
@@ -327,8 +325,7 @@ function buildKeysetFilter(baseFilters, sort, cursorValue, cursorId, cursorValue
 	if (orConditions.length === 0) return combine(baseFilters, { _id: { $in: [] } });
 	return combine(baseFilters, { $or: orConditions });
 }
-//#endregion
-//#region src/pagination/utils/guards.ts
+// src/pagination/utils/guards.ts
 /**
 * Pagination guards shared by every paged read: the deep-offset refusal, the unique `_id`
 * tiebreaker that makes a sort a total order, and the cursor SCOPE fingerprint — a hash of
@@ -446,8 +443,7 @@ function warnIfSortNotTotal(model, pipeline, warnFn) {
 	warnedSortSites.add(site);
 	warnFn(`[mongokit] aggregatePipelinePaginate on '${model}': the page sort is not provably total, so rows that tie can repeat or be skipped across pages. End the \$sort on a key unique per output row, then pass \`sortIsTotal: true\` (or sort on _id with no \$unwind/\$group/_id rewrite before the sort).`);
 }
-//#endregion
-//#region src/pagination/utils/cursor.ts
+// src/pagination/utils/cursor.ts
 /**
 * Cursor Utilities
 *
@@ -455,12 +451,8 @@ function warnIfSortNotTotal(model, pipeline, warnFn) {
 * Cursors are base64-encoded JSON containing position data and metadata.
 */
 var cursor_exports = /* @__PURE__ */ __exportAll({
-	decodeCursor: () => decodeCursor,
 	encodeCursor: () => encodeCursor,
-	readSortValue: () => readSortValue,
-	resolveCursorFilter: () => resolveCursorFilter,
-	validateCursorSort: () => validateCursorSort,
-	validateCursorVersion: () => validateCursorVersion
+	resolveCursorFilter: () => resolveCursorFilter
 });
 /**
 * Encodes document values and sort metadata into a base64 cursor token
@@ -655,8 +647,7 @@ function resolveCursorFilter(after, sort, cursorVersion, baseFilters, minCursorV
 	validateCursorSort(cursor.sort, sort);
 	return buildKeysetFilter(baseFilters, buildSort, cursor.value, cursor.id, cursor.values);
 }
-//#endregion
-//#region src/pagination/utils/index-hint.ts
+// src/pagination/utils/index-hint.ts
 /**
 * The only operators that give the query planner a *bounded equality* it can
 * lead an index with. Everything else (`$ne`, `$nin`, `$gt(e)`, `$lt(e)`,
@@ -789,12 +780,9 @@ function hasCompatibleKeysetIndex(indexes, filterFields, sort) {
 	}
 	return false;
 }
-//#endregion
-//#region src/pagination/utils/sort.ts
+// src/pagination/utils/sort.ts
 var sort_exports = /* @__PURE__ */ __exportAll({
 	getPrimaryField: () => getPrimaryField,
-	invertSort: () => invertSort,
-	normalizeSort: () => normalizeSort,
 	validateKeysetSort: () => validateKeysetSort
 });
 /**
@@ -882,8 +870,7 @@ function invertSort(sort) {
 function getPrimaryField(sort) {
 	return Object.keys(sort).find((k) => k !== "_id") || "_id";
 }
-//#endregion
-//#region src/pagination/PaginationEngine.ts
+// src/pagination/PaginationEngine.ts
 /**
 * Pagination Engine
 *
@@ -1353,5 +1340,4 @@ var PaginationEngine = class {
 		};
 	}
 };
-//#endregion
 export { resolveCursorSecrets as _, cursor_exports as a, PAGINATION_ERROR_CODES as c, withGroupTiebreak as d, withIdTiebreak as f, attachSignature as g, resetPaginationDefaults as h, validateKeysetSort as i, assertOffsetWithinCap as l, getPaginationDefaults as m, getPrimaryField as n, encodeCursor as o, configurePaginationDefaults as p, sort_exports as r, resolveCursorFilter as s, PaginationEngine as t, cursorScope as u, verifySignature as v };

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

@@ -1,8 +1,7 @@
-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 { 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-DAUg5zOY.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
 /**
  * Internal pagination config with required values
  */
@@ -138,5 +137,4 @@ declare class PaginationEngine<TDoc = AnyDocument> {
    */
   aggregatePaginate(options?: AggregatePaginationOptions): Promise<AggregatePaginationResult<TDoc, MongokitPageExtras>>;
 }
-//#endregion
 export { PaginationEngine as n, CountMemoKey as t };

package/dist/{Repository-DnL4xk5w.d.mts → Repository-B6oL6OMv.d.mts}

@@ -1,7 +1,8 @@
-import { S as LookupOptions, _ as SessionOptions, b as WithTransactionOptions, c as DeleteResult, f as LookupPopulateOptions, g as ReadOptions, h as OperationOptions, i as CacheableOptions, l as FindOneAndUpdateOptions, n as AggregateOptions, o as CreateOptions, p as LookupPopulateResult, s as DeleteManyResult, t as AggregateCallOptions, u as GetByIdsOptions, v as UpdateManyResult, x as LookupBuilder, y as UpdateOptions } from "./operations-XiFgG5US.mjs";
-import { A as ObjectId, F as SortSpec$1, M as ReadPreferenceType, N as SelectSpec, c as MongokitPageExtras, i as CountStrategy, j as PopulateSpec, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-D6psses0.mjs";
-import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-MqAP409e.mjs";
-import { n as PaginationEngine } from "./PaginationEngine-CRHyuUtw.mjs";
+import { A as ObjectId, F as SortSpec$1, M as ReadPreferenceType, N as SelectSpec, c as MongokitPageExtras, i as CountStrategy, j as PopulateSpec, r as CollationOptions, t as AggregatePaginationOptions, u as PaginationConfig } from "./pagination-DAUg5zOY.mjs";
+import { r as RetentionPurgeRequest } from "./retention-purge-DqcYvRnG.mjs";
+import { n as PaginationEngine } from "./PaginationEngine-D17AthKw.mjs";
+import { S as LookupOptions, _ as SessionOptions, b as WithTransactionOptions, c as DeleteResult, f as LookupPopulateOptions, g as ReadOptions, h as OperationOptions, i as CacheableOptions, l as FindOneAndUpdateOptions, n as AggregateOptions, o as CreateOptions, p as LookupPopulateResult, s as DeleteManyResult, t as AggregateCallOptions, u as GetByIdsOptions, v as UpdateManyResult, x as LookupBuilder, y as UpdateOptions } from "./operations-Dw9OFV0V.mjs";
+import { _ as RepositoryOptions, d as PluginType, f as PrioritizedHook, o as Middleware, p as RepositoryContext } from "./repository-DzVIwhU2.mjs";
 import { AggPaginationRequest, AggRequest, AggResult, ArchiveOptions, ArchiveResult, ArchiveSink, BulkUpsertOptions, BulkUpsertResult, ChangeEvent, FilterInput, KeysetAggPaginationResult, QueryOptions, RepoCapabilities, RepositoryBase, TenantPurgeOptions, TenantPurgeResult, TenantPurgeStrategy, WatchOptions } from "@classytic/repo-core/repository";
 import { ClientSession, Expression, Model, PipelineStage, PopulateOptions } from "mongoose";
 import { Filter } from "@classytic/repo-core/filter";
@@ -9,7 +10,13 @@ import { RepositoryCacheHandle } from "@classytic/repo-core/cache";
 import { HttpError } from "@classytic/repo-core/errors";
 import { UpdateInput } from "@classytic/repo-core/update";
 import { AggregatePaginationResult, KeysetPaginationResult, OffsetPaginationResult, OffsetPaginationResultCore } from "@classytic/repo-core/pagination";
-//#region src/query/AggregationBuilder.d.ts
+/**
+ * `purgeByFilter` / `purgeByField` options: repo-core's `TenantPurgeOptions`
+ * plus the audited `retentionPurge` (see `SessionOptions.retentionPurge`).
+ */
+type RetentionTenantPurgeOptions = TenantPurgeOptions & {
+  retentionPurge?: RetentionPurgeRequest | undefined;
+};
 /** Options for $vectorSearch stage (Atlas only) */
 interface VectorSearchOptions {
   /** Atlas Search index name */
@@ -475,8 +482,6 @@ declare class AggregationBuilder {
  *      .exec(Model)
  *    ```
  */
-//#endregion
-//#region src/Repository.d.ts
 /**
  * Plugin phase priorities (lower = runs first).
  *
@@ -1397,8 +1402,26 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
     history?: string | false;
     /** Timestamp for the history entry — default `new Date()`. */
     at?: Date;
+    /**
+     * When the row entered its current state (the caller's read).
+     * Adds `durationInPriorMs: max(0, occurredAt - priorAt)` to the
+     * history entry, the same field primitives' `appendStatus` writes,
+     * without a pre-read here. Pair it with a `where` (e.g.
+     * `{ updatedAt: current.updatedAt }`) or `options.target` so a write
+     * between the read and the claim makes the claim miss rather than
+     * record a stale duration. Requires history (400 with `history: false`).
+     */
+    priorAt?: Date;
+    /**
+     * Extra fields merged into the history entry. May not contain the
+     * reserved keys `status`, `occurredAt`, `by`, `note` or
+     * `durationInPriorMs` (400). Requires history.
+     */
+    historyExtra?: Record<string, unknown>;
   }, options?: SessionOptions & {
     idField?: string;
+    /** Forwarded to `claim()`: the caller's same-session read, pinned by version / `updatedAt`. */
+    target?: Record<string, unknown>;
   }): Promise<TDoc>;
   /**
    * Optimistic-concurrency CAS via a version stamp.
@@ -1566,7 +1589,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * + strategy writes). See [actions/purge.ts](./actions/purge.ts) for
    * the port implementation.
    */
-  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  purgeByField(field: string, value: unknown, strategy: TenantPurgeStrategy, options?: RetentionTenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Range/filter-scoped purge — see `StandardRepo.purgeByFilter` for the
    * cross-kit contract. The compliance primitive for "purge/anonymize a
@@ -1581,7 +1604,7 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
    * the same dual-dialect rule as `archiveByFilter` and every other verb.
    * See [actions/purge.ts](./actions/purge.ts) for the port.
    */
-  purgeByFilter(filter: Record<string, unknown> | Filter, strategy: TenantPurgeStrategy, options?: TenantPurgeOptions): Promise<TenantPurgeResult>;
+  purgeByFilter(filter: Record<string, unknown> | Filter, strategy: TenantPurgeStrategy, options?: RetentionTenantPurgeOptions): Promise<TenantPurgeResult>;
   /**
    * Chunked cold-storage extraction — see `StandardRepo.archiveByFilter`
    * for the cross-kit contract (write-before-delete, at-least-once,
@@ -1989,5 +2012,4 @@ declare class Repository<TDoc = unknown> extends RepositoryBase {
   _handleError(error: Error): HttpError;
   private _translateError;
 }
-//#endregion
-export { AggregationBuilder as a, ProjectionSpec as c, VectorSearchOptions as d, TransitionMachine as i, SortOrder as l, HOOK_PRIORITY as n, AggregationPlan as o, Repository as r, GroupSpec as s, GetAllParams as t, SortSpec as u };
+export { AggregationBuilder as a, ProjectionSpec as c, VectorSearchOptions as d, RetentionTenantPurgeOptions as f, TransitionMachine as i, SortOrder as l, HOOK_PRIORITY as n, AggregationPlan as o, Repository as r, GroupSpec as s, GetAllParams as t, SortSpec as u };