nlcurl 0.6.0 → 0.8.0

package/dist/utils/logger.js

@@ -5,24 +5,17 @@ const LEVEL_ORDER = {
     error: 3,
     silent: 4,
 };
-/**
- * Default {@link Logger} implementation that writes to `process.stderr`.
- * Messages are prefixed with `[nlcurl:<level>]` and only emitted when the
- * message severity meets or exceeds the configured `level`.
- *
- * Supports scoped child loggers via {@link ConsoleLogger.child}, which
- * prepend a component tag to every message for easy filtering.
- */
+/** Logger implementation that writes to `stderr` with level filtering. */
 export class ConsoleLogger {
     level;
     prefix;
     bindings;
     /**
-     * Creates a new ConsoleLogger.
+     * Create a console logger.
      *
-     * @param {LogLevel}    [level='warn'] - Minimum severity level to emit.
-     * @param {string}      [prefix='']    - Component prefix prepended to every message.
-     * @param {LogBindings} [bindings={}]  - Key-value metadata appended to every message.
+     * @param {LogLevel} level - Minimum severity to output.
+     * @param {string} prefix - Namespace prefix for log lines.
+     * @param {LogBindings} bindings - Structured context fields.
      */
     constructor(level = "warn", prefix = "", bindings = {}) {
         this.level = LEVEL_ORDER[level];
@@ -30,17 +23,10 @@ export class ConsoleLogger {
         this.bindings = bindings;
     }
     /**
-     * Creates a child logger that inherits this logger's level and prepends
-     * an additional component tag to every message. Bindings from the parent
-     * are merged with the child's bindings (child values win on conflict).
-     *
-     * @param {LogBindings} bindings - Additional metadata for the child scope.
-     * @returns {ConsoleLogger} A new scoped logger instance.
+     * Create a child logger with additional bindings.
      *
-     * @example
-     * const logger = new ConsoleLogger('debug');
-     * const child = logger.child({ component: 'h2' });
-     * child.debug('stream opened', { streamId: 1 });
+     * @param {LogBindings} bindings - Extra structured context fields.
+     * @returns {ConsoleLogger} New child `ConsoleLogger`.
      */
     child(bindings) {
         const component = typeof bindings["component"] === "string" ? bindings["component"] : "";
@@ -49,57 +35,32 @@ export class ConsoleLogger {
         return new ConsoleLogger(this.resolveLevel(), childPrefix, merged);
     }
     /**
-     * Updates the minimum severity level at runtime without creating a new
-     * logger instance.
+     * Change the minimum log level at runtime.
      *
-     * @param {LogLevel} level - New minimum severity level.
+     * @param {LogLevel} level - New severity threshold.
      */
     setLevel(level) {
         this.level = LEVEL_ORDER[level];
     }
-    /**
-     * Emits a debug-level message to `stderr` -- only written when the
-     * configured minimum level is `'debug'`.
-     *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
-     */
+    /** Log a debug-level message. */
     debug(message, ...args) {
         if (this.level <= LEVEL_ORDER.debug) {
             this.write("debug", message, args);
         }
     }
-    /**
-     * Emits an info-level message to `stderr` -- only written when the
-     * configured minimum level is `'debug'` or `'info'`.
-     *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
-     */
+    /** Log an info-level message. */
     info(message, ...args) {
         if (this.level <= LEVEL_ORDER.info) {
             this.write("info", message, args);
         }
     }
-    /**
-     * Emits a warn-level message to `stderr` -- only written when the
-     * configured minimum level is `'debug'`, `'info'`, or `'warn'`.
-     *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
-     */
+    /** Log a warning-level message. */
     warn(message, ...args) {
         if (this.level <= LEVEL_ORDER.warn) {
             this.write("warn", message, args);
         }
     }
-    /**
-     * Emits an error-level message to `stderr` -- only written when the
-     * configured minimum level is not `'silent'`.
-     *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
-     */
+    /** Log an error-level message. */
     error(message, ...args) {
         if (this.level <= LEVEL_ORDER.error) {
             this.write("error", message, args);
@@ -122,30 +83,97 @@ export class ConsoleLogger {
         return "warn";
     }
 }
-/**
- * A no-op {@link Logger} that discards all messages. Assign this via
- * {@link setDefaultLogger} to silence the library entirely.
- */
+/** Singleton no-op logger that discards all messages. */
 export const SILENT_LOGGER = {
     debug() { },
     info() { },
     warn() { },
     error() { },
 };
+/** Logger implementation that writes structured JSON to `stderr` with level filtering. */
+export class JsonLogger {
+    level;
+    service;
+    bindings;
+    /**
+     * Create a JSON logger.
+     *
+     * @param {LogLevel} level - Minimum severity to output.
+     * @param {string} service - Service name included in every log entry.
+     * @param {LogBindings} bindings - Structured context fields.
+     */
+    constructor(level = "warn", service = "nlcurl", bindings = {}) {
+        this.level = LEVEL_ORDER[level];
+        this.service = service;
+        this.bindings = bindings;
+    }
+    /**
+     * Create a child JSON logger with additional bindings.
+     *
+     * @param {LogBindings} bindings - Extra structured context fields.
+     * @returns {JsonLogger} New child `JsonLogger`.
+     */
+    child(bindings) {
+        const merged = { ...this.bindings, ...bindings };
+        return new JsonLogger(this.resolveLevel(), this.service, merged);
+    }
+    /**
+     * Change the minimum log level at runtime.
+     *
+     * @param {LogLevel} level - New severity threshold.
+     */
+    setLevel(level) {
+        this.level = LEVEL_ORDER[level];
+    }
+    debug(message, ...args) {
+        if (this.level <= LEVEL_ORDER.debug)
+            this.emit("debug", message, args);
+    }
+    info(message, ...args) {
+        if (this.level <= LEVEL_ORDER.info)
+            this.emit("info", message, args);
+    }
+    warn(message, ...args) {
+        if (this.level <= LEVEL_ORDER.warn)
+            this.emit("warn", message, args);
+    }
+    error(message, ...args) {
+        if (this.level <= LEVEL_ORDER.error)
+            this.emit("error", message, args);
+    }
+    emit(level, message, args) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            service: this.service,
+        };
+        for (const [k, v] of Object.entries(this.bindings)) {
+            entry[k] = v;
+        }
+        if (args.length > 0) {
+            entry["metadata"] = args;
+        }
+        process.stderr.write(JSON.stringify(entry) + "\n");
+    }
+    resolveLevel() {
+        for (const [name, order] of Object.entries(LEVEL_ORDER)) {
+            if (order === this.level)
+                return name;
+        }
+        return "warn";
+    }
+}
 let _default = new ConsoleLogger("warn");
 /**
- * Replaces the process-wide default logger used by all NLcURL internals.
+ * Set the process-wide default logger.
  *
- * @param {Logger} logger - New logger instance to install.
+ * @param {Logger} logger - Logger instance to use as the default.
  */
 export function setDefaultLogger(logger) {
     _default = logger;
 }
-/**
- * Returns the currently active process-wide logger.
- *
- * @returns {Logger} The active logger instance.
- */
+/** Return the current process-wide default logger. */
 export function getDefaultLogger() {
     return _default;
 }

package/dist/utils/logger.js.map

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

package/dist/utils/tcp-fast-open.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Check whether TCP Fast Open is supported on the current platform.
+ *
+ * @returns {boolean} `true` on Linux and macOS.
+ */
+export declare function isTFOSupported(): boolean;
+/** Configuration for TCP Fast Open (TFO). */
+export interface TFOOptions {
+    /** Enable TCP Fast Open for the connection. */
+    enabled?: boolean;
+    /** Data to send during the TCP handshake. */
+    connectData?: Buffer;
+}
+/**
+ * Build socket creation options for TCP Fast Open.
+ *
+ * @param {TFOOptions} [tfo] - TFO configuration.
+ * @returns {Record<string, unknown>} Options object to merge into socket creation.
+ */
+export declare function buildTFOSocketOptions(tfo?: TFOOptions): Record<string, unknown>;
+/**
+ * Return the current TFO support status and platform name.
+ *
+ * @returns {{ supported: boolean; platform: string }} Object with `supported` flag and `platform` string.
+ */
+export declare function getTFOStatus(): {
+    supported: boolean;
+    platform: string;
+};
+//# sourceMappingURL=tcp-fast-open.d.ts.map

package/dist/utils/tcp-fast-open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcp-fast-open.d.ts","sourceRoot":"","sources":["../../src/utils/tcp-fast-open.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAGxC;AAED,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ/E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKvE"}

package/dist/utils/tcp-fast-open.js

@@ -0,0 +1,36 @@
+import { platform } from "node:os";
+/**
+ * Check whether TCP Fast Open is supported on the current platform.
+ *
+ * @returns {boolean} `true` on Linux and macOS.
+ */
+export function isTFOSupported() {
+    const os = platform();
+    return os === "linux" || os === "darwin";
+}
+/**
+ * Build socket creation options for TCP Fast Open.
+ *
+ * @param {TFOOptions} [tfo] - TFO configuration.
+ * @returns {Record<string, unknown>} Options object to merge into socket creation.
+ */
+export function buildTFOSocketOptions(tfo) {
+    if (!tfo?.enabled || !isTFOSupported()) {
+        return {};
+    }
+    return {
+        fastOpen: true,
+    };
+}
+/**
+ * Return the current TFO support status and platform name.
+ *
+ * @returns {{ supported: boolean; platform: string }} Object with `supported` flag and `platform` string.
+ */
+export function getTFOStatus() {
+    return {
+        supported: isTFOSupported(),
+        platform: platform(),
+    };
+}
+//# sourceMappingURL=tcp-fast-open.js.map

package/dist/utils/tcp-fast-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tcp-fast-open.js","sourceRoot":"","sources":["../../src/utils/tcp-fast-open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC;IACtB,OAAO,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,QAAQ,CAAC;AAC3C,CAAC;AAUD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAgB;IACpD,IAAI,CAAC,GAAG,EAAE,OAAO,IAAI,CAAC,cAAc,EAAE,EAAE,CAAC;QACvC,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,IAAI;KACf,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO;QACL,SAAS,EAAE,cAAc,EAAE;QAC3B,QAAQ,EAAE,QAAQ,EAAE;KACrB,CAAC;AACJ,CAAC"}

package/dist/utils/url.d.ts

@@ -1,62 +1,55 @@
 /**
- * Resolves `relative` against `base`. When `base` is `undefined` or the
- * resolution fails, `relative` is returned as-is.
+ * Resolve a relative URL against an optional base.
  *
- * @param {string | undefined} base     - Base URL string.
- * @param {string}             relative - Relative or absolute URL to resolve.
- * @returns {string} The resolved absolute URL, or `relative` if resolution fails.
+ * @param {string | undefined} base - Base URL string.
+ * @param {string} relative - Relative or absolute URL string.
+ * @returns {string} Resolved absolute URL string.
  */
 export declare function resolveURL(base: string | undefined, relative: string): string;
 /**
- * Appends `params` as query-string parameters to `url`. Existing parameters in
- * the URL are preserved. `undefined` and `null` values are omitted.
+ * Append query parameters to a URL string.
  *
- * @param {string}                                        url    - Base URL.
- * @param {Record<string, string | number | boolean>}     [params] - Key-value pairs to append.
- * @returns {string} URL with appended query parameters.
+ * @param {string} url - Base URL string.
+ * @param {Record<string, string | number | boolean>} [params] - Key-value pairs to append.
+ * @returns {string} URL string with appended query parameters.
  */
 export declare function appendParams(url: string, params?: Record<string, string | number | boolean>): string;
 /**
- * Parses `raw` into a `URL` object.
+ * Parse a URL string into a `URL` object.
  *
- * @param {string} raw - Absolute URL string to parse.
- * @returns {URL} Parsed URL.
- * @throws {TypeError} If `raw` is not a valid absolute URL.
+ * @param {string} raw - Raw URL string.
+ * @returns {URL} Parsed `URL` instance.
  */
 export declare function parseURL(raw: string): URL;
 /**
- * Returns the origin of `url` in `scheme://hostname:port` form. The port is
- * always included explicitly, defaulting to `443` for `https:` and `80` for
- * `http:`.
+ * Extract the origin (scheme + hostname + port) from a URL.
  *
  * @param {string} url - Absolute URL string.
  * @returns {string} Origin string (e.g. `"https://example.com:443"`).
  */
 export declare function originOf(url: string): string;
 /**
- * Extracts the hostname from `url` for use as the TLS SNI server-name value.
+ * Extract the hostname for TLS SNI from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Hostname without port (e.g. `"example.com"`).
+ * @returns {string} Hostname string.
  */
 export declare function sniHost(url: string): string;
 /**
- * Extracts the host and port from `url`. The port defaults to `443` for
- * `https:` and `80` for `http:` when not explicitly specified in the URL.
+ * Extract the hostname and port from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {{ host: string; port: number }} Hostname and numeric port.
+ * @returns {{ host: string; port: number }} Object with `host` and numeric `port`.
  */
 export declare function hostPort(url: string): {
     host: string;
     port: number;
 };
 /**
- * Returns the path and query string of `url` suitable for use as the
- * request-target in an HTTP/1.1 request line.
+ * Extract the request path (pathname + search) from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Path + query string (e.g. `"/search?q=hello"`).
+ * @returns {string} Path string suitable for an HTTP request line.
  */
 export declare function requestPath(url: string): string;
 //# sourceMappingURL=url.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO7E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CASpG;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOpE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO7E;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,GAAG,MAAM,CASpG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAOpE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C"}

package/dist/utils/url.js

@@ -1,10 +1,9 @@
 /**
- * Resolves `relative` against `base`. When `base` is `undefined` or the
- * resolution fails, `relative` is returned as-is.
+ * Resolve a relative URL against an optional base.
  *
- * @param {string | undefined} base     - Base URL string.
- * @param {string}             relative - Relative or absolute URL to resolve.
- * @returns {string} The resolved absolute URL, or `relative` if resolution fails.
+ * @param {string | undefined} base - Base URL string.
+ * @param {string} relative - Relative or absolute URL string.
+ * @returns {string} Resolved absolute URL string.
  */
 export function resolveURL(base, relative) {
     if (!base)
@@ -17,12 +16,11 @@ export function resolveURL(base, relative) {
     }
 }
 /**
- * Appends `params` as query-string parameters to `url`. Existing parameters in
- * the URL are preserved. `undefined` and `null` values are omitted.
+ * Append query parameters to a URL string.
  *
- * @param {string}                                        url    - Base URL.
- * @param {Record<string, string | number | boolean>}     [params] - Key-value pairs to append.
- * @returns {string} URL with appended query parameters.
+ * @param {string} url - Base URL string.
+ * @param {Record<string, string | number | boolean>} [params] - Key-value pairs to append.
+ * @returns {string} URL string with appended query parameters.
  */
 export function appendParams(url, params) {
     if (!params || Object.keys(params).length === 0)
@@ -36,19 +34,16 @@ export function appendParams(url, params) {
     return parsed.toString();
 }
 /**
- * Parses `raw` into a `URL` object.
+ * Parse a URL string into a `URL` object.
  *
- * @param {string} raw - Absolute URL string to parse.
- * @returns {URL} Parsed URL.
- * @throws {TypeError} If `raw` is not a valid absolute URL.
+ * @param {string} raw - Raw URL string.
+ * @returns {URL} Parsed `URL` instance.
  */
 export function parseURL(raw) {
     return new URL(raw);
 }
 /**
- * Returns the origin of `url` in `scheme://hostname:port` form. The port is
- * always included explicitly, defaulting to `443` for `https:` and `80` for
- * `http:`.
+ * Extract the origin (scheme + hostname + port) from a URL.
  *
  * @param {string} url - Absolute URL string.
  * @returns {string} Origin string (e.g. `"https://example.com:443"`).
@@ -59,20 +54,19 @@ export function originOf(url) {
     return `${u.protocol}//${u.hostname}:${port}`;
 }
 /**
- * Extracts the hostname from `url` for use as the TLS SNI server-name value.
+ * Extract the hostname for TLS SNI from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Hostname without port (e.g. `"example.com"`).
+ * @returns {string} Hostname string.
  */
 export function sniHost(url) {
     return new URL(url).hostname;
 }
 /**
- * Extracts the host and port from `url`. The port defaults to `443` for
- * `https:` and `80` for `http:` when not explicitly specified in the URL.
+ * Extract the hostname and port from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {{ host: string; port: number }} Hostname and numeric port.
+ * @returns {{ host: string; port: number }} Object with `host` and numeric `port`.
  */
 export function hostPort(url) {
     const u = new URL(url);
@@ -83,11 +77,10 @@ export function hostPort(url) {
     };
 }
 /**
- * Returns the path and query string of `url` suitable for use as the
- * request-target in an HTTP/1.1 request line.
+ * Extract the request path (pathname + search) from a URL.
  *
  * @param {string} url - Absolute URL string.
- * @returns {string} Path + query string (e.g. `"/search?q=hello"`).
+ * @returns {string} Path string suitable for an HTTP request line.
  */
 export function requestPath(url) {
     const u = new URL(url);

package/dist/utils/url.js.map

@@ -1 +1 @@
-{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,QAAgB;IACnE,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAkD;IAC1F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAE5D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,QAAQ;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;KAClD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"url.js","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,QAAgB;IACnE,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,MAAkD;IAC1F,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAE5D,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QACpD,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW;IACjC,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,MAAM,WAAW,GAAG,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,OAAO;QACL,IAAI,EAAE,CAAC,CAAC,QAAQ;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW;KAClD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC"}

package/dist/ws/client.d.ts

@@ -1,101 +1,84 @@
 import { EventEmitter } from "node:events";
-/**
- * Options for creating a {@link WebSocketClient} connection.
- *
- * @typedef  {Object}    WebSocketOptions
- * @property {string}    [impersonate]  - Browser profile name for fingerprint impersonation.
- * @property {boolean}   [stealth]      - Use the stealth TLS engine for byte-level fingerprinting.
- * @property {Record<string, string>} [headers] - Additional HTTP upgrade request headers.
- * @property {string[]}  [protocols]    - Sub-protocol names to negotiate.
- * @property {boolean}   [insecure]     - Skip TLS certificate validation for `wss:` connections.
- * @property {number}    [timeout]      - Connection timeout in milliseconds.
- */
+/** Configuration options for a WebSocket connection. */
 export interface WebSocketOptions {
+    /** Browser profile name to impersonate for TLS fingerprinting. */
     impersonate?: string;
+    /** Use the stealth TLS engine for fingerprint impersonation. */
     stealth?: boolean;
+    /** Additional HTTP headers to include in the upgrade request. */
     headers?: Record<string, string>;
+    /** Subprotocols to offer during the upgrade handshake. */
     protocols?: string[];
+    /** Skip TLS certificate verification. */
     insecure?: boolean;
+    /** Connection timeout in milliseconds. */
     timeout?: number;
+    /** Enable per-message deflate compression. */
+    compress?: boolean;
 }
-/**
- * WebSocket connection state.
- *
- * @typedef {'connecting' | 'open' | 'closing' | 'closed'} WebSocketState
- */
+/** Current lifecycle state of the WebSocket connection. */
 export type WebSocketState = "connecting" | "open" | "closing" | "closed";
-/**
- * Typed event map for {@link WebSocketClient}.
- *
- * @typedef  {Object}                           WebSocketEvents
- * @property {[]}                               open    - Emitted when the connection is established.
- * @property {[data: string | Buffer, isBinary: boolean]} message - Emitted for each incoming message.
- * @property {[code: number, reason: string]}   close   - Emitted when the connection closes.
- * @property {[error: Error]}                   error   - Emitted on connection or protocol errors.
- * @property {[data: Buffer]}                   ping    - Emitted when a PING frame is received.
- * @property {[data: Buffer]}                   pong    - Emitted when a PONG frame is received.
- */
+/** Event map for {@link WebSocketClient} emitter. */
 export interface WebSocketEvents {
+    /** Fired when the connection has been established. */
     open: [];
+    /** Fired when a text or binary message is received. */
     message: [data: string | Buffer, isBinary: boolean];
+    /** Fired when the connection has been cleanly closed. */
     close: [code: number, reason: string];
+    /** Fired on transport or protocol errors. */
     error: [error: Error];
+    /** Fired when a ping frame is received. */
     ping: [data: Buffer];
+    /** Fired when a pong frame is received. */
     pong: [data: Buffer];
 }
 /**
- * WebSocket client with optional browser fingerprint impersonation. Emits
- * typed lifecycle events (`open`, `message`, `close`, `error`, `ping`, `pong`).
- * The connection is initiated asynchronously in the constructor; listen for
- * the `'open'` event before sending frames.
- *
- * @example
- * const ws = new WebSocketClient('wss://echo.example.com', { impersonate: 'chrome136' });
- * ws.on('open', () => ws.sendText('hello'));
- * ws.on('message', (data) => console.log(data));
+ * RFC 6455 WebSocket client with optional TLS fingerprinting
+ * and per-message deflate compression.
  */
 export declare class WebSocketClient extends EventEmitter {
+    /** Current connection lifecycle state. */
     state: WebSocketState;
+    /** Negotiated subprotocol, or empty string if none. */
     protocol: string;
+    /** Original WebSocket URL. */
     readonly url: string;
     private socket;
     private parser;
     private fragments;
     private fragmentOpcode;
+    private deflate;
     /**
-     * Creates a new WebSocketClient and begins connecting to `url`.
+     * Create a new WebSocket connection.
      *
-     * @param {string}           url       - WebSocket URL (`ws:` or `wss:`).
-     * @param {WebSocketOptions} [options={}] - Connection and impersonation options.
+     * @param {string} url - `ws://` or `wss://` URL to connect to.
+     * @param {WebSocketOptions} [options] - Connection and TLS options.
      */
     constructor(url: string, options?: WebSocketOptions);
     /**
-     * Sends a UTF-8 text message.
+     * Send a UTF-8 text message.
      *
-     * @param {string} data - Text to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {string} data - Text payload to send.
      */
     sendText(data: string): void;
     /**
-     * Sends a binary message.
+     * Send a binary message.
      *
-     * @param {Buffer} data - Binary data to send.
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} data - Binary payload to send.
      */
     sendBinary(data: Buffer): void;
     /**
-     * Sends a PING control frame.
+     * Send a WebSocket ping frame.
      *
-     * @param {Buffer} [data=Buffer.alloc(0)] - Optional ping payload (up to 125 bytes).
-     * @throws {NLcURLError} If the WebSocket is not in the `'open'` state.
+     * @param {Buffer} [data] - Optional payload (up to 125 bytes).
      */
     ping(data?: Buffer): void;
     /**
-     * Initiates a graceful close handshake by sending a CLOSE frame with the
-     * given status code and reason. Does nothing if the connection is not open.
+     * Initiate a graceful close handshake.
      *
-     * @param {number} [code=1000]  - WebSocket close status code.
-     * @param {string} [reason=''] - Human-readable close reason (UTF-8, max 123 bytes).
+     * @param {number} [code] - Close status code (default `1000`).
+     * @param {string} [reason] - Human-readable close reason.
      */
     close(code?: number, reason?: string): void;
     private assertOpen;