Refactored type definitions

docs/typescript.asciidoc

@@ -137,19 +137,43 @@ interface Source {
   foo: string
 }
 
-async function run (): Promise<void> {
-  // Define the search parameters
-  const searchParams: RequestParams.Search<SearchBody> = {
+async function run () {
+  // All of the examples below are valid code, by default,
+  // both the request body and response will be `any`.
+  const response = await client.search({
     index: 'test',
     body: {
       query: {
         match: { foo: 'bar' }
       }
     }
-  }
+  })
+  // body here is `any`
+  console.log(response.body)
+
+  // The first generic is the request body
+  const response = await client.search<SearchBody>({
+    index: 'test',
+    // Here the body must follow the `SearchBody` interface
+    body: {
+      query: {
+        match: { foo: 'bar' }
+      }
+    }
+  })
+  // body here is `any`
+  console.log(response.body)
 
-  // Craft the final type definition
-  const response: ApiResponse<SearchResponse<Source>> = await client.search(searchParams)
+  const response = await client.search<SearchBody, SearchResponse<Source>>({
+    index: 'test',
+    // Here the body must follow the `SearchBody` interface
+    body: {
+      query: {
+        match: { foo: 'bar' }
+      }
+    }
+  })
+  // Now you can have full type definition of the response
   console.log(response.body)
 }
 

lib/Connection.d.ts

@@ -5,35 +5,43 @@
 /// <reference types="node" />
 
 import { URL } from 'url';
-import { inspect, InspectOptions } from 'util';
+import { inspect, InspectOptions } from 'util'
+import { Readable as ReadableStream } from 'stream';
 import { ApiKeyAuth, BasicAuth } from './pool'
-import * as http from 'http';
-import { ConnectionOptions as TlsConnectionOptions } from 'tls';
+import * as http from 'http'
+import { ConnectionOptions as TlsConnectionOptions } from 'tls'
 
 export declare type agentFn = () => any;
 
 interface ConnectionOptions {
   url: URL;
   ssl?: TlsConnectionOptions;
   id?: string;
-  headers?: any;
+  headers?: Record<string, any>;
   agent?: AgentOptions | agentFn;
   status?: string;
-  roles?: any;
+  roles?: ConnectionRoles;
   auth?: BasicAuth | ApiKeyAuth;
 }
 
+interface ConnectionRoles {
+  master?: boolean
+  data?: boolean
+  ingest?: boolean
+  ml?: boolean
+}
+
 interface RequestOptions extends http.ClientRequestArgs {
   asStream?: boolean;
-  body?: any;
+  body?: string | Buffer | ReadableStream;
   querystring?: string;
 }
 
 export interface AgentOptions {
-  keepAlive: boolean;
-  keepAliveMsecs: number;
-  maxSockets: number;
-  maxFreeSockets: number;
+  keepAlive?: boolean;
+  keepAliveMsecs?: number;
+  maxSockets?: number;
+  maxFreeSockets?: number;
 }
 
 export default class Connection {
@@ -47,27 +55,26 @@ export default class Connection {
     INGEST: string;
     ML: string;
   };
-  url: URL;
-  ssl: TlsConnectionOptions | null;
-  id: string;
-  headers: any;
-  deadCount: number;
-  resurrectTimeout: number;
-  statuses: any;
-  roles: any;
-  makeRequest: any;
-  _openRequests: number;
-  _status: string;
-  _agent: http.Agent;
-  constructor(opts?: ConnectionOptions);
-  request(params: RequestOptions, callback: (err: Error | null, response: http.IncomingMessage | null) => void): http.ClientRequest;
-  close(): Connection;
-  setRole(role: string, enabled: boolean): Connection;
-  status: string;
-  buildRequestObject(params: any): http.ClientRequestArgs;
+  url: URL
+  ssl: TlsConnectionOptions | null
+  id: string
+  headers: Record<string, any>
+  status: string
+  roles: ConnectionRoles
+  deadCount: number
+  resurrectTimeout: number
+  makeRequest: any
+  _openRequests: number
+  _status: string
+  _agent: http.Agent
+  constructor(opts?: ConnectionOptions)
+  request(params: RequestOptions, callback: (err: Error | null, response: http.IncomingMessage | null) => void): http.ClientRequest
+  close(): Connection
+  setRole(role: string, enabled: boolean): Connection
+  buildRequestObject(params: any): http.ClientRequestArgs
   // @ts-ignore
-  [inspect.custom](object: any, options: InspectOptions): string;
-  toJSON(): any;
+  [inspect.custom](object: any, options: InspectOptions): string
+  toJSON(): any
 }
 
 export {};

lib/Transport.d.ts

@@ -2,9 +2,16 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+import { Readable as ReadableStream } from 'stream';
 import { ConnectionPool, CloudConnectionPool } from './pool';
 import Connection from './Connection';
 import Serializer from './Serializer';
+import * as errors from './errors';
+
+export type ApiError = errors.ConfigurationError | errors.ConnectionError |
+                       errors.DeserializationError | errors.SerializationError |
+                       errors.NoLivingConnectionsError | errors.ResponseError |
+                       errors.TimeoutError
 
 export interface nodeSelectorFn {
   (connections: Connection[]): Connection;
@@ -18,36 +25,33 @@ export interface generateRequestIdFn {
   (params: TransportRequestParams, options: TransportRequestOptions): any;
 }
 
-declare type noopFn = (...args: any[]) => void;
-declare type emitFn = (event: string | symbol, ...args: any[]) => boolean;
-
 interface TransportOptions {
-  emit: emitFn & noopFn;
+  emit: (event: string | symbol, ...args: any[]) => boolean;
   connectionPool: ConnectionPool | CloudConnectionPool;
   serializer: Serializer;
   maxRetries: number;
   requestTimeout: number | string;
-  suggestCompression: boolean;
+  suggestCompression?: boolean;
   compression?: 'gzip';
-  sniffInterval: number;
-  sniffOnConnectionFault: boolean;
+  sniffInterval?: number;
+  sniffOnConnectionFault?: boolean;
   sniffEndpoint: string;
-  sniffOnStart: boolean;
+  sniffOnStart?: boolean;
   nodeFilter?: nodeFilterFn;
   nodeSelector?: string | nodeSelectorFn;
-  headers?: anyObject;
+  headers?: Record<string, any>;
   generateRequestId?: generateRequestIdFn;
-  name: string;
+  name?: string;
   opaqueIdPrefix?: string;
 }
 
-export interface RequestEvent<T = any, C = any> {
-  body: T;
+export interface RequestEvent<Response = any, Context = unknown> {
+  body: Response;
   statusCode: number | null;
-  headers: anyObject | null;
+  headers: Record<string, any> | null;
   warnings: string[] | null;
   meta: {
-    context: C;
+    context: Context;
     name: string;
     request: {
       params: TransportRequestParams;
@@ -66,31 +70,30 @@ export interface RequestEvent<T = any, C = any> {
 
 // ApiResponse and RequestEvent are the same thing
 // we are doing this for have more clear names
-export interface ApiResponse<T = any, C = any> extends RequestEvent<T, C> {}
+export interface ApiResponse<Response = any, Context = unknown> extends RequestEvent<Response, Context> {}
 
-declare type anyObject = {
-  [key: string]: any;
-};
+export type BodyType = Record<string, any> | string | Buffer | ReadableStream
+export type NDBodyType = Record<string, any>[] | string[] | Buffer | ReadableStream
 
 export interface TransportRequestParams {
   method: string;
   path: string;
-  body?: anyObject;
-  bulkBody?: anyObject;
-  querystring?: anyObject;
+  body?: BodyType;
+  bulkBody?: NDBodyType;
+  querystring?: Record<string, any>;
 }
 
 export interface TransportRequestOptions {
   ignore?: number[];
   requestTimeout?: number | string;
   maxRetries?: number;
   asStream?: boolean;
-  headers?: anyObject;
-  querystring?: anyObject;
-  compression?: string;
+  headers?: Record<string, any>;
+  querystring?: Record<string, any>;
+  compression?: 'gzip';
   id?: any;
   context?: any;
-  warnings?: [string];
+  warnings?: string[];
   opaqueId?: string;
 }
 
@@ -114,7 +117,7 @@ export default class Transport {
     SNIFF_ON_CONNECTION_FAULT: string;
     DEFAULT: string;
   };
-  emit: emitFn & noopFn;
+  emit: (event: string | symbol, ...args: any[]) => boolean;
   connectionPool: ConnectionPool | CloudConnectionPool;
   serializer: Serializer;
   maxRetries: number;
@@ -130,9 +133,7 @@ export default class Transport {
   _isSniffing: boolean;
   constructor(opts: TransportOptions);
   request(params: TransportRequestParams, options?: TransportRequestOptions): Promise<ApiResponse>;
-  request(params: TransportRequestParams, options?: TransportRequestOptions, callback?: (err: Error | null, result: ApiResponse) => void): TransportRequestCallback;
+  request(params: TransportRequestParams, options?: TransportRequestOptions, callback?: (err: ApiError, result: ApiResponse) => void): TransportRequestCallback;
   getConnection(opts: TransportGetConnectionOptions): Connection | null;
   sniff(opts?: TransportSniffOptions, callback?: (...args: any[]) => void): void;
 }
-
-export {};

lib/errors.d.ts

@@ -54,6 +54,6 @@ export declare class ResponseError extends ElasticsearchClientError {
   meta: ApiResponse;
   body: any;
   statusCode: number;
-  headers: any;
+  headers: Record<string, any>;
   constructor(meta: ApiResponse);
 }

lib/pool/index.d.ts

@@ -4,6 +4,7 @@
 
 /// <reference types="node" />
 
+import { URL } from 'url'
 import { SecureContextOptions } from 'tls';
 import Connection, { AgentOptions } from '../Connection';
 import { nodeFilterFn, nodeSelectorFn } from '../Transport';
@@ -13,14 +14,12 @@ interface BaseConnectionPoolOptions {
   agent?: AgentOptions;
   auth?: BasicAuth | ApiKeyAuth;
   emit: (event: string | symbol, ...args: any[]) => boolean;
-  pingTimeout?: number;
   Connection: typeof Connection;
-  resurrectStrategy?: string;
 }
 
 interface ConnectionPoolOptions extends BaseConnectionPoolOptions {
   pingTimeout?: number;
-  resurrectStrategy?: string;
+  resurrectStrategy?: 'ping' | 'optimistic' | 'none';
   sniffEnabled?: boolean;
 }
 
@@ -65,6 +64,8 @@ interface ResurrectEvent {
 
 declare class BaseConnectionPool {
   connections: Connection[];
+  size: number;
+  emit: (event: string | symbol, ...args: any[]) => boolean;
   _ssl: SecureContextOptions | null;
   _agent: AgentOptions | null;
   auth: BasicAuth | ApiKeyAuth;
@@ -137,7 +138,7 @@ declare class BaseConnectionPool {
    * @param {string} url
    * @returns {object} host
    */
-  urlToHost(url: string): any;
+  urlToHost(url: string): { url: URL };
 }
 
 declare class ConnectionPool extends BaseConnectionPool {
@@ -167,7 +168,7 @@ declare class ConnectionPool extends BaseConnectionPool {
 declare class CloudConnectionPool extends BaseConnectionPool {
   cloudConnection: Connection | null
   constructor(opts?: BaseConnectionPoolOptions);
-  getConnection(): Connection;
+  getConnection(): Connection | null;
 }
 
 declare function defaultNodeFilter(node: Connection): boolean;

package.json

@@ -20,7 +20,7 @@
     "test:unit": "tap test/unit/*.test.js -t 300 --no-coverage",
     "test:behavior": "tap test/behavior/*.test.js -t 300 --no-coverage",
     "test:integration": "node test/integration/index.js",
-    "test:types": "tsc --project ./test/types/tsconfig.json",
+    "test:types": "tsd",
     "test:coverage": "nyc tap test/unit/*.test.js test/behavior/*.test.js -t 300 && nyc report --reporter=text-lcov > coverage.lcov",
     "lint": "standard",
     "lint:fix": "standard --fix",
@@ -58,7 +58,7 @@
     "standard": "^13.0.2",
     "stoppable": "^1.1.0",
     "tap": "^14.4.1",
-    "typescript": "^3.4.5",
+    "tsd": "^0.11.0",
     "workq": "^2.1.0"
   },
   "dependencies": {
@@ -80,5 +80,8 @@
   },
   "engines": {
     "node": ">=8"
+  },
+  "tsd": {
+    "directory": "test/types"
   }
 }

scripts/generate.js

@@ -58,7 +58,7 @@ function start (opts) {
       { encoding: 'utf8' }
     )
 
-    const { fn: factory, types } = genFactory(apiOutputFolder)
+    const { fn: factory, types } = genFactory(apiOutputFolder, [apiFolder, xPackFolder])
     writeFileSync(
       mainOutputFile,
       factory,

scripts/utils/generateApis.js

@@ -543,3 +543,4 @@ function intersect (first, ...rest) {
 }
 
 module.exports = generate
+module.exports.ndjsonApi = ndjsonApi