got
16.2.0 · 30 Oct 2026MIT53.2M / weekRepositoryHomepagenpmAtom feed
12.6.1 is the newest release of 12.x.
In short
19 breaking19 new25 fixed6 changed
- Breaking
Got exports an
Optionclass that is specifically designed to parse and validate Got options. It is made of setters and getters that provide fast normalization and more consistent behavior. - Breaking
The
inithook now accepts a second argument:self, which points to anOptionsinstance. - Breaking
The
inithooks are ran only when passing an options object explicitly. - Breaking
options.merge()replacedgot.mergeOptionsandRequest.normalizeArguments - Breaking
Legacy
Urlinstances are not supported anymore. You need to use WHATWG URL instead. - Breaking
No implicit timeout declaration.
- Breaking
No implicit retry declaration.
- Breaking
dnsLookupIpVersionis now a number (4 or 6) or undefined
Security
1 advisory affects 12.0.0; 12.1.0 fixes them
- ModerateGot allows a redirect to a UNIX socketGHSA-pfrx-2q88-qq97 · 19 Jun 2022Fixed in 12.1.0
Release note
Introducing Got v12.0.0 :tada
Long time no see! The latest Got version (v11.8.2) was released just in February ❄️
We have been working hard on squashing bugs and improving overall experience.
If you find Got useful, you might want to sponsor the Got maintainers.
This package is now pure ESM
Please read this. Also see #1789.
Please don't open issues about
[ERR_REQUIRE_ESM]andMust use import to load ES Moduleerrors. This is a problem with your setup, not Got.Please don't open issues about using Got with Jest. Jest does not fully support ESM.
Pretty much any problem with loading this package is a problem with your bundler, test framework, etc, not Got.
If you use TypeScript, you will want to stay on Got v11 until TypeScript 4.6 is out. Why.
If you use a bundler, make sure it supports ESM and that you have correctly configured it for ESM.
The Got issue tracker is not a support channel for your favorite build/bundler tool.
Required Node.js >=14
While working with streams, we encountered more Node.js bugs that needed workarounds.
In order to keep our code clean, we had to drop Node.js v12 as the code would get more messy.
We strongly recommend that you update Node.js to v14 LTS.
HTTP/2 support
Every Node.js release, the native http2 module gets more stable.
Unfortunately there are still some issues on the Node.js side, so we decided to keep HTTP/2 disabled for now.
We may enable it by default in Got v13. It is still possible to turn it on via the http2 option.
To run HTTP/2 requests, it is required to use Node.js v15.10 or above.
Bug fixes
Woah, we possibly couldn't make a release if we didn't fix some bugs!
Remove automatic
content-lengthon ReadStream (#1510) 472b8efFix promise shortcuts in case of error status code (#1543) ff918fb 1107cc6
Invert the
methodRewritingoption 51d88a0Fix
urlnot being reused on retry in rare case (#1487) 462bc63Prevent uncaught ParseErrors on initial successful response (#1527) 77df9c3
Throw an error when retrying with consumed body (#1507) 62305d7
Fix a Node.js 16 bug that hangs Got streams 06a2d3d
Fix default pagination handling for empty Link header (#1768) 1e1e506
Fix incorrect
response.completewhen using cache 9e15d88Fix
Cannot call enderror whenrequestreturns aWritable226cc39Fix Request options not being reused on retry 3c23eea
Fix types being not compatible with CommonJS 3c23eea
Generate a new object when passing options to the native
httpsmodule (#1567) 3c23eeaFix unhandled exception when lookup returns invalid IP early (#1737) 2453e5e
Fix relative URLs when paginating 439fb82
Require url to be an instance of URL when paginating (#1818) eda69ff
Fix
usernameandpasswordencoding in URL (#1169 #1317) d65d0caClone raw options 1c4cefc
Fix invalid
afterResponsereturn check cbc8902Fix
https.alpnProtocolsnot having an effect e1099fb
Improvements
Add generic argument to AfterResponseHook TypeScript type (#1589) 6fc04a9
Change the stackAllItems option to be false by default (#1645) 1120370
Throw when afterResponse hook returns an invalid value 4f21eb3
Add
retry.backoffLimitoption 41c4136Add
noiseretry option e830077Define
error.codef27e8d3Set
options.urleven if some options are invalid 8d6a680Improve memory usage when merging options 2db5ec5
Add missing
oncetypes for Stream API 3c23eeaNew error type:
RetryErrorwhich always triggers a new retry when thrown 3c23eeaerror.optionsis now enumerable 3c23eeadefaults.handlersdon't need a default handler now 3c23eeaAdd a parser for the
Linkheader 3c23eeaGeneral code improvements a5dd9aa
Breaking changes
Improved option normalization
- Breaking
Got exports an
Optionclass that is specifically designed to parse and validate Got options.
It is made of setters and getters that provide fast normalization and more consistent behavior.
When passing an option does not exist, Got will throw an error. In order to retrieve the options before the error, use error.options.
import got from 'got';
try {
await got('https://httpbin.org/anything', {
thisOptionDoesNotExist: true
});
} catch (error) {
console.error(error);
console.error(error.options.url.href);
// Unexpected option: thisOptionDoesNotExist
// https://httpbin.org/anything
}- Breaking
The
inithook now accepts a second argument:self, which points to anOptionsinstance.
In order to define your own options, you have to move them to options.context in an init hook or store them in options.context directly.
- Breaking
The
inithooks are ran only when passing an options object explicitly.
- await got('https://example.com'); // this will *not* trigger the init hooks
+ await got('https://example.com', {}); // this *will** trigger init hooks- Breaking
options.merge()replacedgot.mergeOptionsandRequest.normalizeArguments
- got.defaults.options = got.mergeOptions(got.defaults.options, {…});
+ got.defaults.options.merge(…);This fixes issues like #1450
- Breaking
Legacy
Urlinstances are not supported anymore. You need to use WHATWG URL instead.
- await got(string, {port: 8443});
+ const url = new URL(string);
+ url.port = 8443;
+ await got(url);- Breaking
No implicit timeout declaration.
- await got('https://example.com', {timeout: 5000})
+ await got('https://example.com', {timeout: {request: 5000})- Breaking
No implicit retry declaration.
- await got('https://example.com', {retry: 5})
+ await got('https://example.com', {retry: {limit: 5})- Breaking
dnsLookupIpVersionis now a number (4 or 6) or undefined
- await got('https://example.com', {dnsLookupIpVersion: 'ipv4'})
+ await got('https://example.com', {dnsLookupIpVersion: 4})- Breaking
redirectUrlsandrequestUrlnow give URL instances
- request.requestUrl + request.requestUrl.origin + request.requestUrl.href + request.requestUrl.toString()
- request.redirectUrls[0] + request.redirectUrls[0].origin + request.redirectUrls[0].href + request.redirectUrls[0].toString()
- Breaking
Renamed
request.abortedtorequest.isAborted
- request.aborted + request.isAborted
Reason: consistency with options.isStream.
- Breaking
Renamed the
lookupoption todnsLookup
- await got('https://example.com', {lookup: cacheable.lookup})
+ await got('https://example.com', {dnsLookup: cacheable.lookup})- Breaking
The
beforeRetryhook now accepts only two arguments:errorandretryCount
await got('https://example.com', {
hooks: {
beforeRetry: [
- (options, error, retryCount) => {
- console.log(options, error, retryCount);
- }
+ (error, retryCount) => {
+ console.log(error.options, error, retryCount);
+ }
]
}
})The options argument has been removed, however it's still accessible via error.options. All modifications on error.options will be reflected in the next requests (no behavior change, same as with Got 11).
- Breaking
The
beforeRedirecthook's first argument (options) is now a cloned instance of the Request options.
This was done to make retrieving the original options possible: plainResponse.request.options.
await got('http://szmarczak.com', {
hooks: {
beforeRedirect: [
(options, response) => {
- console.log(options === response.request.options); //=> true [invalid! our original options were overriden]
+ console.log(options === response.request.options); //=> false [we can access the original options now]
}
]
}
})- Breaking
The
redirectevent now takes two arguments in this order:updatedOptionsandplainResponse.
- stream.on('redirect', (response, options) => …)
+ stream.on('redirect', (options, response) => …)Reason: consistency with the beforeRedirect hook.
- Breaking
The
socketPathoption has been removed. Use theunix:protocol instead.
- got('/containers/json', {socketPath: '/var/run/docker.sock'})
+ got('unix:/var/run/docker.sock:/containers/json')
+ got('http://unix:/var/run/docker.sock:/containers/json')- Breaking
The
retryWithMergedOptionsfunction in anafterResponsehook no longer returns aPromise.
It now throws RetryError, so this should this should be the last function being executed.
This was done to allow beforeRetry hooks getting called.
- Breaking
You can no longer set
options.agenttofalse.
To do so, you need to define all theoptions.agentproperties:http,httpsandhttp2.
await got('https://example.com', {
- agent: false
+ agent: {
+ http: false,
+ https: false,
+ http2: false
+ }
})- Breaking
When passing a
urloption when paginating, it now needs to be an absolute URL - theprefixUrloption is always reset from now on. The same when retrying in anafterResponsehook.
- return {url: '/location'};
+ return {url: new URL('/location', response.request.options.url)};There was confusion around the prefixUrl option. It was counterintuitive if used with the Pagination API. For example, it worked fine if the server replied with a relative URL, but if it was an absolute URL then the prefixUrl would end up duplicated. In order to fix this, Got now requires an absolute URL - no prefixUrl will be applied.
- Breaking
got.extend(…)will throw when passing some options that don't accept undefined - undefined no longer retains the old value, as setting undefined explicitly may reset the option
Documentation
We have redesigned the documentation so it's easier to navigate and find exactly what you are looking for. We hope you like it :heart:
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.