Export BasePlugin (#408)

BasePlugin is not described in the TypeScript types published with this module (i.e. types/index.d.ts) which means that it is difficult to write custom plugins in TypeScript or use VS Code with a jsconfig.json file with "checkJS": true.

This commit exposes BasePlugin on the Cloudant factory method so that it can be imported directly from @cloudant/cloudant.

This means that custom plugin authors do not need to require @cloudant/cloudant/plugins/base.

Author: wrumsby

CHANGES.md

@@ -1,3 +1,6 @@
+# UNRELEASED
+- [FIXED] Expose BasePlugin.
+
 # 4.2.2 (2019-10-23)
 - [FIXED] Stopped disabling the IAM auth plugin after failed IAM
   authentications. Subsequent requests will re-request authorization,

cloudant.js

@@ -20,6 +20,9 @@ var debug = require('debug')('cloudant:cloudant');
 var nanodebug = require('debug')('nano');
 
 const Client = require('./lib/client.js');
+const BasePlugin = require('./plugins/base.js');
+
+Cloudant.BasePlugin = BasePlugin; // expose base plugin
 
 // Parse an object (i.e. { account: "myaccount", password: "mypassword" }) and
 // return a URL.
@@ -81,7 +84,7 @@ function Cloudant(options, callback) {
   var nano = Nano(nanoOptions);
 
   nano.cc = cloudantClient; // expose Cloudant client
-  nano.basePlugin = require('./plugins/base.js'); // expose base plugin
+  nano.basePlugin = BasePlugin; // expose base plugin on nano
 
   // ===========================
   // Cloudant Database Functions

types/index.d.ts

@@ -211,6 +211,43 @@ declare namespace cloudant {
             params: nano.DocumentViewParams
         ): Request;
     }
+
+    // types for plugins
+
+    interface PluginConfig {}
+    interface PluginState {
+        maxAttempt: number;
+    }
+
+    type PluginCallbackFunction = (state: PluginState) => void;
+
+    interface PluginRequest {
+        method: 'get' | 'post' | 'options';
+        headers: {},
+        uri: string;
+    }
+
+    interface PluginPostRequest extends PluginRequest {
+        method: 'post';
+        body?: string | {};
+    }
+
+    interface PluginResponse {
+        request: PluginRequest;
+        headers: {};
+        statusCode: number;
+    }
+
+    export class BasePlugin {
+        public static pluginVersion: number; 
+        public static id: string
+        public disabled: boolean;
+        public _cfg: PluginConfig;
+        public constructor(client: nano.DocumentScope<{}>, config?: PluginConfig)
+        public onRequest(state: PluginState, request: PluginRequest, callback: PluginCallbackFunction): void
+        public onResponse(state: PluginState, response: PluginResponse, callback: PluginCallbackFunction): void
+        public onError(state: PluginState, error: Error, callback: PluginCallbackFunction): void
+    }
 }
 
 export = cloudant;

types/tests.ts

@@ -16,14 +16,68 @@
 import cloudant = require('@cloudant/cloudant');
 import nano = require('nano');
 
+const { BasePlugin } = cloudant;
+
+interface ICustomPluginConfig extends cloudant.PluginConfig {
+  customLoggingEnabled?: boolean;
+}
+
+class CustomPlugin extends BasePlugin {
+  public static id = 'custom';
+
+  constructor(client: nano.DocumentScope<{}>, configuration: ICustomPluginConfig) {
+    const cfg = Object.assign({
+      customLoggingEnabled: true
+    }, configuration);
+
+    super(client, cfg);
+  }
+
+  // tslint:disable-next-line:max-line-length
+  public onRequest(state: cloudant.PluginState, request: cloudant.PluginRequest, callback: cloudant.PluginCallbackFunction) {
+    const { customLoggingEnabled } = this._cfg as ICustomPluginConfig;
+
+    if (customLoggingEnabled) {
+      // tslint:disable-next-line:no-console
+      console.log('%s request made to %s with headers %o', request.method, request.uri, request.headers);
+    }
+
+    callback(state);
+  }
+
+  // tslint:disable-next-line:max-line-length
+  public onResponse(state: cloudant.PluginState, response: cloudant.PluginResponse, callback: cloudant.PluginCallbackFunction) {
+    const { customLoggingEnabled } = this._cfg as ICustomPluginConfig;
+
+    if (customLoggingEnabled) {
+      // tslint:disable-next-line
+      console.log('%d response for %s request made to %s', response.statusCode, response.request.method, response.request.uri);
+    }
+
+    callback(state);
+  }
+
+  // tslint:disable-next-line:max-line-length
+  public onError(state: cloudant.PluginState, error: Error, callback: cloudant.PluginCallbackFunction) {
+    const { customLoggingEnabled } = this._cfg as ICustomPluginConfig;
+
+    if (customLoggingEnabled) {
+      // tslint:disable-next-line:no-console
+      console.error(error);
+    }
+
+    callback(state);
+  }
+}
+
 /*
  * Instantiate with configuration object
  */
 const config: cloudant.Configuration = {
   account: 'my-cloudant-account',
   maxAttempt: 3,
   password: 'my-password',
-  plugins: 'retry'
+  plugins: [CustomPlugin, 'retry']
 };
 
 const cfgInstance = cloudant(config);