got

Version 16.2.0
Published 10 days ago
495 kB
10 dependencies
MIT license

Install

npm i got

yarn add got

pnpm add got

Overview

Human-friendly and powerful HTTP request library for Node.js

Index

Variables

variable calculateRetryDelay

const calculateRetryDelay: Returns<RetryFunction, number>;

variable crossOriginStripHeaders

const crossOriginStripHeaders: readonly [
    'host',
    'cookie',
    'cookie2',
    'authorization',
    'proxy-authorization'
];

variable got

const got: Got<Record<never, never>>;

Functions

function applyUrlOverride

applyUrlOverride: (
    options: Options,
    url: string | URL,
    {
        username,
        password,
        baseUrl,
    }?: { username?: string; password?: string; baseUrl?: URL }
) => URL;

function assertUrlHasSameOriginAsPrefixUrlIfNeeded

assertUrlHasSameOriginAsPrefixUrlIfNeeded: (options: Options, url: URL) => void;

function cacheDecodedBody

cacheDecodedBody: (response: PlainResponse, decodedBody: string) => void;

function copyRedirectDecision

copyRedirectDecision: (
    source: PlainResponse,
    destination: PlainResponse
) => void;

Shares the redirect decision when a response stream is wrapped for decompression.

function create

create: (defaults: InstanceDefaults) => Got;

function decodeUint8Array

decodeUint8Array: (data: Uint8Array, encoding?: BufferEncoding) => string;

function generateRequestId

generateRequestId: () => RequestId;

function getUrlPrefixBoundary

getUrlPrefixBoundary: (options: Options) => UrlPrefixBoundary;

function hasBodyOptionChanged

hasBodyOptionChanged: (changedState: Set<string>) => boolean;

function hasExplicitCredentialInUrlChange

hasExplicitCredentialInUrlChange: (
    changedState: Set<string>,
    url: URL | undefined,
    credential: 'username' | 'password'
) => boolean;

function hasUrlOrPrefixUrlBoundaryChanged

hasUrlOrPrefixUrlBoundaryChanged: (
    options: Options,
    currentUrl: URL,
    previous: UrlPrefixBoundary
) => boolean;

function isBodyUnchanged

isBodyUnchanged: (options: Options, previousState: CrossOriginState) => boolean;

function isCrossOriginCredentialChanged

isCrossOriginCredentialChanged: (
    previousUrl: URL,
    nextUrl: URL,
    credential: 'username' | 'password'
) => boolean;

function isResponseOk

isResponseOk: (response: PlainResponse) => boolean;

function isSameOrigin

isSameOrigin: (previousUrl: URL, nextUrl: URL) => boolean;

function isUtf8Encoding

isUtf8Encoding: (encoding?: BufferEncoding) => boolean;

function normalizeError

normalizeError: (error: unknown) => NodeJS.ErrnoException;

function parseBody

parseBody: (
    response: Response,
    responseType: ResponseType,
    parseJson: ParseJsonFunction,
    encoding?: BufferEncoding
) => unknown;

function parseLinkHeader

parseLinkHeader: (
    link: string
) => { reference: string; parameters: Record<string, string> }[];

function publishError

publishError: (message: DiagnosticRequestError) => void;

function publishRedirect

publishRedirect: (message: DiagnosticResponseRedirect) => void;

function publishRequestCreate

publishRequestCreate: (message: DiagnosticRequestCreate) => void;

function publishRequestStart

publishRequestStart: (message: DiagnosticRequestStart) => void;

function publishResponseEnd

publishResponseEnd: (message: DiagnosticResponseEnd) => void;

function publishResponseStart

publishResponseStart: (message: DiagnosticResponseStart) => void;

function publishRetry

publishRetry: (message: DiagnosticRequestRetry) => void;

function snapshotCrossOriginState

snapshotCrossOriginState: (options: Options) => CrossOriginState;

Classes

class AbortError

class AbortError extends RequestError {}

An error to be thrown when the request is aborted by AbortController.

constructor

constructor(request: Request);

property code

code: string;

property name

name: string;

class CacheError

class CacheError extends RequestError {}

An error to be thrown when a cache method fails. For example, if the database goes down or there's a filesystem error.

constructor

constructor(error: NodeJS.ErrnoException, request: Request);

property code

code: string;

property name

name: string;

property request

readonly request: Request;

class HTTPError

class HTTPError<T = unknown> extends RequestError<T> {}

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.

constructor

constructor(response: any);

property code

code: string;

property name

name: string;

property request

readonly request: Request;

property response

readonly response: any;

class MaxRedirectsError

class MaxRedirectsError extends RequestError {}

An error to be thrown when the server redirects you more than ten times. Includes a response property.

constructor

constructor(request: Request);

property code

code: string;

property name

name: string;

property request

readonly request: Request;

property response

readonly response: any;

class Options

class Options {}

constructor

constructor(
    input?: string | URL | OptionsInit,
    options?: OptionsInit,
    defaults?: Options
);

property agent

agent: Agents;

An object representing http, https and http2 keys for [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent), [https.Agent](https://nodejs.org/api/https.html#https_class_https_agent), and Got's internal HTTP/2 session pool. This is necessary because a request to one protocol might redirect to another. In such a scenario, Got will switch over to the right protocol agent for you. When http2 is enabled, a custom agent.https instance makes Got use the native HTTP/1.1 request path because Got's built-in HTTP/2 session pool does not support custom HTTPS agents.
If a key is not present, it will default to a global agent.
Example 1
``` import got from 'got'; import HttpAgent from 'agentkeepalive';
const {HttpsAgent} = HttpAgent;
await got('https://sindresorhus.com', { agent: { http: new HttpAgent(), https: new HttpsAgent() } }); ```

property allowAbsoluteUrls

allowAbsoluteUrls: boolean;

Allow absolute URLs to bypass prefixUrl.
When set to false with prefixUrl, passing an absolute url will throw. This also rejects scheme-relative URL strings like //example.com/path in retry and pagination URL overrides. Use this when untrusted URL input must stay on the same origin as the configured prefixUrl. This is not a path sandbox: relative paths like ../other still follow standard URL resolution on the same origin. Set prefixUrl to an empty string for a request that intentionally needs an absolute URL.
__Note__: This guards the url you pass. It does not block cross-origin redirects issued by the server, though inherited sensitive headers are still stripped when a redirect changes origin.
__Note__: The check is defeated if the same hook or pagination.paginate(…) return also sets prefixUrl or allowAbsoluteUrls. Do not populate those options from untrusted data.
true

property allowGetBody

allowGetBody: boolean;

Set this to true to allow sending body for the GET method. This option is only meant to interact with non-compliant servers when you have no other choice.
__Note__: The [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) doesn't specify any particular behavior for the GET method having a payload, therefore __it's considered an [anti-pattern](https://en.wikipedia.org/wiki/Anti-pattern)__.
false

property body

body: any;

__Note #1__: The body option cannot be used with the json or form option.
__Note #2__: If you provide this option, got.stream() will be read-only.
__Note #3__: If you provide a payload with the GET or HEAD method, it will throw a TypeError unless the method is GET and the allowGetBody option is set to true.
__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 or an ArrayBufferView (including Uint8Array, other typed arrays, and DataView), 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.
You can use Iterable and AsyncIterable objects as request body, including Web [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream):
Example 1
``` import got from 'got';
// Using an async generator async function* generateData() { yield 'Hello, '; yield 'world!'; }
await got.post('https://httpbin.org/anything', { body: generateData() }); ```

property cache

cache: any;

A cache adapter instance for storing cached response data.
undefined

property cacheOptions

cacheOptions: CacheOptions;

From http-cache-semantics
{}

property context

context: Record<string, unknown>;

User data. context is shallow merged and enumerable. If it contains non-enumerable properties they will NOT be merged.
Example 1
``` import got from 'got';
const instance = got.extend({ hooks: { beforeRequest: [ options => { if (!options.context || !options.context.token) { throw new Error('Token required'); }
options.headers.token = options.context.token; } ] } });
const context = { token: 'secret' };
const response = await instance('https://httpbin.org/headers', {context});
// Let's see the headers console.log(response.body); ```

property cookieJar

cookieJar: PromiseCookieJar | ToughCookieJar;

Cookie support. You don't have to care about parsing or how to store them.
__Note__: If you provide this option, options.headers.cookie will be overridden.

property copyPipedHeaders

copyPipedHeaders: 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: Explicitly set headers take precedence over piped headers. Piped headers are only copied when a header is not already explicitly set.
Useful for proxy scenarios when explicitly enabled. Got automatically omits host, authorization, cookie, cookie2, set-cookie, set-cookie2, hop-by-hop headers, and headers nominated by Connection/Proxy-Connection. Got cannot know which app-specific headers are sensitive. Leave copyPipedHeaders disabled and copy only safe headers manually, or explicitly omit those headers before piping. If you trust the upstream and want to forward credentials, pass them explicitly in headers.
false
Example 1
``` import got from 'got'; import {pipeline} from 'node:stream/promises';
// Opt in to automatic header copying for proxy scenarios server.get('/proxy', async (request, response) => { const gotStream = got.stream('https://example.com', { copyPipedHeaders: true, // Explicit headers win over piped headers. // Add credentials here only when the upstream is trusted. headers: { host: 'example.com', } });
await pipeline(request, gotStream, response); }); ```
Example 2
``` import got from 'got'; import {pipeline} from 'node:stream/promises';
// Keep it disabled and manually copy only safe headers server.get('/proxy', async (request, response) => { const gotStream = got.stream('https://example.com', { headers: { 'user-agent': request.headers['user-agent'], 'accept': request.headers['accept'], // Explicitly NOT copying host, connection, authorization, etc. } });
await pipeline(request, gotStream, response); }); ```

property createConnection

createConnection: CreateConnectionFunction;

The function used to retrieve a net.Socket instance when the agent option is not used.
For HTTP/1, either return the socket synchronously or call callback(null, socket) asynchronously. Call callback(error) if socket creation fails.
When http2 is enabled for HTTPS, this function must synchronously return a tls.TLSSocket. Callback-based creation is not supported by HTTP/2 negotiation.

property decompress

decompress: boolean;

Decompress the response automatically.
This will set the accept-encoding header to gzip, deflate, br unless you set it yourself.
If this is disabled, a compressed response is returned as a Uint8Array. This may be useful if you want to handle decompression yourself or stream the raw compressed data.
true

property dnsCache

dnsCache: DnsCacheLookup;

A DNS cache instance used for making DNS lookups. Useful when making lots of requests to different *public* hostnames. Set to true to use Got's shared DNS cache. When using got.extend(), set to false to opt out of a DNS cache configured by the parent instance.
Got's built-in DNS cache uses dns.resolve4(…) and dns.resolve6(…) under the hood and falls back to dns.lookup(…) when no DNS records are found, which may lead to additional delay. Because it resolves A and AAAA records separately, it cannot preserve OS-specific verbatim address ordering from dns.lookup(…). If present, clear(hostname?) can be called by user code to clear cached entries.
__Note__: This should stay disabled when making requests to internal hostnames such as localhost, database.local etc.
undefined

property dnsLookup

dnsLookup: any;

property dnsLookupIpVersion

dnsLookupIpVersion: DnsLookupIpVersion;

Indicates which DNS record family to use.
Values: - undefined: IPv4 (if present) or IPv6 - 4: Only IPv4 - 6: Only IPv6
undefined

property enableUnixSockets

enableUnixSockets: boolean;

property encoding

encoding: any;

[Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on setEncoding of the response data.
To get a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), you need to set responseType to buffer instead. Don't set this option to null.
__Note__: This doesn't affect streams! Instead, you need to do got.stream(...).setEncoding(encoding).
undefined, which decodes the response as UTF-8

property followRedirect

followRedirect: boolean | ((response: PlainResponse) => boolean);

Whether redirect responses should be followed automatically.
Optionally, pass a function to dynamically decide based on the response object. The function is only called for 3xx responses, and an unchanged function is evaluated only once per response.
Note that if a 303 is sent by the server in response to any request type (POST, DELETE, etc.), Got will automatically request the resource pointed to in the location header via GET. This is in accordance with [the spec](https://tools.ietf.org/html/rfc7231#section-6.4.4). You can optionally turn on this behavior also for other redirect codes - see methodRewriting. On cross-origin redirects, Got strips host, cookie, cookie2, authorization, and proxy-authorization. When a redirect rewrites the request to GET, Got also strips request body headers. Use hooks.beforeRedirect for app-specific sensitive headers.
true

property form

form: Record<string, any>;

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).
If the Content-Type header is not present, it will be set to application/x-www-form-urlencoded.
__Note #1__: If you provide this option, got.stream() will be read-only.
__Note #2__: This option is not enumerable and will not be merged with the instance defaults.

property h2session

h2session: any;

property headers

headers: Headers;

Request headers.
Existing headers will be overwritten. Headers set to undefined will be omitted. Number values are stored and sent as strings.
{'user-agent': 'got (https://github.com/sindresorhus/got)'}

property hooks

hooks: Hooks;

Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.

property http2

http2: boolean;

If set to true, Got will additionally accept HTTP/2 requests.
It will choose either HTTP/1.1 or HTTP/2 depending on the ALPN protocol. When a custom agent.https instance is set, Got uses that native HTTPS agent directly and skips HTTP/2 negotiation.
__Note__: If options.request returns a request or response, it controls the transport and Got's HTTP/2 client is bypassed. Return undefined to fall back to Got's built-in transport.
false
Example 1
``` import got from 'got';
const {headers} = await got('https://nghttp2.org/httpbin/anything', {http2: true});
console.log(headers.via); //=> '2 nghttpx' ```

property https

https: HttpsOptions;

Options for the advanced HTTPS API.

property ignoreInvalidCookies

ignoreInvalidCookies: boolean;

Ignore invalid cookies instead of throwing an error. Only useful when the cookieJar option has been set. Not recommended.
false

property json

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.
__Note #2__: This option is not enumerable and will not be merged with the instance defaults.

property localAddress

localAddress: string;

From http.RequestOptions.
The IP address used to send the request from.

property maxHeaderSize

maxHeaderSize: number;

property maxRedirects

maxRedirects: number;

If exceeded, the request will be aborted and a MaxRedirectsError will be thrown.
10

property method

method: LiteralUnion<
    | 'get'
    | 'post'
    | 'put'
    | 'patch'
    | 'head'
    | 'delete'
    | 'query'
    | 'GET'
    | 'POST'
    | 'PUT'
    | 'PATCH'
    | 'HEAD'
    | 'DELETE'
    | 'OPTIONS'
    | 'TRACE'
    | 'QUERY'
    | 'options'
    | 'trace',
    string
>;

The HTTP method used to make the request. Custom methods such as PROPFIND are supported. Method names are normalized to uppercase.
'GET'

property methodRewriting

methodRewriting: boolean;

Specifies if the HTTP request method should be [rewritten as GET](https://tools.ietf.org/html/rfc7231#section-6.4) on redirects.
As the [specification](https://tools.ietf.org/html/rfc7231#section-6.4) prefers to rewrite the HTTP method only on 303 responses, this is Got's default behavior. Cross-origin 301 and 302 redirects also rewrite POST requests to GET by default to avoid forwarding request bodies to another origin. Setting methodRewriting to true will also rewrite same-origin 301 and 302 responses, as allowed by the spec. This is the behavior followed by curl and browsers.
__Note__: Got never performs method rewriting on 307 and 308 responses, as this is [explicitly prohibited by the specification](https://www.rfc-editor.org/rfc/rfc7231#section-6.4.7).
false

property pagination

pagination: PaginationOptions<unknown, unknown>;

property parseJson

parseJson: ParseJsonFunction;

A function used to parse JSON responses.
Example 1
``` import got from 'got'; import {parse} from '@hapi/bourne';
// Preventing prototype pollution by using Bourne const parsed = await got('https://example.com', { parseJson: text => parse(text) }).json();
console.log(parsed); ```

property password

password: string;

property prefixUrl

prefixUrl: string | URL;

When specified, prefixUrl will be prepended to relative string url input. The prefix must be an absolute URL, since Got has no base to resolve it against. It must not contain a query string or a fragment. A trailing slash / is optional - one will be added automatically.
__Note__: Absolute string URLs and URL instances bypass prefixUrl by default. Other instance defaults, including headers, still apply. For untrusted URLs, set allowAbsoluteUrls to false.
__Note__: Got cannot know which custom headers are sensitive. If you use headers like x-api-key, only pass trusted URLs or use allowAbsoluteUrls: false.
__Note__: Leading slashes in input are disallowed when using this option to enforce consistency and avoid confusion. For example, when the prefix URL is https://example.com/foo and the input is /bar, there's ambiguity whether the resulting URL would become https://example.com/foo/bar or https://example.com/bar. The latter is used by browsers.
__Tip__: Useful when used with got.extend() to create niche-specific Got instances.
__Tip__: You can change prefixUrl using hooks as long as the URL still includes the prefixUrl. If the URL doesn't include it anymore, it will throw.
Example 1
``` import got from 'got';
await got('unicorn', {prefixUrl: 'https://cats.com'}); //=> 'https://cats.com/unicorn'
const instance = got.extend({ prefixUrl: 'https://google.com' });
await instance('unicorn', { hooks: { beforeRequest: [ options => { options.prefixUrl = 'https://cats.com'; } ] } }); //=> 'https://cats.com/unicorn' ```

property request

request: RequestFunction;

Custom request function.
Got's built-in HTTP/1.1 or HTTP/2 request implementation

property resolveBodyOnly

resolveBodyOnly: boolean;

When set to true the promise will return the Response body instead of the Response object.
false

property responseType

responseType: ResponseType;

The parsing method.
The promise also has .text(), .json() and .buffer() methods which return another Got promise for the parsed body.
It's like setting the options to {responseType: 'json', resolveBodyOnly: true} but without affecting the main Got promise.
.json() also accepts a [Standard Schema](https://standardschema.dev) validator, in which case the promise resolves with the output of the schema.
__Note__: When using streams, this option is ignored.
Example 1
``` const responsePromise = got(url); const bufferPromise = responsePromise.buffer(); const jsonPromise = responsePromise.json();
const [response, buffer, json] = Promise.all([responsePromise, bufferPromise, jsonPromise]); // response is an instance of Got Response // buffer is an instance of Uint8Array // json is an object ```
Example 2
``` // This const body = await got(url).json();
// is semantically the same as this const body = await got(url, {responseType: 'json', resolveBodyOnly: true}); ```

property retry

retry: Partial<RetryOptions>;

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.
Undefined settings preserve inherited values, except maxRetryAfter, where undefined restores the request timeout fallback.
Delays between retries are calculated with Math.max(1, Math.min((2 ** (attemptCount - 1)) * 1000, backoffLimit) + noise), where attemptCount starts at 1 and noise is the randomized retry noise. Setting both backoffLimit and noise to 0 requests an immediate retry; returning 0 from calculateDelay still aborts the retry.
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).
Delays above 2_147_483_647 milliseconds (Node.js's timer limit), including Infinity, abort the retry instead of triggering an immediate retry. This also applies to delays computed from Retry-After.
The enforceRetryRules property is a boolean that, when set to true (default), enforces the limit, methods, statusCodes, and errorCodes options before calling calculateDelay. Your calculateDelay function is only invoked when a retry is allowed based on these criteria. When false, calculateDelay receives the computed value but can override all retry logic.
__Note:__ When enforceRetryRules is false, you must check computedValue in your calculateDelay function to respect retry rules. When true (default), the retry rules are enforced automatically.
By default, it retries *only* on the specified methods, status codes, and on these network errors:
- ETIMEDOUT: One of the [timeout](#timeout) limits were reached. - ECONNRESET: Connection was forcibly closed by a peer. - EADDRINUSE: Could not bind to any free port. - ECONNREFUSED: Connection was refused by the server. - EPIPE: The remote side of the stream being written has been closed. - ENOTFOUND: Couldn't resolve the hostname to an IP address. - ENETUNREACH: No internet connection. - EAI_AGAIN: DNS lookup timed out.
__Note__: If maxRetryAfter is set to undefined, it will use options.timeout. __Note__: 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.

property searchParams

searchParams: URLSearchParams;

Query string that will be added to the request URL. This will override the query string in url.
If you need to pass in an array, you can do it using a URLSearchParams instance.
Example 1
``` import got from 'got';
const searchParams = new URLSearchParams([['key', 'a'], ['key', 'b']]);
await got('https://example.com', {searchParams});
console.log(searchParams.toString()); //=> 'key=a&key=b' ```

property setHost

setHost: boolean;

property signal

signal: AbortSignal;

You can abort the request using [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
Example 1
``` import got from 'got';
const abortController = new AbortController();
const request = got('https://httpbin.org/anything', { signal: abortController.signal });
setTimeout(() => { abortController.abort(); }, 100); ```

property strictContentLength

strictContentLength: 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. __Note__: Keep custom native responses in byte mode for exact validation. Calling setEncoding() on the native response can lose the original byte count when decoding malformed input.
true

property stringifyJson

stringifyJson: StringifyJsonFunction;

A function used to stringify the body of JSON requests.
Example 1
``` import got from 'got';
await got.post('https://example.com', { stringifyJson: object => JSON.stringify(object, (key, value) => { if (key.startsWith('_')) { return; }
return value; }), json: { some: 'payload', _ignoreMe: 1234 } }); ```
Example 2
``` import got from 'got';
await got.post('https://example.com', { stringifyJson: object => JSON.stringify(object, (key, value) => { if (typeof value === 'number') { return value.toString(); }
return value; }), json: { some: 'payload', number: 1 } }); ```

property throwHttpErrors

throwHttpErrors: boolean;

Determines if a got.HTTPError is thrown for unsuccessful responses.
If this is disabled, requests that encounter an error status code will be resolved with the response instead of throwing. This may be useful if you are checking for resource availability and are expecting error responses.
true

property timeout

timeout: Delays;

Milliseconds to wait for the server to end the response before aborting the request with got.TimeoutError error (a.k.a. request property). By default, there's no timeout.
This also accepts an object with the following fields to constrain the duration of each phase of the request lifecycle:
- lookup starts when a socket is assigned and ends when the hostname has been resolved. Does not apply when using a Unix domain socket. - connect starts when lookup completes (or when the socket is assigned if lookup does not apply to the request) and ends when the socket is connected. - secureConnect starts when connect completes and ends when the handshaking process completes (HTTPS only). - socket starts when the socket is connected. See [request.setTimeout](https://nodejs.org/api/http.html#http_request_settimeout_timeout_callback). - response starts when the request has been written to the socket and ends when the response headers are received. - send starts when the socket is connected and ends with the request has been written to the socket. - request starts when the request is initiated and ends when the response's end event fires.

property url

url: string | URL;

The URL to request, as a string or a [WHATWG URL](https://nodejs.org/api/url.html#url_class_url).
Pass it as the first argument to got(url, options). Setting url inside an options object is not supported.
Properties from options will override properties in the parsed url.
If no protocol is specified, it will throw a TypeError.
__Note__: The query string is **not** parsed as search params.
Example 1
``` await got('https://example.com/?query=a b'); //=> https://example.com/?query=a%20b await got('https://example.com/', {searchParams: {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 ```

property username

username: string;

method clearBody

clearBody: () => void;

method clearUnchangedCookieHeader

clearUnchangedCookieHeader: (
    previousState: CrossOriginState | undefined,
    changedState?: Set<string>
) => void;

method createNativeRequestOptions

createNativeRequestOptions: () => Except<
    {
        h2session: ClientHttp2Session | undefined;
        _socketTimeout?: number | undefined;
        _timeoutPhase?:
            | 'connect'
            | 'lookup'
            | 'secureConnect'
            | 'request'
            | undefined;
        ALPNProtocols: string[] | undefined;
        ca:
            | string
            | Buffer<ArrayBufferLike>
            | (string | Buffer<ArrayBufferLike>)[]
            | undefined;
        cert:
            | string
            | Buffer<ArrayBufferLike>
            | (string | Buffer<ArrayBufferLike>)[]
            | undefined;
        key:
            | string
            | Buffer<ArrayBufferLike>
            | (string | Buffer<ArrayBufferLike> | import('node:tls').KeyObject)[]
            | undefined;
        passphrase: string | undefined;
        pfx: PfxType;
        rejectUnauthorized: boolean | undefined;
        checkServerIdentity:
            | CheckServerIdentityFunction
            | typeof checkServerIdentity;
        servername: string | undefined;
        ciphers: string | undefined;
        honorCipherOrder: boolean | undefined;
        minVersion: import('node:tls').SecureVersion | undefined;
        maxVersion: import('node:tls').SecureVersion | undefined;
        sigalgs: string | undefined;
        sessionTimeout: number | undefined;
        dhparam: string | Buffer<ArrayBufferLike> | undefined;
        ecdhCurve: string | undefined;
        crl:
            | string
            | Buffer<ArrayBufferLike>
            | (string | Buffer<ArrayBufferLike>)[]
            | undefined;
        secureOptions: number | undefined;
        lookup: LookupFunction | undefined;
        family: DnsLookupIpVersion;
        agent:
            | false
            | http.Agent
            | {
                  http2: false | import('./utils/http2-client.js').Http2Agent;
                  http?: HttpAgent | false;
                  https?: HttpsAgent | false;
              }
            | undefined;
        setHost: boolean;
        method: Method;
        maxHeaderSize: number | undefined;
        localAddress: string | undefined;
        headers: Headers;
        createConnection: CreateConnectionFunction | undefined;
        signal: AbortSignal | undefined;
        timeout: number | undefined;
        socketPath?: string | undefined;
        path?: string | undefined;
        host?: string | undefined;
        shared?: boolean;
        cacheHeuristic?: number;
        immutableMinTimeToLive?: number;
        ignoreCargoCult?: boolean;
    },
    '_socketTimeout' | '_timeoutPhase'
>;

method deleteInternalHeader

deleteInternalHeader: (name: string) => void;

method freeze

freeze: () => void;

method getInternalHeaders

getInternalHeaders: () => Headers;

method getRequestFunction

getRequestFunction: () => RequestFunction | typeof https.request | undefined;

method isHeaderExplicitlySet

isHeaderExplicitlySet: (name: string) => boolean;

method merge

merge: (options?: OptionsInit | Options) => void;

method mergeNextRequestOptions

mergeNextRequestOptions: (
    updatedOptions: OptionsInit,
    {
        previousUrl,
        previousState,
        previousBoundary,
        baseUrl,
    }: {
        previousUrl: URL | undefined;
        previousState: CrossOriginState | undefined;
        previousBoundary: UrlPrefixBoundary;
        baseUrl?: URL;
    }
) => { nextUrl: URL | undefined; hasExplicitBody: boolean };

Merge the options for a follow-up request into this and apply the cross-origin rules. This is shared by afterResponse retries (when the hook passes a new options object) and by pagination.
Returns the resolved nextUrl when updatedOptions.url was supplied, so callers can run their own checks on it, and whether the caller supplied an explicit body.

method restoreCookieHeader

restoreCookieHeader: (
    previousState: CrossOriginState | undefined,
    headers?: HeadersInit
) => void;

method setInternalHeader

setInternalHeader: (name: string, value: string | string[] | undefined) => void;

method setPipedHeader

setPipedHeader: (name: string, value: string | string[] | undefined) => void;

method shouldCopyPipedHeader

shouldCopyPipedHeader: (name: string) => boolean;

method stripSensitiveHeaders

stripSensitiveHeaders: (
    previousUrl: URL,
    nextUrl: URL,
    userOptions: OptionsInit
) => void;

Strip sensitive headers and credentials when navigating to a different origin. Headers and credentials explicitly provided in userOptions are preserved.

method stripUnchangedCrossOriginState

stripUnchangedCrossOriginState: (
    previousState: CrossOriginState,
    changedState: Set<string>,
    { clearBody }?: { clearBody?: boolean }
) => void;

method syncCookieHeaderAfterMerge

syncCookieHeaderAfterMerge: (
    previousState: CrossOriginState | undefined,
    headers?: HeadersInit
) => void;

method toJSON

toJSON: () => InternalsType;

method trackStateMutations

trackStateMutations: <Value>(
    operation: (changedState: Set<string>) => Promisable<Value>
) => Promise<Value>;

class ParseError

class ParseError extends RequestError {}

An error to be thrown when server response code is 2xx, and parsing body fails. Includes a response property.

constructor

constructor(error: Error, response: any);

property code

code: string;

property name

name: string;

property response

readonly response: any;

class ReadError

class ReadError extends RequestError {}

An error to be thrown when reading from response stream fails.

constructor

constructor(error: NodeJS.ErrnoException, request: Request);

property code

code: string;

property name

name: string;

property request

readonly request: Request;

property response

readonly response: any;

class Request

class Request extends Duplex implements RequestEvents<Request> {}

constructor

constructor(
    url: string | URL | OptionsInit,
    options?: OptionsInit,
    defaults?: Options,
    retrySource?: Request
);

property ['constructor']

['constructor']: typeof Request;

property downloadProgress

readonly downloadProgress: Progress;

Progress event for downloading (receiving a response).

property ip

readonly ip: string;

The remote IP address.

property isAborted

readonly isAborted: boolean;

Indicates whether the request has been aborted or not.

property isFromCache

readonly isFromCache: boolean;

Whether the response was retrieved from the cache.

property isReadonly

readonly isReadonly: boolean;

Whether the stream is read-only. Returns true when body, json, or form options are provided.

property options

options: Options;

property redirectUrls

redirectUrls: URL[];

property requestUrl

requestUrl?: URL;

property response

response?: any;

property retryCount

retryCount: number;

property reusedSocket

readonly reusedSocket: boolean;

property socket

readonly socket: any;

property timings

readonly timings: Timings;

The object contains the following properties:
- start - Time when the request started. - socket - Time when a socket was assigned to the request. - lookup - Time when the DNS lookup finished. - connect - Time when the socket successfully connected. - secureConnect - Time when the socket securely connected. - upload - Time when the request finished uploading. - response - Time when the request fired response event. - end - Time when the response fired end event. - error - Time when the request fired error event. - abort - Time when the request fired abort event. - phases - wait - timings.socket - timings.start - dns - timings.lookup - timings.socket - tcp - timings.connect - timings.lookup - tls - timings.secureConnect - timings.connect - request - timings.upload - (timings.secureConnect || timings.connect) - firstByte - timings.response - timings.upload - download - timings.end - timings.response - total - (timings.end || timings.error || timings.abort) - timings.start
If something has not been measured yet, it will be undefined.
__Note__: The time is a number representing the milliseconds elapsed since the UNIX epoch.

property uploadProgress

readonly uploadProgress: Progress;

Progress event for uploading (sending a request).

method flush

flush: () => Promise<void>;

method pipe

pipe: <T extends NodeJS.WritableStream>(
    destination: T,
    options?: { end?: boolean }
) => T;

method unpipe

unpipe: <T extends NodeJS.WritableStream>(destination?: T) => this;

method write

write: (
    chunk: unknown,
    encoding?: any,
    callback?: (error?: Error | null) => void
) => boolean;

class RequestError

class RequestError<T = unknown> extends Error {}

An error to be thrown when a request fails. Contains a code property with error class code, like ECONNREFUSED.

constructor

constructor(
    message: string,
    error: Partial<any>,
    self: Options | Request,
    response?: any
);

property code

code: string;

property input

input?: string;

property name

name: string;

property options

readonly options: Options;

property request

readonly request?: Request;

property response

readonly response?: any;

property stack

stack: string;

property timings

readonly timings?: Timings;

class RetryError

class RetryError extends RequestError {}

An error which always triggers a new retry when thrown.

constructor

constructor(request: Request);

property code

code: string;

property name

name: string;

class SchemaValidationError

class SchemaValidationError extends Error {}

An error to be thrown when the response body does not match the [Standard Schema](https://standardschema.dev) validator passed to .json(schema). Includes an issues property with the issues from the schema. Each issue has a message and an optional path.
It intentionally does not extend RequestError, because the request succeeded. The user-provided schema did not accept the data, so it has no code, options, request, response or timings property, and it is not passed to beforeError hooks.
Example 1
import got, {SchemaValidationError} from 'got'; import {z} from 'zod'; const userSchema = z.object({name: z.string()}); try { const user = await got('https://example.com/user').json(userSchema); console.log(user.name); } catch (error) { if (error instanceof SchemaValidationError) { console.error(error.issues); } else { throw error; } }

constructor

constructor(issues: readonly StandardSchemaV1Issue[]);

property issues

readonly issues: readonly StandardSchemaV1Issue[];

property name

name: string;

class TimeoutError

class TimeoutError extends RequestError {}

An error to be thrown when the request is aborted due to a timeout. Includes an event and timings property.

constructor

constructor(error: TimedOutTimeoutError, timings: Timings, request: Request);

property code

code: string;

property event

readonly event: string;

property name

name: string;

property request

readonly request: Request;

property timings

readonly timings: Timings;

class UploadError

class UploadError extends RequestError {}

An error to be thrown when the request body is a stream and an error occurs while reading from that stream.

constructor

constructor(error: NodeJS.ErrnoException, request: Request);

property code

code: string;

property name

name: string;

property request

readonly request: Request;

Type Aliases

type AfterResponseHook

type AfterResponseHook<ResponseType = unknown> = (
    response: Response<ResponseType>,
    retryWithMergedOptions: (options: OptionsInit) => never
) => Promisable<Response | RequestPromise<Response>>;

type Agents

type Agents = {
    http?: HttpAgent | false;
    https?: HttpsAgent | false;
    http2?: false;
};

type BeforeCacheHook

type BeforeCacheHook = (
    response: Pick<PlainResponse, 'headers' | 'statusCode' | 'statusMessage'>
) => false | void;

type BeforeErrorHook

type BeforeErrorHook = (error: RequestError) => Promisable<Error>;

type BeforeRedirectHook

type BeforeRedirectHook = (
    updatedOptions: NormalizedOptions,
    plainResponse: PlainResponse
) => Promisable<void>;

type BeforeRequestHook

type BeforeRequestHook = (
    options: NormalizedOptions,
    context: BeforeRequestHookContext
) => Promisable<void | AcceptableResponse | ClientRequest>;

type BeforeRequestHookContext

type BeforeRequestHookContext = {
    /**
    The current retry count.

    It will be `0` for the initial request and increment for each retry.
    */
    retryCount: number;
};

type BeforeRetryHook

type BeforeRetryHook = (error: RequestError, retryCount: number) => Promisable<void>;

type CacheOptions

type CacheOptions = {
    shared?: boolean;
    cacheHeuristic?: number;
    immutableMinTimeToLive?: number;
    ignoreCargoCult?: boolean;
};

type CheckServerIdentityFunction

type CheckServerIdentityFunction = (
    hostname: string,
    certificate: DetailedPeerCertificate
) => NodeJS.ErrnoException | void;

type CreateConnectionFunction

type CreateConnectionFunction = (
    options: NativeRequestOptions,
    oncreate: (error: NodeJS.ErrnoException | null, socket?: Socket) => void
) => Socket | void;

type CrossOriginState

type CrossOriginState = {
    headers: Headers;
    hadCookieJar: boolean;
    cookieWasExplicitlySet: boolean;
    username: string;
    password: string;
    body: unknown;
    json: unknown;
    form: unknown;
    bodySnapshot: unknown;
    jsonSnapshot: unknown;
    formSnapshot: unknown;
};

type Delays

type Delays = {
    lookup?: number;
    socket?: number;
    connect?: number;
    secureConnect?: number;
    send?: number;
    response?: number;
    read?: number;
    request?: number;
};

type DiagnosticRequestCreate

type DiagnosticRequestCreate = {
    requestId: RequestId;
    url: string;
    method: string;
};

Message for the got:request:create diagnostic channel.
Emitted when a request is created.

type DiagnosticRequestError

type DiagnosticRequestError = {
    requestId: RequestId;
    url: string;
    error: Error;
    timings?: Timings;
};

Message for the got:request:error diagnostic channel.
Emitted when a request fails.
The error can be replaced by a beforeError hook. Use error instanceof RequestError before accessing Got-specific properties.

type DiagnosticRequestRetry

type DiagnosticRequestRetry = {
    requestId: RequestId;
    retryCount: number;
    error: RequestError;
    delay: number;
};

Message for the got:request:retry diagnostic channel.
Emitted when retrying a request.

type DiagnosticRequestStart

type DiagnosticRequestStart = {
    requestId: RequestId;
    url: string;
    method: string;
    headers: Record<string, string | string[] | undefined>;
};

Message for the got:request:start diagnostic channel.
Emitted before the native HTTP request is sent.

type DiagnosticResponseEnd

type DiagnosticResponseEnd = {
    requestId: RequestId;
    url: string;
    statusCode: number;
    bodySize?: number;
    timings?: Timings;
};

Message for the got:response:end diagnostic channel.
Emitted when the response completes.

type DiagnosticResponseRedirect

type DiagnosticResponseRedirect = {
    requestId: RequestId;
    fromUrl: string;
    toUrl: string;
    statusCode: number;
};

Message for the got:response:redirect diagnostic channel.
Emitted when following a redirect.

type DiagnosticResponseStart

type DiagnosticResponseStart = {
    requestId: RequestId;
    url: string;
    statusCode: number;
    headers: Record<string, string | string[] | undefined>;
    isFromCache: boolean;
};

Message for the got:response:start diagnostic channel.
Emitted when response headers are received.

type DnsCacheLookup

type DnsCacheLookup = {
    lookup: LookupFunction;
    clear?(hostname?: string): void;
};

type DnsCacheOptions

type DnsCacheOptions = {
    cache?: DnsCacheStore;
    maxTtl?: number;
    fallbackDuration?: number;
    errorTtl?: number;
    resolver?: Resolver;
    lookup?: LookupFunction | false;
};

type DnsLookupIpVersion

type DnsLookupIpVersion = undefined | 4 | 6;

type ExtendOptions

type ExtendOptions = {
    /**
    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 whether `got()` or `got.stream()` was called.

    @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;
} & Except<OptionsInit, 'url'>;

The options available for got.extend().

type ExtractExtendOptions

type ExtractExtendOptions<T> = T extends Got<infer GotOptions> ? GotOptions : T;

type FilterData

type FilterData<ElementType> = {
    item: ElementType;
    currentItems: ElementType[];
    allItems: ElementType[];
};

type Got

type Got<GotOptions extends ExtendOptions = Record<never, never>> = {
    /**
    Returns a [duplex stream](https://nodejs.org/api/stream.html#stream_class_stream_duplex) with additional events:
    - request
    - response
    - redirect
    - uploadProgress
    - downloadProgress
    - error

    Note: Writable request streams do not auto-end for POST, PUT, OPTIONS, PATCH, DELETE, or QUERY. Call `stream.end()` when you are not piping a body.
    */
    stream: GotStream;
    /**
    Returns an async iterator.

    See pagination.options for more pagination options.

    @example
    ```
    import got from 'got';

    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.
    */
    readonly defaults: InstanceDefaults;
    /**
    Configure a new `got` instance with default `options`.
    The `options` are merged with the parent instance's `defaults.options` using `Options#merge`.
    You can access the resolved options with the `.defaults` property on the instance.

    Scalar options such as `responseType` and `resolveBodyOnly` ignore `undefined` and preserve the parent value. To restore their defaults, explicitly pass `responseType: 'text'` or `resolveBodyOnly: false`.

    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 `Options#merge` (including hooks),
    - handlers are stored in an array (you can access them through `instance.defaults.handlers`).

    @example
    ```
    import got from 'got';

    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(): Got<GotOptions>;
    extend<T extends Array<Got<any> | ExtendOptions>>(
        ...instancesOrOptions: T
    ): Got<MergeExtendsConfig<[GotOptions, ...T]>>;
} & Record<HTTPAlias, GotRequestFunction<GotOptions>> &
    GotRequestFunction<GotOptions>;

An instance of got.

type GotEventFunction

type GotEventFunction<T> =
    /**
`request` event to get the request object of the request.

 __Tip__: You can use `request` event to abort requests.

@example
```
import got from 'got';

got.stream('https://github.com')
    .on('request', request => setTimeout(() => request.destroy(), 50));
```
*/
    ((name: 'request', listener: (request: ClientRequest) => void) => T) &
        /**
The `response` event to get the response object of the final request.

__Note__: Stream responses are plain: `body` and `rawBody` are only parsed for the Promise API.
*/
        (<R extends PlainResponse>(
            name: 'response',
            listener: (response: R) => void
        ) => T) &
        /**
The `redirect` event to get the options for the next request to the redirect location. The second argument is the response object of the redirect.
*/
        (<R extends PlainResponse, N extends Options>(
            name: 'redirect',
            listener: (nextOptions: N, response: R) => void
        ) => T) &
        /**
Progress events for uploading (sending a request) and downloading (receiving a response).
The `progress` argument is an object like:

```
{
    percent: 0.1,
    transferred: 1024,
    total: 10240
}
```

If the `content-length` header is missing, `total` will be `undefined`.

@example
```
import got from 'got';

const response = await got('https://sindresorhus.com')
    .on('downloadProgress', progress => {
        // Report download progress
    })
    .on('uploadProgress', progress => {
        // Report upload progress
    });

console.log(response);
```
*/
        ((
            name: 'uploadProgress' | 'downloadProgress',
            listener: (progress: Progress) => void
        ) => T) &
        /**
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 `got.options.retry` for more information.
*/
        ((
            name: 'retry',
            listener: (
                retryCount: number,
                error: RequestError,
                createRetryStream: (options?: OptionsInit) => Request
            ) => void
        ) => T);

type GotPaginate

type GotPaginate = {
    /**
    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>;
    /**
    Returns an async iterator.

    See pagination.options for more pagination options.

    @example
    ```
    import got from 'got';

    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
    ```
    import got from 'got';

    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[]>);
};

An instance of got.paginate.

type GotRequestFunction

type GotRequestFunction<U extends ExtendOptions = Record<string, unknown>> = {
    (url: string | URL, options?: StrictOptions): GotResponseResult<
        U,
        DefaultResponseBodyType<U>
    >;
    (
        url: string | URL,
        options?: OptionsOfUnknownResponseBodyWrapped
    ): RequestPromise<Response<DefaultResponseBodyType<U>>>;
    (url: string | URL, options?: OptionsOfUnknownResponseBodyOnly): RequestPromise<
        DefaultResponseBodyType<U>
    >;
    (url: string | URL, options?: OptionsOfTextResponseBody): GotResponseResult<
        U,
        string
    >;
    <T>(url: string | URL, options?: OptionsOfJSONResponseBody): GotResponseResult<
        U,
        T
    >;
    (url: string | URL, options?: OptionsOfBufferResponseBody): GotResponseResult<
        U,
        Uint8Array<ArrayBuffer>
    >;
    (url: string | URL, options?: OptionsOfTextResponseBodyWrapped): RequestPromise<
        Response<string>
    >;
    <T>(
        url: string | URL,
        options?: OptionsOfJSONResponseBodyWrapped
    ): RequestPromise<Response<T>>;
    (
        url: string | URL,
        options?: OptionsOfBufferResponseBodyWrapped
    ): RequestPromise<Response<Uint8Array<ArrayBuffer>>>;
    (
        url: string | URL,
        options?: OptionsOfTextResponseBodyOnly
    ): RequestPromise<string>;
    <T>(
        url: string | URL,
        options?: OptionsOfJSONResponseBodyOnly
    ): RequestPromise<T>;
    (url: string | URL, options?: OptionsOfBufferResponseBodyOnly): RequestPromise<
        Uint8Array<ArrayBuffer>
    >;
    (options: StrictOptions): GotResponseResult<U, DefaultResponseBodyType<U>>;
    (options: OptionsOfUnknownResponseBodyWrapped): RequestPromise<
        Response<DefaultResponseBodyType<U>>
    >;
    (options: OptionsOfUnknownResponseBodyOnly): RequestPromise<
        DefaultResponseBodyType<U>
    >;
    (options: OptionsOfTextResponseBody): GotResponseResult<U, string>;
    <T>(options: OptionsOfJSONResponseBody): GotResponseResult<U, T>;
    (options: OptionsOfBufferResponseBody): GotResponseResult<
        U,
        Uint8Array<ArrayBuffer>
    >;
    (options: OptionsOfTextResponseBodyWrapped): RequestPromise<Response<string>>;
    <T>(options: OptionsOfJSONResponseBodyWrapped): RequestPromise<Response<T>>;
    (options: OptionsOfBufferResponseBodyWrapped): RequestPromise<
        Response<Uint8Array<ArrayBuffer>>
    >;
    (options: OptionsOfTextResponseBodyOnly): RequestPromise<string>;
    <T>(options: OptionsOfJSONResponseBodyOnly): RequestPromise<T>;
    (options: OptionsOfBufferResponseBodyOnly): RequestPromise<
        Uint8Array<ArrayBuffer>
    >;
    (url: string | URL, options?: StreamOptions): RequestPromise;
    (options: StreamOptions): RequestPromise;
    (url: undefined, options: undefined, defaults: Options): RequestPromise;
};

type GotReturn

type GotReturn = Request | RequestPromise;

A Request object returned by calling Got, or any of the Got HTTP alias request functions.

type GotStream

type GotStream = GotStreamFunction & Record<HTTPAlias, GotStreamFunction>;

An instance of got.stream().

type HandlerFunction

type HandlerFunction = <T extends GotReturn>(
    options: Options,
    next: (options: Options) => T
) => T | Promise<T>;

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.

type Headers

type Headers = Record<string, string | string[] | undefined>;

type Hooks

type Hooks = {
    /**
    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.

    For example, this can be used to fix typos to migrate from older versions faster.

    @example
    ```
    import got from 'got';

    const instance = got.extend({
        hooks: {
            init: [
                plain => {
                    if ('followRedirects' in plain) {
                        plain.followRedirect = plain.followRedirects;
                        delete plain.followRedirects;
                    }
                }
            ]
        }
    });

    // 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 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 []

    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, context) => {
                        options.body = JSON.stringify({payload: 'new'});
                        options.headers['content-length'] = options.body.length.toString();
                    }
                ]
            }
        }
    );
    ```

    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).
    */
    beforeRequest: BeforeRequestHook[];
    /**
    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';

    const response = await got('https://example.com', {
        hooks: {
            beforeRedirect: [
                (options, response) => {
                    if (options.url.hostname === 'dead-site.example') {
                        options.url = 'https://fallback-site.example';
                    }
                }
            ]
        }
    });
    ```
    */
    beforeRedirect: BeforeRedirectHook[];
    /**
    Called with a `RequestError` instance. The error is passed to the hook right before it's thrown.

    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: {
            beforeError: [
                error => {
                    const {response} = error;
                    if (response && response.body) {
                        error.name = 'GitHubError';
                        error.message = `${response.body.message} (${response.statusCode})`;
                    }

                    return error;
                }
            ]
        }
    });

    // 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[];
    /**
    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';

    await got('https://httpbin.org/status/500', {
        hooks: {
            beforeRetry: [
                (error, retryCount) => {
                    console.log(`Retrying [${retryCount}]: ${error.code}`);
                    // Retrying [1]: ERR_NON_2XX_3XX_RESPONSE
                }
            ]
        }
    });
    ```
    */
    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 []

    Note:
    > - When using the Stream API, this hook is ignored.

    Note:
    > - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. By default, remaining `afterResponse` hooks are removed to prevent duplicate execution. To preserve remaining hooks on retry, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. 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.

    Note:
    > - To preserve remaining `afterResponse` hooks after calling `retryWithMergedOptions`, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. This is useful when you want hooks to run on retried requests.

    Warning:
    > - Be cautious when using `preserveHooks: true`. If a hook unconditionally calls `retryWithMergedOptions` with `preserveHooks: true`, it will create an infinite retry loop. Always ensure hooks have proper conditional logic to avoid infinite retries.

    @example
    ```
    import got from 'got';

    const instance = got.extend({
        hooks: {
            afterResponse: [
                (response, retryWithMergedOptions) => {
                    // Unauthorized
                    if (response.statusCode === 401) {
                        // Refresh the access token
                        const updatedOptions = {
                            headers: {
                                token: getNewToken()
                            }
                        };

                        // Update the defaults
                        instance.defaults.options.merge(updatedOptions);

                        // Make a new retry
                        return retryWithMergedOptions(updatedOptions);
                    }

                    // No changes otherwise
                    return response;
                }
            ],
            beforeRetry: [
                error => {
                    // This will be called on `retryWithMergedOptions(...)`
                }
            ]
        },
        mutableDefaults: true
    });
    ```

    @example
    ```
    // Example with preserveHooks
    import got from 'got';

    const instance = got.extend({
        hooks: {
            afterResponse: [
                (response, retryWithMergedOptions) => {
                    if (response.statusCode === 401) {
                        return retryWithMergedOptions({
                            headers: {
                                authorization: getNewToken()
                            },
                            preserveHooks: true  // Keep remaining hooks
                        });
                    }

                    return response;
                },
                (response) => {
                    // This hook will run on the retried request
                    // (the original request is interrupted when the first hook triggers a retry)
                    console.log('Response received:', response.statusCode);
                    return response;
                }
            ]
        }
    });
    ```
    */
    afterResponse: AfterResponseHook[];
};

All available hooks of Got.

type HTTPAlias

type HTTPAlias = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete' | 'query';

All available HTTP shortcut aliases provided by Got.

type HttpsOptions

type HttpsOptions = {
    alpnProtocols?: string[];
    rejectUnauthorized?: NativeRequestOptions['rejectUnauthorized'];
    checkServerIdentity?: CheckServerIdentityFunction;
    /**
    Server name for the [Server Name Indication (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication) TLS extension.

    This is useful when requesting to servers that don't have a proper domain name but use a certificate with a known CN/SAN.

    @example
    ```
    import got from 'got';

    // Request to IP address with specific servername for TLS
    await got('https://192.168.1.100', {
        https: {
            serverName: 'example.com'
        }
    });
    ```
    */
    serverName?: string;
    /**
    Override the default Certificate Authorities ([from Mozilla](https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReport)).

    @example
    ```
    // Single Certificate Authority
    await got('https://example.com', {
        https: {
            certificateAuthority: fs.readFileSync('./my_ca.pem')
        }
    });
    ```
    */
    certificateAuthority?: SecureContextOptions['ca'];
    /**
    Private keys in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format.

    [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) allows the option of private keys being encrypted.
    Encrypted keys will be decrypted with `options.https.passphrase`.

    Multiple keys with different passphrases can be provided as an array of `{pem: <string | Uint8Array>, passphrase: <string>}`
    */
    key?: SecureContextOptions['key'];
    /**
    [Certificate chains](https://en.wikipedia.org/wiki/X.509#Certificate_chains_and_cross-certification) in [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) format.

    One cert chain should be provided per private key (`options.https.key`).

    When providing multiple cert chains, they do not have to be in the same order as their private keys in `options.https.key`.

    If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.
    */
    certificate?: SecureContextOptions['cert'];
    /**
    The passphrase to decrypt the `options.https.key` (if different keys have different passphrases refer to `options.https.key` documentation).
    */
    passphrase?: SecureContextOptions['passphrase'];
    pfx?: PfxType;
    ciphers?: SecureContextOptions['ciphers'];
    honorCipherOrder?: SecureContextOptions['honorCipherOrder'];
    minVersion?: SecureContextOptions['minVersion'];
    maxVersion?: SecureContextOptions['maxVersion'];
    signatureAlgorithms?: SecureContextOptions['sigalgs'];
    tlsSessionLifetime?: SecureContextOptions['sessionTimeout'];
    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;
};

type InitHook

type InitHook = (init: OptionsInit, self: Options) => void;

type InstanceDefaults

type InstanceDefaults = {
    /**
    An object containing the default options of Got.
    */
    options: 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 whether `got()` or `got.stream()` was called.

    @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
    */
    readonly mutableDefaults: boolean;
};

Defaults for each Got instance.

type InternalsType

type InternalsType = OverrideProperties<
    Except<Options, OptionsToSkip>,
    {
        searchParams: URLSearchParams | undefined;
    }
>;

type MergeExtendsConfig

type MergeExtendsConfig<
    Value extends Array<Got<any> | ExtendOptions>,
    MergedOptions extends ExtendOptions = Record<never, never>
> = Value extends [
    infer First extends Got<any> | ExtendOptions,
    ...infer Rest extends Array<Got<any> | ExtendOptions>
]
    ? MergeExtendsConfig<
          Rest,
          Spread<MergedOptions, DefinedOptions<ExtractExtendOptions<First>>>
      >
    : Value extends [
          ...infer Rest extends Array<Got<any> | ExtendOptions>,
          infer Last extends Got<any> | ExtendOptions
      ]
    ? Spread<
          MergeExtendsConfig<Rest, MergedOptions>,
          DefinedOptions<ExtractExtendOptions<Last>>
      >
    : [Value[number]] extends [never]
    ? MergedOptions
    : Spread<
          MergedOptions,
          Partial<DefinedOptions<ExtractExtendOptions<Value[number]>>>
      >;

Merges the options of multiple Got instances.

type Method

type Method = LiteralUnion<
    | 'GET'
    | 'POST'
    | 'PUT'
    | 'PATCH'
    | 'HEAD'
    | 'DELETE'
    | 'OPTIONS'
    | 'TRACE'
    | 'QUERY'
    | 'get'
    | 'post'
    | 'put'
    | 'patch'
    | 'head'
    | 'delete'
    | 'options'
    | 'trace'
    | 'query',
    string
>;

HTTP request methods, including custom methods.

type NativeRequestOptions

type NativeRequestOptions = HttpsRequestOptions &
    CacheOptions & {
        checkServerIdentity?: CheckServerIdentityFunction;
    };

type NormalizedOptions

type NormalizedOptions = OverrideProperties<
    Options,
    {
        get url(): URL | undefined;
        set url(value: Options['url']);
        get dnsCache(): DnsCacheLookup | undefined;
        set dnsCache(value: DnsCacheLookup | boolean | undefined);
        get cache(): string | StorageAdapter | undefined;
        set cache(value: Options['cache']);
        get prefixUrl(): string;
        set prefixUrl(value: Options['prefixUrl']);
        get searchParams(): URLSearchParams;
        set searchParams(
            value: string | SearchParameters | URLSearchParams | undefined
        );
    }
>;

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.

type OptionsError

type OptionsError = NodeJS.ErrnoException & {
    options?: Options;
};

type OptionsInit

type OptionsInit = OverrideProperties<
    Except<Partial<InternalsType>, 'hooks' | 'retry' | 'isStream'>,
    {
        dnsCache?: DnsCacheLookup | boolean | undefined;
        searchParams?: string | SearchParameters | URLSearchParams | undefined;
        headers?: HeadersInit;
    }
> & {
    hooks?: Partial<Hooks>;
    retry?: Partial<RetryOptions>;
    preserveHooks?: boolean;
};

type OptionsOfBufferResponseBody

type OptionsOfBufferResponseBody = Merge<
    StrictOptions,
    {
        responseType?: 'buffer';
    }
>;

type OptionsOfBufferResponseBodyOnly

type OptionsOfBufferResponseBodyOnly = Merge<
    StrictOptions,
    {
        resolveBodyOnly: true;
        responseType?: 'buffer';
    }
>;

type OptionsOfBufferResponseBodyWrapped

type OptionsOfBufferResponseBodyWrapped = Merge<
    StrictOptions,
    {
        resolveBodyOnly: false;
        responseType?: 'buffer';
    }
>;

type OptionsOfJSONResponseBody

type OptionsOfJSONResponseBody = Merge<
    StrictOptions,
    {
        responseType?: 'json';
    }
>;

type OptionsOfJSONResponseBodyOnly

type OptionsOfJSONResponseBodyOnly = Merge<
    StrictOptions,
    {
        resolveBodyOnly: true;
        responseType?: 'json';
    }
>;

type OptionsOfJSONResponseBodyWrapped

type OptionsOfJSONResponseBodyWrapped = Merge<
    StrictOptions,
    {
        resolveBodyOnly: false;
        responseType?: 'json';
    }
>;

type OptionsOfTextResponseBody

type OptionsOfTextResponseBody = Merge<
    StrictOptions,
    {
        responseType?: 'text';
    }
>;

type OptionsOfTextResponseBodyOnly

type OptionsOfTextResponseBodyOnly = Merge<
    StrictOptions,
    {
        resolveBodyOnly: true;
        responseType?: 'text';
    }
>;

type OptionsOfTextResponseBodyWrapped

type OptionsOfTextResponseBodyWrapped = Merge<
    StrictOptions,
    {
        resolveBodyOnly: false;
        responseType?: 'text';
    }
>;

type OptionsOfUnknownResponseBodyOnly

type OptionsOfUnknownResponseBodyOnly = Merge<
    StrictOptions,
    {
        resolveBodyOnly: true;
    }
>;

type OptionsOfUnknownResponseBodyWrapped

type OptionsOfUnknownResponseBodyWrapped = Merge<
    StrictOptions,
    {
        resolveBodyOnly: false;
    }
>;

type OptionsWithPagination

type OptionsWithPagination<T = unknown, R = unknown> = Merge<
    StreamOptions,
    {
        pagination?: PaginationOptions<T, R>;
    }
>;

type PaginateData

type PaginateData<BodyType, ElementType> = {
    response: Response<BodyType>;
    currentItems: ElementType[];
    allItems: ElementType[];
};

type PaginationOptions

type PaginationOptions<ElementType, BodyType> = {
    /**
    A function that transforms [`Response`](#response) into an array of items.
    This is where you should do the parsing.

    @default Parses text and buffer responses as JSON using the configured encoding, and returns JSON responses unchanged.
    */
    transform?: (
        response: Response<BodyType>
    ) => Promise<ElementType[]> | ElementType[];
    /**
    Checks whether the item should be emitted or not.

    @default ({item, currentItems, allItems}) => true
    */
    filter?: (data: FilterData<ElementType>) => boolean;
    /**
    By default, links with an `anchor` parameter are ignored, as permitted by [RFC 8288, section 3.2](https://www.rfc-editor.org/rfc/rfc8288#section-3.2).

    The function takes an object with the following properties:
    - `response` - The current response object.
    - `currentItems` - Items from the current response.
    - `allItems` - An empty array, unless `pagination.stackAllItems` is set to `true`, in which case, it's an array of the emitted items.

    It should return an object representing Got options pointing to the next page. The options are merged automatically with the previous request, therefore the options returned `pagination.paginate(...)` must reflect changes only. The returned `url` can be a string or URL instance. Relative string URLs resolve against the current request URL, which after a cross-origin redirect is the final redirected URL rather than the original `prefixUrl`. If there are no more pages, `false` should be returned. The function may also be async and return a promise for either value.

    When pagination navigates to a different origin, Got strips inherited sensitive headers such as `authorization`, `cookie`, and `proxy-authorization`. If you trust the next-page URL and want to forward a sensitive header, return it explicitly from `pagination.paginate(...)`.

    @example
    ```
    import got from 'got';

    const limit = 10;

    const items = got.paginate('https://example.com/items', {
        searchParams: {
            limit,
            offset: 0
        },
        pagination: {
            paginate: ({response, currentItems}) => {
                const previousSearchParams = response.request.options.searchParams;
                const previousOffset = previousSearchParams.get('offset');

                if (currentItems.length < limit) {
                    return false;
                }

                return {
                    searchParams: {
                        ...previousSearchParams,
                        offset: Number(previousOffset) + limit,
                    }
                };
            }
        }
    });

    console.log('Items from all pages:', items);
    ```
    */
    paginate?: (
        data: PaginateData<BodyType, ElementType>
    ) => Promisable<OptionsInit | false>;
    /**
    Checks whether the pagination should continue.

    For example, if you need to stop **before** emitting an entry with some flag, you should use `({item}) => !item.flag`.

    If you want to stop **after** emitting the entry, you should use
    `({item, allItems}) => allItems.some(item => item.flag)` instead.

    @default ({item, currentItems, allItems}) => true
    */
    shouldContinue?: (data: FilterData<ElementType>) => boolean;
    /**
    The maximum amount of items that should be emitted.

    @default Infinity
    */
    countLimit?: number;
    /**
    Milliseconds to wait before the next request is triggered.

    @default 0
    */
    backoff?: number;
    /**
    The maximum amount of request that should be triggered.
    Retries on failure are not counted towards this limit.

    For example, it can be helpful during development to avoid an infinite number of requests.

    @default 10000
    */
    requestLimit?: number;
    /**
    Defines how the property `allItems` in `pagination.paginate`, `pagination.filter` and `pagination.shouldContinue` is managed.

    By default, the property `allItems` is always an empty array. This setting can be helpful to save on memory usage when working with a large dataset.

    When set to `true`, the property `allItems` is an array of the emitted items.

    @default false
    */
    stackAllItems?: boolean;
};

All options accepted by got.paginate().

type ParseJsonFunction

type ParseJsonFunction = (text: string) => unknown;

type PlainResponse

type PlainResponse = {
    /**
    The original request URL.
    */
    requestUrl: URL;
    /**
    The redirect URLs.
    */
    redirectUrls: URL[];
    /**
    - `options` - The Got options that were set on this request.

    __Note__: This is not a [http.ClientRequest](https://nodejs.org/api/http.html#http_class_http_clientrequest).
    */
    request: Request;
    /**
    The remote IP address.

    This is hopefully a temporary limitation, see [lukechilds/cacheable-request#86](https://web.archive.org/web/20220804165050/https://github.com/jaredwray/cacheable-request/issues/86).

    __Note__: Not available when the response is cached.
    */
    ip?: string;
    /**
    Whether the response was retrieved from the cache.
    */
    isFromCache: boolean;
    /**
    The status code of the response.
    */
    statusCode: number;
    /**
    The request URL or the final URL after redirects.
    */
    url: string;
    /**
    The object contains the following properties:

    - `start` - Time when the request started.
    - `socket` - Time when a socket was assigned to the request.
    - `lookup` - Time when the DNS lookup finished.
    - `connect` - Time when the socket successfully connected.
    - `secureConnect` - Time when the socket securely connected.
    - `upload` - Time when the request finished uploading.
    - `response` - Time when the request fired `response` event.
    - `end` - Time when the response fired `end` event.
    - `error` - Time when the request fired `error` event.
    - `abort` - Time when the request fired `abort` event.
    - `phases`
        - `wait` - `timings.socket - timings.start`
        - `dns` - `timings.lookup - timings.socket`
        - `tcp` - `timings.connect - timings.lookup`
        - `tls` - `timings.secureConnect - timings.connect`
        - `request` - `timings.upload - (timings.secureConnect || timings.connect)`
        - `firstByte` - `timings.response - timings.upload`
        - `download` - `timings.end - timings.response`
        - `total` - `(timings.end || timings.error || timings.abort) - timings.start`

    If something has not been measured yet, it will be `undefined`.

    The entire property is `undefined` for cached responses and responses returned directly by hooks or custom request functions without timing information.

    __Note__: The time is a `number` representing the milliseconds elapsed since the UNIX epoch.
    */
    timings?: Timings;
    /**
    The number of times the request was retried.
    */
    retryCount: number;
    /**
    The raw result of the request.
    */
    rawBody?: Uint8Array<ArrayBuffer>;
    /**
    The result of the request.
    */
    body?: unknown;
    /**
    Whether the response was successful.

    __Note__: Got throws automatically when `response.ok` is `false` and `throwHttpErrors` is `true`.
    */
    ok: boolean;
} & IncomingMessageWithTimings;

type Progress

type Progress = {
    percent: number;
    transferred: number;
    total?: number;
};

type PromiseCookieJar

type PromiseCookieJar = {
    getCookieString: (url: string) => Promise<string>;
    setCookie: (rawCookie: string, url: string) => Promise<unknown>;
};

type RequestEvents

type RequestEvents<T> = {
    on: GotEventFunction<T>;
    once: GotEventFunction<T>;
    off: GotEventFunction<T>;
};

type RequestFunction

type RequestFunction = (
    url: URL,
    options: NativeRequestOptions,
    callback?: (response: AcceptableResponse) => void
) => AcceptableRequestResult;

type RequestId

type RequestId = string;

type RequestPromise

type RequestPromise<T extends Response | Response['body'] = Response['body']> =
    Promise<T> & RequestPromiseShape<T>;

type Response

type Response<T = unknown> = {
    /**
    The result of the request.
    */
    body: T;
    /**
    The raw result of the request.
    */
    rawBody: Uint8Array<ArrayBuffer>;
} & PlainResponse;

type ResponseType

type ResponseType = 'json' | 'buffer' | 'text';

All parsing methods supported by Got.

type RetryFunction

type RetryFunction = (retryObject: RetryObject) => Promisable<number>;

type RetryObject

type RetryObject = {
    attemptCount: number;
    retryOptions: RetryOptions;
    error: RequestError;
    computedValue: number;
    retryAfter?: number;
};

type RetryOptions

type RetryOptions = {
    limit: number;
    methods: Method[];
    statusCodes: number[];
    errorCodes: string[];
    calculateDelay: RetryFunction;
    backoffLimit: number;
    noise: number;
    maxRetryAfter?: number;
    enforceRetryRules?: boolean;
};

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.
Delays between retries are calculated with Math.max(1, Math.min((2 ** (attemptCount - 1)) * 1000, backoffLimit) + noise), where attemptCount starts at 1 and noise is the randomized retry noise. Setting both backoffLimit and noise to 0 requests an immediate retry; returning 0 from calculateDelay still aborts the retry.
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).
Delays above 2_147_483_647 milliseconds (Node.js's timer limit), including Infinity, abort the retry instead of triggering an immediate retry. This also applies to delays computed from Retry-After.
The enforceRetryRules property is a boolean that, when set to true (default), enforces the limit, methods, statusCodes, and errorCodes options before calling calculateDelay. Your calculateDelay function is only invoked when a retry is allowed based on these criteria. When false, calculateDelay receives the computed value but can override all retry logic.
__Note:__ When enforceRetryRules is false, you must check computedValue in your calculateDelay function to respect retry rules. When true (default), the retry rules are enforced automatically.
By default, it retries *only* on the specified methods, status codes, and on these network errors: - ETIMEDOUT: One of the [timeout](#timeout) limits were reached. - ECONNRESET: Connection was forcibly closed by a peer. - EADDRINUSE: Could not bind to any free port. - ECONNREFUSED: Connection was refused by the server. - EPIPE: The remote side of the stream being written has been closed. - ENOTFOUND: Couldn't resolve the hostname to an IP address. - ENETUNREACH: No internet connection. - EAI_AGAIN: DNS lookup timed out.
__Note:__ Got does not retry on POST by default. __Note:__ If maxRetryAfter is set to undefined, it will use options.timeout. __Note:__ 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.

type SearchParameters

type SearchParameters = Record<string, string | number | boolean | null | undefined>;

type StandardSchemaV1

type StandardSchemaV1<InputType = unknown, OutputType = InputType> = {
    readonly '~standard': {
        readonly version: 1;
        readonly vendor: string;
        readonly validate: (
            value: unknown,
            options?: StandardSchemaV1Options
        ) =>
            | StandardSchemaV1Result<OutputType>
            | Promise<StandardSchemaV1Result<OutputType>>;
        readonly types?: StandardSchemaV1Types<InputType, OutputType> | undefined;
    };
};

type StandardSchemaV1InferOutput

type StandardSchemaV1InferOutput<Schema extends StandardSchemaV1> =
    Schema['~standard'] extends {
        readonly types: StandardSchemaV1Types<unknown, infer OutputType>;
    }
        ? OutputType
        : Extract<
              Awaited<ReturnType<Schema['~standard']['validate']>>,
              StandardSchemaV1SuccessResult<unknown>
          > extends StandardSchemaV1SuccessResult<infer OutputType>
        ? OutputType
        : unknown;

Infer the output type of a Standard Schema.

type StandardSchemaV1Issue

type StandardSchemaV1Issue = {
    readonly message: string;
    readonly path?:
        | ReadonlyArray<
              | PropertyKey
              | {
                    readonly key: PropertyKey;
                }
          >
        | undefined;
};

The types of the [Standard Schema](https://standardschema.dev) specification (v1).
Copied from the specification so Got does not need a dependency for types only.

type StreamOptions

type StreamOptions = Except<OptionsInit, 'url'>;

type StrictOptions

type StrictOptions = Merge<
    StreamOptions,
    {
        responseType?: undefined;
        resolveBodyOnly?: undefined;
    }
>;

type StringifyJsonFunction

type StringifyJsonFunction = (object: unknown) => string;

type Timings

type Timings = {
    start: number;
    socket?: number;
    lookup?: number;
    connect?: number;
    secureConnect?: number;
    upload?: number;
    response?: number;
    end?: number;
    error?: number;
    abort?: number;
    phases: {
        wait?: number;
        dns?: number;
        tcp?: number;
        tls?: number;
        request?: number;
        firstByte?: number;
        download?: number;
        total?: number;
    };
};

type ToughCookieJar

type ToughCookieJar = {
    getCookieString: ((
        currentUrl: string,
        options: Record<string, unknown>,
        callback: (error: Error | undefined, cookies: string) => void
    ) => void) &
        ((
            url: string,
            callback: (error: Error | undefined, cookieHeader: string) => void
        ) => void);
    setCookie: ((
        cookieOrString: unknown,
        currentUrl: string,
        options: Record<string, unknown>,
        callback: (error: Error | undefined, cookie: unknown) => void
    ) => void) &
        ((
            rawCookie: string,
            url: string,
            callback: (error: Error | undefined, result: unknown) => void
        ) => void);
};

type UrlPrefixBoundary

type UrlPrefixBoundary = {
    url?: URL;
    prefixUrl?: string;
    allowAbsoluteUrls?: boolean;
};

Package Files (15)

Dependencies (10)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/got.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/got)

HTML

<a href="https://www.jsdocs.io/package/got"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 10 days ago.
Package analyzed in 5484 ms.
Missing or incorrect documentation? Open an issue for this package.

got

Install

Overview

Index

Variables

Functions

Classes

Type Aliases

Variables

variable calculateRetryDelay

variable crossOriginStripHeaders

variable got

Functions

function applyUrlOverride

function assertUrlHasSameOriginAsPrefixUrlIfNeeded

function cacheDecodedBody

function copyRedirectDecision

function create

function decodeUint8Array

function generateRequestId

function getUrlPrefixBoundary

function hasBodyOptionChanged

function hasExplicitCredentialInUrlChange

function hasUrlOrPrefixUrlBoundaryChanged

function isBodyUnchanged

function isCrossOriginCredentialChanged

function isResponseOk

function isSameOrigin

function isUtf8Encoding

function normalizeError

function parseBody

function parseLinkHeader

function publishError

function publishRedirect

function publishRequestCreate

function publishRequestStart

function publishResponseEnd

function publishResponseStart

function publishRetry

function snapshotCrossOriginState

Classes

class AbortError

constructor

property code

property name

class CacheError

constructor

property code

property name

property request

class HTTPError

constructor

property code

property name

property request

property response

class MaxRedirectsError

constructor

property code

property name

property request

property response

class Options

constructor

property agent

Example 1

property allowAbsoluteUrls

property allowGetBody

property body

Example 1

property cache

property cacheOptions

property context

Example 1

property cookieJar

property copyPipedHeaders

Example 1

Example 2

property createConnection

property decompress