h3 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,54 +1,90 @@
-import { IncomingMessage, ServerResponse } from 'http';
+import http from 'http';
+import { CookieSerializeOptions } from 'cookie-es';
 import * as ufo from 'ufo';
 
-declare type Encoding = false | 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'latin1' | 'binary' | 'hex';
+interface H3Event {
+    '__is_event__': true;
+    event: H3Event;
+    req: IncomingMessage;
+    res: ServerResponse;
+    /**
+     * Request params only filled with h3 Router handlers
+     */
+    params?: Record<string, any>;
+}
+declare type CompatibilityEvent = H3Event | IncomingMessage | ServerResponse;
+declare type _JSONValue<T = string | number | boolean> = T | T[] | Record<string, T>;
+declare type JSONValue = _JSONValue<_JSONValue>;
+declare type H3Response = void | JSONValue | Buffer;
+interface EventHandler {
+    '__is_handler__'?: true;
+    (event: CompatibilityEvent): H3Response | Promise<H3Response>;
+}
+declare function defineEventHandler(handler: EventHandler): EventHandler;
+declare function defineLazyEventHandler(factory: () => EventHandler | Promise<EventHandler>): EventHandler;
+declare function isEventHandler(input: any): input is EventHandler;
+declare type CompatibilityEventHandler = EventHandler | Handler | Middleware;
+declare function toEventHandler(handler: CompatibilityEventHandler): EventHandler;
+declare function createEvent(req: http.IncomingMessage, res: http.ServerResponse): CompatibilityEvent;
+declare function isEvent(input: any): input is H3Event;
 
-declare type Handle<T = any, ReqT = {}> = (req: IncomingMessage & ReqT, res: ServerResponse) => T;
-declare type PHandle = Handle<Promise<any>>;
+interface IncomingMessage extends http.IncomingMessage {
+    originalUrl?: string;
+    event: H3Event;
+    req: H3Event['req'];
+    res: H3Event['res'];
+}
+interface ServerResponse extends http.ServerResponse {
+    event: H3Event;
+    res: H3Event['res'];
+    req: http.ServerResponse['req'] & {
+        event: H3Event;
+        originalUrl?: string;
+    };
+}
+declare type Handler<T = any, ReqT = {}> = (req: IncomingMessage & ReqT, res: ServerResponse) => T;
+declare type PromisifiedHandler = Handler<Promise<any>>;
 declare type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: Error) => any) => any;
-declare type LazyHandle = () => Handle | Promise<Handle>;
-declare const defineHandle: <T>(handler: Handle<T, {}>) => Handle<T, {}>;
-declare const defineMiddleware: (middleware: Middleware) => Middleware;
-declare function promisifyHandle(handle: Handle | Middleware): PHandle;
-declare function callHandle(handle: Middleware, req: IncomingMessage, res: ServerResponse): Promise<unknown>;
-declare function lazyHandle(handle: LazyHandle, promisify?: boolean): PHandle;
-declare function useBase(base: string, handle: PHandle): PHandle;
+declare type LazyHandler = () => Handler | Promise<Handler>;
+declare type Encoding = false | 'ascii' | 'utf8' | 'utf-8' | 'utf16le' | 'ucs2' | 'ucs-2' | 'base64' | 'latin1' | 'binary' | 'hex';
+declare type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE';
 
 interface Layer {
     route: string;
     match?: Matcher;
-    handle: Handle;
+    handler: EventHandler;
 }
 declare type Stack = Layer[];
 interface InputLayer {
     route?: string;
     match?: Matcher;
-    handle: Handle | LazyHandle;
+    handler: Handler | LazyHandler;
     lazy?: boolean;
+    /**
+     * @deprecated
+     */
     promisify?: boolean;
 }
 declare type InputStack = InputLayer[];
-declare type Matcher = (url: string, req?: IncomingMessage) => boolean;
+declare type Matcher = (url: string, event?: CompatibilityEvent) => boolean;
 interface AppUse {
-    (route: string | string[], handle: Middleware | Middleware[], options?: Partial<InputLayer>): App;
-    (route: string | string[], handle: Handle | Handle[], options?: Partial<InputLayer>): App;
-    (handle: Middleware | Middleware[], options?: Partial<InputLayer>): App;
-    (handle: Handle | Handle[], options?: Partial<InputLayer>): App;
+    (route: string | string[], handler: CompatibilityEventHandler | CompatibilityEventHandler[], options?: Partial<InputLayer>): App;
+    (handler: CompatibilityEventHandler | CompatibilityEventHandler[], options?: Partial<InputLayer>): App;
     (options: InputLayer): App;
 }
-interface App {
-    (req: IncomingMessage, res: ServerResponse): Promise<any>;
+declare type NodeHandler = (req: http.IncomingMessage, res: http.ServerResponse) => void | Promise<void>;
+interface App extends NodeHandler {
     stack: Stack;
-    _handle: PHandle;
+    handler: EventHandler;
     use: AppUse;
 }
 interface AppOptions {
     debug?: boolean;
-    onError?: (error: Error, req: IncomingMessage, res: ServerResponse) => any;
+    onError?: (error: Error, event: CompatibilityEvent) => any;
 }
 declare function createApp(options?: AppOptions): App;
-declare function use(app: App, arg1: string | Handle | InputLayer | InputLayer[], arg2?: Handle | Partial<InputLayer> | Handle[] | Middleware | Middleware[], arg3?: Partial<InputLayer>): App;
-declare function createHandle(stack: Stack, options: AppOptions): PHandle;
+declare function use(app: App, arg1: string | Handler | InputLayer | InputLayer[], arg2?: Handler | Partial<InputLayer> | Handler[] | Middleware | Middleware[], arg3?: Partial<InputLayer>): App;
+declare function createAppEventHandler(stack: Stack, options: AppOptions): EventHandler;
 
 /**
  * H3 Runtime Error
@@ -77,30 +113,37 @@ declare function createError(input: Partial<H3Error>): H3Error;
  *  H3 internally uses this function to handle unhandled errors.<br>
  *  Note that calling this function will close the connection and no other data will be sent to client afterwards.
  *
- * @param res {ServerResponse} The ServerResponse object is passed as the second parameter in the handler function
+ @param event {CompatibilityEvent} H3 event or req passed by h3 handler
  * @param error {H3Error|Error} Raised error
  * @param debug {Boolean} Whether application is in debug mode.<br>
  *  In the debug mode the stack trace of errors will be return in response.
  */
-declare function sendError(res: ServerResponse, error: Error | H3Error, debug?: boolean): void;
+declare function sendError(event: CompatibilityEvent, error: Error | H3Error, debug?: boolean): void;
+
+declare const defineHandler: <T>(handler: Handler<T, {}>) => Handler<T, {}>;
+/** @deprecated Use defineHandler */
+declare const defineHandle: <T>(handler: Handler<T, {}>) => Handler<T, {}>;
+declare const defineMiddleware: (middleware: Middleware) => Middleware;
+declare function promisifyHandler(handler: Handler | Middleware): PromisifiedHandler;
+/** @deprecated Use defineHandler */
+declare const promisifyHandle: typeof promisifyHandler;
+declare function callHandler(handler: Middleware, req: IncomingMessage, res: ServerResponse): Promise<unknown>;
+declare function defineLazyHandler(handler: LazyHandler, promisify?: boolean): PromisifiedHandler;
+/** @deprecated Use defineLazyHandler */
+declare const lazyHandle: typeof defineLazyHandler;
+declare function useBase(base: string, handler: PromisifiedHandler): PromisifiedHandler;
 
-declare const RawBodySymbol: unique symbol;
-interface _IncomingMessage extends IncomingMessage {
-    [RawBodySymbol]?: Promise<Buffer>;
-    ParsedBodySymbol?: any;
-    body?: any;
-}
 /**
  * Reads body of the request and returns encoded raw string (default) or `Buffer` if encoding if falsy.
- * @param req {IncomingMessage} An IncomingMessage object is created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param event {CompatibilityEvent} H3 event or req passed by h3 handler
  * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
  *
  * @return {String|Buffer} Encoded raw string or raw Buffer of the body
  */
-declare function useRawBody(req: _IncomingMessage, encoding?: Encoding): Encoding extends false ? Buffer : Promise<string>;
+declare function useRawBody(event: CompatibilityEvent, encoding?: Encoding): Encoding extends false ? Buffer : Promise<string | Buffer>;
 /**
  * Reads request body and try to safely parse using [destr](https://github.com/unjs/destr)
- * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param event {CompatibilityEvent} H3 event or req passed by h3 handler
  * @param encoding {Encoding} encoding="utf-8" - The character encoding to use.
  *
  * @return {*} The `Object`, `Array`, `String`, `Number`, `Boolean`, or `null` value corresponding to the request JSON body
@@ -109,121 +152,35 @@ declare function useRawBody(req: _IncomingMessage, encoding?: Encoding): Encodin
  * const body = await useBody(req)
  * ```
  */
-declare function useBody<T = any>(req: _IncomingMessage): Promise<T>;
+declare function useBody<T = any>(event: CompatibilityEvent): Promise<T>;
 
 declare const MIMES: {
     html: string;
     json: string;
 };
 
-/**
- * Additional serialization options
- */
-interface CookieSerializeOptions {
-    /**
-     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.3|Domain Set-Cookie attribute}. By default, no
-     * domain is set, and most clients will consider the cookie to apply to only
-     * the current domain.
-     */
-    domain?: string;
-    /**
-     * Specifies a function that will be used to encode a cookie's value. Since
-     * value of a cookie has a limited character set (and must be a simple
-     * string), this function can be used to encode a value into a string suited
-     * for a cookie's value.
-     *
-     * The default function is the global `encodeURIComponent`, which will
-     * encode a JavaScript string into UTF-8 byte sequences and then URL-encode
-     * any that fall outside of the cookie range.
-     */
-    encode?(value: string): string;
-    /**
-     * Specifies the `Date` object to be the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.1|`Expires` `Set-Cookie` attribute}. By default,
-     * no expiration is set, and most clients will consider this a "non-persistent cookie" and will delete
-     * it on a condition like exiting a web browser application.
-     *
-     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
-     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
-     * possible not all clients by obey this, so if both are set, they should
-     * point to the same date and time.
-     */
-    expires?: Date;
-    /**
-     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.6|`HttpOnly` `Set-Cookie` attribute}.
-     * When truthy, the `HttpOnly` attribute is set, otherwise it is not. By
-     * default, the `HttpOnly` attribute is not set.
-     *
-     * *Note* be careful when setting this to true, as compliant clients will
-     * not allow client-side JavaScript to see the cookie in `document.cookie`.
-     */
-    httpOnly?: boolean;
-    /**
-     * Specifies the number (in seconds) to be the value for the `Max-Age`
-     * `Set-Cookie` attribute. The given number will be converted to an integer
-     * by rounding down. By default, no maximum age is set.
-     *
-     * *Note* the {@link https://tools.ietf.org/html/rfc6265#section-5.3|cookie storage model specification}
-     * states that if both `expires` and `maxAge` are set, then `maxAge` takes precedence, but it is
-     * possible not all clients by obey this, so if both are set, they should
-     * point to the same date and time.
-     */
-    maxAge?: number;
-    /**
-     * Specifies the value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.4|`Path` `Set-Cookie` attribute}.
-     * By default, the path is considered the "default path".
-     */
-    path?: string;
-    /**
-     * Specifies the boolean or string to be the value for the {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|`SameSite` `Set-Cookie` attribute}.
-     *
-     * - `true` will set the `SameSite` attribute to `Strict` for strict same
-     * site enforcement.
-     * - `false` will not set the `SameSite` attribute.
-     * - `'lax'` will set the `SameSite` attribute to Lax for lax same site
-     * enforcement.
-     * - `'strict'` will set the `SameSite` attribute to Strict for strict same
-     * site enforcement.
-     *  - `'none'` will set the SameSite attribute to None for an explicit
-     *  cross-site cookie.
-     *
-     * More information about the different enforcement levels can be found in {@link https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7|the specification}.
-     *
-     * *note* This is an attribute that has not yet been fully standardized, and may change in the future. This also means many clients may ignore this attribute until they understand it.
-     */
-    sameSite?: true | false | 'lax' | 'strict' | 'none';
-    /**
-     * Specifies the boolean value for the {@link https://tools.ietf.org/html/rfc6265#section-5.2.5|`Secure` `Set-Cookie` attribute}. When truthy, the
-     * `Secure` attribute is set, otherwise it is not. By default, the `Secure` attribute is not set.
-     *
-     * *Note* be careful when setting this to `true`, as compliant clients will
-     * not send the cookie back to the server in the future if the browser does
-     * not have an HTTPS connection.
-     */
-    secure?: boolean;
-}
-
 /**
  * Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
- * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param event {CompatibilityEvent} H3 event or req passed by h3 handler
  * @returns Object of cookie name-value pairs
  * ```ts
  * const cookies = useCookies(req)
  * ```
  */
-declare function useCookies(req: IncomingMessage): Record<string, string>;
+declare function useCookies(event: CompatibilityEvent): Record<string, string>;
 /**
  * Get a cookie value by name.
- * @param req {IncomingMessage} An IncomingMessage object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param event {CompatibilityEvent} H3 event or req passed by h3 handler
  * @param name Name of the cookie to get
  * @returns {*} Value of the cookie (String or undefined)
  * ```ts
  * const authorization = useCookie(request, 'Authorization')
  * ```
  */
-declare function useCookie(req: IncomingMessage, name: string): string | undefined;
+declare function useCookie(event: CompatibilityEvent, name: string): string | undefined;
 /**
  * Set a cookie value by name.
- * @param res {ServerResponse} A ServerResponse object created by [http.Server](https://nodejs.org/api/http.html#http_class_http_server)
+ * @param event {CompatibilityEvent} H3 event or res passed by h3 handler
  * @param name Name of the cookie to set
  * @param value Value of the cookie to set
  * @param serializeOptions {CookieSerializeOptions} Options for serializing the cookie
@@ -231,30 +188,38 @@ declare function useCookie(req: IncomingMessage, name: string): string | undefin
  * setCookie(res, 'Authorization', '1234567')
  * ```
  */
-declare function setCookie(res: ServerResponse, name: string, value: string, serializeOptions?: CookieSerializeOptions): void;
-
-declare type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE';
+declare function setCookie(event: CompatibilityEvent, name: string, value: string, serializeOptions?: CookieSerializeOptions): void;
+/**
+ * Set a cookie value by name.
+ * @param event {CompatibilityEvent} H3 event or res passed by h3 handler
+ * @param name Name of the cookie to delete
+ * @param serializeOptions {CookieSerializeOptions} Cookie options
+ * ```ts
+ * deleteCookie(res, 'SessionId')
+ * ```
+ */
+declare function deleteCookie(event: CompatibilityEvent, name: string, serializeOptions?: CookieSerializeOptions): void;
 
-declare function useQuery(req: IncomingMessage): ufo.QueryObject;
-declare function useMethod(req: IncomingMessage, defaultMethod?: HTTPMethod): HTTPMethod;
-declare function isMethod(req: IncomingMessage, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): boolean;
-declare function assertMethod(req: IncomingMessage, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
+declare function useQuery(event: CompatibilityEvent): ufo.QueryObject;
+declare function useMethod(event: CompatibilityEvent, defaultMethod?: HTTPMethod): HTTPMethod;
+declare function isMethod(event: CompatibilityEvent, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): boolean;
+declare function assertMethod(event: CompatibilityEvent, expected: HTTPMethod | HTTPMethod[], allowHead?: boolean): void;
 
-declare function send(res: ServerResponse, data: any, type?: string): Promise<unknown>;
-declare function defaultContentType(res: ServerResponse, type?: string): void;
-declare function sendRedirect(res: ServerResponse, location: string, code?: number): Promise<unknown>;
-declare function appendHeader(res: ServerResponse, name: string, value: string): void;
+declare function send(event: CompatibilityEvent, data: any, type?: string): Promise<void>;
+declare function defaultContentType(event: CompatibilityEvent, type?: string): void;
+declare function sendRedirect(event: CompatibilityEvent, location: string, code?: number): Promise<void>;
+declare function appendHeader(event: CompatibilityEvent, name: string, value: string): void;
+declare function isStream(data: any): any;
+declare function sendStream(event: CompatibilityEvent, data: any): Promise<void>;
 
 declare type RouterMethod = Lowercase<HTTPMethod>;
-declare type HandleWithParams = Handle<any, {
-    params: Record<string, string>;
-}>;
-declare type AddWithMethod = (path: string, handle: HandleWithParams) => Router;
-declare type AddRouteShortcuts = Record<Lowercase<HTTPMethod>, AddWithMethod>;
+declare type RouterUse = (path: string, handler: CompatibilityEventHandler, method?: RouterMethod) => Router;
+declare type AddRouteShortcuts = Record<RouterMethod, RouterUse>;
 interface Router extends AddRouteShortcuts {
-    add: (path: string, handle: HandleWithParams, method?: RouterMethod | 'all') => Router;
-    handle: Handle;
+    add: RouterUse;
+    use: RouterUse;
+    handler: EventHandler;
 }
 declare function createRouter(): Router;
 
-export { AddRouteShortcuts, AddWithMethod, App, AppOptions, AppUse, H3Error, Handle, HandleWithParams, InputLayer, InputStack, Layer, LazyHandle, MIMES, Matcher, Middleware, PHandle, Router, RouterMethod, Stack, appendHeader, assertMethod, callHandle, createApp, createError, createHandle, createRouter, defaultContentType, defineHandle, defineMiddleware, isMethod, lazyHandle, promisifyHandle, send, sendError, sendRedirect, setCookie, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };
+export { AddRouteShortcuts, App, AppOptions, AppUse, CompatibilityEvent, CompatibilityEventHandler, EventHandler, H3Error, H3Event, H3Response, InputLayer, InputStack, JSONValue, Layer, MIMES, Matcher, NodeHandler, Router, RouterMethod, RouterUse, Stack, _JSONValue, appendHeader, assertMethod, callHandler, createApp, createAppEventHandler, createError, createEvent, createRouter, defaultContentType, defineEventHandler, defineHandle, defineHandler, defineLazyEventHandler, defineLazyHandler, defineMiddleware, deleteCookie, isEvent, isEventHandler, isMethod, isStream, lazyHandle, promisifyHandle, promisifyHandler, send, sendError, sendRedirect, sendStream, setCookie, toEventHandler, use, useBase, useBody, useCookie, useCookies, useMethod, useQuery, useRawBody };