@classytic/mongokit 3.43.1 → 3.45.0

package/dist/lock/index.mjs

@@ -1,5 +1,276 @@
 import mongoose, { Schema } from "mongoose";
-//#region src/lock/index.ts
+import { randomUUID } from "node:crypto";
+import { AsyncLocalStorage } from "node:async_hooks";
+// src/lock/daily-ledger.ts
+/**
+* Mongo-backed daily ledger — one claim row per `(key, civilDate)`.
+*
+* Structurally implements arc's `DailyLedger` (`@classytic/arc` →
+* `createDailyGate` / `ScheduleDefinition.daily`) without importing arc:
+* pass the returned object as `ledger`. Exactly one replica wins
+* `claimDay` for a given key and civil date (unique `_id` + upsert; the
+* loser's upsert hits E11000 and returns `false`). An uncompleted claim
+* older than `info.staleAfterMs` may be re-granted (crash mid-run); a
+* completed day never is.
+*
+*     {
+*       _id: 'cron.digest|2026-10-30',
+*       key: 'cron.digest',
+*       civilDate: '2026-10-30',
+*       claimedAt: 2026-10-30T06:00:01.000Z,   // the gate's clock (info.now)
+*       completed: true,
+*       completedAt: 2026-10-30T06:00:04.000Z,
+*       result: { sent: 12 },
+*     }
+*
+* `civilDate` must be `YYYY-MM-DD` (what arc passes), so the composite
+* `_id` stays unambiguous whatever the key contains.
+*
+* Fencing is per INVOCATION, not per ledger instance: every won claim
+* gets a unique `claimToken` (stored on the row), and completing or
+* releasing only touches the row while it still carries that token. A
+* run that outlived `staleAfterMs` and was re-granted (by another
+* replica, or by this same instance on a later tick) can therefore
+* neither delete nor complete the newer claim, and a retry of its
+* completion stays fenced.
+*
+* - `claim()` returns a handle carrying the token; its `complete()` /
+*   `release()` are fenced by it. Prefer it in host code.
+* - `claimDay` / `completeDay` / `releaseDay` (arc's token-less
+*   `DailyLedger` shape) bind the token to the calling async context:
+*   `completeDay` / `releaseDay` act on the claim that THIS invocation
+*   (the async flow that awaited `claimDay`) won. Called from a flow
+*   that won nothing, they fall back to the instance's claim on the row
+*   only when it holds exactly one, and are otherwise a no-op.
+* - `adminCompleteDay` is the separate, explicit, unfenced manual
+*   completion. Nothing ever falls through to it.
+*/
+const CIVIL_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function rowId(key, civilDate) {
+	if (typeof key !== "string" || key.length === 0) throw new Error("MongoDailyLedger: key must be a non-empty string");
+	if (typeof civilDate !== "string" || !CIVIL_DATE.test(civilDate)) throw new Error(`MongoDailyLedger: civilDate must be YYYY-MM-DD, got "${String(civilDate)}"`);
+	return `${key}|${civilDate}`;
+}
+/**
+* Build a Mongo-backed daily ledger. Idempotent per `(connection,
+* modelName)` like `createMongoLockAdapter`.
+*
+* @example
+* import { createDailyGate } from '@classytic/arc/plugins';
+* import { createMongoDailyLedger } from '@classytic/mongokit/lock';
+*
+* const gate = createDailyGate({
+*   key: 'digest', zone: 'Asia/Dubai', hour: 6, staleAfterMs: 15 * 60_000,
+*   ledger: createMongoDailyLedger({ connection, collectionName: 'app_daily_ledger' }),
+* });
+*/
+function createMongoDailyLedger(options = {}) {
+	const { connection, collectionName = "mongo_daily_ledger", modelName = "MongoDailyLedger", nowFn = () => /* @__PURE__ */ new Date() } = options;
+	const model = getOrCreateLedgerModel(connection ?? mongoose, modelName, collectionName);
+	const sessionOpt = () => {
+		const s = options.session?.();
+		return s ? { session: s } : {};
+	};
+	/**
+	* Token-less (arc-shaped) claims this instance won and has not finished: rowId → tokens. The
+	* fallback for a `completeDay` / `releaseDay` called outside the invocation that claimed.
+	*/
+	const live = /* @__PURE__ */ new Map();
+	const invocation = new AsyncLocalStorage();
+	const slotToken = (slot) => {
+		for (let s = slot; s; s = s.prev) if (s.token !== void 0) return s.token;
+	};
+	const isLive = (id, token) => live.get(id)?.has(token) === true;
+	const forget = (id, token) => {
+		const set = live.get(id);
+		set?.delete(token);
+		if (set?.size === 0) live.delete(id);
+	};
+	/** The token-less caller's claim on the row: its invocation's, else the instance's only one. */
+	const tokenFor = (id) => {
+		const own = slotToken(invocation.getStore()?.get(id));
+		if (own !== void 0) return own;
+		const set = live.get(id);
+		return set?.size === 1 ? [...set][0] : void 0;
+	};
+	const validate = (key, civilDate, info) => {
+		const _id = rowId(key, civilDate);
+		const now = info?.now;
+		if (!(now instanceof Date) || Number.isNaN(now.getTime())) throw new Error("MongoDailyLedger.claimDay: info.now must be a valid Date");
+		const staleAfterMs = info.staleAfterMs;
+		if (staleAfterMs !== void 0 && (typeof staleAfterMs !== "number" || !Number.isFinite(staleAfterMs) || staleAfterMs < 0)) throw new Error("MongoDailyLedger.claimDay: info.staleAfterMs must be a finite number >= 0");
+		return {
+			_id,
+			now,
+			staleAfterMs
+		};
+	};
+	/** Try to win the row; the new claim's token, or `undefined` when not won. */
+	const claimRow = async (key, civilDate, v) => {
+		const { _id, now, staleAfterMs } = v;
+		const claimToken = randomUUID();
+		try {
+			if (staleAfterMs === void 0) {
+				await model.create([{
+					_id,
+					key,
+					civilDate,
+					claimedAt: now,
+					claimToken,
+					completed: false
+				}]);
+				return claimToken;
+			}
+			const res = await model.updateOne({
+				_id,
+				completed: false,
+				claimedAt: { $lt: new Date(now.getTime() - staleAfterMs) }
+			}, {
+				$set: {
+					key,
+					civilDate,
+					claimedAt: now,
+					claimToken,
+					completed: false
+				},
+				$unset: {
+					result: "",
+					completedAt: ""
+				}
+			}, { upsert: true });
+			return res.upsertedCount + res.modifiedCount > 0 ? claimToken : void 0;
+		} catch (err) {
+			if (err?.code === 11e3) return void 0;
+			throw err;
+		}
+	};
+	/** Complete the row while `token` still holds it uncompleted. */
+	const completeRow = async (_id, token, result) => {
+		return (await model.updateOne({
+			_id,
+			claimToken: token,
+			completed: false
+		}, { $set: {
+			completed: true,
+			completedAt: nowFn(),
+			...result !== void 0 ? { result } : {}
+		} }, sessionOpt())).modifiedCount > 0;
+	};
+	/** Delete the row while `token` still holds it uncompleted. */
+	const releaseRow = async (_id, token) => {
+		return (await model.deleteOne({
+			_id,
+			claimToken: token,
+			completed: false
+		}, sessionOpt())).deletedCount > 0;
+	};
+	return {
+		async claimDay(key, civilDate, info) {
+			const v = validate(key, civilDate, info);
+			const outer = invocation.getStore();
+			const scope = /* @__PURE__ */ new Map();
+			if (outer) for (const [id, slot] of outer) {
+				const t = slotToken(slot);
+				if (t === void 0 || isLive(id, t)) scope.set(id, slot);
+			}
+			const slot = { prev: outer?.get(v._id) };
+			scope.set(v._id, slot);
+			invocation.enterWith(scope);
+			const token = await claimRow(key, civilDate, v);
+			if (token === void 0) return false;
+			slot.token = token;
+			const set = live.get(v._id) ?? /* @__PURE__ */ new Set();
+			set.add(token);
+			live.set(v._id, set);
+			return true;
+		},
+		async completeDay(key, civilDate, result) {
+			const _id = rowId(key, civilDate);
+			const token = tokenFor(_id);
+			if (token === void 0) return;
+			await completeRow(_id, token, result);
+			forget(_id, token);
+		},
+		async releaseDay(key, civilDate) {
+			const _id = rowId(key, civilDate);
+			const token = tokenFor(_id);
+			if (token === void 0) return;
+			forget(_id, token);
+			await releaseRow(_id, token);
+		},
+		async claim(key, civilDate, info) {
+			const v = validate(key, civilDate, info);
+			const token = await claimRow(key, civilDate, v);
+			if (token === void 0) return null;
+			return {
+				key,
+				civilDate,
+				token,
+				claimedAt: v.now,
+				complete: (result) => completeRow(v._id, token, result),
+				release: () => releaseRow(v._id, token)
+			};
+		},
+		async adminCompleteDay(key, civilDate, result) {
+			const _id = rowId(key, civilDate);
+			return (await model.updateOne({
+				_id,
+				completed: false
+			}, { $set: {
+				completed: true,
+				completedAt: nowFn(),
+				...result !== void 0 ? { result } : {}
+			} }, sessionOpt())).modifiedCount > 0;
+		},
+		async inspect(key, civilDate) {
+			const doc = await model.findById(rowId(key, civilDate), null, sessionOpt()).lean();
+			if (!doc) return null;
+			const { _id: _ignored, ...row } = doc;
+			return row;
+		}
+	};
+}
+function getOrCreateLedgerModel(conn, modelName, collectionName) {
+	const existing = "models" in conn ? conn.models[modelName] : void 0;
+	if (existing) return existing;
+	const schema = new Schema({
+		_id: {
+			type: String,
+			required: true
+		},
+		key: {
+			type: String,
+			required: true
+		},
+		civilDate: {
+			type: String,
+			required: true
+		},
+		claimedAt: {
+			type: Date,
+			required: true
+		},
+		claimToken: { type: String },
+		completed: {
+			type: Boolean,
+			required: true,
+			default: false
+		},
+		completedAt: { type: Date },
+		result: { type: Schema.Types.Mixed }
+	}, {
+		versionKey: false,
+		timestamps: false,
+		_id: false,
+		minimize: false
+	});
+	schema.index({
+		key: 1,
+		civilDate: -1
+	});
+	return conn.model(modelName, schema, collectionName);
+}
+// src/lock/index.ts
 /**
 * Build a Mongo-backed lock adapter. Idempotent — the underlying
 * model is registered once per `(connection, modelName)` pair, so
@@ -7,27 +278,30 @@ import mongoose, { Schema } from "mongoose";
 * collection (no duplicate-model errors).
 */
 function createMongoLockAdapter(options = {}) {
-	const { connection, collectionName = "mongo_locks", modelName = "MongoLock", defaultLeaseMs = 3e4 } = options;
+	const { connection, collectionName = "mongo_locks", modelName = "MongoLock", defaultLeaseMs = 3e4, nowFn = () => /* @__PURE__ */ new Date() } = options;
 	const model = getOrCreateModel(connection ?? mongoose, modelName, collectionName);
 	return {
 		async tryAcquire(name, holderId, leaseMs) {
 			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
-			const now = /* @__PURE__ */ new Date();
+			const now = nowFn();
 			const expiresAt = new Date(now.getTime() + ms);
 			try {
+				const holder = { $literal: holderId };
 				const result = await model.findOneAndUpdate({
 					_id: name,
 					$or: [{ expiresAt: { $lt: now } }, { holder: holderId }]
-				}, {
-					$set: {
-						holder: holderId,
-						expiresAt
-					},
-					$setOnInsert: { acquiredAt: now }
-				}, {
+				}, [{ $set: {
+					acquiredAt: { $cond: [
+						{ $and: [{ $eq: ["$holder", holder] }, { $ne: [{ $type: "$acquiredAt" }, "missing"] }] },
+						"$acquiredAt",
+						{ $literal: now }
+					] },
+					holder,
+					expiresAt: { $literal: expiresAt }
+				} }], {
 					upsert: true,
 					returnDocument: "after",
-					setDefaultsOnInsert: true
+					updatePipeline: true
 				}).lean();
 				return !!result && result.holder === holderId;
 			} catch (err) {
@@ -35,6 +309,68 @@ function createMongoLockAdapter(options = {}) {
 				throw err;
 			}
 		},
+		async acquire(name, holderId, leaseMs) {
+			const ms = leaseMs > 0 ? leaseMs : defaultLeaseMs;
+			const now = nowFn();
+			const expiresAt = new Date(now.getTime() + ms);
+			const holder = { $literal: holderId };
+			const won = "$__lockWon";
+			const pipeline = [
+				{ $set: { __lockWon: { $or: [{ $lt: ["$expiresAt", { $literal: now }] }, { $eq: ["$holder", holder] }] } } },
+				{ $set: {
+					acquiredAt: { $cond: [
+						won,
+						{ $cond: [
+							{ $and: [{ $eq: ["$holder", holder] }, { $ne: [{ $type: "$acquiredAt" }, "missing"] }] },
+							"$acquiredAt",
+							{ $literal: now }
+						] },
+						"$acquiredAt"
+					] },
+					holder: { $cond: [
+						won,
+						holder,
+						"$holder"
+					] },
+					expiresAt: { $cond: [
+						won,
+						{ $literal: expiresAt },
+						"$expiresAt"
+					] }
+				} },
+				{ $unset: "__lockWon" }
+			];
+			for (let attempt = 0;; attempt++) try {
+				const before = await model.findOneAndUpdate({ _id: name }, pipeline, {
+					upsert: true,
+					returnDocument: "before",
+					updatePipeline: true
+				}).lean();
+				if (!before) return {
+					acquired: true,
+					holder: holderId,
+					acquiredAt: now,
+					expiresAt
+				};
+				const mine = before.holder === holderId;
+				if (mine || before.expiresAt.getTime() < now.getTime()) return {
+					acquired: true,
+					holder: holderId,
+					previousHolder: before.holder,
+					acquiredAt: mine && before.acquiredAt ? before.acquiredAt : now,
+					expiresAt
+				};
+				return {
+					acquired: false,
+					holder: before.holder,
+					acquiredAt: before.acquiredAt,
+					expiresAt: before.expiresAt
+				};
+			} catch (err) {
+				if (err?.code === 11e3 && attempt < 3) continue;
+				throw err;
+			}
+		},
 		async release(name, holderId) {
 			return !!await model.findOneAndDelete({
 				_id: name,
@@ -44,7 +380,7 @@ function createMongoLockAdapter(options = {}) {
 		async inspect(name) {
 			const doc = await model.findById(name).lean();
 			if (!doc) return null;
-			if (doc.expiresAt.getTime() <= Date.now()) return null;
+			if (doc.expiresAt.getTime() <= nowFn().getTime()) return null;
 			return {
 				name,
 				holder: doc.holder,
@@ -88,5 +424,4 @@ function getOrCreateModel(conn, modelName, collectionName) {
 	schema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });
 	return conn.model(modelName, schema, collectionName);
 }
-//#endregion
-export { createMongoLockAdapter };
+export { createMongoDailyLedger, createMongoLockAdapter };

package/dist/{logger-K7dPmu2U.mjs → logger-hbWOlj_X.mjs}

@@ -1,4 +1,4 @@
-//#region src/utils/logger.ts
+// src/utils/logger.ts
 const noop = () => {};
 let current = {
 	warn: console.warn.bind(console),
@@ -22,5 +22,4 @@ function configureLogger(config) {
 function warn(message, ...args) {
 	current.warn(message, ...args);
 }
-//#endregion
 export { warn as n, configureLogger as t };

package/dist/{method-registry.plugin-C63pGn1d.mjs → method-registry.plugin-BeJfQBJV.mjs}

@@ -1,5 +1,5 @@
-import { t as createError } from "./error-BuByZwKU.mjs";
-//#region src/plugins/batch-operations.plugin.ts
+import { t as createError } from "./error-DjdmPLWO.mjs";
+// src/plugins/batch-operations.plugin.ts
 /**
 * Batch operations plugin.
 *
@@ -31,7 +31,8 @@ const BULK_WRITE_OPTIONS = [
 	"bypassDocumentValidation",
 	"comment",
 	"let",
-	"ignoreUndefined"
+	"ignoreUndefined",
+	"maxTimeMS"
 ];
 /**
 * Driver options that EXIST but this method does not forward.
@@ -51,7 +52,6 @@ const BULK_WRITE_OPTIONS = [
 const UNSUPPORTED_DRIVER_OPTIONS = /* @__PURE__ */ new Set([
 	"forceServerObjectId",
 	"timeoutMS",
-	"maxTimeMS",
 	"retryWrites",
 	"checkKeys",
 	"serializeFunctions",
@@ -123,8 +123,7 @@ function batchOperationsPlugin() {
 		}
 	};
 }
-//#endregion
-//#region src/plugins/method-registry.plugin.ts
+// src/plugins/method-registry.plugin.ts
 /**
 * Method registry plugin that enables dynamic method registration
 */
@@ -158,5 +157,4 @@ function methodRegistryPlugin() {
 		}
 	};
 }
-//#endregion
 export { batchOperationsPlugin as n, methodRegistryPlugin as t };

package/dist/{model-registry-ClKtWiHa.mjs → model-registry-DrVfJ3Nt.mjs}

@@ -1,5 +1,5 @@
 import mongoose from "mongoose";
-//#region src/model-registry.ts
+// src/model-registry.ts
 /**
 * Model registration — the ONE place `mongoose.models` is touched.
 *
@@ -63,5 +63,4 @@ function defineModel(name, schema, options) {
 	}
 	return target ? target.model(name, schema(), options.collection) : mongoose.model(name, schema(), options.collection);
 }
-//#endregion
 export { defineModel as n, isModelRegistered as r, ModelCollisionError as t };

package/dist/{mongooseToJsonSchema-C3k4ide0.mjs → mongooseToJsonSchema-DMDotz4_.mjs}

@@ -1,7 +1,7 @@
-import { r as isObjectIdInstance } from "./id-resolution-BqDrk0S2.mjs";
+import { r as isObjectIdInstance } from "./id-resolution-Cqh49d9J.mjs";
 import mongoose from "mongoose";
 import { applyFieldRules, collectFieldsToOmit } from "@classytic/repo-core/schema";
-//#region src/utils/mongooseToJsonSchema.ts
+// src/utils/mongooseToJsonSchema.ts
 /**
 * Mongoose → JSON Schema converter.
 *
@@ -600,5 +600,4 @@ function buildJsonSchemaForQuery(_tree, options) {
 	for (const [k, v] of Object.entries(filterable)) if (basePagination.properties) basePagination.properties[k] = v && typeof v === "object" && "type" in v ? v : { type: "string" };
 	return basePagination;
 }
-//#endregion
 export { buildCrudSchemasFromMongooseSchema as n, buildCrudSchemasFromModel as t };