@classytic/mongokit 3.38.1 → 3.40.0

package/dist/transaction-B5L9glO0.mjs

@@ -0,0 +1,533 @@
+//#region src/capabilities.ts
+/**
+* Read the provenance of a capability descriptor's `transactions` flag.
+* A descriptor without the field is a static declaration (`'declared'`) —
+* which is exactly right for sqlitekit / prismakit / any kit whose answer
+* genuinely does not depend on a live deployment.
+*/
+function transactionResolutionOf(caps) {
+	const value = caps.transactionsResolution;
+	return value === "observed" || value === "unknown" ? value : "declared";
+}
+/**
+* What MongoDB supports through mongokit's surface, DECLARED (not observed).
+*
+* Deployment-dependent flags (`transactions`, `changeStreams` — both need a
+* replica set or mongos) are `true` here because they describe the product,
+* not the server you happen to be pointed at. `nestedTransactions` is NOT one
+* of them: it is `false` unconditionally, because the refusal comes from
+* mongokit's own tx-bound proxy rather than from the deployment. **Do not read this constant to decide whether a live connection can run
+* a transaction** — that is {@link resolveMongoCapabilities}, which is what
+* `Repository#capabilities` returns. This one is for the cross-kit conformance
+* harness (which overrides environment-specific limits where it is
+* constructed) and as the base every observed descriptor is derived from.
+*/
+const MONGOKIT_CAPABILITIES = Object.freeze({
+	transactionsResolution: "declared",
+	transactions: true,
+	nestedTransactions: false,
+	transactionRetry: "managed",
+	upsert: true,
+	duplicateKeyError: true,
+	optimisticConcurrency: true,
+	distinct: true,
+	aggregate: true,
+	aggregateOps: Object.freeze({
+		percentile: true,
+		stddev: true,
+		topN: true,
+		dateBucketTimezone: true,
+		customDateBuckets: true,
+		dateBucketSubMinute: true,
+		cache: true
+	}),
+	getOrCreate: true,
+	countAndExists: true,
+	purgeByField: true,
+	purgeByFilter: true,
+	archiveByFilter: true,
+	arrayOperators: true,
+	regexFilter: true,
+	changeStreams: true,
+	lean: true,
+	lookupPopulate: true,
+	lookupCoerce: true,
+	streaming: true
+});
+/**
+* Driver `ServerType`s that positively imply a session-capable, transaction-
+* capable deployment. Verified against mongodb driver 7.x: a single-node
+* replica set reports `RSPrimary` (topology `ReplicaSetWithPrimary`, or
+* `Single` when reached with `directConnection`), a standalone `mongod`
+* reports `Standalone`, and a mongos reports `Mongos`.
+*
+* **This is why the check reads SERVER type, not just topology type.** The
+* pre-existing heuristic (`topology.description.type !== 'Single'`) has a
+* false NEGATIVE: a directly-connected single-node replica set is `Single`
+* yet runs transactions fine.
+*/
+const TRANSACTION_CAPABLE_SERVER_TYPES = /* @__PURE__ */ new Set([
+	"RSPrimary",
+	"RSSecondary",
+	"RSArbiter",
+	"RSOther",
+	"RSGhost",
+	"Mongos",
+	"LoadBalancer"
+]);
+/** Topology types that positively imply transactions regardless of server detail. */
+const TRANSACTION_CAPABLE_TOPOLOGY_TYPES = /* @__PURE__ */ new Set([
+	"ReplicaSetWithPrimary",
+	"ReplicaSetNoPrimary",
+	"Sharded",
+	"LoadBalanced"
+]);
+function clientOf(connection) {
+	const probe = connection;
+	if (!probe || typeof probe !== "object") return void 0;
+	try {
+		return probe.getClient?.() ?? probe.client ?? (probe.topology !== void 0 ? probe : void 0);
+	} catch {
+		return;
+	}
+}
+function serverTypes(description) {
+	const servers = description.servers;
+	if (!servers) return [];
+	return (typeof servers.values === "function" ? [...servers.values()] : Object.values(servers)).map((s) => s?.type).filter((t) => typeof t === "string");
+}
+/**
+* Read whether a connection's LIVE deployment supports multi-document
+* transactions, synchronously, from the driver's SDAM topology description.
+*
+* Free (a few property reads against an object the driver keeps current), so
+* it is deliberately NOT memoized — a connection that opens after the repo was
+* constructed upgrades its own answer with no invalidation step. What IS
+* memoized is the async {@link probeMongoCapabilities} result, which this
+* function consults first so an exotic deployment that answered `hello` but
+* exposes no topology still reports definitively.
+*
+* @returns `'yes'` / `'no'` when the topology is conclusive, `'unknown'`
+*   otherwise — never optimistic. See the module docblock on rule 3.
+*/
+function resolveTransactionSupport(connection) {
+	const cached = readProbeCache(connection);
+	if (cached) return cached;
+	const description = clientOf(connection)?.topology?.description;
+	if (!description) return "unknown";
+	const types = serverTypes(description);
+	if (types.some((t) => TRANSACTION_CAPABLE_SERVER_TYPES.has(t))) return "yes";
+	if (types.length > 0 && types.every((t) => t === "Standalone")) return "no";
+	const topologyType = description.type;
+	if (topologyType && TRANSACTION_CAPABLE_TOPOLOGY_TYPES.has(topologyType)) return "yes";
+	return "unknown";
+}
+function deriveCapabilities(support) {
+	const available = support === "yes";
+	return Object.freeze({
+		...MONGOKIT_CAPABILITIES,
+		transactionsResolution: support === "unknown" ? "unknown" : "observed",
+		transactions: available,
+		nestedTransactions: false,
+		changeStreams: available
+	});
+}
+/** Three possible answers ⇒ three frozen singletons; the getter allocates nothing. */
+const DERIVED = Object.freeze({
+	yes: deriveCapabilities("yes"),
+	no: deriveCapabilities("no"),
+	unknown: deriveCapabilities("unknown")
+});
+/**
+* The capability descriptor for a LIVE connection — what
+* `Repository#capabilities` returns.
+*
+* Every deployment-dependent flag reflects the observed topology; everything
+* else comes from {@link MONGOKIT_CAPABILITIES}. Cheap enough to call per
+* access (topology read + one frozen-object lookup).
+*/
+function resolveMongoCapabilities(connection) {
+	return DERIVED[resolveTransactionSupport(connection)];
+}
+/** The three derived descriptors, for tests and for gates that want to compare identity. */
+function capabilitiesForSupport(support) {
+	return DERIVED[support];
+}
+/** Definitive results only. Keyed on the connection object; never holds `'unknown'`. */
+const PROBE_RESULTS = /* @__PURE__ */ new WeakMap();
+/** In-flight de-duplication so N repos on one connection issue ONE `hello`. */
+const PROBE_INFLIGHT = /* @__PURE__ */ new WeakMap();
+function readProbeCache(connection) {
+	if (!connection || typeof connection !== "object") return void 0;
+	return PROBE_RESULTS.get(connection);
+}
+/** Test seam — drop memoized probe answers (a reused connection object across suites). */
+function resetCapabilityProbeCache(connection) {
+	if (connection && typeof connection === "object") {
+		PROBE_RESULTS.delete(connection);
+		PROBE_INFLIGHT.delete(connection);
+	}
+}
+function withTimeout(promise, ms, onTimeout) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => resolve(onTimeout), ms);
+		timer.unref?.();
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, () => {
+			clearTimeout(timer);
+			resolve(onTimeout);
+		});
+	});
+}
+/**
+* Classify a `hello` (or legacy `isMaster`) reply.
+*
+* - `msg: 'isdbgrid'` ⇒ mongos ⇒ transactions (Mongo 4.2+ sharded).
+* - `setName` ⇒ a replica-set member ⇒ transactions.
+* - a reply that IS a hello (`isWritablePrimary` / `ismaster` present) with
+*   neither marker ⇒ standalone ⇒ **no**. Verified: a memory-server standalone
+*   returns `{ isWritablePrimary: true }` and nothing else.
+* - anything unrecognised ⇒ `'unknown'`. A reply we cannot parse is not a yes.
+*/
+function classifyHelloReply(reply) {
+	if (!reply || typeof reply !== "object") return "unknown";
+	const { msg, setName } = reply;
+	if (msg === "isdbgrid") return "yes";
+	if (typeof setName === "string" && setName.length > 0) return "yes";
+	return "isWritablePrimary" in reply || "ismaster" in reply ? "no" : "unknown";
+}
+async function runProbe(connection, timeoutMs) {
+	if (connection.readyState === 2 && typeof connection.asPromise === "function") await withTimeout(connection.asPromise().then(() => void 0, () => void 0), timeoutMs, void 0);
+	const fromTopology = resolveTransactionSupport(connection);
+	if (fromTopology !== "unknown") return fromTopology;
+	const admin = connection.db?.admin?.();
+	if (!admin) return "unknown";
+	return classifyHelloReply(await withTimeout(admin.command({ hello: 1 }).catch(async () => admin.command({ isMaster: 1 }).catch(() => void 0)), timeoutMs, void 0));
+}
+/**
+* Resolve a connection's real capabilities, waiting for (and if necessary
+* asking) the deployment. Memoized per connection: N repositories and N
+* kernels on one connection issue at most ONE `hello`.
+*
+* Hosts do not have to call this — `Repository#capabilities` reads the live
+* topology synchronously, which is already conclusive once
+* `await mongoose.connect()` has returned (the Kernel Construction Standard's
+* Describe → **Bind** ordering guarantees that). It exists for the cases the
+* sync read cannot cover: binding while a connection is still opening, or a
+* deployment whose driver surfaces no topology description. Calling it makes
+* the SUBSEQUENT synchronous reads definitive, so nothing else needs rewiring:
+*
+* ```ts
+* await probeMongoCapabilities(connection);   // once, before bind
+* const engine = defineWallet().bind(connection);  // gate now sees the truth
+* ```
+*
+* Only definitive answers are cached — an `'unknown'` may be re-probed later
+* (the deployment may simply not have been up yet).
+*/
+async function probeMongoCapabilities(connection, options = {}) {
+	if (!connection || typeof connection !== "object") return DERIVED.unknown;
+	const key = connection;
+	const cached = PROBE_RESULTS.get(key);
+	if (cached) return DERIVED[cached];
+	const inflight = PROBE_INFLIGHT.get(key);
+	if (inflight) return DERIVED[await inflight];
+	const run = runProbe(connection, options.timeoutMs ?? 2e3).catch(() => "unknown").then((support) => {
+		if (support !== "unknown") PROBE_RESULTS.set(key, support);
+		PROBE_INFLIGHT.delete(key);
+		return support;
+	});
+	PROBE_INFLIGHT.set(key, run);
+	return DERIVED[await run];
+}
+//#endregion
+//#region src/tx-bound.ts
+/**
+* Map of session-aware method name → positional index of the `{ session }`
+* options bag. Keep this list in sync with the method signatures in
+* `Repository.ts` and the plugin method definitions. Unknown plugin
+* methods pass through unwrapped (callers use the standalone helper).
+*/
+const SESSION_OPTIONS_INDEX = Object.freeze({
+	create: 1,
+	update: 2,
+	delete: 1,
+	getById: 1,
+	getAll: 1,
+	getByIds: 1,
+	createMany: 1,
+	findAll: 1,
+	getOrCreate: 2,
+	count: 1,
+	exists: 1,
+	getByQuery: 1,
+	getOne: 1,
+	findOneAndUpdate: 2,
+	distinct: 2,
+	aggregate: 1,
+	aggregatePaginate: 0,
+	aggregatePipeline: 1,
+	aggregatePipelinePaginate: 0,
+	lookupPopulate: 0,
+	cursor: 1,
+	claim: 3,
+	claimVersion: 3,
+	applyTransition: 3,
+	archiveByFilter: 2,
+	purgeByField: 3,
+	purgeByFilter: 2,
+	upsert: 2,
+	increment: 3,
+	decrement: 3,
+	multiplyField: 3,
+	setMin: 3,
+	setMax: 3,
+	pushToArray: 3,
+	pullFromArray: 3,
+	addToSet: 3,
+	setField: 3,
+	unsetField: 2,
+	renameField: 3,
+	atomicUpdate: 2,
+	updateMany: 2,
+	deleteMany: 1,
+	bulkWrite: 1,
+	restore: 1,
+	getDeleted: 1,
+	addSubdocument: 3,
+	getSubdocument: 3,
+	updateSubdocument: 4,
+	deleteSubdocument: 3,
+	groupBy: 1,
+	sum: 2,
+	average: 2,
+	min: 2,
+	max: 2
+});
+/**
+* Public methods that pass through bound to the outer repo, WITHOUT the session — each for a stated
+* reason. Anything neither here nor in `SESSION_OPTIONS_INDEX` throws when called.
+*/
+const PASS_THROUGH = /* @__PURE__ */ new Set([
+	"on",
+	"off",
+	"emit",
+	"emitAsync",
+	"removeAllListeners",
+	"use",
+	"useMiddleware",
+	"buildAggregation",
+	"buildLookup",
+	"isDuplicateKeyError",
+	"isTransientConflictError",
+	"invalidateAggregateCache",
+	"registerMethod",
+	"hasMethod",
+	"getRegisteredMethods",
+	"embed",
+	"search",
+	"lease",
+	"extend",
+	"release",
+	"claimKey",
+	"completeClaim",
+	"expireClaim",
+	"failClaim",
+	"releaseClaim",
+	"saveClaimProgress",
+	"searchSimilar"
+]);
+/** Methods MongoDB cannot run inside a transaction. */
+const REFUSED_IN_TX = Object.freeze({ watch: "a change stream cannot be opened inside a transaction" });
+/**
+* Build a session-threaded proxy over `outer`. The returned object has the
+* same method signatures, but every CRUD call auto-injects the supplied
+* session into the options bag. Non-CRUD properties (Model, modelName,
+* hook API, utility helpers) pass through.
+*/
+function createTxBoundRepo(outer, session) {
+	return new Proxy(outer, { get(target, prop, receiver) {
+		if (prop === "withTransaction") return () => {
+			throw new Error("[mongokit] Nested withTransaction is not supported on a tx-bound repository. Reuse the outer `txRepo` directly, or collapse the nesting.");
+		};
+		const value = Reflect.get(target, prop, receiver);
+		if (typeof value !== "function") return value;
+		if (prop === "Model") return value;
+		if (typeof prop === "symbol") return value.bind(target);
+		if (prop.startsWith("_")) return value.bind(target);
+		const optionsIndex = SESSION_OPTIONS_INDEX[prop];
+		if (optionsIndex === void 0) {
+			if (PASS_THROUGH.has(prop)) return value.bind(target);
+			const refused = REFUSED_IN_TX[prop];
+			return () => {
+				throw new Error(refused ? `[mongokit] ${prop}() cannot run on a tx-bound repository: ${refused}.` : `[mongokit] ${prop}() is not classified for transactions, so on a tx-bound repository it would run OUTSIDE the transaction. Call it on the outer repository with the session the callback receives — \`repo.${prop}(..., { session: uow.session })\` — or add it to tx-bound's SESSION_OPTIONS_INDEX / PASS_THROUGH.`);
+			};
+		}
+		return function txBoundMethod(...args) {
+			while (args.length <= optionsIndex) args.push(void 0);
+			const current = args[optionsIndex];
+			if (current === void 0) args[optionsIndex] = { session };
+			else if (typeof current === "object" && current !== null && !Array.isArray(current)) args[optionsIndex] = {
+				...current,
+				session
+			};
+			else throw new TypeError(`[mongokit] ${prop}(): argument ${optionsIndex} must be an options object on a tx-bound repository (got ${Array.isArray(current) ? "an array" : typeof current}) — the session could not be threaded.`);
+			return value.apply(target, args);
+		};
+	} });
+}
+//#endregion
+//#region src/transaction.ts
+/**
+* Run a callback inside a MongoDB transaction on the given connection.
+*
+* - Starts a session, runs `session.withTransaction(callback)` (which auto-retries
+*   on `TransientTransactionError` and `UnknownTransactionCommitResult`), and
+*   always ends the session in `finally`.
+* - When `allowFallback` is true and the deployment doesn't support transactions
+*   (e.g. standalone MongoDB in dev), the callback runs once without a
+*   transaction on the same session. `onFallback` is invoked with the original
+*   error so hosts can log the degradation.
+*
+* @example
+* ```ts
+* import mongoose from 'mongoose';
+* import { withTransaction } from '@classytic/mongokit';
+*
+* await withTransaction(mongoose.connection, async (session) => {
+*   const order  = await orderRepo.create(data, { session });
+*   await inventoryRepo.decrement(order.items, { session });
+*   return order;
+* });
+* ```
+*/
+async function withTransaction(connection, callback, options = {}) {
+	const session = await connection.startSession();
+	try {
+		return await session.withTransaction(() => callback(session), options.transactionOptions);
+	} catch (error) {
+		const err = error;
+		if (options.allowFallback && isTransactionUnsupported(err)) {
+			options.onFallback?.(err);
+			return await callback(session);
+		}
+		throw err;
+	} finally {
+		await session.endSession();
+	}
+}
+/**
+* Multi-repo transactional batch — every repo in `repos` becomes a
+* session-bound proxy inside the callback. Eliminates the per-call
+* `{ session }` threading that was repeated across ~20 call sites
+* (be-prod outbox writes, order placement, transfer source/dest pairs,
+* payrun saga steps).
+*
+* Same retry + fallback semantics as `withTransaction`: the
+* `transactionOptions` / `allowFallback` / `onFallback` knobs apply.
+*
+* Each property of the input `repos` map is rebound via the
+* `createTxBoundRepo` proxy — every CRUD method on the bound repo
+* auto-injects `session` into its options bag, including
+* `claim` / `claimVersion` / `findOneAndUpdate` and plugin-contributed
+* methods. Non-CRUD properties (Model, modelName, hook engine,
+* idField) pass through to the underlying repo. Nested
+* `boundRepo.withTransaction(...)` throws — reuse the outer bound
+* repos.
+*
+* @example Order placement across three repos in one transaction
+* ```ts
+* import { batchTransaction } from '@classytic/mongokit';
+*
+* const order = await batchTransaction(
+*   mongoose.connection,
+*   { orders: orderRepo, events: eventRepo, inventory: inventoryRepo },
+*   async ({ orders, events, inventory }) => {
+*     const created = await orders.create(orderData);          // session auto-injected
+*     await events.create({ type: 'order.placed', orderId: created._id });
+*     await inventory.claim(skuId, { from: 'available', to: 'reserved' });
+*     return created;
+*   },
+* );
+* ```
+*
+* @example With fallback for standalone-mongo dev environments
+* ```ts
+* await batchTransaction(
+*   mongoose.connection,
+*   { orders, events },
+*   async ({ orders, events }) => { ... },
+*   { allowFallback: true, onFallback: (err) => log.warn(err) },
+* );
+* ```
+*
+* @param connection - Mongoose connection (or anything with
+*   `startSession()`). Single source of session truth — every bound
+*   repo shares this session.
+* @param repos - Map of repo instances to rebind. Keys become the
+*   property names on the callback's argument.
+* @param callback - Receives the bound repo map. Return value flows
+*   through to the outer `Promise`.
+*/
+async function batchTransaction(connection, repos, callback, options = {}) {
+	return withTransaction(connection, async (session) => {
+		const bound = {};
+		for (const key of Object.keys(repos)) {
+			const repo = repos[key];
+			bound[key] = createTxBoundRepo(repo, session);
+		}
+		return callback(bound);
+	}, options);
+}
+/**
+* Detect whether an error indicates the MongoDB deployment does not support
+* multi-document transactions (standalone server, older topology, etc.).
+*
+* Checks MongoDB error codes first — 263 (standalone) and 20 (unsupported
+* topology) — with a message-matching fallback for edge cases surfaced by
+* driver versions that throw before the proper code lands.
+*
+* **Driver-version drift:** modern mongoose / mongodb-driver versions hit
+* the standalone case via the retryable-writes precondition rather than
+* the transaction precondition (`retryWrites=true` is on by default,
+* standalone Mongo rejects it before the transaction is even attempted).
+* So we accept that message as equivalent — the underlying topology
+* problem is the same, and the fallback semantics are correct either way.
+*/
+function isTransactionUnsupported(error) {
+	const code = error.code;
+	if (code === 263 || code === 20) return true;
+	const message = (error.message || "").toLowerCase();
+	return message.includes("transaction numbers are only allowed on a replica set member") || message.includes("transaction is not supported") || message.includes("does not support retryable writes");
+}
+/**
+* PROACTIVELY report whether a connection's deployment supports multi-document
+* transactions — the read-side companion to {@link isTransactionUnsupported}
+* (which classifies a FAILED attempt). Lets a caller skip a doomed transaction
+* attempt on standalone dev Mongo rather than starting one just to catch the
+* error.
+*
+* Delegates to {@link resolveTransactionSupport} so mongokit has exactly ONE
+* topology reader. That also fixes a false NEGATIVE this function used to
+* have: it tested `description.type !== 'Single'`, but a single-node replica
+* set reached with `directConnection` is `Single` with a server type of
+* `RSPrimary` and runs transactions fine. The shared reader looks at the
+* SERVER descriptions first.
+*
+* **`unknown` is optimistic HERE and pessimistic in `capabilities.ts` — the
+* difference is deliberate.** This answers "should I bother ATTEMPTING a
+* transaction?", where guessing yes costs one caught error (`allowFallback`
+* still recovers). The capability descriptor answers "may this deployment be
+* trusted with money?", where guessing yes is the bug class this repo keeps
+* hitting (AGENTS.md FAIL LOUD rule 3). Do not "unify" them.
+*
+* Accepts a Mongoose `Connection` (or anything exposing `getClient()`/`client`
+* with a driver `topology`), so it stays decoupled from mongoose types.
+*/
+function supportsTransactions(connection) {
+	return resolveTransactionSupport(connection) !== "no";
+}
+//#endregion
+export { createTxBoundRepo as a, classifyHelloReply as c, resolveMongoCapabilities as d, resolveTransactionSupport as f, withTransaction as i, probeMongoCapabilities as l, isTransactionUnsupported as n, MONGOKIT_CAPABILITIES as o, transactionResolutionOf as p, supportsTransactions as r, capabilitiesForSupport as s, batchTransaction as t, resetCapabilityProbeCache as u };