got 14.4.9 → 14.6.0

package/dist/source/core/options.js

@@ -11,11 +11,43 @@ import http2wrapper from 'http2-wrapper';
 import { isFormData } from 'form-data-encoder';
 import parseLinkHeader from './parse-link-header.js';
 const [major, minor] = process.versions.node.split('.').map(Number);
+/**
+Generic helper that wraps any assertion function to add context to error messages.
+*/
+function wrapAssertionWithContext(optionName, assertionFn) {
+    try {
+        assertionFn();
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            error.message = `Option '${optionName}': ${error.message}`;
+        }
+        throw error;
+    }
+}
+/**
+Helper function that wraps assert.any() to provide better error messages.
+When assertion fails, it includes the option name in the error message.
+*/
+function assertAny(optionName, validators, value) {
+    wrapAssertionWithContext(optionName, () => {
+        assert.any(validators, value);
+    });
+}
+/**
+Helper function that wraps assert.plainObject() to provide better error messages.
+When assertion fails, it includes the option name in the error message.
+*/
+function assertPlainObject(optionName, value) {
+    wrapAssertionWithContext(optionName, () => {
+        assert.plainObject(value);
+    });
+}
 function validateSearchParameters(searchParameters) {
     // eslint-disable-next-line guard-for-in
     for (const key in searchParameters) {
         const value = searchParameters[key];
-        assert.any([is.string, is.number, is.boolean, is.null, is.undefined], value);
+        assertAny(`searchParams.${key}`, [is.string, is.number, is.boolean, is.null, is.undefined], value);
     }
 }
 const globalCache = new Map();
@@ -27,6 +59,39 @@ const getGlobalDnsCache = () => {
     globalDnsCache = new CacheableLookup();
     return globalDnsCache;
 };
+// Detects and wraps QuickLRU v7+ instances to make them compatible with the StorageAdapter interface
+const wrapQuickLruIfNeeded = (value) => {
+    // Check if this is QuickLRU v7+ using Symbol.toStringTag and the evict method (added in v7)
+    if (value?.[Symbol.toStringTag] === 'QuickLRU' && typeof value.evict === 'function') {
+        // QuickLRU v7+ uses set(key, value, {maxAge: number}) but StorageAdapter expects set(key, value, ttl)
+        // Wrap it to translate the interface
+        return {
+            get(key) {
+                return value.get(key);
+            },
+            set(key, cacheValue, ttl) {
+                if (ttl === undefined) {
+                    value.set(key, cacheValue);
+                }
+                else {
+                    value.set(key, cacheValue, { maxAge: ttl });
+                }
+                return true;
+            },
+            delete(key) {
+                return value.delete(key);
+            },
+            clear() {
+                return value.clear();
+            },
+            has(key) {
+                return value.has(key);
+            },
+        };
+    }
+    // QuickLRU v5 and other caches work as-is
+    return value;
+};
 const defaultInternals = {
     request: undefined,
     agent: {
@@ -115,6 +180,8 @@ const defaultInternals = {
         calculateDelay: ({ computedValue }) => computedValue,
         backoffLimit: Number.POSITIVE_INFINITY,
         noise: 100,
+        // TODO: Change default to `true` in the next major version to fix https://github.com/sindresorhus/got/issues/2243
+        enforceRetryRules: false,
     },
     localAddress: undefined,
     method: 'GET',
@@ -129,6 +196,7 @@ const defaultInternals = {
         alpnProtocols: undefined,
         rejectUnauthorized: undefined,
         checkServerIdentity: undefined,
+        serverName: undefined,
         certificateAuthority: undefined,
         key: undefined,
         certificate: undefined,
@@ -143,6 +211,7 @@ const defaultInternals = {
         dhparam: undefined,
         ecdhCurve: undefined,
         certificateRevocationLists: undefined,
+        secureOptions: undefined,
     },
     encoding: undefined,
     resolveBodyOnly: false,
@@ -181,6 +250,7 @@ const defaultInternals = {
     maxHeaderSize: undefined,
     signal: undefined,
     enableUnixSockets: false,
+    strictContentLength: false,
 };
 const cloneInternals = (internals) => {
     const { hooks, retry } = internals;
@@ -300,9 +370,9 @@ export default class Options {
     _merging;
     _init;
     constructor(input, options, defaults) {
-        assert.any([is.string, is.urlInstance, is.object, is.undefined], input);
-        assert.any([is.object, is.undefined], options);
-        assert.any([is.object, is.undefined], defaults);
+        assertAny('input', [is.string, is.urlInstance, is.object, is.undefined], input);
+        assertAny('options', [is.object, is.undefined], options);
+        assertAny('defaults', [is.object, is.undefined], defaults);
         if (input instanceof Options || options instanceof Options) {
             throw new TypeError('The defaults must be passed as the third argument');
         }
@@ -386,6 +456,10 @@ export default class Options {
                 if (key === 'url') {
                     continue;
                 }
+                // Never merge `preserveHooks` - it's a control flag, not a persistent option
+                if (key === 'preserveHooks') {
+                    continue;
+                }
                 if (!(key in this)) {
                     throw new Error(`Unexpected option: ${key}`);
                 }
@@ -416,7 +490,7 @@ export default class Options {
         return this._internals.request;
     }
     set request(value) {
-        assert.any([is.function, is.undefined], value);
+        assertAny('request', [is.function, is.undefined], value);
         this._internals.request = value;
     }
     /**
@@ -445,14 +519,14 @@ export default class Options {
         return this._internals.agent;
     }
     set agent(value) {
-        assert.plainObject(value);
+        assertPlainObject('agent', value);
         // eslint-disable-next-line guard-for-in
         for (const key in value) {
             if (!(key in this._internals.agent)) {
                 throw new TypeError(`Unexpected agent option: ${key}`);
             }
             // @ts-expect-error - No idea why `value[key]` doesn't work here.
-            assert.any([is.object, is.undefined], value[key]);
+            assertAny(`agent.${key}`, [is.object, is.undefined, (v) => v === false], value[key]);
         }
         if (this._merging) {
             Object.assign(this._internals.agent, value);
@@ -505,14 +579,14 @@ export default class Options {
         return this._internals.timeout;
     }
     set timeout(value) {
-        assert.plainObject(value);
+        assertPlainObject('timeout', value);
         // eslint-disable-next-line guard-for-in
         for (const key in value) {
             if (!(key in this._internals.timeout)) {
                 throw new Error(`Unexpected timeout option: ${key}`);
             }
             // @ts-expect-error - No idea why `value[key]` doesn't work here.
-            assert.any([is.number, is.undefined], value[key]);
+            assertAny(`timeout.${key}`, [is.number, is.undefined], value[key]);
         }
         if (this._merging) {
             Object.assign(this._internals.timeout, value);
@@ -566,7 +640,7 @@ export default class Options {
         return this._internals.prefixUrl;
     }
     set prefixUrl(value) {
-        assert.any([is.string, is.urlInstance], value);
+        assertAny('prefixUrl', [is.string, is.urlInstance], value);
         if (value === '') {
             this._internals.prefixUrl = '';
             return;
@@ -590,15 +664,32 @@ export default class Options {
 
     __Note #4__: This option is not enumerable and will not be merged with the instance defaults.
 
-    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
+    The `content-length` header will be automatically set if `body` is a `string` / `Buffer` / typed array ([`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array), etc.) / [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) / [`form-data` instance](https://github.com/form-data/form-data), and `content-length` and `transfer-encoding` are not manually set in `options.headers`.
 
     Since Got 12, the `content-length` is not automatically set when `body` is a `fs.createReadStream`.
+
+    You can use `Iterable` and `AsyncIterable` objects as request body, including Web [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream):
+
+    @example
+    ```
+    import got from 'got';
+
+    // Using an async generator
+    async function* generateData() {
+        yield 'Hello, ';
+        yield 'world!';
+    }
+
+    await got.post('https://httpbin.org/anything', {
+        body: generateData()
+    });
+    ```
     */
     get body() {
         return this._internals.body;
     }
     set body(value) {
-        assert.any([is.string, is.buffer, is.nodeStream, is.generator, is.asyncGenerator, isFormData, is.undefined], value);
+        assertAny('body', [is.string, is.buffer, is.nodeStream, is.generator, is.asyncGenerator, is.iterable, is.asyncIterable, isFormData, is.typedArray, is.undefined], value);
         if (is.nodeStream(value)) {
             assert.truthy(value.readable);
         }
@@ -621,7 +712,7 @@ export default class Options {
         return this._internals.form;
     }
     set form(value) {
-        assert.any([is.plainObject, is.undefined], value);
+        assertAny('form', [is.plainObject, is.undefined], value);
         if (value !== undefined) {
             assert.undefined(this._internals.body);
             assert.undefined(this._internals.json);
@@ -629,7 +720,9 @@ export default class Options {
         this._internals.form = value;
     }
     /**
-    JSON body. If the `Content-Type` header is not set, it will be set to `application/json`.
+    JSON request body. If the `content-type` header is not set, it will be set to `application/json`.
+
+    __Important__: This option only affects the request body you send to the server. To parse the response as JSON, you must either call `.json()` on the promise or set `responseType: 'json'` in the options.
 
     __Note #1__: If you provide this option, `got.stream()` will be read-only.
 
@@ -667,7 +760,7 @@ export default class Options {
         return this._internals.url;
     }
     set url(value) {
-        assert.any([is.string, is.urlInstance, is.undefined], value);
+        assertAny('url', [is.string, is.urlInstance, is.undefined], value);
         if (value === undefined) {
             this._internals.url = undefined;
             return;
@@ -727,7 +820,7 @@ export default class Options {
         return this._internals.cookieJar;
     }
     set cookieJar(value) {
-        assert.any([is.object, is.undefined], value);
+        assertAny('cookieJar', [is.object, is.undefined], value);
         if (value === undefined) {
             this._internals.cookieJar = undefined;
             return;
@@ -814,7 +907,7 @@ export default class Options {
         return this._internals.searchParams;
     }
     set searchParams(value) {
-        assert.any([is.string, is.object, is.undefined], value);
+        assertAny('searchParams', [is.string, is.object, is.undefined], value);
         const url = this._internals.url;
         if (value === undefined) {
             this._internals.searchParams = undefined;
@@ -874,7 +967,7 @@ export default class Options {
         return this._internals.dnsLookup;
     }
     set dnsLookup(value) {
-        assert.any([is.function, is.undefined], value);
+        assertAny('dnsLookup', [is.function, is.undefined], value);
         this._internals.dnsLookup = value;
     }
     /**
@@ -891,7 +984,7 @@ export default class Options {
         return this._internals.dnsCache;
     }
     set dnsCache(value) {
-        assert.any([is.object, is.boolean, is.undefined], value);
+        assertAny('dnsCache', [is.object, is.boolean, is.undefined], value);
         if (value === true) {
             this._internals.dnsCache = getGlobalDnsCache();
         }
@@ -961,7 +1054,7 @@ export default class Options {
             }
             const typedKnownHookEvent = knownHookEvent;
             const hooks = value[typedKnownHookEvent];
-            assert.any([is.array, is.undefined], hooks);
+            assertAny(`hooks.${knownHookEvent}`, [is.array, is.undefined], hooks);
             if (hooks) {
                 for (const hook of hooks) {
                     assert.function(hook);
@@ -996,7 +1089,7 @@ export default class Options {
         return this._internals.followRedirect;
     }
     set followRedirect(value) {
-        assert.any([is.boolean, is.function], value);
+        assertAny('followRedirect', [is.boolean, is.function], value);
         this._internals.followRedirect = value;
     }
     get followRedirects() {
@@ -1026,7 +1119,7 @@ export default class Options {
         return this._internals.cache;
     }
     set cache(value) {
-        assert.any([is.object, is.string, is.boolean, is.undefined], value);
+        assertAny('cache', [is.object, is.string, is.boolean, is.undefined], value);
         if (value === true) {
             this._internals.cache = globalCache;
         }
@@ -1034,7 +1127,7 @@ export default class Options {
             this._internals.cache = undefined;
         }
         else {
-            this._internals.cache = value;
+            this._internals.cache = wrapQuickLruIfNeeded(value);
         }
     }
     /**
@@ -1139,7 +1232,7 @@ export default class Options {
         return this._internals.headers;
     }
     set headers(value) {
-        assert.plainObject(value);
+        assertPlainObject('headers', value);
         if (this._merging) {
             Object.assign(this._internals.headers, lowercaseKeys(value));
         }
@@ -1261,7 +1354,9 @@ export default class Options {
     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).
 
-    __Note:__ When you provide `calculateDelay`, you take full control of retry decisions. The `limit` option is not automatically enforced - you must check `attemptCount` yourself or return `0` when `computedValue` is `0` to respect the default retry logic.
+    The `enforceRetryRules` property is a `boolean` that, when set to `true`, 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` (default), `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 the default retry logic. When `true`, the retry rules are enforced automatically.
 
     By default, it retries *only* on the specified methods, status codes, and on these network errors:
 
@@ -1281,14 +1376,15 @@ export default class Options {
         return this._internals.retry;
     }
     set retry(value) {
-        assert.plainObject(value);
-        assert.any([is.function, is.undefined], value.calculateDelay);
-        assert.any([is.number, is.undefined], value.maxRetryAfter);
-        assert.any([is.number, is.undefined], value.limit);
-        assert.any([is.array, is.undefined], value.methods);
-        assert.any([is.array, is.undefined], value.statusCodes);
-        assert.any([is.array, is.undefined], value.errorCodes);
-        assert.any([is.number, is.undefined], value.noise);
+        assertPlainObject('retry', value);
+        assertAny('retry.calculateDelay', [is.function, is.undefined], value.calculateDelay);
+        assertAny('retry.maxRetryAfter', [is.number, is.undefined], value.maxRetryAfter);
+        assertAny('retry.limit', [is.number, is.undefined], value.limit);
+        assertAny('retry.methods', [is.array, is.undefined], value.methods);
+        assertAny('retry.statusCodes', [is.array, is.undefined], value.statusCodes);
+        assertAny('retry.errorCodes', [is.array, is.undefined], value.errorCodes);
+        assertAny('retry.noise', [is.number, is.undefined], value.noise);
+        assertAny('retry.enforceRetryRules', [is.boolean, is.undefined], value.enforceRetryRules);
         if (value.noise && Math.abs(value.noise) > 100) {
             throw new Error(`The maximum acceptable retry noise is +/- 100ms, got ${value.noise}`);
         }
@@ -1317,7 +1413,7 @@ export default class Options {
         return this._internals.localAddress;
     }
     set localAddress(value) {
-        assert.any([is.string, is.undefined], value);
+        assertAny('localAddress', [is.string, is.undefined], value);
         this._internals.localAddress = value;
     }
     /**
@@ -1336,7 +1432,7 @@ export default class Options {
         return this._internals.createConnection;
     }
     set createConnection(value) {
-        assert.any([is.function, is.undefined], value);
+        assertAny('createConnection', [is.function, is.undefined], value);
         this._internals.createConnection = value;
     }
     /**
@@ -1348,11 +1444,11 @@ export default class Options {
         return this._internals.cacheOptions;
     }
     set cacheOptions(value) {
-        assert.plainObject(value);
-        assert.any([is.boolean, is.undefined], value.shared);
-        assert.any([is.number, is.undefined], value.cacheHeuristic);
-        assert.any([is.number, is.undefined], value.immutableMinTimeToLive);
-        assert.any([is.boolean, is.undefined], value.ignoreCargoCult);
+        assertPlainObject('cacheOptions', value);
+        assertAny('cacheOptions.shared', [is.boolean, is.undefined], value.shared);
+        assertAny('cacheOptions.cacheHeuristic', [is.number, is.undefined], value.cacheHeuristic);
+        assertAny('cacheOptions.immutableMinTimeToLive', [is.number, is.undefined], value.immutableMinTimeToLive);
+        assertAny('cacheOptions.ignoreCargoCult', [is.boolean, is.undefined], value.ignoreCargoCult);
         for (const key in value) {
             if (!(key in this._internals.cacheOptions)) {
                 throw new Error(`Cache option \`${key}\` does not exist`);
@@ -1372,24 +1468,26 @@ export default class Options {
         return this._internals.https;
     }
     set https(value) {
-        assert.plainObject(value);
-        assert.any([is.boolean, is.undefined], value.rejectUnauthorized);
-        assert.any([is.function, is.undefined], value.checkServerIdentity);
-        assert.any([is.string, is.object, is.array, is.undefined], value.certificateAuthority);
-        assert.any([is.string, is.object, is.array, is.undefined], value.key);
-        assert.any([is.string, is.object, is.array, is.undefined], value.certificate);
-        assert.any([is.string, is.undefined], value.passphrase);
-        assert.any([is.string, is.buffer, is.array, is.undefined], value.pfx);
-        assert.any([is.array, is.undefined], value.alpnProtocols);
-        assert.any([is.string, is.undefined], value.ciphers);
-        assert.any([is.string, is.buffer, is.undefined], value.dhparam);
-        assert.any([is.string, is.undefined], value.signatureAlgorithms);
-        assert.any([is.string, is.undefined], value.minVersion);
-        assert.any([is.string, is.undefined], value.maxVersion);
-        assert.any([is.boolean, is.undefined], value.honorCipherOrder);
-        assert.any([is.number, is.undefined], value.tlsSessionLifetime);
-        assert.any([is.string, is.undefined], value.ecdhCurve);
-        assert.any([is.string, is.buffer, is.array, is.undefined], value.certificateRevocationLists);
+        assertPlainObject('https', value);
+        assertAny('https.rejectUnauthorized', [is.boolean, is.undefined], value.rejectUnauthorized);
+        assertAny('https.checkServerIdentity', [is.function, is.undefined], value.checkServerIdentity);
+        assertAny('https.serverName', [is.string, is.undefined], value.serverName);
+        assertAny('https.certificateAuthority', [is.string, is.object, is.array, is.undefined], value.certificateAuthority);
+        assertAny('https.key', [is.string, is.object, is.array, is.undefined], value.key);
+        assertAny('https.certificate', [is.string, is.object, is.array, is.undefined], value.certificate);
+        assertAny('https.passphrase', [is.string, is.undefined], value.passphrase);
+        assertAny('https.pfx', [is.string, is.buffer, is.array, is.undefined], value.pfx);
+        assertAny('https.alpnProtocols', [is.array, is.undefined], value.alpnProtocols);
+        assertAny('https.ciphers', [is.string, is.undefined], value.ciphers);
+        assertAny('https.dhparam', [is.string, is.buffer, is.undefined], value.dhparam);
+        assertAny('https.signatureAlgorithms', [is.string, is.undefined], value.signatureAlgorithms);
+        assertAny('https.minVersion', [is.string, is.undefined], value.minVersion);
+        assertAny('https.maxVersion', [is.string, is.undefined], value.maxVersion);
+        assertAny('https.honorCipherOrder', [is.boolean, is.undefined], value.honorCipherOrder);
+        assertAny('https.tlsSessionLifetime', [is.number, is.undefined], value.tlsSessionLifetime);
+        assertAny('https.ecdhCurve', [is.string, is.undefined], value.ecdhCurve);
+        assertAny('https.certificateRevocationLists', [is.string, is.buffer, is.array, is.undefined], value.certificateRevocationLists);
+        assertAny('https.secureOptions', [is.number, is.undefined], value.secureOptions);
         for (const key in value) {
             if (!(key in this._internals.https)) {
                 throw new Error(`HTTPS option \`${key}\` does not exist`);
@@ -1419,7 +1517,7 @@ export default class Options {
         if (value === null) {
             throw new TypeError('To get a Buffer, set `options.responseType` to `buffer` instead');
         }
-        assert.any([is.string, is.undefined], value);
+        assertAny('encoding', [is.string, is.undefined], value);
         this._internals.encoding = value;
     }
     /**
@@ -1519,7 +1617,7 @@ export default class Options {
         return this._internals.maxHeaderSize;
     }
     set maxHeaderSize(value) {
-        assert.any([is.number, is.undefined], value);
+        assertAny('maxHeaderSize', [is.number, is.undefined], value);
         this._internals.maxHeaderSize = value;
     }
     get enableUnixSockets() {
@@ -1529,6 +1627,23 @@ export default class Options {
         assert.boolean(value);
         this._internals.enableUnixSockets = value;
     }
+    /**
+    Throw an error if the server response's `content-length` header value doesn't match the number of bytes received.
+
+    This is useful for detecting truncated responses and follows RFC 9112 requirements for message completeness.
+
+    __Note__: Responses without a `content-length` header are not validated.
+    __Note__: When enabled and validation fails, a `ReadError` with code `ERR_HTTP_CONTENT_LENGTH_MISMATCH` will be thrown.
+
+    @default false
+    */
+    get strictContentLength() {
+        return this._internals.strictContentLength;
+    }
+    set strictContentLength(value) {
+        assert.boolean(value);
+        this._internals.strictContentLength = value;
+    }
     // eslint-disable-next-line @typescript-eslint/naming-convention
     toJSON() {
         return { ...this._internals };
@@ -1541,7 +1656,17 @@ export default class Options {
         const url = internals.url;
         let agent;
         if (url.protocol === 'https:') {
-            agent = internals.http2 ? internals.agent : internals.agent.https;
+            if (internals.http2) {
+                // Ensure HTTP/2 agent is configured for connection reuse
+                // If no custom agent.http2 is provided, use the global agent for connection pooling
+                agent = {
+                    ...internals.agent,
+                    http2: internals.agent.http2 ?? http2wrapper.globalAgent,
+                };
+            }
+            else {
+                agent = internals.agent.https;
+            }
         }
         else {
             agent = internals.agent.http;
@@ -1567,6 +1692,7 @@ export default class Options {
             pfx: https.pfx,
             rejectUnauthorized: https.rejectUnauthorized,
             checkServerIdentity: https.checkServerIdentity ?? checkServerIdentity,
+            servername: https.serverName,
             ciphers: https.ciphers,
             honorCipherOrder: https.honorCipherOrder,
             minVersion: https.minVersion,
@@ -1576,6 +1702,7 @@ export default class Options {
             dhparam: https.dhparam,
             ecdhCurve: https.ecdhCurve,
             crl: https.certificateRevocationLists,
+            secureOptions: https.secureOptions,
             // HTTP options
             lookup: internals.dnsLookup ?? internals.dnsCache?.lookup,
             family: internals.dnsLookupIpVersion,

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

@@ -15,8 +15,24 @@ export default async function getBodySize(body, headers) {
     if (is.buffer(body)) {
         return body.length;
     }
+    if (is.typedArray(body)) {
+        return body.byteLength;
+    }
     if (isFormData(body)) {
-        return promisify(body.getLength.bind(body))();
+        try {
+            return await promisify(body.getLength.bind(body))();
+        }
+        catch (error) {
+            const typedError = error;
+            throw new Error('Cannot determine content-length for form-data with stream(s) of unknown length. '
+                + 'This is a limitation of the `form-data` package. '
+                + 'To fix this, either:\n'
+                + '1. Use the `knownLength` option when appending streams:\n'
+                + '   form.append(\'file\', stream, {knownLength: 12345});\n'
+                + '2. Switch to spec-compliant FormData (formdata-node package)\n'
+                + 'See: https://github.com/form-data/form-data#alternative-submission-methods\n'
+                + `Original error: ${typedError.message}`);
+        }
     }
     return undefined;
 }

package/dist/source/core/utils/is-unix-socket-url.d.ts

@@ -1 +1,17 @@
 export default function isUnixSocketURL(url: URL): boolean;
+/**
+Extract the socket path from a UNIX socket URL.
+
+@example
+```
+getUnixSocketPath(new URL('http://unix/foo:/path'));
+//=> '/foo'
+
+getUnixSocketPath(new URL('unix:/foo:/path'));
+//=> '/foo'
+
+getUnixSocketPath(new URL('http://example.com'));
+//=> undefined
+```
+*/
+export declare function getUnixSocketPath(url: URL): string | undefined;

package/dist/source/core/utils/is-unix-socket-url.js

@@ -2,3 +2,24 @@
 export default function isUnixSocketURL(url) {
     return url.protocol === 'unix:' || url.hostname === 'unix';
 }
+/**
+Extract the socket path from a UNIX socket URL.
+
+@example
+```
+getUnixSocketPath(new URL('http://unix/foo:/path'));
+//=> '/foo'
+
+getUnixSocketPath(new URL('unix:/foo:/path'));
+//=> '/foo'
+
+getUnixSocketPath(new URL('http://example.com'));
+//=> undefined
+```
+*/
+export function getUnixSocketPath(url) {
+    if (!isUnixSocketURL(url)) {
+        return undefined;
+    }
+    return /(?<socketPath>.+?):(?<path>.+)/.exec(`${url.pathname}${url.search}`)?.groups?.socketPath;
+}

package/dist/source/create.js

@@ -139,7 +139,15 @@ const create = (defaults) => {
             }
             else {
                 normalizedOptions.merge(optionsToMerge);
-                assert.any([is.urlInstance, is.undefined], optionsToMerge.url);
+                try {
+                    assert.any([is.urlInstance, is.undefined], optionsToMerge.url);
+                }
+                catch (error) {
+                    if (error instanceof Error) {
+                        error.message = `Option 'pagination.paginate.url': ${error.message}`;
+                    }
+                    throw error;
+                }
                 if (optionsToMerge.url !== undefined) {
                     normalizedOptions.prefixUrl = '';
                     normalizedOptions.url = optionsToMerge.url;