@classytic/mongokit 3.24.0 → 3.28.0

package/dist/{validation-chain.plugin-CFJbr964.d.mts → validation-chain.plugin-Cm0Ttnd8.d.mts}

@@ -1,4 +1,6 @@
-import { B as ObjectId, C as FieldPreset, G as Plugin, J as PopulateSpec, Q as RepositoryContext, _t as ValidationChainOptions, et as RepositoryInstance, it as SelectSpec, j as Logger, l as CascadeOptions, st as SoftDeleteOptions, ut as SortSpec, vt as ValidatorDefinition } from "./types-BtMuhoX5.mjs";
+import { a as PopulateSpec, i as ObjectId, l as SortSpec, s as SelectSpec } from "./core-62oo3N1C.mjs";
+import { h as RepositoryInstance, l as Plugin, p as RepositoryContext } from "./repository-DCHRWRXw.mjs";
+import { c as ValidationChainOptions, i as Logger, l as ValidatorDefinition, o as SoftDeleteOptions, r as FieldPreset, t as CascadeOptions } from "./plugin-options-vFufQZMZ.mjs";
 import { BulkWriteResult } from "@classytic/repo-core/repository";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { OffsetPaginationResult } from "@classytic/repo-core/pagination";
@@ -224,6 +226,142 @@ interface ImmutableStatesPluginOptions {
 }
 declare function immutableStatesPlugin(options: ImmutableStatesPluginOptions): Plugin;
 //#endregion
+//#region src/plugins/idempotency-store.plugin.d.ts
+interface IdempotencyStorePluginOptions {
+  /** Field carrying the deterministic operation key. @default `'key'` */
+  keyField?: string;
+  /** Field carrying the row's claim status. @default `'status'` */
+  statusField?: string;
+  /** Field carrying the current holder's lease token. @default `'leaseToken'` */
+  leaseTokenField?: string;
+  /** Field carrying the lease expiry timestamp. @default `'leaseExpiresAt'` */
+  leaseExpiresAtField?: string;
+  /** Field counting claim acquisitions (1 = first). @default `'attempts'` */
+  attemptsField?: string;
+  /** Field carrying saga resume data (Mixed). @default `'progress'` */
+  progressField?: string;
+  /** Field carrying the replayable success outcome (Mixed). @default `'result'` */
+  resultField?: string;
+  /** Field carrying the terminal failure code. @default `'failureCode'` */
+  failureCodeField?: string;
+  /** Field carrying the last error message (diagnostics). @default `'lastError'` */
+  lastErrorField?: string;
+  /** Status value of an in-flight claim. @default `'in_flight'` */
+  inFlightStatus?: string;
+  /** Terminal success status. @default `'succeeded'` */
+  succeededStatus?: string;
+  /** Terminal failure status. @default `'failed'` */
+  failedStatus?: string;
+  /** Claim lease (ms) — must outlive the longest guarded execution. @default 60_000 */
+  defaultLeaseMs?: number;
+  /**
+   * Re-acquisition ceiling. When > 0, an expired in-flight claim whose
+   * `attempts` already reached this value returns `exhausted` instead of
+   * re-acquiring — the bounded-retry escalation valve for operations whose
+   * external side effect is idempotent but may be wedged. 0 = unbounded
+   * (flow/order semantics: recovery always re-claims). @default 0
+   */
+  maxAttempts?: number;
+}
+/** Outcome of `claimKey()` — the claim decision matrix. */
+type IdempotencyClaim<TProgress = Record<string, unknown>, TResult = unknown> =
+/**
+ * This caller owns the lease — execute. `progress` present ⇒ a stale-lease
+ * re-acquire after a previous attempt persisted resume data (crash
+ * recovery): resume from it instead of re-running completed pivots.
+ * `attempt` is 1 on a fresh claim.
+ */
+{
+  kind: 'acquired';
+  leaseToken: string;
+  attempt: number;
+  progress?: TProgress;
+} |
+/** A previous execution succeeded — replay its stored outcome. */
+{
+  kind: 'completed';
+  result?: TResult;
+} |
+/** A previous execution failed terminally — replay the recorded code. */
+{
+  kind: 'failed';
+  failureCode?: string;
+  error?: string;
+} |
+/** Another caller holds a live lease. `progress` (when persisted) lets a
+ *  domain layer act on completed pivots without owning the lease — e.g.
+ *  finish an idempotent post-pivot sync while the holder is wedged. */
+{
+  kind: 'busy';
+  progress?: TProgress;
+  leaseToken?: string;
+} |
+/** `maxAttempts` re-acquisitions exhausted — escalate to a human. */
+{
+  kind: 'exhausted';
+  attempts: number;
+  progress?: TProgress;
+};
+/**
+ * Methods contributed by `idempotencyStorePlugin()`. Use as a type assertion
+ * when constructing the repo (same convention as `LeaseMethods`).
+ */
+interface IdempotencyStoreMethods<TProgress = Record<string, unknown>, TResult = unknown> {
+  /**
+   * Atomically claim `key`. Exactly one concurrent caller acquires; the rest
+   * branch on the row's durable state — see {@link IdempotencyClaim}.
+   *
+   * `seed` merges extra fields into the row on FIRST insert only (domain
+   * columns, tenant stamp). It never mutates an existing row.
+   */
+  claimKey(key: string, opts?: {
+    leaseMs?: number;
+    seed?: Record<string, unknown>;
+  }): Promise<IdempotencyClaim<TProgress, TResult>>;
+  /**
+   * Persist saga resume data (post-pivot, pre-complete). Lease-token-guarded —
+   * a stale crashed holder can't clobber a re-acquirer's record. Optional
+   * `where` adds domain guards to the CAS filter.
+   */
+  saveClaimProgress(key: string, leaseToken: string, progress: TProgress, opts?: {
+    where?: Record<string, unknown>;
+  }): Promise<boolean>;
+  /**
+   * CAS the claim to the terminal SUCCESS status, storing `result` for
+   * replay. Loses cleanly (returns false) when the lease was re-acquired.
+   */
+  completeClaim(key: string, leaseToken: string, result?: TResult, opts?: {
+    where?: Record<string, unknown>;
+  }): Promise<boolean>;
+  /**
+   * CAS the claim to the terminal FAILURE status. Later claims replay
+   * `failureCode` instead of re-executing. Use ONLY for definitive failures
+   * where the external side effect is known NOT to have happened.
+   */
+  failClaim(key: string, leaseToken: string, failure: {
+    code: string;
+    error?: string;
+  }, opts?: {
+    where?: Record<string, unknown>;
+  }): Promise<boolean>;
+  /**
+   * Delete the caller's own in-flight row on definitive PRE-side-effect
+   * failure so a retry re-executes cleanly. Never deletes a terminal row or
+   * a re-acquired lease.
+   */
+  releaseClaim(key: string, leaseToken: string): Promise<boolean>;
+  /**
+   * Record an AMBIGUOUS error and lapse the lease immediately (keeps the row
+   * in-flight) so a recovery sweep re-claims without waiting out the lease.
+   * The bridge between "this attempt is giving up" and "the operation is not
+   * over" — e.g. a network error mid-external-call.
+   */
+  expireClaim(key: string, leaseToken: string, opts?: {
+    error?: string;
+  }): Promise<boolean>;
+}
+declare function idempotencyStorePlugin(options?: IdempotencyStorePluginOptions): Plugin;
+//#endregion
 //#region src/plugins/lease.plugin.d.ts
 interface LeasePluginOptions {
   /** Field carrying the row's status. @default `'status'` */
@@ -820,4 +958,4 @@ declare function immutableField(field: string): ValidatorDefinition;
  */
 declare function uniqueField(field: string, errorMessage?: string): ValidatorDefinition;
 //#endregion
-export { elasticSearchPlugin as A, LeasePluginOptions as C, immutableStatesPlugin as D, ImmutableStatesPluginOptions as E, auditLogPlugin as F, AppendOnlyPluginOptions as I, appendOnlyPlugin as L, BatchOperationsMethods as M, BulkWriteResult as N, fieldFilterPlugin as O, batchOperationsPlugin as P, AggregateHelpersMethods as R, LeaseMethods as S, ImmutableClaimView as T, observabilityPlugin as _, uniqueField as a, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, cascadePlugin as j, ElasticSearchOptions as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y, aggregateHelpersPlugin as z };
+export { ImmutableStatesPluginOptions as A, AppendOnlyPluginOptions as B, LeasePluginOptions as C, IdempotencyStorePluginOptions as D, IdempotencyStoreMethods as E, cascadePlugin as F, AggregateHelpersMethods as H, BatchOperationsMethods as I, BulkWriteResult as L, fieldFilterPlugin as M, ElasticSearchOptions as N, idempotencyStorePlugin as O, elasticSearchPlugin as P, batchOperationsPlugin as R, LeaseMethods as S, IdempotencyClaim as T, aggregateHelpersPlugin as U, appendOnlyPlugin as V, observabilityPlugin as _, uniqueField as a, MethodRegistryRepository as b, TenantContext as c, SubdocumentMethods as d, subdocumentPlugin as f, OperationMetric as g, ObservabilityOptions as h, requireField as i, immutableStatesPlugin as j, ImmutableClaimView as k, TenantStore as l, softDeletePlugin as m, blockIf as n, validationChainPlugin as o, SoftDeleteMethods as p, immutableField as r, timestampPlugin as s, autoInject as t, createTenantContext as u, MongoOperationsMethods as v, leasePlugin as w, methodRegistryPlugin as x, mongoOperationsPlugin as y, auditLogPlugin as z };

package/dist/{validation-chain.plugin-Dtt4tO7R.mjs → validation-chain.plugin-k9joH2qw.mjs}

@@ -1,4 +1,4 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-ClOraFjT.mjs";
+import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-BFBTAMlA.mjs";
 import { _ as upsert } from "./update-1Lq9OMD2.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
@@ -610,6 +610,153 @@ function immutableStatesPlugin(options) {
 	};
 }
 //#endregion
+//#region src/plugins/idempotency-store.plugin.ts
+function randomToken() {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	globalThis.crypto.getRandomValues(bytes);
+	return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function idempotencyStorePlugin(options = {}) {
+	const keyField = options.keyField ?? "key";
+	const statusField = options.statusField ?? "status";
+	const leaseTokenField = options.leaseTokenField ?? "leaseToken";
+	const leaseExpiresAtField = options.leaseExpiresAtField ?? "leaseExpiresAt";
+	const attemptsField = options.attemptsField ?? "attempts";
+	const progressField = options.progressField ?? "progress";
+	const resultField = options.resultField ?? "result";
+	const failureCodeField = options.failureCodeField ?? "failureCode";
+	const lastErrorField = options.lastErrorField ?? "lastError";
+	const inFlightStatus = options.inFlightStatus ?? "in_flight";
+	const succeededStatus = options.succeededStatus ?? "succeeded";
+	const failedStatus = options.failedStatus ?? "failed";
+	const defaultLeaseMs = options.defaultLeaseMs ?? 6e4;
+	const maxAttempts = options.maxAttempts ?? 0;
+	return {
+		name: "idempotencyStore",
+		apply(repo) {
+			if (!repo.registerMethod) throw new Error("idempotencyStorePlugin requires methodRegistryPlugin. Add methodRegistryPlugin() before idempotencyStorePlugin().");
+			const asDoc = (d) => d;
+			repo.registerMethod("claimKey", async function(key, opts = {}) {
+				if (typeof key !== "string" || key.length === 0) throw createError(400, "idempotencyStorePlugin.claimKey: key must be a non-empty string");
+				const leaseMs = opts.leaseMs ?? defaultLeaseMs;
+				const now = /* @__PURE__ */ new Date();
+				const leaseToken = randomToken();
+				const { doc, created } = await this.getOrCreate({ [keyField]: key }, {
+					...opts.seed ?? {},
+					[keyField]: key,
+					[statusField]: inFlightStatus,
+					[leaseTokenField]: leaseToken,
+					[leaseExpiresAtField]: new Date(now.getTime() + leaseMs),
+					[attemptsField]: 1
+				});
+				if (created) return {
+					kind: "acquired",
+					leaseToken,
+					attempt: 1
+				};
+				const row = asDoc(doc);
+				if (row[statusField] === succeededStatus) return {
+					kind: "completed",
+					result: row[resultField]
+				};
+				if (row[statusField] === failedStatus) return {
+					kind: "failed",
+					failureCode: row[failureCodeField],
+					error: row[lastErrorField]
+				};
+				const leaseExpiresAt = row[leaseExpiresAtField];
+				const progress = row[progressField];
+				if (leaseExpiresAt && leaseExpiresAt > now) return {
+					kind: "busy",
+					...progress !== void 0 ? { progress } : {},
+					...row[leaseTokenField] !== void 0 ? { leaseToken: row[leaseTokenField] } : {}
+				};
+				const attempts = row[attemptsField] ?? 1;
+				if (maxAttempts > 0 && attempts >= maxAttempts) return {
+					kind: "exhausted",
+					attempts,
+					...progress !== void 0 ? { progress } : {}
+				};
+				const reclaimed = await this.findOneAndUpdate({
+					[keyField]: key,
+					[statusField]: inFlightStatus,
+					[leaseExpiresAtField]: { $lte: now }
+				}, {
+					$set: {
+						[leaseTokenField]: leaseToken,
+						[leaseExpiresAtField]: new Date(now.getTime() + leaseMs)
+					},
+					$inc: { [attemptsField]: 1 }
+				}, { returnDocument: "after" });
+				if (reclaimed) {
+					const rec = asDoc(reclaimed);
+					const recProgress = rec[progressField];
+					return {
+						kind: "acquired",
+						leaseToken,
+						attempt: rec[attemptsField] ?? attempts + 1,
+						...recProgress !== void 0 ? { progress: recProgress } : {}
+					};
+				}
+				return {
+					kind: "busy",
+					...progress !== void 0 ? { progress } : {}
+				};
+			});
+			repo.registerMethod("saveClaimProgress", async function(key, leaseToken, progress, opts = {}) {
+				return await this.findOneAndUpdate({
+					...opts.where ?? {},
+					[keyField]: key,
+					[leaseTokenField]: leaseToken,
+					[statusField]: inFlightStatus
+				}, { $set: { [progressField]: progress } }, { returnDocument: "after" }) !== null;
+			});
+			repo.registerMethod("completeClaim", async function(key, leaseToken, result, opts = {}) {
+				return await this.findOneAndUpdate({
+					...opts.where ?? {},
+					[keyField]: key,
+					[leaseTokenField]: leaseToken,
+					[statusField]: inFlightStatus
+				}, { $set: {
+					[statusField]: succeededStatus,
+					...result !== void 0 ? { [resultField]: result } : {}
+				} }, { returnDocument: "after" }) !== null;
+			});
+			repo.registerMethod("failClaim", async function(key, leaseToken, failure, opts = {}) {
+				if (!failure || typeof failure.code !== "string" || failure.code.length === 0) throw createError(400, "idempotencyStorePlugin.failClaim: failure.code must be a non-empty string");
+				return await this.findOneAndUpdate({
+					...opts.where ?? {},
+					[keyField]: key,
+					[leaseTokenField]: leaseToken,
+					[statusField]: inFlightStatus
+				}, { $set: {
+					[statusField]: failedStatus,
+					[failureCodeField]: failure.code,
+					...failure.error !== void 0 ? { [lastErrorField]: failure.error } : {}
+				} }, { returnDocument: "after" }) !== null;
+			});
+			repo.registerMethod("releaseClaim", async function(key, leaseToken) {
+				const res = await this.deleteMany({
+					[keyField]: key,
+					[leaseTokenField]: leaseToken,
+					[statusField]: inFlightStatus
+				});
+				return (typeof res === "number" ? res : res?.deletedCount ?? 0) > 0;
+			});
+			repo.registerMethod("expireClaim", async function(key, leaseToken, opts = {}) {
+				return await this.findOneAndUpdate({
+					[keyField]: key,
+					[leaseTokenField]: leaseToken,
+					[statusField]: inFlightStatus
+				}, { $set: {
+					[leaseExpiresAtField]: /* @__PURE__ */ new Date(),
+					...opts.error !== void 0 ? { [lastErrorField]: opts.error } : {}
+				} }, { returnDocument: "after" }) !== null;
+			});
+		}
+	};
+}
+//#endregion
 //#region src/plugins/lease.plugin.ts
 function leasePlugin(options = {}) {
 	const statusField = options.statusField ?? "status";
@@ -1304,4 +1451,4 @@ function uniqueField(field, errorMessage) {
 	};
 }
 //#endregion
-export { appendOnlyPlugin as _, uniqueField as a, subdocumentPlugin as c, mongoOperationsPlugin as d, leasePlugin as f, cascadePlugin as g, elasticSearchPlugin as h, requireField as i, observabilityPlugin as l, fieldFilterPlugin as m, blockIf as n, validationChainPlugin as o, immutableStatesPlugin as p, immutableField as r, createTenantContext as s, autoInject as t, MONGOKIT_PLUGIN_NAMES as u, aggregateHelpersPlugin as v };
+export { cascadePlugin as _, uniqueField as a, subdocumentPlugin as c, mongoOperationsPlugin as d, leasePlugin as f, elasticSearchPlugin as g, fieldFilterPlugin as h, requireField as i, observabilityPlugin as l, immutableStatesPlugin as m, blockIf as n, validationChainPlugin as o, idempotencyStorePlugin as p, immutableField as r, createTenantContext as s, autoInject as t, MONGOKIT_PLUGIN_NAMES as u, appendOnlyPlugin as v, aggregateHelpersPlugin as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/mongokit",
-  "version": "3.24.0",
+  "version": "3.28.0",
   "description": "Production-grade MongoDB repositories - smart pagination, events, and plugins. Built on @classytic/repo-core.",
   "type": "module",
   "sideEffects": false,
@@ -113,7 +113,7 @@
   },
   "homepage": "https://github.com/classytic/mongokit#readme",
   "peerDependencies": {
-    "@classytic/repo-core": ">=0.14.0",
+    "@classytic/repo-core": ">=0.17.0",
     "mongoose": ">=9.4.1"
   },
   "engines": {
@@ -139,8 +139,10 @@
     "lint:package": "publint && attw --pack . --profile esm-only",
     "format": "biome format src/ --write",
     "check": "biome ci src/ --diagnostic-level=error",
+    "check:dead-code": "knip",
+    "ci": "npm run check && npm run typecheck && npm run typecheck:tests && npm run build && npm run lint:package && npm run check:dead-code && npm test",
     "push": "classytic-push",
-    "prepublishOnly": "npm run check && npm run build && publint && npm run typecheck && npm run typecheck:tests && npm test",
+    "prepublishOnly": "npm run ci",
     "publish:dry": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public",
     "release:tag": "node -e \"require('child_process').execSync('npm run push -- v'+require('./package.json').version,{stdio:'inherit'})\"",
@@ -155,7 +157,7 @@
     "@better-auth/mongo-adapter": "^1.6.22",
     "@biomejs/biome": "^2.4.10",
     "@classytic/dev-tools": "^0.2.0",
-    "@classytic/repo-core": "^0.14.0",
+    "@classytic/repo-core": "^0.17.0",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.4",
     "ajv": "^8.18.0",
@@ -168,7 +170,7 @@
     "mongoose": "^9.4.1",
     "publint": "^0.3.18",
     "tsdown": "^0.22.5",
-    "typescript": "^7.0.2",
+    "typescript": "~5.9.0",
     "vitest": "^4.1.4"
   },
   "overrides": {