got 14.6.0 → 14.6.2

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

@@ -67,8 +67,9 @@ export type BeforeRequestHookContext = {
 };
 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<RequestError>;
+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.
@@ -255,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: {
@@ -278,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[];
@@ -315,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 []
@@ -1057,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.
@@ -1315,6 +1463,7 @@ export default class Options {
         throwHttpErrors: boolean;
         http2: boolean;
         allowGetBody: boolean;
+        copyPipedHeaders: boolean;
         methodRewriting: boolean;
         dnsLookupIpVersion: DnsLookupIpVersion;
         parseJson: ParseJsonFunction;
@@ -1379,7 +1528,6 @@ export default class Options {
         _defaultAgent?: http.Agent | undefined;
         auth?: string | null | undefined;
         defaultPort?: number | string | undefined;
-        hints?: import("dns").LookupOptions["hints"];
         host?: string | null | undefined;
         hostname?: string | null | undefined;
         insecureHTTPParser?: boolean | undefined;
@@ -1391,7 +1539,8 @@ export default class Options {
         signal?: AbortSignal | undefined;
         socketPath?: string | undefined;
         uniqueHeaders?: Array<string | string[]> | undefined;
-        joinDuplicateHeaders?: boolean;
+        joinDuplicateHeaders?: boolean | undefined;
+        hints?: number | undefined;
         ALPNCallback?: ((arg: {
             servername: string;
             protocols: string[];

package/dist/source/core/options.js

@@ -127,6 +127,7 @@ const defaultInternals = {
         beforeError: [],
         beforeRedirect: [],
         beforeRetry: [],
+        beforeCache: [],
         afterResponse: [],
     },
     followRedirect: true,
@@ -137,6 +138,7 @@ const defaultInternals = {
     password: '',
     http2: false,
     allowGetBody: false,
+    copyPipedHeaders: true,
     headers: {
         'user-agent': 'got (https://github.com/sindresorhus/got)',
     },
@@ -274,14 +276,12 @@ const cloneInternals = (internals) => {
             beforeError: [...hooks.beforeError],
             beforeRedirect: [...hooks.beforeRedirect],
             beforeRetry: [...hooks.beforeRetry],
+            beforeCache: [...hooks.beforeCache],
             afterResponse: [...hooks.afterResponse],
         },
         searchParams: internals.searchParams ? new URLSearchParams(internals.searchParams) : undefined,
         pagination: { ...internals.pagination },
     };
-    if (result.url !== undefined) {
-        result.prefixUrl = '';
-    }
     return result;
 };
 const cloneRaw = (raw) => {
@@ -339,11 +339,24 @@ const cloneRaw = (raw) => {
         if (is.array(hooks.beforeRetry)) {
             result.hooks.beforeRetry = [...hooks.beforeRetry];
         }
+        if (is.array(hooks.beforeCache)) {
+            result.hooks.beforeCache = [...hooks.beforeCache];
+        }
         if (is.array(hooks.afterResponse)) {
             result.hooks.afterResponse = [...hooks.afterResponse];
         }
     }
-    // TODO: raw.searchParams
+    if (raw.searchParams) {
+        if (is.string(raw.searchParams)) {
+            result.searchParams = raw.searchParams;
+        }
+        else if (raw.searchParams instanceof URLSearchParams) {
+            result.searchParams = new URLSearchParams(raw.searchParams);
+        }
+        else if (is.object(raw.searchParams)) {
+            result.searchParams = { ...raw.searchParams };
+        }
+    }
     if (is.object(raw.pagination)) {
         result.pagination = { ...raw.pagination };
     }
@@ -367,7 +380,7 @@ const init = (options, withOptions, self) => {
 export default class Options {
     _unixOptions;
     _internals;
-    _merging;
+    _merging = false;
     _init;
     constructor(input, options, defaults) {
         assertAny('input', [is.string, is.urlInstance, is.object, is.undefined], input);
@@ -378,8 +391,6 @@ export default class Options {
         }
         this._internals = cloneInternals(defaults?._internals ?? defaults ?? defaultInternals);
         this._init = [...(defaults?._init ?? [])];
-        this._merging = false;
-        this._unixOptions = undefined;
         // This rule allows `finally` to be considered more important.
         // Meaning no matter the error thrown in the `try` block,
         // if `finally` throws then the `finally` error will be thrown.
@@ -768,7 +779,11 @@ export default class Options {
         if (is.string(value) && value.startsWith('/')) {
             throw new Error('`url` must not start with a slash');
         }
-        const urlString = `${this.prefixUrl}${value.toString()}`;
+        // Detect if URL is already absolute (has a protocol/scheme)
+        const valueString = value.toString();
+        const isAbsolute = is.urlInstance(value) || /^[a-z][a-z\d+.-]*:\/\//i.test(valueString);
+        // Only concatenate prefixUrl if the URL is relative
+        const urlString = isAbsolute ? valueString : `${this.prefixUrl}${valueString}`;
         const url = new URL(urlString);
         this._internals.url = url;
         if (url.protocol === 'unix:') {
@@ -1222,6 +1237,62 @@ export default class Options {
         this._internals.allowGetBody = value;
     }
     /**
+    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() {
+        return this._internals.copyPipedHeaders;
+    }
+    set copyPipedHeaders(value) {
+        assert.boolean(value);
+        this._internals.copyPipedHeaders = value;
+    }
+    /**
     Request headers.
 
     Existing headers will be overwritten. Headers set to `undefined` will be omitted.

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

@@ -101,6 +101,8 @@ 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 {
+    name: string;
+    code: string;
     readonly response: Response;
     constructor(error: Error, response: Response);
 }

package/dist/source/core/response.js

@@ -11,11 +11,11 @@ An error to be thrown when server response code is 2xx, and parsing body fails.
 Includes a `response` property.
 */
 export class ParseError extends RequestError {
+    name = 'ParseError';
+    code = 'ERR_BODY_PARSE_FAILURE';
     constructor(error, response) {
         const { options } = response.request;
         super(`${error.message} in "${options.url.toString()}"`, error, response.request);
-        this.name = 'ParseError';
-        this.code = 'ERR_BODY_PARSE_FAILURE';
     }
 }
 export const parseBody = (response, responseType, parseJson, encoding) => {

package/dist/source/core/timed-out.d.ts

@@ -18,6 +18,7 @@ export type Delays = {
 export type ErrorCode = 'ETIMEDOUT' | 'ECONNRESET' | 'EADDRINUSE' | 'ECONNREFUSED' | 'EPIPE' | 'ENOTFOUND' | 'ENETUNREACH' | 'EAI_AGAIN';
 export declare class TimeoutError extends Error {
     event: string;
+    name: string;
     code: ErrorCode;
     constructor(threshold: number, event: string);
 }

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

@@ -4,12 +4,11 @@ const reentry = Symbol('reentry');
 const noop = () => { };
 export class TimeoutError extends Error {
     event;
-    code;
+    name = 'TimeoutError';
+    code = 'ETIMEDOUT';
     constructor(threshold, event) {
         super(`Timeout awaiting '${event}' for ${threshold}ms`);
         this.event = event;
-        this.name = 'TimeoutError';
-        this.code = 'ETIMEDOUT';
     }
 }
 export default function timedOut(request, delays, options) {

package/dist/source/core/utils/get-body-size.js

@@ -1,4 +1,3 @@
-import { Buffer } from 'node:buffer';
 import { promisify } from 'node:util';
 import is from '@sindresorhus/is';
 import isFormData from './is-form-data.js';
@@ -10,7 +9,7 @@ export default async function getBodySize(body, headers) {
         return 0;
     }
     if (is.string(body)) {
-        return Buffer.byteLength(body);
+        return new TextEncoder().encode(body).byteLength;
     }
     if (is.buffer(body)) {
         return body.length;

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

@@ -1,7 +1,6 @@
 export default class WeakableMap<K, V> {
     weakMap: WeakMap<Record<string, unknown>, V>;
     map: Map<K, V>;
-    constructor();
     set(key: K, value: V): void;
     get(key: K): V | undefined;
     has(key: K): boolean;

package/dist/source/core/utils/weakable-map.js

@@ -1,10 +1,6 @@
 export default class WeakableMap {
-    weakMap;
-    map;
-    constructor() {
-        this.weakMap = new WeakMap();
-        this.map = new Map();
-    }
+    weakMap = new WeakMap();
+    map = new Map();
     set(key, value) {
         if (typeof key === 'object') {
             this.weakMap.set(key, value);

package/dist/source/index.d.ts

@@ -7,6 +7,7 @@ export * from './core/response.js';
 export type { default as Request } from './core/index.js';
 export * from './core/index.js';
 export * from './core/errors.js';
+export * from './core/diagnostics-channel.js';
 export type { Delays } from './core/timed-out.js';
 export { default as calculateRetryDelay } from './core/calculate-retry-delay.js';
 export * from './as-promise/types.js';

package/dist/source/index.js

@@ -14,6 +14,7 @@ export * from './core/options.js';
 export * from './core/response.js';
 export * from './core/index.js';
 export * from './core/errors.js';
+export * from './core/diagnostics-channel.js';
 export { default as calculateRetryDelay } from './core/calculate-retry-delay.js';
 export * from './as-promise/types.js';
 export * from './types.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "got",
-	"version": "14.6.0",
+	"version": "14.6.2",
 	"description": "Human-friendly and powerful HTTP request library for Node.js",
 	"license": "MIT",
 	"repository": "sindresorhus/got",
@@ -53,6 +53,7 @@
 	"dependencies": {
 		"@sindresorhus/is": "^7.0.1",
 		"@szmarczak/http-timer": "^5.0.1",
+		"byte-counter": "^0.1.0",
 		"cacheable-lookup": "^7.0.0",
 		"cacheable-request": "^13.0.12",
 		"decompress-response": "^10.0.0",
@@ -82,6 +83,7 @@
 		"bluebird": "^3.7.2",
 		"body-parser": "^1.20.3",
 		"c8": "^10.1.3",
+		"chunk-data": "^0.1.0",
 		"create-cert": "^1.0.6",
 		"create-test-server": "^3.0.1",
 		"del-cli": "^6.0.0",