Merge pull request #687 from kuzzleio/7.9.0-proposal

# [7.9.0](https://github.com/kuzzleio/sdk-javascript/releases/tag/7.9.0) (2022-03-16)


#### New features

- [ [#679](#679) ] Add BatchController for performant document writing   ([Aschen](https://github.com/Aschen))

#### Enhancements

- [ [#686](#686) ] Add KDocument<T> strong param type for Kuzzle Document   ([Aschen](https://github.com/Aschen))
---

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="7.9.0" />
+
+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="7.9.0" />
+
+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="7.9.0" />
+
+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,80 @@
+---
+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.*`
+
+::: info
+The BatchController can be used with [strong typing](/sdk/js/7/essentials/strong-typing) like the Document controller.
+
+```js
+const doc = await batch.get<DeviceContent>('nyc-open-data', 'yellow-taxi', 'aschen');
+```
+
+:::
+
+
+**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.
+:::
+
+

doc/7/essentials/realtime-application/index.md

@@ -56,6 +56,15 @@ const doc = await observer.get('nyc-open-data', 'yellow-taxi', 'aschen');
 */
 ```
 
+::: info
+The Observer controller can be used with [strong typing](/sdk/js/7/essentials/strong-typing) like the Document controller.
+
+```js
+const doc = await observer.get<DeviceContent>('nyc-open-data', 'yellow-taxi', 'aschen');
+```
+
+:::
+
 ### Retrieve realtime documents
 
 Realtime documents can be retrieved by using one of those methods:

doc/7/essentials/strong-typing/index.md

@@ -0,0 +1,33 @@
+---
+code: false
+type: page
+title: Strong Typing
+description: Use strong typing for more safety
+order: 700
+---
+
+# Strong Typing
+
+The SDK exposes numerous types to help Typescript developer to maintain a safer codebase and prevents obvious errors.
+
+## Kuzzle Document (KDocument)
+
+The Document controller methods can be used with an explicit type that represents the content of the manipulated document.
+
+Document content must be defined by extending the `KDocumentContent` interface.
+
+```js
+interface DeviceContent extends KDocumentContent {
+  model: string;
+  reference: string;
+  battery: number;
+}
+
+const device = await sdk.document.get<DeviceContent>('iot', 'devices', 'abeeway-H72K2');
+```
+
+The returned type is `KDocument<DeviceContent>` and it contains a `_source` property of type `DeviceContent`.
+
+::: info
+By default, a generic document content with only a strongly defined `_kuzzle_info` property is returned.
+:::

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';
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "kuzzle-sdk",
-  "version": "7.8.4",
+  "version": "7.9.0",
   "description": "Official Javascript SDK for Kuzzle",
   "author": "The Kuzzle Team <[email protected]>",
   "repository": {