1 | import * as stream from 'stream';
|
2 | import {Service} from './service';
|
3 | import {Response} from './response';
|
4 | import {HttpRequest} from './http_request';
|
5 | import {AWSError} from './error';
|
6 | export class Request<D, E> {
|
7 | /**
|
8 | * Creates a request for an operation on a given service with a set of input parameters.
|
9 | *
|
10 | * @param {AWS.Service} service - The service to perform the operation on.
|
11 | * @param {string} operation - The operation to perform on the service.
|
12 | * @param {object} params - Parameters to send to the operation.
|
13 | */
|
14 | constructor(service: Service, operation: string, params?: any);
|
15 | /**
|
16 | * Aborts a request, emitting the error and complete events.
|
17 | * This feature is not supported in the browser environment of the SDK.
|
18 | */
|
19 | abort(): void;
|
20 | /**
|
21 | * Converts the request object into a readable stream that can be read from or piped into a writable stream.
|
22 | * The data read from a readable stream contains only the raw HTTP body contents.
|
23 | * This feature is not supported in the browser environment of the SDK.
|
24 | */
|
25 | createReadStream(): stream.Readable;
|
26 | /**
|
27 | * Iterates over each page of results given a pageable request, calling the provided callback with each page of data.
|
28 | * After all pages have been retrieved, the callback is called with null data.
|
29 | *
|
30 | * @param {eachPage} callback - The callback that handles the response.
|
31 | */
|
32 | eachPage(callback: (err: E, data: D, doneCallback?: () => void) => boolean): void;
|
33 | /**
|
34 | * Returns whether the operation can return multiple pages of response data.
|
35 | */
|
36 | isPageable(): boolean;
|
37 | /**
|
38 | * Sends the request object.
|
39 | * If a callback is supplied, it is called when a response is returned from the service.
|
40 | */
|
41 | send(callback?: (err: E, data: D) => void): void;
|
42 | /**
|
43 | * Adds a listener that is triggered when a request emits the specified event.
|
44 | *
|
45 | * @param {string} event - 'Name of a request event.'
|
46 | * @param {function} listener - Callback to run when the event is triggered on the request.
|
47 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
48 | */
|
49 | on(event: string, listener: () => void, prepend?: boolean): Request<D, E>;
|
50 | /**
|
51 | * Adds a listener that is triggered when a request is being validated.
|
52 | *
|
53 | * @param {string} event - validate: triggered when a request is being validated.
|
54 | * @param {function} listener - Callback to run when the request is being validated.
|
55 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
56 | */
|
57 | on(event: "validate", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
58 | /**
|
59 | * Adds a listener that is triggered when the request payload is being built.
|
60 | *
|
61 | * @param {string} event - build: triggered when the request payload is being built.
|
62 | * @param {function} listener - Callback to run when the request's payload is being built.
|
63 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
64 | */
|
65 | on(event: "build", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
66 | /**
|
67 | * Adds a listener that is triggered when a request is being signed.
|
68 | *
|
69 | * @param {string} event - sign: triggered when a request is being signed.
|
70 | * @param {function} listener - Callback to run when the request is being signed.
|
71 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
72 | */
|
73 | on(event: "sign", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
74 | /**
|
75 | * Adds a listener that is triggered when a request is ready to be sent.
|
76 | *
|
77 | * @param {string} event - send: triggered when a request is ready to be sent.
|
78 | * @param {function} listener - Callback to run when the request is ready to be sent.
|
79 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
80 | */
|
81 | on(event: "send", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
82 | /**
|
83 | * Adds a listener that is triggered when a request failed and might need to be retried or redirected.
|
84 | *
|
85 | * @param {string} event - retry: triggered when a request failed and might need to be retried or redirected.
|
86 | * @param {function} listener - Callback to run when the request failed and may be retried.
|
87 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
88 | */
|
89 | on(event: "retry", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
90 | /**
|
91 | * Adds a listener that is triggered on all non-2xx requests so that listeners can extract error details from the response body.
|
92 | *
|
93 | * @param {string} event - extractError: triggered on all non-2xx requests so that listeners can extract error details from the response body.
|
94 | * @param {function} listener - Callback to run when the request failed.
|
95 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
96 | */
|
97 | on(event: "extractError", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
98 | /**
|
99 | * Adds a listener that is triggered in successful requests to allow listeners to de-serialize the response body into response.data.
|
100 | *
|
101 | * @param {string} event - extractData: triggered in successful requests to allow listeners to de-serialize the response body into response.data.
|
102 | * @param {function} listener - Callback to run when the request succeeded.
|
103 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
104 | */
|
105 | on(event: "extractData", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
106 | /**
|
107 | * Adds a listener that is triggered when the request completed successfully.
|
108 | *
|
109 | * @param {string} event - success: triggered when the request completed successfully.
|
110 | * @param {function} listener - Callback to run when the request completed successfully.
|
111 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
112 | */
|
113 | on(event: "success", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
114 | /**
|
115 | * Adds a listener that is triggered when an error occurs at any point during the request.
|
116 | *
|
117 | * @param {string} event - error: triggered when an error occurs at any point during the request.
|
118 | * @param {function} listener - Callback to run when the request errors at any point.
|
119 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
120 | */
|
121 | on(event: "error", listener: (err: AWSError, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
122 | /**
|
123 | * Adds a listener that is triggered whenever a request cycle completes.
|
124 | *
|
125 | * @param {string} event - complete: triggered whenever a request cycle completes.
|
126 | * @param {function} listener - Callback to run when the request cycle completes.
|
127 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
128 | */
|
129 | on(event: "complete", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
130 | /**
|
131 | * Adds a listener that is triggered when headers are sent by the remote server.
|
132 | *
|
133 | * @param {string} event - httpHeaders: triggered when headers are sent by the remote server.
|
134 | * @param {function} listener - Callback to run when the headers are sent by the remote server.
|
135 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
136 | */
|
137 | on(event: "httpHeaders", listener: (statusCode: number, headers: {[key: string]: string}, response: Response<D, E>, statusMessage: string) => void, prepend?: boolean): Request<D, E>;
|
138 | /**
|
139 | * Adds a listener that is triggered when data is sent by the remote server.
|
140 | *
|
141 | * @param {string} event - httpData: triggered when data is sent by the remote server.
|
142 | * @param {function} listener - Callback to run when data is sent by the remote server.
|
143 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
144 | */
|
145 | on(event: "httpData", listener: (chunk: Buffer|Uint8Array, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
146 | /**
|
147 | * Adds a listener that is triggered when the HTTP request has uploaded more data.
|
148 | *
|
149 | * @param {string} event - httpUploadProgress: triggered when the HTTP request has uploaded more data.
|
150 | * @param {function} listener - Callback to run when the HTTP request has uploaded more data.
|
151 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
152 | */
|
153 | on(event: "httpUploadProgress", listener: (progress: Progress, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
154 | /**
|
155 | * Adds a listener that is triggered when the HTTP request has downloaded more data.
|
156 | *
|
157 | * @param {string} event - httpDownloadProgress: triggered when the HTTP request has downloaded more data.
|
158 | * @param {function} listener - Callback to run when the HTTP request has downloaded more data.
|
159 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
160 | */
|
161 | on(event: "httpDownloadProgress", listener: (progress: Progress, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
162 | /**
|
163 | * Adds a listener that is triggered when the HTTP request failed.
|
164 | *
|
165 | * @param {string} event - httpError: triggered when the HTTP request failed.
|
166 | * @param {function} listener - Callback to run when the HTTP request failed.
|
167 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
168 | */
|
169 | on(event: "httpError", listener: (err: Error, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
170 | /**
|
171 | * Adds a listener that is triggered when the server is finished sending data.
|
172 | *
|
173 | * @param {string} event - httpDone: triggered when the server is finished sending data.
|
174 | * @param {function} listener - Callback to run when the server is finished sending data.
|
175 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
176 | */
|
177 | on(event: "httpDone", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
178 | /**
|
179 | * Adds a listener that is triggered when a request emits the specified event.
|
180 | *
|
181 | * @param {string} event - 'Name of a request event.'
|
182 | * @param {function} listener - Callback to run when the event is triggered on the request.
|
183 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
184 | */
|
185 | onAsync(event: string, listener: () => void, prepend?: boolean): Request<D, E>;
|
186 | /**
|
187 | * Adds a listener that is triggered when a request is being validated.
|
188 | *
|
189 | * @param {string} event - validate: triggered when a request is being validated.
|
190 | * @param {function} listener - Callback to run when the request is being validated.
|
191 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
192 | */
|
193 | onAsync(event: "validate", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
194 | /**
|
195 | * Adds a listener that is triggered when the request payload is being built.
|
196 | *
|
197 | * @param {string} event - build: triggered when the request payload is being built.
|
198 | * @param {function} listener - Callback to run when the request's payload is being built.
|
199 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
200 | */
|
201 | onAsync(event: "build", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
202 | /**
|
203 | * Adds a listener that is triggered when a request is being signed.
|
204 | *
|
205 | * @param {string} event - sign: triggered when a request is being signed.
|
206 | * @param {function} listener - Callback to run when the request is being signed.
|
207 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
208 | */
|
209 | onAsync(event: "sign", listener: (request: Request<D, E>) => void, prepend?: boolean): Request<D, E>;
|
210 | /**
|
211 | * Adds a listener that is triggered when a request is ready to be sent.
|
212 | *
|
213 | * @param {string} event - send: triggered when a request is ready to be sent.
|
214 | * @param {function} listener - Callback to run when the request is ready to be sent.
|
215 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
216 | */
|
217 | onAsync(event: "send", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
218 | /**
|
219 | * Adds a listener that is triggered when a request failed and might need to be retried or redirected.
|
220 | *
|
221 | * @param {string} event - retry: triggered when a request failed and might need to be retried or redirected.
|
222 | * @param {function} listener - Callback to run when the request failed and may be retried.
|
223 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
224 | */
|
225 | onAsync(event: "retry", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
226 | /**
|
227 | * Adds a listener that is triggered on all non-2xx requests so that listeners can extract error details from the response body.
|
228 | *
|
229 | * @param {string} event - extractError: triggered on all non-2xx requests so that listeners can extract error details from the response body.
|
230 | * @param {function} listener - Callback to run when the request failed.
|
231 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
232 | */
|
233 | onAsync(event: "extractError", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
234 | /**
|
235 | * Adds a listener that is triggered in successful requests to allow listeners to de-serialize the response body into response.data.
|
236 | *
|
237 | * @param {string} event - extractData: triggered in successful requests to allow listeners to de-serialize the response body into response.data.
|
238 | * @param {function} listener - Callback to run when the request succeeded.
|
239 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
240 | */
|
241 | onAsync(event: "extractData", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
242 | /**
|
243 | * Adds a listener that is triggered when the request completed successfully.
|
244 | *
|
245 | * @param {string} event - success: triggered when the request completed successfully.
|
246 | * @param {function} listener - Callback to run when the request completed successfully.
|
247 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
248 | */
|
249 | onAsync(event: "success", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
250 | /**
|
251 | * Adds a listener that is triggered when an error occurs at any point during the request.
|
252 | *
|
253 | * @param {string} event - error: triggered when an error occurs at any point during the request.
|
254 | * @param {function} listener - Callback to run when the request errors at any point.
|
255 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
256 | */
|
257 | onAsync(event: "error", listener: (err: AWSError, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
258 | /**
|
259 | * Adds a listener that is triggered whenever a request cycle completes.
|
260 | *
|
261 | * @param {string} event - complete: triggered whenever a request cycle completes.
|
262 | * @param {function} listener - Callback to run when the request cycle completes.
|
263 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
264 | */
|
265 | onAsync(event: "complete", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
266 | /**
|
267 | * Adds a listener that is triggered when headers are sent by the remote server.
|
268 | *
|
269 | * @param {string} event - httpHeaders: triggered when headers are sent by the remote server.
|
270 | * @param {function} listener - Callback to run when the headers are sent by the remote server.
|
271 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
272 | */
|
273 | onAsync(event: "httpHeaders", listener: (statusCode: number, headers: {[key: string]: string}, response: Response<D, E>, statusMessage: string) => void, prepend?: boolean): Request<D, E>;
|
274 | /**
|
275 | * Adds a listener that is triggered when data is sent by the remote server.
|
276 | *
|
277 | * @param {string} event - httpData: triggered when data is sent by the remote server.
|
278 | * @param {function} listener - Callback to run when data is sent by the remote server.
|
279 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
280 | */
|
281 | onAsync(event: "httpData", listener: (chunk: Buffer|Uint8Array, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
282 | /**
|
283 | * Adds a listener that is triggered when the HTTP request has uploaded more data.
|
284 | *
|
285 | * @param {string} event - httpUploadProgress: triggered when the HTTP request has uploaded more data.
|
286 | * @param {function} listener - Callback to run when the HTTP request has uploaded more data.
|
287 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
288 | */
|
289 | onAsync(event: "httpUploadProgress", listener: (progress: Progress, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
290 | /**
|
291 | * Adds a listener that is triggered when the HTTP request has downloaded more data.
|
292 | *
|
293 | * @param {string} event - httpDownloadProgress: triggered when the HTTP request has downloaded more data.
|
294 | * @param {function} listener - Callback to run when the HTTP request has downloaded more data.
|
295 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
296 | */
|
297 | onAsync(event: "httpDownloadProgress", listener: (progress: Progress, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
298 | /**
|
299 | * Adds a listener that is triggered when the HTTP request failed.
|
300 | *
|
301 | * @param {string} event - httpError: triggered when the HTTP request failed.
|
302 | * @param {function} listener - Callback to run when the HTTP request failed.
|
303 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
304 | */
|
305 | onAsync(event: "httpError", listener: (err: Error, response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
306 | /**
|
307 | * Adds a listener that is triggered when the server is finished sending data.
|
308 | *
|
309 | * @param {string} event - httpDone: triggered when the server is finished sending data.
|
310 | * @param {function} listener - Callback to run when the server is finished sending data.
|
311 | * @param {boolean} prepend - If set, prepends listener instead of appending.
|
312 | */
|
313 | onAsync(event: "httpDone", listener: (response: Response<D, E>) => void, prepend?: boolean): Request<D, E>;
|
314 | /**
|
315 | * Returns a 'thenable' promise.
|
316 | */
|
317 | promise(): Promise<PromiseResult<D, E>>
|
318 | /**
|
319 | * The time that the request started.
|
320 | */
|
321 | startTime: Date;
|
322 | /**
|
323 | * The raw HTTP request object containing request headers and body information sent by the service.
|
324 | */
|
325 | httpRequest: HttpRequest;
|
326 |
|
327 | }
|
328 |
|
329 | export type PromiseResult<D, E> = D & {$response: Response<D, E>};
|
330 |
|
331 | export interface Progress {
|
332 | loaded: number;
|
333 | total: number;
|
334 | }
|