Method withTransaction

src/sessions.ts:714–915

* 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 function passed in to return a Promise. That promise must be made by `await`-ing all opera

(
    fn: WithTransactionCallback<T>,
    options?: TransactionOptions & {
      /**
       * Configures a timeoutMS expiry for the entire withTransactionCallback.
       *
       * @remarks
       * - The remaining timeout will not be applied to callback operations that do not use the ClientSession.
       * - Overriding timeoutMS for operations executed using the explicit session inside the provided callback will result in a client-side error.
       */
      timeoutMS?: number;
    }
  )

   * @returns A raw command response or undefined
   */
  async withTransaction<T = any>(
    fn: WithTransactionCallback<T>,
    options?: TransactionOptions & {
      /**
       * Configures a timeoutMS expiry for the entire withTransactionCallback.
       *
       * @remarks
       * - The remaining timeout will not be applied to callback operations that do not use the ClientSession.
       * - Overriding timeoutMS for operations executed using the explicit session inside the provided callback will result in a client-side error.
       */
      timeoutMS?: number;
    }
  ): Promise<T> {
    const MAX_TIMEOUT = 120_000;

    const timeoutMS = options?.timeoutMS ?? this.timeoutMS ?? null;
    this.timeoutContext =
      timeoutMS != null
        ? TimeoutContext.create({
            timeoutMS,
            serverSelectionTimeoutMS: this.clientOptions.serverSelectionTimeoutMS,
            socketTimeoutMS: this.clientOptions.socketTimeoutMS
          })
        : null;

    // 1. Define the following:
    // 1.1 Record the current monotonic time, which will be used to enforce the 120-second / CSOT timeout before later retry attempts.
    // 1.2 Set `transactionAttempt` to `0`.
    // 1.3 Set `TIMEOUT_MS` to be `timeoutMS` if given, otherwise MAX_TIMEOUT (120-seconds).

    // Timeout Error propagation
    // When the previously encountered error needs to be propagated because there is no more time for another attempt,
    // and it is not already a timeout error, then:
    //  - A timeout error MUST be propagated instead. It MUST expose the previously encountered error as specified in
    //    the "Errors" section of the CSOT specification.
    //  - If exposing the previously encountered error from a timeout error is impossible in a driver, then the driver
    //    is exempt from the requirement and MUST propagate the previously encountered error as is. The timeout error
    //    MUST copy all error labels from the previously encountered error.

    // The spec describes timeout checks as "elapsed time < TIMEOUT_MS" (where elapsed = now - start).
    // We precompute `deadline = now + remainingTimeMS` so each check becomes simply `now < deadline`.
    const csotEnabled = !!this.timeoutContext?.csotEnabled();
    const remainingTimeMS = this.timeoutContext?.csotEnabled()
      ? this.timeoutContext.remainingTimeMS
      : MAX_TIMEOUT;
    const deadline = processTimeMS() + remainingTimeMS;

    let committed = false;
    let result: T;

    let lastError: Error | null = null;

    try {
      retryTransaction: for (
        let transactionAttempt = 0, isRetry = false;
        !committed;
        ++transactionAttempt, isRetry = transactionAttempt > 0
      ) {