Add Cursor#nextBatch (#627)

* Add Cursor#nextBatch and hasNextBatch

* Remove cursor.hasNextBatch

The name is misleading, just use cursor.hasNext instead.

* Add docs

* Add tests

* Fix test

Author: pluma

CHANGELOG.md

@@ -15,6 +15,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   `cursor.kill` method. Note that this method has no effect if the cursor
   is already depleted.
 
+- Added `cursor.nextBatch` method
+
+  Cursors normally fetch additional batches as necessary while iterating
+  over the individual results, this method allows consuming an entire batch
+  at a time.
+
 ## [6.11.1] - 2019-08-30
 
 ### Fixed

docs/Drivers/JS/Reference/Cursor.md

@@ -72,6 +72,25 @@ await cursor.all(); // exhausts the cursor
 assert.equal(cursor.hasNext(), false);
 ```
 
+## cursor.nextBatch
+
+`async cursor.nextBatch(): Object`
+
+Advances the cursor and returns all remaining values in the cursor's current
+batch. If the current batch has already been exhausted, fetches the next batch
+from the server and returns it. If no more batches are available, returns
+`undefined` instead.
+
+**Examples**
+
+```js
+const cursor = await db.query(aql`FOR i IN 1..10 RETURN i`, { batchSize: 5 });
+await cursor.nextBatch(); // [1, 2, 3, 4, 5]
+await cursor.next(); // 6
+await cursor.nextBatch(); // [7, 8, 9, 10]
+cursor.hasNext(); // false
+```
+
 ## cursor.each
 
 `async cursor.each(fn): any`
@@ -165,7 +184,7 @@ const result = await cursor.every(even);
 assert.equal(result, false); // 3 is not even
 assert.equal(cursor.hasNext(), true);
 
-const value = await cursor.next();
+const value = await cursor.nextBatch();
 assert.equal(value, 4); // next value after 3
 ```
 

src/cursor.ts

@@ -64,10 +64,20 @@ export class ArrayCursor {
     return this._result.shift();
   }
 
-  hasNext() {
+  hasNext(): boolean {
     return Boolean(this._hasMore || this._result.length);
   }
 
+  async nextBatch(): Promise<any[] | undefined> {
+    while (!this._result.length && this._hasMore) {
+      await this._more();
+    }
+    if (!this._result.length) {
+      return undefined;
+    }
+    return this._result.splice(0, this._result.length);
+  }
+
   async each(
     fn: (value: any, index: number, self: ArrayCursor) => boolean | void
   ): Promise<boolean> {

src/test/08-cursors.ts

@@ -193,6 +193,23 @@ describe("Cursor API", () => {
       expect(result).to.eql(aqlResult.reduce((a, b) => a + b));
     });
   });
+  describe("cursor.nextBatch", () => {
+    beforeEach(async () => {
+      cursor = await db.query(aql`FOR i IN 1..10 RETURN i`, { batchSize: 5 });
+    });
+    it("fetches the next batch when empty", async () => {
+      expect((cursor as any)._result).to.eql([1, 2, 3, 4, 5]);
+      expect(cursor).to.have.property("_hasMore", true);
+      (cursor as any)._result.splice(0, 5);
+      expect(await cursor.nextBatch()).to.eql([6, 7, 8, 9, 10]);
+      expect(cursor).to.have.property("_hasMore", false);
+    });
+    it("returns all fetched values", async () => {
+      expect(await cursor.nextBatch()).to.eql([1, 2, 3, 4, 5]);
+      expect(await cursor.next()).to.equal(6);
+      expect(await cursor.nextBatch()).to.eql([7, 8, 9, 10]);
+    });
+  });
   describe("cursor.kill", () => {
     it("kills the cursor", async () => {
       const cursor = await db.query(aql`FOR i IN 1..5 RETURN i`, {