@wooksjs/event-http 0.6.2 → 0.6.4

package/dist/index.d.ts

@@ -155,6 +155,7 @@ declare class WooksURLSearchParams extends URLSearchParams {
 interface THttpEventData {
     req: IncomingMessage;
     res: ServerResponse;
+    requestLimits?: TRequestLimits;
 }
 interface THttpEvent {
     type: 'HTTP';
@@ -196,6 +197,19 @@ interface TAuthCache {
         password: string;
     } | null;
 }
+/** App-level request body limits (all optional, defaults apply when omitted). */
+interface TRequestLimits {
+    /** Max compressed body size in bytes (default: 1 MB). */
+    maxCompressed?: number;
+    /** Max inflated (decompressed) body size in bytes (default: 10 MB). */
+    maxInflated?: number;
+    /** Max compression ratio, e.g. 100 means 100× expansion (default: 100). */
+    maxRatio?: number;
+    /** Body read timeout in milliseconds (default: 10 000). */
+    readTimeoutMs?: number;
+    /** Internal flag: true when this object is a per-request clone (copy-on-write). */
+    perRequest?: boolean;
+}
 interface TRequestCache {
     rawBody: Promise<Buffer>;
     parsed: unknown;
@@ -207,20 +221,25 @@ interface TRequestCache {
     };
     contentEncodings?: string[];
     isCompressed?: boolean;
-    maxCompressed?: number;
-    maxInflated?: number;
-    maxRatio?: number;
-    readTimeoutMs?: number;
 }
 interface TSearchParamsCache {
     raw?: string;
     urlSearchParams?: WooksURLSearchParams;
 }
 
+/**
+ * Provides access to parsed request cookies.
+ * @example
+ * ```ts
+ * const { getCookie, rawCookies } = useCookies()
+ * const sessionId = getCookie('session_id')
+ * ```
+ */
 declare function useCookies(): {
     rawCookies: string | undefined;
     getCookie: (name: string) => string | null;
 };
+/** Provides methods to set, get, remove, and clear outgoing response cookies. */
 declare function useSetCookies(): {
     setCookie: (name: string, value: string, attrs?: Partial<TCookieAttributes>) => void;
     getCookie: <K2 extends string>(key2: K2) => TSetCookieData | undefined;
@@ -228,12 +247,15 @@ declare function useSetCookies(): {
     clearCookies: () => void;
     cookies: () => string[];
 };
+/** Returns a hookable accessor for a single outgoing cookie by name. */
 declare function useSetCookie(name: string): {
     name: string;
     type: string;
 } & _wooksjs_event_core.THook<string, "value"> & _wooksjs_event_core.THook<TCookieAttributes, "attrs">;
+/** Hook type returned by {@link useSetCookie}. */
 type TCookieHook = ReturnType<typeof useSetCookie>;
 
+/** Provides helpers to check the request's Accept header for supported MIME types. */
 declare function useAccept(): {
     accept: string | undefined;
     accepts: (mime: string) => unknown;
@@ -243,6 +265,14 @@ declare function useAccept(): {
     acceptsHtml: () => unknown;
 };
 
+/**
+ * Provides parsed access to the Authorization header (type, credentials, Basic decoding).
+ * @example
+ * ```ts
+ * const { isBearer, authRawCredentials, basicCredentials } = useAuthorization()
+ * if (isBearer()) { const token = authRawCredentials() }
+ * ```
+ */
 declare function useAuthorization(): {
     authorization: string | undefined;
     authType: () => string | null;
@@ -268,6 +298,7 @@ interface TCacheControl {
 }
 declare function renderCacheControl(data: TCacheControl): string;
 
+/** Provides helpers to set cache-related response headers (Cache-Control, Expires, Age, Pragma). */
 declare function useSetCacheControl(): {
     setExpires: (value: Date | string | number) => void;
     setAge: (value: number | TTimeMultiString) => void;
@@ -275,7 +306,22 @@ declare function useSetCacheControl(): {
     setCacheControl: (data: TCacheControl) => void;
 };
 
+/**
+ * Returns the incoming request headers.
+ * @example
+ * ```ts
+ * const { host, authorization } = useHeaders()
+ * ```
+ */
 declare function useHeaders(): IncomingHttpHeaders;
+/**
+ * Provides methods to set, get, and remove outgoing response headers.
+ * @example
+ * ```ts
+ * const { setHeader, setContentType, enableCors } = useSetHeaders()
+ * setHeader('x-request-id', '123')
+ * ```
+ */
 declare function useSetHeaders(): {
     setHeader: (name: string, value: string | number) => void;
     getHeader: <K2 extends string>(key2: K2) => string | string[] | undefined;
@@ -284,18 +330,29 @@ declare function useSetHeaders(): {
     headers: () => Record<string, string | string[]>;
     enableCors: (origin?: string) => void;
 };
+/** Returns a hookable accessor for a single outgoing response header by name. */
 declare function useSetHeader(name: string): {
     value: string | string[];
     isDefined: boolean;
 };
+/** Hook type returned by {@link useSetHeader}. */
 type THeaderHook = ReturnType<typeof useSetHeader>;
 
+/** Default safety limits for request body reading (size, ratio, timeout). */
 declare const DEFAULT_LIMITS: {
     readonly maxCompressed: number;
     readonly maxInflated: number;
     readonly maxRatio: 100;
     readonly readTimeoutMs: 10000;
 };
+/**
+ * Provides access to the incoming HTTP request (method, url, headers, body, IP).
+ * @example
+ * ```ts
+ * const { method, url, rawBody, getIp } = useRequest()
+ * const body = await rawBody()
+ * ```
+ */
 declare function useRequest(): {
     rawRequest: http.IncomingMessage;
     url: string | undefined;
@@ -312,27 +369,47 @@ declare function useRequest(): {
     };
     isCompressed: () => boolean;
     getMaxCompressed: () => number;
-    setMaxCompressed: (limit: number) => unknown;
+    setMaxCompressed: (limit: number) => void;
     getReadTimeoutMs: () => number;
-    setReadTimeoutMs: (limit: number) => unknown;
+    setReadTimeoutMs: (limit: number) => void;
     getMaxInflated: () => number;
-    setMaxInflated: (limit: number) => unknown;
+    setMaxInflated: (limit: number) => void;
+    getMaxRatio: () => number;
+    setMaxRatio: (limit: number) => void;
 };
 
 interface TUseResponseOptions {
     passthrough: boolean;
 }
+/**
+ * Provides access to the raw HTTP response and status code management.
+ * @example
+ * ```ts
+ * const { status, rawResponse, hasResponded } = useResponse()
+ * status(200)
+ * ```
+ */
 declare function useResponse(): {
     rawResponse: (options?: TUseResponseOptions) => http.ServerResponse<http.IncomingMessage>;
     hasResponded: () => boolean;
     status: ((code?: EHttpStatusCode) => EHttpStatusCode) & _wooksjs_event_core.THook<EHttpStatusCode, "value">;
 };
+/** Returns a hookable accessor for the response status code. */
 declare function useStatus(): {
     value: EHttpStatusCode;
     isDefined: boolean;
 };
+/** Hook type returned by {@link useStatus}. */
 type TStatusHook = ReturnType<typeof useStatus>;
 
+/**
+ * Provides access to URL search (query) parameters from the request.
+ * @example
+ * ```ts
+ * const { urlSearchParams, jsonSearchParams } = useSearchParams()
+ * const page = urlSearchParams().get('page')
+ * ```
+ */
 declare function useSearchParams(): {
     rawSearchParams: () => string;
     urlSearchParams: () => WooksURLSearchParams;
@@ -374,6 +451,7 @@ declare class BaseHttpResponse<BodyType = unknown> {
     respond(): Promise<unknown>;
 }
 
+/** Represents an HTTP error with a status code and optional structured body. */
 declare class HttpError<T extends TWooksErrorBody = TWooksErrorBody> extends Error {
     protected code: THttpErrorCodes;
     protected _body: string | T;
@@ -384,15 +462,18 @@ declare class HttpError<T extends TWooksErrorBody = TWooksErrorBody> extends Err
     attachRenderer(renderer: HttpErrorRenderer): void;
     getRenderer(): HttpErrorRenderer | undefined;
 }
+/** Base shape for an HTTP error response body. */
 interface TWooksErrorBody {
     message: string;
     statusCode: EHttpStatusCode;
     error?: string;
 }
+/** Extended error body that always includes the error description string. */
 interface TWooksErrorBodyExt extends TWooksErrorBody {
     error: string;
 }
 
+/** Renders HTTP error responses in HTML, JSON, or plain text based on the Accept header. */
 declare class HttpErrorRenderer extends BaseHttpResponseRenderer<TWooksErrorBodyExt> {
     protected opts?: {
         version: string;
@@ -424,6 +505,7 @@ declare class HttpErrorRenderer extends BaseHttpResponseRenderer<TWooksErrorBody
     render(response: BaseHttpResponse<TWooksErrorBodyExt>): string;
 }
 
+/** Creates an async event context for an incoming HTTP request/response pair. */
 declare function createHttpContext(data: THttpEventData, options: TEventOptions): <T>(cb: (...a: any[]) => T) => T;
 /**
  * Wrapper on useEventContext with HTTP event types
@@ -436,23 +518,35 @@ declare function createWooksResponder(renderer?: TWooksResponseRenderer<any>, er
     respond: (data: unknown) => Promise<unknown> | undefined;
 };
 
+/** Configuration options for the WooksHttp adapter. */
 interface TWooksHttpOptions {
     logger?: TConsoleBase;
     eventOptions?: TEventOptions;
     onNotFound?: TWooksHandler;
     router?: TWooksOptions['router'];
+    /** Default request body limits applied to every request (overridable per-request via `useRequest()`). */
+    requestLimits?: Omit<TRequestLimits, 'perRequest'>;
 }
+/** HTTP adapter for Wooks that provides route registration, server lifecycle, and request handling. */
 declare class WooksHttp extends WooksAdapterBase {
     protected opts?: TWooksHttpOptions | undefined;
     protected logger: TConsoleBase;
     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>;
+    /** Registers a GET route handler. */
     get<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers a POST route handler. */
     post<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers a PUT route handler. */
     put<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers a PATCH route handler. */
     patch<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers a DELETE route handler. */
     delete<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers a HEAD route handler. */
     head<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
+    /** Registers an OPTIONS route handler. */
     options<ResType = unknown, ParamsType = Record<string, string | string[]>>(path: string, handler: TWooksHandler<ResType>): wooks.TProstoRouterPathHandle<ParamsType>;
     protected server?: Server;
     /**
@@ -510,11 +604,15 @@ declare class WooksHttp extends WooksAdapterBase {
     protected processHandlers(handlers: TWooksHandler[]): Promise<unknown>;
 }
 /**
- * Factory for WooksHttp App
- * @param opts TWooksHttpOptions
- * @param wooks Wooks | WooksAdapterBase
- * @returns WooksHttp
+ * Creates a new WooksHttp application instance.
+ * @example
+ * ```ts
+ * const app = createHttpApp()
+ * app.get('/hello', () => 'Hello World!')
+ * app.listen(3000)
+ * ```
  */
 declare function createHttpApp(opts?: TWooksHttpOptions, wooks?: Wooks | WooksAdapterBase): WooksHttp;
 
-export { BaseHttpResponse, BaseHttpResponseRenderer, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpErrorRenderer, type TAuthCache, type TCacheControl, type TCookieAttributes, type TCookieAttributesInput, type TCookieHook, type THeaderHook, type THttpContextStore, type THttpEvent, type THttpEventData, type TRequestCache, type TSearchParamsCache, type TSetCookieData, type TStatusHook, type TWooksErrorBody, type TWooksErrorBodyExt, type TWooksHttpOptions, type TWooksResponseRenderer, WooksHttp, WooksURLSearchParams, createHttpApp, createHttpContext, createWooksResponder, httpStatusCodes, renderCacheControl, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useSearchParams, useSetCacheControl, useSetCookie, useSetCookies, useSetHeader, useSetHeaders, useStatus };
+export { BaseHttpResponse, BaseHttpResponseRenderer, DEFAULT_LIMITS, EHttpStatusCode, HttpError, HttpErrorRenderer, WooksHttp, WooksURLSearchParams, createHttpApp, createHttpContext, createWooksResponder, httpStatusCodes, renderCacheControl, useAccept, useAuthorization, useCookies, useHeaders, useHttpContext, useRequest, useResponse, useSearchParams, useSetCacheControl, useSetCookie, useSetCookies, useSetHeader, useSetHeaders, useStatus };
+export type { TAuthCache, TCacheControl, TCookieAttributes, TCookieAttributesInput, TCookieHook, THeaderHook, THttpContextStore, THttpEvent, THttpEventData, TRequestCache, TRequestLimits, TSearchParamsCache, TSetCookieData, TStatusHook, TWooksErrorBody, TWooksErrorBodyExt, TWooksHttpOptions, TWooksResponseRenderer };