got 11.5.2 → 11.6.0

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,10 +86,60 @@ 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>;
 }
 export interface GotRequestFunction {
@@ -74,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, {
@@ -83,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;
+    /**
+    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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "got",
-	"version": "11.5.2",
+	"version": "11.6.0",
 	"description": "Human-friendly and powerful HTTP request library for Node.js",
 	"license": "MIT",
 	"repository": "sindresorhus/got",
@@ -43,14 +43,14 @@
 		"ky"
 	],
 	"dependencies": {
-		"@sindresorhus/is": "^3.0.0",
+		"@sindresorhus/is": "^3.1.1",
 		"@szmarczak/http-timer": "^4.0.5",
 		"@types/cacheable-request": "^6.0.1",
 		"@types/responselike": "^1.0.0",
 		"cacheable-lookup": "^5.0.3",
 		"cacheable-request": "^7.0.1",
 		"decompress-response": "^6.0.0",
-		"http2-wrapper": "^1.0.0-beta.5.0",
+		"http2-wrapper": "^1.0.0-beta.5.2",
 		"lowercase-keys": "^2.0.0",
 		"p-cancelable": "^2.0.0",
 		"responselike": "^2.0.0"
@@ -60,34 +60,38 @@
 		"@sindresorhus/tsconfig": "^0.7.0",
 		"@sinonjs/fake-timers": "^6.0.1",
 		"@types/benchmark": "^1.0.33",
-		"@types/express": "^4.17.6",
-		"@types/node": "^14.0.14",
+		"@types/express": "^4.17.7",
+		"@types/node": "^14.6.0",
 		"@types/node-fetch": "^2.5.7",
+		"@types/pem": "^1.9.5",
+		"@types/pify": "^3.0.2",
 		"@types/request": "^2.48.5",
-		"@types/sinon": "^9.0.4",
+		"@types/sinon": "^9.0.5",
 		"@types/tough-cookie": "^4.0.0",
-		"ava": "^3.10.0",
-		"axios": "^0.19.2",
+		"ava": "^3.11.1",
+		"axios": "^0.20.0",
 		"benchmark": "^2.1.4",
 		"coveralls": "^3.1.0",
 		"create-test-server": "^3.0.1",
 		"del-cli": "^3.0.1",
-		"delay": "^4.3.0",
+		"delay": "^4.4.0",
 		"express": "^4.17.1",
 		"form-data": "^3.0.0",
-		"get-stream": "^5.1.0",
-		"nock": "^13.0.2",
+		"get-stream": "^6.0.0",
+		"nock": "^13.0.4",
 		"node-fetch": "^2.6.0",
-		"np": "^6.3.0",
+		"np": "^6.4.0",
 		"nyc": "^15.1.0",
 		"p-event": "^4.2.0",
-		"sinon": "^9.0.2",
+		"pem": "^1.14.4",
+		"pify": "^5.0.0",
+		"sinon": "^9.0.3",
 		"slow-stream": "0.0.4",
-		"tempy": "^0.5.0",
+		"tempy": "^0.6.0",
 		"to-readable-stream": "^2.1.0",
 		"tough-cookie": "^4.0.0",
-		"typescript": "3.9.6",
-		"xo": "^0.32.1"
+		"typescript": "^4.0.2",
+		"xo": "^0.33.0"
 	},
 	"types": "dist/source",
 	"sideEffects": false,

package/readme.md

@@ -40,7 +40,7 @@ For browser usage, we recommend [Ky](https://github.com/sindresorhus/ky) by the
 - [Errors with metadata](#errors)
 - [JSON mode](#json-mode)
 - [WHATWG URL support](#url)
-- [HTTPS API](#https)
+- [HTTPS API](#advanced-https-api)
 - [Hooks](#hooks)
 - [Instances with custom defaults](#instances)
 - [Types](#types)
@@ -510,12 +510,10 @@ Default:
 
 An object representing `limit`, `calculateDelay`, `methods`, `statusCodes`, `maxRetryAfter` and `errorCodes` fields for maximum retry count, retry handler, allowed methods, allowed status codes, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time and allowed error codes.
 
-**Note:** When using streams, this option is ignored. If the connection is reset when downloading, you need to catch the error and clear the file you were writing into to prevent duplicated content.
-
 If `maxRetryAfter` is set to `undefined`, it will use `options.timeout`.\
 If [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header is greater than `maxRetryAfter`, it will cancel the request.
 
-Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.random() * 100`, where `retry` is attempt number (starts from 1).
+Delays between retries counts with function `1000 * Math.pow(2, retry - 1) + Math.random() * 100`, where `retry` is attempt number (starts from 1).
 
 The `calculateDelay` property is a `function` that receives an object with `attemptCount`, `retryOptions`, `error` and `computedValue` properties for current retry count, the retry options, error and default computed value. The function must return a delay in milliseconds (or a Promise resolving with it) (`0` return value cancels retry).
 
@@ -529,6 +527,36 @@ By default, it retries *only* on the specified methods, status codes, and on the
 - `ENETUNREACH`: No internet connection.
 - `EAI_AGAIN`: DNS lookup timed out.
 
+<a name="retry-stream"></a>
+
+You can retry Got streams too. The implementation looks like this:
+
+```js
+const got = require('got');
+const fs = require('fs');
+
+let writeStream;
+
+const fn = (retryCount = 0) => {
+	const stream = got.stream('https://example.com');
+	stream.retryCount = retryCount;
+
+	if (writeStream) {
+		writeStream.destroy();
+	}
+
+	writeStream = fs.createWriteStream('example.com');
+
+	stream.pipe(writeStream);
+
+	// If you don't attach the listener, it will NOT make a retry.
+	// It automatically checks the listener count so it knows whether to retry or not :)
+	stream.once('retry', fn);
+};
+
+fn();
+```
+
 ###### followRedirect
 
 Type: `boolean`\
@@ -579,6 +607,13 @@ Default: `false`
 
 [Cache adapter instance](#cache-adapters) for storing cached response data.
 
+###### cacheOptions
+
+Type: `object | undefined`\
+Default: `{}`
+
+[Cache options](https://github.com/kornelski/http-cache-semantics#constructor-options) used for the specified request.
+
 ###### dnsCache
 
 Type: `CacheableLookup | false`\
@@ -1250,6 +1285,13 @@ If the `content-length` header is missing, `total` will be `undefined`.
 })();
 ```
 
+##### .once('retry', retryCount, error)
+
+To enable retrying on a Got stream, it is required to have a `retry` handler attached.\
+When this event is emitted, you should reset the stream you were writing to and prepare the body again.
+
+See the [`retry`](#retry-stream) option for an example implementation.
+
 ##### .ip
 
 Type: `string`
@@ -1574,7 +1616,7 @@ Additionaly, the errors may have `request` (Got Stream) and `response` (Got Resp
 
 #### got.RequestError
 
-When a request fails. Contains a `code` property with error class code, like `ECONNREFUSED`. Note that all other types of errors listed below are subclasses of this one, with the exception of `CancelError`.
+When a request fails. Contains a `code` property with error class code, like `ECONNREFUSED`. All the errors below inherit this one.
 
 #### got.CacheError
 
@@ -1610,7 +1652,7 @@ When the request is aborted due to a [timeout](#timeout). Includes an `event` an
 
 #### got.CancelError
 
-When the request is aborted with `.cancel()`. This type is not a subclass of `RequestError` as it is re-exported from the `p-cancelable` package.
+When the request is aborted with `.cancel()`.
 
 ## Aborting the request
 
@@ -1889,6 +1931,32 @@ nock('https://sindresorhus.com')
 })();
 ```
 
+Bear in mind, that by default `nock` mocks only one request. Got will [retry](#retry) on failed requests by default, causing a `No match for request ...` error. The solution is to either disable retrying (set `options.retry` to `0`) or call `.persist()` on the mocked request.
+
+```js
+const got = require('got');
+const nock = require('nock');
+
+const scope = nock('https://sindresorhus.com')
+	.get('/')
+	.reply(500, 'Internal server error')
+	.persist();
+
+(async () => {
+	try {
+		await got('https://sindresorhus.com')
+	} catch (error) {
+		console.log(error.response.body);
+		//=> 'Internal server error'
+
+		console.log(error.response.retryCount);
+		//=> 2
+	}
+
+	scope.persist(false);
+})();
+```
+
 For real integration testing we recommend using [`ava`](https://github.com/avajs/ava) with [`create-test-server`](https://github.com/lukechilds/create-test-server). We're using a macro so we don't have to `server.listen()` and `server.close()` every test. Take a look at one of our tests:
 
 ```js
@@ -2046,7 +2114,7 @@ The Electron `net` module is not consistent with the Node.js `http` module. See
 \* It's almost API compatible with the browser `fetch` API.\
 \*\* Need to switch the protocol manually. Doesn't accept PUSH streams and doesn't reuse HTTP/2 sessions.\
 \*\*\* Currently, only `DownloadProgress` event is supported, `UploadProgress` event is not supported.\
-:sparkle: Almost-stable feature, but the API may change. Don't hestitate to try it out!\
+:sparkle: Almost-stable feature, but the API may change. Don't hesitate to try it out!\
 :grey_question: Feature in early stage of development. Very experimental.
 
 <!-- GITHUB -->

package/dist/source/as-promise/calculate-retry-delay.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const types_1 = require("./types");
-const retryAfterStatusCodes = new Set([413, 429, 503]);
-const isErrorWithResponse = (error) => (error instanceof types_1.HTTPError || error instanceof types_1.ParseError || error instanceof types_1.MaxRedirectsError);
-const calculateRetryDelay = ({ attemptCount, retryOptions, error }) => {
-    if (attemptCount > retryOptions.limit) {
-        return 0;
-    }
-    const hasMethod = retryOptions.methods.includes(error.options.method);
-    const hasErrorCode = retryOptions.errorCodes.includes(error.code);
-    const hasStatusCode = isErrorWithResponse(error) && retryOptions.statusCodes.includes(error.response.statusCode);
-    if (!hasMethod || (!hasErrorCode && !hasStatusCode)) {
-        return 0;
-    }
-    if (isErrorWithResponse(error)) {
-        const { response } = error;
-        if (response && 'retry-after' in response.headers && retryAfterStatusCodes.has(response.statusCode)) {
-            let after = Number(response.headers['retry-after']);
-            if (Number.isNaN(after)) {
-                after = Date.parse(response.headers['retry-after']) - Date.now();
-            }
-            else {
-                after *= 1000;
-            }
-            if (retryOptions.maxRetryAfter === undefined || after > retryOptions.maxRetryAfter) {
-                return 0;
-            }
-            return after;
-        }
-        if (response.statusCode === 413) {
-            return 0;
-        }
-    }
-    const noise = Math.random() * 100;
-    return ((2 ** (attemptCount - 1)) * 1000) + noise;
-};
-exports.default = calculateRetryDelay;

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

@@ -1,13 +0,0 @@
-/// <reference types="node" />
-import { URL } from 'url';
-import { Options, NormalizedOptions, Defaults, ResponseType, Response } from './types';
-import Request, { ParseJsonFunction } from '../core';
-export declare const knownBodyTypes: string[];
-export 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 class PromisableRequest extends Request {
-    ['constructor']: typeof PromisableRequest;
-    options: NormalizedOptions;
-    static normalizeArguments(url?: string | URL, nonNormalizedOptions?: Options, defaults?: Defaults): NormalizedOptions;
-    static mergeOptions(...sources: Options[]): NormalizedOptions;
-    _beforeError(error: Error): void;
-}