From d15dcbb3e7ca8ce192611041f70ce7af7b30bded Mon Sep 17 00:00:00 2001 From: Aditi Khare <106987683+aditi-khare-mongoDB@users.noreply.github.com> Date: Fri, 15 Mar 2024 09:55:19 -0400 Subject: [PATCH] docs(NODE-5721): thrown error expectations in withTransaction (#4038) --- src/sessions.ts | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/src/sessions.ts b/src/sessions.ts index e04c802b3c..4738c0f64e 100644 --- a/src/sessions.ts +++ b/src/sessions.ts @@ -435,18 +435,26 @@ export class ClientSession extends TypedEventEmitter { /** * Starts a transaction and runs a provided function, ensuring the commitTransaction is always attempted when all operations run in the function have completed. * - * **IMPORTANT:** This method requires the user to return a Promise, and `await` all operations. + * **IMPORTANT:** This method requires the function passed in to return a Promise. That promise must be made by `await`-ing all operations in such a way that rejections are propagated to the returned promise. * * @remarks - * This function: - * - If all operations successfully complete and the `commitTransaction` operation is successful, then this function will return the result of the provided function. - * - If the transaction is unable to complete or an error is thrown from within the provided function, then this function will throw an error. + * - If all operations successfully complete and the `commitTransaction` operation is successful, then the provided function will return the result of the provided function. + * - If the transaction is unable to complete or an error is thrown from within the provided function, then the provided function will throw an error. * - If the transaction is manually aborted within the provided function it will not throw. - * - May be called multiple times if the driver needs to attempt to retry the operations. + * - If the driver needs to attempt to retry the operations, the provided function may be called multiple times. * * Checkout a descriptive example here: * @see https://www.mongodb.com/blog/post/quick-start-nodejs--mongodb--how-to-implement-transactions * + * If a command inside withTransaction fails: + * - It may cause the transaction on the server to be aborted. + * - This situation is normally handled transparently by the driver. + * - However, if the application catches such an error and does not rethrow it, the driver will not be able to determine whether the transaction was aborted or not. + * - The driver will then retry the transaction indefinitely. + * + * To avoid this situation, the application must not silently handle errors within the provided function. + * If the application needs to handle errors within, it must await all operations such that if an operation is rejected it becomes the rejection of the callback function passed into withTransaction. + * * @param fn - callback to run within a transaction * @param options - optional settings for the transaction * @returns A raw command response or undefined