Add query typing (#707)

A new BaseRequest interface can be extended to define the request type.

Author: Adrien Maret

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

@@ -32,4 +32,53 @@ The returned type is `KDocument<DeviceContent>` and it contains a `_source` prop
 
 ::: info
 By default, a generic document content with only a strongly defined `_kuzzle_info` property is returned.
-:::
+:::
+
+## Kuzzle.query method
+
+<SinceBadge version="auto-version"/>
+
+The [Kuzzle.query](/sdk/js/7/core-classes/kuzzle/query) method can accept 2 optional types.
+
+Those types are used to strongly type both the request payload and the response result for each API action used.
+
+```js
+query<TRequest extends BaseRequest, TResult> (
+  req: TRequest,
+  opts: JSONObject = {},
+): Promise<ResponsePayload<TResult>>;
+```
+
+You can define the `TRequest` type by extending the `BaseRequest` type. It corresponds to the payload sent to Kuzzle API.
+
+```js
+interface NotificationSmsRequest extends BaseRequest {
+  body: {
+    phone: string;
+    message: string;
+  }
+}
+```
+
+The `TResult` is just a definition of the expected result for the API action.
+
+```js
+interface NotificationSmsResult {
+  smsCount: number;
+}
+```
+
+The complete usage with strong typing will be:
+
+```js
+const { result } = await sdk.query<NotificationSmsRequest, NotificationSmsResult>({
+  controller: 'notification',
+  action: 'sms',
+  body: {
+    phone: '+33629951621',
+    message: 'Hello, world',
+  }
+});
+
+result.smsCount; // number
+```

src/Kuzzle.ts

@@ -15,7 +15,7 @@ import { Deprecation } from './utils/Deprecation';
 import { uuidv4 } from './utils/uuidv4';
 import { proxify } from './utils/proxify';
 import { debug } from './utils/debug';
-import { JSONObject } from './types';
+import { BaseRequest, JSONObject } from './types';
 import { RequestPayload } from './types/RequestPayload';
 import { ResponsePayload } from './types/ResponsePayload';
 import { RequestTimeoutError } from './RequestTimeoutError';
@@ -766,7 +766,10 @@ export class Kuzzle extends KuzzleEventEmitter {
    * @param req
    * @param opts - Optional arguments
    */
-  query (req: RequestPayload = {}, opts: JSONObject = {}): Promise<ResponsePayload> {
+  query<TRequest extends BaseRequest, TResult> (
+    req: TRequest,
+    opts: JSONObject = {},
+  ): Promise<ResponsePayload<TResult>> {
     if (typeof req !== 'object' || Array.isArray(req)) {
       throw new Error(`Kuzzle.query: Invalid request: ${JSON.stringify(req)}`);
     }
@@ -857,7 +860,7 @@ Discarded request: ${JSON.stringify(request)}`));
       requestTimeout,
       request,
       options
-    ).then((response: ResponsePayload) => {
+    ).then((response: ResponsePayload<TResult>) => {
       debug('RESPONSE', response);
 
       return this.deprecationHandler.logDeprecation(response);

src/controllers/Base.ts

@@ -1,6 +1,5 @@
 import { Kuzzle } from '../Kuzzle';
 import { JSONObject } from '../types';
-import { RequestPayload } from '../types/RequestPayload';
 
 export class BaseController {
   private _name: string;
@@ -36,7 +35,7 @@ export class BaseController {
    * @param request
    * @param options
   */
-  query (request: RequestPayload = {}, options: any = {}): Promise<JSONObject> {
+  query (request: any, options: any = {}): Promise<JSONObject> {
     request.controller = request.controller || this.name;
 
     return this._kuzzle.query(request, options);

src/core/searchResult/SearchResultBase.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from '../../types';
+import { BaseRequest, JSONObject } from '../../types';
 import { RequestPayload } from '../../types/RequestPayload';
 import { Kuzzle } from '../../Kuzzle';
 
@@ -60,7 +60,7 @@ export class SearchResultBase<T> implements SearchResult<T> {
 
   constructor (
     kuzzle: Kuzzle,
-    request: RequestPayload = {},
+    request: BaseRequest,
     options: JSONObject = {},
     result: any = {}
   ) {

src/types/BaseRequest.ts

@@ -0,0 +1,9 @@
+import { JSONObject } from './JSONObject';
+
+export interface BaseRequest {
+  controller: string;
+
+  action: string;
+
+  body?: JSONObject;
+}

src/types/RequestPayload.ts

@@ -5,16 +5,16 @@ import { JSONObject } from './JSONObject';
  *
  * @see https://docs.kuzzle.io/core/2/api/payloads/request
  */
-export type RequestPayload = {
+export interface RequestPayload {
   /**
    * API controller name
    */
-  controller?: string;
+  controller: string;
 
   /**
    * API action name
    */
-  action?: string;
+  action: string;
 
   /**
    * Index name
@@ -52,4 +52,4 @@ export type RequestPayload = {
   requestId?: string;
 
   [key: string]: any;
-}
+}

src/types/ResponsePayload.ts

@@ -5,7 +5,7 @@ import { JSONObject } from './JSONObject';
  *
  * @see https://docs.kuzzle.io/core/2/api/payloads/response
  */
-export type ResponsePayload = {
+export interface ResponsePayload<TResult = JSONObject> {
   /**
    * API controller name
    */
@@ -86,7 +86,7 @@ export type ResponsePayload = {
   /**
    * API action result
    */
-  result: any;
+  result: TResult;
 
   /**
    * HTTP status code

src/types/index.ts

@@ -22,4 +22,6 @@ export * from './mResponses';
 
 export * from './KDocument';
 
-export * from './RequestPayload';
+export * from './RequestPayload';
+
+export * from './BaseRequest';

test/kuzzle/query.test.js

@@ -174,7 +174,7 @@ describe('Kuzzle query management', () => {
       };
 
       kuzzle.volatile = volatile;
-      kuzzle.query();
+      kuzzle.query({});
       should(kuzzle._timeoutRequest).be.calledOnce();
       should(kuzzle._timeoutRequest).be.calledWithMatch(kuzzle._requestTimeout, {volatile: kuzzle.volatile});
     });