@digitaldefiance/node-express-suite-mongo 4.23.0

package/src/utils/mongo-transaction.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * @fileoverview Mongoose-specific transaction utilities.
+ * Contains the Mongoose Connection overload of withTransaction
+ * and related helper functions for transient error detection and retry logic.
+ * @module utils/mongo-transaction
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTransientTransactionError = isTransientTransactionError;
+exports.computeRetryDelay = computeRetryDelay;
+exports.withMongoTransaction = withMongoTransaction;
+const suite_core_lib_1 = require("@digitaldefiance/suite-core-lib");
+const node_express_suite_1 = require("@digitaldefiance/node-express-suite");
+/**
+ * Checks whether an error is a transient transaction error that can be retried.
+ */
+function isTransientTransactionError(error) {
+    if (!error)
+        return false;
+    const errorLabelSet = error['errorLabelSet'];
+    const code = error['code'];
+    const message = error['message'];
+    return ((errorLabelSet?.has('TransientTransactionError') ?? false) ||
+        (errorLabelSet?.has('UnknownTransactionCommitResult') ?? false) ||
+        code === 251 || // NoSuchTransaction
+        code === 112 || // WriteConflict
+        code === 11000 || // DuplicateKey
+        code === 16500 || // TransactionAborted
+        code === 244 || // TransactionTooOld
+        code === 246 || // ExceededTimeLimit
+        code === 13436 || // TransactionTooLargeForCache
+        code === 50 || // MaxTimeMSExpired
+        (message?.includes('Transaction') ?? false) ||
+        (message?.includes('aborted') ?? false) ||
+        (message?.includes('WriteConflict') ?? false) ||
+        (message?.includes('NoSuchTransaction') ?? false) ||
+        (message?.includes('TransactionTooOld') ?? false) ||
+        (message?.includes('ExceededTimeLimit') ?? false) ||
+        (message?.includes('duplicate key error') ?? false) ||
+        (message?.includes('E11000') ?? false) ||
+        (code === 11000 && (message?.includes('duplicate') ?? false)));
+}
+/**
+ * Computes the retry delay with linear backoff and jitter.
+ */
+function computeRetryDelay(baseDelay, attempt, isTestEnvironment) {
+    const jitter = Math.random() * 0.3;
+    const actualBaseDelay = isTestEnvironment
+        ? Math.floor(baseDelay * 0.5)
+        : baseDelay;
+    return Math.floor(actualBaseDelay * (1 + attempt * 0.5) * (1 + jitter));
+}
+/**
+ * Wraps a callback in a Mongoose transaction if necessary.
+ * Uses a mongoose Connection to manage sessions and transactions.
+ * @param connection The mongoose connection
+ * @param useTransaction Whether to use a transaction
+ * @param session The session to use
+ * @param callback The callback to wrap
+ * @param options Transaction options including timeout and retry attempts
+ * @param args The arguments to pass to the callback
+ * @returns The result of the callback
+ */
+async function withMongoTransaction(connection, useTransaction, session, callback, options = {}, ...args) {
+    const engine = (0, suite_core_lib_1.getSuiteCoreI18nEngine)(options.application
+        ? { constants: options.application.constants }
+        : undefined);
+    const isTestEnvironment = process.env['NODE_ENV'] === 'test';
+    const { timeoutMs = node_express_suite_1.DEFAULT_TRANSACTION_TIMEOUT, retryAttempts = node_express_suite_1.DEFAULT_RETRY_ATTEMPTS, baseDelay = (0, node_express_suite_1.getDefaultBaseDelay)(), debugLogEnabled, } = options;
+    if (!useTransaction) {
+        return await callback(session, undefined, ...args);
+    }
+    const needSession = useTransaction && session === undefined;
+    const client = connection.getClient();
+    if (!client) {
+        (0, node_express_suite_1.debugLog)(debugLogEnabled === true, 'warn', engine.translateStringKey(suite_core_lib_1.SuiteCoreStringKey.Admin_NoMongoDbClientFoundFallingBack));
+        return await callback(session, undefined, ...args);
+    }
+    let attempt = 0;
+    while (attempt < retryAttempts) {
+        const s = needSession
+            ? await client.startSession()
+            : session;
+        try {
+            if (needSession && s !== undefined) {
+                await s.startTransaction({
+                    maxCommitTimeMS: timeoutMs,
+                });
+            }
+            // Race the callback against the timeout
+            const timeoutPromise = new Promise((_, reject) => {
+                setTimeout(() => {
+                    reject(new Error(engine.translateStringKey(suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionTimeoutTemplate, { timeMs: timeoutMs })));
+                }, timeoutMs);
+            });
+            const result = await Promise.race([callback(s, ...args), timeoutPromise]);
+            if (needSession && s !== undefined)
+                await s.commitTransaction();
+            return result;
+        }
+        catch (error) {
+            const err = error;
+            if (needSession && s !== undefined && s.inTransaction())
+                await s.abortTransaction();
+            const isTransientError = isTransientTransactionError(err);
+            if (isTransientError && attempt < retryAttempts - 1) {
+                attempt++;
+                const delay = computeRetryDelay(baseDelay, attempt, isTestEnvironment);
+                (0, node_express_suite_1.debugLog)(debugLogEnabled === true, 'warn', engine.translateStringKey(suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionFailedTransientTemplate, { delayMs: delay, attempt, attempts: retryAttempts }, undefined));
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw error;
+        }
+        finally {
+            if (needSession && s !== undefined)
+                await s.endSession();
+        }
+    }
+    const jitter = Math.random() * 0.3;
+    const actualBaseDelay = isTestEnvironment
+        ? Math.floor(baseDelay * 0.5)
+        : baseDelay;
+    const delay = Math.floor(actualBaseDelay * (1 + attempt * 0.5) * (1 + jitter));
+    throw new suite_core_lib_1.TranslatableSuiteError(suite_core_lib_1.SuiteCoreStringKey.Admin_TransactionFailedTransientTemplate, {
+        delayMs: delay,
+        attempt,
+        attempts: retryAttempts,
+    });
+}
+//# sourceMappingURL=mongo-transaction.js.map

package/src/utils/mongo-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongo-transaction.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite-mongo/src/utils/mongo-transaction.ts"],"names":[],"mappings":"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"}

package/src/utils/object-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview MongoDB ObjectId validation utilities.
+ * @module utils/object-id
+ */
+/**
+ * Checks if a value is a valid MongoDB ObjectId string.
+ * @param id Value to check
+ * @returns True if valid ObjectId string
+ */
+export declare function isValidStringObjectId(id: unknown): boolean;
+//# sourceMappingURL=object-id.d.ts.map

package/src/utils/object-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-id.d.ts","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite-mongo/src/utils/object-id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAE1D"}

package/src/utils/object-id.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @fileoverview MongoDB ObjectId validation utilities.
+ * @module utils/object-id
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidStringObjectId = isValidStringObjectId;
+const mongoose_types_1 = require("@digitaldefiance/mongoose-types");
+/**
+ * Checks if a value is a valid MongoDB ObjectId string.
+ * @param id Value to check
+ * @returns True if valid ObjectId string
+ */
+function isValidStringObjectId(id) {
+    return typeof id === 'string' && mongoose_types_1.Types.ObjectId.isValid(id);
+}
+//# sourceMappingURL=object-id.js.map

package/src/utils/object-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-id.js","sourceRoot":"","sources":["../../../../../packages/digitaldefiance-node-express-suite-mongo/src/utils/object-id.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AASH,sDAEC;AATD,oEAAwD;AAExD;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,EAAW;IAC/C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,sBAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;AAC9D,CAAC"}