rezo 1.0.11 → 1.0.13

package/dist/adapters/http2.js

@@ -4,14 +4,15 @@ import { URL } from "node:url";
 import { Readable } from "node:stream";
 import { RezoError } from '../errors/rezo-error.js';
 import { buildSmartError, buildDecompressionError, builErrorFromResponse, buildDownloadError } from '../responses/buildError.js';
-import { Cookie } from '../utils/cookies.js';
+import { RezoCookieJar } from '../utils/cookies.js';
 import RezoFormData from '../utils/form-data.js';
 import { getDefaultConfig, prepareHTTPOptions } from '../utils/http-config.js';
-import { RezoHeaders } from '../utils/headers.js';
+import { RezoHeaders, sanitizeHttp2Headers } from '../utils/headers.js';
 import { RezoURLSearchParams } from '../utils/data-operations.js';
 import { StreamResponse } from '../responses/stream.js';
 import { DownloadResponse } from '../responses/download.js';
 import { UploadResponse } from '../responses/upload.js';
+import { CompressionUtil } from '../utils/compression.js';
 import { isSameDomain, RezoPerformance } from '../utils/tools.js';
 import { ResponseCache } from '../cache/response-cache.js';
 let zstdDecompressSync = null;
@@ -142,6 +143,9 @@ class Http2SessionPool {
           reject(new Error(`HTTP/2 connection timeout after ${timeout}ms`));
         }
       }, timeout) : null;
+      if (timeoutId && typeof timeoutId === "object" && "unref" in timeoutId) {
+        timeoutId.unref();
+      }
       session.on("connect", () => {
         if (!settled) {
           settled = true;
@@ -166,6 +170,12 @@ class Http2SessionPool {
     if (entry) {
       entry.refCount = Math.max(0, entry.refCount - 1);
       entry.lastUsed = Date.now();
+      if (entry.refCount === 0) {
+        const socket = entry.session.socket;
+        if (socket && typeof socket.unref === "function") {
+          socket.unref();
+        }
+      }
     }
   }
   closeSession(url) {
@@ -271,38 +281,66 @@ function updateCookies(config, headers, url) {
   if (!setCookieHeaders)
     return;
   const cookieHeaderArray = Array.isArray(setCookieHeaders) ? setCookieHeaders : [setCookieHeaders];
-  if (!config.responseCookies) {
-    config.responseCookies = {
-      array: [],
-      serialized: [],
-      netscape: "",
-      string: "",
-      setCookiesString: []
-    };
+  if (cookieHeaderArray.length === 0)
+    return;
+  const jar = new RezoCookieJar;
+  jar.setCookiesSync(cookieHeaderArray, url);
+  if (config.enableCookieJar && config.cookieJar) {
+    config.cookieJar.setCookiesSync(cookieHeaderArray, url);
   }
-  for (const cookieStr of cookieHeaderArray) {
-    config.responseCookies.setCookiesString.push(cookieStr);
-    const parts = cookieStr.split(";");
-    const [nameValue] = parts;
-    const [name, ...valueParts] = nameValue.split("=");
-    const value = valueParts.join("=");
-    if (name && value !== undefined) {
-      const cookie = new Cookie({
-        key: name.trim(),
-        value: value.trim(),
-        domain: new URL(url).hostname,
-        path: "/",
-        httpOnly: cookieStr.toLowerCase().includes("httponly"),
-        secure: cookieStr.toLowerCase().includes("secure"),
-        sameSite: "lax"
-      });
-      config.responseCookies.array.push(cookie);
+  const cookies = jar.cookies();
+  cookies.setCookiesString = cookieHeaderArray;
+  if (config.useCookies) {
+    const existingArray = config.responseCookies?.array || [];
+    for (const cookie of cookies.array) {
+      const existingIndex = existingArray.findIndex((c) => c.key === cookie.key && c.domain === cookie.domain);
+      if (existingIndex >= 0) {
+        existingArray[existingIndex] = cookie;
+      } else {
+        existingArray.push(cookie);
+      }
     }
+    const mergedJar = new RezoCookieJar(existingArray, url);
+    config.responseCookies = mergedJar.cookies();
+    config.responseCookies.setCookiesString = cookieHeaderArray;
+  } else {
+    config.responseCookies = cookies;
   }
-  config.responseCookies.string = config.responseCookies.array.map((c) => `${c.key}=${c.value}`).join("; ");
-  config.responseCookies.serialized = config.responseCookies.array.map((c) => c.toJSON());
-  config.responseCookies.netscape = config.responseCookies.array.map((c) => c.toNetscapeFormat()).join(`
-`);
+}
+function mergeRequestAndResponseCookies(config, responseCookies, url) {
+  const mergedCookiesArray = [];
+  const cookieKeyDomainMap = new Map;
+  if (config.requestCookies && config.requestCookies.length > 0) {
+    for (const cookie of config.requestCookies) {
+      const key = `${cookie.key}|${cookie.domain || ""}`;
+      mergedCookiesArray.push(cookie);
+      cookieKeyDomainMap.set(key, mergedCookiesArray.length - 1);
+    }
+  }
+  for (const cookie of responseCookies.array) {
+    const key = `${cookie.key}|${cookie.domain || ""}`;
+    const existingIndex = cookieKeyDomainMap.get(key);
+    if (existingIndex !== undefined) {
+      mergedCookiesArray[existingIndex] = cookie;
+    } else {
+      mergedCookiesArray.push(cookie);
+      cookieKeyDomainMap.set(key, mergedCookiesArray.length - 1);
+    }
+  }
+  if (mergedCookiesArray.length > 0) {
+    const mergedJar = new RezoCookieJar(mergedCookiesArray, url);
+    return mergedJar.cookies();
+  }
+  return {
+    array: [],
+    serialized: [],
+    netscape: `# Netscape HTTP Cookie File
+# This file was generated by Rezo HTTP client
+# Based on uniqhtt cookie implementation
+`,
+    string: "",
+    setCookiesString: []
+  };
 }
 export async function executeRequest(options, defaultOptions, jar) {
   if (!options.responseType) {
@@ -480,6 +518,8 @@ async function executeHttp2Request(fetchOptions, config, options, perform, fs, s
         if (fileName && fs && fs.existsSync(fileName)) {
           fs.unlinkSync(fileName);
         }
+        if (!config.errors)
+          config.errors = [];
         config.errors.push({
           attempt: config.retryAttempts + 1,
           error: response,
@@ -517,7 +557,7 @@ async function executeHttp2Request(fetchOptions, config, options, perform, fs, s
         }
         continue;
       }
-      if (statusOnNext === "success") {
+      if (statusOnNext === "success" || statusOnNext === "error") {
         return response;
       }
       if (statusOnNext === "redirect") {
@@ -616,6 +656,13 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
       if (!headers["accept-encoding"]) {
         headers["accept-encoding"] = "gzip, deflate, br";
       }
+      if (body instanceof RezoFormData) {
+        headers["content-type"] = `multipart/form-data; boundary=${body.getBoundary()}`;
+      } else if (body instanceof FormData) {
+        const tempForm = await RezoFormData.fromNativeFormData(body);
+        headers["content-type"] = `multipart/form-data; boundary=${tempForm.getBoundary()}`;
+        fetchOptions._convertedFormData = tempForm;
+      }
       const eventEmitter = streamResult || downloadResult || uploadResult;
       if (eventEmitter && requestCount === 0) {
         const startEvent = {
@@ -731,6 +778,25 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
         config.timing.endTimestamp = Date.now();
         config.timing.durationMs = performance.now() - timing.startTime;
         config.timing.transferMs = timing.firstByteTime ? performance.now() - timing.firstByteTime : config.timing.durationMs;
+        if (!config.transfer) {
+          config.transfer = { requestSize: 0, responseSize: 0, headerSize: 0, bodySize: 0 };
+        }
+        if (config.transfer.requestSize === undefined) {
+          config.transfer.requestSize = 0;
+        }
+        if (config.transfer.requestSize === 0 && body) {
+          if (typeof body === "string") {
+            config.transfer.requestSize = Buffer.byteLength(body, "utf8");
+          } else if (body instanceof Buffer || body instanceof Uint8Array) {
+            config.transfer.requestSize = body.length;
+          } else if (body instanceof URLSearchParams || body instanceof RezoURLSearchParams) {
+            config.transfer.requestSize = Buffer.byteLength(body.toString(), "utf8");
+          } else if (body instanceof RezoFormData) {
+            config.transfer.requestSize = body.getLengthSync();
+          } else if (typeof body === "object") {
+            config.transfer.requestSize = Buffer.byteLength(JSON.stringify(body), "utf8");
+          }
+        }
         config.transfer.bodySize = contentLengthCounter;
         config.transfer.responseSize = contentLengthCounter;
         (sessionPool || Http2SessionPool.getInstance()).releaseSession(url);
@@ -739,7 +805,7 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
             data: "",
             status,
             statusText,
-            headers: new RezoHeaders(responseHeaders),
+            headers: new RezoHeaders(sanitizeHttp2Headers(responseHeaders)),
             cookies: config.responseCookies || { array: [], serialized: [], netscape: "", string: "", setCookiesString: [] },
             config,
             contentType: responseHeaders["content-type"],
@@ -752,14 +818,14 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
         }
         let responseBody = Buffer.concat(chunks);
         const contentEncoding = responseHeaders["content-encoding"];
-        if (contentEncoding && contentLengthCounter > 0) {
+        if (contentEncoding && contentLengthCounter > 0 && CompressionUtil.shouldDecompress(contentEncoding, config)) {
           try {
             const decompressed = await decompressBuffer(responseBody, contentEncoding);
             responseBody = decompressed;
           } catch (err) {
             const error = buildDecompressionError({
               statusCode: status,
-              headers: responseHeaders,
+              headers: sanitizeHttp2Headers(responseHeaders),
               contentType: responseHeaders["content-type"],
               contentLength: String(contentLengthCounter),
               cookies: config.responseCookies?.setCookiesString || [],
@@ -799,24 +865,17 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
             data = responseBody.toString("utf-8");
           }
         }
-        if (status >= 400) {
-          const error = builErrorFromResponse(`HTTP Error ${status}: ${statusText}`, {
-            status,
-            statusText,
-            headers: new RezoHeaders(responseHeaders),
-            data
-          }, config, fetchOptions);
-          _stats.statusOnNext = "error";
-          resolve(error);
-          return;
-        }
-        _stats.statusOnNext = "success";
+        config.status = status;
+        config.statusText = statusText;
+        _stats.statusOnNext = status >= 400 ? "error" : "success";
+        const responseCookies = config.responseCookies || { array: [], serialized: [], netscape: "", string: "", setCookiesString: [] };
+        const mergedCookies = mergeRequestAndResponseCookies(config, responseCookies, url.href);
         const finalResponse = {
           data,
           status,
           statusText,
-          headers: new RezoHeaders(responseHeaders),
-          cookies: config.responseCookies || { array: [], serialized: [], netscape: "", string: "", setCookiesString: [] },
+          headers: new RezoHeaders(sanitizeHttp2Headers(responseHeaders)),
+          cookies: mergedCookies,
           config,
           contentType,
           contentLength: contentLengthCounter,
@@ -829,11 +888,11 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
             const downloadFinishEvent = {
               status,
               statusText,
-              headers: new RezoHeaders(responseHeaders),
+              headers: new RezoHeaders(sanitizeHttp2Headers(responseHeaders)),
               contentType,
               contentLength: responseBody.length,
               finalUrl: url.href,
-              cookies: config.responseCookies || { array: [], serialized: [], netscape: "", string: "", setCookiesString: [] },
+              cookies: mergedCookies,
               urls: buildUrlTree(config, url.href),
               fileName: config.fileName,
               fileSize: responseBody.length,
@@ -854,7 +913,7 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
           } catch (err) {
             const error = buildDownloadError({
               statusCode: status,
-              headers: responseHeaders,
+              headers: sanitizeHttp2Headers(responseHeaders),
               contentType,
               contentLength: String(contentLengthCounter),
               cookies: config.responseCookies?.setCookiesString || [],
@@ -874,7 +933,7 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
           const streamFinishEvent = {
             status,
             statusText,
-            headers: new RezoHeaders(responseHeaders),
+            headers: new RezoHeaders(sanitizeHttp2Headers(responseHeaders)),
             contentType,
             contentLength: contentLengthCounter,
             finalUrl: url.href,
@@ -900,7 +959,7 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
             response: {
               status,
               statusText,
-              headers: new RezoHeaders(responseHeaders),
+              headers: new RezoHeaders(sanitizeHttp2Headers(responseHeaders)),
               data,
               contentType,
               contentLength: contentLengthCounter
@@ -945,7 +1004,7 @@ async function executeHttp2Stream(config, fetchOptions, requestCount, timing, _s
             body.pipe(req);
             return;
           } else {
-            const form = await RezoFormData.fromNativeFormData(body);
+            const form = fetchOptions._convertedFormData || await RezoFormData.fromNativeFormData(body);
             form.pipe(req);
             return;
           }

package/dist/adapters/index.cjs

@@ -1,6 +1,6 @@
-const _mod_2r8qwe = require('./picker.cjs');
-exports.detectRuntime = _mod_2r8qwe.detectRuntime;
-exports.getAdapterCapabilities = _mod_2r8qwe.getAdapterCapabilities;
-exports.buildAdapterContext = _mod_2r8qwe.buildAdapterContext;
-exports.getAvailableAdapters = _mod_2r8qwe.getAvailableAdapters;
-exports.selectAdapter = _mod_2r8qwe.selectAdapter;;
+const _mod_h6yyuw = require('./picker.cjs');
+exports.detectRuntime = _mod_h6yyuw.detectRuntime;
+exports.getAdapterCapabilities = _mod_h6yyuw.getAdapterCapabilities;
+exports.buildAdapterContext = _mod_h6yyuw.buildAdapterContext;
+exports.getAvailableAdapters = _mod_h6yyuw.getAvailableAdapters;
+exports.selectAdapter = _mod_h6yyuw.selectAdapter;;

package/dist/cache/index.cjs

@@ -1,13 +1,13 @@
-const _mod_n1lpkm = require('./lru-cache.cjs');
-exports.LRUCache = _mod_n1lpkm.LRUCache;;
-const _mod_iq5ukf = require('./dns-cache.cjs');
-exports.DNSCache = _mod_iq5ukf.DNSCache;
-exports.getGlobalDNSCache = _mod_iq5ukf.getGlobalDNSCache;
-exports.resetGlobalDNSCache = _mod_iq5ukf.resetGlobalDNSCache;;
-const _mod_f96z7x = require('./response-cache.cjs');
-exports.ResponseCache = _mod_f96z7x.ResponseCache;
-exports.normalizeResponseCacheConfig = _mod_f96z7x.normalizeResponseCacheConfig;;
-const _mod_j5l68j = require('./file-cacher.cjs');
-exports.FileCacher = _mod_j5l68j.FileCacher;;
-const _mod_2bqslo = require('./url-store.cjs');
-exports.UrlStore = _mod_2bqslo.UrlStore;;
+const _mod_vgyhxh = require('./lru-cache.cjs');
+exports.LRUCache = _mod_vgyhxh.LRUCache;;
+const _mod_57d30y = require('./dns-cache.cjs');
+exports.DNSCache = _mod_57d30y.DNSCache;
+exports.getGlobalDNSCache = _mod_57d30y.getGlobalDNSCache;
+exports.resetGlobalDNSCache = _mod_57d30y.resetGlobalDNSCache;;
+const _mod_qx55fg = require('./response-cache.cjs');
+exports.ResponseCache = _mod_qx55fg.ResponseCache;
+exports.normalizeResponseCacheConfig = _mod_qx55fg.normalizeResponseCacheConfig;;
+const _mod_clz0cm = require('./file-cacher.cjs');
+exports.FileCacher = _mod_clz0cm.FileCacher;;
+const _mod_39vswi = require('./url-store.cjs');
+exports.UrlStore = _mod_39vswi.UrlStore;;

package/dist/crawler.d.ts

@@ -2620,8 +2620,73 @@ export interface RezoRequestConfig<D = any> {
 	maxRedirects?: number;
 	/** Whether to automatically decompress response data */
 	decompress?: boolean;
-	/** Whether to keep the connection alive for reuse */
+	/**
+	 * Whether to keep TCP connections alive for reuse across multiple requests.
+	 *
+	 * When enabled, the underlying TCP connection is kept open after a request completes,
+	 * allowing subsequent requests to the same host to reuse the connection. This reduces
+	 * latency by avoiding the overhead of establishing new connections (TCP handshake,
+	 * TLS negotiation for HTTPS).
+	 *
+	 * **Behavior:**
+	 * - `false` (default) - Connection closes after each request. Process exits immediately.
+	 * - `true` - Connection stays open for reuse. Idle connections close after `keepAliveMsecs`.
+	 *
+	 * **When to use `keepAlive: true`:**
+	 * - Making multiple requests to the same host in sequence
+	 * - Long-running applications (servers, bots, scrapers)
+	 * - Performance-critical applications where connection overhead matters
+	 *
+	 * **When to use `keepAlive: false` (default):**
+	 * - Single requests or scripts that should exit immediately
+	 * - CLI tools that make one-off requests
+	 * - When you need predictable process termination
+	 *
+	 * @example
+	 * ```typescript
+	 * // Default: process exits immediately after request
+	 * const { data } = await rezo.get('https://api.example.com/data');
+	 *
+	 * // Keep connection alive for 1 minute (default) for subsequent requests
+	 * const client = new Rezo({ keepAlive: true });
+	 * await client.get('https://api.example.com/users');
+	 * await client.get('https://api.example.com/posts'); // Reuses connection
+	 *
+	 * // Custom keep-alive timeout (30 seconds)
+	 * const client = new Rezo({ keepAlive: true, keepAliveMsecs: 30000 });
+	 * ```
+	 *
+	 * @default false
+	 */
 	keepAlive?: boolean;
+	/**
+	 * How long to keep idle connections alive in milliseconds.
+	 *
+	 * Only applies when `keepAlive: true`. After this duration of inactivity,
+	 * the connection is closed automatically. This prevents resource leaks
+	 * from connections that are no longer needed.
+	 *
+	 * **Note:** Even with keep-alive enabled, the Node.js process can still exit
+	 * cleanly when there's no other work to do, thanks to socket unreferencing.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Keep connections alive for 30 seconds
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 30000
+	 * });
+	 *
+	 * // Keep connections alive for 2 minutes
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 120000
+	 * });
+	 * ```
+	 *
+	 * @default 60000 (1 minute)
+	 */
+	keepAliveMsecs?: number;
 	withoutBodyOnRedirect?: boolean;
 	autoSetReferer?: boolean;
 	autoSetOrigin?: boolean;

package/dist/entries/crawler.cjs

@@ -1,5 +1,5 @@
-const _mod_260i4j = require('../plugin/crawler.cjs');
-exports.Crawler = _mod_260i4j.Crawler;;
-const _mod_laig8l = require('../plugin/crawler-options.cjs');
-exports.CrawlerOptions = _mod_laig8l.CrawlerOptions;
-exports.Domain = _mod_laig8l.Domain;;
+const _mod_m9euun = require('../plugin/crawler.cjs');
+exports.Crawler = _mod_m9euun.Crawler;;
+const _mod_358g2f = require('../plugin/crawler-options.cjs');
+exports.CrawlerOptions = _mod_358g2f.CrawlerOptions;
+exports.Domain = _mod_358g2f.Domain;;

package/dist/index.cjs

@@ -1,27 +1,27 @@
-const _mod_ivdy34 = require('./core/rezo.cjs');
-exports.Rezo = _mod_ivdy34.Rezo;
-exports.createRezoInstance = _mod_ivdy34.createRezoInstance;
-exports.createDefaultInstance = _mod_ivdy34.createDefaultInstance;;
-const _mod_eleqc6 = require('./errors/rezo-error.cjs');
-exports.RezoError = _mod_eleqc6.RezoError;
-exports.RezoErrorCode = _mod_eleqc6.RezoErrorCode;;
-const _mod_s3mojl = require('./utils/headers.cjs');
-exports.RezoHeaders = _mod_s3mojl.RezoHeaders;;
-const _mod_ltzvhk = require('./utils/form-data.cjs');
-exports.RezoFormData = _mod_ltzvhk.RezoFormData;;
-const _mod_9b4i5y = require('./utils/cookies.cjs');
-exports.RezoCookieJar = _mod_9b4i5y.RezoCookieJar;
-exports.Cookie = _mod_9b4i5y.Cookie;;
-const _mod_ip126y = require('./core/hooks.cjs');
-exports.createDefaultHooks = _mod_ip126y.createDefaultHooks;
-exports.mergeHooks = _mod_ip126y.mergeHooks;;
-const _mod_zptoz7 = require('./proxy/manager.cjs');
-exports.ProxyManager = _mod_zptoz7.ProxyManager;;
-const _mod_qvzoi6 = require('./queue/index.cjs');
-exports.RezoQueue = _mod_qvzoi6.RezoQueue;
-exports.HttpQueue = _mod_qvzoi6.HttpQueue;
-exports.Priority = _mod_qvzoi6.Priority;
-exports.HttpMethodPriority = _mod_qvzoi6.HttpMethodPriority;;
+const _mod_txkkmz = require('./core/rezo.cjs');
+exports.Rezo = _mod_txkkmz.Rezo;
+exports.createRezoInstance = _mod_txkkmz.createRezoInstance;
+exports.createDefaultInstance = _mod_txkkmz.createDefaultInstance;;
+const _mod_a3vsp1 = require('./errors/rezo-error.cjs');
+exports.RezoError = _mod_a3vsp1.RezoError;
+exports.RezoErrorCode = _mod_a3vsp1.RezoErrorCode;;
+const _mod_2ef980 = require('./utils/headers.cjs');
+exports.RezoHeaders = _mod_2ef980.RezoHeaders;;
+const _mod_e56bdp = require('./utils/form-data.cjs');
+exports.RezoFormData = _mod_e56bdp.RezoFormData;;
+const _mod_ss7zpn = require('./utils/cookies.cjs');
+exports.RezoCookieJar = _mod_ss7zpn.RezoCookieJar;
+exports.Cookie = _mod_ss7zpn.Cookie;;
+const _mod_vdi6fa = require('./core/hooks.cjs');
+exports.createDefaultHooks = _mod_vdi6fa.createDefaultHooks;
+exports.mergeHooks = _mod_vdi6fa.mergeHooks;;
+const _mod_049k4s = require('./proxy/manager.cjs');
+exports.ProxyManager = _mod_049k4s.ProxyManager;;
+const _mod_5l0v67 = require('./queue/index.cjs');
+exports.RezoQueue = _mod_5l0v67.RezoQueue;
+exports.HttpQueue = _mod_5l0v67.HttpQueue;
+exports.Priority = _mod_5l0v67.Priority;
+exports.HttpMethodPriority = _mod_5l0v67.HttpMethodPriority;;
 const { RezoError } = require('./errors/rezo-error.cjs');
 const isRezoError = exports.isRezoError = RezoError.isRezoError;
 const Cancel = exports.Cancel = RezoError;

package/dist/index.d.ts

@@ -2628,8 +2628,73 @@ export interface RezoRequestConfig<D = any> {
 	maxRedirects?: number;
 	/** Whether to automatically decompress response data */
 	decompress?: boolean;
-	/** Whether to keep the connection alive for reuse */
+	/**
+	 * Whether to keep TCP connections alive for reuse across multiple requests.
+	 *
+	 * When enabled, the underlying TCP connection is kept open after a request completes,
+	 * allowing subsequent requests to the same host to reuse the connection. This reduces
+	 * latency by avoiding the overhead of establishing new connections (TCP handshake,
+	 * TLS negotiation for HTTPS).
+	 *
+	 * **Behavior:**
+	 * - `false` (default) - Connection closes after each request. Process exits immediately.
+	 * - `true` - Connection stays open for reuse. Idle connections close after `keepAliveMsecs`.
+	 *
+	 * **When to use `keepAlive: true`:**
+	 * - Making multiple requests to the same host in sequence
+	 * - Long-running applications (servers, bots, scrapers)
+	 * - Performance-critical applications where connection overhead matters
+	 *
+	 * **When to use `keepAlive: false` (default):**
+	 * - Single requests or scripts that should exit immediately
+	 * - CLI tools that make one-off requests
+	 * - When you need predictable process termination
+	 *
+	 * @example
+	 * ```typescript
+	 * // Default: process exits immediately after request
+	 * const { data } = await rezo.get('https://api.example.com/data');
+	 *
+	 * // Keep connection alive for 1 minute (default) for subsequent requests
+	 * const client = new Rezo({ keepAlive: true });
+	 * await client.get('https://api.example.com/users');
+	 * await client.get('https://api.example.com/posts'); // Reuses connection
+	 *
+	 * // Custom keep-alive timeout (30 seconds)
+	 * const client = new Rezo({ keepAlive: true, keepAliveMsecs: 30000 });
+	 * ```
+	 *
+	 * @default false
+	 */
 	keepAlive?: boolean;
+	/**
+	 * How long to keep idle connections alive in milliseconds.
+	 *
+	 * Only applies when `keepAlive: true`. After this duration of inactivity,
+	 * the connection is closed automatically. This prevents resource leaks
+	 * from connections that are no longer needed.
+	 *
+	 * **Note:** Even with keep-alive enabled, the Node.js process can still exit
+	 * cleanly when there's no other work to do, thanks to socket unreferencing.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Keep connections alive for 30 seconds
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 30000
+	 * });
+	 *
+	 * // Keep connections alive for 2 minutes
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 120000
+	 * });
+	 * ```
+	 *
+	 * @default 60000 (1 minute)
+	 */
+	keepAliveMsecs?: number;
 	withoutBodyOnRedirect?: boolean;
 	autoSetReferer?: boolean;
 	autoSetOrigin?: boolean;

package/dist/platform/browser.d.ts

@@ -2502,8 +2502,73 @@ export interface RezoRequestConfig<D = any> {
 	maxRedirects?: number;
 	/** Whether to automatically decompress response data */
 	decompress?: boolean;
-	/** Whether to keep the connection alive for reuse */
+	/**
+	 * Whether to keep TCP connections alive for reuse across multiple requests.
+	 *
+	 * When enabled, the underlying TCP connection is kept open after a request completes,
+	 * allowing subsequent requests to the same host to reuse the connection. This reduces
+	 * latency by avoiding the overhead of establishing new connections (TCP handshake,
+	 * TLS negotiation for HTTPS).
+	 *
+	 * **Behavior:**
+	 * - `false` (default) - Connection closes after each request. Process exits immediately.
+	 * - `true` - Connection stays open for reuse. Idle connections close after `keepAliveMsecs`.
+	 *
+	 * **When to use `keepAlive: true`:**
+	 * - Making multiple requests to the same host in sequence
+	 * - Long-running applications (servers, bots, scrapers)
+	 * - Performance-critical applications where connection overhead matters
+	 *
+	 * **When to use `keepAlive: false` (default):**
+	 * - Single requests or scripts that should exit immediately
+	 * - CLI tools that make one-off requests
+	 * - When you need predictable process termination
+	 *
+	 * @example
+	 * ```typescript
+	 * // Default: process exits immediately after request
+	 * const { data } = await rezo.get('https://api.example.com/data');
+	 *
+	 * // Keep connection alive for 1 minute (default) for subsequent requests
+	 * const client = new Rezo({ keepAlive: true });
+	 * await client.get('https://api.example.com/users');
+	 * await client.get('https://api.example.com/posts'); // Reuses connection
+	 *
+	 * // Custom keep-alive timeout (30 seconds)
+	 * const client = new Rezo({ keepAlive: true, keepAliveMsecs: 30000 });
+	 * ```
+	 *
+	 * @default false
+	 */
 	keepAlive?: boolean;
+	/**
+	 * How long to keep idle connections alive in milliseconds.
+	 *
+	 * Only applies when `keepAlive: true`. After this duration of inactivity,
+	 * the connection is closed automatically. This prevents resource leaks
+	 * from connections that are no longer needed.
+	 *
+	 * **Note:** Even with keep-alive enabled, the Node.js process can still exit
+	 * cleanly when there's no other work to do, thanks to socket unreferencing.
+	 *
+	 * @example
+	 * ```typescript
+	 * // Keep connections alive for 30 seconds
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 30000
+	 * });
+	 *
+	 * // Keep connections alive for 2 minutes
+	 * const client = new Rezo({
+	 *   keepAlive: true,
+	 *   keepAliveMsecs: 120000
+	 * });
+	 * ```
+	 *
+	 * @default 60000 (1 minute)
+	 */
+	keepAliveMsecs?: number;
 	withoutBodyOnRedirect?: boolean;
 	autoSetReferer?: boolean;
 	autoSetOrigin?: boolean;