snapreq 0.0.3 → 0.0.4

package/README.md

@@ -63,6 +63,7 @@ new SnapReq({
   headers,        // default headers — object or a factory `() => ({...})` for dynamic auth
   retry,          // default retry policy (see below)
   throwOnError,   // throw SnapReqHttpError on non-2xx (default false)
+  timeoutMs,      // default request/body timeout in milliseconds; per-request 0 disables it
   credentials,    // fetch credentials mode: "omit" | "same-origin" | "include"
   transport,      // "auto" (default) | "node" | "fetch" | "xhr" | a transport instance
 
@@ -73,6 +74,17 @@ new SnapReq({
 })
 ```
 
+### Timeouts
+
+Set `timeoutMs` on the client or a single request to abort stalled requests. The timeout covers the response headers and body reads through `json()`, `text()`, `bytes()`, `buffer()`, or `stream()`. A timed-out request rejects with `SnapReqTimeoutError`.
+
+```js
+const client = new SnapReq({baseUrl: "https://api.example.com", timeoutMs: 120000})
+
+await client.get("/slow", {timeoutMs: 5000})
+await client.get("/long-running", {timeoutMs: 0}) // disable the client default for this call
+```
+
 ### Retry
 
 Retries transient network errors and retryable HTTP statuses (502/503/504 by default). Only applies to buffered requests — never to streamed bodies.

package/package.json

@@ -1,22 +1,55 @@
 {
   "name": "snapreq",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Cross-platform HTTP and WebSocket client with one API across Node, web, Expo and React Native",
   "type": "module",
   "main": "./src/snap-req.js",
   "types": "./types/snap-req.d.ts",
   "exports": {
-    ".": {"types": "./types/snap-req.d.ts", "default": "./src/snap-req.js"},
-    "./websocket": {"types": "./types/websocket/websocket-client.d.ts", "default": "./src/websocket/websocket-client.js"},
-    "./errors": {"types": "./types/errors.d.ts", "default": "./src/errors.js"},
-    "./headers": {"types": "./types/headers.d.ts", "default": "./src/headers.js"},
-    "./response": {"types": "./types/response.d.ts", "default": "./src/response.js"},
-    "./retry": {"types": "./types/retry.d.ts", "default": "./src/retry.js"},
-    "./capabilities": {"types": "./types/capabilities.d.ts", "default": "./src/capabilities.js"},
-    "./transports/select": {"types": "./types/transports/select.d.ts", "default": "./src/transports/select.js"},
-    "./transports/fetch": {"types": "./types/transports/fetch-transport.d.ts", "default": "./src/transports/fetch-transport.js"},
-    "./transports/xhr": {"types": "./types/transports/xhr-transport.d.ts", "default": "./src/transports/xhr-transport.js"},
-    "./*": {"types": "./types/*.d.ts", "default": "./src/*.js"}
+    ".": {
+      "types": "./types/snap-req.d.ts",
+      "default": "./src/snap-req.js"
+    },
+    "./websocket": {
+      "types": "./types/websocket/websocket-client.d.ts",
+      "default": "./src/websocket/websocket-client.js"
+    },
+    "./errors": {
+      "types": "./types/errors.d.ts",
+      "default": "./src/errors.js"
+    },
+    "./headers": {
+      "types": "./types/headers.d.ts",
+      "default": "./src/headers.js"
+    },
+    "./response": {
+      "types": "./types/response.d.ts",
+      "default": "./src/response.js"
+    },
+    "./retry": {
+      "types": "./types/retry.d.ts",
+      "default": "./src/retry.js"
+    },
+    "./capabilities": {
+      "types": "./types/capabilities.d.ts",
+      "default": "./src/capabilities.js"
+    },
+    "./transports/select": {
+      "types": "./types/transports/select.d.ts",
+      "default": "./src/transports/select.js"
+    },
+    "./transports/fetch": {
+      "types": "./types/transports/fetch-transport.d.ts",
+      "default": "./src/transports/fetch-transport.js"
+    },
+    "./transports/xhr": {
+      "types": "./types/transports/xhr-transport.d.ts",
+      "default": "./src/transports/xhr-transport.js"
+    },
+    "./*": {
+      "types": "./types/*.d.ts",
+      "default": "./src/*.js"
+    }
   },
   "files": [
     "src/**",
@@ -43,12 +76,12 @@
   "author": "kasper@diestoeckels.de",
   "license": "ISC",
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "@types/node": "^22.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
     "eslint": "^10.3.0",
-    "eslint-plugin-jsdoc": "^62.9.0",
-    "globals": "^16.0.0",
+    "eslint-plugin-jsdoc": "^63.0.0",
+    "globals": "^17.6.0",
     "release-patch": "^1.0.0",
     "typescript": "^6.0.3",
     "ws": "^8.21.0"

package/src/errors.js

@@ -67,3 +67,20 @@ export class SnapReqAbortError extends SnapReqError {
     this.name = "SnapReqAbortError"
   }
 }
+
+/** Thrown when a request exceeds its configured timeout. */
+export class SnapReqTimeoutError extends SnapReqError {
+  /**
+   * @param {object} options - Error metadata.
+   * @param {string} options.method - HTTP method used for the request.
+   * @param {string} options.url - Fully resolved request URL.
+   * @param {number} options.timeoutMs - Timeout in milliseconds.
+   */
+  constructor({method, url, timeoutMs}) {
+    super(`Request timed out after ${timeoutMs}ms: ${method} ${url}`)
+    this.name = "SnapReqTimeoutError"
+    this.method = method
+    this.url = url
+    this.timeoutMs = timeoutMs
+  }
+}

package/src/response.js

@@ -40,8 +40,10 @@ export default class SnapReqResponse {
    * @param {Uint8Array} [options.bytes] - Fully-read body, when the transport already buffered it.
    * @param {AsyncIterable<Uint8Array>} [options.stream] - Streamed body, when the transport supports streaming.
    * @param {import("node:stream").Readable} [options.nodeStream] - Raw Node stream, when available, for advanced consumers.
+   * @param {() => void} [options.onBodyDone] - Callback fired when body reading finishes or fails.
+   * @param {(error: unknown) => unknown} [options.mapBodyError] - Maps body read errors before rethrowing.
    */
-  constructor({url, method, status, statusText = "", headers, bytes, stream, nodeStream}) {
+  constructor({url, method, status, statusText = "", headers, bytes, stream, nodeStream, onBodyDone, mapBodyError}) {
     this.url = url
     this.method = method
     this.status = status
@@ -54,6 +56,11 @@ export default class SnapReqResponse {
     /** @type {import("node:stream").Readable | undefined} */
     this.nodeStream = nodeStream
     this._streamConsumed = false
+    this._bodyDone = false
+    this._onBodyDone = onBodyDone
+    this._mapBodyError = mapBodyError
+
+    if (bytes !== undefined) this._finishBody()
   }
 
   /** @returns {boolean} - Whether the status is in the 2xx range. */
@@ -77,7 +84,7 @@ export default class SnapReqResponse {
 
     this._streamConsumed = true
 
-    return this._stream
+    return this._wrappedStream(this._stream)
   }
 
   /** @returns {boolean} - Whether the body is available as a stream that has not been read yet. */
@@ -94,20 +101,15 @@ export default class SnapReqResponse {
 
     if (!this._stream) {
       this._bytes = new Uint8Array(0)
+      this._finishBody()
 
       return this._bytes
     }
 
-    if (this._streamConsumed) {
-      throw new Error("Cannot buffer this response: its stream was already consumed via stream().")
-    }
-
-    this._streamConsumed = true
-
     /** @type {Uint8Array[]} */
     const chunks = []
 
-    for await (const chunk of this._stream) {
+    for await (const chunk of this.stream()) {
       chunks.push(chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk))
     }
 
@@ -153,4 +155,43 @@ export default class SnapReqResponse {
 
     return JSON.parse(text)
   }
+
+  /**
+   * @param {AsyncIterable<Uint8Array>} source - Source response stream.
+   * @returns {AsyncIterable<Uint8Array>} - Stream with cleanup/error mapping.
+   */
+  _wrappedStream(source) {
+    const response = this
+
+    return (async function* () {
+      try {
+        for await (const chunk of source) {
+          yield chunk
+        }
+      } catch (error) {
+        throw response._mappedBodyError(error)
+      } finally {
+        response._finishBody()
+      }
+    })()
+  }
+
+  /**
+   * @param {unknown} error - Body read error.
+   * @returns {unknown} - Error to rethrow.
+   */
+  _mappedBodyError(error) {
+    if (this._mapBodyError) return this._mapBodyError(error)
+
+    return error
+  }
+
+  /** @returns {void} */
+  _finishBody() {
+    if (this._bodyDone) return
+
+    this._bodyDone = true
+
+    if (this._onBodyDone) this._onBodyDone()
+  }
 }

package/src/retry.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import {SnapReqHttpError} from "./errors.js"
+import {SnapReqHttpError, SnapReqTimeoutError} from "./errors.js"
 
 const RETRYABLE_ERROR_CODES = new Set(["ECONNREFUSED", "ECONNRESET", "EHOSTUNREACH", "ENOENT", "ETIMEDOUT", "EPIPE"])
 const DEFAULT_RETRYABLE_STATUSES = [502, 503, 504]
@@ -28,6 +28,8 @@ const DEFAULT_RETRYABLE_STATUSES = [502, 503, 504]
  * @returns {boolean} - Whether the error is a transient network failure.
  */
 export function defaultRetryableError(error) {
+  if (error instanceof SnapReqTimeoutError) return true
+
   if (!error || typeof error !== "object") return false
 
   if ("code" in error && typeof error.code === "string" && RETRYABLE_ERROR_CODES.has(error.code)) {

package/src/snap-req.js

@@ -1,6 +1,6 @@
 // @ts-check
 
-import {SnapReqHttpError, SnapReqUnsupportedFeatureError} from "./errors.js"
+import {SnapReqHttpError, SnapReqTimeoutError, SnapReqUnsupportedFeatureError} from "./errors.js"
 import SnapReqHeaders from "./headers.js"
 import {buildUrl, normalizeBody} from "./request.js"
 import {normalizeRetryOptions, runWithRetry} from "./retry.js"
@@ -18,6 +18,7 @@ import {selectTransport} from "./transports/select.js"
  * @property {import("./request.js").NormalizedBody} body - Normalized request body.
  * @property {CompressionEncoding} bodyCompression - Request body compression.
  * @property {AbortSignal} [signal] - Abort signal.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds.
  * @property {string} [credentials] - Fetch credentials mode ("omit" | "same-origin" | "include").
  */
 
@@ -31,11 +32,20 @@ import {selectTransport} from "./transports/select.js"
  * @property {any} [body] - Request body: string, object (JSON), Uint8Array/ArrayBuffer, or a stream/async-iterable.
  * @property {CompressionEncoding} [bodyCompression] - Compress the request body (Node transport only).
  * @property {AbortSignal} [signal] - Abort signal for the request.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds. Set to `0` to disable a client default.
  * @property {string} [credentials] - Fetch credentials mode.
  * @property {boolean | import("./retry.js").RetryOptions} [retry] - Retry transient failures.
  * @property {boolean} [throwOnError] - Throw `SnapReqHttpError` on non-2xx responses.
  */
 
+/**
+ * @typedef {object} RequestTimeout
+ * @property {AbortSignal | undefined} signal - Signal to use for the request.
+ * @property {() => void} clear - Clears timeout resources.
+ * @property {(response: import("./response.js").default, request: NormalizedRequest) => import("./response.js").default} response - Attaches timeout handling to a response.
+ * @property {(error: unknown, request: NormalizedRequest) => unknown} error - Maps a thrown error.
+ */
+
 /**
  * A cross-platform HTTP client with one API across Node, web, Expo and React
  * Native. The right transport is chosen at runtime; features a platform cannot
@@ -52,14 +62,16 @@ export default class SnapReq {
    * @param {Record<string, string | number> | (() => Record<string, string | number>)} [config.headers] - Default headers (object or factory).
    * @param {boolean | import("./retry.js").RetryOptions} [config.retry] - Default retry policy.
    * @param {boolean} [config.throwOnError] - Throw `SnapReqHttpError` on non-2xx responses by default. Defaults to false.
+   * @param {number} [config.timeoutMs] - Default request timeout in milliseconds. Set per-request `timeoutMs: 0` to disable.
    * @param {string} [config.credentials] - Default fetch credentials mode.
    * @param {import("./transports/select.js").TransportName | import("./transports/select.js").Transport} [config.transport] - Transport preference or instance. Defaults to "auto".
    */
-  constructor({baseUrl, socketPath, tls, keepAlive = true, headers, retry, throwOnError = false, credentials, transport = "auto"} = {}) {
+  constructor({baseUrl, socketPath, tls, keepAlive = true, headers, retry, throwOnError = false, timeoutMs, credentials, transport = "auto"} = {}) {
     this.baseUrl = baseUrl
     this.defaultHeaders = headers
     this.defaultRetry = retry
     this.throwOnError = throwOnError
+    this.timeoutMs = timeoutMs
     this.credentials = credentials
     this._transportPreference = transport
     this._nodeConfig = {socketPath, tls, keepAlive}
@@ -110,10 +122,120 @@ export default class SnapReq {
       body,
       bodyCompression: options.bodyCompression || "identity",
       signal: options.signal,
+      timeoutMs: options.timeoutMs ?? this.timeoutMs,
       credentials: options.credentials ?? this.credentials
     }
   }
 
+  /**
+   * @param {RequestOptions} options - Request options.
+   * @returns {RequestTimeout} - Timeout handling for one request attempt.
+   */
+  _requestTimeout(options) {
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs
+
+    if (!timeoutMs || timeoutMs <= 0) {
+      return {
+        signal: options.signal,
+        clear: () => {},
+        response: (response) => response,
+        error: (error) => error
+      }
+    }
+
+    const timeoutController = new AbortController()
+    const composedSignal = this._composeSignal(options.signal, timeoutController.signal)
+    let timedOut = false
+    const timer = setTimeout(() => {
+      timedOut = true
+      timeoutController.abort()
+    }, timeoutMs)
+
+    if (typeof timer.unref === "function") timer.unref()
+
+    const clear = () => {
+      clearTimeout(timer)
+      composedSignal.clear()
+    }
+    const toError = (error, request) => {
+      if (timedOut) {
+        return new SnapReqTimeoutError({
+          method: request.method,
+          url: request.url,
+          timeoutMs
+        })
+      }
+
+      return error
+    }
+
+    return {
+      signal: composedSignal.signal,
+      clear,
+      response: (response, request) => {
+        if (response._bodyDone) {
+          clear()
+
+          return response
+        }
+
+        response._onBodyDone = this._chainBodyDone(response._onBodyDone, clear)
+        response._mapBodyError = this._chainBodyError(response._mapBodyError, (error) => toError(error, request))
+
+        return response
+      },
+      error: toError
+    }
+  }
+
+  /**
+   * @param {AbortSignal | undefined} callerSignal - Caller-supplied signal.
+   * @param {AbortSignal} timeoutSignal - Timeout signal.
+   * @returns {{signal: AbortSignal, clear: () => void}} - Signal that aborts when either source aborts.
+   */
+  _composeSignal(callerSignal, timeoutSignal) {
+    if (!callerSignal) return {signal: timeoutSignal, clear: () => {}}
+
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+
+    if (callerSignal.aborted || timeoutSignal.aborted) {
+      controller.abort()
+    } else {
+      callerSignal.addEventListener("abort", abort, {once: true})
+      timeoutSignal.addEventListener("abort", abort, {once: true})
+    }
+
+    return {
+      signal: controller.signal,
+      clear: () => {
+        callerSignal.removeEventListener("abort", abort)
+        timeoutSignal.removeEventListener("abort", abort)
+      }
+    }
+  }
+
+  /**
+   * @param {(() => void) | undefined} existing - Existing body-done callback.
+   * @param {() => void} next - Callback to add.
+   * @returns {() => void} - Combined callback.
+   */
+  _chainBodyDone(existing, next) {
+    return () => {
+      if (existing) existing()
+      next()
+    }
+  }
+
+  /**
+   * @param {((error: unknown) => unknown) | undefined} existing - Existing error mapper.
+   * @param {(error: unknown) => unknown} next - Mapper to add.
+   * @returns {(error: unknown) => unknown} - Combined mapper.
+   */
+  _chainBodyError(existing, next) {
+    return (error) => next(existing ? existing(error) : error)
+  }
+
   /**
    * Performs a request and buffers nothing eagerly — read the body via the
    * returned response (`json()`, `text()`, `bytes()`). Retries transient
@@ -122,16 +244,15 @@ export default class SnapReq {
    * @returns {Promise<import("./response.js").default>} - The response.
    */
   async request(options) {
-    const normalized = this._normalize(options)
     const transport = await this._resolveTransport()
     const throwOnError = options.throwOnError ?? this.throwOnError
     const retry = normalizeRetryOptions(options.retry ?? this.defaultRetry)
-    const canRetry = retry && normalized.body.kind !== "stream"
-
-    const attempt = () => transport.performRequest(normalized)
+    const body = normalizeBody(options.body, new SnapReqHeaders(options.headers))
+    const canRetry = retry && body.kind !== "stream"
+    const attempt = async () => this._requestWithTimeout(options, (request) => transport.performRequest(request))
     const response = canRetry ? await runWithRetry(attempt, /** @type {any} */ (retry)) : await attempt()
 
-    if (throwOnError && !response.ok) throw await this._httpError(response, normalized)
+    if (throwOnError && !response.ok) throw await this._httpError(response, this._normalize(options))
 
     return response
   }
@@ -144,7 +265,6 @@ export default class SnapReq {
    * @returns {Promise<import("./response.js").default>} - The streaming response.
    */
   async requestStream(options) {
-    const normalized = this._normalize(options)
     const transport = await this._resolveTransport()
 
     if (!transport.capabilities.responseStreaming) {
@@ -154,15 +274,35 @@ export default class SnapReq {
       })
     }
 
-    const response = await transport.performRequest(normalized)
+    const response = await this._requestWithTimeout(options, (request) => transport.performRequest(request))
 
     if ((options.throwOnError ?? this.throwOnError) && !response.ok) {
-      throw await this._httpError(response, normalized)
+      throw await this._httpError(response, this._normalize(options))
     }
 
     return response
   }
 
+  /**
+   * @param {RequestOptions} options - Request options.
+   * @param {(request: NormalizedRequest) => Promise<import("./response.js").default>} performRequest - Transport request runner.
+   * @returns {Promise<import("./response.js").default>} - Response with timeout handling attached.
+   */
+  async _requestWithTimeout(options, performRequest) {
+    const timeout = this._requestTimeout(options)
+    const normalized = this._normalize({...options, signal: timeout.signal})
+
+    try {
+      const response = await performRequest(normalized)
+
+      return timeout.response(response, normalized)
+    } catch (error) {
+      timeout.clear()
+
+      throw timeout.error(error, normalized)
+    }
+  }
+
   /**
    * @param {string} path - Request path or absolute URL.
    * @param {RequestOptions} [options] - Request options.
@@ -221,7 +361,9 @@ export default class SnapReq {
 
     try {
       responseText = await response.text()
-    } catch {
+    } catch (error) {
+      if (error instanceof SnapReqTimeoutError) throw error
+
       // Body unavailable (already streamed or read error) — fall back to status text.
     }
 

package/types/errors.d.ts

@@ -62,3 +62,20 @@ export class SnapReqAbortError extends SnapReqError {
     /** @param {string} [message] - Human readable description. */
     constructor(message?: string);
 }
+/** Thrown when a request exceeds its configured timeout. */
+export class SnapReqTimeoutError extends SnapReqError {
+    /**
+     * @param {object} options - Error metadata.
+     * @param {string} options.method - HTTP method used for the request.
+     * @param {string} options.url - Fully resolved request URL.
+     * @param {number} options.timeoutMs - Timeout in milliseconds.
+     */
+    constructor({ method, url, timeoutMs }: {
+        method: string;
+        url: string;
+        timeoutMs: number;
+    });
+    method: string;
+    url: string;
+    timeoutMs: number;
+}

package/types/response.d.ts

@@ -15,8 +15,10 @@ export default class SnapReqResponse {
      * @param {Uint8Array} [options.bytes] - Fully-read body, when the transport already buffered it.
      * @param {AsyncIterable<Uint8Array>} [options.stream] - Streamed body, when the transport supports streaming.
      * @param {import("node:stream").Readable} [options.nodeStream] - Raw Node stream, when available, for advanced consumers.
+     * @param {() => void} [options.onBodyDone] - Callback fired when body reading finishes or fails.
+     * @param {(error: unknown) => unknown} [options.mapBodyError] - Maps body read errors before rethrowing.
      */
-    constructor({ url, method, status, statusText, headers, bytes, stream, nodeStream }: {
+    constructor({ url, method, status, statusText, headers, bytes, stream, nodeStream, onBodyDone, mapBodyError }: {
         url: string;
         method: string;
         status: number;
@@ -25,6 +27,8 @@ export default class SnapReqResponse {
         bytes?: Uint8Array;
         stream?: AsyncIterable<Uint8Array>;
         nodeStream?: import("node:stream").Readable;
+        onBodyDone?: () => void;
+        mapBodyError?: (error: unknown) => unknown;
     });
     url: string;
     method: string;
@@ -38,6 +42,9 @@ export default class SnapReqResponse {
     /** @type {import("node:stream").Readable | undefined} */
     nodeStream: import("node:stream").Readable | undefined;
     _streamConsumed: boolean;
+    _bodyDone: boolean;
+    _onBodyDone: () => void;
+    _mapBodyError: (error: unknown) => unknown;
     /** @returns {boolean} - Whether the status is in the 2xx range. */
     get ok(): boolean;
     /**
@@ -70,5 +77,17 @@ export default class SnapReqResponse {
      * @returns {Promise<any>} - The parsed JSON body.
      */
     json(): Promise<any>;
+    /**
+     * @param {AsyncIterable<Uint8Array>} source - Source response stream.
+     * @returns {AsyncIterable<Uint8Array>} - Stream with cleanup/error mapping.
+     */
+    _wrappedStream(source: AsyncIterable<Uint8Array>): AsyncIterable<Uint8Array>;
+    /**
+     * @param {unknown} error - Body read error.
+     * @returns {unknown} - Error to rethrow.
+     */
+    _mappedBodyError(error: unknown): unknown;
+    /** @returns {void} */
+    _finishBody(): void;
 }
 import SnapReqHeaders from "./headers.js";

package/types/snap-req.d.ts

@@ -9,6 +9,7 @@
  * @property {import("./request.js").NormalizedBody} body - Normalized request body.
  * @property {CompressionEncoding} bodyCompression - Request body compression.
  * @property {AbortSignal} [signal] - Abort signal.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds.
  * @property {string} [credentials] - Fetch credentials mode ("omit" | "same-origin" | "include").
  */
 /**
@@ -21,10 +22,18 @@
  * @property {any} [body] - Request body: string, object (JSON), Uint8Array/ArrayBuffer, or a stream/async-iterable.
  * @property {CompressionEncoding} [bodyCompression] - Compress the request body (Node transport only).
  * @property {AbortSignal} [signal] - Abort signal for the request.
+ * @property {number} [timeoutMs] - Request timeout in milliseconds. Set to `0` to disable a client default.
  * @property {string} [credentials] - Fetch credentials mode.
  * @property {boolean | import("./retry.js").RetryOptions} [retry] - Retry transient failures.
  * @property {boolean} [throwOnError] - Throw `SnapReqHttpError` on non-2xx responses.
  */
+/**
+ * @typedef {object} RequestTimeout
+ * @property {AbortSignal | undefined} signal - Signal to use for the request.
+ * @property {() => void} clear - Clears timeout resources.
+ * @property {(response: import("./response.js").default, request: NormalizedRequest) => import("./response.js").default} response - Attaches timeout handling to a response.
+ * @property {(error: unknown, request: NormalizedRequest) => unknown} error - Maps a thrown error.
+ */
 /**
  * A cross-platform HTTP client with one API across Node, web, Expo and React
  * Native. The right transport is chosen at runtime; features a platform cannot
@@ -41,10 +50,11 @@ export default class SnapReq {
      * @param {Record<string, string | number> | (() => Record<string, string | number>)} [config.headers] - Default headers (object or factory).
      * @param {boolean | import("./retry.js").RetryOptions} [config.retry] - Default retry policy.
      * @param {boolean} [config.throwOnError] - Throw `SnapReqHttpError` on non-2xx responses by default. Defaults to false.
+     * @param {number} [config.timeoutMs] - Default request timeout in milliseconds. Set per-request `timeoutMs: 0` to disable.
      * @param {string} [config.credentials] - Default fetch credentials mode.
      * @param {import("./transports/select.js").TransportName | import("./transports/select.js").Transport} [config.transport] - Transport preference or instance. Defaults to "auto".
      */
-    constructor({ baseUrl, socketPath, tls, keepAlive, headers, retry, throwOnError, credentials, transport }?: {
+    constructor({ baseUrl, socketPath, tls, keepAlive, headers, retry, throwOnError, timeoutMs, credentials, transport }?: {
         baseUrl?: string;
         socketPath?: string;
         tls?: {
@@ -57,6 +67,7 @@ export default class SnapReq {
         headers?: Record<string, string | number> | (() => Record<string, string | number>);
         retry?: boolean | import("./retry.js").RetryOptions;
         throwOnError?: boolean;
+        timeoutMs?: number;
         credentials?: string;
         transport?: import("./transports/select.js").TransportName | import("./transports/select.js").Transport;
     });
@@ -64,6 +75,7 @@ export default class SnapReq {
     defaultHeaders: Record<string, string | number> | (() => Record<string, string | number>);
     defaultRetry: boolean | import("./retry.js").RetryOptions;
     throwOnError: boolean;
+    timeoutMs: number;
     credentials: string;
     _transportPreference: import("./transports/select.js").TransportName | import("./transports/select.js").Transport;
     _nodeConfig: {
@@ -91,6 +103,32 @@ export default class SnapReq {
      * @returns {NormalizedRequest} - The normalized request.
      */
     _normalize(options: RequestOptions): NormalizedRequest;
+    /**
+     * @param {RequestOptions} options - Request options.
+     * @returns {RequestTimeout} - Timeout handling for one request attempt.
+     */
+    _requestTimeout(options: RequestOptions): RequestTimeout;
+    /**
+     * @param {AbortSignal | undefined} callerSignal - Caller-supplied signal.
+     * @param {AbortSignal} timeoutSignal - Timeout signal.
+     * @returns {{signal: AbortSignal, clear: () => void}} - Signal that aborts when either source aborts.
+     */
+    _composeSignal(callerSignal: AbortSignal | undefined, timeoutSignal: AbortSignal): {
+        signal: AbortSignal;
+        clear: () => void;
+    };
+    /**
+     * @param {(() => void) | undefined} existing - Existing body-done callback.
+     * @param {() => void} next - Callback to add.
+     * @returns {() => void} - Combined callback.
+     */
+    _chainBodyDone(existing: (() => void) | undefined, next: () => void): () => void;
+    /**
+     * @param {((error: unknown) => unknown) | undefined} existing - Existing error mapper.
+     * @param {(error: unknown) => unknown} next - Mapper to add.
+     * @returns {(error: unknown) => unknown} - Combined mapper.
+     */
+    _chainBodyError(existing: ((error: unknown) => unknown) | undefined, next: (error: unknown) => unknown): (error: unknown) => unknown;
     /**
      * Performs a request and buffers nothing eagerly — read the body via the
      * returned response (`json()`, `text()`, `bytes()`). Retries transient
@@ -107,6 +145,12 @@ export default class SnapReq {
      * @returns {Promise<import("./response.js").default>} - The streaming response.
      */
     requestStream(options: RequestOptions): Promise<import("./response.js").default>;
+    /**
+     * @param {RequestOptions} options - Request options.
+     * @param {(request: NormalizedRequest) => Promise<import("./response.js").default>} performRequest - Transport request runner.
+     * @returns {Promise<import("./response.js").default>} - Response with timeout handling attached.
+     */
+    _requestWithTimeout(options: RequestOptions, performRequest: (request: NormalizedRequest) => Promise<import("./response.js").default>): Promise<import("./response.js").default>;
     /**
      * @param {string} path - Request path or absolute URL.
      * @param {RequestOptions} [options] - Request options.
@@ -178,6 +222,10 @@ export type NormalizedRequest = {
      * - Abort signal.
      */
     signal?: AbortSignal;
+    /**
+     * - Request timeout in milliseconds.
+     */
+    timeoutMs?: number;
     /**
      * - Fetch credentials mode ("omit" | "same-origin" | "include").
      */
@@ -216,6 +264,10 @@ export type RequestOptions = {
      * - Abort signal for the request.
      */
     signal?: AbortSignal;
+    /**
+     * - Request timeout in milliseconds. Set to `0` to disable a client default.
+     */
+    timeoutMs?: number;
     /**
      * - Fetch credentials mode.
      */
@@ -229,5 +281,23 @@ export type RequestOptions = {
      */
     throwOnError?: boolean;
 };
+export type RequestTimeout = {
+    /**
+     * - Signal to use for the request.
+     */
+    signal: AbortSignal | undefined;
+    /**
+     * - Clears timeout resources.
+     */
+    clear: () => void;
+    /**
+     * - Attaches timeout handling to a response.
+     */
+    response: (response: import("./response.js").default, request: NormalizedRequest) => import("./response.js").default;
+    /**
+     * - Maps a thrown error.
+     */
+    error: (error: unknown, request: NormalizedRequest) => unknown;
+};
 import { SnapReqHttpError } from "./errors.js";
 import SnapReqHeaders from "./headers.js";