@microlink/mql 0.15.1 → 0.16.0

package/dist/index.js

@@ -63,23 +63,53 @@ function flattie(input, glue, toNull) {
 
 dist.flattie = flattie;
 
-class HTTPError extends Error {
+/**
+Base class for all Ky-specific errors. `HTTPError`, `NetworkError`, `TimeoutError`, and `ForceRetryError` extend this class.
+*/
+class KyError extends Error {
+    name = 'KyError';
+    get isKyError() {
+        return true;
+    }
+}
+
+/**
+Error thrown when the response has a non-2xx status code and `throwHttpErrors` is enabled.
+
+The error has a `response` property with the `Response` object, a `request` property with the `Request` object, an `options` property with the normalized options, and a `data` property with the pre-parsed response body. The response body is automatically consumed when populating `data`, so `response.json()` and other body methods will not work. Use `data` instead.
+*/
+class HTTPError extends KyError {
+    name = 'HTTPError';
     response;
     request;
     options;
+    data;
     constructor(response, request, options) {
         const code = (response.status || response.status === 0) ? response.status : '';
         const title = response.statusText ?? '';
         const status = `${code} ${title}`.trim();
         const reason = status ? `status code ${status}` : 'an unknown error';
         super(`Request failed with ${reason}: ${request.method} ${request.url}`);
-        this.name = 'HTTPError';
         this.response = response;
         this.request = request;
         this.options = options;
     }
 }
 
+/**
+Error thrown when a network error occurs during the request (e.g., DNS failure, connection refused, offline).
+
+The error has a `request` property with the `Request` object. The original error is available via the standard `cause` property.
+*/
+class NetworkError extends KyError {
+    name = 'NetworkError';
+    request;
+    constructor(request, options) {
+        super(`Request failed due to a network error: ${request.method} ${request.url}`, options);
+        this.request = request;
+    }
+}
+
 /**
 Wrapper for non-Error values that were thrown.
 
@@ -108,10 +138,11 @@ class NonError extends Error {
 }
 
 /**
-Internal error used to signal a forced retry from afterResponse hooks.
-This is thrown when a user returns ky.retry() from an afterResponse hook.
+Error used to signal a forced retry from `afterResponse` hooks.
+
+This is thrown when `ky.retry()` is returned from an `afterResponse` hook. It is observable in `beforeRetry` and `beforeError` hooks via the `isForceRetryError()` type guard.
 */
-class ForceRetryError extends Error {
+class ForceRetryError extends KyError {
     name = 'ForceRetryError';
     customDelay;
     code;
@@ -129,6 +160,51 @@ class ForceRetryError extends Error {
     }
 }
 
+/**
+Thrown when a response body fails validation against a user-provided Standard Schema.
+
+This error intentionally does not extend `KyError` because it does not represent a failure in Ky's HTTP lifecycle. The request succeeded; the user's schema rejected the data. As such, it is not matched by `isKyError()`.
+
+@example
+```
+import ky, {SchemaValidationError} from 'ky';
+import {z} from 'zod';
+
+const userSchema = z.object({name: z.string()});
+
+try {
+    const user = await ky('/api/user').json(userSchema);
+    console.log(user.name);
+} catch (error) {
+    if (error instanceof SchemaValidationError) {
+        console.error(error.issues);
+    }
+}
+```
+*/
+class SchemaValidationError extends Error {
+    name = 'SchemaValidationError';
+    issues;
+    constructor(issues) {
+        super('Response schema validation failed');
+        this.issues = issues;
+    }
+}
+
+/**
+Error thrown when the request times out.
+
+The error has a `request` property with the `Request` object.
+*/
+class TimeoutError extends KyError {
+    name = 'TimeoutError';
+    request;
+    constructor(request) {
+        super(`Request timed out: ${request.method} ${request.url}`);
+        this.request = request;
+    }
+}
+
 const supportsRequestStreams = (() => {
     let duplexAccessed = false;
     let hasContentType = false;
@@ -173,11 +249,14 @@ const responseTypes = {
 };
 // The maximum value of a 32bit int (see issue #117)
 const maxSafeTimeout = 2_147_483_647;
-// Size in bytes of a typical form boundary, used to help estimate upload size
-const usualFormBoundarySize = new TextEncoder().encode('------WebKitFormBoundaryaxpyiPgbbPti10Rw').length;
+// Size in bytes of a typical form boundary (e.g., '------WebKitFormBoundaryaxpyiPgbbPti10Rw'), used to help estimate upload size
+const usualFormBoundarySize = 40;
+/**
+Symbol that can be returned by a `beforeRetry` hook to stop retrying without throwing an error.
+*/
 const stop = Symbol('stop');
 /**
-Marker returned by ky.retry() to signal a forced retry from afterResponse hooks.
+Marker returned by `ky.retry()` to signal a forced retry from `afterResponse` hooks.
 */
 class RetryMarker {
     options;
@@ -199,7 +278,7 @@ import ky, {isForceRetryError} from 'ky';
 const api = ky.extend({
     hooks: {
         afterResponse: [
-            async (request, options, response) => {
+            async ({request, response}) => {
                 // Retry based on response body content
                 if (response.status === 200) {
                     const data = await response.clone().json();
@@ -274,9 +353,11 @@ const kyOptionKeys = {
     parseJson: true,
     stringifyJson: true,
     searchParams: true,
-    prefixUrl: true,
+    baseUrl: true,
+    prefix: true,
     retry: true,
     timeout: true,
+    totalTimeout: true,
     hooks: true,
     throwHttpErrors: true,
     onDownloadProgress: true,
@@ -312,7 +393,8 @@ const requestOptionsRegistry = {
     duplex: true,
 };
 
-// eslint-disable-next-line @typescript-eslint/ban-types
+const encoder = new TextEncoder();
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
 const getBodySize = (body) => {
     if (!body) {
         return 0;
@@ -322,9 +404,9 @@ const getBodySize = (body) => {
         let size = 0;
         for (const [key, value] of body) {
             size += usualFormBoundarySize;
-            size += new TextEncoder().encode(`Content-Disposition: form-data; name="${key}"`).length;
+            size += encoder.encode(`Content-Disposition: form-data; name="${key}"`).byteLength;
             size += typeof value === 'string'
-                ? new TextEncoder().encode(value).length
+                ? encoder.encode(value).byteLength
                 : value.size;
         }
         return size;
@@ -332,28 +414,16 @@ const getBodySize = (body) => {
     if (body instanceof Blob) {
         return body.size;
     }
-    if (body instanceof ArrayBuffer) {
+    if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
         return body.byteLength;
     }
     if (typeof body === 'string') {
-        return new TextEncoder().encode(body).length;
+        return encoder.encode(body).byteLength;
     }
     if (body instanceof URLSearchParams) {
-        return new TextEncoder().encode(body.toString()).length;
-    }
-    if ('byteLength' in body) {
-        return (body).byteLength;
+        return encoder.encode(body.toString()).byteLength;
     }
-    if (typeof body === 'object' && body !== null) {
-        try {
-            const jsonString = JSON.stringify(body);
-            return new TextEncoder().encode(jsonString).length;
-        }
-        catch {
-            return 0;
-        }
-    }
-    return 0; // Default case, unable to determine size
+    return 0;
 };
 const withProgress = (stream, totalBytes, onProgress) => {
     let previousChunk;
@@ -386,21 +456,18 @@ const streamResponse = (response, onDownloadProgress) => {
     if (!response.body) {
         return response;
     }
-    if (response.status === 204) {
-        return new Response(null, {
-            status: response.status,
-            statusText: response.statusText,
-            headers: response.headers,
-        });
-    }
-    const totalBytes = Math.max(0, Number(response.headers.get('content-length')) || 0);
-    return new Response(withProgress(response.body, totalBytes, onDownloadProgress), {
+    const responseInit = {
         status: response.status,
         statusText: response.statusText,
         headers: response.headers,
-    });
+    };
+    if (response.status === 204) {
+        return new Response(null, responseInit);
+    }
+    const totalBytes = Math.max(0, Number(response.headers.get('content-length')) || 0);
+    return new Response(withProgress(response.body, totalBytes, onDownloadProgress), responseInit);
 };
-// eslint-disable-next-line @typescript-eslint/ban-types
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
 const streamRequest = (request, onUploadProgress, originalBody) => {
     if (!request.body) {
         return request;
@@ -414,12 +481,46 @@ const streamRequest = (request, onUploadProgress, originalBody) => {
     });
 };
 
-// eslint-disable-next-line @typescript-eslint/ban-types
-const isObject$1 = (value) => value !== null && typeof value === 'object';
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
+const isObject = (value) => value !== null && typeof value === 'object';
+
+const replaceSymbol = Symbol('replaceOption');
+const getReplaceState = (value) => isObject(value) && value[replaceSymbol] === true
+    ? {
+        isReplace: true,
+        value: value.value,
+    }
+    : {
+        isReplace: false,
+        value,
+    };
+/**
+Wraps a value so that `ky.extend()` will replace the parent value instead of merging with it.
+
+By default, `.extend()` deep-merges options with the parent instance: hooks get appended, headers get merged, and search parameters get accumulated. Use `replaceOption` when you want to fully replace a merged property instead.
+
+@example
+```
+import ky, {replaceOption} from 'ky';
+
+const base = ky.create({
+    hooks: {beforeRequest: [addAuth, addTracking]},
+});
 
+// Replaces instead of appending
+const extended = base.extend({
+    hooks: replaceOption({beforeRequest: [onlyThis]}),
+});
+// hooks.beforeRequest is now [onlyThis], not [addAuth, addTracking, onlyThis]
+```
+*/
+const replaceOption = (value) => {
+    const markedValue = { [replaceSymbol]: true, value };
+    return markedValue;
+};
 const validateAndMerge = (...sources) => {
     for (const source of sources) {
-        if ((!isObject$1(source) || Array.isArray(source)) && source !== undefined) {
+        if ((!isObject(source) || Array.isArray(source)) && source !== undefined) {
             throw new TypeError('The `options` argument must be an object');
         }
     }
@@ -439,19 +540,52 @@ const mergeHeaders = (source1 = {}, source2 = {}) => {
     }
     return result;
 };
+const isPlainObject = (value) => {
+    if (!isObject(value) || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+const cloneShallow = (value) => {
+    if (value instanceof URLSearchParams) {
+        return new URLSearchParams(value);
+    }
+    if (value instanceof globalThis.Headers) {
+        return new globalThis.Headers(value);
+    }
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    if (isPlainObject(value)) {
+        const copy = { ...value };
+        return copy;
+    }
+    return value;
+};
+const normalizeHeaderObject = (headers) => Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] !== undefined));
+const mergeHeaderContainers = (source1, source2) => {
+    if (isPlainObject(source1) && isPlainObject(source2)) {
+        return normalizeHeaderObject({ ...source1, ...source2 });
+    }
+    return mergeHeaders(source1, source2);
+};
 function newHookValue(original, incoming, property) {
     return (Object.hasOwn(incoming, property) && incoming[property] === undefined)
         ? []
         : deepMerge(original[property] ?? [], incoming[property] ?? []);
 }
 const mergeHooks = (original = {}, incoming = {}) => ({
+    init: newHookValue(original, incoming, 'init'),
     beforeRequest: newHookValue(original, incoming, 'beforeRequest'),
     beforeRetry: newHookValue(original, incoming, 'beforeRetry'),
-    afterResponse: newHookValue(original, incoming, 'afterResponse'),
     beforeError: newHookValue(original, incoming, 'beforeError'),
+    afterResponse: newHookValue(original, incoming, 'afterResponse'),
 });
+const deletedParametersSymbol = Symbol('deletedParameters');
 const appendSearchParameters = (target, source) => {
     const result = new URLSearchParams();
+    const deleted = new Set();
     for (const input of [target, source]) {
         if (input === undefined) {
             continue;
@@ -459,6 +593,14 @@ const appendSearchParameters = (target, source) => {
         if (input instanceof URLSearchParams) {
             for (const [key, value] of input.entries()) {
                 result.append(key, value);
+                deleted.delete(key);
+            }
+            const inputDeleted = input[deletedParametersSymbol];
+            if (inputDeleted) {
+                for (const key of inputDeleted) {
+                    result.delete(key);
+                    deleted.add(key);
+                }
             }
         }
         else if (Array.isArray(input)) {
@@ -467,12 +609,18 @@ const appendSearchParameters = (target, source) => {
                     throw new TypeError('Array search parameters must be provided in [[key, value], ...] format');
                 }
                 result.append(String(pair[0]), String(pair[1]));
+                deleted.delete(String(pair[0]));
             }
         }
-        else if (isObject$1(input)) {
+        else if (isObject(input)) {
             for (const [key, value] of Object.entries(input)) {
-                if (value !== undefined) {
+                if (value === undefined) {
+                    result.delete(key);
+                    deleted.add(key);
+                }
+                else {
                     result.append(key, String(value));
+                    deleted.delete(key);
                 }
             }
         }
@@ -481,9 +629,13 @@ const appendSearchParameters = (target, source) => {
             const parameters = new URLSearchParams(input);
             for (const [key, value] of parameters.entries()) {
                 result.append(key, value);
+                deleted.delete(key);
             }
         }
     }
+    if (deleted.size > 0) {
+        result[deletedParametersSymbol] = deleted;
+    }
     return result;
 };
 // TODO: Make this strongly-typed (no `any`).
@@ -500,16 +652,19 @@ const deepMerge = (...sources) => {
             }
             returnValue = [...returnValue, ...source];
         }
-        else if (isObject$1(source)) {
+        else if (isObject(source)) {
             for (let [key, value] of Object.entries(source)) {
                 // Special handling for AbortSignal instances
                 if (key === 'signal' && value instanceof globalThis.AbortSignal) {
                     signals.push(value);
                     continue;
                 }
+                const replaceState = getReplaceState(value);
+                const { isReplace } = replaceState;
+                value = replaceState.value;
                 // Special handling for context - shallow merge only
                 if (key === 'context') {
-                    if (value !== undefined && value !== null && (!isObject$1(value) || Array.isArray(value))) {
+                    if (value !== undefined && value !== null && (!isObject(value) || Array.isArray(value))) {
                         throw new TypeError('The `context` option must be an object');
                     }
                     // Shallow merge: always create a new object to prevent mutation bugs
@@ -517,7 +672,9 @@ const deepMerge = (...sources) => {
                         ...returnValue,
                         context: (value === undefined || value === null)
                             ? {}
-                            : { ...returnValue.context, ...value },
+                            : (isReplace
+                                ? { ...value }
+                                : { ...returnValue.context, ...value }),
                     };
                     continue;
                 }
@@ -527,6 +684,9 @@ const deepMerge = (...sources) => {
                         // Explicit undefined or null removes searchParams
                         searchParameters = undefined;
                     }
+                    else if (isReplace) {
+                        searchParameters = value;
+                    }
                     else {
                         // First source: keep as-is to preserve type (string/object/URLSearchParams)
                         // Subsequent sources: merge and convert to URLSearchParams
@@ -534,17 +694,23 @@ const deepMerge = (...sources) => {
                     }
                     continue;
                 }
-                if (isObject$1(value) && key in returnValue) {
+                if (isObject(value) && !isReplace && key in returnValue) {
                     value = deepMerge(returnValue[key], value);
                 }
                 returnValue = { ...returnValue, [key]: value };
             }
-            if (isObject$1(source.hooks)) {
-                hooks = mergeHooks(hooks, source.hooks);
+            if (isObject(source.hooks)) {
+                const { value: hookValue, isReplace } = getReplaceState(source.hooks);
+                hooks = isReplace
+                    ? mergeHooks({}, hookValue)
+                    : mergeHooks(hooks, hookValue);
                 returnValue.hooks = hooks;
             }
-            if (isObject$1(source.headers)) {
-                headers = mergeHeaders(headers, source.headers);
+            if (isObject(source.headers)) {
+                const { value: headerValue, isReplace } = getReplaceState(source.headers);
+                headers = isReplace
+                    ? cloneShallow(headerValue)
+                    : mergeHeaderContainers(headers, headerValue);
                 returnValue.headers = headers;
             }
         }
@@ -605,15 +771,6 @@ const normalizeRetryOptions = (retry = {}) => {
     };
 };
 
-class TimeoutError extends Error {
-    request;
-    constructor(request) {
-        super(`Request timed out: ${request.method} ${request.url}`);
-        this.name = 'TimeoutError';
-        this.request = request;
-    }
-}
-
 // `Promise.race()` workaround (#91)
 async function timeout(request, init, abortController, options) {
     return new Promise((resolve, reject) => {
@@ -679,7 +836,7 @@ const hasSearchParameters = (search) => {
         return search.length > 0;
     }
     if (search instanceof URLSearchParams) {
-        return search.size > 0;
+        return search.size > 0 || Boolean(search[deletedParametersSymbol]?.size);
     }
     // Record
     if (typeof search === 'object') {
@@ -691,8 +848,52 @@ const hasSearchParameters = (search) => {
     return Boolean(search);
 };
 
+// Inlined from https://github.com/sindresorhus/is-network-error v1.3.1
+const objectToString = Object.prototype.toString;
+const isError = (value) => objectToString.call(value) === '[object Error]';
+const errorMessages = new Set([
+    'network error', // Chrome
+    'NetworkError when attempting to fetch resource.', // Firefox
+    'The Internet connection appears to be offline.', // Safari 16
+    'Network request failed', // `cross-fetch`
+    'fetch failed', // Undici (Node.js)
+    'terminated', // Undici (Node.js)
+    ' A network error occurred.', // Bun (WebKit) - leading space is intentional
+    'Network connection lost', // Cloudflare Workers (fetch)
+]);
+function isRawNetworkError(error) {
+    const isValid = error
+        && isError(error)
+        && error.name === 'TypeError'
+        && typeof error.message === 'string';
+    if (!isValid) {
+        return false;
+    }
+    const { message, stack } = error;
+    // Safari 17+ has generic message but no stack for network errors
+    if (message === 'Load failed') {
+        return stack === undefined
+            // Sentry adds its own stack trace to the fetch error, so also check for that
+            || '__sentry_captured__' in error;
+    }
+    // Deno network errors start with specific text
+    if (message.startsWith('error sending request for url')) {
+        return true;
+    }
+    // Chrome: exact "Failed to fetch" or with hostname: "Failed to fetch (example.com)"
+    if (message === 'Failed to fetch' || (message.startsWith('Failed to fetch (') && message.endsWith(')'))) {
+        return true;
+    }
+    // Standard network error messages
+    return errorMessages.has(message);
+}
+
+// Handles cross-realm cases (e.g., iframes, different JS contexts) where `instanceof` fails.
+const isErrorType = (error, cls) => error instanceof cls || error?.name === cls.name;
 /**
-Type guard to check if an error is a Ky error.
+Type guard to check if an error is a `KyError`.
+
+Note: `SchemaValidationError` is intentionally not considered a Ky error. `KyError` covers failures in Ky's HTTP lifecycle (bad status, timeout, retry), while schema validation errors originate from the user-provided schema, not from Ky itself.
 
 @param error - The error to check
 @returns `true` if the error is a Ky error, `false` otherwise
@@ -714,13 +915,13 @@ try {
 ```
 */
 function isKyError(error) {
-    return isHTTPError(error) || isTimeoutError(error) || isForceRetryError(error);
+    return error?.isKyError === true || isHTTPError(error) || isNetworkError(error) || isTimeoutError(error) || isForceRetryError(error);
 }
 /**
-Type guard to check if an error is an HTTPError.
+Type guard to check if an error is an `HTTPError`.
 
 @param error - The error to check
-@returns `true` if the error is an HTTPError, `false` otherwise
+@returns `true` if the error is an `HTTPError`, `false` otherwise
 
 @example
 ```
@@ -735,13 +936,34 @@ try {
 ```
 */
 function isHTTPError(error) {
-    return error instanceof HTTPError || (error?.name === HTTPError.name);
+    return isErrorType(error, HTTPError);
 }
 /**
-Type guard to check if an error is a TimeoutError.
+Type guard to check if an error is a `NetworkError`.
 
 @param error - The error to check
-@returns `true` if the error is a TimeoutError, `false` otherwise
+@returns `true` if the error is a `NetworkError`, `false` otherwise
+
+@example
+```
+import ky, {isNetworkError} from 'ky';
+try {
+    const response = await ky.get('/api/data');
+} catch (error) {
+    if (isNetworkError(error)) {
+        console.log('Network error:', error.request.url);
+    }
+}
+```
+*/
+function isNetworkError(error) {
+    return isErrorType(error, NetworkError);
+}
+/**
+Type guard to check if an error is a `TimeoutError`.
+
+@param error - The error to check
+@returns `true` if the error is a `TimeoutError`, `false` otherwise
 
 @example
 ```
@@ -756,13 +978,13 @@ try {
 ```
 */
 function isTimeoutError(error) {
-    return error instanceof TimeoutError || (error?.name === TimeoutError.name);
+    return isErrorType(error, TimeoutError);
 }
 /**
-Type guard to check if an error is a ForceRetryError.
+Type guard to check if an error is a `ForceRetryError`.
 
 @param error - The error to check
-@returns `true` if the error is a ForceRetryError, `false` otherwise
+@returns `true` if the error is a `ForceRetryError`, `false` otherwise
 
 @example
 ```
@@ -782,65 +1004,120 @@ const api = ky.extend({
 ```
 */
 function isForceRetryError(error) {
-    return error instanceof ForceRetryError || (error?.name === ForceRetryError.name);
+    return isErrorType(error, ForceRetryError);
 }
 
+const maxErrorResponseBodySize = 10 * 1024 * 1024;
+const prefixUrlRenamedErrorMessage = 'The `prefixUrl` option has been renamed `prefix` in v2 and enhanced to allow slashes in input. See also the new `baseUrl` option for improved flexibility with standard URL resolution: https://github.com/sindresorhus/ky#baseurl';
+const timedOutResponseData = Symbol('timedOutResponseData');
+const createTextDecoder = (contentType) => {
+    const match = /;\s*charset\s*=\s*(?:"([^"]+)"|([^;,\s]+))/i.exec(contentType);
+    const charset = match?.[1] ?? match?.[2];
+    if (charset) {
+        try {
+            return new TextDecoder(charset);
+        }
+        catch { }
+    }
+    return new TextDecoder();
+};
+const invalidSchemaMessage = 'The `schema` argument must follow the Standard Schema specification';
+// Shallow-clone mutable option properties so init hook mutations don't leak across requests.
+function cloneInitHookOptions(options) {
+    return {
+        ...options,
+        json: cloneShallow(options.json),
+        retry: cloneShallow(options.retry),
+        context: cloneShallow(options.context),
+        headers: cloneShallow(options.headers),
+        searchParams: cloneShallow(options.searchParams),
+    };
+}
+const validateJsonWithSchema = async (jsonValue, schema) => {
+    if ((typeof schema !== 'object'
+        && typeof schema !== 'function')
+        || schema === null) {
+        throw new TypeError(invalidSchemaMessage);
+    }
+    const standardSchema = schema['~standard'];
+    if (typeof standardSchema !== 'object'
+        || standardSchema === null
+        || typeof standardSchema.validate !== 'function') {
+        throw new TypeError(invalidSchemaMessage);
+    }
+    const validationResult = await standardSchema.validate(jsonValue);
+    if (validationResult.issues) {
+        throw new SchemaValidationError(validationResult.issues);
+    }
+    return validationResult.value;
+};
 class Ky {
     static create(input, options) {
-        const ky = new Ky(input, options);
+        const initHooks = options.hooks?.init ?? [];
+        const initHookOptions = initHooks.length > 0 ? cloneInitHookOptions(options) : options;
+        for (const hook of initHooks) {
+            hook(initHookOptions);
+        }
+        const ky = new Ky(input, initHookOptions);
         const function_ = async () => {
             if (typeof ky.#options.timeout === 'number' && ky.#options.timeout > maxSafeTimeout) {
                 throw new RangeError(`The \`timeout\` option cannot be greater than ${maxSafeTimeout}`);
             }
+            if (typeof ky.#options.totalTimeout === 'number' && ky.#options.totalTimeout > maxSafeTimeout) {
+                throw new RangeError(`The \`totalTimeout\` option cannot be greater than ${maxSafeTimeout}`);
+            }
             // Delay the fetch so that body method shortcuts can set the Accept header
             await Promise.resolve();
-            // Before using ky.request, _fetch clones it and saves the clone for future retries to use.
-            // If retry is not needed, close the cloned request's ReadableStream for memory safety.
-            let response = await ky.#fetch();
-            for (const hook of ky.#options.hooks.afterResponse) {
-                // Clone the response before passing to hook so we can cancel it if needed
-                const clonedResponse = ky.#decorateResponse(response.clone());
-                let modifiedResponse;
+            const beforeRequestResponse = await ky.#runBeforeRequestHooks();
+            let response = beforeRequestResponse ?? await ky.#retry(async () => ky.#fetch());
+            let responseFromHook = beforeRequestResponse !== undefined
+                || ky.#consumeReturnedResponseFromBeforeRetryHook();
+            if (!(response instanceof globalThis.Response)) {
+                return response;
+            }
+            for (;;) {
                 try {
                     // eslint-disable-next-line no-await-in-loop
-                    modifiedResponse = await hook(ky.request, ky.#getNormalizedOptions(), clonedResponse, { retryCount: ky.#retryCount });
+                    response = await ky.#runAfterResponseHooks(response);
                 }
                 catch (error) {
-                    // Cancel both responses to prevent memory leaks when hook throws
-                    ky.#cancelResponseBody(clonedResponse);
-                    ky.#cancelResponseBody(response);
-                    throw error;
-                }
-                if (modifiedResponse instanceof RetryMarker) {
-                    // Cancel both the cloned response passed to the hook and the current response to prevent resource leaks (especially important in Deno/Bun).
-                    // Do not await cancellation since hooks can clone the response, leaving extra tee branches that keep cancel promises pending per the Streams spec.
-                    ky.#cancelResponseBody(clonedResponse);
-                    ky.#cancelResponseBody(response);
-                    throw new ForceRetryError(modifiedResponse.options);
-                }
-                // Determine which response to use going forward
-                const nextResponse = modifiedResponse instanceof globalThis.Response ? modifiedResponse : response;
-                // Cancel any response bodies we won't use to prevent memory leaks.
-                // Uses fire-and-forget since hooks may have cloned the response, creating tee branches that block cancellation.
-                if (clonedResponse !== nextResponse) {
-                    ky.#cancelResponseBody(clonedResponse);
-                }
-                if (response !== nextResponse) {
-                    ky.#cancelResponseBody(response);
+                    if (!(error instanceof ForceRetryError)) {
+                        throw error;
+                    }
+                    // eslint-disable-next-line no-await-in-loop
+                    const retriedResponse = await ky.#retryFromError(error, async () => ky.#fetch());
+                    if (!(retriedResponse instanceof globalThis.Response)) {
+                        return retriedResponse;
+                    }
+                    response = retriedResponse;
+                    responseFromHook = ky.#consumeReturnedResponseFromBeforeRetryHook();
+                    continue;
                 }
-                response = nextResponse;
-            }
-            ky.#decorateResponse(response);
-            if (!response.ok && (typeof ky.#options.throwHttpErrors === 'function'
-                ? ky.#options.throwHttpErrors(response.status)
-                : ky.#options.throwHttpErrors)) {
-                let error = new HTTPError(response, ky.request, ky.#getNormalizedOptions());
-                for (const hook of ky.#options.hooks.beforeError) {
+                // Opaque responses (`response.type === 'opaque'`) from `no-cors` requests always have `status: 0` and `ok: false`, but this is not a failure - the actual status is hidden by the browser.
+                if (!response.ok && response.type !== 'opaque' && (typeof ky.#options.throwHttpErrors === 'function'
+                    ? ky.#options.throwHttpErrors(response.status)
+                    : ky.#options.throwHttpErrors)) {
+                    // `request` must reflect the request that actually failed, but `options` stays as Ky's
+                    // normalized options snapshot. Replacement `Request` instances do not preserve the
+                    // original `BodyInit`, so trying to make `options` mirror arbitrary requests would be lossy.
+                    const error = new HTTPError(response, ky.#getResponseRequest(response), ky.#getNormalizedOptions());
                     // eslint-disable-next-line no-await-in-loop
-                    error = await hook(error, { retryCount: ky.#retryCount });
+                    error.data = await ky.#getResponseData(response);
+                    if (responseFromHook) {
+                        throw error;
+                    }
+                    // eslint-disable-next-line no-await-in-loop
+                    const retriedResponse = await ky.#retryFromError(error, async () => ky.#fetch());
+                    if (!(retriedResponse instanceof globalThis.Response)) {
+                        return retriedResponse;
+                    }
+                    response = retriedResponse;
+                    responseFromHook = ky.#consumeReturnedResponseFromBeforeRetryHook();
+                    continue;
                 }
-                throw error;
+                break;
             }
+            ky.#decorateResponse(response);
             // If `onDownloadProgress` is passed, it uses the stream API internally
             if (ky.#options.onDownloadProgress) {
                 if (typeof ky.#options.onDownloadProgress !== 'function') {
@@ -855,39 +1132,71 @@ class Ky {
             }
             return response;
         };
-        // Always wrap in #retry to catch forced retries from afterResponse hooks
-        // Method retriability is checked in #calculateRetryDelay for non-forced retries
-        const result = ky.#retry(function_)
-            .finally(() => {
-            const originalRequest = ky.#originalRequest;
-            // Ignore cancellation errors from already-locked or already-consumed streams.
-            ky.#cancelBody(originalRequest?.body ?? undefined);
-            ky.#cancelBody(ky.request.body ?? undefined);
-        });
+        const result = (async () => {
+            try {
+                return await function_();
+            }
+            catch (error) {
+                // Non-Error throws (e.g., thrown strings) pass through unchanged
+                if (!(error instanceof Error)) {
+                    throw error;
+                }
+                // Errors thrown by beforeRetry hooks must propagate unchanged.
+                if (ky.#beforeRetryHookErrors.has(error)) {
+                    throw error;
+                }
+                let processedError = error;
+                for (const hook of ky.#options.hooks.beforeError) {
+                    // `request` is the current failing request. `options` intentionally remains the
+                    // stable normalized Ky options snapshot for the same reason as `HTTPError` above.
+                    // eslint-disable-next-line no-await-in-loop
+                    const hookResult = await hook({
+                        request: ky.request,
+                        options: ky.#getNormalizedOptions(),
+                        error: processedError,
+                        retryCount: ky.#retryCount,
+                    });
+                    // Only overwrite if the hook returns a valid Error instance.
+                    if (hookResult instanceof Error) {
+                        processedError = hookResult;
+                    }
+                }
+                throw processedError;
+            }
+            finally {
+                const originalRequest = ky.#originalRequest;
+                // Ignore cancellation errors from already-locked or already-consumed streams.
+                ky.#cancelBody(originalRequest?.body ?? undefined);
+                // Only cancel the current request body if it's distinct from the original (i.e. it was cloned for retries).
+                if (ky.request !== originalRequest) {
+                    ky.#cancelBody(ky.request.body ?? undefined);
+                }
+            }
+        })();
         for (const [type, mimeType] of Object.entries(responseTypes)) {
             // Only expose `.bytes()` when the environment implements it.
             if (type === 'bytes'
                 && typeof globalThis.Response?.prototype?.bytes !== 'function') {
                 continue;
             }
-            result[type] = async () => {
+            result[type] = async (schema) => {
                 // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
                 ky.request.headers.set('accept', ky.request.headers.get('accept') || mimeType);
                 const response = await result;
-                if (type === 'json') {
-                    if (response.status === 204) {
-                        return '';
-                    }
-                    const text = await response.text();
-                    if (text === '') {
-                        return '';
-                    }
-                    if (options.parseJson) {
-                        return options.parseJson(text);
+                if (type !== 'json') {
+                    return response[type]();
+                }
+                const text = await response.text();
+                if (text === '') {
+                    if (schema !== undefined) {
+                        return validateJsonWithSchema(undefined, schema);
                     }
                     return JSON.parse(text);
                 }
-                return response[type]();
+                const jsonValue = initHookOptions.parseJson
+                    ? await initHookOptions.parseJson(text, { request: ky.#getResponseRequest(response), response })
+                    : JSON.parse(text);
+                return schema === undefined ? jsonValue : validateJsonWithSchema(jsonValue, schema);
             };
         }
         return result;
@@ -908,44 +1217,55 @@ class Ky {
     #options;
     #originalRequest;
     #userProvidedAbortSignal;
+    #beforeRetryHookErrors = new WeakSet();
     #cachedNormalizedOptions;
+    #startTime;
+    #returnedResponseFromBeforeRetryHook = false;
+    #responseRequests = new WeakMap();
     // eslint-disable-next-line complexity
     constructor(input, options = {}) {
         this.#input = input;
+        if (Object.hasOwn(options, 'prefixUrl')) {
+            throw new Error(prefixUrlRenamedErrorMessage);
+        }
         this.#options = {
             ...options,
             headers: mergeHeaders(this.#input.headers, options.headers),
-            hooks: mergeHooks({
-                beforeRequest: [],
-                beforeRetry: [],
-                beforeError: [],
-                afterResponse: [],
-            }, options.hooks),
+            hooks: mergeHooks({}, options.hooks),
             method: normalizeRequestMethod(options.method ?? this.#input.method ?? 'GET'),
             // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
-            prefixUrl: String(options.prefixUrl || ''),
+            prefix: String(options.prefix || ''),
             retry: normalizeRetryOptions(options.retry),
             throwHttpErrors: options.throwHttpErrors ?? true,
             timeout: options.timeout ?? 10_000,
+            totalTimeout: options.totalTimeout ?? false,
             fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
             context: options.context ?? {},
         };
         if (typeof this.#input !== 'string' && !(this.#input instanceof URL || this.#input instanceof globalThis.Request)) {
             throw new TypeError('`input` must be a string, URL, or Request');
         }
-        if (this.#options.prefixUrl && typeof this.#input === 'string') {
-            if (this.#input.startsWith('/')) {
-                throw new Error('`input` must not begin with a slash when using `prefixUrl`');
+        if (typeof this.#input === 'string') {
+            if (this.#options.prefix) {
+                const normalizedPrefix = this.#options.prefix.replace(/\/+$/, '');
+                const normalizedInput = this.#input.replace(/^\/+/, '');
+                this.#input = `${normalizedPrefix}/${normalizedInput}`;
             }
-            if (!this.#options.prefixUrl.endsWith('/')) {
-                this.#options.prefixUrl += '/';
+            if (this.#options.baseUrl) {
+                let absoluteInput;
+                try {
+                    absoluteInput = new URL(this.#input);
+                }
+                catch { }
+                if (!absoluteInput) {
+                    this.#input = new URL(this.#input, (new Request(this.#options.baseUrl)).url);
+                }
             }
-            this.#input = this.#options.prefixUrl + this.#input;
         }
         if (supportsAbortController && supportsAbortSignal) {
             this.#userProvidedAbortSignal = this.#options.signal ?? this.#input.signal;
             this.#abortController = new globalThis.AbortController();
-            this.#options.signal = this.#userProvidedAbortSignal ? AbortSignal.any([this.#userProvidedAbortSignal, this.#abortController.signal]) : this.#abortController.signal;
+            this.#options.signal = this.#createManagedSignal();
         }
         if (supportsRequestStreams) {
             // @ts-expect-error - Types are outdated.
@@ -965,29 +1285,45 @@ class Ky {
         }
         this.request = new globalThis.Request(this.#input, this.#options);
         if (hasSearchParameters(this.#options.searchParams)) {
-            // eslint-disable-next-line unicorn/prevent-abbreviations
-            const textSearchParams = typeof this.#options.searchParams === 'string'
-                ? this.#options.searchParams.replace(/^\?/, '')
-                : new URLSearchParams(Ky.#normalizeSearchParams(this.#options.searchParams)).toString();
-            // eslint-disable-next-line unicorn/prevent-abbreviations
-            const searchParams = '?' + textSearchParams;
-            const url = this.request.url.replace(/(?:\?.*?)?(?=#|$)/, searchParams);
+            const url = new URL(this.request.url);
+            if (typeof this.#options.searchParams === 'string') {
+                const stringSearchParameters = this.#options.searchParams.replace(/^\?/, '');
+                if (stringSearchParameters !== '') {
+                    url.search = url.search ? `${url.search}&${stringSearchParameters}` : `?${stringSearchParameters}`;
+                }
+            }
+            else {
+                const optionsSearchParameters = new URLSearchParams(Ky.#normalizeSearchParams(this.#options.searchParams));
+                for (const [key, value] of optionsSearchParameters.entries()) {
+                    url.searchParams.append(key, value);
+                }
+            }
+            if (this.#options.searchParams
+                && typeof this.#options.searchParams === 'object'
+                && !Array.isArray(this.#options.searchParams)
+                && !(this.#options.searchParams instanceof URLSearchParams)) {
+                for (const [key, value] of Object.entries(this.#options.searchParams)) {
+                    if (value === undefined) {
+                        url.searchParams.delete(key);
+                    }
+                }
+            }
+            const deleted = this.#options.searchParams?.[deletedParametersSymbol];
+            if (deleted) {
+                for (const key of deleted) {
+                    url.searchParams.delete(key);
+                }
+            }
             // Recreate request with the updated URL. We already have all options in this.#options, including duplex.
             this.request = new globalThis.Request(url, this.#options);
         }
-        // If `onUploadProgress` is passed, it uses the stream API internally
-        if (this.#options.onUploadProgress) {
-            if (typeof this.#options.onUploadProgress !== 'function') {
-                throw new TypeError('The `onUploadProgress` option must be a function');
-            }
-            if (!supportsRequestStreams) {
-                throw new Error('Request streams are not supported in your environment. The `duplex` option for `Request` is not available.');
-            }
-            this.request = this.#wrapRequestWithUploadProgress(this.request, this.#options.body ?? undefined);
+        if (this.#options.onUploadProgress && typeof this.#options.onUploadProgress !== 'function') {
+            throw new TypeError('The `onUploadProgress` option must be a function');
         }
+        this.#startTime = typeof this.#options.totalTimeout === 'number' ? this.#getCurrentTime() : undefined;
     }
     #calculateDelay() {
-        const retryDelay = this.#options.retry.delay(this.#retryCount);
+        const retryDelay = this.#options.retry.delay(this.#retryCount + 1);
         let jitteredDelay = retryDelay;
         if (this.#options.retry.jitter === true) {
             jitteredDelay = Math.random() * retryDelay;
@@ -998,13 +1334,10 @@ class Ky {
                 jitteredDelay = retryDelay;
             }
         }
-        // Handle undefined backoffLimit by treating it as no limit (Infinity)
-        const backoffLimit = this.#options.retry.backoffLimit ?? Number.POSITIVE_INFINITY;
-        return Math.min(backoffLimit, jitteredDelay);
+        return Math.min(this.#options.retry.backoffLimit, jitteredDelay);
     }
     async #calculateRetryDelay(error) {
-        this.#retryCount++;
-        if (this.#retryCount > this.#options.retry.limit) {
+        if (this.#retryCount >= this.#options.retry.limit) {
             throw error;
         }
         // Wrap non-Error throws to ensure consistent error handling
@@ -1017,9 +1350,9 @@ class Ky {
         if (!this.#options.retry.methods.includes(this.request.method.toLowerCase())) {
             throw error;
         }
-        // User-provided shouldRetry function takes precedence over all other checks
+        // User-provided shouldRetry function takes precedence over default checks (retryOnTimeout, status codes, etc.)
         if (this.#options.retry.shouldRetry !== undefined) {
-            const result = await this.#options.retry.shouldRetry({ error: errorObject, retryCount: this.#retryCount });
+            const result = await this.#options.retry.shouldRetry({ error: errorObject, retryCount: this.#retryCount + 1 });
             // Strict boolean checking - only exact true/false are handled specially
             if (result === false) {
                 throw error;
@@ -1031,8 +1364,11 @@ class Ky {
             // If undefined or any other value, fall through to default behavior
         }
         // Default timeout behavior
-        if (isTimeoutError(error) && !this.#options.retry.retryOnTimeout) {
-            throw error;
+        if (isTimeoutError(error)) {
+            if (!this.#options.retry.retryOnTimeout) {
+                throw error;
+            }
+            return this.#calculateDelay();
         }
         if (isHTTPError(error)) {
             if (!this.#options.retry.statusCodes.includes(error.response.status)) {
@@ -1052,22 +1388,152 @@ class Ky {
                     // A large number is treated as a timestamp (fixed threshold protects against clock skew)
                     after -= Date.now();
                 }
-                const max = this.#options.retry.maxRetryAfter ?? after;
+                if (!Number.isFinite(after)) {
+                    return Math.min(this.#options.retry.maxRetryAfter, this.#calculateDelay());
+                }
+                after = Math.max(0, after);
                 // Don't apply jitter when server provides explicit retry timing
-                return after < max ? after : max;
+                return Math.min(this.#options.retry.maxRetryAfter, after);
             }
             if (error.response.status === 413) {
                 throw error;
             }
+            return this.#calculateDelay();
+        }
+        // Only retry known retriable error types. Unknown errors (e.g., programming bugs) are not retried.
+        if (!isNetworkError(error)) {
+            throw error;
         }
         return this.#calculateDelay();
     }
     #decorateResponse(response) {
+        const request = this.#getResponseRequest(response);
         if (this.#options.parseJson) {
-            response.json = async () => this.#options.parseJson(await response.text());
+            response.json = async () => {
+                const text = await response.text();
+                if (text === '') {
+                    return JSON.parse(text);
+                }
+                return this.#options.parseJson(text, { request, response });
+            };
         }
         return response;
     }
+    async #getResponseData(response) {
+        // Even with request timeouts disabled, bound error-body reads so retries and error propagation
+        // cannot be stalled indefinitely by never-ending response streams.
+        const text = await this.#readResponseText(response, this.#getErrorDataTimeout());
+        if (text === timedOutResponseData) {
+            this.#throwIfTotalTimeoutExhausted();
+            return undefined;
+        }
+        if (!text) {
+            return undefined;
+        }
+        if (!this.#isJsonContentType(response.headers.get('content-type') ?? '')) {
+            return text;
+        }
+        const data = await this.#parseJson(text, response, this.#getErrorDataTimeout(), this.#getResponseRequest(response));
+        if (data === timedOutResponseData) {
+            this.#throwIfTotalTimeoutExhausted();
+            return undefined;
+        }
+        return data;
+    }
+    #getErrorDataTimeout() {
+        const errorDataTimeout = this.#options.timeout === false ? 10_000 : this.#options.timeout;
+        const remainingTotal = this.#getRemainingTotalTimeout();
+        if (remainingTotal === undefined) {
+            return errorDataTimeout;
+        }
+        if (remainingTotal <= 0) {
+            throw new TimeoutError(this.request);
+        }
+        return Math.min(errorDataTimeout, remainingTotal);
+    }
+    #isJsonContentType(contentType) {
+        // Match JSON subtypes like `json`, `problem+json`, and `vnd.api+json`.
+        const mimeType = (contentType.split(';', 1)[0] ?? '').trim().toLowerCase();
+        return /\/(?:.*[.+-])?json$/.test(mimeType);
+    }
+    async #readResponseText(response, timeoutMs) {
+        const { body } = response;
+        if (!body) {
+            try {
+                return await response.text();
+            }
+            catch {
+                return undefined;
+            }
+        }
+        let reader;
+        try {
+            reader = body.getReader();
+        }
+        catch {
+            // Another consumer already locked the stream.
+            return undefined;
+        }
+        const decoder = createTextDecoder(response.headers.get('content-type') ?? '');
+        const chunks = [];
+        let totalBytes = 0;
+        const readAll = (async () => {
+            try {
+                for (;;) {
+                    // eslint-disable-next-line no-await-in-loop
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        break;
+                    }
+                    totalBytes += value.byteLength;
+                    if (totalBytes > maxErrorResponseBodySize) {
+                        void reader.cancel().catch(() => undefined);
+                        return undefined;
+                    }
+                    chunks.push(decoder.decode(value, { stream: true }));
+                }
+            }
+            catch {
+                return undefined;
+            }
+            chunks.push(decoder.decode());
+            return chunks.join('');
+        })();
+        const timeoutPromise = new Promise(resolve => {
+            const timeoutId = setTimeout(() => {
+                resolve(timedOutResponseData);
+            }, timeoutMs);
+            void readAll.finally(() => {
+                clearTimeout(timeoutId);
+            });
+        });
+        const result = await Promise.race([readAll, timeoutPromise]);
+        if (result === timedOutResponseData) {
+            void reader.cancel().catch(() => undefined);
+        }
+        return result;
+    }
+    async #parseJson(text, response, timeoutMs, request) {
+        let timeoutId;
+        try {
+            return await Promise.race([
+                Promise.resolve().then(() => this.#options.parseJson
+                    ? this.#options.parseJson(text, { request, response })
+                    : JSON.parse(text)),
+                new Promise(resolve => {
+                    timeoutId = setTimeout(() => {
+                        resolve(timedOutResponseData);
+                    }, timeoutMs);
+                }),
+            ]);
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     #cancelBody(body) {
         if (!body) {
             return;
@@ -1079,90 +1545,224 @@ class Ky {
         // Ignore cancellation failures from already-locked or already-consumed streams.
         this.#cancelBody(response.body ?? undefined);
     }
+    #createManagedSignal() {
+        return this.#userProvidedAbortSignal
+            ? AbortSignal.any([this.#userProvidedAbortSignal, this.#abortController.signal])
+            : this.#abortController.signal;
+    }
+    #throwIfTotalTimeoutExhausted() {
+        const remaining = this.#getRemainingTotalTimeout();
+        if (remaining !== undefined && remaining <= 0) {
+            throw new TimeoutError(this.request);
+        }
+    }
+    async #runBeforeRequestHooks() {
+        for (const hook of this.#options.hooks.beforeRequest) {
+            // eslint-disable-next-line no-await-in-loop
+            const result = await hook({
+                request: this.request,
+                options: this.#getNormalizedOptions(),
+                retryCount: 0,
+            });
+            if (result instanceof Response) {
+                return result;
+            }
+            if (result instanceof globalThis.Request) {
+                this.#assignRequest(result);
+            }
+        }
+        return undefined;
+    }
+    async #runAfterResponseHooks(response) {
+        const responseRequest = this.#getResponseRequest(response);
+        for (const hook of this.#options.hooks.afterResponse) {
+            // Clone the response before passing to hook so we can cancel it if needed
+            const clonedResponse = this.#setResponseRequest(response.clone(), responseRequest);
+            this.#decorateResponse(clonedResponse);
+            let modifiedResponse;
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                modifiedResponse = await hook({
+                    request: this.request,
+                    options: this.#getNormalizedOptions(),
+                    response: clonedResponse,
+                    retryCount: this.#retryCount,
+                });
+            }
+            catch (error) {
+                // Cancel both responses to prevent memory leaks when hook throws
+                this.#cancelResponseBody(clonedResponse);
+                this.#cancelResponseBody(response);
+                throw error;
+            }
+            if (modifiedResponse instanceof RetryMarker) {
+                // Cancel both the cloned response passed to the hook and the current response to prevent resource leaks (especially important in Deno/Bun).
+                // Do not await cancellation since hooks can clone the response, leaving extra tee branches that keep cancel promises pending per the Streams spec.
+                this.#cancelResponseBody(clonedResponse);
+                this.#cancelResponseBody(response);
+                throw new ForceRetryError(modifiedResponse.options);
+            }
+            // Determine which response to use going forward
+            const nextResponse = this.#setResponseRequest(modifiedResponse instanceof globalThis.Response ? modifiedResponse : response, responseRequest);
+            // Cancel any response bodies we won't use to prevent memory leaks.
+            // Uses fire-and-forget since hooks may have cloned the response, creating tee branches that block cancellation.
+            if (clonedResponse !== nextResponse) {
+                this.#cancelResponseBody(clonedResponse);
+            }
+            if (response !== nextResponse) {
+                this.#cancelResponseBody(response);
+            }
+            response = nextResponse;
+        }
+        return response;
+    }
     async #retry(function_) {
         try {
             return await function_();
         }
         catch (error) {
-            const ms = Math.min(await this.#calculateRetryDelay(error), maxSafeTimeout);
-            if (this.#retryCount < 1) {
-                throw error;
+            return this.#retryFromError(error, function_);
+        }
+    }
+    async #retryFromError(error, function_) {
+        this.#returnedResponseFromBeforeRetryHook = false;
+        const retryDelay = Math.min(await this.#calculateRetryDelay(error), maxSafeTimeout);
+        const delayOptions = { signal: this.#userProvidedAbortSignal };
+        const remainingTimeout = this.#getRemainingTotalTimeout();
+        if (remainingTimeout !== undefined) {
+            if (remainingTimeout <= 0) {
+                throw new TimeoutError(this.request);
             }
-            // Only use user-provided signal for delay, not our internal abortController
-            await delay(ms, this.#userProvidedAbortSignal ? { signal: this.#userProvidedAbortSignal } : {});
-            // Apply custom request from forced retry before beforeRetry hooks
-            // Ensure the custom request has the correct managed signal for timeouts and user aborts
-            if (error instanceof ForceRetryError && error.customRequest) {
-                const managedRequest = this.#options.signal
-                    ? new globalThis.Request(error.customRequest, { signal: this.#options.signal })
-                    : new globalThis.Request(error.customRequest);
-                this.#assignRequest(managedRequest);
+            // If waiting would consume all remaining budget, time out without starting another request.
+            if (retryDelay >= remainingTimeout) {
+                await delay(remainingTimeout, delayOptions);
+                throw new TimeoutError(this.request);
             }
-            for (const hook of this.#options.hooks.beforeRetry) {
+        }
+        // Only use user-provided signal for delay, not our internal abortController
+        await delay(retryDelay, delayOptions);
+        this.#throwIfTotalTimeoutExhausted();
+        // Apply custom request from forced retry before beforeRetry hooks
+        // Ensure the custom request has the correct managed signal for timeouts and user aborts
+        if (error instanceof ForceRetryError && error.customRequest) {
+            this.#assignRequest(new globalThis.Request(error.customRequest, this.#options.signal ? { signal: this.#options.signal } : undefined));
+        }
+        for (const hook of this.#options.hooks.beforeRetry) {
+            let hookResult;
+            try {
                 // eslint-disable-next-line no-await-in-loop
-                const hookResult = await hook({
+                hookResult = await hook({
                     request: this.request,
                     options: this.#getNormalizedOptions(),
                     error: error,
-                    retryCount: this.#retryCount,
+                    retryCount: this.#retryCount + 1,
                 });
-                if (hookResult instanceof globalThis.Request) {
-                    this.#assignRequest(hookResult);
-                    break;
-                }
-                // If a Response is returned, use it and skip the retry
-                if (hookResult instanceof globalThis.Response) {
-                    return hookResult;
-                }
-                // If `stop` is returned from the hook, the retry process is stopped
-                if (hookResult === stop) {
-                    return;
+            }
+            catch (hookError) {
+                // Preserve the original request error path (`throw error`) so beforeError hooks can still run.
+                if (hookError instanceof Error && hookError !== error) {
+                    this.#beforeRetryHookErrors.add(hookError);
                 }
+                throw hookError;
+            }
+            if (hookResult instanceof globalThis.Request) {
+                this.#assignRequest(hookResult);
+                break;
+            }
+            // If a Response is returned, use it and skip the retry
+            if (hookResult instanceof globalThis.Response) {
+                this.#returnedResponseFromBeforeRetryHook = true;
+                this.#retryCount++;
+                return hookResult;
+            }
+            // If `stop` is returned from the hook, the retry process is stopped
+            if (hookResult === stop) {
+                return;
             }
-            return this.#retry(function_);
         }
+        this.#throwIfTotalTimeoutExhausted();
+        this.#retryCount++;
+        return this.#retry(function_);
+    }
+    #consumeReturnedResponseFromBeforeRetryHook() {
+        const value = this.#returnedResponseFromBeforeRetryHook;
+        this.#returnedResponseFromBeforeRetryHook = false;
+        return value;
     }
     async #fetch() {
         // Reset abortController if it was aborted (happens on timeout retry)
         if (this.#abortController?.signal.aborted) {
             this.#abortController = new globalThis.AbortController();
-            this.#options.signal = this.#userProvidedAbortSignal ? AbortSignal.any([this.#userProvidedAbortSignal, this.#abortController.signal]) : this.#abortController.signal;
+            this.#options.signal = this.#createManagedSignal();
             // Recreate request with new signal
             this.request = new globalThis.Request(this.request, { signal: this.#options.signal });
         }
-        for (const hook of this.#options.hooks.beforeRequest) {
-            // eslint-disable-next-line no-await-in-loop
-            const result = await hook(this.request, this.#getNormalizedOptions(), { retryCount: this.#retryCount });
-            if (result instanceof Response) {
-                return result;
+        const nonRequestOptions = findUnknownOptions(this.request, this.#options);
+        const retryRequest = this.#options.retry.limit > 0 ? this.request.clone() : undefined;
+        const request = this.#wrapRequestWithUploadProgress(this.request, this.#options.body ?? undefined);
+        // Cloning is done here to prepare in advance for retries.
+        // Skip cloning when retries are disabled - cloning a streaming body calls ReadableStream#tee()
+        // which buffers the entire stream in memory, causing excessive memory usage for large uploads.
+        this.#originalRequest = request;
+        if (retryRequest) {
+            this.request = retryRequest;
+        }
+        try {
+            const remainingTotal = this.#getRemainingTotalTimeout();
+            if (remainingTotal !== undefined && remainingTotal <= 0) {
+                throw new TimeoutError(this.request);
             }
-            if (result instanceof globalThis.Request) {
-                this.#assignRequest(result);
-                break;
+            const effectiveTimeout = this.#options.timeout === false
+                ? remainingTotal
+                : (remainingTotal === undefined
+                    ? this.#options.timeout
+                    : Math.min(this.#options.timeout, remainingTotal));
+            const response = effectiveTimeout === undefined
+                ? await this.#options.fetch(request, nonRequestOptions)
+                : await timeout(request, nonRequestOptions, this.#abortController, {
+                    timeout: effectiveTimeout,
+                    fetch: this.#options.fetch,
+                });
+            return this.#setResponseRequest(response, request);
+        }
+        catch (error) {
+            if (isRawNetworkError(error)) {
+                throw new NetworkError(this.request, { cause: error });
             }
+            throw error;
         }
-        const nonRequestOptions = findUnknownOptions(this.request, this.#options);
-        // Cloning is done here to prepare in advance for retries
-        this.#originalRequest = this.request;
-        this.request = this.#originalRequest.clone();
-        if (this.#options.timeout === false) {
-            return this.#options.fetch(this.#originalRequest, nonRequestOptions);
+    }
+    #getRemainingTotalTimeout() {
+        if (this.#startTime === undefined) {
+            return undefined;
         }
-        return timeout(this.#originalRequest, nonRequestOptions, this.#abortController, this.#options);
+        const elapsed = this.#getCurrentTime() - this.#startTime;
+        return Math.max(0, this.#options.totalTimeout - elapsed);
+    }
+    #getCurrentTime() {
+        return globalThis.performance?.now() ?? Date.now();
     }
     #getNormalizedOptions() {
         if (!this.#cachedNormalizedOptions) {
-            const { hooks, ...normalizedOptions } = this.#options;
+            // Exclude Ky-specific options that are not part of `RequestInit`.
+            const { hooks, json, parseJson, stringifyJson, searchParams, timeout, totalTimeout, throwHttpErrors, fetch, ...normalizedOptions } = this.#options;
             this.#cachedNormalizedOptions = Object.freeze(normalizedOptions);
         }
         return this.#cachedNormalizedOptions;
     }
     #assignRequest(request) {
         this.#cachedNormalizedOptions = undefined;
-        this.request = this.#wrapRequestWithUploadProgress(request);
+        this.request = request;
+    }
+    #getResponseRequest(response) {
+        return this.#responseRequests.get(response) ?? this.request;
+    }
+    #setResponseRequest(response, request) {
+        this.#responseRequests.set(response, request);
+        return response;
     }
     #wrapRequestWithUploadProgress(request, originalBody) {
-        if (!this.#options.onUploadProgress || !request.body) {
+        if (!this.#options.onUploadProgress || !request.body || !supportsRequestStreams) {
             return request;
         }
         return streamRequest(request, this.#options.onUploadProgress, originalBody ?? this.#options.body ?? undefined);
@@ -1196,185 +1796,96 @@ var distribution = /*#__PURE__*/Object.freeze({
 	__proto__: null,
 	ForceRetryError: ForceRetryError,
 	HTTPError: HTTPError,
+	KyError: KyError,
+	NetworkError: NetworkError,
+	SchemaValidationError: SchemaValidationError,
 	TimeoutError: TimeoutError,
 	default: ky,
 	isForceRetryError: isForceRetryError,
 	isHTTPError: isHTTPError,
 	isKyError: isKyError,
-	isTimeoutError: isTimeoutError
+	isNetworkError: isNetworkError,
+	isTimeoutError: isTimeoutError,
+	replaceOption: replaceOption
 });
 
 var require$$1 = /*@__PURE__*/getAugmentedNamespace(distribution);
 
-const VERSION = '0.15.1';
+const VERSION = '0.16.0';
 
 var constants = {
   VERSION,
   USER_AGENT: `mql/${VERSION}`,
   /**
-   * Retry status codes, excluding 429 (too many requests).
+   * Based on Ky default retry status codes, excluding 429:
+   * https://github.com/sindresorhus/ky/blob/main/source/core/constants.ts
    */
-  RETRY_STATUS_CODES: [408, 413, 500, 502, 503, 504, 521, 522, 524]
-};
-
-const ENDPOINT = {
-  FREE: 'https://api.microlink.io/',
-  PRO: 'https://pro.microlink.io/'
-};
-
-const isObject = input => input !== null && typeof input === 'object';
-
-const isBuffer = input =>
-  input != null &&
-  input.constructor != null &&
-  typeof input.constructor.isBuffer === 'function' &&
-  input.constructor.isBuffer(input);
-
-const parseBody = (input, error, url) => {
-  try {
-    return JSON.parse(input)
-  } catch (_) {
-    const message = input || error.message;
-
-    return {
-      status: 'error',
-      data: { url: message },
-      more: 'https://microlink.io/efatalclient',
-      code: 'EFATALCLIENT',
-      message,
-      url
-    }
-  }
-};
-
-const isURL = url => {
-  try {
-    return /^https?:\/\//i.test(new URL(url).href)
-  } catch (_) {
-    return false
-  }
-};
-
-const factory = streamResponseType => ({
-  VERSION,
-  MicrolinkError,
-  got,
-  flatten
-}) => {
-  const assertUrl = (url = '') => {
-    if (!isURL(url)) {
-      const message = `The \`url\` as \`${url}\` is not valid. Ensure it has protocol (http or https) and hostname.`;
-      throw new MicrolinkError({
-        status: 'fail',
-        data: { url: message },
-        more: 'https://microlink.io/einvalurlclient',
-        code: 'EINVALURLCLIENT',
-        message,
-        url
-      })
-    }
-  };
-
-  const mapRules = rules => {
-    if (!isObject(rules)) return
-    const flatRules = flatten(rules);
-    return Object.keys(flatRules).reduce((acc, key) => {
-      acc[`data.${key}`] = flatRules[key].toString();
-      return acc
-    }, {})
-  };
-
-  const fetchFromApi = async (apiUrl, opts = {}) => {
-    try {
-      const response = await got(apiUrl, opts);
-      return opts.responseType === streamResponseType
-        ? response
-        : { ...response.body, response }
-    } catch (error) {
-      const { response = {} } = error;
-      const {
-        statusCode,
-        body: rawBody,
-        headers = {},
-        url: uri = apiUrl
-      } = response;
-      const isBodyBuffer = isBuffer(rawBody);
-
-      const body =
-        isObject(rawBody) && !isBodyBuffer
-          ? rawBody
-          : parseBody(isBodyBuffer ? rawBody.toString() : rawBody, error, uri);
-
-      throw new MicrolinkError({
-        ...body,
-        message: body.message,
-        url: uri,
-        statusCode,
-        headers
-      })
-    }
-  };
-
-  const getApiUrl = (
-    url,
-    { data, apiKey, endpoint, ...opts } = {},
-    { responseType = 'json', headers: gotHeaders, ...gotOpts } = {}
-  ) => {
-    const isPro = !!apiKey;
-    const apiEndpoint = endpoint || ENDPOINT[isPro ? 'PRO' : 'FREE'];
-
-    const apiUrl = `${apiEndpoint}?${new URLSearchParams({
-      url,
-      ...mapRules(data),
-      ...flatten(opts)
-    }).toString()}`;
-
-    const headers = isPro
-      ? { ...gotHeaders, 'x-api-key': apiKey }
-      : { ...gotHeaders };
-
-    if (opts.stream) {
-      responseType = streamResponseType;
-    }
-    return [apiUrl, { ...gotOpts, responseType, headers }]
-  };
-
-  const createMql = defaultOpts => async (url, opts, gotOpts) => {
-    assertUrl(url);
-    const [apiUrl, fetchOpts] = getApiUrl(url, opts, {
-      ...defaultOpts,
-      ...gotOpts
-    });
-    return fetchFromApi(apiUrl, fetchOpts)
-  };
-
-  const mql = createMql();
-  mql.extend = createMql;
-  mql.MicrolinkError = MicrolinkError;
-  mql.getApiUrl = getApiUrl;
-  mql.fetchFromApi = fetchFromApi;
-  mql.mapRules = mapRules;
-  mql.version = VERSION;
-  mql.stream = got.stream;
-
-  return mql
+  RETRY_STATUS_CODES: [408, 413, 500, 502, 503, 504, 521, 522, 524],
+  /**
+   * Based on Ky default Retry-After status codes, excluding 429:
+   * https://github.com/sindresorhus/ky/blob/main/source/core/constants.ts
+   */
+  RETRY_AFTER_STATUS_CODES: [413, 503]
 };
 
-var factory_1 = factory;
-
 (function (module) {
 
 	const { flattie: flatten } = dist;
 	const { default: ky } = require$$1;
 
-	const { VERSION, USER_AGENT, RETRY_STATUS_CODES } = constants;
+	const {
+	  VERSION,
+	  USER_AGENT,
+	  RETRY_STATUS_CODES,
+	  RETRY_AFTER_STATUS_CODES
+	} = constants;
+
+	const ENDPOINT = {
+	  FREE: 'https://api.microlink.io/',
+	  PRO: 'https://pro.microlink.io/'
+	};
+
+	const STREAM_RESPONSE_TYPE = 'arrayBuffer';
 
 	const kyInstance = ky.extend({
 	  headers: { 'user-agent': USER_AGENT },
-	  retry: { statusCodes: RETRY_STATUS_CODES }
+	  retry: {
+	    statusCodes: RETRY_STATUS_CODES,
+	    afterStatusCodes: RETRY_AFTER_STATUS_CODES
+	  }
 	});
 
-	const factory = factory_1('arrayBuffer');
+	const isObject = input => input !== null && typeof input === 'object';
+
+	const isBuffer = input =>
+	  typeof input?.constructor?.isBuffer === 'function' &&
+	  input.constructor.isBuffer(input);
+
+	const parseBody = (input, error, url) => {
+	  try {
+	    return JSON.parse(input)
+	  } catch (_) {
+	    const message = input || error.message;
+
+	    return {
+	      status: 'error',
+	      data: { url: message },
+	      more: 'https://microlink.io/efatalclient',
+	      code: 'EFATALCLIENT',
+	      message,
+	      url
+	    }
+	  }
+	};
+
+	const isURL = url => {
+	  try {
+	    const { protocol } = new URL(url);
+	    return protocol === 'http:' || protocol === 'https:'
+	  } catch (_) {
+	    return false
+	  }
+	};
 
 	class MicrolinkError extends Error {
 	  constructor (props) {
@@ -1388,44 +1899,132 @@ var factory_1 = factory;
 	  }
 	}
 
-	const got = async (url, { responseType, ...opts }) => {
+	const assertUrl = (url = '') => {
+	  if (!isURL(url)) {
+	    const message = `The \`url\` as \`${url}\` is not valid. Ensure it has protocol (http or https) and hostname.`;
+	    throw new MicrolinkError({
+	      status: 'fail',
+	      data: { url: message },
+	      more: 'https://microlink.io/einvalurlclient',
+	      code: 'EINVALURLCLIENT',
+	      message,
+	      url
+	    })
+	  }
+	};
+
+	const mapRules = rules => {
+	  if (!isObject(rules)) return
+	  return Object.fromEntries(
+	    Object.entries(flatten(rules)).map(([key, value]) => [
+	      `data.${key}`,
+	      value.toString()
+	    ])
+	  )
+	};
+
+	const doFetch = async (apiUrl, { responseType, ...opts }) => {
+	  if (opts.timeout === undefined) opts.timeout = false;
+	  const response = await kyInstance(apiUrl, opts);
+	  const body = await response[responseType]();
+	  const { headers, status: statusCode } = response;
+	  return { url: response.url, body, headers, statusCode }
+	};
+
+	const fetchFromApi = async (apiUrl, opts = {}) => {
 	  try {
-	    if (opts.timeout === undefined) opts.timeout = false;
-	    const response = await kyInstance(url, opts);
-	    const body = await response[responseType]();
-	    const { headers, status: statusCode } = response;
-	    return { url: response.url, body, headers, statusCode }
+	    const response = await doFetch(apiUrl, opts);
+	    return opts.responseType === STREAM_RESPONSE_TYPE
+	      ? response
+	      : { ...response.body, response }
 	  } catch (error) {
-	    if (error.response) {
-	      const { response } = error;
-	      error.response = {
-	        ...response,
-	        headers: Array.from(response.headers.entries()).reduce(
-	          (acc, [key, value]) => {
-	            acc[key] = value;
-	            return acc
-	          },
-	          {}
-	        ),
-	        statusCode: response.status,
-	        body: await response.text()
-	      };
+	    const { response = {} } = error;
+	    const { statusCode: responseStatusCode, status } = response;
+	    const {
+	      body: rawBody,
+	      headers: responseHeaders,
+	      url: uri = apiUrl
+	    } = response;
+
+	    const statusCode = responseStatusCode ?? status;
+	    const headers =
+	      typeof responseHeaders?.entries === 'function'
+	        ? Object.fromEntries(responseHeaders.entries())
+	        : responseHeaders || {};
+
+	    let bodyInput = error.data ?? rawBody;
+	    const isBodyReadableStream = typeof bodyInput?.getReader === 'function';
+
+	    if (
+	      (bodyInput === undefined || isBodyReadableStream) &&
+	      typeof response.text === 'function'
+	    ) {
+	      try {
+	        bodyInput = await response.text();
+	      } catch (_) {
+	        bodyInput = undefined;
+	      }
 	    }
-	    throw error
+
+	    const isBodyBuffer = isBuffer(bodyInput);
+	    const body =
+	      isObject(bodyInput) && !isBodyBuffer
+	        ? bodyInput
+	        : parseBody(isBodyBuffer ? bodyInput.toString() : bodyInput, error, uri);
+
+	    throw new MicrolinkError({
+	      ...body,
+	      url: uri,
+	      statusCode,
+	      headers
+	    })
 	  }
 	};
 
-	got.stream = (...args) => kyInstance(...args).then(res => res.body);
+	const getApiUrl = (
+	  url,
+	  { data, apiKey, endpoint, ...opts } = {},
+	  { responseType = 'json', headers: responseHeaders = {}, ...gotOpts } = {}
+	) => {
+	  const isPro = !!apiKey;
+	  const apiEndpoint = endpoint || ENDPOINT[isPro ? 'PRO' : 'FREE'];
 
-	const mql = factory({
-	  MicrolinkError,
-	  got,
-	  flatten,
-	  VERSION
-	});
+	  const apiUrl = `${apiEndpoint}?${new URLSearchParams({
+	    url,
+	    ...mapRules(data),
+	    ...flatten(opts)
+	  })}`;
+
+	  const headers = isPro
+	    ? { ...responseHeaders, 'x-api-key': apiKey }
+	    : responseHeaders;
+
+	  if (opts.stream) responseType = STREAM_RESPONSE_TYPE;
+
+	  return [apiUrl, { ...gotOpts, responseType, headers }]
+	};
+
+	const createMql = defaultOpts => async (url, opts, gotOpts) => {
+	  assertUrl(url);
+	  const [apiUrl, fetchOpts] = getApiUrl(url, opts, {
+	    ...defaultOpts,
+	    ...gotOpts
+	  });
+	  return fetchFromApi(apiUrl, fetchOpts)
+	};
+
+	const mql = createMql();
+
+	mql.extend = createMql;
+	mql.MicrolinkError = MicrolinkError;
+	mql.getApiUrl = getApiUrl;
+	mql.fetchFromApi = fetchFromApi;
+	mql.mapRules = mapRules;
+	mql.version = VERSION;
+	mql.stream = (...args) => kyInstance(...args).then(res => res.body);
 
 	module.exports = mql;
-	module.exports.arrayBuffer = mql.extend({ responseType: 'arrayBuffer' });
+	module.exports.arrayBuffer = mql.extend({ responseType: STREAM_RESPONSE_TYPE });
 	module.exports.buffer = module.exports.arrayBuffer;
 	module.exports.extend = mql.extend;
 	module.exports.fetchFromApi = mql.fetchFromApi;