Implement Symbol.asyncIterator for cursors (#616)

* Implement Symbol.asyncIterator

* Add to CHANGELOG, add warning

Author: pluma

CHANGELOG.md

@@ -327,6 +327,11 @@ This is a major release and breaks backwards compatibility.
   The method takes a document or a document key and returns a fully qualified
   document ID string for the document in the current collection.
 
+- Added support for `for await` in `ArrayCursor`
+
+  It is now possible to use `for await` to iterate over each item in a cursor
+  asynchronously.
+
 - Improved type signatures for TypeScript
 
   Most methods should now provide full type signatures for options and response

src/cursor.ts

@@ -100,6 +100,34 @@ export class ArrayCursor<T = any> {
     return this.hasMore || Boolean(this._result.length);
   }
 
+  /**
+   * Enables use with `for await` to exhaust the cursor by asynchronously
+   * yielding every value in the cursor's remaining result set.
+   *
+   * **Note**: If the result set spans multiple batches, any unfetched batches
+   * will only be fetched on demand. Depending on the cursor's TTL and the
+   * processing speed, this may result in the server discarding the cursor
+   * before it is fully depleted.
+   *
+   * @example
+   * ```js
+   * const cursor = await db.query(aql`
+   *   FOR user IN users
+   *   FILTER user.isActive
+   *   RETURN user
+   * `);
+   * for await (const user of cursor) {
+   *   console.log(user.email, user.isAdmin);
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator](): AsyncGenerator<T, undefined, undefined> {
+    while (this.hasNext) {
+      yield this.next() as Promise<T>;
+    }
+    return undefined;
+  }
+
   /**
    * TODO
    */

src/test/08-cursors.ts

@@ -30,6 +30,17 @@ describe("Cursor API", () => {
   beforeEach(async () => {
     cursor = await db.query(aqlQuery);
   });
+  describe("for await of cursor", () => {
+    it("returns each next result of the Cursor", async () => {
+      let i = 0;
+      for await (const value of cursor) {
+        expect(value).to.equal(aqlResult[i]);
+        i += 1;
+      }
+      expect(i).to.equal(aqlResult.length);
+      expect(cursor.hasNext).to.equal(false);
+    });
+  });
   describe("cursor.all", () => {
     it("returns an Array of all results", async () => {
       const values = await cursor.all();