nlcurl 0.7.0 → 0.9.0

package/dist/utils/compression.js

@@ -0,0 +1,34 @@
+import * as zlib from "node:zlib";
+import { promisify } from "node:util";
+const gzipAsync = promisify(zlib.gzip);
+const deflateAsync = promisify(zlib.deflate);
+const brotliCompressAsync = promisify(zlib.brotliCompress);
+/**
+ * Compress a request body buffer with the specified encoding.
+ *
+ * @param {Buffer} body - Uncompressed body bytes.
+ * @param {RequestEncoding} encoding - Compression algorithm.
+ * @returns {Promise<Buffer>} Compressed buffer.
+ */
+export async function compressBody(body, encoding) {
+    switch (encoding) {
+        case "gzip":
+            return gzipAsync(body);
+        case "deflate":
+            return deflateAsync(body);
+        case "br":
+            return brotliCompressAsync(body);
+        default:
+            return body;
+    }
+}
+/**
+ * Determine whether a body is large enough to benefit from compression.
+ *
+ * @param {number} bodySize - Body size in bytes.
+ * @returns {boolean} `true` if the body meets the minimum threshold.
+ */
+export function shouldCompress(bodySize) {
+    return bodySize >= 1024;
+}
+//# sourceMappingURL=compression.js.map

package/dist/utils/compression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/utils/compression.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvC,MAAM,YAAY,GAAG,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC7C,MAAM,mBAAmB,GAAG,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAK3D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,QAAyB;IACxE,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM;YACT,OAAO,SAAS,CAAC,IAAI,CAAoB,CAAC;QAC5C,KAAK,SAAS;YACZ,OAAO,YAAY,CAAC,IAAI,CAAoB,CAAC;QAC/C,KAAK,IAAI;YACP,OAAO,mBAAmB,CAAC,IAAI,CAAoB,CAAC;QACtD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,QAAQ,IAAI,IAAI,CAAC;AAC1B,CAAC"}

package/dist/utils/dictionary-transport.d.ts

@@ -0,0 +1,97 @@
+/** Stored compression dictionary with associated metadata. */
+export interface CompressionDictionary {
+    /** SHA-256 hash of the dictionary data in structured field format. */
+    hash: string;
+    /** URL from which the dictionary was fetched. */
+    url: string;
+    /** Raw dictionary bytes. */
+    data: Buffer;
+    /** Timestamp (ms since epoch) when the dictionary was stored. */
+    storedAt: number;
+    /** URL match pattern from the `Use-As-Dictionary` header. */
+    matchPattern?: string;
+    /** Expiry timestamp (ms since epoch). */
+    expiresAt?: number;
+}
+/** Configuration for the compression dictionary store. */
+export interface DictionaryConfig {
+    /** Maximum number of dictionaries to cache. */
+    maxEntries?: number;
+    /** Maximum individual dictionary size in bytes. */
+    maxDictionarySize?: number;
+}
+/**
+ * Parse a `Use-As-Dictionary` response header.
+ *
+ * @param {string} header - Raw header value.
+ * @returns {{ match?: string; matchDest?: string[]; id?: string } | null} Parsed fields, or `null` if the header is empty.
+ */
+export declare function parseUseAsDictionary(header: string): {
+    match?: string;
+    matchDest?: string[];
+    id?: string;
+} | null;
+/**
+ * Compute the SHA-256 structured hash of dictionary data.
+ *
+ * @param {Buffer} data - Raw dictionary bytes.
+ * @returns {string} Hash string in structured field byte-sequence format.
+ */
+export declare function computeDictionaryHash(data: Buffer): string;
+/**
+ * Build an `Available-Dictionary` request header value.
+ *
+ * @param {string} hash - Dictionary hash.
+ * @returns {string} Header value string.
+ */
+export declare function buildAvailableDictionaryHeader(hash: string): string;
+/**
+ * Append dictionary-based encodings to an `Accept-Encoding` header.
+ *
+ * @param {string} [existingEncoding] - Current `Accept-Encoding` value.
+ * @returns {string} Updated encoding string with `dcb` and `dcz` appended.
+ */
+export declare function buildDictionaryAcceptEncoding(existingEncoding?: string): string;
+/** Cache of compression dictionaries for shared dictionary transport. */
+export declare class DictionaryStore {
+    private readonly dictionaries;
+    private readonly maxEntries;
+    private readonly maxDictionarySize;
+    /**
+     * Create a new dictionary store.
+     *
+     * @param {DictionaryConfig} [config] - Cache size and dictionary size limits.
+     */
+    constructor(config?: DictionaryConfig);
+    /**
+     * Store a dictionary response.
+     *
+     * @param {string} url - URL the dictionary was fetched from.
+     * @param {Buffer} data - Raw dictionary bytes.
+     * @param {{ match?: string; id?: string }} [metadata] - Match pattern and ID from the response header.
+     * @param {number} [maxAge] - Maximum age in seconds.
+     */
+    store(url: string, data: Buffer, metadata?: {
+        match?: string;
+        id?: string;
+    }, maxAge?: number): void;
+    /**
+     * Find a dictionary whose match pattern covers the given request URL.
+     *
+     * @param {string} requestUrl - URL being requested.
+     * @returns {CompressionDictionary | undefined} Matching dictionary, or `undefined` if none found.
+     */
+    findForUrl(requestUrl: string): CompressionDictionary | undefined;
+    /**
+     * Retrieve a dictionary by its hash.
+     *
+     * @param {string} hash - Dictionary hash string.
+     * @returns {CompressionDictionary | undefined} Dictionary entry, or `undefined` if not found.
+     */
+    getByHash(hash: string): CompressionDictionary | undefined;
+    /** Number of dictionaries currently stored. */
+    get size(): number;
+    /** Remove all stored dictionaries. */
+    clear(): void;
+}
+//# sourceMappingURL=dictionary-transport.d.ts.map

package/dist/utils/dictionary-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictionary-transport.d.ts","sourceRoot":"","sources":["../../src/utils/dictionary-transport.ts"],"names":[],"mappings":"AAEA,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,GAAG,IAAI,CA2BP;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ/E;AAED,yEAAyE;AACzE,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4C;IACzE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C;;;;OAIG;gBACS,MAAM,CAAC,EAAE,gBAAgB;IAKrC;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IA2BnG;;;;;OAKG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAmBjE;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;IAI1D,+CAA+C;IAC/C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sCAAsC;IACtC,KAAK,IAAI,IAAI;CAGd"}

package/dist/utils/dictionary-transport.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+/**
+ * Parse a `Use-As-Dictionary` response header.
+ *
+ * @param {string} header - Raw header value.
+ * @returns {{ match?: string; matchDest?: string[]; id?: string } | null} Parsed fields, or `null` if the header is empty.
+ */
+export function parseUseAsDictionary(header) {
+    if (!header)
+        return null;
+    const result = {};
+    const matchRegex = /match="([^"]+)"/;
+    const matchMatch = header.match(matchRegex);
+    if (matchMatch) {
+        result.match = matchMatch[1];
+    }
+    const destRegex = /match-dest=\(([^)]*)\)/;
+    const destMatch = header.match(destRegex);
+    if (destMatch) {
+        result.matchDest = destMatch[1]
+            .split(/\s+/)
+            .map((s) => s.replace(/"/g, ""))
+            .filter(Boolean);
+    }
+    const idRegex = /id="([^"]+)"/;
+    const idMatch = header.match(idRegex);
+    if (idMatch) {
+        result.id = idMatch[1];
+    }
+    return result;
+}
+/**
+ * Compute the SHA-256 structured hash of dictionary data.
+ *
+ * @param {Buffer} data - Raw dictionary bytes.
+ * @returns {string} Hash string in structured field byte-sequence format.
+ */
+export function computeDictionaryHash(data) {
+    const hash = createHash("sha256").update(data).digest("base64");
+    return `:${hash}:`;
+}
+/**
+ * Build an `Available-Dictionary` request header value.
+ *
+ * @param {string} hash - Dictionary hash.
+ * @returns {string} Header value string.
+ */
+export function buildAvailableDictionaryHeader(hash) {
+    return hash;
+}
+/**
+ * Append dictionary-based encodings to an `Accept-Encoding` header.
+ *
+ * @param {string} [existingEncoding] - Current `Accept-Encoding` value.
+ * @returns {string} Updated encoding string with `dcb` and `dcz` appended.
+ */
+export function buildDictionaryAcceptEncoding(existingEncoding) {
+    const base = existingEncoding ?? "gzip, deflate, br";
+    const encodings = base.split(",").map((s) => s.trim());
+    if (!encodings.includes("dcb"))
+        encodings.push("dcb");
+    if (!encodings.includes("dcz"))
+        encodings.push("dcz");
+    return encodings.join(", ");
+}
+/** Cache of compression dictionaries for shared dictionary transport. */
+export class DictionaryStore {
+    dictionaries = new Map();
+    maxEntries;
+    maxDictionarySize;
+    /**
+     * Create a new dictionary store.
+     *
+     * @param {DictionaryConfig} [config] - Cache size and dictionary size limits.
+     */
+    constructor(config) {
+        this.maxEntries = config?.maxEntries ?? 50;
+        this.maxDictionarySize = config?.maxDictionarySize ?? 10 * 1024 * 1024;
+    }
+    /**
+     * Store a dictionary response.
+     *
+     * @param {string} url - URL the dictionary was fetched from.
+     * @param {Buffer} data - Raw dictionary bytes.
+     * @param {{ match?: string; id?: string }} [metadata] - Match pattern and ID from the response header.
+     * @param {number} [maxAge] - Maximum age in seconds.
+     */
+    store(url, data, metadata, maxAge) {
+        if (data.length > this.maxDictionarySize)
+            return;
+        if (this.dictionaries.size >= this.maxEntries) {
+            let oldest;
+            let oldestTime = Infinity;
+            for (const [key, entry] of this.dictionaries) {
+                if (entry.storedAt < oldestTime) {
+                    oldestTime = entry.storedAt;
+                    oldest = key;
+                }
+            }
+            if (oldest)
+                this.dictionaries.delete(oldest);
+        }
+        const hash = computeDictionaryHash(data);
+        const now = Date.now();
+        this.dictionaries.set(hash, {
+            hash,
+            url,
+            data,
+            storedAt: now,
+            matchPattern: metadata?.match,
+            expiresAt: maxAge ? now + maxAge * 1000 : undefined,
+        });
+    }
+    /**
+     * Find a dictionary whose match pattern covers the given request URL.
+     *
+     * @param {string} requestUrl - URL being requested.
+     * @returns {CompressionDictionary | undefined} Matching dictionary, or `undefined` if none found.
+     */
+    findForUrl(requestUrl) {
+        const now = Date.now();
+        for (const dict of this.dictionaries.values()) {
+            if (dict.expiresAt && dict.expiresAt < now) {
+                this.dictionaries.delete(dict.hash);
+                continue;
+            }
+            if (dict.matchPattern) {
+                if (matchesPattern(requestUrl, dict.matchPattern, dict.url)) {
+                    return dict;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Retrieve a dictionary by its hash.
+     *
+     * @param {string} hash - Dictionary hash string.
+     * @returns {CompressionDictionary | undefined} Dictionary entry, or `undefined` if not found.
+     */
+    getByHash(hash) {
+        return this.dictionaries.get(hash);
+    }
+    /** Number of dictionaries currently stored. */
+    get size() {
+        return this.dictionaries.size;
+    }
+    /** Remove all stored dictionaries. */
+    clear() {
+        this.dictionaries.clear();
+    }
+}
+function matchesPattern(requestUrl, pattern, dictionaryUrl) {
+    try {
+        const dictBase = new URL(dictionaryUrl);
+        const reqUrl = new URL(requestUrl);
+        if (reqUrl.origin !== dictBase.origin)
+            return false;
+        if (pattern === "*" || pattern === "/*")
+            return true;
+        if (pattern.endsWith("*")) {
+            const prefix = pattern.slice(0, -1);
+            return reqUrl.pathname.startsWith(prefix);
+        }
+        return reqUrl.pathname === pattern;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=dictionary-transport.js.map

package/dist/utils/dictionary-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictionary-transport.js","sourceRoot":"","sources":["../../src/utils/dictionary-transport.ts"],"names":[],"mappings":"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"}

package/dist/utils/encoding.d.ts

@@ -1,46 +1,28 @@
 import { Transform } from "node:stream";
-/**
- * `true` when the current Node.js runtime provides native Zstandard
- * decompression support (`zlib.zstdDecompress`). `false` on older Node.js
- * versions that lack the API.
- */
+/** Whether the current Node.js build supports zstd decompression. */
 export declare const supportsZstd: boolean;
 /**
- * Decompresses a response body buffer handling potentially multiple
- * Content-Encoding layers (e.g. `"gzip, br"`). Layers are applied in
- * reverse order per RFC 9110 §8.4. Throws if the number of layers
- * exceeds {@link MAX_CONTENT_ENCODING_LAYERS}.
+ * Decompress a response body according to `Content-Encoding` layers.
  *
- * @param {Buffer}            body            - Raw compressed body bytes.
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Promise<Buffer>} Decompressed body bytes.
+ * @param {Buffer} body - Compressed body bytes.
+ * @param {string | undefined} contentEncoding - Comma-separated encoding list.
+ * @returns {Promise<Buffer>} Decompressed buffer.
  */
 export declare function decompressBody(body: Buffer, contentEncoding: string | undefined): Promise<Buffer>;
 /**
- * Creates a Node.js `Transform` stream that decompresses data on-the-fly
- * using the algorithm(s) indicated by `contentEncoding`. Supports multiple
- * comma-separated encodings (e.g. `"gzip, br"`). Returns `null` when no
- * transform is needed. Throws if the number of encoding layers exceeds
- * {@link MAX_CONTENT_ENCODING_LAYERS}.
+ * Create a streaming decompressor for the given `Content-Encoding`.
  *
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Transform | null} Decompressor stream, or `null` if no decompression is required.
+ * @param {string | undefined} contentEncoding - Comma-separated encoding list.
+ * @returns {Transform | null} Transform stream, or `null` if no decompression is needed.
  */
 export declare function createDecompressStream(contentEncoding: string | undefined): Transform | null;
-/**
- * Returns the default `Accept-Encoding` header value supported by this
- * Node.js runtime. Includes `zstd` when Zstandard is available.
- *
- * @returns {string} E.g. `"gzip, deflate, br, zstd"` or `"gzip, deflate, br"`.
- */
+/** Return the default `Accept-Encoding` header value for this runtime. */
 export declare function defaultAcceptEncoding(): string;
 /**
- * Filters `zstd` from a caller-supplied `Accept-Encoding` value when the
- * current runtime does not support Zstandard decompression. Otherwise returns
- * the value unchanged.
+ * Strip unsupported encodings (e.g. `zstd`) from an `Accept-Encoding` value.
  *
- * @param {string} value - Caller-supplied `Accept-Encoding` header value.
- * @returns {string} Sanitized encoding list compatible with the runtime.
+ * @param {string} value - Original `Accept-Encoding` header value.
+ * @returns {string} Sanitized header value.
  */
 export declare function sanitizeAcceptEncoding(value: string): string;
 //# sourceMappingURL=encoding.d.ts.map

package/dist/utils/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAiB,MAAM,aAAa,CAAC;AASvD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,OAAsC,CAAC;AAoDlE;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvG;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CAwC5F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO5D"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AASxC,qEAAqE;AACrE,eAAO,MAAM,YAAY,EAAE,OAAsC,CAAC;AAwClE;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAWvG;AA2BD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CA0C5F;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO5D"}

package/dist/utils/encoding.js

@@ -6,22 +6,9 @@ const inflateAsync = promisify(zlib.inflate);
 const brotliDecompressAsync = promisify(zlib.brotliDecompress);
 const _zstdFn = zlib["zstdDecompress"];
 const zstdDecompressAsync = typeof _zstdFn === "function" ? promisify(_zstdFn) : null;
-/**
- * `true` when the current Node.js runtime provides native Zstandard
- * decompression support (`zlib.zstdDecompress`). `false` on older Node.js
- * versions that lack the API.
- */
+/** Whether the current Node.js build supports zstd decompression. */
 export const supportsZstd = zstdDecompressAsync !== null;
-/**
- * Maximum number of Content-Encoding layers permitted. Prevents
- * decompression bomb attacks that nest many encoding layers to cause
- * exponential memory/CPU usage. Matches undici's limit.
- */
 const MAX_CONTENT_ENCODING_LAYERS = 5;
-/**
- * Parses a Content-Encoding header value into individual encoding tokens,
- * filters out `identity`, and validates the layer count.
- */
 function parseEncodings(contentEncoding) {
     const encodings = contentEncoding
         .split(",")
@@ -32,9 +19,6 @@ function parseEncodings(contentEncoding) {
     }
     return encodings;
 }
-/**
- * Decompresses a single buffer using the specified encoding algorithm.
- */
 async function decompressSingle(body, encoding) {
     switch (encoding) {
         case "gzip":
@@ -54,14 +38,11 @@ async function decompressSingle(body, encoding) {
     }
 }
 /**
- * Decompresses a response body buffer handling potentially multiple
- * Content-Encoding layers (e.g. `"gzip, br"`). Layers are applied in
- * reverse order per RFC 9110 §8.4. Throws if the number of layers
- * exceeds {@link MAX_CONTENT_ENCODING_LAYERS}.
+ * Decompress a response body according to `Content-Encoding` layers.
  *
- * @param {Buffer}            body            - Raw compressed body bytes.
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Promise<Buffer>} Decompressed body bytes.
+ * @param {Buffer} body - Compressed body bytes.
+ * @param {string | undefined} contentEncoding - Comma-separated encoding list.
+ * @returns {Promise<Buffer>} Decompressed buffer.
  */
 export async function decompressBody(body, contentEncoding) {
     if (!contentEncoding || body.length === 0)
@@ -75,9 +56,6 @@ export async function decompressBody(body, contentEncoding) {
     }
     return result;
 }
-/**
- * Creates a decompressor Transform for a single encoding algorithm.
- */
 function createSingleDecompressStream(encoding) {
     switch (encoding) {
         case "gzip":
@@ -99,14 +77,10 @@ function createSingleDecompressStream(encoding) {
     }
 }
 /**
- * Creates a Node.js `Transform` stream that decompresses data on-the-fly
- * using the algorithm(s) indicated by `contentEncoding`. Supports multiple
- * comma-separated encodings (e.g. `"gzip, br"`). Returns `null` when no
- * transform is needed. Throws if the number of encoding layers exceeds
- * {@link MAX_CONTENT_ENCODING_LAYERS}.
+ * Create a streaming decompressor for the given `Content-Encoding`.
  *
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Transform | null} Decompressor stream, or `null` if no decompression is required.
+ * @param {string | undefined} contentEncoding - Comma-separated encoding list.
+ * @returns {Transform | null} Transform stream, or `null` if no decompression is needed.
  */
 export function createDecompressStream(contentEncoding) {
     if (!contentEncoding)
@@ -138,29 +112,24 @@ export function createDecompressStream(contentEncoding) {
         },
         flush(callback) {
             first.end();
-            last.once("end", () => callback());
+            last.once("end", () => {
+                callback();
+            });
         },
     });
     last.on("data", (chunk) => compound.push(chunk));
     last.on("error", (err) => compound.destroy(err));
     return compound;
 }
-/**
- * Returns the default `Accept-Encoding` header value supported by this
- * Node.js runtime. Includes `zstd` when Zstandard is available.
- *
- * @returns {string} E.g. `"gzip, deflate, br, zstd"` or `"gzip, deflate, br"`.
- */
+/** Return the default `Accept-Encoding` header value for this runtime. */
 export function defaultAcceptEncoding() {
     return supportsZstd ? "gzip, deflate, br, zstd" : "gzip, deflate, br";
 }
 /**
- * Filters `zstd` from a caller-supplied `Accept-Encoding` value when the
- * current runtime does not support Zstandard decompression. Otherwise returns
- * the value unchanged.
+ * Strip unsupported encodings (e.g. `zstd`) from an `Accept-Encoding` value.
  *
- * @param {string} value - Caller-supplied `Accept-Encoding` header value.
- * @returns {string} Sanitized encoding list compatible with the runtime.
+ * @param {string} value - Original `Accept-Encoding` header value.
+ * @returns {string} Sanitized header value.
  */
 export function sanitizeAcceptEncoding(value) {
     if (supportsZstd)

package/dist/utils/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"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"}

package/dist/utils/happy-eyeballs.d.ts

@@ -1,29 +1,39 @@
 import * as net from "node:net";
 import type { DoHResolver } from "../dns/doh-resolver.js";
+/** Options for the Happy Eyeballs (RFC 8305) connection algorithm. */
 export interface HappyEyeballsOptions {
+    /** Destination hostname or IP address. */
     host: string;
+    /** Destination port. */
     port: number;
+    /** Restrict connections to IPv4 (`4`) or IPv6 (`6`). */
     family?: 4 | 6;
+    /** Overall connection timeout in milliseconds. */
     timeout?: number;
+    /** Abort signal to cancel the connection attempt. */
     signal?: AbortSignal;
-    /** Optional DoH resolver for encrypted DNS resolution (RFC 8484). */
+    /** DNS-over-HTTPS resolver to use instead of system DNS. */
     dohResolver?: DoHResolver;
 }
+/** Outcome of a Happy Eyeballs connection attempt. */
 export interface HappyEyeballsResult {
+    /** Connected TCP socket. */
     socket: net.Socket;
+    /** Resolved IP address that was connected to. */
     address: string;
+    /** IP address family of the connected socket. */
     family: number;
+    /** Time spent on DNS resolution in milliseconds. */
     dnsTimeMs: number;
 }
 /**
- * Establish a TCP connection using the Happy Eyeballs algorithm (RFC 8305).
+ * Connect to a host using the Happy Eyeballs algorithm (RFC 8305).
  *
- * 1. Resolves ALL addresses for the hostname (both A and AAAA).
- * 2. Interleaves IPv6 and IPv4 addresses (IPv6 first).
- * 3. Starts connecting to the first address.
- * 4. After 250 ms (or immediately on a synchronous error like ENETUNREACH),
- *    starts the next address in parallel.
- * 5. Returns the first socket that connects; destroys all others.
+ * Races IPv6 and IPv4 connection attempts with a staggered delay
+ * for fast fallback.
+ *
+ * @param {HappyEyeballsOptions} options - Connection options.
+ * @returns {Promise<HappyEyeballsResult>} Connected socket and connection metadata.
  */
 export declare function happyEyeballsConnect(options: HappyEyeballsOptions): Promise<HappyEyeballsResult>;
 //# sourceMappingURL=happy-eyeballs.d.ts.map

package/dist/utils/happy-eyeballs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"happy-eyeballs.d.ts","sourceRoot":"","sources":["../../src/utils/happy-eyeballs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAY1D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6BtG"}
+{"version":3,"file":"happy-eyeballs.d.ts","sourceRoot":"","sources":["../../src/utils/happy-eyeballs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAW1D,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6BtG"}