Print deprecation warning from Kuzzle

doc/7/core-classes/kuzzle/constructor/index.md

@@ -36,18 +36,19 @@ It can be one of the following available protocols:
 
 Kuzzle SDK instance options.
 
-| Property          | Type<br/>(default)               | Description                                                        |
-| ----------------- | -------------------------------- | ------------------------------------------------------------------ |
-| `autoQueue`       | <pre>boolean</pre><br/>(`false`) | Automatically queue all requests during offline mode               |
-| `autoReplay`      | <pre>boolean</pre><br/>(`false`) | Automatically replay queued requests on a `reconnected` event      |
-| `autoResubscribe` | <pre>boolean</pre><br/>(`true`)  | Automatically renew all subscriptions on a `reconnected` event     |
-| `eventTimeout`    | <pre>number</pre><br/>(`200`)    | Time (in ms) during which a similar event is ignored               |
-| `offlineMode`     | <pre>string</pre><br/>(`manual`) | Offline mode configuration. Can be `manual` or `auto`              |
-| `queueTTL`        | <pre>number</pre><br/>(`120000`) | Time a queued request is kept during offline mode, in milliseconds |
-| `queueMaxSize`    | <pre>number</pre><br/>(`500`)    | Number of maximum requests kept during offline mode                |
-| `replayInterval`  | <pre>number</pre><br/>(`10`)     | Delay between each replayed requests, in milliseconds              |
-| `tokenExpiredInterval` | <pre>number</pre><br/>(`1000`)    | Time (in ms) during which a TokenExpired event is ignored               |
-| `volatile`        | <pre>object</pre><br/>(`{}`)     | Common volatile data, will be sent to all future requests          |
+| Property               | Type<br/>(default)               | Description                                                              |
+| ---------------------- | -------------------------------- | ------------------------------------------------------------------------ |
+| `autoQueue`            | <pre>boolean</pre><br/>(`false`) | Automatically queue all requests during offline mode                     |
+| `autoReplay`           | <pre>boolean</pre><br/>(`false`) | Automatically replay queued requests on a `reconnected` event            |
+| `autoResubscribe`      | <pre>boolean</pre><br/>(`true`)  | Automatically renew all subscriptions on a `reconnected` event           |
+| `eventTimeout`         | <pre>number</pre><br/>(`200`)    | Time (in ms) during which a similar event is ignored                     |
+| `deprecationWarning`   | <pre>boolean</pre><br />(`true`) | Show deprecation warning in development (hidden either way in production)|
+| `offlineMode`          | <pre>string</pre><br/>(`manual`) | Offline mode configuration. Can be `manual` or `auto`                    |
+| `queueTTL`             | <pre>number</pre><br/>(`120000`) | Time a queued request is kept during offline mode, in milliseconds       |
+| `queueMaxSize`         | <pre>number</pre><br/>(`500`)    | Number of maximum requests kept during offline mode                      |
+| `replayInterval`       | <pre>number</pre><br/>(`10`)     | Delay between each replayed requests, in milliseconds                    |
+| `tokenExpiredInterval` | <pre>number</pre><br/>(`1000`)   | Time (in ms) during which a TokenExpired event is ignored                |
+| `volatile`             | <pre>object</pre><br/>(`{}`)     | Common volatile data, will be sent to all future requests                |
 
 ## Return
 

src/Kuzzle.ts

@@ -11,6 +11,7 @@ import { ServerController } from './controllers/Server';
 import { SecurityController } from './controllers/Security';
 import { MemoryStorageController } from './controllers/MemoryStorage';
 
+import { Deprecation } from './utils/Deprecation';
 import { uuidv4 } from './utils/uuidv4';
 import { proxify } from './utils/proxify';
 import { JSONObject } from './types';
@@ -61,6 +62,10 @@ export class Kuzzle extends KuzzleEventEmitter {
    * Common volatile data that will be sent to all future requests.
    */
   public volatile: JSONObject;
+  /**
+   * Handle deprecation warning in development mode (hidden in production)
+   */
+  public deprecationHandler: Deprecation;
 
   public auth: AuthController;
   public bulk: any;
@@ -164,6 +169,11 @@ export class Kuzzle extends KuzzleEventEmitter {
        * If set to `auto`, the `autoQueue` and `autoReplay` are also set to `true`
        */
       offlineMode?: 'auto';
+      /**
+       * Show deprecation warning in development mode (hidden either way in production)
+       * Default: `true`
+       */
+      deprecationWarning?: boolean;
     } = {}
   ) {
     super();
@@ -208,6 +218,10 @@ export class Kuzzle extends KuzzleEventEmitter {
       ? options.volatile
       : {};
 
+    this.deprecationHandler = new Deprecation(
+      typeof options.deprecationWarning === 'boolean' ? options.deprecationWarning : true
+    );
+
     // controllers
     this.useController(AuthController, 'auth');
     this.useController(BulkController, 'bulk');
@@ -514,7 +528,7 @@ export class Kuzzle extends KuzzleEventEmitter {
    * @param req
    * @param opts - Optional arguments
    */
-  query (req: RequestPayload = {}, opts: JSONObject = {}): Promise<ResponsePayload> {
+  async query (req: RequestPayload = {}, opts: JSONObject = {}): Promise<ResponsePayload> {
     if (typeof req !== 'object' || Array.isArray(req)) {
       throw new Error(`Kuzzle.query: Invalid request: ${JSON.stringify(req)}`);
     }
@@ -586,7 +600,9 @@ export class Kuzzle extends KuzzleEventEmitter {
 Discarded request: ${JSON.stringify(request)}`));
     }
 
-    return this.protocol.query(request, options);
+    const response = await this.protocol.query(request, options) as ResponsePayload;
+
+    return this.deprecationHandler.logDeprecation(response);
   }
 
   /**

src/controllers/Base.ts

@@ -1,9 +1,10 @@
+import { Kuzzle } from '../Kuzzle';
 import { JSONObject } from '../types';
 import { RequestPayload } from '../types/RequestPayload';
 
 export class BaseController {
   private _name: string;
-  private _kuzzle: any;
+  private _kuzzle: Kuzzle;
 
   /**
    * @param {Kuzzle} kuzzle - Kuzzle SDK object.

src/types/ResponsePayload.ts

@@ -31,10 +31,27 @@ export type ResponsePayload = {
    */
   _id?: string;
 
+  /**
+   * Array of deprecation warnings (hidden if NODE_ENV=production)
+   */
+  deprecations?: {
+
+    /**
+     * Deprecation description
+     */
+    message: string;
+
+    /**
+     * Deprecated since this version
+     */
+    version: string;
+  }[];
+
   /**
    * API error
    */
   error?: {
+
     /**
      * Error human readable identifier
      */

src/utils/Deprecation.ts

@@ -0,0 +1,31 @@
+import { ResponsePayload } from 'src/types/ResponsePayload';
+
+export class Deprecation {
+
+  private _deprecationWarning: boolean;
+
+  constructor (deprecationWarning: boolean) {
+    this._deprecationWarning = deprecationWarning;
+  }
+
+  /**
+   * Warn the developer that he is using a deprecated action (disabled if NODE_ENV=production)
+   * 
+   * @param response Result of a query to the API
+   * 
+   * @returns Same as response param, just like a middleware
+   */
+  logDeprecation (response: ResponsePayload) {
+    if ( process.env.NODE_ENV !== 'production'
+      && this._deprecationWarning
+      && response.deprecations
+      && response.deprecations.length
+    ) {
+      for (const deprecation of response.deprecations) {
+        // eslint-disable-next-line no-console
+        console.warn(deprecation.message);    
+      }
+    }
+    return response;
+  }
+}

test/kuzzle/query.test.js

@@ -242,5 +242,14 @@ describe('Kuzzle query management', () => {
 
       should(request).be.eql({ controller: 'server', action: 'now' });
     });
+
+    it('should call logDeprecation with the response', async () => {
+      kuzzle.deprecationHandler.logDeprecation = sinon.stub().returns(response);
+      await kuzzle.query(query);
+
+      should(kuzzle.deprecationHandler.logDeprecation)
+        .be.calledOnce()
+        .be.calledWith(response);
+    });
   });
 });

test/utils/Deprecation.test.js

@@ -0,0 +1,81 @@
+const should = require('should');
+const sinon = require('sinon');
+const { Deprecation } = require('../../src/utils/Deprecation');
+
+describe('Deprecation', () => {
+  let deprecationHandler, response;
+  const sandbox = sinon.createSandbox();
+
+  beforeEach(()=>{
+    sandbox.stub(console, 'warn');
+    deprecationHandler = new Deprecation(true);
+    process.env.NODE_ENV = 'development';
+
+    response = {
+      action: 'test',
+      collection: 'collection',
+      controller: 'controller',
+      deprecations: [
+        {
+          message: 'Use this route instead: http://kuzzle:7512/test/succeed',
+          version: '6.6.6'
+        }
+      ],
+      error: null,
+      index: null,
+      node: 'nodeJS',
+      requestId: 'idididididid',
+      result: true,
+      status: 200,
+      volatile: null
+    };
+  });
+
+  afterEach(()=>{
+    sandbox.restore();
+  });
+
+  it('should warn the developer that he is using a deprecated action', () => {
+    deprecationHandler.logDeprecation(response);
+
+    should(console.warn)
+      .be.calledOnce()
+      .be.calledWith(response.deprecations[0].message);
+  });
+
+  it('should return the same response as it has received', () => {
+    should(deprecationHandler.logDeprecation(response)).match(response);
+  });
+
+  it('should handle multiple deprecations', () => {
+    response.deprecations.push(response);
+
+    deprecationHandler.logDeprecation(response);
+
+    should(console.warn).be.calledTwice();
+  });
+
+  it('should not warn the developer if he refused to', () => {
+    deprecationHandler = new Deprecation(false);
+
+    deprecationHandler.logDeprecation(response);
+
+    should(console.warn).not.have.been.called();
+  });
+
+  it('should not warn the developer if there is no deprecation', () => {
+    response.deprecations = [];
+
+    deprecationHandler.logDeprecation(response);
+
+    should(console.warn).not.have.been.called();
+  });
+
+  it('should not warn the developer in production', () => {
+    process.env.NODE_ENV = 'production';
+
+    deprecationHandler.logDeprecation(response);
+
+    should(console.warn).not.have.been.called();
+  });
+});