got 11.5.2 → 11.7.0

package/dist/source/as-promise/index.d.ts

@@ -1,5 +1,3 @@
 import { NormalizedOptions, CancelableRequest } from './types';
-import PromisableRequest from './core';
-export default function asPromise<T>(options: NormalizedOptions): CancelableRequest<T>;
+export default function asPromise<T>(normalizedOptions: NormalizedOptions): CancelableRequest<T>;
 export * from './types';
-export { PromisableRequest };

package/dist/source/as-promise/index.js

@@ -7,18 +7,18 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
     o[k2] = m[k];
 }));
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !exports.hasOwnProperty(p)) __createBinding(exports, m, p);
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PromisableRequest = void 0;
 const events_1 = require("events");
+const is_1 = require("@sindresorhus/is");
 const PCancelable = require("p-cancelable");
-const calculate_retry_delay_1 = require("./calculate-retry-delay");
 const types_1 = require("./types");
-const core_1 = require("./core");
-exports.PromisableRequest = core_1.default;
+const parse_body_1 = require("./parse-body");
+const core_1 = require("../core");
 const proxy_events_1 = require("../core/utils/proxy-events");
 const get_buffer_1 = require("../core/utils/get-buffer");
+const is_response_ok_1 = require("../core/utils/is-response-ok");
 const proxiedRequestEvents = [
     'request',
     'response',
@@ -26,53 +26,26 @@ const proxiedRequestEvents = [
     'uploadProgress',
     'downloadProgress'
 ];
-function asPromise(options) {
-    let retryCount = 0;
+function asPromise(normalizedOptions) {
     let globalRequest;
     let globalResponse;
     const emitter = new events_1.EventEmitter();
-    const promise = new PCancelable((resolve, _reject, onCancel) => {
-        const makeRequest = () => {
-            // Support retries
-            // `options.throwHttpErrors` needs to be always true,
-            // so the HTTP errors are caught and the request is retried.
-            // The error is **eventually** thrown if the user value is true.
-            const { throwHttpErrors } = options;
-            if (!throwHttpErrors) {
-                options.throwHttpErrors = true;
-            }
-            // Note from @szmarczak: I think we should use `request.options` instead of the local options
-            const request = new core_1.default(options.url, options);
+    const promise = new PCancelable((resolve, reject, onCancel) => {
+        const makeRequest = (retryCount) => {
+            const request = new core_1.default(undefined, normalizedOptions);
+            request.retryCount = retryCount;
             request._noPipe = true;
             onCancel(() => request.destroy());
-            const reject = (error) => {
-                void (async () => {
-                    try {
-                        for (const hook of options.hooks.beforeError) {
-                            // eslint-disable-next-line no-await-in-loop
-                            error = await hook(error);
-                        }
-                    }
-                    catch (error_) {
-                        _reject(new types_1.RequestError(error_.message, error_, request));
-                        return;
-                    }
-                    _reject(error);
-                })();
-            };
+            onCancel.shouldReject = false;
+            onCancel(() => reject(new types_1.CancelError(request)));
             globalRequest = request;
-            const onResponse = async (response) => {
+            request.once('response', async (response) => {
                 var _a;
                 response.retryCount = retryCount;
                 if (response.request.aborted) {
                     // Canceled while downloading - will throw a `CancelError` or `TimeoutError` error
                     return;
                 }
-                const isOk = () => {
-                    const { statusCode } = response;
-                    const limitStatusCode = options.followRedirect ? 299 : 399;
-                    return (statusCode >= 200 && statusCode <= limitStatusCode) || statusCode === 304;
-                };
                 // Download body
                 let rawBody;
                 try {
@@ -84,22 +57,25 @@ function asPromise(options) {
                     // See request.once('error')
                     return;
                 }
+                if (request._isAboutToError) {
+                    return;
+                }
                 // Parse body
                 const contentEncoding = ((_a = response.headers['content-encoding']) !== null && _a !== void 0 ? _a : '').toLowerCase();
                 const isCompressed = ['gzip', 'deflate', 'br'].includes(contentEncoding);
+                const { options } = request;
                 if (isCompressed && !options.decompress) {
                     response.body = rawBody;
                 }
                 else {
                     try {
-                        response.body = core_1.parseBody(response, options.responseType, options.parseJson, options.encoding);
+                        response.body = parse_body_1.default(response, options.responseType, options.parseJson, options.encoding);
                     }
                     catch (error) {
                         // Fallback to `utf8`
                         response.body = rawBody.toString();
-                        if (isOk()) {
-                            // TODO: Call `request._beforeError`, see https://github.com/nodejs/node/issues/32995
-                            reject(error);
+                        if (is_response_ok_1.isResponseOk(response)) {
+                            request._beforeError(error);
                             return;
                         }
                     }
@@ -134,99 +110,40 @@ function asPromise(options) {
                     }
                 }
                 catch (error) {
-                    // TODO: Call `request._beforeError`, see https://github.com/nodejs/node/issues/32995
-                    reject(new types_1.RequestError(error.message, error, request));
+                    request._beforeError(new types_1.RequestError(error.message, error, request));
                     return;
                 }
-                if (throwHttpErrors && !isOk()) {
-                    reject(new types_1.HTTPError(response));
+                if (!is_response_ok_1.isResponseOk(response)) {
+                    request._beforeError(new types_1.HTTPError(response));
                     return;
                 }
                 globalResponse = response;
-                resolve(options.resolveBodyOnly ? response.body : response);
-            };
-            const onError = async (error) => {
+                resolve(request.options.resolveBodyOnly ? response.body : response);
+            });
+            const onError = (error) => {
                 if (promise.isCanceled) {
                     return;
                 }
-                if (!request.options) {
-                    reject(error);
-                    return;
-                }
-                request.off('response', onResponse);
-                let gotUnexpectedError = false;
-                const onUnexpectedError = (error) => {
-                    gotUnexpectedError = true;
-                    reject(error);
-                };
-                // If this is an HTTP error, then it can throw again with `ECONNRESET` or `Parse Error`
-                request.once('error', onUnexpectedError);
-                let backoff;
-                retryCount++;
-                try {
-                    backoff = await options.retry.calculateDelay({
-                        attemptCount: retryCount,
-                        retryOptions: options.retry,
-                        error,
-                        computedValue: calculate_retry_delay_1.default({
-                            attemptCount: retryCount,
-                            retryOptions: options.retry,
-                            error,
-                            computedValue: 0
-                        })
-                    });
-                }
-                catch (error_) {
-                    // Don't emit the `response` event
-                    request.destroy();
-                    reject(new types_1.RequestError(error_.message, error, request));
-                    return;
-                }
-                // Another error was thrown already
-                if (gotUnexpectedError) {
+                const { options } = request;
+                if (error instanceof types_1.HTTPError && !options.throwHttpErrors) {
+                    const { response } = error;
+                    resolve(request.options.resolveBodyOnly ? response.body : response);
                     return;
                 }
-                request.off('error', onUnexpectedError);
-                if (backoff) {
-                    // Don't emit the `response` event
-                    request.destroy();
-                    const retry = async () => {
-                        options.throwHttpErrors = throwHttpErrors;
-                        try {
-                            for (const hook of options.hooks.beforeRetry) {
-                                // eslint-disable-next-line no-await-in-loop
-                                await hook(options, error, retryCount);
-                            }
-                        }
-                        catch (error_) {
-                            // Don't emit the `response` event
-                            request.destroy();
-                            reject(new types_1.RequestError(error_.message, error, request));
-                            return;
-                        }
-                        makeRequest();
-                    };
-                    setTimeout(retry, backoff);
-                    return;
-                }
-                // The retry has not been made
-                retryCount--;
-                if (error instanceof types_1.HTTPError) {
-                    // The error will be handled by the `response` event
-                    void onResponse(request._response);
-                    // Reattach the error handler, because there may be a timeout later.
-                    request.once('error', onError);
-                    return;
-                }
-                // Don't emit the `response` event
-                request.destroy();
                 reject(error);
             };
-            request.once('response', onResponse);
             request.once('error', onError);
+            request.once('retry', (newRetryCount, error) => {
+                var _a;
+                if (is_1.default.nodeStream((_a = error.request) === null || _a === void 0 ? void 0 : _a.options.body)) {
+                    onError(error);
+                    return;
+                }
+                makeRequest(newRetryCount);
+            });
             proxy_events_1.default(request, emitter, proxiedRequestEvents);
         };
-        makeRequest();
+        makeRequest(0);
     });
     promise.on = (event, fn) => {
         emitter.on(event, fn);
@@ -236,14 +153,16 @@ function asPromise(options) {
         const newPromise = (async () => {
             // Wait until downloading has ended
             await promise;
-            return core_1.parseBody(globalResponse, responseType, options.parseJson, options.encoding);
+            const { options } = globalResponse.request;
+            return parse_body_1.default(globalResponse, responseType, options.parseJson, options.encoding);
         })();
         Object.defineProperties(newPromise, Object.getOwnPropertyDescriptors(promise));
         return newPromise;
     };
     promise.json = () => {
-        if (!globalRequest.writableFinished && options.headers.accept === undefined) {
-            options.headers.accept = 'application/json';
+        const { headers } = globalRequest.options;
+        if (!globalRequest.writableFinished && headers.accept === undefined) {
+            headers.accept = 'application/json';
         }
         return shortcut('json');
     };

package/dist/source/as-promise/normalize-arguments.d.ts

@@ -0,0 +1,3 @@
+import { NormalizedOptions, Defaults } from './types';
+declare const normalizeArguments: (options: NormalizedOptions, defaults?: Defaults | undefined) => NormalizedOptions;
+export default normalizeArguments;

package/dist/source/as-promise/normalize-arguments.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const is_1 = require("@sindresorhus/is");
+const normalizeArguments = (options, defaults) => {
+    if (is_1.default.null_(options.encoding)) {
+        throw new TypeError('To get a Buffer, set `options.responseType` to `buffer` instead');
+    }
+    is_1.assert.any([is_1.default.string, is_1.default.undefined], options.encoding);
+    is_1.assert.any([is_1.default.boolean, is_1.default.undefined], options.resolveBodyOnly);
+    is_1.assert.any([is_1.default.boolean, is_1.default.undefined], options.methodRewriting);
+    is_1.assert.any([is_1.default.boolean, is_1.default.undefined], options.isStream);
+    is_1.assert.any([is_1.default.string, is_1.default.undefined], options.responseType);
+    // `options.responseType`
+    if (options.responseType === undefined) {
+        options.responseType = 'text';
+    }
+    // `options.retry`
+    const { retry } = options;
+    if (defaults) {
+        options.retry = { ...defaults.retry };
+    }
+    else {
+        options.retry = {
+            calculateDelay: retryObject => retryObject.computedValue,
+            limit: 0,
+            methods: [],
+            statusCodes: [],
+            errorCodes: [],
+            maxRetryAfter: undefined
+        };
+    }
+    if (is_1.default.object(retry)) {
+        options.retry = {
+            ...options.retry,
+            ...retry
+        };
+        options.retry.methods = [...new Set(options.retry.methods.map(method => method.toUpperCase()))];
+        options.retry.statusCodes = [...new Set(options.retry.statusCodes)];
+        options.retry.errorCodes = [...new Set(options.retry.errorCodes)];
+    }
+    else if (is_1.default.number(retry)) {
+        options.retry.limit = retry;
+    }
+    if (is_1.default.undefined(options.retry.maxRetryAfter)) {
+        options.retry.maxRetryAfter = Math.min(
+        // TypeScript is not smart enough to handle `.filter(x => is.number(x))`.
+        // eslint-disable-next-line unicorn/no-fn-reference-in-iterator
+        ...[options.timeout.request, options.timeout.connect].filter(is_1.default.number));
+    }
+    // `options.pagination`
+    if (is_1.default.object(options.pagination)) {
+        if (defaults) {
+            options.pagination = {
+                ...defaults.pagination,
+                ...options.pagination
+            };
+        }
+        const { pagination } = options;
+        if (!is_1.default.function_(pagination.transform)) {
+            throw new Error('`options.pagination.transform` must be implemented');
+        }
+        if (!is_1.default.function_(pagination.shouldContinue)) {
+            throw new Error('`options.pagination.shouldContinue` must be implemented');
+        }
+        if (!is_1.default.function_(pagination.filter)) {
+            throw new TypeError('`options.pagination.filter` must be implemented');
+        }
+        if (!is_1.default.function_(pagination.paginate)) {
+            throw new Error('`options.pagination.paginate` must be implemented');
+        }
+    }
+    // JSON mode
+    if (options.responseType === 'json' && options.headers.accept === undefined) {
+        options.headers.accept = 'application/json';
+    }
+    return options;
+};
+exports.default = normalizeArguments;

package/dist/source/as-promise/parse-body.d.ts

@@ -0,0 +1,3 @@
+import { ResponseType, Response, ParseJsonFunction } from './types';
+declare const parseBody: (response: Response, responseType: ResponseType, parseJson: ParseJsonFunction, encoding?: "ascii" | "utf8" | "utf-8" | "utf16le" | "ucs2" | "ucs-2" | "base64" | "latin1" | "binary" | "hex" | undefined) => unknown;
+export default parseBody;

package/dist/source/as-promise/parse-body.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const types_1 = require("./types");
+const parseBody = (response, responseType, parseJson, encoding) => {
+    const { rawBody } = response;
+    try {
+        if (responseType === 'text') {
+            return rawBody.toString(encoding);
+        }
+        if (responseType === 'json') {
+            return rawBody.length === 0 ? '' : parseJson(rawBody.toString());
+        }
+        if (responseType === 'buffer') {
+            return rawBody;
+        }
+        throw new types_1.ParseError({
+            message: `Unknown body type '${responseType}'`,
+            name: 'Error'
+        }, response);
+    }
+    catch (error) {
+        throw new types_1.ParseError(error, response);
+    }
+};
+exports.default = parseBody;

package/dist/source/as-promise/types.d.ts

@@ -1,53 +1,225 @@
 /// <reference types="node" />
 import PCancelable = require('p-cancelable');
-import { CancelError } from 'p-cancelable';
-import { NormalizedOptions, Options, Response, Method, TimeoutError, RequestError, RequestEvents } from '../core';
+import Request, { Options, Response, RequestError, RequestEvents } from '../core';
+/**
+All parsing methods supported by Got.
+*/
 export declare type ResponseType = 'json' | 'buffer' | 'text';
-export interface RetryObject {
-    attemptCount: number;
-    retryOptions: RequiredRetryOptions;
-    error: TimeoutError | RequestError;
-    computedValue: number;
-}
-export declare type RetryFunction = (retryObject: RetryObject) => number | Promise<number>;
-export interface RequiredRetryOptions {
-    limit: number;
-    methods: Method[];
-    statusCodes: number[];
-    errorCodes: string[];
-    calculateDelay: RetryFunction;
-    maxRetryAfter?: number;
-}
 export interface PaginationOptions<T, R> {
+    /**
+    All options accepted by `got.paginate()`.
+    */
     pagination?: {
+        /**
+        A function that transform [`Response`](#response) into an array of items.
+        This is where you should do the parsing.
+
+        @default response => JSON.parse(response.body)
+        */
         transform?: (response: Response<R>) => Promise<T[]> | T[];
+        /**
+        Checks whether the item should be emitted or not.
+
+        @default (item, allItems, currentItems) => true
+        */
         filter?: (item: T, allItems: T[], currentItems: T[]) => boolean;
+        /**
+        The function takes three arguments:
+        - `response` - The current response object.
+        - `allItems` - An array of the emitted items.
+        - `currentItems` - Items from the current response.
+
+        It should return an object representing Got options pointing to the next page.
+        The options are merged automatically with the previous request, therefore the options returned `pagination.paginate(...)` must reflect changes only.
+        If there are no more pages, `false` should be returned.
+
+        @example
+        ```
+        const got = require('got');
+
+        (async () => {
+            const limit = 10;
+
+            const items = got.paginate('https://example.com/items', {
+                searchParams: {
+                    limit,
+                    offset: 0
+                },
+                pagination: {
+                    paginate: (response, allItems, currentItems) => {
+                        const previousSearchParams = response.request.options.searchParams;
+                        const previousOffset = previousSearchParams.get('offset');
+
+                        if (currentItems.length < limit) {
+                            return false;
+                        }
+
+                        return {
+                            searchParams: {
+                                ...previousSearchParams,
+                                offset: Number(previousOffset) + limit,
+                            }
+                        };
+                    }
+                }
+            });
+
+            console.log('Items from all pages:', items);
+        })();
+        ```
+        */
         paginate?: (response: Response<R>, allItems: T[], currentItems: T[]) => Options | false;
+        /**
+        Checks whether the pagination should continue.
+
+        For example, if you need to stop **before** emitting an entry with some flag, you should use `(item, allItems, currentItems) => !item.flag`.
+        If you want to stop **after** emitting the entry, you should use `(item, allItems, currentItems) => allItems.some(entry => entry.flag)` instead.
+
+        @default (item, allItems, currentItems) => true
+        */
         shouldContinue?: (item: T, allItems: T[], currentItems: T[]) => boolean;
+        /**
+        The maximum amount of items that should be emitted.
+
+        @default Infinity
+        */
         countLimit?: number;
+        /**
+        Milliseconds to wait before the next request is triggered.
+
+        @default 0
+        */
         backoff?: number;
+        /**
+        The maximum amount of request that should be triggered.
+        Retries on failure are not counted towards this limit.
+
+        For example, it can be helpful during development to avoid an infinite number of requests.
+
+        @default 10000
+        */
         requestLimit?: number;
+        /**
+        Defines how the parameter `allItems` in pagination.paginate, pagination.filter and pagination.shouldContinue is managed.
+        When set to `false`, the parameter `allItems` is always an empty array.
+
+        This option can be helpful to save on memory usage when working with a large dataset.
+        */
         stackAllItems?: boolean;
     };
 }
-export declare type BeforeRetryHook = (options: NormalizedOptions, error?: RequestError, retryCount?: number) => void | Promise<void>;
 export declare type AfterResponseHook = (response: Response, retryWithMergedOptions: (options: Options) => CancelableRequest<Response>) => Response | CancelableRequest<Response> | Promise<Response | CancelableRequest<Response>>;
 export declare namespace PromiseOnly {
     interface Hooks {
-        beforeRetry?: BeforeRetryHook[];
+        /**
+        Called with [response object](#response) and a retry function.
+        Calling the retry function will trigger `beforeRetry` hooks.
+
+        Each function should return the response.
+        This is especially useful when you want to refresh an access token.
+
+        __Note__: When using streams, this hook is ignored.
+
+        @example
+        ```
+        const got = require('got');
+
+        const instance = got.extend({
+            hooks: {
+                afterResponse: [
+                    (response, retryWithMergedOptions) => {
+                        if (response.statusCode === 401) { // Unauthorized
+                            const updatedOptions = {
+                                headers: {
+                                    token: getNewToken() // Refresh the access token
+                                }
+                            };
+
+                            // Save for further requests
+                            instance.defaults.options = got.mergeOptions(instance.defaults.options, updatedOptions);
+
+                            // Make a new retry
+                            return retryWithMergedOptions(updatedOptions);
+                        }
+
+                        // No changes otherwise
+                        return response;
+                    }
+                ],
+                beforeRetry: [
+                    (options, error, retryCount) => {
+                        // This will be called on `retryWithMergedOptions(...)`
+                    }
+                ]
+            },
+            mutableDefaults: true
+        });
+        ```
+        */
         afterResponse?: AfterResponseHook[];
     }
     interface Options extends PaginationOptions<unknown, unknown> {
+        /**
+        The parsing method.
+
+        The promise also has `.text()`, `.json()` and `.buffer()` methods which return another Got promise for the parsed body.
+
+        It's like setting the options to `{responseType: 'json', resolveBodyOnly: true}` but without affecting the main Got promise.
+
+        __Note__: When using streams, this option is ignored.
+
+        @example
+        ```
+        (async () => {
+            const responsePromise = got(url);
+            const bufferPromise = responsePromise.buffer();
+            const jsonPromise = responsePromise.json();
+
+            const [response, buffer, json] = Promise.all([responsePromise, bufferPromise, jsonPromise]);
+            // `response` is an instance of Got Response
+            // `buffer` is an instance of Buffer
+            // `json` is an object
+        })();
+        ```
+
+        @example
+        ```
+        // This
+        const body = await got(url).json();
+
+        // is semantically the same as this
+        const body = await got(url, {responseType: 'json', resolveBodyOnly: true});
+        ```
+        */
         responseType?: ResponseType;
+        /**
+        When set to `true` the promise will return the Response body instead of the Response object.
+
+        @default false
+        */
         resolveBodyOnly?: boolean;
-        retry?: Partial<RequiredRetryOptions> | number;
+        /**
+        Returns a `Stream` instead of a `Promise`.
+        This is equivalent to calling `got.stream(url, options?)`.
+
+        @default false
+        */
         isStream?: boolean;
+        /**
+        [Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on `setEncoding` of the response data.
+
+        To get a [`Buffer`](https://nodejs.org/api/buffer.html), you need to set `responseType` to `buffer` instead.
+        Don't set this option to `null`.
+
+        __Note__: This doesn't affect streams! Instead, you need to do `got.stream(...).setEncoding(encoding)`.
+
+        @default 'utf-8'
+        */
         encoding?: BufferEncoding;
     }
     interface NormalizedOptions {
         responseType: ResponseType;
         resolveBodyOnly: boolean;
-        retry: RequiredRetryOptions;
         isStream: boolean;
         encoding?: BufferEncoding;
         pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
@@ -55,20 +227,30 @@ export declare namespace PromiseOnly {
     interface Defaults {
         responseType: ResponseType;
         resolveBodyOnly: boolean;
-        retry: RequiredRetryOptions;
         isStream: boolean;
         pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
     }
-    type HookEvent = 'beforeRetry' | 'afterResponse';
+    type HookEvent = 'afterResponse';
 }
+/**
+An error to be thrown when server response code is 2xx, and parsing body fails.
+Includes a `response` property.
+*/
 export declare class ParseError extends RequestError {
     readonly response: Response;
     constructor(error: Error, response: Response);
 }
+/**
+An error to be thrown when the request is aborted with `.cancel()`.
+*/
+export declare class CancelError extends RequestError {
+    readonly response: Response;
+    constructor(request: Request);
+    get isCanceled(): boolean;
+}
 export interface CancelableRequest<T extends Response | Response['body'] = Response['body']> extends PCancelable<T>, RequestEvents<CancelableRequest<T>> {
     json: <ReturnType>() => CancelableRequest<ReturnType>;
     buffer: () => CancelableRequest<Buffer>;
     text: () => CancelableRequest<string>;
 }
-export { CancelError };
 export * from '../core';