Add BatchController for performant document writing (#679)

This PR introduce a new advanced class to process documents per batch without modifying existing code.

The `BatchController` extends the `DocumentController` except that the following methods are replaced by their batch equivalent:
  - create => mCreate
  - replace => mReplace
  - createOrReplace => mCreateOrReplace
  - update => mUpdate
  - get => mGet
  - exists => mGet
  - delete => mDelete 

You only need to replace the `sdk.document.XXX` call by `batchController.XXX`:

```
await sdk.document.create('test', 'test', { name: 'aschen' });

const batchController = new BatchController(sdk);

await batchController.create('test', 'test', { name: 'aschen' });
```

The actual drawback is that the error management won't be the same because the `BatchController` with throw generic errors if something went wrong and not Kuzzle specifics errors with appropriate error codes.

Author: Adrien Maret

doc/7/core-classes/batch-controller/constructor/index.md

@@ -0,0 +1,34 @@
+---
+code: true
+type: page
+title: constructor
+description: BatchController constructor method
+---
+
+# constructor
+
+<SinceBadge version="auto-version" />
+
+Instantiate a new BatchController.
+
+Each instance will start a timer to periodically send batch requests.
+
+## Arguments
+
+```js
+const batch = new BatchController(sdk, options);
+```
+
+<br/>
+
+| Argument  | Type              | Description        |
+| --------- | ----------------- | ------------------ |
+| `sdk`     | <pre>Kuzzle</pre> | SDK instance       |
+| `options` | <pre>object</pre> | Additional options |
+
+## options
+
+  * `interval`:  Timer interval in ms (10). Actions will be executed every {interval} ms
+  * `maxWriteBufferSize`: Max write buffer size (200). (Should match config "limits.documentsWriteCount")
+  * `maxReadBufferSize`: Max read buffer size (10000). (Should match config "limits.documentsReadCount")
+

doc/7/core-classes/batch-controller/dispose/index.md

@@ -0,0 +1,20 @@
+---
+code: true
+type: page
+title: dispose
+description: BatchController dispose method
+---
+
+# dispose
+
+<SinceBadge version="auto-version" />
+
+Dispose the instance.
+
+This method has to be called to destroy the underlaying timer sending batch requests.
+
+## Arguments
+
+```js
+dispose (): Promise<void>
+```

doc/7/core-classes/batch-controller/index.md

@@ -0,0 +1,6 @@
+---
+code: true
+type: branch
+title: BatchController
+description: BatchController class documentation
+---

doc/7/core-classes/batch-controller/introduction/index.md

@@ -0,0 +1,63 @@
+---
+code: false
+type: page
+title: Introduction
+description: BatchController class
+order: 0
+---
+
+# BatchController
+
+<SinceBadge version="auto-version" />
+
+This class is an overload of the document controller and can be switched "as-is" in your code.
+
+It allows to group API actions into batches to significantly increase performances.
+
+The following methods will be executed by batch using
+m* actions:
+ - create => mCreate
+ - replace => mReplace
+ - createOrReplace => mCreateOrReplace
+ - update => mUpdate
+ - get => mGet
+ - exists => mGet
+ - delete => mDelete
+
+::: warning
+Standard API errors will not be available.
+Except for the `services.storage.not_found` error.
+:::
+
+By default, the BatchController sends a batch of documents every 10ms. This can be configured when instantiating the BatchController through the `options.interval` constructor parameter.
+
+::: info
+Depending on your workload, you may want to increase the timer interval to execute bigger batches.
+A bigger interval will also mean more time between two batches and potentially degraded performances.
+The default value of 10ms offers a good balance between batch size and maximum delay between two batches and should be suitable for most situations.
+:::
+
+**Example:**
+
+```js
+import { BatchController, Kuzzle, Http } from 'kuzzle';
+
+const sdk = new Kuzzle(new Http('localhost'));
+
+const batch = new BatchController(sdk);
+
+// Same as sdk.document.exists but executed in a batch
+const exists = await batch.exists('city', 'galle', 'dana');
+
+if (exists) {
+  // Same as sdk.document.update but executed in a batch
+  await batch.update('city', 'galle', 'dana', { power: 'off' });
+}
+else {
+  // Same as sdk.document.create but executed in a batch
+  await batch.create('city', 'galle', { power: 'off' }, 'dana');
+}
+
+// Original sdk.document.search method
+const results = await batch.search('city', 'galle', {});
+```

doc/7/essentials/batch-processing/index.md

@@ -0,0 +1,70 @@
+---
+code: false
+type: page
+title: Batch Processing
+description: Process batches of data with the SDK
+order: 600
+---
+
+# Batch Processing
+
+Most of the methods of the Document controller have a batch alternative:
+ - create => mCreate
+ - replace => mReplace
+ - createOrReplace => mCreateOrReplace
+ - update => mUpdate
+ - get => mGet
+ - exists => mGet
+ - delete => mDelete
+
+Those methods can be used to process batches of documents at once and increase performances.
+
+## BatchController
+
+Although the m* methods offer very good performances when handling documents, they will need a refactor of the code and architecture.
+
+Instead the [BatchController](/sdk/js/7/core-classes/batch-controller/introduction) provides a consistent way to deal with documents per batch.
+
+It overloads the original DocumentController but methods will be executed in batch at a fixed interval.
+
+The BatchController is usable without modifying the original code, just by replacing the original calls to `document.*` to `batch.*`
+
+**Example:**
+
+```js
+import { BatchController, Kuzzle, Http } from 'kuzzle';
+
+const sdk = new Kuzzle(new Http('localhost'));
+
+const batch = new BatchController(sdk);
+
+// Same as sdk.document.exists but executed in a batch
+const exists = await batch.exists('city', 'galle', 'dana');
+
+if (exists) {
+  // Same as sdk.document.update but executed in a batch
+  await batch.update('city', 'galle', 'dana', { power: 'off' });
+}
+else {
+  // Same as sdk.document.create but executed in a batch
+  await batch.create('city', 'galle', { power: 'off' }, 'dana');
+}
+
+// Original sdk.document.search method
+const results = await batch.search('city', 'galle', {});
+```
+
+::: warning
+Standard API errors will not be available.
+Except for the `services.storage.not_found` error.
+:::
+
+By default, the BatchController send a batch of document every 10ms. This can be configured when instantiating the BatchController through the `options.interval` [constructor](/sdk/js/7/core-classes/batch-controller/constructor) parameter.
+
+::: info
+Depending on your load, you may want to increase the timer interval to execute bigger batch.
+A bigger interval will also mean more time between two batch and potentialy degraded performances.
+The default value of 10ms offer a good balance between batch size and maximum delay between two batch and should be suitable for most situations.
+:::
+
+

index.ts

@@ -21,6 +21,7 @@ export * from './src/core/searchResult/Specifications';
 export * from './src/core/searchResult/User';
 export * from './src/core/Observer';
 export * from './src/core/RealtimeDocument';
+export * from './src/core/batchWriter/BatchController';
 
 export * from './src/types';
 

src/KuzzleError.ts

@@ -2,6 +2,7 @@
 
 import { hilightUserCode } from './utils/stackTrace';
 import { RequestPayload } from './types/RequestPayload';
+import { JSONObject } from './types';
 
 /**
  * Standard Kuzzle error.
@@ -81,7 +82,7 @@ export class KuzzleError extends Error {
    * The SDK stack is needed alongside the protocol used.
    * Those information will allow to construct a enhanced stacktrace:
    *
-   * BadRequestError: lol
+   * BadRequestError: Trololol
           at new BadRequestError (/home/aschen/projets/kuzzleio/kuzzle/lib/kerror/errors/badRequestError.ts:26:5)
     >    at BaseController.handler [as sayHello] (/home/aschen/projets/kuzzleio/kuzzle/test.js:9:15)
           at doAction (/home/aschen/projets/kuzzleio/kuzzle/lib/api/funnel.js:759:47)
@@ -96,13 +97,18 @@ export class KuzzleError extends Error {
     >    at /home/aschen/projets/kuzzleio/sdk-javascript/test.js:8:18
           at processTicksAndRejections (internal/process/task_queues.js:97:5)
    */
-  constructor (apiError, sdkStack: string, protocol: string, request?: RequestPayload) {
+  constructor (
+    apiError: { message: string, status?: number, id?: string, code?: number, errors?: JSONObject[], count?: number, stack?: string },
+    sdkStack?: string,
+    protocol?: string,
+    request?: RequestPayload,
+  ) {
     super(apiError.message);
-    this.status = apiError.status;
 
+    this.status = apiError.status;
     this.id = apiError.id;
     this.code = apiError.code;
-  
+
     if (request) {
       this.controller = request.controller;
       this.collection = request.collection;
@@ -135,10 +141,12 @@ export class KuzzleError extends Error {
     }
 
     // Append the SDK stacktrace
-    this.stack += sdkStack
-      .split('\n')
-      .map(hilightUserCode)
-      .slice(1)
-      .join('\n');
+    if (sdkStack) {
+      this.stack += sdkStack
+        .split('\n')
+        .map(hilightUserCode)
+        .slice(1)
+        .join('\n');
+    }
   }
 }

src/controllers/Document.ts

@@ -66,11 +66,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param content Document content
    * @param _id Optional document ID
-   * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The created document
    */
@@ -104,11 +103,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param id Document ID
    * @param content Document content
-   * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The created or replaced document
    */
@@ -141,10 +139,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param _id Document ID
    * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The document ID
    */
@@ -153,7 +151,7 @@ export class DocumentController extends BaseController {
     collection: string,
     _id: string,
     options: ArgsDocumentControllerDelete = {}
-  ): Promise<number> {
+  ): Promise<string> {
     const request = {
       index,
       collection,
@@ -249,10 +247,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param _id Document ID
    * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns True if the document exists
    */
@@ -282,10 +280,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param _id Document ID
    * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The document
    */
@@ -577,11 +575,10 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param id Document ID
    * @param content Document content
-   * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The replaced document
    */
@@ -674,13 +671,12 @@ export class DocumentController extends BaseController {
    * @param collection Collection name
    * @param id Document ID
    * @param content Document content
-   * @param options Additional options
-   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
-   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
-   *    - `silent` If true, then Kuzzle will not generate notifications
-   *    - `retryOnConflict` Number of times the database layer should retry in case of version conflict
-   *    - `source` If true, returns the updated document inside the response
-   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   * @param options.queuable If true, queues the request during downtime, until connected to Kuzzle again
+   * @param options.refresh If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   * @param options.silent If true, then Kuzzle will not generate notifications
+   * @param options.retryOnConflict Number of times the database layer should retry in case of version conflict
+   * @param options.source If true, returns the updated document inside the response
+   * @param options.timeout Request Timeout in ms, after the delay if not resolved the promise will be rejected
    *
    * @returns The replaced document
    */

src/core/InstrumentablePromise.ts

@@ -0,0 +1,12 @@
+export class InstrumentablePromise {
+  public promise: Promise<any>;
+  public resolve: (...any) => any;
+  public reject: (...any) => any;
+
+  constructor () {
+    this.promise = new Promise((resolve, reject) => {
+      this.resolve = resolve;
+      this.reject = reject;
+    });
+  }
+}