Updated TypeScript docs (#1144)

Author: delvedor

docs/typescript.asciidoc

@@ -1,4 +1,5 @@
 [[typescript]]
+
 == TypeScript support
 
 The client offers a first-class support for TypeScript, since it ships the type 
@@ -7,76 +8,36 @@ definitions for every exposed API.
 NOTE: If you are using TypeScript you will be required to use _snake_case_ style 
 to define the API parameters instead of _camelCase_. 
 
-Other than the types for the surface API, the client offers the types for every 
-request method, via the `RequestParams`, if you need the types for a search 
-request for instance, you can access them via `RequestParams.Search`.
-Every API that supports a body, accepts a 
-https://www.typescriptlang.org/docs/handbook/generics.html[generics] which 
-represents the type of the request body, if you don't configure anything, it 
-will default to `RequestBody`. +
-`RequestBody`, along with `RequestNDBody` and `ResponseBody` are defined inside the client, and it looks like this:
+By default event API uses https://www.typescriptlang.org/docs/handbook/generics.html[generics] to specify the requets and response bodies and the `meta.context`. Currently we can't provide those definitions, but we are working to improve this situation.
+
+You can't fid a partial definition of the request types by importing `RequestParams`, which it is used by default in the client and accepts a body (when needed) as a generic to provide a better specification.
+
+The body defaults to `RequestBody` and `RequestNDBody`, which are defined as follows:
+
 [source,ts]
 ----
-type RequestBody<T = Record<string, any>> = T | string | Buffer | ReadableStream
-type RequestNDBody<T = Record<string, any>[]> = T | string[] | Buffer | ReadableStream
-type ResponseBody<T = Record<string, any>> = T | string | boolean | ReadableStream
+type RequestBody<T = Record<string, any>>  = T | string | Buffer | ReadableStream
+type RequestNDBody<T = Record<string, any>[]>  = T | string | string[] | Buffer | ReadableStream
 ----
 
-For example:
+You can specify the response and request body in each API as follows:
 
 [source,ts]
 ----
-import { RequestParams } from '@elastic/elasticsearch'
-
-interface SearchBody {
-  query: {
-    match: { foo: string }
-  }
-}
-
-const searchParams: RequestParams.Search<SearchBody> = {
-  index: 'test',
-  body: {
-    query: {
-      match: { foo: 'bar' }
-    }
-  }
-}
-
-// This is valid as well
-const searchParams: RequestParams.Search = {
+const response = await client.search<ResponseBody, RequestBody, Context>({
   index: 'test',
   body: {
     query: {
       match: { foo: 'bar' }
     }
   }
-}
-----
+})
 
-You can find the type definiton of a response in `ApiResponse`, which accepts a 
-generics as well if you want to specify the body type, otherwise it defaults to 
-`BodyType`.
-
-[source,ts]
+console.log(response.body)
 ----
-interface SearchResponse<T> {
-  hits: {
-    hits: Array<{
-      _source: T;
-    }>
-  }
-}
 
-// Define the interface of the source object
-interface Source {
-  foo: string
-}
+You don't have to specify all the generics, but the order must be respected.
 
-client.search(searchParams)
-  .then((response: ApiResponse<SearchResponse<Source>>) => console.log(response))
-  .catch((err: Error) => {})
-----
 
 === A complete example
 
@@ -146,7 +107,7 @@ interface Source {
 
 async function run () {
   // All of the examples below are valid code, by default,
-  // the request body will be `RequestBody` and response will be `ResponseBody`.
+  // the request body will be `RequestBody` and response will be `Record<string, any>`.
   const response = await client.search({
     index: 'test',
     body: {
@@ -158,20 +119,20 @@ async function run () {
   // body here is `ResponseBody`
   console.log(response.body)
 
-  // The first generic is the request body
-  const response = await client.search<SearchBody>({
+  // The first generic is the response body
+  const response = await client.search<SearchResponse<Source>>({
     index: 'test',
-    // Here the body must follow the `SearchBody` interface
+    // Here the body must follow the `RequestBody` interface
     body: {
       query: {
         match: { foo: 'bar' }
       }
     }
   })
-  // body here is `ResponseBody`
+  // body here is `SearchResponse<Source>`
   console.log(response.body)
 
-  const response = await client.search<SearchBody, SearchResponse<Source>>({
+  const response = await client.search<SearchResponse<Source>, SearchBody>({
     index: 'test',
     // Here the body must follow the `SearchBody` interface
     body: {
@@ -180,7 +141,7 @@ async function run () {
       }
     }
   })
-  // Now you can have full type definition of the response
+  // body here is `SearchResponse<Source>`
   console.log(response.body)
 }