Implement db.withTransaction helper

Author: pluma

CHANGELOG.md

@@ -52,6 +52,21 @@ This driver uses semantic versioning:
 
 - Added cluster rebalancing methods to `Database` (DE-583)
 
+- Added `db.withTransaction` helper method for streaming transactions ([#786](https://github.com/arangodb/arangojs/discussions/786))
+
+  This method allows using streaming transactions without having to manually
+  begin and commit or abort the transaction.
+
+  ```ts
+  const vertices = db.collection("vertices");
+  const edges = db.collection("edges");
+  const info = await db.withTransaction([vertices, edges], async (step) => {
+    const start = await step(() => vertices.document("a"));
+    const end = await step(() => vertices.document("b"));
+    return await step(() => edges.save({ _from: start._id, _to: end._id }));
+  });
+  ```
+
 ## [8.3.1] - 2023-06-05
 
 ### Changed

src/database.ts

@@ -3677,7 +3677,7 @@ export class Database {
    * {@link graph.GraphVertexCollection}, {@link graph.GraphEdgeCollection} as well as
    * (in TypeScript) {@link collection.DocumentCollection} and {@link collection.EdgeCollection}.
    *
-   * @param collections - A collection that can be read from and written to
+   * @param collection - A collection that can be read from and written to
    * during the transaction.
    * @param options - Options for the transaction.
    *
@@ -3721,6 +3721,142 @@ export class Database {
     );
   }
 
+  /**
+   * Begins and commits a transaction using the given callback. Individual
+   * requests that are part of the transaction need to be wrapped in the step
+   * function passed into the callback. If the promise returned by the callback
+   * is rejected, the transaction will be aborted.
+   *
+   * Collections can be specified as collection names (strings) or objects
+   * implementing the {@link collection.ArangoCollection} interface: `Collection`,
+   * {@link graph.GraphVertexCollection}, {@link graph.GraphEdgeCollection} as
+   * well as (in TypeScript) {@link collection.DocumentCollection} and
+   * {@link collection.EdgeCollection}.
+   *
+   * @param collections - Collections involved in the transaction.
+   * @param callback - Callback function executing the transaction steps.
+   * @param options - Options for the transaction.
+   *
+   * @example
+   * ```js
+   * const vertices = db.collection("vertices");
+   * const edges = db.collection("edges");
+   * await db.withTransaction(
+   *   {
+   *     read: ["vertices"],
+   *     write: [edges] // collection instances can be passed directly
+   *   },
+   *   async (step) => {
+   *     const start = await step(() => vertices.document("a"));
+   *     const end = await step(() => vertices.document("b"));
+   *     await step(() => edges.save({ _from: start._id, _to: end._id }));
+   *   }
+   * );
+   * ```
+   */
+  withTransaction<T>(
+    collections: TransactionCollections,
+    callback: (step: Transaction["step"]) => Promise<T>,
+    options?: TransactionOptions
+  ): Promise<T>;
+  /**
+   * Begins and commits a transaction using the given callback. Individual
+   * requests that are part of the transaction need to be wrapped in the step
+   * function passed into the callback. If the promise returned by the callback
+   * is rejected, the transaction will be aborted.
+   *
+   * Collections can be specified as collection names (strings) or objects
+   * implementing the {@link collection.ArangoCollection} interface: `Collection`,
+   * {@link graph.GraphVertexCollection}, {@link graph.GraphEdgeCollection} as well as
+   * (in TypeScript) {@link collection.DocumentCollection} and {@link collection.EdgeCollection}.
+   *
+   * @param collections - Collections that can be read from and written to
+   * during the transaction.
+   * @param callback - Callback function executing the transaction steps.
+   * @param options - Options for the transaction.
+   *
+   * @example
+   * ```js
+   * const vertices = db.collection("vertices");
+   * const edges = db.collection("edges");
+   * await db.withTransaction(
+   *   [
+   *     "vertices",
+   *     edges, // collection instances can be passed directly
+   *   ],
+   *   async (step) => {
+   *     const start = await step(() => vertices.document("a"));
+   *     const end = await step(() => vertices.document("b"));
+   *     await step(() => edges.save({ _from: start._id, _to: end._id }));
+   *   }
+   * );
+   * ```
+   */
+  withTransaction<T>(
+    collections: (string | ArangoCollection)[],
+    callback: (step: Transaction["step"]) => Promise<T>,
+    options?: TransactionOptions
+  ): Promise<T>;
+  /**
+   * Begins and commits a transaction using the given callback. Individual
+   * requests that are part of the transaction need to be wrapped in the step
+   * function passed into the callback. If the promise returned by the callback
+   * is rejected, the transaction will be aborted.
+   *
+   * The Collection can be specified as a collection name (string) or an object
+   * implementing the {@link collection.ArangoCollection} interface: `Collection`,
+   * {@link graph.GraphVertexCollection}, {@link graph.GraphEdgeCollection} as well as
+   * (in TypeScript) {@link collection.DocumentCollection} and {@link collection.EdgeCollection}.
+   *
+   * @param collection - A collection that can be read from and written to
+   * during the transaction.
+   * @param callback - Callback function executing the transaction steps.
+   * @param options - Options for the transaction.
+   *
+   * @example
+   * ```js
+   * const vertices = db.collection("vertices");
+   * const start = vertices.document("a");
+   * const end = vertices.document("b");
+   * const edges = db.collection("edges");
+   * await db.withTransaction(
+   *   edges, // collection instances can be passed directly
+   *   async (step) => {
+   *     await step(() => edges.save({ _from: start._id, _to: end._id }));
+   *   }
+   * );
+   * ```
+   */
+  withTransaction<T>(
+    collection: string | ArangoCollection,
+    callback: (step: Transaction["step"]) => Promise<T>,
+    options?: TransactionOptions
+  ): Promise<T>;
+  async withTransaction<T>(
+    collections:
+      | TransactionCollections
+      | (string | ArangoCollection)[]
+      | string
+      | ArangoCollection,
+    callback: (step: Transaction["step"]) => Promise<T>,
+    options: TransactionOptions = {}
+  ): Promise<T> {
+    const trx = await this.beginTransaction(
+      collections as TransactionCollections,
+      options
+    );
+    try {
+      const result = await callback((fn) => trx.step(fn));
+      await trx.commit();
+      return result;
+    } catch (e) {
+      try {
+        await trx.abort();
+      } catch {}
+      throw e;
+    }
+  }
+
   /**
    * Fetches all active transactions from the database and returns an array of
    * transaction descriptions.