Add cursor.kill (#629)

* Add cursor.kill

* Add test case

* fix query -> cursor

* typo

Author: pluma

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+## Added
+
+- Added `cursor.kill` method
+
+  Cursors that have not yet been fully depleted can now be killed using the
+  `cursor.kill` method. Note that this method has no effect if the cursor
+  is already depleted.
+
 ## [6.11.1] - 2019-08-30
 
 ### Fixed

docs/Drivers/JS/Reference/Cursor.md

@@ -7,7 +7,7 @@ _Cursor_ instances are incrementally depleted as they are read from.
 
 ```js
 const db = new Database();
-const cursor = await db.query('FOR x IN 1..5 RETURN x');
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
 // query result list: [1, 2, 3, 4, 5]
 const value = await cursor.next();
 assert.equal(value, 1);
@@ -31,8 +31,8 @@ remaining result list.
 **Examples**
 
 ```js
-const cursor = await db.query('FOR x IN 1..5 RETURN x');
-const result = await cursor.all()
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
+const result = await cursor.all();
 // result is an array containing the entire query result
 assert.deepEqual(result, [1, 2, 3, 4, 5]);
 assert.equal(cursor.hasNext(), false);
@@ -86,22 +86,22 @@ Equivalent to _Array.prototype.forEach_ (except async).
 
 **Arguments**
 
-* **fn**: `Function`
+- **fn**: `Function`
 
   A function that will be invoked for each value in the cursor's remaining
   result list until it explicitly returns `false` or the cursor is exhausted.
 
   The function receives the following arguments:
 
-  * **value**: `any`
+  - **value**: `any`
 
     The value in the cursor's remaining result list.
 
-  * **index**: `number`
+  - **index**: `number`
 
     The index of the value in the cursor's remaining result list.
 
-  * **cursor**: `Cursor`
+  - **cursor**: `Cursor`
 
     The cursor itself.
 
@@ -115,11 +115,11 @@ function doStuff(value) {
   return VALUE;
 }
 
-const cursor = await db.query('FOR x IN ["a", "b", "c"] RETURN x')
+const cursor = await db.query(aql`FOR x IN ["a", "b", "c"] RETURN x`);
 const last = await cursor.each(doStuff);
-assert.deepEqual(results, ['A', 'B', 'C']);
+assert.deepEqual(results, ["A", "B", "C"]);
 assert.equal(cursor.hasNext(), false);
-assert.equal(last, 'C');
+assert.equal(last, "C");
 ```
 
 ## cursor.every
@@ -137,30 +137,30 @@ Equivalent to _Array.prototype.every_ (except async).
 
 **Arguments**
 
-* **fn**: `Function`
+- **fn**: `Function`
 
   A function that will be invoked for each value in the cursor's remaining
   result list until it returns a value that evaluates to `false` or the cursor
   is exhausted.
 
   The function receives the following arguments:
 
-  * **value**: `any`
+  - **value**: `any`
 
     The value in the cursor's remaining result list.
 
-  * **index**: `number`
+  - **index**: `number`
 
     The index of the value in the cursor's remaining result list.
 
-  * **cursor**: `Cursor`
+  - **cursor**: `Cursor`
 
     The cursor itself.
 
 ```js
 const even = value => value % 2 === 0;
 
-const cursor = await db.query('FOR x IN 2..5 RETURN x');
+const cursor = await db.query(aql`FOR x IN 2..5 RETURN x`);
 const result = await cursor.every(even);
 assert.equal(result, false); // 3 is not even
 assert.equal(cursor.hasNext(), true);
@@ -187,7 +187,7 @@ Equivalent to _Array.prototype.some_ (except async).
 ```js
 const even = value => value % 2 === 0;
 
-const cursor = await db.query('FOR x IN 1..5 RETURN x');
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
 const result = await cursor.some(even);
 assert.equal(result, true); // 2 is even
 assert.equal(cursor.hasNext(), true);
@@ -198,7 +198,7 @@ assert.equal(value, 3); // next value after 2
 
 ## cursor.map
 
-`cursor.map(fn): Array<any>`
+`async cursor.map(fn): Array<any>`
 
 Advances the cursor by applying the function _fn_ to each value in the cursor's
 remaining result list until the cursor is exhausted.
@@ -212,30 +212,30 @@ to do this for very large query result sets.
 
 **Arguments**
 
-* **fn**: `Function`
+- **fn**: `Function`
 
   A function that will be invoked for each value in the cursor's remaining
   result list until the cursor is exhausted.
 
   The function receives the following arguments:
 
-  * **value**: `any`
+  - **value**: `any`
 
     The value in the cursor's remaining result list.
 
-  * **index**: `number`
+  - **index**: `number`
 
     The index of the value in the cursor's remaining result list.
 
-  * **cursor**: `Cursor`
+  - **cursor**: `Cursor`
 
     The cursor itself.
 
 **Examples**
 
 ```js
 const square = value => value * value;
-const cursor = await db.query('FOR x IN 1..5 RETURN x');
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
 const result = await cursor.map(square);
 assert.equal(result.length, 5);
 assert.deepEqual(result, [1, 4, 9, 16, 25]);
@@ -244,7 +244,7 @@ assert.equal(cursor.hasNext(), false);
 
 ## cursor.reduce
 
-`cursor.reduce(fn, [accu]): any`
+`async cursor.reduce(fn, [accu]): any`
 
 Exhausts the cursor by reducing the values in the cursor's remaining result list
 with the given function _fn_. If _accu_ is not provided, the first value in the
@@ -255,28 +255,28 @@ Equivalent to _Array.prototype.reduce_ (except async).
 
 **Arguments**
 
-* **fn**: `Function`
+- **fn**: `Function`
 
   A function that will be invoked for each value in the cursor's remaining
   result list until the cursor is exhausted.
 
   The function receives the following arguments:
 
-  * **accu**: `any`
+  - **accu**: `any`
 
     The return value of the previous call to _fn_. If this is the first call,
     _accu_ will be set to the _accu_ value passed to _reduce_ or the first value
     in the cursor's remaining result list.
 
-  * **value**: `any`
+  - **value**: `any`
 
     The value in the cursor's remaining result list.
 
-  * **index**: `number`
+  - **index**: `number`
 
     The index of the value in the cursor's remaining result list.
 
-  * **cursor**: `Cursor`
+  - **cursor**: `Cursor`
 
     The cursor itself.
 
@@ -286,8 +286,8 @@ Equivalent to _Array.prototype.reduce_ (except async).
 const add = (a, b) => a + b;
 const baseline = 1000;
 
-const cursor = await db.query('FOR x IN 1..5 RETURN x');
-const result = await cursor.reduce(add, baseline)
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
+const result = await cursor.reduce(add, baseline);
 assert.equal(result, baseline + 1 + 2 + 3 + 4 + 5);
 assert.equal(cursor.hasNext(), false);
 
@@ -297,3 +297,21 @@ const result = await cursor.reduce(add);
 assert.equal(result, 1 + 2 + 3 + 4 + 5);
 assert.equal(cursor.hasNext(), false);
 ```
+
+## cursor.kill
+
+`async cursor.kill(): void`
+
+Kills the cursor and frees up associated database resources.
+
+This method has no effect if all result batches have already been fetched.
+
+**Examples**
+
+```js
+const cursor = await db.query(aql`FOR x IN 1..5 RETURN x`);
+await cursor.kill(); // has no effect
+
+const cursor2 = await db.query(aql`FOR x IN 1..5 RETURN x`, { batchSize: 2 });
+await cursor2.kill(); // this kills the cursor
+```

src/cursor.ts

@@ -7,7 +7,7 @@ export class ArrayCursor {
   private _connection: Connection;
   private _result: any;
   private _hasMore: boolean;
-  private _id: string;
+  private _id: string | undefined;
   private _host?: number;
   private _allowDirtyRead?: boolean;
 
@@ -20,8 +20,8 @@ export class ArrayCursor {
     this.extra = body.extra;
     this._connection = connection;
     this._result = body.result;
-    this._hasMore = Boolean(body.hasMore);
     this._id = body.id;
+    this._hasMore = Boolean(body.id && body.hasMore);
     this._host = host;
     this.count = body.count;
     this._allowDirtyRead = allowDirtyRead;
@@ -152,4 +152,18 @@ export class ArrayCursor {
     }
     return accu;
   }
+
+  async kill(): Promise<void> {
+    if (!this._hasMore) return undefined;
+    return this._connection.request(
+      {
+        method: "DELETE",
+        path: `/_api/cursor/${this._id}`
+      },
+      () => {
+        this._hasMore = false;
+        return undefined;
+      }
+    );
+  }
 }

src/test/08-cursors.ts

@@ -193,4 +193,26 @@ describe("Cursor API", () => {
       expect(result).to.eql(aqlResult.reduce((a, b) => a + b));
     });
   });
+  describe("cursor.kill", () => {
+    it("kills the cursor", async () => {
+      const cursor = await db.query(aql`FOR i IN 1..5 RETURN i`, {
+        batchSize: 2
+      });
+      const { _connection: connection, _host: host, _id: id } = cursor as any;
+      expect(cursor).to.have.property("_hasMore", true);
+      await cursor.kill();
+      expect(cursor).to.have.property("_hasMore", false);
+      try {
+        await connection.request({
+          method: "PUT",
+          path: `/_api/cursor/${id}`,
+          host: host
+        });
+      } catch (e) {
+        expect(e).to.have.property("errorNum", 1600);
+        return;
+      }
+      expect.fail("should not be able to fetch additional result set");
+    });
+  });
 });