nlcurl 0.7.0 → 0.9.0

package/dist/core/response.js

@@ -1,50 +1,39 @@
 /**
- * Represents the complete HTTP response from a successful request. Provides
- * convenience accessors for common content-type parsing, streaming, and
- * header inspection.
+ * Encapsulates an HTTP response with status, headers, body, timing data,
+ * and convenience accessors for common header values and body parsing.
  *
- * @template T - Expected shape of the JSON-decoded body when calling {@link NLcURLResponse.json}.
+ * @class
+ * @template T - The expected JSON body type.
  */
 export class NLcURLResponse {
-    /** HTTP status code (e.g. `200`, `404`). */
+    /** The HTTP status code. */
     status;
-    /** HTTP status text (e.g. `"OK"`, `"Not Found"`). */
+    /** The HTTP reason phrase. */
     statusText;
-    /** Normalized, lowercase response headers. Duplicate values are joined by `, `. */
+    /** Response headers as a case-insensitive key-value map. */
     headers;
-    /** All response header name-value pairs exactly as received, in transmission order. */
+    /** Raw header pairs preserving original casing and duplicates. */
     rawHeaders;
-    /** Fully buffered response body. Empty when the response was opened in streaming mode. */
+    /** The full response body as a Buffer. */
     rawBody;
-    /** Readable stream of the response body, or `null` for buffered responses. */
+    /** A readable stream for streaming responses, or `null` for buffered responses. */
     body;
-    /** HTTP protocol version string (e.g. `"HTTP/1.1"`, `"HTTP/2.0"`). */
+    /** The negotiated HTTP version (e.g. "1.1", "2"). */
     httpVersion;
-    /** Final URL of the response after any redirects. */
+    /** The final URL after any redirects. */
     url;
-    /** Number of redirects followed before this response was received. */
+    /** The number of redirects followed to reach this response. */
     redirectCount;
-    /** Granular timing measurements for each phase of the request lifecycle. */
+    /** Timing measurements for each request phase. */
     timings;
     /** Metadata about the originating request. */
     request;
     _json;
     _text;
     /**
-     * Creates a new NLcURLResponse instance.
+     * Creates a new NLcURLResponse from the provided initialization fields.
      *
-     * @param {Object}                         init                 - Response initialization data.
-     * @param {number}                         init.status          - HTTP status code.
-     * @param {string}                         init.statusText      - HTTP status text.
-     * @param {Record<string,string>}          init.headers         - Normalized response headers.
-     * @param {Array<[string,string]>}         [init.rawHeaders]    - Raw header pairs; defaults to entries of `headers`.
-     * @param {Buffer}                         init.rawBody         - Fully buffered response body.
-     * @param {Readable|null}                  [init.body]          - Streaming body, or `null`.
-     * @param {string}                         init.httpVersion     - Protocol version string.
-     * @param {string}                         init.url             - Final URL after redirects.
-     * @param {number}                         init.redirectCount   - Number of redirects followed.
-     * @param {RequestTimings}                 init.timings         - Lifecycle timing measurements.
-     * @param {ResponseMeta}                   init.request         - Originating request metadata.
+     * @param {Object} init - Response initialization fields.
      */
     constructor(init) {
         this.status = init.status;
@@ -60,8 +49,7 @@ export class NLcURLResponse {
         this.request = init.request;
     }
     /**
-     * Returns `true` when the HTTP status code is in the 200–299 (successful)
-     * range, `false` otherwise.
+     * Returns `true` if the response status is in the 2xx range.
      *
      * @returns {boolean} Whether the response indicates success.
      */
@@ -69,11 +57,10 @@ export class NLcURLResponse {
         return this.status >= 200 && this.status < 300;
     }
     /**
-     * Decodes the raw body as a UTF-8 string and returns it. The result is
-     * memoized after the first call.
+     * Decodes the raw body as a UTF-8 string. Throws if the response is streaming.
      *
-     * @returns {string} The response body decoded as UTF-8.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @returns {string} The response body as text.
+     * @throws {Error} If the response is a streaming response.
      */
     text() {
         if (this.body) {
@@ -87,17 +74,12 @@ export class NLcURLResponse {
         return cached;
     }
     /**
-     * Parses the raw body as JSON and returns the decoded value. The result is
-     * memoized after the first call.
+     * Parses the response body as JSON. Throws if the response is streaming.
      *
-     * @template R - Expected type of the decoded JSON value; defaults to `T`.
-     * @returns {R} The JSON-decoded response body.
-     * @throws {Error} If the response was opened in streaming mode (`stream: true`).
+     * @template R - The expected parsed type.
+     * @returns {R} The parsed JSON value.
+     * @throws {Error} If the response is a streaming response.
      * @throws {SyntaxError} If the body is not valid JSON.
-     *
-     * @example
-     * const data = response.json<{ id: number; name: string }>();
-     * console.log(data.id);
      */
     json() {
         if (this.body) {
@@ -109,8 +91,7 @@ export class NLcURLResponse {
         return this._json;
     }
     /**
-     * Returns the `Content-Length` as a number. Falls back to the buffer byte
-     * length when the header is absent or unparseable.
+     * Returns the Content-Length header value, or the raw body length as a fallback.
      *
      * @returns {number} The content length in bytes.
      */
@@ -124,53 +105,58 @@ export class NLcURLResponse {
         return this.rawBody.length;
     }
     /**
-     * Returns the value of the `Content-Type` response header, or an empty
-     * string when the header is absent.
+     * Returns the Content-Type header value.
      *
-     * @returns {string} The `Content-Type` header value.
+     * @returns {string} The content type, or an empty string if absent.
      */
     get contentType() {
         return this.headers["content-type"] ?? "";
     }
     /**
-     * Returns the `ETag` response header value, or `undefined` when absent.
+     * Returns the ETag header value, if present.
+     *
+     * @returns {string|undefined} The entity tag.
      */
     get etag() {
         return this.headers["etag"];
     }
     /**
-     * Returns the `Last-Modified` response header value, or `undefined` when absent.
+     * Returns the Last-Modified header value, if present.
+     *
+     * @returns {string|undefined} The last modified date string.
      */
     get lastModified() {
         return this.headers["last-modified"];
     }
     /**
-     * Returns the `Cache-Control` response header value, or `undefined` when absent.
+     * Returns the Cache-Control header value, if present.
+     *
+     * @returns {string|undefined} The cache control directive string.
      */
     get cacheControl() {
         return this.headers["cache-control"];
     }
     /**
-     * Returns the `Content-Range` response header value, or `undefined` when absent.
-     * Present on 206 Partial Content responses (RFC 9110 §14.4).
+     * Returns the Content-Range header value, if present.
+     *
+     * @returns {string|undefined} The content range descriptor.
      */
     get contentRange() {
         return this.headers["content-range"];
     }
     /**
-     * Returns the `Accept-Ranges` response header value, or `undefined` when absent.
-     * Indicates whether the server supports range requests (RFC 9110 §14.3).
+     * Returns the Accept-Ranges header value, if present.
+     *
+     * @returns {string|undefined} The accepted range unit.
      */
     get acceptRanges() {
         return this.headers["accept-ranges"];
     }
     /**
-     * Returns all values for a response header, in transmission order,
-     * supporting multi-value headers such as `Set-Cookie` which are joined
-     * when accessed through `headers`.
+     * Retrieves all values for a given header name from the raw headers array.
      *
-     * @param {string} name - The case-insensitive header name to look up.
-     * @returns {string[]} All header values for the given name, or an empty array.
+     * @param {string} name - The header name (case-insensitive).
+     * @returns {string[]} All values for the specified header.
      */
     getAll(name) {
         const lower = name.toLowerCase();

package/dist/core/response.js.map

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

package/dist/core/session.d.ts

@@ -6,21 +6,14 @@ import { type RateLimitConfig } from "../middleware/rate-limiter.js";
 import { CacheStore } from "../cache/store.js";
 import { HSTSStore } from "../hsts/store.js";
 /**
- * Request options that can be passed alongside a URL and HTTP method. All
- * fields from {@link NLcURLRequest} except `url`, `method`, and `body`.
- *
- * @typedef {Omit<NLcURLRequest, 'url'|'method'|'body'>} RequestOptions
+ * Request options excluding URL, method, and body — used for convenience method signatures.
  */
 export type RequestOptions = Omit<NLcURLRequest, "url" | "method" | "body">;
 /**
- * Stateful HTTP client session that persists connections, cookies, interceptors,
- * and configuration across multiple requests. Prefer using a session when making
- * many requests to the same origin, or when you need shared cookie state.
+ * Manages a persistent HTTP session with connection pooling, cookie storage,
+ * caching, HSTS enforcement, interceptors, rate limiting, and retry logic.
  *
- * @example
- * const session = new NLcURLSession({ impersonate: 'chrome136' });
- * const response = await session.get('https://example.com');
- * session.close();
+ * @class
  */
 export declare class NLcURLSession {
     private readonly config;
@@ -33,143 +26,138 @@ export declare class NLcURLSession {
     private readonly hstsStore;
     private closed;
     /**
-     * Creates a new NLcURLSession.
+     * Creates a new session with the given configuration.
      *
-     * @param {NLcURLSessionConfig} [config={}] - Session-level defaults applied to every request.
+     * @param {NLcURLSessionConfig} [config={}] - Session-level defaults and feature toggles.
+     * @throws {NLcURLError} If configuration values are invalid.
      */
     constructor(config?: NLcURLSessionConfig);
     /**
-     * Registers a request interceptor that is invoked (in registration order)
-     * before each request is dispatched. The interceptor may return a modified
-     * request object or a `Promise` that resolves to one.
+     * Registers a request interceptor invoked before each outgoing request.
      *
-     * @param {RequestInterceptor} fn - The interceptor function to add.
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {RequestInterceptor} fn - The interceptor function.
+     * @returns {this} The session instance for chaining.
      */
     onRequest(fn: RequestInterceptor): this;
     /**
-     * Registers a response interceptor that is invoked (in registration order)
-     * after each response is received. The interceptor may return a modified
-     * response object or a `Promise` that resolves to one.
+     * Registers a response interceptor invoked after each incoming response.
      *
-     * @param {ResponseInterceptor} fn - The interceptor function to add.
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {ResponseInterceptor} fn - The interceptor function.
+     * @returns {this} The session instance for chaining.
      */
     onResponse(fn: ResponseInterceptor): this;
     /**
-     * Applies a token-bucket rate limit to all requests issued by this session.
-     * Requests that exceed the configured rate will wait until a token becomes
-     * available before proceeding.
+     * Configures a token-bucket rate limiter for this session.
      *
-     * @param {RateLimitConfig} config - Rate limit parameters (`maxRequests` per `windowMs`).
-     * @returns {this} The session instance, enabling a fluent call chain.
+     * @param {RateLimitConfig} config - Rate limit parameters.
+     * @returns {this} The session instance for chaining.
+     * @throws {NLcURLError} If the rate limit config is invalid.
      */
     setRateLimit(config: RateLimitConfig): this;
     /**
-     * Issues a `GET` request and resolves with the complete response.
+     * Sends an HTTP GET request.
      *
-     * @param {string}          url      - The URL to request.
-     * @param {RequestOptions}  [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     get(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues a `POST` request and resolves with the complete response.
+     * Sends an HTTP POST request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     post(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues a `PUT` request and resolves with the complete response.
+     * Sends an HTTP PUT request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     put(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues a `PATCH` request and resolves with the complete response.
+     * Sends an HTTP PATCH request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestBody}    [body]   - Request body payload.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The request body.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     patch(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues a `DELETE` request and resolves with the complete response.
+     * Sends an HTTP DELETE request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     delete(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues a `HEAD` request and resolves with the complete response (no body).
+     * Sends an HTTP HEAD request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     head(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Issues an `OPTIONS` request and resolves with the complete response.
+     * Sends an HTTP OPTIONS request.
      *
-     * @param {string}         url      - The URL to request.
-     * @param {RequestOptions} [options] - Optional per-request settings.
+     * @param {string} url - The target URL.
+     * @param {RequestOptions} [options] - Additional request options.
      * @returns {Promise<NLcURLResponse>} Resolves with the server response.
      */
     options(url: string, options?: RequestOptions): Promise<NLcURLResponse>;
     /**
-     * Executes a fully described HTTP request, applying session defaults, request
-     * interceptors, redirect following, cookie management, and response
-     * interceptors in sequence.
+     * Sends an HTTP QUERY request (RFC 9110).
      *
-     * @param {NLcURLRequest} input - The request descriptor.
-     * @returns {Promise<NLcURLResponse>} Resolves with the final response after all redirects.
-     * @throws {NLcURLError}     If the session has been closed.
-     * @throws {AbortError}      If the provided `AbortSignal` fires before completion.
-     * @throws {TimeoutError}    If any configured timeout is exceeded.
-     * @throws {ConnectionError} If a TCP connection cannot be established.
-     * @throws {TLSError}        If the TLS handshake fails.
-     * @throws {ProxyError}      If the proxy tunnel cannot be established.
-     * @throws {NLcURLError}     If the maximum number of redirects is exceeded (`ERR_MAX_REDIRECTS`).
+     * @param {string} url - The target URL.
+     * @param {RequestBody} [body] - The query body.
+     * @param {RequestOptions} [options] - Additional request options.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     */
+    query(url: string, body?: RequestBody, options?: RequestOptions): Promise<NLcURLResponse>;
+    /**
+     * Sends an HTTP request with full session features including caching,
+     * HSTS upgrade, cookie handling, compression, retry, and interceptors.
+     *
+     * @param {NLcURLRequest} input - The complete request descriptor.
+     * @returns {Promise<NLcURLResponse>} Resolves with the server response.
+     * @throws {NLcURLError} If the session is closed.
+     * @throws {HTTPError} If `throwOnError` is enabled and the response is non-2xx.
      */
     request(input: NLcURLRequest): Promise<NLcURLResponse>;
     /**
-     * Returns the active {@link CookieJar} for this session, or `null` if
-     * cookie management was disabled via `cookieJar: false`.
+     * Returns the session's cookie jar, or `null` if cookies are disabled.
      *
-     * @returns {CookieJar|null} The shared cookie jar, or `null`.
+     * @returns {CookieJar|null} The cookie jar instance.
      */
     getCookies(): CookieJar | null;
     /**
-     * Returns the active {@link CacheStore} for this session, or `null` if
-     * caching was not enabled.
+     * Returns the session's cache store, or `null` if caching is disabled.
      *
-     * @returns {CacheStore|null} The cache store, or `null`.
+     * @returns {CacheStore|null} The cache store instance.
      */
     getCache(): CacheStore | null;
     /**
-     * Returns the active {@link HSTSStore} for this session, or `null` if
-     * HSTS was not enabled.
+     * Returns the session's HSTS store, or `null` if HSTS is disabled.
      *
-     * @returns {HSTSStore|null} The HSTS store, or `null`.
+     * @returns {HSTSStore|null} The HSTS store instance.
      */
     getHSTS(): HSTSStore | null;
     /**
-     * Returns the Alt-Svc store used by this session's negotiator.
-     * The store records Alt-Svc headers from responses for HTTP/3 discovery.
+     * Returns the session's Alt-Svc store for HTTP alternative service lookups.
+     *
+     * @returns {import("../http/alt-svc.js").AltSvcStore} The Alt-Svc store instance.
      */
     getAltSvc(): import("../http/alt-svc.js").AltSvcStore;
     /**
-     * Closes the session, releasing any pooled connections. After calling this
-     * method, issuing further requests will throw an `NLcURLError` with code
-     * `ERR_SESSION_CLOSED`. Subsequent calls are no-ops.
+     * Closes the session and releases all pooled connections.
      */
     close(): void;
     private mergeDefaults;

package/dist/core/session.d.ts.map

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