Added Database#close

Author: pluma

CHANGELOG.md

@@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Added `database.close` method
+
 - Added `opts` parameter to `EdgeCollection#save`
 
 ## [6.3.0] - 2018-06-20

docs/Drivers/JS/Reference/Database/README.md

@@ -10,11 +10,11 @@ If _config_ is a string, it will be interpreted as _config.url_.
 
 **Arguments**
 
-* **config**: `Object` (optional)
+- **config**: `Object` (optional)
 
   An object with the following properties:
 
-  * **url**: `string | Array<string>` (Default: `http://localhost:8529`)
+  - **url**: `string | Array<string>` (Default: `http://localhost:8529`)
 
     Base URL of the ArangoDB server or list of server URLs.
 
@@ -36,14 +36,14 @@ If _config_ is a string, it will be interpreted as _config.url_.
     }
     ```
 
-  * **isAbsolute**: `boolean` (Default: `false`)
+  - **isAbsolute**: `boolean` (Default: `false`)
 
     If this option is explicitly set to `true`, the _url_ will be treated as the
     absolute database path. This is an escape hatch to allow using arangojs with
     database APIs exposed with a reverse proxy and makes it impossible to switch
     databases with _useDatabase_ or using _acquireHostList_.
 
-  * **arangoVersion**: `number` (Default: `30000`)
+  - **arangoVersion**: `number` (Default: `30000`)
 
     Value of the `x-arango-version` header. This should match the lowest
     version of ArangoDB you expect to be using. The format is defined as
@@ -57,14 +57,14 @@ If _config_ is a string, it will be interpreted as _config.url_.
     not available on every major version of ArangoDB as indicated in their
     descriptions below (e.g. _collection.first_, _collection.bulkUpdate_).
 
-  * **headers**: `Object` (optional)
+  - **headers**: `Object` (optional)
 
     An object with additional headers to send with every request.
 
     Header names should always be lowercase. If an `"authorization"` header is
     provided, it will be overridden when using _useBasicAuth_ or _useBearerAuth_.
 
-  * **agent**: `Agent` (optional)
+  - **agent**: `Agent` (optional)
 
     An http Agent instance to use for connections.
 
@@ -74,7 +74,7 @@ If _config_ is a string, it will be interpreted as _config.url_.
 
     This option has no effect when using the browser version of arangojs.
 
-  * **agentOptions**: `Object` (Default: see below)
+  - **agentOptions**: `Object` (Default: see below)
 
     An object with options for the agent. This will be ignored if _agent_ is
     also provided.
@@ -91,15 +91,41 @@ If _config_ is a string, it will be interpreted as _config.url_.
     additional options to the underlying calls of the
     [`xhr`](https://www.npmjs.com/package/xhr) module.
 
-  * **loadBalancingStrategy**: `string` (Default: `"NONE"`)
+  - **loadBalancingStrategy**: `string` (Default: `"NONE"`)
 
-    Determines the behaviour when multiple URLs are provided:
+    Determines the behavior when multiple URLs are provided:
 
-    * `NONE`: No load balancing. All requests will be handled by the first
+    - `NONE`: No load balancing. All requests will be handled by the first
       URL in the list until a network error is encountered. On network error,
       arangojs will advance to using the next URL in the list.
 
-    * `ONE_RANDOM`: Randomly picks one URL from the list initially, then
+    - `ONE_RANDOM`: Randomly picks one URL from the list initially, then
       behaves like `NONE`.
 
-    * `ROUND_ROBIN`: Every sequential request uses the next URL in the list.
+    - `ROUND_ROBIN`: Every sequential request uses the next URL in the list.
+
+## database.close
+
+`database.close(): void`
+
+Closes all active connections of the database instance.
+Can be used to clean up idling connections during longer periods of inactivity.
+
+**Note**: This method currently has no effect in the browser version of arangojs.
+
+**Examples**
+
+```js
+const db = new Database();
+const sessions = db.collection("sessions");
+// Clean up expired sessions once per hour
+setInterval(async () => {
+  await db.query(aql`
+    FOR session IN ${sessions}
+    FILTER session.expires < DATE_NOW()
+    REMOVE session IN ${sessions}
+  `);
+  // Make sure to close the connections because they're no longer used
+  db.close();
+}, 1000 * 60 * 60);
+```

src/connection.ts

@@ -1,14 +1,13 @@
+import { stringify as querystringify } from "querystring";
 import { ArangoError, HttpError } from "./error";
+import { byteLength } from "./util/bytelength";
 import {
   ArangojsResponse,
-  RequestFunction,
   createRequest,
-  isBrowser
+  isBrowser,
+  RequestFunction
 } from "./util/request";
 
-import { byteLength } from "./util/bytelength";
-import { stringify as querystringify } from "querystring";
-
 const LinkedList = require("linkedlist/lib/linkedlist") as typeof Array;
 
 const MIME_JSON = /\/(json|javascript)(\W|$)/;
@@ -58,14 +57,14 @@ export type Config =
       isAbsolute: boolean;
       arangoVersion: number;
       loadBalancingStrategy: LoadBalancingStrategy;
-      agent: Function;
+      agent: any;
       agentOptions: { [key: string]: any };
       headers: { [key: string]: string };
     }>;
 
 export class Connection {
   private _activeTasks: number = 0;
-  private _agent?: Function;
+  private _agent?: any;
   private _agentOptions: { [key: string]: any };
   private _arangoVersion: number = 30000;
   private _databaseName: string | false = "_system";
@@ -105,7 +104,9 @@ export class Connection {
     this._useFailOver = this._loadBalancingStrategy !== "ROUND_ROBIN";
 
     const urls = config.url
-      ? Array.isArray(config.url) ? config.url : [config.url]
+      ? Array.isArray(config.url)
+        ? config.url
+        : [config.url]
       : ["http://localhost:8529"];
     this.addToHostList(urls);
 
@@ -221,6 +222,12 @@ export class Connection {
     this._headers[key] = value;
   }
 
+  close() {
+    for (const host of this._hosts) {
+      if (host.close) host.close();
+    }
+  }
+
   request<T = ArangojsResponse>(
     {
       host,

src/database.ts

@@ -70,6 +70,10 @@ export class Database {
     this._connection.addToHostList(urls);
   }
 
+  close () {
+    this._connection.close();
+  }
+
   // Database manipulation
 
   useDatabase(databaseName: string) {

src/test/00-basics.ts

@@ -1,10 +1,8 @@
+import { expect } from "chai";
 import * as http from "http";
 import * as https from "https";
-
 import arangojs, { Database } from "../arangojs";
-
 import { Connection } from "../connection";
-import { expect } from "chai";
 
 describe("Creating a Database", () => {
   describe("using the factory", () => {
@@ -132,22 +130,22 @@ describe("Configuring the driver", () => {
       (https as any).request = _httpsRequest;
     });
     it("passes the agent to the request function", () => {
-      let agent = function() {};
+      let agent = Symbol("agent");
       let conn;
       conn = new Connection({ agent }); // default: http
       conn.request({ headers: {} }, () => {});
       expect(options).to.have.property("agent", agent);
-      agent = function() {};
+      agent = Symbol("agent");
       conn = new Connection({ agent, url: "https://localhost:8529" });
       conn.request({ headers: {} }, () => {});
       expect(options).to.have.property("agent", agent);
-      agent = function() {};
+      agent = Symbol("agent");
       conn = new Connection({ agent, url: "http://localhost:8529" });
       conn.request({ headers: {} }, () => {});
       expect(options).to.have.property("agent", agent);
     });
     it("uses the request function for the protocol", () => {
-      const agent = function() {};
+      const agent = Symbol("agent");
       let conn;
       conn = new Connection({ agent }); // default: http
       conn.request({ headers: {} }, () => {});
@@ -159,5 +157,17 @@ describe("Configuring the driver", () => {
       conn.request({ headers: {} }, () => {});
       expect(protocol).to.equal("http");
     });
+    it("calls Agent#destroy when the connection is closed", () => {
+      const agent = {
+        _destroyed: false,
+        destroy() {
+          this._destroyed = true;
+        }
+      };
+      const conn = new Connection({ agent });
+      expect(agent._destroyed).to.equal(false);
+      conn.close();
+      expect(agent._destroyed).to.equal(true);
+    });
   });
 });

src/util/request.node.ts

@@ -5,7 +5,7 @@ import {
   request as httpRequest
 } from "http";
 import { Agent as HttpsAgent, request as httpsRequest } from "https";
-import { Url, parse as parseUrl } from "url";
+import { parse as parseUrl, Url } from "url";
 import { joinPath } from "./joinPath";
 import { Errback } from "./types";
 
@@ -18,18 +18,18 @@ export type ArangojsError = Error & {
   request: ClientRequest;
 };
 
-export type RequestOptions = {
+export interface RequestOptions {
   method: string;
   url: Url;
   headers: { [key: string]: string };
   body: any;
   expectBinary: boolean;
-};
+}
 
-export type RequestFunction = (
-  opts: RequestOptions,
-  cb: Errback<ArangojsResponse>
-) => void;
+export interface RequestFunction {
+  (opts: RequestOptions, cb: Errback<ArangojsResponse>): void;
+  close?: () => void;
+}
 
 export const isBrowser = false;
 
@@ -44,54 +44,61 @@ export function createRequest(
     if (isTls) agent = new HttpsAgent(agentOptions);
     else agent = new HttpAgent(agentOptions);
   }
-  return function request(
-    { method, url, headers, body }: RequestOptions,
-    callback: Errback<ArangojsResponse>
-  ) {
-    let path = baseUrlParts.pathname
-      ? url.pathname
-        ? joinPath(baseUrlParts.pathname, url.pathname)
-        : baseUrlParts.pathname
-      : url.pathname;
-    const search = url.search
-      ? baseUrlParts.search
-        ? `${baseUrlParts.search}&${url.search.slice(1)}`
-        : url.search
-      : baseUrlParts.search;
-    if (search) path += search;
-    const options: any = { path, method, headers, agent };
-    options.hostname = baseUrlParts.hostname;
-    options.port = baseUrlParts.port;
-    options.auth = baseUrlParts.auth;
-    let called = false;
-    try {
-      const req = (isTls ? httpsRequest : httpRequest)(
-        options,
-        (res: IncomingMessage) => {
-          const data: Buffer[] = [];
-          res.on("data", chunk => data.push(chunk as Buffer));
-          res.on("end", () => {
-            const result = res as ArangojsResponse;
-            result.body = Buffer.concat(data);
-            if (called) return;
-            called = true;
-            callback(null, result);
-          });
-        }
-      );
-      req.on("error", err => {
-        const error = err as ArangojsError;
-        error.request = req;
+  return Object.assign(
+    function request(
+      { method, url, headers, body }: RequestOptions,
+      callback: Errback<ArangojsResponse>
+    ) {
+      let path = baseUrlParts.pathname
+        ? url.pathname
+          ? joinPath(baseUrlParts.pathname, url.pathname)
+          : baseUrlParts.pathname
+        : url.pathname;
+      const search = url.search
+        ? baseUrlParts.search
+          ? `${baseUrlParts.search}&${url.search.slice(1)}`
+          : url.search
+        : baseUrlParts.search;
+      if (search) path += search;
+      const options: any = { path, method, headers, agent };
+      options.hostname = baseUrlParts.hostname;
+      options.port = baseUrlParts.port;
+      options.auth = baseUrlParts.auth;
+      let called = false;
+      try {
+        const req = (isTls ? httpsRequest : httpRequest)(
+          options,
+          (res: IncomingMessage) => {
+            const data: Buffer[] = [];
+            res.on("data", chunk => data.push(chunk as Buffer));
+            res.on("end", () => {
+              const result = res as ArangojsResponse;
+              result.body = Buffer.concat(data);
+              if (called) return;
+              called = true;
+              callback(null, result);
+            });
+          }
+        );
+        req.on("error", err => {
+          const error = err as ArangojsError;
+          error.request = req;
+          if (called) return;
+          called = true;
+          callback(err);
+        });
+        if (body) req.write(body);
+        req.end();
+      } catch (e) {
         if (called) return;
         called = true;
-        callback(err);
-      });
-      if (body) req.write(body);
-      req.end();
-    } catch (e) {
-      if (called) return;
-      called = true;
-      callback(e);
+        callback(e);
+      }
+    },
+    {
+      close() {
+        agent.destroy();
+      }
     }
-  };
+  );
 }