Are there any code examples demonstrating how to include AQL queries in a stream transaction?

[ir0nCr055]

Aside from a brief mention of db.query in this source code comment I couldn't find any explicit documentation on how someone could run AQL queries as part of a stream transaction using arangojs.

Given the subtleties of the Transaction's step() API it would be extremely helpful if there were at least one full example showing how this could be achieved according to best practices (using trx.step with db.query, curor.next, cursor.all, etc.).

I assume there are legit cases where mixing AQL queries with Collection API calls inside a stream transaction could address known AQL limitations.

For the sake of this Github issue, here's a (admittedly weak) example showing how a stream transaction could be used to configure fine-grained collection access for an AQL query (or maybe I'm doing it wrong. :) )

   /**
     *
     * @example
     * ```js
     *  const completedTransactionIds = ['1', '2', '3'];     
     *
     *  const db = new Database();
     *  const transactions = db.collection("transactions");
     *  const logs = db.collection("logs")
     *  const trx = await db.beginTransaction({ exclusive: [transactions], write: [logs] });
     * 
     *
     *  // Stream Transactions may include AQL queries
     *  await trx.step(() => db.query(aql`
     *      FOR tran IN ${transactions}
     *         FILTER tran.id IN ${completedTransactionIds}
     *         UPDATE tran WITH { status: "completed" } IN ${transactions}
     *         INSERT { transactionId: tran.id, message: "Transaction was completed", created: DATE_NOW() } INTO ${logs}
     *  `));
     *
     *  await trx.commit();
     * ```
     *
     */

[pluma4345]

Cursors that are split over multiple batches are identified by a batch ID so fetching additional batches does not require the use of trx.step (but it won't hurt). This is an implementation detail of ArangoDB.

[pluma4345]

I've added a note to the db.query documentation to clarify that the step method is not necessary to consume the cursor.