nlcurl 0.6.0 → 0.8.0

package/dist/utils/encoding.js

@@ -1,30 +1,25 @@
 import * as zlib from "node:zlib";
 import { promisify } from "node:util";
+import { Transform } from "node:stream";
 const gunzipAsync = promisify(zlib.gunzip);
 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;
-/**
- * Decompresses a response body buffer using the algorithm indicated by
- * `contentEncoding`. Supports `gzip`, `x-gzip`, `deflate`, `br` (Brotli),
- * `zstd` (when available), and `identity`. Unrecognized encodings are
- * returned as-is.
- *
- * @param {Buffer}            body            - Raw compressed body bytes.
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Promise<Buffer>} Decompressed body bytes.
- */
-export async function decompressBody(body, contentEncoding) {
-    if (!contentEncoding || body.length === 0)
-        return body;
-    const encoding = contentEncoding.trim().toLowerCase();
+const MAX_CONTENT_ENCODING_LAYERS = 5;
+function parseEncodings(contentEncoding) {
+    const encodings = contentEncoding
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0 && s !== "identity");
+    if (encodings.length > MAX_CONTENT_ENCODING_LAYERS) {
+        throw new Error(`Content-Encoding exceeds maximum layer count (${encodings.length} > ${MAX_CONTENT_ENCODING_LAYERS})`);
+    }
+    return encodings;
+}
+async function decompressSingle(body, encoding) {
     switch (encoding) {
         case "gzip":
         case "x-gzip":
@@ -38,24 +33,30 @@ export async function decompressBody(body, contentEncoding) {
                 return zstdDecompressAsync(body);
             }
             return body;
-        case "identity":
-            return body;
         default:
             return body;
     }
 }
 /**
- * Creates a Node.js `Transform` stream that decompresses data on-the-fly
- * using the algorithm indicated by `contentEncoding`. Returns `null` when
- * no transform is needed (unknown or `identity` encoding).
+ * Decompress a response body according to `Content-Encoding` layers.
  *
- * @param {string | undefined} contentEncoding - Value of the `Content-Encoding` header.
- * @returns {Transform | null} Decompressor stream, or `null` if no decompression is required.
+ * @param {Buffer} body - Compressed body bytes.
+ * @param {string | undefined} contentEncoding - Comma-separated encoding list.
+ * @returns {Promise<Buffer>} Decompressed buffer.
  */
-export function createDecompressStream(contentEncoding) {
-    if (!contentEncoding)
-        return null;
-    const encoding = contentEncoding.trim().toLowerCase();
+export async function decompressBody(body, contentEncoding) {
+    if (!contentEncoding || body.length === 0)
+        return body;
+    const encodings = parseEncodings(contentEncoding);
+    if (encodings.length === 0)
+        return body;
+    let result = body;
+    for (let i = encodings.length - 1; i >= 0; i--) {
+        result = await decompressSingle(result, encodings[i]);
+    }
+    return result;
+}
+function createSingleDecompressStream(encoding) {
     switch (encoding) {
         case "gzip":
         case "x-gzip":
@@ -71,28 +72,64 @@ export function createDecompressStream(contentEncoding) {
             }
             return null;
         }
-        case "identity":
-            return null;
         default:
             return null;
     }
 }
 /**
- * Returns the default `Accept-Encoding` header value supported by this
- * Node.js runtime. Includes `zstd` when Zstandard is available.
+ * Create a streaming decompressor for the given `Content-Encoding`.
  *
- * @returns {string} E.g. `"gzip, deflate, br, zstd"` or `"gzip, deflate, br"`.
+ * @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)
+        return null;
+    const encodings = parseEncodings(contentEncoding);
+    if (encodings.length === 0)
+        return null;
+    if (encodings.length === 1) {
+        return createSingleDecompressStream(encodings[0]);
+    }
+    const decompressors = [];
+    for (let i = encodings.length - 1; i >= 0; i--) {
+        const d = createSingleDecompressStream(encodings[i]);
+        if (d)
+            decompressors.push(d);
+    }
+    if (decompressors.length === 0)
+        return null;
+    if (decompressors.length === 1)
+        return decompressors[0];
+    for (let i = 0; i < decompressors.length - 1; i++) {
+        decompressors[i].pipe(decompressors[i + 1]);
+    }
+    const first = decompressors[0];
+    const last = decompressors[decompressors.length - 1];
+    const compound = new Transform({
+        transform(chunk, _encoding, callback) {
+            first.write(chunk, _encoding, callback);
+        },
+        flush(callback) {
+            first.end();
+            last.once("end", () => {
+                callback();
+            });
+        },
+    });
+    last.on("data", (chunk) => compound.push(chunk));
+    last.on("error", (err) => compound.destroy(err));
+    return compound;
+}
+/** 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,26 +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;
+    /** 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;AAWhC,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;CACtB;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,CAuBtG"}
+{"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"}

package/dist/utils/happy-eyeballs.js

@@ -1,26 +1,32 @@
 import * as net from "node:net";
 import { lookup } from "node:dns/promises";
-/** Connection Attempt Delay per RFC 8305 §5 — 250 ms. */
+import { parseARecord, parseAAAARecord } from "../dns/codec.js";
+import { RTYPE } from "../dns/types.js";
 const ATTEMPT_DELAY_MS = 250;
 /**
- * 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 async function happyEyeballsConnect(options) {
-    const { host, port, family, timeout, signal } = options;
+    const { host, port, family, timeout, signal, dohResolver } = options;
     const ipVersion = net.isIP(host);
     if (ipVersion) {
         const socket = await raceTcpConnections([{ address: host, family: ipVersion }], port, timeout, signal);
         return { socket: socket.socket, address: host, family: ipVersion, dnsTimeMs: 0 };
     }
     const dnsStart = Date.now();
-    const addresses = await lookup(host, { all: true, family: family ?? 0 });
+    let addresses;
+    if (dohResolver) {
+        addresses = await resolveWithDoH(dohResolver, host, family, signal);
+    }
+    else {
+        addresses = await lookup(host, { all: true, family: family ?? 0 });
+    }
     const dnsTimeMs = Date.now() - dnsStart;
     if (!addresses.length) {
         const err = new Error(`getaddrinfo ENOTFOUND ${host}`);
@@ -31,10 +37,6 @@ export async function happyEyeballsConnect(options) {
     const result = await raceTcpConnections(sorted, port, timeout, signal);
     return { socket: result.socket, address: result.address, family: result.family, dnsTimeMs };
 }
-/**
- * Interleave IPv6 and IPv4 addresses per RFC 8305 §4.
- * The first address family returned by the resolver leads.
- */
 function interleaveAddressFamilies(addresses) {
     const ipv6 = [];
     const ipv4 = [];
@@ -59,11 +61,6 @@ function interleaveAddressFamilies(addresses) {
     }
     return out;
 }
-/**
- * Race TCP connections across the sorted address list.
- * Each new attempt starts after ATTEMPT_DELAY_MS or immediately after
- * the previous attempt fails — whichever comes first.
- */
 function raceTcpConnections(addresses, port, timeout, signal) {
     if (addresses.length === 1) {
         return singleConnect(addresses[0], port, timeout, signal);
@@ -104,7 +101,7 @@ function raceTcpConnections(addresses, port, timeout, signal) {
             if (errors.length >= sockets.length && attemptIndex >= addresses.length) {
                 settled = true;
                 cleanup();
-                reject(errors[0]);
+                reject(errors[0] ?? new Error("All connection attempts failed"));
                 return;
             }
             if (attemptIndex < addresses.length) {
@@ -119,7 +116,9 @@ function raceTcpConnections(addresses, port, timeout, signal) {
             const entry = addresses[attemptIndex++];
             const socket = net.createConnection({ host: entry.address, port, family: entry.family });
             sockets.push(socket);
-            socket.once("connect", () => onSettled(socket, entry.address, entry.family));
+            socket.once("connect", () => {
+                onSettled(socket, entry.address, entry.family);
+            });
             socket.once("error", onAttemptError);
             if (attemptIndex < addresses.length) {
                 delayTimer = setTimeout(startNextAttempt, ATTEMPT_DELAY_MS);
@@ -154,7 +153,6 @@ function raceTcpConnections(addresses, port, timeout, signal) {
         startNextAttempt();
     });
 }
-/** Direct single-address connect, used when there is only one candidate. */
 function singleConnect(entry, port, timeout, signal) {
     return new Promise((resolve, reject) => {
         let settled = false;
@@ -191,11 +189,45 @@ function singleConnect(entry, port, timeout, signal) {
                 reject(new Error("Connection aborted"));
                 return;
             }
-            abortHandler = () => finish(new Error("Connection aborted"));
+            abortHandler = () => {
+                finish(new Error("Connection aborted"));
+            };
             signal.addEventListener("abort", abortHandler, { once: true });
         }
-        socket.once("connect", () => finish());
-        socket.once("error", (err) => finish(err));
+        socket.once("connect", () => {
+            finish();
+        });
+        socket.once("error", (err) => {
+            finish(err);
+        });
     });
 }
+async function resolveWithDoH(resolver, host, family, signal) {
+    const results = [];
+    try {
+        if (!family || family === 6) {
+            const aaaa = await resolver.query(host, "AAAA", signal);
+            for (const r of aaaa) {
+                if (r.type === RTYPE.AAAA && r.data.length === 16) {
+                    results.push({ address: parseAAAARecord(r.data), family: 6 });
+                }
+            }
+        }
+        if (!family || family === 4) {
+            const a = await resolver.query(host, "A", signal);
+            for (const r of a) {
+                if (r.type === RTYPE.A && r.data.length === 4) {
+                    results.push({ address: parseARecord(r.data), family: 4 });
+                }
+            }
+        }
+    }
+    catch {
+        return lookup(host, { all: true, family: family ?? 0 });
+    }
+    if (results.length === 0) {
+        return lookup(host, { all: true, family: family ?? 0 });
+    }
+    return results;
+}
 //# sourceMappingURL=happy-eyeballs.js.map

package/dist/utils/happy-eyeballs.js.map

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

package/dist/utils/logger.d.ts

@@ -1,124 +1,97 @@
-/**
- * Minimum severity level for log emission. Messages below this level are
- * suppressed. `'silent'` disables all output.
- *
- * @typedef {'debug' | 'info' | 'warn' | 'error' | 'silent'} LogLevel
- */
+/** Severity levels for log output. */
 export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
-/**
- * Key-value metadata attached to every log entry produced by a child logger.
- * Bindings are inherited from parent to child, allowing nested scoping.
- *
- * @typedef {Record<string, unknown>} LogBindings
- */
+/** Structured key-value bindings attached to log messages. */
 export type LogBindings = Record<string, unknown>;
-/**
- * Minimal logger interface consumed throughout the library. Implementations
- * must provide four severity methods; all parameters follow `console.log`
- * semantics (a primary message string followed by optional extra values).
- */
+/** Minimal structured logging interface. */
 export interface Logger {
-    /** Emits a diagnostic message useful only during development. */
+    /** Emit a debug-level message. */
     debug(message: string, ...args: unknown[]): void;
-    /** Emits a significant lifecycle or business event. */
+    /** Emit an info-level message. */
     info(message: string, ...args: unknown[]): void;
-    /** Emits a warning about an unexpected but recoverable condition. */
+    /** Emit a warning-level message. */
     warn(message: string, ...args: unknown[]): void;
-    /** Emits an error indicating an operation failure that requires attention. */
+    /** Emit an error-level message. */
     error(message: string, ...args: unknown[]): void;
 }
-/**
- * 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 declare class ConsoleLogger implements Logger {
     private level;
     private readonly prefix;
     private readonly 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?: LogLevel, prefix?: string, bindings?: LogBindings);
     /**
-     * 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: LogBindings): ConsoleLogger;
     /**
-     * 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: LogLevel): void;
-    /**
-     * 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: string, ...args: unknown[]): void;
+    /** Log an info-level message. */
+    info(message: string, ...args: unknown[]): void;
+    /** Log a warning-level message. */
+    warn(message: string, ...args: unknown[]): void;
+    /** Log an error-level message. */
+    error(message: string, ...args: unknown[]): void;
+    private write;
+    private formatArgs;
+    private resolveLevel;
+}
+/** Singleton no-op logger that discards all messages. */
+export declare const SILENT_LOGGER: Logger;
+/** Logger implementation that writes structured JSON to `stderr` with level filtering. */
+export declare class JsonLogger implements Logger {
+    private level;
+    private readonly service;
+    private readonly bindings;
     /**
-     * Emits an info-level message to `stderr` -- only written when the
-     * configured minimum level is `'debug'` or `'info'`.
+     * Create a JSON logger.
      *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
+     * @param {LogLevel} level - Minimum severity to output.
+     * @param {string} service - Service name included in every log entry.
+     * @param {LogBindings} bindings - Structured context fields.
      */
-    info(message: string, ...args: unknown[]): void;
+    constructor(level?: LogLevel, service?: string, bindings?: LogBindings);
     /**
-     * Emits a warn-level message to `stderr` -- only written when the
-     * configured minimum level is `'debug'`, `'info'`, or `'warn'`.
+     * Create a child JSON logger with additional bindings.
      *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
+     * @param {LogBindings} bindings - Extra structured context fields.
+     * @returns {JsonLogger} New child `JsonLogger`.
      */
-    warn(message: string, ...args: unknown[]): void;
+    child(bindings: LogBindings): JsonLogger;
     /**
-     * Emits an error-level message to `stderr` -- only written when the
-     * configured minimum level is not `'silent'`.
+     * Change the minimum log level at runtime.
      *
-     * @param {string}    message - Primary log message.
-     * @param {...unknown} args   - Additional values appended after the message.
+     * @param {LogLevel} level - New severity threshold.
      */
+    setLevel(level: LogLevel): void;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
-    private write;
-    private formatArgs;
+    private emit;
     private resolveLevel;
 }
 /**
- * A no-op {@link Logger} that discards all messages. Assign this via
- * {@link setDefaultLogger} to silence the library entirely.
- */
-export declare const SILENT_LOGGER: Logger;
-/**
- * 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 declare function setDefaultLogger(logger: Logger): void;
-/**
- * Returns the currently active process-wide logger.
- *
- * @returns {Logger} The active logger instance.
- */
+/** Return the current process-wide default logger. */
 export declare function getDefaultLogger(): Logger;
 //# sourceMappingURL=logger.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAUlD;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,iEAAiE;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,uDAAuD;IACvD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,qEAAqE;IACrE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,8EAA8E;IAC9E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IAEvC;;;;;;OAMG;gBACS,KAAK,GAAE,QAAiB,EAAE,MAAM,GAAE,MAAW,EAAE,QAAQ,GAAE,WAAgB;IAMrF;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa;IAO3C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMhD;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAMhD,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,YAAY;CAMrB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAK3B,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}