snapreq 0.0.1 → 0.0.4

package/README.md

@@ -15,6 +15,19 @@ The same code runs everywhere. Where a platform cannot provide a feature (Unix s
 npm install snapreq
 ```
 
+## Imports
+
+snapreq has **no barrel entry point** — you import each piece from its own subpath so a bundler (Metro/Expo, webpack, …) only pulls in what you use, and the HTTP client never drags the WebSocket client into your bundle:
+
+```js
+import SnapReq from "snapreq"                       // the HTTP client
+import SnapReqWebSocketClient from "snapreq/websocket"
+import {SnapReqHttpError, SnapReqUnsupportedFeatureError} from "snapreq/errors"
+import {defaultRetryableError} from "snapreq/retry"
+import SnapReqResponse from "snapreq/response"
+import SnapReqHeaders from "snapreq/headers"
+```
+
 ## HTTP
 
 ```js
@@ -50,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
 
@@ -60,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.
@@ -69,7 +94,7 @@ await client.get("/flaky", {retry: true})
 await client.get("/flaky", {retry: {tries: 5, waitMs: 200, retryableStatuses: [503]}})
 
 // Compose extra rules on top of the default network classifier:
-import {defaultRetryableError} from "snapreq"
+import {defaultRetryableError} from "snapreq/retry"
 
 await client.get("/x", {retry: {shouldRetry: (error) => defaultRetryableError(error) || isMyCase(error)}})
 ```
@@ -118,7 +143,7 @@ const caps = await client.capabilities()
 A WebSocket client over `globalThis.WebSocket` with auto-reconnect, session resumption, request/response calls, channel subscriptions and 1:1 connections.
 
 ```js
-import {SnapReqWebSocketClient} from "snapreq"
+import SnapReqWebSocketClient from "snapreq/websocket"
 
 const client = new SnapReqWebSocketClient({url: "wss://example.com/websocket"})
 
@@ -137,7 +162,7 @@ await connection.ready
 connection.sendMessage({text: "hi"})
 ```
 
-Optional adapters: `networkMonitor` (gate reconnects on online state) and `sessionStore` (persist the session id across reloads).
+Optional adapters: `networkMonitor` (gate reconnects on online state), `sessionStore` (persist the session id across reloads) and `deserialize` (a `(value) => value` transform applied inside `response.json()` so an app can re-hydrate its own wire format).
 
 ## License
 

package/package.json

@@ -1,17 +1,66 @@
 {
   "name": "snapreq",
-  "version": "0.0.1",
+  "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/index.js",
+  "main": "./src/snap-req.js",
+  "types": "./types/snap-req.d.ts",
   "exports": {
-    ".": "./src/index.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/**"
+    "src/**",
+    "types/**"
   ],
   "scripts": {
+    "all-checks": "npm run typecheck && npm run lint && npm run test",
+    "build:types": "tsc -p tsconfig.build.json",
     "lint": "eslint src spec",
+    "prepublishOnly": "npm run build:types",
+    "release:patch": "release-patch",
     "test": "node --test \"spec/**/*-spec.js\"",
     "typecheck": "tsc --noEmit"
   },
@@ -27,12 +76,13 @@
   "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/src/websocket/websocket-client.js

@@ -31,11 +31,14 @@ export default class SnapReqWebSocketClient {
    * @param {{getIsOnline?: () => boolean | Promise<boolean>, subscribe?: (callback: (isOnline: boolean) => void) => (() => void) | {remove: () => void}}} [args.networkMonitor] - Optional online-state adapter. When provided, auto-reconnect can wait for the network to report online before reconnecting, and open sockets are closed when the monitor reports offline.
    * @param {number[]} [args.reconnectDelays] - Backoff delays in ms (default: [1000, 2000, 4000, 8000, 15000]).
    * @param {{get: () => string | null | undefined | Promise<string | null | undefined>, set: (sessionId: string) => void | Promise<void>, clear: () => void | Promise<void>}} [args.sessionStore] - Optional sessionId persistence hook surviving reloads (localStorage, a cookie, SQLite, etc.).
+   * @param {(value: any) => any} [args.deserialize] - Optional transform applied to a response body inside `response.json()`. Lets an app re-hydrate its own wire format. Defaults to identity.
    */
-  constructor({autoReconnect = true, debug = false, networkMonitor, reconnectDelays, sessionStore, url} = /** @type {any} */ ({})) {
+  constructor({autoReconnect = true, debug = false, deserialize, networkMonitor, reconnectDelays, sessionStore, url} = /** @type {any} */ ({})) {
     if (!globalThis.WebSocket) throw new Error("WebSocket global is not available")
     if (!url) throw new Error("SnapReqWebSocketClient requires a url")
 
+    /** @type {(value: any) => any} */
+    this._deserialize = deserialize || ((value) => value)
     /** @type {boolean} */
     this.autoReconnect = autoReconnect
     this.debug = debug
@@ -637,7 +640,7 @@ export default class SnapReqWebSocketClient {
 
       if (pending) {
         this.pendingRequests.delete(id)
-        pending.resolve(new SnapReqWebSocketResponse(message))
+        pending.resolve(new SnapReqWebSocketResponse(message, this._deserialize))
       } else {
         this._debug(`No pending request for response id ${id}`)
       }
@@ -1006,8 +1009,9 @@ export default class SnapReqWebSocketClient {
 export class SnapReqWebSocketResponse {
   /**
    * @param {object} message - The response message.
+   * @param {(value: any) => any} [deserialize] - Transform applied to the parsed body in `json()`. Defaults to identity.
    */
-  constructor(message) {
+  constructor(message, deserialize) {
     const responseMessage = /** @type {{body?: any, headers?: Record<string, any>, id?: string | number | null, statusCode?: number, statusMessage?: string, type?: string}} */ (message)
 
     this.body = responseMessage.body
@@ -1016,14 +1020,15 @@ export class SnapReqWebSocketResponse {
     this.statusCode = responseMessage.statusCode || 200
     this.statusMessage = responseMessage.statusMessage || "OK"
     this.type = responseMessage.type
+    this._deserialize = deserialize || ((value) => value)
   }
 
-  /** @returns {any} - The parsed JSON body. */
+  /** @returns {any} - The parsed (and optionally deserialized) JSON body. */
   json() {
     if (typeof this.body !== "string") {
       throw new Error("Response body is not a string")
     }
 
-    return JSON.parse(this.body)
+    return this._deserialize(JSON.parse(this.body))
   }
 }

package/types/capabilities.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @typedef {object} TransportCapabilities
+ * @property {boolean} unixSocket - Connect over a Unix domain socket.
+ * @property {boolean} tlsClientCert - Present a client certificate / custom CA for TLS.
+ * @property {boolean} requestCompression - Compress the request body (gzip/deflate/br/zstd).
+ * @property {boolean} responseStreaming - Expose the response body as a stream before it is fully read.
+ * @property {boolean} requestStreaming - Send a streamed (async-iterable) request body.
+ * @property {boolean} keepAlive - Reuse connections across requests (HTTP keep-alive).
+ * @property {boolean} abort - Cancel an in-flight request via an `AbortSignal`.
+ */
+/**
+ * Builds a fully-populated capability object so callers can read every flag
+ * without undefined checks.
+ * @param {Partial<TransportCapabilities>} overrides - Capabilities the transport supports.
+ * @returns {TransportCapabilities} - Complete capability flags.
+ */
+export function buildCapabilities(overrides: Partial<TransportCapabilities>): TransportCapabilities;
+export type TransportCapabilities = {
+    /**
+     * - Connect over a Unix domain socket.
+     */
+    unixSocket: boolean;
+    /**
+     * - Present a client certificate / custom CA for TLS.
+     */
+    tlsClientCert: boolean;
+    /**
+     * - Compress the request body (gzip/deflate/br/zstd).
+     */
+    requestCompression: boolean;
+    /**
+     * - Expose the response body as a stream before it is fully read.
+     */
+    responseStreaming: boolean;
+    /**
+     * - Send a streamed (async-iterable) request body.
+     */
+    requestStreaming: boolean;
+    /**
+     * - Reuse connections across requests (HTTP keep-alive).
+     */
+    keepAlive: boolean;
+    /**
+     * - Cancel an in-flight request via an `AbortSignal`.
+     */
+    abort: boolean;
+};