Add TransactionOptions (#6189)

* Add TransactionOptions

* Fix whitespace

* Fix whitespace

* Add changeset

* Update comments

Author: tom-andersen

.changeset/lazy-nails-guess.md

@@ -0,0 +1,5 @@
+---
+'@firebase/firestore': patch
+---
+
+Add `TransactionOptions` param to `runTransaction` method

common/api-review/firestore-lite.api.md

@@ -254,7 +254,7 @@ export class QuerySnapshot<T = DocumentData> {
 export function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
 
 // @public
-export function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>): Promise<T>;
+export function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
 
 // @public
 export function serverTimestamp(): FieldValue;
@@ -331,6 +331,11 @@ export class Transaction {
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this;
 }
 
+// @public
+export interface TransactionOptions {
+    readonly maxAttempts?: number;
+}
+
 // @public
 export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 

common/api-review/firestore.api.md

@@ -385,7 +385,7 @@ export class QuerySnapshot<T = DocumentData> {
 export function refEqual<T>(left: DocumentReference<T> | CollectionReference<T>, right: DocumentReference<T> | CollectionReference<T>): boolean;
 
 // @public
-export function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>): Promise<T>;
+export function runTransaction<T>(firestore: Firestore, updateFunction: (transaction: Transaction) => Promise<T>, options?: TransactionOptions): Promise<T>;
 
 // @public
 export function serverTimestamp(): FieldValue;
@@ -475,6 +475,11 @@ export class Transaction {
     update(documentRef: DocumentReference<unknown>, field: string | FieldPath, value: unknown, ...moreFieldsAndValues: unknown[]): this;
 }
 
+// @public
+export interface TransactionOptions {
+    readonly maxAttempts?: number;
+}
+
 // @public
 export type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
 

packages/firestore/lite/index.ts

@@ -111,6 +111,8 @@ export {
 
 export { WriteBatch, writeBatch } from '../src/lite-api/write_batch';
 
+export { TransactionOptions } from '../src/lite-api/transaction_options';
+
 export { Transaction, runTransaction } from '../src/lite-api/transaction';
 
 export { setLogLevel, LogLevelString as LogLevel } from '../src/util/log';

packages/firestore/src/api.ts

@@ -89,6 +89,8 @@ export {
 
 export { Unsubscribe, SnapshotListenOptions } from './api/reference_impl';
 
+export { TransactionOptions } from './api/transaction_options';
+
 export { runTransaction, Transaction } from './api/transaction';
 
 export {

packages/firestore/src/api/transaction.ts

@@ -17,6 +17,11 @@
 
 import { firestoreClientTransaction } from '../core/firestore_client';
 import { Transaction as InternalTransaction } from '../core/transaction';
+import {
+  TransactionOptions as TranasactionOptionsInternal,
+  DEFAULT_TRANSACTION_OPTIONS,
+  validateTransactionOptions
+} from '../core/transaction_options';
 import { DocumentReference } from '../lite-api/reference';
 import { Transaction as LiteTransaction } from '../lite-api/transaction';
 import { validateReference } from '../lite-api/write_batch';
@@ -25,6 +30,7 @@ import { cast } from '../util/input_validation';
 import { ensureFirestoreConfigured, Firestore } from './database';
 import { ExpUserDataWriter } from './reference_impl';
 import { DocumentSnapshot, SnapshotMetadata } from './snapshot';
+import { TransactionOptions } from './transaction_options';
 
 /**
  * A reference to a transaction.
@@ -92,11 +98,20 @@ export class Transaction extends LiteTransaction {
  */
 export function runTransaction<T>(
   firestore: Firestore,
-  updateFunction: (transaction: Transaction) => Promise<T>
+  updateFunction: (transaction: Transaction) => Promise<T>,
+  options?: TransactionOptions
 ): Promise<T> {
   firestore = cast(firestore, Firestore);
+  const optionsWithDefaults: TranasactionOptionsInternal = {
+    ...DEFAULT_TRANSACTION_OPTIONS,
+    ...options
+  };
+  validateTransactionOptions(optionsWithDefaults);
   const client = ensureFirestoreConfigured(firestore);
-  return firestoreClientTransaction(client, internalTransaction =>
-    updateFunction(new Transaction(firestore, internalTransaction))
+  return firestoreClientTransaction(
+    client,
+    internalTransaction =>
+      updateFunction(new Transaction(firestore, internalTransaction)),
+    optionsWithDefaults
   );
 }

packages/firestore/src/api/transaction_options.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { TransactionOptions } from '../lite-api/transaction_options';

packages/firestore/src/core/firestore_client.ts

@@ -82,6 +82,7 @@ import {
   syncEngineWrite
 } from './sync_engine_impl';
 import { Transaction } from './transaction';
+import { TransactionOptions } from './transaction_options';
 import { TransactionRunner } from './transaction_runner';
 import { View } from './view';
 import { ViewSnapshot } from './view_snapshot';
@@ -483,14 +484,16 @@ export function firestoreClientAddSnapshotsInSyncListener(
  */
 export function firestoreClientTransaction<T>(
   client: FirestoreClient,
-  updateFunction: (transaction: Transaction) => Promise<T>
+  updateFunction: (transaction: Transaction) => Promise<T>,
+  options: TransactionOptions
 ): Promise<T> {
   const deferred = new Deferred<T>();
   client.asyncQueue.enqueueAndForget(async () => {
     const datastore = await getDatastore(client);
     new TransactionRunner<T>(
       client.asyncQueue,
       datastore,
+      options,
       updateFunction,
       deferred
     ).run();

packages/firestore/src/core/transaction_options.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Code, FirestoreError } from '../util/error';
+
+export const DEFAULT_TRANSACTION_OPTIONS: TransactionOptions = {
+  maxAttempts: 5
+};
+
+/**
+ * Options to customize transaction behavior.
+ */
+export declare interface TransactionOptions {
+  /** Maximum number of attempts to commit, after which transaction fails. Default is 5. */
+  readonly maxAttempts: number;
+}
+
+export function validateTransactionOptions(options: TransactionOptions): void {
+  if (options.maxAttempts < 1) {
+    throw new FirestoreError(
+      Code.INVALID_ARGUMENT,
+      'Max attempts must be at least 1'
+    );
+  }
+}

packages/firestore/src/core/transaction_runner.ts

@@ -24,23 +24,24 @@ import { Deferred } from '../util/promise';
 import { isNullOrUndefined } from '../util/types';
 
 import { Transaction } from './transaction';
-
-export const DEFAULT_MAX_ATTEMPTS_COUNT = 5;
+import { TransactionOptions } from './transaction_options';
 
 /**
  * TransactionRunner encapsulates the logic needed to run and retry transactions
  * with backoff.
  */
 export class TransactionRunner<T> {
-  private attemptsRemaining = DEFAULT_MAX_ATTEMPTS_COUNT;
+  private attemptsRemaining: number;
   private backoff: ExponentialBackoff;
 
   constructor(
     private readonly asyncQueue: AsyncQueue,
     private readonly datastore: Datastore,
+    private readonly options: TransactionOptions,
     private readonly updateFunction: (transaction: Transaction) => Promise<T>,
     private readonly deferred: Deferred<T>
   ) {
+    this.attemptsRemaining = options.maxAttempts;
     this.backoff = new ExponentialBackoff(
       this.asyncQueue,
       TimerId.TransactionRetry

packages/firestore/src/lite-api/transaction.ts

@@ -18,6 +18,11 @@
 import { getModularInstance } from '@firebase/util';
 
 import { Transaction as InternalTransaction } from '../core/transaction';
+import {
+  DEFAULT_TRANSACTION_OPTIONS,
+  TransactionOptions as TranasactionOptionsInternal,
+  validateTransactionOptions
+} from '../core/transaction_options';
 import { TransactionRunner } from '../core/transaction_runner';
 import { fail } from '../util/assert';
 import { newAsyncQueue } from '../util/async_queue_impl';
@@ -39,6 +44,7 @@ import {
   LiteUserDataWriter
 } from './reference_impl';
 import { DocumentSnapshot } from './snapshot';
+import { TransactionOptions } from './transaction_options';
 import {
   newUserDataReader,
   parseSetData,
@@ -266,14 +272,21 @@ export class Transaction {
  */
 export function runTransaction<T>(
   firestore: Firestore,
-  updateFunction: (transaction: Transaction) => Promise<T>
+  updateFunction: (transaction: Transaction) => Promise<T>,
+  options?: TransactionOptions
 ): Promise<T> {
   firestore = cast(firestore, Firestore);
   const datastore = getDatastore(firestore);
+  const optionsWithDefaults: TranasactionOptionsInternal = {
+    ...DEFAULT_TRANSACTION_OPTIONS,
+    ...options
+  };
+  validateTransactionOptions(optionsWithDefaults);
   const deferred = new Deferred<T>();
   new TransactionRunner<T>(
     newAsyncQueue(),
     datastore,
+    optionsWithDefaults,
     internalTransaction =>
       updateFunction(new Transaction(firestore, internalTransaction)),
     deferred

packages/firestore/src/lite-api/transaction_options.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2022 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Options to customize transaction behavior.
+ */
+export declare interface TransactionOptions {
+  /** Maximum number of attempts to commit, after which transaction fails. Default is 5. */
+  readonly maxAttempts?: number;
+}