got 14.5.0 → 14.6.1

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

@@ -39,11 +39,37 @@ export type PromiseCookieJar = {
     getCookieString: (url: string) => Promise<string>;
     setCookie: (rawCookie: string, url: string) => Promise<unknown>;
 };
+/**
+Utility type to override specific properties in a type.
+
+Uses `Omit` to remove properties before adding them back to ensure proper type replacement rather than intersection, which handles edge cases with optional/required properties correctly.
+*/
+type OverrideProperties<T, U> = Omit<T, keyof U> & U;
+/**
+Represents the runtime state of Options as seen by hooks after normalization.
+
+Some Options properties accept multiple input types but are normalized to a single type internally by the Options class setters. This type reflects the actual runtime types that hooks receive, ensuring type safety when accessing options within hook functions.
+*/
+export type NormalizedOptions = OverrideProperties<Options, {
+    url: URL | undefined;
+    dnsCache: CacheableLookup | undefined;
+    cache: StorageAdapter | undefined;
+    prefixUrl: string;
+}>;
 export type InitHook = (init: OptionsInit, self: Options) => void;
-export type BeforeRequestHook = (options: Options) => Promisable<void | Response | ResponseLike>;
-export type BeforeRedirectHook = (updatedOptions: Options, plainResponse: PlainResponse) => Promisable<void>;
-export type BeforeErrorHook = (error: RequestError) => Promisable<RequestError>;
+export type BeforeRequestHookContext = {
+    /**
+    The current retry count.
+
+    It will be `0` for the initial request and increment for each retry.
+    */
+    retryCount: number;
+};
+export type BeforeRequestHook = (options: NormalizedOptions, context: BeforeRequestHookContext) => Promisable<void | Response | ResponseLike>;
+export type BeforeRedirectHook = (updatedOptions: NormalizedOptions, plainResponse: PlainResponse) => Promisable<void>;
+export type BeforeErrorHook = (error: RequestError) => Promisable<Error>;
 export type BeforeRetryHook = (error: RequestError, retryCount: number) => Promisable<void>;
+export type BeforeCacheHook = (response: PlainResponse) => false | void;
 export type AfterResponseHook<ResponseType = unknown> = (response: Response<ResponseType>, retryWithMergedOptions: (options: OptionsInit) => never) => Promisable<Response | CancelableRequest<Response>>;
 /**
 All available hooks of Got.
@@ -142,6 +168,8 @@ export type Hooks = {
     /**
     Called right before making the request with `options.createNativeRequestOptions()`.
 
+    The second argument is a context object containing request state information.
+
     This hook is especially useful in conjunction with `got.extend()` when you want to sign your request.
 
     @default []
@@ -162,7 +190,7 @@ export type Hooks = {
             json: {payload: 'old'},
             hooks: {
                 beforeRequest: [
-                    options => {
+                    (options, context) => {
                         options.body = JSON.stringify({payload: 'new'});
                         options.headers['content-length'] = options.body.length.toString();
                     }
@@ -172,6 +200,28 @@ export type Hooks = {
     );
     ```
 
+    **Example using `context.retryCount`:**
+
+    ```
+    import got from 'got';
+
+    await got('https://httpbin.org/status/500', {
+        retry: {
+            limit: 2
+        },
+        hooks: {
+            beforeRequest: [
+                (options, context) => {
+                    // Only log on the initial request, not on retries
+                    if (context.retryCount === 0) {
+                        console.log('Making initial request');
+                    }
+                }
+            ]
+        }
+    });
+    ```
+
     **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).
@@ -206,13 +256,20 @@ export type Hooks = {
     /**
     Called with a `RequestError` 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.
+    This hook can return any `Error` instance, allowing you to:
+    - Return custom error classes for better error handling in your application
+    - Extend `RequestError` with additional properties
+    - Return plain `Error` instances when you don't need Got-specific error information
+
+    This is especially useful when you want to have more detailed errors or maintain backward compatibility with existing error handling code.
 
     @default []
 
+    @example
     ```
     import got from 'got';
 
+    // Modify and return the error
     await got('https://api.github.com/repos/sindresorhus/got/commits', {
         responseType: 'json',
         hooks: {
@@ -229,6 +286,29 @@ export type Hooks = {
             ]
         }
     });
+
+    // Return a custom error class
+    class CustomAPIError extends Error {
+        constructor(message, statusCode) {
+            super(message);
+            this.name = 'CustomAPIError';
+            this.statusCode = statusCode;
+        }
+    }
+
+    await got('https://api.example.com/endpoint', {
+        hooks: {
+            beforeError: [
+                error => {
+                    // Return a custom error for backward compatibility with your application
+                    return new CustomAPIError(
+                        error.message,
+                        error.response?.statusCode
+                    );
+                }
+            ]
+        }
+    });
     ```
     */
     beforeError: BeforeErrorHook[];
@@ -266,6 +346,72 @@ export type Hooks = {
     */
     beforeRetry: BeforeRetryHook[];
     /**
+    Called right before the response is cached. Allows you to control caching behavior by directly modifying the response or preventing caching.
+
+    This is especially useful when you want to prevent caching of specific responses or modify cache headers.
+
+    @default []
+
+    **Return value:**
+    > - `false` - Prevent caching (remaining hooks are skipped)
+    > - `void`/`undefined` - Use default caching behavior (mutations take effect)
+
+    **Modifying the response:**
+    > - Hooks can directly mutate response properties like `headers`, `statusCode`, and `statusMessage`
+    > - Mutations to `response.headers` affect how the caching layer decides whether to cache the response and for how long
+    > - Changes are applied to what gets cached
+
+    **Note:**
+    > - This hook is only called when the `cache` option is enabled.
+
+    **Note:**
+    > - This hook must be synchronous. It cannot return a Promise. If you need async logic to determine caching behavior, use a `beforeRequest` hook instead.
+
+    **Note:**
+    > - When returning `false`, remaining hooks are skipped and the response will not be cached.
+
+    **Note:**
+    > - Returning anything other than `false` or `undefined` will throw a TypeError.
+
+    **Note:**
+    > - If a hook throws an error, it will be propagated and the request will fail. This is consistent with how other hooks in Got handle errors.
+
+    **Note:**
+    > - At this stage, the response body has not been read yet - it's still a stream. Properties like `response.body` and `response.rawBody` are not available. You can only inspect/modify response headers and status code.
+
+    @example
+    ```
+    import got from 'got';
+
+    // Simple: Don't cache errors
+    const instance = got.extend({
+        cache: new Map(),
+        hooks: {
+            beforeCache: [
+                (response) => response.statusCode >= 400 ? false : undefined
+            ]
+        }
+    });
+
+    // Advanced: Modify headers for fine control
+    const instance2 = got.extend({
+        cache: new Map(),
+        hooks: {
+            beforeCache: [
+                (response) => {
+                    // Force caching with explicit duration
+                    // Mutations work directly - no need to return
+                    response.headers['cache-control'] = 'public, max-age=3600';
+                }
+            ]
+        }
+    });
+
+    await instance('https://example.com');
+    ```
+    */
+    beforeCache: BeforeCacheHook[];
+    /**
     Each function should return the response. This is especially useful when you want to refresh an access token.
 
     @default []
@@ -487,6 +633,27 @@ export type HttpsOptions = {
     dhparam?: SecureContextOptions['dhparam'];
     ecdhCurve?: SecureContextOptions['ecdhCurve'];
     certificateRevocationLists?: SecureContextOptions['crl'];
+    /**
+    Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all!
+
+    The value is a numeric bitmask of the `SSL_OP_*` options from OpenSSL.
+
+    For example, to allow connections to legacy servers that do not support secure renegotiation, you can use `crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT`.
+
+    @example
+    ```
+    import crypto from 'node:crypto';
+    import got from 'got';
+
+    // Allow connections to servers with legacy renegotiation
+    await got('https://legacy-server.com', {
+        https: {
+            secureOptions: crypto.constants.SSL_OP_LEGACY_SERVER_CONNECT
+        }
+    });
+    ```
+    */
+    secureOptions?: number;
 };
 export type PaginateData<BodyType, ElementType> = {
     response: Response<BodyType>;
@@ -735,7 +902,7 @@ 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` / [`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`.
+    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / typed array ([`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), etc.) / [`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`.
 
@@ -756,8 +923,8 @@ export default class Options {
     });
     ```
     */
-    get body(): string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | undefined;
-    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | undefined);
+    get body(): string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | undefined;
+    set body(value: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | 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).
 
@@ -770,7 +937,9 @@ export default class Options {
     get form(): Record<string, any> | undefined;
     set form(value: Record<string, any> | undefined);
     /**
-    JSON body. If the `Content-Type` header is not set, it will be set to `application/json`.
+    JSON request body. If the `content-type` header is not set, it will be set to `application/json`.
+
+    __Important__: This option only affects the request body you send to the server. To parse the response as JSON, you must either call `.json()` on the promise or set `responseType: 'json'` in the options.
 
     __Note #1__: If you provide this option, `got.stream()` will be read-only.
 
@@ -985,6 +1154,57 @@ export default class Options {
     get allowGetBody(): boolean;
     set allowGetBody(value: boolean);
     /**
+    Automatically copy headers from piped streams.
+
+    When piping a request into a Got stream (e.g., `request.pipe(got.stream(url))`), this controls whether headers from the source stream are automatically merged into the Got request headers.
+
+    Note: Piped headers overwrite any explicitly set headers with the same name. To override this, either set `copyPipedHeaders` to `false` and manually copy safe headers, or use a `beforeRequest` hook to force specific header values after piping.
+
+    Useful for proxy scenarios, but you may want to disable this to filter out headers like `Host`, `Connection`, `Authorization`, etc.
+
+    @default true
+
+    @example
+    ```
+    import got from 'got';
+    import {pipeline} from 'node:stream/promises';
+
+    // Disable automatic header copying and manually copy only safe headers
+    server.get('/proxy', async (request, response) => {
+        const gotStream = got.stream('https://example.com', {
+            copyPipedHeaders: false,
+            headers: {
+                'user-agent': request.headers['user-agent'],
+                'accept': request.headers['accept'],
+                // Explicitly NOT copying host, connection, authorization, etc.
+            }
+        });
+
+        await pipeline(request, gotStream, response);
+    });
+    ```
+
+    @example
+    ```
+    import got from 'got';
+
+    // Override piped headers using beforeRequest hook
+    const gotStream = got.stream('https://example.com', {
+        hooks: {
+            beforeRequest: [
+                options => {
+                    // Force specific header values after piping
+                    options.headers.host = 'example.com';
+                    delete options.headers.authorization;
+                }
+            ]
+        }
+    });
+    ```
+    */
+    get copyPipedHeaders(): boolean;
+    set copyPipedHeaders(value: boolean);
+    /**
     Request headers.
 
     Existing headers will be overwritten. Headers set to `undefined` will be omitted.
@@ -1202,6 +1422,18 @@ export default class Options {
     set maxHeaderSize(value: number | undefined);
     get enableUnixSockets(): boolean;
     set enableUnixSockets(value: boolean);
+    /**
+    Throw an error if the server response's `content-length` header value doesn't match the number of bytes received.
+
+    This is useful for detecting truncated responses and follows RFC 9112 requirements for message completeness.
+
+    __Note__: Responses without a `content-length` header are not validated.
+    __Note__: When enabled and validation fails, a `ReadError` with code `ERR_HTTP_CONTENT_LENGTH_MISMATCH` will be thrown.
+
+    @default false
+    */
+    get strictContentLength(): boolean;
+    set strictContentLength(value: boolean);
     toJSON(): {
         headers: Headers;
         timeout: Delays;
@@ -1215,7 +1447,7 @@ export default class Options {
         h2session: ClientHttp2Session | undefined;
         decompress: boolean;
         prefixUrl: string | URL;
-        body: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | undefined;
+        body: string | Buffer | Readable | Generator | AsyncGenerator | Iterable<unknown> | AsyncIterable<unknown> | FormDataLike | ArrayBufferView | undefined;
         form: Record<string, any> | undefined;
         url: string | URL | undefined;
         cookieJar: PromiseCookieJar | ToughCookieJar | undefined;
@@ -1231,6 +1463,7 @@ export default class Options {
         throwHttpErrors: boolean;
         http2: boolean;
         allowGetBody: boolean;
+        copyPipedHeaders: boolean;
         methodRewriting: boolean;
         dnsLookupIpVersion: DnsLookupIpVersion;
         parseJson: ParseJsonFunction;
@@ -1248,6 +1481,7 @@ export default class Options {
         setHost: boolean;
         maxHeaderSize: number | undefined;
         enableUnixSockets: boolean;
+        strictContentLength: boolean;
     };
     createNativeRequestOptions(): {
         ALPNProtocols: string[] | undefined;
@@ -1268,6 +1502,7 @@ export default class Options {
         dhparam: string | Buffer<ArrayBufferLike> | undefined;
         ecdhCurve: string | undefined;
         crl: string | Buffer<ArrayBufferLike> | (string | Buffer<ArrayBufferLike>)[] | undefined;
+        secureOptions: number | undefined;
         lookup: {
             (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;
@@ -1314,7 +1549,6 @@ export default class Options {
         clientCertEngine?: string | undefined;
         privateKeyEngine?: string | undefined;
         privateKeyIdentifier?: string | undefined;
-        secureOptions?: number | undefined;
         secureProtocol?: string | undefined;
         sessionIdContext?: string | undefined;
         ticketKeys?: Buffer | undefined;