@classytic/mongokit 3.25.0 → 3.29.0

package/dist/testkit/index.mjs

@@ -1,4 +1,4 @@
-import { t as createRepository } from "../create-repository-DA5VJh-3.mjs";
+import { t as createRepository } from "../create-repository-uhKt_oUT.mjs";
 import { createConnection } from "mongoose";
 //#region src/testkit/index.ts
 function idempotentStop(server) {

package/dist/{timestamp.plugin-B8252GuQ.mjs → timestamp.plugin-CFL6LlYZ.mjs}

@@ -1,4 +1,4 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS, t as HOOK_PRIORITY } from "./Repository-KKR8jxfD.mjs";
+import { c as ALL_OPERATIONS, t as HOOK_PRIORITY, u as OP_REGISTRY } from "./Repository-DThvFCaV.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { throwIfAborted, withRetry } from "@classytic/repo-core/repository";

package/dist/{update-1Lq9OMD2.mjs → update-CI2NdAW6.mjs}

@@ -1,7 +1,7 @@
 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 { isFilter } from "@classytic/repo-core/filter";
+import { coerceFilterDates, isFilter } from "@classytic/repo-core/filter";
 //#region src/filter/compile.ts
 /**
 * Compile a Filter IR node to a MongoDB query object. Returns `{}`
@@ -34,47 +34,41 @@ const SHORTHAND_OPS = /* @__PURE__ */ new Set([
 	"regex",
 	"mod"
 ]);
-/** Range operators whose string values should be coerced to Date. */
-const RANGE_OPS = /* @__PURE__ */ new Set([
-	"gt",
-	"gte",
-	"lt",
-	"lte"
+/** Logical operators whose operand is an array of sub-queries to recurse into. */
+const LOGICAL_ARRAY_OPS = /* @__PURE__ */ new Set([
+	"$and",
+	"$or",
+	"$nor"
 ]);
-/** ISO-8601 date-only or datetime string pattern. */
-const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}/;
-/**
-* Coerce a string value to a Date when it looks like an ISO-8601 date.
-* Needed because MongoDB won't match a BSON Date field against a string
-* value even when using range operators — BSON type comparison treats
-* Date (type 9) and String (type 2) as distinct, so `{ createdAt: {
-* $gte: "2026-05-01" } }` never matches a Date-typed field.
-*/
-function tryCoerceDate(value) {
-	if (typeof value === "string" && ISO_DATE_RE.test(value)) {
-		const d = new Date(value);
-		return Number.isNaN(d.getTime()) ? value : d;
-	}
-	return value;
-}
 /**
-* Expand operator shorthand values in a plain Mongo-style query object.
+* Expand operator shorthand values in a plain Mongo-style query object —
+* `$`-prefixing is the ONE Mongo-dialect concern this function owns. Date
+* coercion is delegated to `coerceFilterDates` (repo-core) so the ISO
+* pattern has a single source of truth shared with the URL-parsing boundary.
+*
 * Only expands nested objects whose keys are ALL in `SHORTHAND_OPS` — so
 * real nested documents (e.g. `address: { city: 'Dhaka' }`) pass through
 * unchanged, while `createdAt: { gte: '2026-04-01', lte: '2026-05-01' }`
-* becomes `createdAt: { $gte: Date(2026-04-01), $lte: Date(2026-05-01) }`.
-* String values on range operators are coerced to Date when they match the
-* ISO-8601 pattern, so BSON Date fields in MongoDB are compared correctly.
+* becomes `createdAt: { $gte: '2026-04-01', $lte: '2026-05-01' }` for the
+* coercion pass to type.
+*
+* Recurses `$and` / `$or` / `$nor` because a policy-scope merge conjoins the
+* caller filter under `$and`, and un-prefixed shorthand nested there would
+* otherwise reach `$match` as a literal field named `gte`.
 */
 function expandShorthands(obj) {
 	const out = {};
 	for (const [key, value] of Object.entries(obj)) {
+		if (LOGICAL_ARRAY_OPS.has(key) && Array.isArray(value)) {
+			out[key] = value.map((entry) => entry !== null && typeof entry === "object" && !Array.isArray(entry) ? expandShorthands(entry) : entry);
+			continue;
+		}
 		if (value !== null && typeof value === "object" && !Array.isArray(value)) {
 			const nested = value;
 			const keys = Object.keys(nested);
 			if (keys.length > 0 && keys.every((k) => !k.startsWith("$") && SHORTHAND_OPS.has(k))) {
 				const expanded = {};
-				for (const [op, opVal] of Object.entries(nested)) expanded[`$${op}`] = RANGE_OPS.has(op) ? tryCoerceDate(opVal) : opVal;
+				for (const [op, opVal] of Object.entries(nested)) expanded[`$${op}`] = opVal;
 				out[key] = expanded;
 				continue;
 			}
@@ -85,7 +79,7 @@ function expandShorthands(obj) {
 }
 function compileFilterToMongo(input) {
 	if (!input) return {};
-	if (!isFilter(input)) return expandShorthands(input);
+	if (!isFilter(input)) return coerceFilterDates(expandShorthands(input));
 	return compile(input);
 }
 function compile(filter) {

package/dist/{validation-chain.plugin-DxD15h-2.d.mts → validation-chain.plugin-BLecaKa0.d.mts}

@@ -185,6 +185,142 @@ declare function elasticSearchPlugin(options: ElasticSearchOptions): Plugin;
  */
 declare function fieldFilterPlugin(fieldPreset: FieldPreset): 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/immutable-states.plugin.d.ts
 /** The slice of a `before:claim` context `allowClaim` predicates see. */
 interface ImmutableClaimView {
@@ -822,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 { IdempotencyStorePluginOptions as A, AppendOnlyPluginOptions as B, LeasePluginOptions as C, immutableStatesPlugin as D, ImmutableStatesPluginOptions as E, cascadePlugin as F, AggregateHelpersMethods as H, BatchOperationsMethods as I, BulkWriteResult as L, fieldFilterPlugin as M, ElasticSearchOptions as N, IdempotencyClaim as O, elasticSearchPlugin as P, batchOperationsPlugin as R, LeaseMethods as S, ImmutableClaimView 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, idempotencyStorePlugin as j, IdempotencyStoreMethods 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-C3Vwp-Rk.mjs → validation-chain.plugin-CwOcUJC1.mjs}

@@ -1,5 +1,5 @@
-import { l as OP_REGISTRY, s as ALL_OPERATIONS } from "./Repository-KKR8jxfD.mjs";
-import { _ as upsert } from "./update-1Lq9OMD2.mjs";
+import { c as ALL_OPERATIONS, u as OP_REGISTRY } from "./Repository-DThvFCaV.mjs";
+import { _ as upsert } from "./update-CI2NdAW6.mjs";
 import { n as warn } from "./logger-K7dPmu2U.mjs";
 import { t as createError } from "./error-BuByZwKU.mjs";
 import { r as getFieldsForUser } from "./field-selection-FSQFLpsU.mjs";
@@ -476,6 +476,153 @@ function fieldFilterPlugin(fieldPreset) {
 	};
 }
 //#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/immutable-states.plugin.ts
 /** Ops this plugin has an explicit strategy for (see module doc). */
 const STRATEGY_OPS = /* @__PURE__ */ new Set([
@@ -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, idempotencyStorePlugin 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, appendOnlyPlugin as v, aggregateHelpersPlugin as y };