From d3031a5fd818ab2ec1fbaf85464bf55413a4a25f Mon Sep 17 00:00:00 2001
From: Warren James <warren.james@mongodb.com>
Date: Tue, 28 May 2024 16:08:02 -0400
Subject: [PATCH] docs(NODE-6191): clarify that operations should not be
 parallelized in transactions (#4122)

Co-authored-by: Aditi Khare <106987683+aditi-khare-mongoDB@users.noreply.github.com>
---
 src/sessions.ts | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/sessions.ts b/src/sessions.ts
index b766d40e28..20699d24ac 100644
--- a/src/sessions.ts
+++ b/src/sessions.ts
@@ -369,6 +369,11 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
   /**
    * Starts a new transaction with the given options.
    *
+   * @remarks
+   * **IMPORTANT**: Running operations in parallel is not supported during a transaction. The use of `Promise.all`,
+   * `Promise.allSettled`, `Promise.race`, etc to parallelize operations inside a transaction is
+   * undefined behaviour.
+   *
    * @param options - Options for the transaction
    */
   startTransaction(options?: TransactionOptions): void {
@@ -443,6 +448,11 @@ export class ClientSession extends TypedEventEmitter<ClientSessionEvents> {
    *
    * **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.
    *
+   * **IMPORTANT:** Running operations in parallel is not supported during a transaction. The use of `Promise.all`,
+   * `Promise.allSettled`, `Promise.race`, etc to parallelize operations inside a transaction is
+   * undefined behaviour.
+   *
+   *
    * @remarks
    * - 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.