got 12.0.0-beta.1 → 12.0.0

package/dist/source/core/options.d.ts

@@ -1,13 +1,16 @@
 /// <reference types="node" />
-import { URL, URLSearchParams } from 'url';
-import { request as httpsRequest } from 'https';
-import type { Readable } from 'stream';
-import type { Socket } from 'net';
-import type { SecureContextOptions, DetailedPeerCertificate } from 'tls';
-import type { Agent as HttpAgent, ClientRequest } from 'http';
-import type { RequestOptions as HttpsRequestOptions, Agent as HttpsAgent } from 'https';
+import { Buffer } from 'node:buffer';
+import { URL, URLSearchParams } from 'node:url';
+import { checkServerIdentity } from 'node:tls';
+import { request as httpsRequest } from 'node:https';
+import type { Readable } from 'node:stream';
+import type { Socket } from 'node:net';
+import type { SecureContextOptions, DetailedPeerCertificate } from 'node:tls';
+import type { Agent as HttpAgent, ClientRequest } from 'node:http';
+import type { RequestOptions as HttpsRequestOptions, Agent as HttpsAgent } from 'node:https';
 import CacheableLookup from 'cacheable-lookup';
 import http2wrapper, { ClientHttp2Session } from 'http2-wrapper';
+import type { FormDataLike } from 'form-data-encoder';
 import type CacheableRequest from 'cacheable-request';
 import type ResponseLike from 'responselike';
 import type { IncomingMessageWithTimings } from '@szmarczak/http-timer';
@@ -49,39 +52,146 @@ All available hooks of Got.
 */
 export interface Hooks {
     /**
-    Called with plain request options, right before their normalization.
+    Called with the plain request options, right before their normalization.
+
+    The second argument represents the current `Options` instance.
+
+    @default []
+
+    **Note:**
+    > - This hook must be synchronous.
+
+    **Note:**
+    > - This is called every time options are merged.
+
+    **Note:**
+    > - The `options` object may not have the `url` property. To modify it, use a `beforeRequest` hook instead.
+
+    **Note:**
+    > - This hook is called when a new instance of `Options` is created.
+    > - Do not confuse this with the creation of `Request` or `got(…)`.
+
+    **Note:**
+    > - When using `got(url)` or `got(url, undefined, defaults)` this hook will **not** be called.
+
     This is especially useful in conjunction with `got.extend()` when the input needs custom handling.
 
-    __Note #1__: This hook must be synchronous!
+    For example, this can be used to fix typos to migrate from older versions faster.
 
-    __Note #2__: Errors in this hook will be converted into an instances of `RequestError`.
+    @example
+    ```
+    import got from 'got';
 
-    __Note #3__: The options object may not have a `url` property.
-    To modify it, use a `beforeRequest` hook instead.
+    const instance = got.extend({
+        hooks: {
+            init: [
+                plain => {
+                    if ('followRedirects' in plain) {
+                        plain.followRedirect = plain.followRedirects;
+                        delete plain.followRedirects;
+                    }
+                }
+            ]
+        }
+    });
 
-    @default []
+    // Normally, the following would throw:
+    const response = await instance(
+        'https://example.com',
+        {
+            followRedirects: true
+        }
+    );
+
+    // There is no option named `followRedirects`, but we correct it in an `init` hook.
+    ```
+
+    Or you can create your own option and store it in a context:
+
+    ```
+    import got from 'got';
+
+    const instance = got.extend({
+        hooks: {
+            init: [
+                (plain, options) => {
+                    if ('secret' in plain) {
+                        options.context.secret = plain.secret;
+                        delete plain.secret;
+                    }
+                }
+            ],
+            beforeRequest: [
+                options => {
+                    options.headers.secret = options.context.secret;
+                }
+            ]
+        }
+    });
+
+    const {headers} = await instance(
+        'https://httpbin.org/anything',
+        {
+            secret: 'passphrase'
+        }
+    ).json();
+
+    console.log(headers.Secret);
+    //=> 'passphrase'
+    ```
     */
     init: InitHook[];
     /**
-    Called with normalized request options.
-    Got will make no further changes to the request before it is sent.
-    This is especially useful in conjunction with `got.extend()` when you want to create an API client that, for example, uses HMAC-signing.
+    Called right before making the request with `options.createNativeRequestOptions()`.
+
+    This hook is especially useful in conjunction with `got.extend()` when you want to sign your request.
 
     @default []
+
+    **Note:**
+    > - Got will make no further changes to the request before it is sent.
+
+    **Note:**
+    > - Changing `options.json` or `options.form` has no effect on the request. You should change `options.body` instead. If needed, update the `options.headers` accordingly.
+
+    @example
+    ```
+    import got from 'got';
+
+    const response = await got.post(
+        'https://httpbin.org/anything',
+        {
+            json: {payload: 'old'},
+            hooks: {
+                beforeRequest: [
+                    options => {
+                        options.body = JSON.stringify({payload: 'new'});
+                        options.headers['content-length'] = options.body.length.toString();
+                    }
+                ]
+            }
+        }
+    );
+    ```
+
+    **Tip:**
+    > - You can indirectly override the `request` function by early returning a [`ClientRequest`-like](https://nodejs.org/api/http.html#http_class_http_clientrequest) instance or a [`IncomingMessage`-like](https://nodejs.org/api/http.html#http_class_http_incomingmessage) instance. This is very useful when creating a custom cache mechanism.
+    > - [Read more about this tip](https://github.com/sindresorhus/got/blob/main/documentation/cache.md#advanced-caching-mechanisms).
     */
     beforeRequest: BeforeRequestHook[];
     /**
-    Called with normalized request options and the redirect response.
-    Got will make no further changes to the request.
-    This is especially useful when you want to avoid dead sites.
+    The equivalent of `beforeRequest` but when redirecting.
 
     @default []
 
+    **Tip:**
+    > - This is especially useful when you want to avoid dead sites.
+
     @example
     ```
     import got from 'got';
 
-    await got('https://example.com', {
+    const response = await got('https://example.com', {
         hooks: {
             beforeRedirect: [
                 (options, response) => {
@@ -96,19 +206,17 @@ export interface Hooks {
     */
     beforeRedirect: BeforeRedirectHook[];
     /**
-    Called with an `Error` instance.
-    The error is passed to the hook right before it's thrown.
-    This is especially useful when you want to have more detailed errors.
+    Called with a `RequestError` instance. The error is passed to the hook right before it's thrown.
 
-    __Note__: Errors thrown while normalizing input options are thrown directly and not part of this hook.
+    This is especially useful when you want to have more detailed errors.
 
     @default []
 
-    @example
     ```
     import got from 'got';
 
-    await got('https://api.github.com/some-endpoint', {
+    await got('https://api.github.com/repos/sindresorhus/got/commits', {
+        responseType: 'json',
         hooks: {
             beforeError: [
                 error => {
@@ -127,26 +235,31 @@ export interface Hooks {
     */
     beforeError: BeforeErrorHook[];
     /**
-    Called with normalized request options, the error and the retry count.
-  Got will make no further changes to the request.
-    This is especially useful when some extra work is required before the next try.
-
-    __Note__: When using streams, this hook is ignored.
-    __Note__: When retrying in a `afterResponse` hook, all remaining `beforeRetry` hooks will be called without the `error` and `retryCount` arguments.
+    The equivalent of `beforeError` but when retrying. Additionally, there is a second argument `retryCount`, the current retry number.
 
     @default []
 
+    **Note:**
+    > - When using the Stream API, this hook is ignored.
+
+    **Note:**
+    > - When retrying, the `beforeRequest` hook is called afterwards.
+
+    **Note:**
+    > - If no retry occurs, the `beforeError` hook is called instead.
+
+    This hook is especially useful when you want to retrieve the cause of a retry.
+
     @example
     ```
     import got from 'got';
 
-    got.post('https://example.com', {
+    await got('https://httpbin.org/status/500', {
         hooks: {
             beforeRetry: [
-                (options, error, retryCount) => {
-                    if (error.response.statusCode === 413) { // Payload too large
-                        options.body = getNewBody();
-                    }
+                (error, retryCount) => {
+                    console.log(`Retrying [${retryCount}]: ${error.code}`);
+                    // Retrying [1]: ERR_NON_2XX_3XX_RESPONSE
                 }
             ]
         }
@@ -155,13 +268,16 @@ export 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.
 
-    Each function should return the response.
-    This is especially useful when you want to refresh an access token.
+    @default []
 
-    __Note__: When using streams, this hook is ignored.
+    **Note:**
+    > - When using the Stream API, this hook is ignored.
+
+    **Note:**
+    > - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. If the retry is successful, all remaining `afterResponse` hooks will be called. In case of an error, `beforeRetry` hooks will be called instead.
+    Meanwhile the `init`, `beforeRequest` , `beforeRedirect` as well as already executed `afterResponse` hooks will be skipped.
 
     @example
     ```
@@ -171,15 +287,17 @@ export interface Hooks {
         hooks: {
             afterResponse: [
                 (response, retryWithMergedOptions) => {
-                    if (response.statusCode === 401) { // Unauthorized
+                    // Unauthorized
+                    if (response.statusCode === 401) {
+                        // Refresh the access token
                         const updatedOptions = {
                             headers: {
-                                token: getNewToken() // Refresh the access token
+                                token: getNewToken()
                             }
                         };
 
-                        // Save for further requests
-                        instance.defaults.options = got.mergeOptions(instance.defaults.options, updatedOptions);
+                        // Update the defaults
+                        instance.defaults.options.merge(updatedOptions);
 
                         // Make a new retry
                         return retryWithMergedOptions(updatedOptions);
@@ -190,7 +308,7 @@ export interface Hooks {
                 }
             ],
             beforeRetry: [
-                (options, error, retryCount) => {
+                error => {
                     // This will be called on `retryWithMergedOptions(...)`
                 }
             ]
@@ -247,8 +365,8 @@ export interface RetryOptions {
     noise: number;
     maxRetryAfter?: number;
 }
-export declare type CreateConnectionFunction = (options: NativeRequestOptions, oncreate: (error: Error, socket: Socket) => void) => Socket;
-export declare type CheckServerIdentityFunction = (hostname: string, certificate: DetailedPeerCertificate) => Error | void;
+export declare type CreateConnectionFunction = (options: NativeRequestOptions, oncreate: (error: NodeJS.ErrnoException, socket: Socket) => void) => Socket;
+export declare type CheckServerIdentityFunction = (hostname: string, certificate: DetailedPeerCertificate) => NodeJS.ErrnoException | void;
 export interface CacheOptions {
     shared?: boolean;
     cacheHeuristic?: number;
@@ -354,13 +472,13 @@ export interface PaginationOptions<ElementType, BodyType> {
     const limit = 10;
 
     const items = got.paginate('https://example.com/items', {
-        searchParameters: {
+        searchParams: {
             limit,
             offset: 0
         },
         pagination: {
             paginate: ({response, currentItems}) => {
-                const previousSearchParams = response.request.options.searchParameters;
+                const previousSearchParams = response.request.options.searchParams;
                 const previousOffset = previousSearchParams.get('offset');
 
                 if (currentItems.length < limit) {
@@ -368,7 +486,7 @@ export interface PaginationOptions<ElementType, BodyType> {
                 }
 
                 return {
-                    searchParameters: {
+                    searchParams: {
                         ...previousSearchParams,
                         offset: Number(previousOffset) + limit,
                     }
@@ -443,7 +561,7 @@ export default class Options {
     private _internals;
     private _merging;
     private readonly _init;
-    constructor(input?: string | URL | OptionsInit, options?: OptionsInit, defaults?: Options | OptionsInit);
+    constructor(input?: string | URL | OptionsInit, options?: OptionsInit, defaults?: Options);
     merge(options?: OptionsInit | Options): void;
     /**
     Custom request function.
@@ -558,12 +676,12 @@ export default class Options {
 
     __Note #4__: This option is not enumerable and will not be merged with the instance defaults.
 
-    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
+    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
 
     Since Got 12, the `content-length` is not automatically set when `body` is a `fs.createReadStream`.
     */
-    get body(): string | Buffer | Readable | Generator | AsyncGenerator | undefined;
-    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | undefined);
+    get body(): string | Buffer | Readable | Generator | AsyncGenerator | FormDataLike | undefined;
+    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | FormDataLike | undefined);
     /**
     The form body is converted to a query string using [`(new URLSearchParams(object)).toString()`](https://nodejs.org/api/url.html#url_constructor_new_urlsearchparams_obj).
 
@@ -596,10 +714,10 @@ export default class Options {
     @example
     ```
     await got('https://example.com/?query=a b'); //=> https://example.com/?query=a%20b
-    await got('https://example.com/', {searchParameters: {query: 'a b'}}); //=> https://example.com/?query=a+b
+    await got('https://example.com/', {searchParams: {query: 'a b'}}); //=> https://example.com/?query=a+b
 
-    // The query string is overridden by `searchParameters`
-    await got('https://example.com/?query=a b', {searchParameters: {query: 'a b'}}); //=> https://example.com/?query=a+b
+    // The query string is overridden by `searchParams`
+    await got('https://example.com/?query=a b', {searchParams: {query: 'a b'}}); //=> https://example.com/?query=a+b
     ```
     */
     get url(): string | URL | undefined;
@@ -629,11 +747,11 @@ export default class Options {
     ```
     import got from 'got';
 
-    const searchParameters = new URLSearchParams([['key', 'a'], ['key', 'b']]);
+    const searchParams = new URLSearchParams([['key', 'a'], ['key', 'b']]);
 
-    await got('https://example.com', {searchParameters});
+    await got('https://example.com', {searchParams});
 
-    console.log(searchParameters.toString());
+    console.log(searchParams.toString());
     //=> 'key=a&key=b'
     ```
     */
@@ -981,25 +1099,27 @@ export default class Options {
         headers: Headers;
         timeout: Delays;
         request: RequestFunction | undefined;
+        username: string;
+        password: string;
         json: Record<string, any> | undefined;
         retry: Partial<RetryOptions>;
         agent: Agents;
         h2session: http2wrapper.ClientHttp2Session | undefined;
         decompress: boolean;
         prefixUrl: string | URL;
-        body: string | Readable | Buffer | Generator<unknown, any, unknown> | AsyncGenerator<unknown, any, unknown> | undefined;
+        body: string | Readable | Buffer | Generator<unknown, any, unknown> | AsyncGenerator<unknown, any, unknown> | FormDataLike | undefined;
         form: Record<string, any> | undefined;
         url: string | URL | undefined;
         cookieJar: PromiseCookieJar | ToughCookieJar | undefined;
         ignoreInvalidCookies: boolean;
         searchParams: string | SearchParameters | URLSearchParams | undefined;
         dnsLookup: {
-            (hostname: string, family: import("cacheable-lookup").IPFamily, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
-            (hostname: string, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            (hostname: string, family: import("cacheable-lookup").IPFamily, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            (hostname: string, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
             (hostname: string, options: import("cacheable-lookup").LookupOptions & {
                 all: true;
-            }, callback: (error: NodeJS.ErrnoException, result: readonly import("cacheable-lookup").EntryObject[]) => void): void;
-            (hostname: string, options: import("cacheable-lookup").LookupOptions, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            }, callback: (error: NodeJS.ErrnoException | null, result: readonly import("cacheable-lookup").EntryObject[]) => void): void;
+            (hostname: string, options: import("cacheable-lookup").LookupOptions, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
         } | undefined;
         dnsCache: boolean | CacheableLookup | undefined;
         context: Record<string, unknown>;
@@ -1008,8 +1128,6 @@ export default class Options {
         maxRedirects: number;
         cache: string | boolean | CacheableRequest.StorageAdapter | undefined;
         throwHttpErrors: boolean;
-        username: string;
-        password: string;
         http2: boolean;
         allowGetBody: boolean;
         methodRewriting: boolean;
@@ -1030,13 +1148,14 @@ export default class Options {
         maxHeaderSize: number | undefined;
     };
     createNativeRequestOptions(): {
+        ALPNProtocols: string[] | undefined;
         ca: string | Buffer | (string | Buffer)[] | undefined;
         cert: string | Buffer | (string | Buffer)[] | undefined;
         key: string | Buffer | (Buffer | import("tls").KeyObject)[] | undefined;
         passphrase: string | undefined;
         pfx: PfxType;
         rejectUnauthorized: boolean | undefined;
-        checkServerIdentity: CheckServerIdentityFunction;
+        checkServerIdentity: CheckServerIdentityFunction | typeof checkServerIdentity;
         ciphers: string | undefined;
         honorCipherOrder: boolean | undefined;
         minVersion: import("tls").SecureVersion | undefined;
@@ -1047,12 +1166,12 @@ export default class Options {
         ecdhCurve: string | undefined;
         crl: string | Buffer | (string | Buffer)[] | undefined;
         lookup: {
-            (hostname: string, family: import("cacheable-lookup").IPFamily, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
-            (hostname: string, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            (hostname: string, family: import("cacheable-lookup").IPFamily, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            (hostname: string, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
             (hostname: string, options: import("cacheable-lookup").LookupOptions & {
                 all: true;
-            }, callback: (error: NodeJS.ErrnoException, result: readonly import("cacheable-lookup").EntryObject[]) => void): void;
-            (hostname: string, options: import("cacheable-lookup").LookupOptions, callback: (error: NodeJS.ErrnoException, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
+            }, callback: (error: NodeJS.ErrnoException | null, result: readonly import("cacheable-lookup").EntryObject[]) => void): void;
+            (hostname: string, options: import("cacheable-lookup").LookupOptions, callback: (error: NodeJS.ErrnoException | null, address: string, family: import("cacheable-lookup").IPFamily) => void): void;
         } | undefined;
         family: DnsLookupIpVersion;
         agent: false | Agents | HttpAgent | undefined;
@@ -1064,6 +1183,7 @@ export default class Options {
         createConnection: CreateConnectionFunction | undefined;
         timeout: number | undefined;
         h2session: http2wrapper.ClientHttp2Session | undefined;
+        signal?: AbortSignal | undefined;
         protocol?: string | null | undefined;
         host?: string | null | undefined;
         hostname?: string | null | undefined;
@@ -1086,8 +1206,8 @@ export default class Options {
         immutableMinTimeToLive?: number | undefined;
         ignoreCargoCult?: boolean | undefined;
     };
-    getRequestFunction(): RequestFunction | typeof httpsRequest;
-    getFallbackRequestFunction(): RequestFunction | typeof httpsRequest;
+    getRequestFunction(): RequestFunction | typeof httpsRequest | undefined;
+    getFallbackRequestFunction(): RequestFunction | typeof httpsRequest | undefined;
     freeze(): void;
 }
 export {};