@wooksjs/event-http 0.7.26 → 0.7.28

package/dist/index.d.ts

@@ -80,7 +80,7 @@ declare const rawBodySlot: _wooksjs_event_core.Cached<Promise<Buffer<ArrayBuffer
  * ```
  */
 declare const useRequest: _wooksjs_event_core.WookComposable<{
-    raw: http.IncomingMessage;
+    raw: IncomingMessage;
     url: string | undefined;
     method: string | undefined;
     headers: http.IncomingHttpHeaders;
@@ -347,6 +347,60 @@ interface TCacheControl {
 /** Renders a `TCacheControl` object into a `Cache-Control` header string. */
 declare function renderCacheControl(data: TCacheControl): string;
 
+/** Content codings supported by response compression, in the order they are listed by default. */
+type THttpCompressionEncoding = 'br' | 'gzip';
+/**
+ * Response compression settings — the `compression` option of `createHttpApp()` and the
+ * argument of `HttpResponse.setCompression()`.
+ */
+interface THttpCompressionOptions {
+    /** Minimum body size in bytes to compress. Smaller bodies are sent as is. @default 1024 */
+    threshold?: number;
+    /**
+     * Codings the server may use, in preference order. The client's `Accept-Encoding` q-values
+     * decide first; this order breaks ties. @default ['br', 'gzip']
+     */
+    encodings?: THttpCompressionEncoding[];
+    /** Brotli quality (0–11). Higher is smaller and much slower — keep 4–5 for dynamic bodies. @default 4 */
+    brotliQuality?: number;
+    /** Gzip level (1–9). @default 6 */
+    gzipLevel?: number;
+    /**
+     * Decides whether a response with this content type may be compressed.
+     * Replaces the default check — call `isCompressibleType(contentType)` inside to extend it.
+     * @default isCompressibleType
+     */
+    filter?: (contentType: string, response: HttpResponse) => boolean;
+}
+/** Fully resolved compression settings (what `HttpResponse.compression` returns). */
+interface TResolvedHttpCompression {
+    threshold: number;
+    encodings: THttpCompressionEncoding[];
+    brotliQuality: number;
+    gzipLevel: number;
+    filter: (contentType: string, response: HttpResponse) => boolean;
+}
+/**
+ * Default compression filter: `text/*` (except `text/event-stream`), JSON and `+json`, XML and
+ * `+xml`, JavaScript, SVG, NDJSON, WASM and form-urlencoded content types.
+ */
+declare function isCompressibleType(contentType: string): boolean;
+/**
+ * Picks the content coding for a response from the request's `Accept-Encoding` header.
+ *
+ * The coding with the highest client q-value wins; `supported` order breaks ties. `q=0`
+ * excludes a coding, `*` matches every coding not listed explicitly. Returns `undefined` when
+ * the header is missing or none of `supported` is acceptable — send the body uncompressed then.
+ *
+ * @example
+ * ```ts
+ * negotiateEncoding('gzip, deflate, br', ['br', 'gzip']) // 'br'
+ * negotiateEncoding('br;q=0.5, gzip', ['br', 'gzip'])     // 'gzip'
+ * negotiateEncoding('*;q=0, identity', ['br', 'gzip'])    // undefined
+ * ```
+ */
+declare function negotiateEncoding<T extends string>(acceptEncoding: string | string[] | undefined, supported: readonly T[]): T | undefined;
+
 /**
  * Manages response status, headers, cookies, cache control, and body for an HTTP request.
  *
@@ -370,15 +424,23 @@ declare class HttpResponse {
      * @param _req - The underlying Node.js `IncomingMessage`.
      * @param _logger - Logger instance for error reporting.
      * @param defaultHeaders - Optional headers to pre-populate on this response (e.g. from `securityHeaders()`).
+     * @param _captureMode - Finalize state on `send()` without writing to `_res` (programmatic fetch).
+     * @param compression - App-level response compression settings (`undefined` = off).
      */
-    constructor(_res: ServerResponse, _req: IncomingMessage, _logger: Logger, defaultHeaders?: Record<string, string | string[]>, _captureMode?: boolean);
+    constructor(_res: ServerResponse, _req: IncomingMessage, _logger: Logger, defaultHeaders?: Record<string, string | string[]>, _captureMode?: boolean, compression?: TResolvedHttpCompression);
     protected _status: EHttpStatusCode;
     protected _body: unknown;
     protected _headers: Record<string, string | string[]>;
-    protected _cookies: Record<string, TSetCookieData>;
-    protected _rawCookies: string[];
+    /** Outgoing named cookies — allocated on the first `setCookie()`. */
+    protected _cookies?: Record<string, TSetCookieData>;
+    /** Outgoing raw `Set-Cookie` strings — allocated on the first `setCookieRaw()`. */
+    protected _rawCookies?: string[];
     protected _hasCookies: boolean;
     protected _responded: boolean;
+    /** Registry entry of the prerendered body picked by the last `renderBody()` (see `prerenderJson`). */
+    private _prerendered?;
+    /** Effective compression settings for this response (`undefined` = off). */
+    protected _compression: TResolvedHttpCompression | undefined;
     /** The HTTP status code. If not set, it is inferred automatically when `send()` is called. */
     get status(): EHttpStatusCode;
     set status(value: EHttpStatusCode);
@@ -433,6 +495,19 @@ declare class HttpResponse {
     setExpires(value: Date | string | number): this;
     /** Sets or clears the `Pragma: no-cache` header (chainable). */
     setPragmaNoCache(value?: boolean): this;
+    /**
+     * Overrides response compression for this response (chainable).
+     *
+     * - `false` — never compress this response (e.g. a body that mixes secrets with reflected input).
+     * - `true` — compress with the app settings, or the defaults when the app has compression off.
+     * - an options object — compress with these settings over the app settings (or the defaults).
+     *
+     * Only regular bodies (strings, numbers, booleans, objects, `Uint8Array`) are compressed; streams
+     * and fetch `Response` bodies are sent as is.
+     */
+    setCompression(value: boolean | THttpCompressionOptions): this;
+    /** Effective compression settings for this response, or `false` when compression is off. */
+    get compression(): Readonly<TResolvedHttpCompression> | false;
     /**
      * Returns the underlying Node.js `ServerResponse`.
      * @param passthrough - If `true`, the framework still manages the response lifecycle. If `false` (default), the response is marked as "responded" and the framework will not touch it.
@@ -463,11 +538,23 @@ declare class HttpResponse {
      *
      * Flushes all accumulated headers (including cookies) in a single `writeHead()` call,
      * then writes the body. Supports `Readable` streams, `fetch` `Response` objects, and regular values.
+     * Returns a Promise (which never rejects) for streamed bodies and compressed regular bodies.
      *
      * @throws Error if the response was already sent.
      */
     send(): void | Promise<void>;
     private finalizeCookies;
+    /**
+     * For a body registered with `prerenderJson(obj, { etag: true })`: sets the `ETag` header on a
+     * GET/HEAD 2xx response (unless one was set explicitly) and turns a `200` whose `If-None-Match`
+     * matches into a bodiless `304`. Returns `true` when the response became `304`.
+     * Other methods get no ETag (a validator on e.g. a PUT response would describe the stored resource).
+     */
+    private applyPrerenderedEtag;
+    /** Returns the stored key of header `name` (lower-case) in whatever casing it was set with. */
+    private headerKeyIgnoreCase;
+    /** Returns and clears the prerender entry picked by the last `renderBody()`. */
+    private takePrerendered;
     private autoStatus;
     private sendStream;
     /**
@@ -481,6 +568,25 @@ declare class HttpResponse {
     private pipeToResponse;
     private sendFetchResponse;
     private sendRegular;
+    /**
+     * Whether a rendered regular body of `size` bytes may be compressed — independent of the
+     * request's `Accept-Encoding` (and of HEAD, which is answered uncompressed).
+     */
+    private isCompressible;
+    /** Adds `token` to the `Vary` header (case-insensitive merge, keeps existing entries). */
+    private appendVary;
+    /**
+     * Sends the body compressed with `encoding`. Prerendered bodies are compressed once per coding
+     * and level and the bytes reused (sent synchronously once ready). A compressor failure is
+     * logged and the body is sent uncompressed — headers are not written yet, so that is safe.
+     * Never rejects: a sync handler's `send()` is not awaited.
+     */
+    private sendCompressed;
+    /**
+     * Writes the body picked by `sendCompressed()` — the `encoding`-compressed bytes, or the identity
+     * body after a compressor failure — unless the client went away meanwhile.
+     */
+    private writeDeferred;
 }
 /** Converts a Record of headers to a Web Standard `Headers` object. */
 declare function recordToWebHeaders(record: Record<string, string | string[]>): Headers;
@@ -583,6 +689,18 @@ interface TWooksHttpOptions {
      * @default DEFAULT_FORWARD_HEADERS — ['authorization', 'cookie', 'accept-language', 'x-forwarded-for', 'x-request-id']
      */
     forwardHeaders?: string[] | false;
+    /**
+     * Compresses regular response bodies (JSON, text, HTML, …) with brotli or gzip, negotiated
+     * from the request's `Accept-Encoding`. Off by default. `true` uses the defaults
+     * (`threshold: 1024`, `encodings: ['br', 'gzip']`, `brotliQuality: 4`, `gzipLevel: 6`);
+     * an object overrides them. Streams, fetch `Response` bodies and programmatic `fetch()`
+     * responses are never compressed. Opt a single response out with
+     * `useResponse().setCompression(false)`.
+     *
+     * Do not enable it for responses that mix secrets with attacker-controlled input (BREACH).
+     * @default false
+     */
+    compression?: boolean | THttpCompressionOptions;
 }
 /** HTTP adapter for Wooks that provides route registration, server lifecycle, and request handling. */
 declare class WooksHttp extends WooksAdapterBase {
@@ -590,6 +708,7 @@ declare class WooksHttp extends WooksAdapterBase {
     protected logger: TConsoleBase;
     protected ResponseClass: typeof WooksHttpResponse;
     protected eventContextOptions: EventContextOptions;
+    protected compression: TResolvedHttpCompression | undefined;
     constructor(opts?: TWooksHttpOptions | undefined, wooks?: Wooks | WooksAdapterBase);
     /** Registers a handler for all HTTP methods on the given path. */
     all<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
@@ -729,6 +848,49 @@ declare class WooksHttp extends WooksAdapterBase {
  */
 declare function createHttpApp(opts?: TWooksHttpOptions, wooks?: Wooks | WooksAdapterBase): WooksHttp;
 
+/** Options for {@link prerenderJson}. */
+interface TPrerenderJsonOptions {
+    /**
+     * Also compute a weak `ETag` from the serialized bytes. Responses that send the object then
+     * carry the `ETag` header and answer a matching `If-None-Match` (GET/HEAD, status 200) with
+     * `304 Not Modified`.
+     */
+    etag?: boolean;
+}
+/**
+ * Serializes `obj` to JSON once and remembers the string by object identity. Whenever a handler
+ * (or an interceptor) responds with that same object, the response reuses the stored JSON instead
+ * of calling `JSON.stringify` again. Use it for large, long-lived response objects that many
+ * requests return as is — e.g. a schema or metadata envelope built once and cached.
+ *
+ * With `{ etag: true }` a weak `ETag` is derived from the serialized bytes; a `GET`/`HEAD`
+ * that responds `200` with the object sets the `ETag` header and answers a matching
+ * `If-None-Match` with `304 Not Modified` (no body; other headers such as `Cache-Control`
+ * and `Vary` are kept). Error responses never become `304`. An `ETag` header set explicitly
+ * on the response wins and disables the `304` handling for that response.
+ *
+ * **Contract: never mutate a registered object (or anything it references).** The stored JSON
+ * is not refreshed, so a mutation would keep serving the old bytes. Build a new object instead —
+ * freezing registered objects (`Object.freeze`, deeply) in development makes violations throw.
+ *
+ * Calling it again for the same object is a no-op (it adds the `ETag` if it was not requested
+ * the first time). Entries are held weakly and disappear with the object.
+ *
+ * @param obj - A JSON-serializable object or array
+ * @param options - `{ etag: true }` to also compute a weak ETag
+ * @returns The same `obj`, so it can wrap a return value
+ *
+ * @example
+ * ```ts
+ * const envelope = prerenderJson(Object.freeze(buildMeta()), { etag: true })
+ * app.get('/meta', () => {
+ *   useResponse().setHeader('cache-control', 'private, no-cache')
+ *   return envelope // sent without re-serializing; 304 on a matching If-None-Match
+ * })
+ * ```
+ */
+declare function prerenderJson<T extends object>(obj: T, options?: TPrerenderJsonOptions): T;
+
 /**
  * Configuration for `securityHeaders()`. Each option accepts a `string` (override value),
  * `false` (disable), or `undefined` (use default). `strictTransportSecurity` has no default (opt-in only).
@@ -793,5 +955,5 @@ interface TTestHttpContext {
  */
 declare function prepareTestHttpContext(options: TTestHttpContext): <T>(cb: (...a: any[]) => T) => T;
 
-export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, prepareTestHttpContext, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useUrlParams };
-export type { KnownAcceptType, KnownAuthType, SecurityHeadersOptions, TCacheControl, TCookieAttributes, TCookieAttributesInput, THttpEventData, TRequestLimits, TSetCookieData, TTestHttpContext, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions };
+export { DEFAULT_FORWARD_HEADERS, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpResponse, WooksHttp, WooksHttpResponse, WooksURLSearchParams, createHttpApp, createHttpContext, httpKind, httpStatusCodes, isCompressibleType, negotiateEncoding, prepareTestHttpContext, prerenderJson, rawBodySlot, recordToWebHeaders, renderCacheControl, securityHeaders, seedRawBody, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useUrlParams };
+export type { KnownAcceptType, KnownAuthType, SecurityHeadersOptions, TCacheControl, TCookieAttributes, TCookieAttributesInput, THttpCompressionEncoding, THttpCompressionOptions, THttpEventData, TPrerenderJsonOptions, TRequestLimits, TResolvedHttpCompression, TSetCookieData, TTestHttpContext, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions };