1 | /// <reference types="node" />
|
2 | import PCancelable = require('p-cancelable');
|
3 | import Request, { Options, Response, RequestError, RequestEvents } from '../core';
|
4 | /**
|
5 | All parsing methods supported by Got.
|
6 | */
|
7 | export declare type ResponseType = 'json' | 'buffer' | 'text';
|
8 | export interface PaginationOptions<T, R> {
|
9 | /**
|
10 | All options accepted by `got.paginate()`.
|
11 | */
|
12 | pagination?: {
|
13 | /**
|
14 | A function that transform [`Response`](#response) into an array of items.
|
15 | This is where you should do the parsing.
|
16 |
|
17 | @default response => JSON.parse(response.body)
|
18 | */
|
19 | transform?: (response: Response<R>) => Promise<T[]> | T[];
|
20 | /**
|
21 | Checks whether the item should be emitted or not.
|
22 |
|
23 | @default (item, allItems, currentItems) => true
|
24 | */
|
25 | filter?: (item: T, allItems: T[], currentItems: T[]) => boolean;
|
26 | /**
|
27 | The function takes three arguments:
|
28 | - `response` - The current response object.
|
29 | - `allItems` - An array of the emitted items.
|
30 | - `currentItems` - Items from the current response.
|
31 |
|
32 | It should return an object representing Got options pointing to the next page.
|
33 | The options are merged automatically with the previous request, therefore the options returned `pagination.paginate(...)` must reflect changes only.
|
34 | If there are no more pages, `false` should be returned.
|
35 |
|
36 | @example
|
37 | ```
|
38 | const got = require('got');
|
39 |
|
40 | (async () => {
|
41 | const limit = 10;
|
42 |
|
43 | const items = got.paginate('https://example.com/items', {
|
44 | searchParams: {
|
45 | limit,
|
46 | offset: 0
|
47 | },
|
48 | pagination: {
|
49 | paginate: (response, allItems, currentItems) => {
|
50 | const previousSearchParams = response.request.options.searchParams;
|
51 | const previousOffset = previousSearchParams.get('offset');
|
52 |
|
53 | if (currentItems.length < limit) {
|
54 | return false;
|
55 | }
|
56 |
|
57 | return {
|
58 | searchParams: {
|
59 | ...previousSearchParams,
|
60 | offset: Number(previousOffset) + limit,
|
61 | }
|
62 | };
|
63 | }
|
64 | }
|
65 | });
|
66 |
|
67 | console.log('Items from all pages:', items);
|
68 | })();
|
69 | ```
|
70 | */
|
71 | paginate?: (response: Response<R>, allItems: T[], currentItems: T[]) => Options | false;
|
72 | /**
|
73 | Checks whether the pagination should continue.
|
74 |
|
75 | For example, if you need to stop **before** emitting an entry with some flag, you should use `(item, allItems, currentItems) => !item.flag`.
|
76 | If you want to stop **after** emitting the entry, you should use `(item, allItems, currentItems) => allItems.some(entry => entry.flag)` instead.
|
77 |
|
78 | @default (item, allItems, currentItems) => true
|
79 | */
|
80 | shouldContinue?: (item: T, allItems: T[], currentItems: T[]) => boolean;
|
81 | /**
|
82 | The maximum amount of items that should be emitted.
|
83 |
|
84 | @default Infinity
|
85 | */
|
86 | countLimit?: number;
|
87 | /**
|
88 | Milliseconds to wait before the next request is triggered.
|
89 |
|
90 | @default 0
|
91 | */
|
92 | backoff?: number;
|
93 | /**
|
94 | The maximum amount of request that should be triggered.
|
95 | Retries on failure are not counted towards this limit.
|
96 |
|
97 | For example, it can be helpful during development to avoid an infinite number of requests.
|
98 |
|
99 | @default 10000
|
100 | */
|
101 | requestLimit?: number;
|
102 | /**
|
103 | Defines how the parameter `allItems` in pagination.paginate, pagination.filter and pagination.shouldContinue is managed.
|
104 | When set to `false`, the parameter `allItems` is always an empty array.
|
105 |
|
106 | This option can be helpful to save on memory usage when working with a large dataset.
|
107 | */
|
108 | stackAllItems?: boolean;
|
109 | };
|
110 | }
|
111 | export declare type AfterResponseHook = (response: Response, retryWithMergedOptions: (options: Options) => CancelableRequest<Response>) => Response | CancelableRequest<Response> | Promise<Response | CancelableRequest<Response>>;
|
112 | export declare namespace PromiseOnly {
|
113 | interface Hooks {
|
114 | /**
|
115 | Called with [response object](#response) and a retry function.
|
116 | Calling the retry function will trigger `beforeRetry` hooks.
|
117 |
|
118 | Each function should return the response.
|
119 | This is especially useful when you want to refresh an access token.
|
120 |
|
121 | __Note__: When using streams, this hook is ignored.
|
122 |
|
123 | @example
|
124 | ```
|
125 | const got = require('got');
|
126 |
|
127 | const instance = got.extend({
|
128 | hooks: {
|
129 | afterResponse: [
|
130 | (response, retryWithMergedOptions) => {
|
131 | if (response.statusCode === 401) { // Unauthorized
|
132 | const updatedOptions = {
|
133 | headers: {
|
134 | token: getNewToken() // Refresh the access token
|
135 | }
|
136 | };
|
137 |
|
138 | // Save for further requests
|
139 | instance.defaults.options = got.mergeOptions(instance.defaults.options, updatedOptions);
|
140 |
|
141 | // Make a new retry
|
142 | return retryWithMergedOptions(updatedOptions);
|
143 | }
|
144 |
|
145 | // No changes otherwise
|
146 | return response;
|
147 | }
|
148 | ],
|
149 | beforeRetry: [
|
150 | (options, error, retryCount) => {
|
151 | // This will be called on `retryWithMergedOptions(...)`
|
152 | }
|
153 | ]
|
154 | },
|
155 | mutableDefaults: true
|
156 | });
|
157 | ```
|
158 | */
|
159 | afterResponse?: AfterResponseHook[];
|
160 | }
|
161 | interface Options extends PaginationOptions<unknown, unknown> {
|
162 | /**
|
163 | The parsing method.
|
164 |
|
165 | The promise also has `.text()`, `.json()` and `.buffer()` methods which return another Got promise for the parsed body.
|
166 |
|
167 | It's like setting the options to `{responseType: 'json', resolveBodyOnly: true}` but without affecting the main Got promise.
|
168 |
|
169 | __Note__: When using streams, this option is ignored.
|
170 |
|
171 | @example
|
172 | ```
|
173 | (async () => {
|
174 | const responsePromise = got(url);
|
175 | const bufferPromise = responsePromise.buffer();
|
176 | const jsonPromise = responsePromise.json();
|
177 |
|
178 | const [response, buffer, json] = Promise.all([responsePromise, bufferPromise, jsonPromise]);
|
179 | // `response` is an instance of Got Response
|
180 | // `buffer` is an instance of Buffer
|
181 | // `json` is an object
|
182 | })();
|
183 | ```
|
184 |
|
185 | @example
|
186 | ```
|
187 | // This
|
188 | const body = await got(url).json();
|
189 |
|
190 | // is semantically the same as this
|
191 | const body = await got(url, {responseType: 'json', resolveBodyOnly: true});
|
192 | ```
|
193 | */
|
194 | responseType?: ResponseType;
|
195 | /**
|
196 | When set to `true` the promise will return the Response body instead of the Response object.
|
197 |
|
198 | @default false
|
199 | */
|
200 | resolveBodyOnly?: boolean;
|
201 | /**
|
202 | Returns a `Stream` instead of a `Promise`.
|
203 | This is equivalent to calling `got.stream(url, options?)`.
|
204 |
|
205 | @default false
|
206 | */
|
207 | isStream?: boolean;
|
208 | /**
|
209 | [Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on `setEncoding` of the response data.
|
210 |
|
211 | To get a [`Buffer`](https://nodejs.org/api/buffer.html), you need to set `responseType` to `buffer` instead.
|
212 | Don't set this option to `null`.
|
213 |
|
214 | __Note__: This doesn't affect streams! Instead, you need to do `got.stream(...).setEncoding(encoding)`.
|
215 |
|
216 | @default 'utf-8'
|
217 | */
|
218 | encoding?: BufferEncoding;
|
219 | }
|
220 | interface NormalizedOptions {
|
221 | responseType: ResponseType;
|
222 | resolveBodyOnly: boolean;
|
223 | isStream: boolean;
|
224 | encoding?: BufferEncoding;
|
225 | pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
|
226 | }
|
227 | interface Defaults {
|
228 | responseType: ResponseType;
|
229 | resolveBodyOnly: boolean;
|
230 | isStream: boolean;
|
231 | pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
|
232 | }
|
233 | type HookEvent = 'afterResponse';
|
234 | }
|
235 | /**
|
236 | An error to be thrown when server response code is 2xx, and parsing body fails.
|
237 | Includes a `response` property.
|
238 | */
|
239 | export declare class ParseError extends RequestError {
|
240 | readonly response: Response;
|
241 | constructor(error: Error, response: Response);
|
242 | }
|
243 | /**
|
244 | An error to be thrown when the request is aborted with `.cancel()`.
|
245 | */
|
246 | export declare class CancelError extends RequestError {
|
247 | readonly response: Response;
|
248 | constructor(request: Request);
|
249 | get isCanceled(): boolean;
|
250 | }
|
251 | export interface CancelableRequest<T extends Response | Response['body'] = Response['body']> extends PCancelable<T>, RequestEvents<CancelableRequest<T>> {
|
252 | json: <ReturnType>() => CancelableRequest<ReturnType>;
|
253 | buffer: () => CancelableRequest<Buffer>;
|
254 | text: () => CancelableRequest<string>;
|
255 | }
|
256 | export * from '../core';
|