Add KDocument<T> strong param type for Kuzzle Document (#686)

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

// this is still possible
const device = await sdk.document.get('iot', 'devices', 'abeeway-H72K2');
```

The returned type is `KDocument<DeviceContent>` and it contains a `_source` property of type `DeviceContent`.

This is not a breaking change since the `KDocument` type is compatible with the former `Document` type.

fix #670

Author: Adrien Maret

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

@@ -29,6 +29,16 @@ It overloads the original DocumentController but methods will be executed in bat
 
 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

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.
+:::

src/controllers/Document.ts

@@ -2,7 +2,6 @@ import { BaseController } from './Base';
 import { DocumentSearchResult } from '../core/searchResult/Document';
 import {
   JSONObject,
-  Document,
   mCreateResponse,
   ArgsDefault,
   mCreateRequest,
@@ -14,7 +13,9 @@ import {
   mReplaceResponse,
   mUpdateRequest,
   mUpdateResponse,
-  DocumentHit,
+  KDocumentContentGeneric,
+  KDocument,
+  KHit,
 } from '../types';
 import { SearchResult } from '../core/searchResult/SearchResultBase';
 
@@ -73,13 +74,13 @@ export class DocumentController extends BaseController {
    *
    * @returns The created document
    */
-  create (
+  create<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    content: JSONObject,
+    content: Partial<TKDocumentContent>,
     _id: string = null,
     options: ArgsDocumentControllerCreate = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -110,13 +111,13 @@ export class DocumentController extends BaseController {
    *
    * @returns The created or replaced document
    */
-  createOrReplace (
+  createOrReplace<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
-    content: JSONObject,
+    content: Partial<TKDocumentContent>,
     options: ArgsDocumentControllerCreateOrReplace = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -181,12 +182,12 @@ export class DocumentController extends BaseController {
    *
    * @returns The deleted documents IDs
    */
-  deleteByQuery(
+  deleteByQuery (
     index: string,
     collection: string,
     query: JSONObject = {},
     options: ArgsDocumentControllerDeleteByQuery = {}
-  ): Promise<Array<string>> {
+  ): Promise<string[]> {
     const request = {
       index,
       collection,
@@ -217,13 +218,13 @@ export class DocumentController extends BaseController {
    *
    * @returns The updated document
    */
-  deleteFields(
+  deleteFields<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
     fields: string[],
     options: ArgsDocumentControllerDeleteFields = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -287,12 +288,12 @@ export class DocumentController extends BaseController {
    *
    * @returns The document
    */
-  get (
+  get<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
     options: ArgsDocumentControllerGet = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -321,10 +322,10 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mCreate (
+  mCreate<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    documents: mCreateRequest,
+    documents: mCreateRequest<TKDocumentContent>,
     options: ArgsDocumentControllerMCreate = {}
   ): Promise<mCreateResponse> {
     const request = {
@@ -357,10 +358,10 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mCreateOrReplace (
+  mCreateOrReplace<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    documents: mCreateOrReplaceRequest,
+    documents: mCreateOrReplaceRequest<TKDocumentContent>,
     options: ArgsDocumentControllerMCreateOrReplace = {}
   ): Promise<mCreateOrReplaceResponse> {
     const request = {
@@ -427,20 +428,20 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mGet (
+  mGet<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    ids: Array<string>,
+    ids: string[],
     options: ArgsDocumentControllerMGet = {}
   ): Promise<{
     /**
      * Array of successfully retrieved documents
      */
-    successes: Array<Document>;
+    successes: KDocument<TKDocumentContent>[];
     /**
      * Array of the IDs of not found documents.
      */
-    errors: Array<string>;
+    errors: string[];
   }> {
     const request = {
       index,
@@ -470,10 +471,10 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mReplace (
+  mReplace<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    documents: mReplaceRequest,
+    documents: mReplaceRequest<TKDocumentContent>,
     options: ArgsDocumentControllerMReplace = {}
   ): Promise<mReplaceResponse> {
     const request = {
@@ -510,10 +511,10 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mUpdate (
+  mUpdate<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    documents: mUpdateRequest,
+    documents: mUpdateRequest<TKDocumentContent>,
     options: ArgsDocumentControllerMUpdate = {}
   ): Promise<mUpdateResponse> {
     const request = {
@@ -547,10 +548,10 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  mUpsert (
+  mUpsert<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    documents: mUpdateRequest,
+    documents: mUpdateRequest<TKDocumentContent>,
     options: ArgsDocumentControllerMUpsert = {}
   ): Promise<mUpdateResponse> {
     const request = {
@@ -582,13 +583,13 @@ export class DocumentController extends BaseController {
    *
    * @returns The replaced document
    */
-  replace (
+  replace<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
-    content: JSONObject,
+    content: Partial<TKDocumentContent>,
     options: ArgsDocumentControllerReplace = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -620,12 +621,12 @@ export class DocumentController extends BaseController {
    *
    * @returns A SearchResult
    */
-  search (
+  search<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     searchBody: JSONObject = {},
     options: ArgsDocumentControllerSearch = {}
-  ): Promise<SearchResult<DocumentHit>> {
+  ): Promise<SearchResult<KHit<TKDocumentContent>>> {
     return this._search(index, collection, searchBody, options)
       .then(({ response, request, opts }) => (
         new DocumentSearchResult(this.kuzzle, request, opts, response.result)
@@ -680,13 +681,13 @@ export class DocumentController extends BaseController {
    *
    * @returns The replaced document
    */
-  update (
+  update<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
-    content: JSONObject,
+    content: Partial<TKDocumentContent>,
     options: ArgsDocumentControllerUpdate = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -720,7 +721,7 @@ export class DocumentController extends BaseController {
    *
    * @returns An object containing 2 arrays: "successes" and "errors"
    */
-  updateByQuery(
+  updateByQuery<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     query: JSONObject,
@@ -730,15 +731,15 @@ export class DocumentController extends BaseController {
     /**
      * Array of successfully updated documents
      */
-    successes: Array<Document>;
+    successes: KDocument<TKDocumentContent>[];
     /**
      * Array of failed creation
      */
     errors: Array<{
       /**
        * Document that cause the error
        */
-      document: Document;
+      document: KDocument<TKDocumentContent>;
       /**
        * HTTP error status
        */
@@ -781,13 +782,13 @@ export class DocumentController extends BaseController {
    *
    * @returns Information about the updated document
   */
-  upsert (
+  upsert<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
     _id: string,
-    changes: JSONObject,
+    changes: Partial<TKDocumentContent>,
     options: ArgsDocumentControllerUpsert = {}
-  ): Promise<Document> {
+  ): Promise<KDocument<TKDocumentContent>> {
     const request = {
       index,
       collection,
@@ -816,10 +817,10 @@ export class DocumentController extends BaseController {
    *
    * @returns True if the document is valid
    */
-  validate (
+  validate<TKDocumentContent extends KDocumentContentGeneric> (
     index: string,
     collection: string,
-    content: JSONObject,
+    content: TKDocumentContent,
     options: ArgsDocumentControllerValidate = {}
   ): Promise<boolean> {
     return this.query({