got 11.4.0 → 11.6.0

package/dist/source/core/utils/dns-ip-version.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.dnsLookupIpVersionToFamily = exports.isDnsLookupIpVersion = void 0;
 const conversionTable = {
     auto: 0,
     ipv4: 4,

package/dist/source/core/utils/get-body-size.d.ts

@@ -1,5 +1,3 @@
-/// <reference path="timed-out.d.ts" />
-/// <reference types="node" />
-/// <reference types="node/http" />
-declare const _default: (body: unknown, headers: import("http").OutgoingHttpHeaders | undefined) => Promise<number | undefined>;
+import { ClientRequestArgs } from 'http';
+declare const _default: (body: unknown, headers: ClientRequestArgs['headers']) => Promise<number | undefined>;
 export default _default;

package/dist/source/core/utils/is-form-data.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="node" />
 import { Readable } from 'stream';
 interface FormData extends Readable {
-    getBoundary(): string;
-    getLength(callback: (error: Error | null, length: number) => void): void;
+    getBoundary: () => string;
+    getLength: (callback: (error: Error | null, length: number) => void) => void;
 }
 declare const _default: (body: unknown) => body is FormData;
 export default _default;

package/dist/source/core/utils/is-response-ok.d.ts

@@ -0,0 +1,2 @@
+import { Response } from '..';
+export declare const isResponseOk: (response: Response) => boolean;

package/dist/source/core/utils/is-response-ok.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isResponseOk = void 0;
+exports.isResponseOk = (response) => {
+    const { statusCode } = response;
+    const limitStatusCode = response.request.options.followRedirect ? 299 : 399;
+    return (statusCode >= 200 && statusCode <= limitStatusCode) || statusCode === 304;
+};

package/dist/source/core/utils/options-to-url.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { URL } from 'url';
 export interface URLOptions {
     href?: string;

package/dist/source/core/utils/timed-out.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = void 0;
 const net = require("net");
 const unhandle_1 = require("./unhandle");
 const reentry = Symbol('reentry');

package/dist/source/core/utils/url-to-options.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import { URL, UrlWithStringQuery } from 'url';
 export interface LegacyUrlOptions {
     protocol: string;

package/dist/source/core/utils/weakable-map.d.ts

@@ -1,5 +1,5 @@
 export default class WeakableMap<K, V> {
-    weakMap: WeakMap<object, V>;
+    weakMap: WeakMap<Record<string, unknown>, V>;
     map: Map<K, V>;
     constructor();
     set(key: K, value: V): void;

package/dist/source/create.js

@@ -1,6 +1,16 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-const p_cancelable_1 = require("p-cancelable");
+exports.defaultHandler = void 0;
 const is_1 = require("@sindresorhus/is");
 const as_promise_1 = require("./as-promise");
 const create_rejection_1 = require("./as-promise/create-rejection");
@@ -14,12 +24,23 @@ const errors = {
     MaxRedirectsError: as_promise_1.MaxRedirectsError,
     TimeoutError: as_promise_1.TimeoutError,
     ParseError: as_promise_1.ParseError,
-    CancelError: p_cancelable_1.CancelError,
+    CancelError: as_promise_1.CancelError,
     UnsupportedProtocolError: as_promise_1.UnsupportedProtocolError,
     UploadError: as_promise_1.UploadError
 };
-const { normalizeArguments, mergeOptions } = as_promise_1.PromisableRequest;
-const getPromiseOrStream = (options) => options.isStream ? new core_1.default(options.url, options) : as_promise_1.default(options);
+// The `delay` package weighs 10KB (!)
+const delay = async (ms) => new Promise(resolve => {
+    setTimeout(resolve, ms);
+});
+const { normalizeArguments } = core_1.default;
+const mergeOptions = (...sources) => {
+    let mergedOptions;
+    for (const source of sources) {
+        mergedOptions = normalizeArguments(undefined, source, mergedOptions);
+    }
+    return mergedOptions;
+};
+const getPromiseOrStream = (options) => options.isStream ? new core_1.default(undefined, options) : as_promise_1.default(options);
 const isGotInstance = (value) => ('defaults' in value && 'options' in value.defaults);
 const aliases = [
     'get',
@@ -61,13 +82,13 @@ const create = (defaults) => {
         return result;
     }));
     // Got interface
-    const got = ((url, options) => {
+    const got = ((url, options, _defaults) => {
         var _a, _b;
         let iteration = 0;
         const iterateHandlers = (newOptions) => {
             return defaults.handlers[iteration++](newOptions, iteration === defaults.handlers.length ? getPromiseOrStream : iterateHandlers);
         };
-        // TODO: remove this in Got 12
+        // TODO: Remove this in Got 12.
         if (is_1.default.plainObject(url)) {
             const mergedOptions = {
                 ...url,
@@ -88,7 +109,7 @@ const create = (defaults) => {
                 initHookError = error;
             }
             // Normalize options & call handlers
-            const normalizedOptions = normalizeArguments(url, options, defaults.options);
+            const normalizedOptions = normalizeArguments(url, options, _defaults !== null && _defaults !== void 0 ? _defaults : defaults.options);
             normalizedOptions[core_1.kIsNormalizedAlready] = true;
             if (initHookError) {
                 throw new as_promise_1.RequestError(initHookError.message, initHookError, normalizedOptions);
@@ -134,6 +155,9 @@ const create = (defaults) => {
     };
     // Pagination
     const paginateEach = (async function* (url, options) {
+        // TODO: Remove this `@ts-expect-error` when upgrading to TypeScript 4.
+        // Error: Argument of type 'Merge<Options, PaginationOptions<T, R>> | undefined' is not assignable to parameter of type 'Options | undefined'.
+        // @ts-expect-error
         let normalizedOptions = normalizeArguments(url, options, defaults.options);
         normalizedOptions.resolveBodyOnly = false;
         const pagination = normalizedOptions.pagination;
@@ -144,9 +168,14 @@ const create = (defaults) => {
         let { countLimit } = pagination;
         let numberOfRequests = 0;
         while (numberOfRequests < pagination.requestLimit) {
+            if (numberOfRequests !== 0) {
+                // eslint-disable-next-line no-await-in-loop
+                await delay(pagination.backoff);
+            }
+            // @ts-expect-error FIXME!
             // TODO: Throw when result is not an instance of Response
             // eslint-disable-next-line no-await-in-loop
-            const result = (await got(normalizedOptions));
+            const result = (await got(undefined, undefined, normalizedOptions));
             // eslint-disable-next-line no-await-in-loop
             const parsed = await pagination.transform(result);
             const current = [];
@@ -178,12 +207,10 @@ const create = (defaults) => {
             numberOfRequests++;
         }
     });
-    got.paginate = ((url, options) => {
-        return paginateEach(url, options);
-    });
+    got.paginate = paginateEach;
     got.paginate.all = (async (url, options) => {
         const results = [];
-        for await (const item of got.paginate(url, options)) {
+        for await (const item of paginateEach(url, options)) {
             results.push(item);
         }
         return results;
@@ -199,13 +226,15 @@ const create = (defaults) => {
             return got(url, { ...options, method, isStream: true });
         });
     }
-    Object.assign(got, { ...errors, mergeOptions });
+    Object.assign(got, errors);
     Object.defineProperty(got, 'defaults', {
         value: defaults.mutableDefaults ? defaults : deep_freeze_1.default(defaults),
         writable: defaults.mutableDefaults,
         configurable: defaults.mutableDefaults,
         enumerable: true
     });
+    got.mergeOptions = mergeOptions;
     return got;
 };
 exports.default = create;
+__exportStar(require("./types"), exports);

package/dist/source/index.js

@@ -1,7 +1,14 @@
 "use strict";
-function __export(m) {
-    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
-}
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const url_1 = require("url");
 const create_1 = require("./create");
@@ -104,11 +111,13 @@ const defaults = {
             filter: () => true,
             shouldContinue: () => true,
             countLimit: Infinity,
+            backoff: 0,
             requestLimit: 10000,
             stackAllItems: true
         },
         parseJson: (text) => JSON.parse(text),
-        stringifyJson: (object) => JSON.stringify(object)
+        stringifyJson: (object) => JSON.stringify(object),
+        cacheOptions: {}
     },
     handlers: [create_1.defaultHandler],
     mutableDefaults: false
@@ -118,5 +127,6 @@ exports.default = got;
 // For CommonJS default export support
 module.exports = got;
 module.exports.default = got;
-__export(require("./create"));
-__export(require("./as-promise"));
+module.exports.__esModule = true; // Workaround for TS issue: https://github.com/sindresorhus/got/pull/1267
+__exportStar(require("./create"), exports);
+__exportStar(require("./as-promise"), exports);

package/dist/source/types.d.ts

@@ -1,20 +1,62 @@
 /// <reference types="node" />
 import { URL } from 'url';
 import { CancelError } from 'p-cancelable';
-import { CancelableRequest, Response, Options, NormalizedOptions, Defaults as DefaultOptions, PaginationOptions, ParseError, RequestError, CacheError, ReadError, HTTPError, MaxRedirectsError, TimeoutError } from './as-promise';
+import { CancelableRequest, Response, Options, NormalizedOptions, Defaults as DefaultOptions, PaginationOptions, ParseError, RequestError, CacheError, ReadError, HTTPError, MaxRedirectsError, TimeoutError, UnsupportedProtocolError, UploadError } from './as-promise';
 import Request from './core';
 declare type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;
 declare type Merge<FirstType, SecondType> = Except<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;
+/**
+Defaults for each Got instance.
+*/
 export interface InstanceDefaults {
+    /**
+  An object containing the default options of Got.
+    */
     options: DefaultOptions;
+    /**
+    An array of functions. You execute them directly by calling `got()`.
+    They are some sort of "global hooks" - these functions are called first.
+    The last handler (*it's hidden*) is either `asPromise` or `asStream`, depending on the `options.isStream` property.
+
+    @default []
+    */
     handlers: HandlerFunction[];
+    /**
+    A read-only boolean describing whether the defaults are mutable or not.
+    If set to `true`, you can update headers over time, for example, update an access token when it expires.
+
+    @default false
+    */
     mutableDefaults: boolean;
     _rawHandlers?: HandlerFunction[];
 }
+/**
+A Request object returned by calling Got, or any of the Got HTTP alias request functions.
+*/
 export declare type GotReturn = Request | CancelableRequest;
+/**
+A function to handle options and returns a Request object.
+It acts sort of like a "global hook", and will be called before any actual request is made.
+*/
 export declare type HandlerFunction = <T extends GotReturn>(options: NormalizedOptions, next: (options: NormalizedOptions) => T) => T | Promise<T>;
+/**
+The options available for `got.extend()`.
+*/
 export interface ExtendOptions extends Options {
+    /**
+    An array of functions. You execute them directly by calling `got()`.
+    They are some sort of "global hooks" - these functions are called first.
+    The last handler (*it's hidden*) is either `asPromise` or `asStream`, depending on the `options.isStream` property.
+
+    @default []
+    */
     handlers?: HandlerFunction[];
+    /**
+    A read-only boolean describing whether the defaults are mutable or not.
+    If set to `true`, you can update headers over time, for example, update an access token when it expires.
+
+    @default false
+    */
     mutableDefaults?: boolean;
 }
 export declare type OptionsOfTextResponseBody = Merge<Options, {
@@ -44,13 +86,61 @@ declare type ResponseBodyOnly = {
     resolveBodyOnly: true;
 };
 export declare type OptionsWithPagination<T = unknown, R = unknown> = Merge<Options, PaginationOptions<T, R>>;
+/**
+An instance of `got.paginate`.
+*/
 export interface GotPaginate {
+    /**
+    Returns an async iterator.
+
+    See pagination.options for more pagination options.
+
+    @example
+    ```
+    (async () => {
+        const countLimit = 10;
+
+        const pagination = got.paginate('https://api.github.com/repos/sindresorhus/got/commits', {
+            pagination: {countLimit}
+        });
+
+        console.log(`Printing latest ${countLimit} Got commits (newest to oldest):`);
+
+        for await (const commitData of pagination) {
+            console.log(commitData.commit.message);
+        }
+    })();
+    ```
+    */
+    each: (<T, R = unknown>(url: string | URL, options?: OptionsWithPagination<T, R>) => AsyncIterableIterator<T>) & (<T, R = unknown>(options?: OptionsWithPagination<T, R>) => AsyncIterableIterator<T>);
+    /**
+    Returns a Promise for an array of all results.
+
+    See pagination.options for more pagination options.
+
+    @example
+    ```
+    (async () => {
+        const countLimit = 10;
+
+        const results = await got.paginate.all('https://api.github.com/repos/sindresorhus/got/commits', {
+            pagination: {countLimit}
+        });
+
+        console.log(`Printing latest ${countLimit} Got commits (newest to oldest):`);
+        console.log(results);
+    })();
+    ```
+    */
+    all: (<T, R = unknown>(url: string | URL, options?: OptionsWithPagination<T, R>) => Promise<T[]>) & (<T, R = unknown>(options?: OptionsWithPagination<T, R>) => Promise<T[]>);
+    /**
+    Same as `GotPaginate.each`.
+    */
     <T, R = unknown>(url: string | URL, options?: OptionsWithPagination<T, R>): AsyncIterableIterator<T>;
+    /**
+    Same as `GotPaginate.each`.
+    */
     <T, R = unknown>(options?: OptionsWithPagination<T, R>): AsyncIterableIterator<T>;
-    each<T, R = unknown>(url: string | URL, options?: OptionsWithPagination<T, R>): AsyncIterableIterator<T>;
-    each<T, R = unknown>(options?: OptionsWithPagination<T, R>): AsyncIterableIterator<T>;
-    all<T, R = unknown>(url: string | URL, options?: OptionsWithPagination<T, R>): Promise<T[]>;
-    all<T, R = unknown>(options?: OptionsWithPagination<T, R>): Promise<T[]>;
 }
 export interface GotRequestFunction {
     (url: string | URL, options?: OptionsOfTextResponseBody): CancelableRequest<Response<string>>;
@@ -76,6 +166,9 @@ export interface GotRequestFunction {
     (url: string | URL, options?: Options): CancelableRequest | Request;
     (options: Options): CancelableRequest | Request;
 }
+/**
+All available HTTP request methods provided by Got.
+*/
 export declare type HTTPAlias = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';
 interface GotStreamFunction {
     (url: string | URL, options?: Merge<Options, {
@@ -85,21 +178,165 @@ interface GotStreamFunction {
         isStream?: true;
     }>): Request;
 }
+/**
+An instance of `got.stream()`.
+*/
 export declare type GotStream = GotStreamFunction & Record<HTTPAlias, GotStreamFunction>;
+/**
+An instance of `got`.
+*/
 export interface Got extends Record<HTTPAlias, GotRequestFunction>, GotRequestFunction {
+    /**
+    Sets `options.isStream` to `true`.
+
+    Returns a [duplex stream](https://nodejs.org/api/stream.html#stream_class_stream_duplex) with additional events:
+    - request
+    - response
+    - redirect
+    - uploadProgress
+    - downloadProgress
+    - error
+    */
     stream: GotStream;
+    /**
+    Returns an async iterator.
+
+    See pagination.options for more pagination options.
+
+    @example
+    ```
+    (async () => {
+        const countLimit = 10;
+
+        const pagination = got.paginate('https://api.github.com/repos/sindresorhus/got/commits', {
+            pagination: {countLimit}
+        });
+
+        console.log(`Printing latest ${countLimit} Got commits (newest to oldest):`);
+
+        for await (const commitData of pagination) {
+            console.log(commitData.commit.message);
+        }
+    })();
+    ```
+    */
     paginate: GotPaginate;
+    /**
+    The Got defaults used in that instance.
+    */
     defaults: InstanceDefaults;
+    /**
+    An error to be thrown when a cache method fails.
+    For example, if the database goes down or there's a filesystem error.
+    */
     CacheError: typeof CacheError;
+    /**
+    An error to be thrown when a request fails.
+    Contains a `code` property with error class code, like `ECONNREFUSED`.
+    */
     RequestError: typeof RequestError;
+    /**
+    An error to be thrown when reading from response stream fails.
+    */
     ReadError: typeof ReadError;
+    /**
+    An error to be thrown when server response code is 2xx, and parsing body fails.
+    Includes a `response` property.
+    */
     ParseError: typeof ParseError;
+    /**
+    An error to be thrown when the server response code is not 2xx nor 3xx if `options.followRedirect` is `true`, but always except for 304.
+    Includes a `response` property.
+    */
     HTTPError: typeof HTTPError;
+    /**
+    An error to be thrown when the server redirects you more than ten times.
+    Includes a `response` property.
+    */
     MaxRedirectsError: typeof MaxRedirectsError;
+    /**
+    An error to be thrown when given an unsupported protocol.
+    */
+    UnsupportedProtocolError: typeof UnsupportedProtocolError;
+    /**
+    An error to be thrown when the request is aborted due to a timeout.
+    Includes an `event` and `timings` property.
+    */
     TimeoutError: typeof TimeoutError;
+    /**
+    An error to be thrown when the request body is a stream and an error occurs while reading from that stream.
+    */
+    UploadError: typeof UploadError;
+    /**
+    An error to be thrown when the request is aborted with `.cancel()`.
+    */
     CancelError: typeof CancelError;
-    extend(...instancesOrOptions: Array<Got | ExtendOptions>): Got;
-    mergeInstances(parent: Got, ...instances: Got[]): Got;
-    mergeOptions(...sources: Options[]): NormalizedOptions;
+    /**
+    Configure a new `got` instance with default `options`.
+    The `options` are merged with the parent instance's `defaults.options` using `got.mergeOptions`.
+    You can access the resolved options with the `.defaults` property on the instance.
+
+    Additionally, `got.extend()` accepts two properties from the `defaults` object: `mutableDefaults` and `handlers`.
+
+    It is also possible to merges many instances into a single one:
+    - options are merged using `got.mergeOptions()` (including hooks),
+    - handlers are stored in an array (you can access them through `instance.defaults.handlers`).
+
+    @example
+    ```js
+    const client = got.extend({
+        prefixUrl: 'https://example.com',
+        headers: {
+            'x-unicorn': 'rainbow'
+        }
+    });
+
+    client.get('demo');
+
+    // HTTP Request =>
+    // GET /demo HTTP/1.1
+    // Host: example.com
+    // x-unicorn: rainbow
+    ```
+    */
+    extend: (...instancesOrOptions: Array<Got | ExtendOptions>) => Got;
+    /**
+    Merges multiple `got` instances into the parent.
+    */
+    mergeInstances: (parent: Got, ...instances: Got[]) => Got;
+    /**
+    Extends parent options.
+    Avoid using [object spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax#Spread_in_object_literals) as it doesn't work recursively.
+
+    Options are deeply merged to a new object. The value of each key is determined as follows:
+
+    - If the new property is not defined, the old value is used.
+    - If the new property is explicitly set to `undefined`:
+        - If the parent property is a plain `object`, the parent value is deeply cloned.
+        - Otherwise, `undefined` is used.
+    - If the parent value is an instance of `URLSearchParams`:
+        - If the new value is a `string`, an `object` or an instance of `URLSearchParams`, a new `URLSearchParams` instance is created.
+            The values are merged using [`urlSearchParams.append(key, value)`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/append).
+            The keys defined in the new value override the keys defined in the parent value.
+        - Otherwise, the only available value is `undefined`.
+    - If the new property is a plain `object`:
+        - If the parent property is a plain `object` too, both values are merged recursively into a new `object`.
+        - Otherwise, only the new value is deeply cloned.
+    - If the new property is an `Array`, it overwrites the old one with a deep clone of the new property.
+    - Properties that are not enumerable, such as `context`, `body`, `json`, and `form`, will not be merged.
+    - Otherwise, the new value is assigned to the key.
+
+    **Note:** Only Got options are merged! Custom user options should be defined via [`options.context`](#context).
+
+    @example
+    ```
+    const a = {headers: {cat: 'meow', wolf: ['bark', 'wrrr']}};
+    const b = {headers: {cow: 'moo', wolf: ['auuu']}};
+
+    {...a, ...b}            // => {headers: {cow: 'moo', wolf: ['auuu']}}
+    got.mergeOptions(a, b)  // => {headers: {cat: 'meow', cow: 'moo', wolf: ['auuu']}}
+    ```
+    */
+    mergeOptions: (...sources: Options[]) => NormalizedOptions;
 }
 export {};

package/dist/source/utils/deep-freeze.d.ts

@@ -1 +1 @@
-export default function deepFreeze<T extends object>(object: T): Readonly<T>;
+export default function deepFreeze<T extends Record<string, any>>(object: T): Readonly<T>;

package/dist/source/utils/deprecation-warning.js

@@ -6,7 +6,7 @@ exports.default = (message) => {
         return;
     }
     alreadyWarned.add(message);
-    // @ts-ignore Missing types.
+    // @ts-expect-error Missing types.
     process.emitWarning(`Got: ${message}`, {
         type: 'DeprecationWarning'
     });