Improve typings (#813)
The ApiResponse now accepts a generics that defaults to any, same for every API method that might need a body.
This commit is contained in:
Tomas Della Vedova
committed by
delvedor
delvedor
parent
48233503f7
commit
48c6ad15a6
@ -4289,6 +4289,149 @@ link:http://www.elastic.co/guide/en/elasticsearch/reference/current[Reference]
|
||||
|
||||
|===
|
||||
|
||||
<<<<<<< HEAD
|
||||
=======
|
||||
=== dataFrame.deleteDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.deleteDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/delete-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id of the transform to delete
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.getDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.getDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/get-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id or comma delimited list of id expressions of the transforms to get, '_all' or '*' implies get all transforms
|
||||
|
||||
|`from`
|
||||
|`number` - skips a number of transform configs, defaults to 0
|
||||
|
||||
|`size`
|
||||
|`number` - specifies a max number of transforms to get, defaults to 100
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.getDataFrameTransformStats
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.getDataFrameTransformStats([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/get-data-frame-transform-stats.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id of the transform for which to get stats. '_all' or '*' implies all transforms
|
||||
|
||||
|`from`
|
||||
|`number` - skips a number of transform stats, defaults to 0
|
||||
|
||||
|`size`
|
||||
|`number` - specifies a max number of transform stats to get, defaults to 100
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.previewDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.previewDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/preview-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`body`
|
||||
|`object` - The definition for the data_frame transform to preview
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.putDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.putDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/put-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id of the new transform.
|
||||
|
||||
|`body`
|
||||
|`object` - The data frame transform definition
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.startDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.startDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/start-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id of the transform to start
|
||||
|
||||
|`timeout`
|
||||
|`string` - Controls the time to wait for the transform to start
|
||||
|
||||
|===
|
||||
|
||||
=== dataFrame.stopDataFrameTransform
|
||||
[source,js]
|
||||
----
|
||||
client.dataFrame.stopDataFrameTransform([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/stop-data-frame-transform.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`transform_id` or `transformId`
|
||||
|`string` - The id of the transform to stop
|
||||
|
||||
|`wait_for_completion` or `waitForCompletion`
|
||||
|`boolean` - Whether to wait for the transform to fully stop before returning or not. Default to false
|
||||
|
||||
|`timeout`
|
||||
|`string` - Controls the time to wait until the transform has stopped. Default to 30 seconds
|
||||
|
||||
|===
|
||||
|
||||
=== graph.explore
|
||||
[source,js]
|
||||
----
|
||||
client.graph.explore([params] [, options] [, callback])
|
||||
----
|
||||
link:{ref}/graph-explore-api.html[Reference]
|
||||
[cols=2*]
|
||||
|===
|
||||
|`index`
|
||||
|`string, string[]` - A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices
|
||||
|
||||
|`type`
|
||||
|`string, string[]` - A comma-separated list of document types to search; leave empty to perform the operation on all types
|
||||
|
||||
|`routing`
|
||||
|`string` - Specific routing value
|
||||
|
||||
|`timeout`
|
||||
|`string` - Explicit operation timeout
|
||||
|
||||
|`body`
|
||||
|`object` - Graph Query DSL
|
||||
|
||||
|===
|
||||
|
||||
>>>>>>> a21281f... Improve typings (#813)
|
||||
=== ilm.deleteLifecycle
|
||||
[source,js]
|
||||
----
|
||||
|
||||
@ -3,58 +3,146 @@
|
||||
|
||||
The client offers a first-class support for TypeScript, since it ships the type definitions for every exposed API.
|
||||
|
||||
While the client offers type definitions for Request parameters, Request bodies and responses are shipped with `any` because there is not an official spec that defines them, so we cannot make guarantees over them (but since they are shipped with `any`, you can easily override them with your own typing definitions).
|
||||
|
||||
NOTE: If you are using TypeScript you will be required to use _snake_case_ style to define the API parameters instead of _camelCase_.
|
||||
|
||||
=== How to extend the provided typings?
|
||||
Extend the provided typings is very straightforward, you should declare a custom `.d.ts` file and then write inside your type extensions, following there is an example of how do it.
|
||||
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 `any`.
|
||||
|
||||
For example:
|
||||
|
||||
[source,ts]
|
||||
----
|
||||
declare module '@elastic/elasticsearch' {
|
||||
export interface ShardsResponse {
|
||||
total: number;
|
||||
successful: number;
|
||||
failed: number;
|
||||
skipped: number;
|
||||
}
|
||||
import { RequestParams } from '@elastic/elasticsearch'
|
||||
|
||||
export interface Explanation {
|
||||
value: number;
|
||||
description: string;
|
||||
details: Explanation[];
|
||||
}
|
||||
|
||||
export interface SearchResponse<T> {
|
||||
took: number;
|
||||
timed_out: boolean;
|
||||
_scroll_id?: string;
|
||||
_shards: ShardsResponse;
|
||||
hits: {
|
||||
total: number;
|
||||
max_score: number;
|
||||
hits: Array<{
|
||||
_index: string;
|
||||
_type: string;
|
||||
_id: string;
|
||||
_score: number;
|
||||
_source: T;
|
||||
_version?: number;
|
||||
_explanation?: Explanation;
|
||||
fields?: any;
|
||||
highlight?: any;
|
||||
inner_hits?: any;
|
||||
matched_queries?: string[];
|
||||
sort?: string[];
|
||||
}>;
|
||||
};
|
||||
aggregations?: any;
|
||||
}
|
||||
|
||||
export interface MSearchResponse<T> {
|
||||
responses?: Array<SearchResponse<T>>;
|
||||
interface SearchBody {
|
||||
query: {
|
||||
match: { foo: string }
|
||||
}
|
||||
}
|
||||
|
||||
export {};
|
||||
const searchParams: RequestParams.Search<SearchBody> = {
|
||||
index: 'test',
|
||||
body: {
|
||||
query: {
|
||||
match: { foo: 'bar' }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// This is valid as well
|
||||
const searchParams: RequestParams.Search = {
|
||||
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 `any`.
|
||||
|
||||
[source,ts]
|
||||
----
|
||||
interface SearchResponse<T> {
|
||||
hits: {
|
||||
hits: Array<{
|
||||
_source: T;
|
||||
}>
|
||||
}
|
||||
}
|
||||
|
||||
// Define the intefrace of the source object
|
||||
interface Source {
|
||||
foo: string
|
||||
}
|
||||
|
||||
client.search(searchParams)
|
||||
.then((response: ApiResponse<SearchResponse<Source>>) => console.log(response))
|
||||
.catch((err: Error) => {})
|
||||
----
|
||||
|
||||
=== A complete example
|
||||
|
||||
[source,ts]
|
||||
----
|
||||
import {
|
||||
Client,
|
||||
// Object that contains the type definitions of every API method
|
||||
RequestParams,
|
||||
// Interface of the generic API response
|
||||
ApiResponse,
|
||||
} from '@elastic/elasticsearch'
|
||||
|
||||
const client = new Client({ node: 'http://localhost:9200' })
|
||||
|
||||
// Define the type of the body for the Search request
|
||||
interface SearchBody {
|
||||
query: {
|
||||
match: { foo: string }
|
||||
}
|
||||
}
|
||||
|
||||
// Complete definition of the Search response
|
||||
interface ShardsResponse {
|
||||
total: number;
|
||||
successful: number;
|
||||
failed: number;
|
||||
skipped: number;
|
||||
}
|
||||
|
||||
interface Explanation {
|
||||
value: number;
|
||||
description: string;
|
||||
details: Explanation[];
|
||||
}
|
||||
|
||||
interface SearchResponse<T> {
|
||||
took: number;
|
||||
timed_out: boolean;
|
||||
_scroll_id?: string;
|
||||
_shards: ShardsResponse;
|
||||
hits: {
|
||||
total: number;
|
||||
max_score: number;
|
||||
hits: Array<{
|
||||
_index: string;
|
||||
_type: string;
|
||||
_id: string;
|
||||
_score: number;
|
||||
_source: T;
|
||||
_version?: number;
|
||||
_explanation?: Explanation;
|
||||
fields?: any;
|
||||
highlight?: any;
|
||||
inner_hits?: any;
|
||||
matched_queries?: string[];
|
||||
sort?: string[];
|
||||
}>;
|
||||
};
|
||||
aggregations?: any;
|
||||
}
|
||||
|
||||
// Define the intefrace of the source object
|
||||
interface Source {
|
||||
foo: string
|
||||
}
|
||||
|
||||
async function run (): Promise<void> {
|
||||
// Define the search parameters
|
||||
const searchParams: RequestParams.Search<SearchBody> = {
|
||||
index: 'test',
|
||||
body: {
|
||||
query: {
|
||||
match: { foo: 'bar' }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Craft the final type definition
|
||||
const response: ApiResponse<SearchResponse<Source>> = await client.search(searchParams)
|
||||
console.log(response.body)
|
||||
}
|
||||
|
||||
run().catch(console.log)
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user