h3

Version 1.11.1
Published 1 month ago
289 kB
10 dependencies
MIT license

Install

npm i h3

yarn add h3

pnpm add h3

Overview

Minimal H(TTP) framework built for high performance and portability.

Index

Variables

variable appendHeader

const appendHeader: (
    event: H3Event<EventHandlerRequest>,
    name: HTTPHeaderName,
    value: string
) => void;

Alias for appendResponseHeader.

variable appendHeaders

const appendHeaders: (
    event: H3Event<EventHandlerRequest>,
    headers: Record<string, string>
) => void;

Alias for appendResponseHeaders.

variable eventHandler

const eventHandler: {
    <Request extends EventHandlerRequest = EventHandlerRequest, Response = any>(
        handler:
            | EventHandler<Request, Response>
            | EventHandlerObject<Request, Response>
    ): EventHandler<Request, Response>;
    <Request = EventHandlerRequest, Response = any>(
        handler: EventHandler<
            Request extends EventHandlerRequest ? Request : EventHandlerRequest,
            Request extends EventHandlerRequest ? Response : Request
        >
    ): EventHandler<
        Request extends EventHandlerRequest ? Request : EventHandlerRequest,
        Request extends EventHandlerRequest ? Response : Request
    >;
};

variable getHeader

const getHeader: (
    event: H3Event<EventHandlerRequest>,
    name: HTTPHeaderName
) => string;

Alias for getRequestHeader.

variable getHeaders

const getHeaders: (
    event: H3Event<EventHandlerRequest>
) => Partial<Record<HTTPHeaderName, string>>;

Alias for getRequestHeaders.

variable getSessionPromise

const getSessionPromise: Symbol;

variable H3Headers

const H3Headers: {
    new (init?: HeadersInit | undefined): Headers;
    prototype: Headers;
};

Deprecated
Please use native web Headers https://developer.mozilla.org/en-US/docs/Web/API/Headers

variable H3Response

const H3Response: {
    new (
        body?: BodyInit | null | undefined,
        init?: ResponseInit | undefined
    ): Response;
    prototype: Response;
    error(): Response;
    json(data: any, init?: ResponseInit | undefined): Response;
    redirect(url: string | URL, status?: number | undefined): Response;
};

Deprecated
Please use native web Response https://developer.mozilla.org/en-US/docs/Web/API/Response

variable lazyEventHandler

const lazyEventHandler: <T extends LazyEventHandler>(
    factory: T
) => Awaited<ReturnType<T>>;

variable MIMES

const MIMES: { html: string; json: string };

variable setHeader

const setHeader: (
    event: H3Event<EventHandlerRequest>,
    name: HTTPHeaderName,
    value: unknown
) => void;

Alias for setResponseHeader.

variable setHeaders

const setHeaders: (
    event: H3Event<EventHandlerRequest>,
    headers: Partial<Record<HTTPHeaderName, unknown>>
) => void;

Alias for setResponseHeaders.

Functions

function appendCorsHeaders

appendCorsHeaders: (event: H3Event, options: H3CorsOptions) => void;

Append CORS headers to the response.

function appendCorsPreflightHeaders

appendCorsPreflightHeaders: (event: H3Event, options: H3CorsOptions) => void;

Append CORS preflight headers to the response.

function appendResponseHeader

appendResponseHeader: (
    event: H3Event,
    name: HTTPHeaderName,
    value: string
) => void;

Append a response header by name.

function appendResponseHeaders

appendResponseHeaders: (event: H3Event, headers: Record<string, string>) => void;

Append the response headers.

function assertMethod

assertMethod: (
    event: H3Event,
    expected: HTTPMethod | HTTPMethod[],
    allowHead?: boolean
) => void;

Asserts that the incoming request method is of the expected type using isMethod.
If the method is not allowed, it will throw a 405 error with the message "HTTP method is not allowed".

function callNodeListener

callNodeListener: (
    handler: NodeMiddleware,
    req: IncomingMessage,
    res: ServerResponse
) => Promise<unknown>;

function clearResponseHeaders

clearResponseHeaders: (event: H3Event, headerNames?: string[]) => void;

Remove all response headers, or only those specified in the headerNames array.
Parameter event
H3 event
Parameter headerNames
Array of header names to remove

function clearSession

clearSession: (event: H3Event, config: Partial<SessionConfig>) => Promise<void>;

Clear the session data for the current request.

function createApp

createApp: (options?: AppOptions) => App;

Create a new H3 app instance.

function createAppEventHandler

createAppEventHandler: (
    stack: Stack,
    options: AppOptions
) => EventHandler<EventHandlerRequest, Promise<void>>;

function createError

createError: <DataT = unknown>(
    input:
        | string
        | (Partial<H3Error<DataT>> & { status?: number; statusText?: string })
) => H3Error<DataT>;

Creates a new Error that can be used to handle both internal and runtime errors.
Parameter input
The error message or an object containing error properties. {H3Error} - An instance of H3Error.

function createEvent

createEvent: (req: IncomingMessage, res: ServerResponse) => H3Event;

Creates a new H3Event instance from the given Node.js request and response objects.
Parameter req
The NodeIncomingMessage object.
Parameter res
The NodeServerResponse object.
Returns
A new H3Event instance.
See Also
- H3Event

function createEventStream

createEventStream: (event: H3Event, opts?: EventStreamOptions) => EventStream;

Initialize an EventStream instance for creating [server sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)

This function is experimental and might be unstable in some environments.

Example 1

import { createEventStream, sendEventStream } from "h3";

eventHandler((event) => {
  const eventStream = createEventStream(event);

  // Send a message every second
  const interval = setInterval(async () => {
    await eventStream.push("Hello world");
  }, 1000);

  // cleanup the interval and close the stream when the connection is terminated
  eventStream.onClosed(async () => {
    console.log("closing SSE...");
    clearInterval(interval);
    await eventStream.close();
  });

  return eventStream.send();
});

Modifiers

@experimental

function createRouter

createRouter: (opts?: CreateRouterOptions) => Router;

Create a new h3 router instance.

function defaultContentType

defaultContentType: (event: H3Event, type?: string) => void;

Set the response status code and message.

function defineEventHandler

defineEventHandler: {
    <Request extends EventHandlerRequest = EventHandlerRequest, Response = any>(
        handler:
            | EventHandler<Request, Response>
            | EventHandlerObject<Request, Response>
    ): EventHandler<Request, Response>;
    <Request = EventHandlerRequest, Response = any>(
        handler: EventHandler<
            Request extends EventHandlerRequest ? Request : EventHandlerRequest,
            Request extends EventHandlerRequest ? Response : Request
        >
    ): EventHandler<
        Request extends EventHandlerRequest ? Request : EventHandlerRequest,
        Request extends EventHandlerRequest ? Response : Request
    >;
};

function defineLazyEventHandler

defineLazyEventHandler: <T extends LazyEventHandler>(
    factory: T
) => Awaited<ReturnType<T>>;

function defineNodeListener

defineNodeListener: (handler: NodeListener) => NodeListener;

function defineNodeMiddleware

defineNodeMiddleware: (middleware: NodeMiddleware) => NodeMiddleware;

function defineRequestMiddleware

defineRequestMiddleware: <
    Request extends EventHandlerRequest = EventHandlerRequest
>(
    fn: _RequestMiddleware<Request>
) => _RequestMiddleware<Request>;

function defineResponseMiddleware

defineResponseMiddleware: <
    Request extends EventHandlerRequest = EventHandlerRequest
>(
    fn: _ResponseMiddleware<Request>
) => _ResponseMiddleware<Request>;

function defineWebSocket

defineWebSocket: (hooks: Hooks) => Hooks;

Define WebSocket hooks.
See Also
- https://h3.unjs.io/guide/websocket

function defineWebSocketHandler

defineWebSocketHandler: (
    hooks: Hooks
) => EventHandler<EventHandlerRequest, never>;

Define WebSocket event handler.
See Also
- https://h3.unjs.io/guide/websocket

function deleteCookie

deleteCookie: (
    event: H3Event,
    name: string,
    serializeOptions?: CookieSerializeOptions
) => void;

Remove a cookie by name.
Parameter event
H3 event or res passed by h3 handler
Parameter name
Name of the cookie to delete
Parameter serializeOptions
Cookie options
deleteCookie(res, 'SessionId')

function dynamicEventHandler

dynamicEventHandler: (initial?: EventHandler) => DynamicEventHandler;

function fetchWithEvent

fetchWithEvent: <
    T = unknown,
    _R = any,
    F extends (req: RequestInfo | URL, opts?: any) => any = (
        input: URL | RequestInfo,
        init?: RequestInit
    ) => Promise<Response>
>(
    event: H3Event,
    req: RequestInfo | URL,
    init?: RequestInit & { context?: H3EventContext },
    options?: { fetch: F }
) => unknown extends T ? ReturnType<F> : T;

Make a fetch request with the event's context and headers.

function fromNodeMiddleware

fromNodeMiddleware: (handler: NodeListener | NodeMiddleware) => EventHandler;

function fromPlainHandler

fromPlainHandler: (
    handler: PlainHandler
) => EventHandler<EventHandlerRequest, Promise<unknown>>;

Modifiers
- @experimental

function fromWebHandler

fromWebHandler: (
    handler: WebHandler
) => EventHandler<EventHandlerRequest, Promise<Response>>;

Modifiers
- @experimental

function getCookie

getCookie: (event: H3Event, name: string) => string | undefined;

Get a cookie value by name.
Parameter event
H3 event or req passed by h3 handler
Parameter name
Name of the cookie to get
Returns
{*} Value of the cookie (String or undefined)
const authorization = getCookie(request, 'Authorization')

function getMethod

getMethod: (event: H3Event, defaultMethod?: HTTPMethod) => HTTPMethod;

Deprecated
Directly use event.method instead.

function getProxyRequestHeaders

getProxyRequestHeaders: (event: H3Event) => any;

Get the request headers object without headers known to cause issues when proxying.

function getQuery

getQuery: <
    T,
    Event extends H3Event<EventHandlerRequest> = H3Event<EventHandlerRequest>,
    _T = Exclude<InferEventInput<'query', Event, T>, undefined>
>(
    event: Event
) => _T;

Get query the params object from the request URL parsed with [unjs/ufo](https://ufo.unjs.io).

function getRequestFingerprint

getRequestFingerprint: (
    event: H3Event,
    opts?: RequestFingerprintOptions
) => Promise<string | null>;

Get a unique fingerprint for the incoming request.
Behavior of this utility might change in the future versions
Modifiers
- @experimental

function getRequestHeader

getRequestHeader: (
    event: H3Event,
    name: HTTPHeaderName
) => RequestHeaders[string];

Get a request header by name.

function getRequestHeaders

getRequestHeaders: (event: H3Event) => RequestHeaders;

Get the request headers object.
Array headers are joined with a comma.

function getRequestHost

getRequestHost: (event: H3Event, opts?: { xForwardedHost?: boolean }) => string;

Get the request hostname.
If xForwardedHost is true, it will use the x-forwarded-host header if it exists.
If no host header is found, it will default to "localhost".

function getRequestIP

getRequestIP: (
    event: H3Event,
    opts?: { xForwardedFor?: boolean }
) => string | undefined;

Try to get the client IP address from the incoming request.
If xForwardedFor is true, it will use the x-forwarded-for header if it exists.

function getRequestPath

getRequestPath: (event: H3Event) => string;

Deprecated
Use event.path instead

function getRequestProtocol

getRequestProtocol: (
    event: H3Event,
    opts?: { xForwardedProto?: boolean }
) => 'https' | 'http';

Get the request protocol.
If x-forwarded-proto header is set to "https", it will return "https". You can disable this behavior by setting xForwardedProto to false.
If protocol cannot be determined, it will default to "http".

function getRequestURL

getRequestURL: (
    event: H3Event,
    opts?: { xForwardedHost?: boolean; xForwardedProto?: boolean }
) => URL;

Generated the full incoming request URL using getRequestProtocol, getRequestHost and event.path.
If xForwardedHost is true, it will use the x-forwarded-host header if it exists.
If xForwardedProto is false, it will not use the x-forwarded-proto header.

function getRequestWebStream

getRequestWebStream: (event: H3Event) => undefined | ReadableStream;

Captures a stream from a request.
Parameter event
The H3Event object containing the request information.
Returns
Undefined if the request can't transport a payload, otherwise a ReadableStream of the request body.

function getResponseHeader

getResponseHeader: (
    event: H3Event,
    name: HTTPHeaderName
) => ReturnType<H3Event['node']['res']['getHeader']>;

Alias for getResponseHeaders.

function getResponseHeaders

getResponseHeaders: (
    event: H3Event
) => ReturnType<H3Event['node']['res']['getHeaders']>;

Get the response headers object.

function getResponseStatus

getResponseStatus: (event: H3Event) => number;

Get the current response status code.

function getResponseStatusText

getResponseStatusText: (event: H3Event) => string;

Get the current response status message.

function getRouterParam

getRouterParam: (
    event: H3Event,
    name: string,
    opts?: { decode?: boolean }
) => string | undefined;

Get a matched route param by name.

function getRouterParams

getRouterParams: (
    event: H3Event,
    opts?: { decode?: boolean }
) => NonNullable<H3Event['context']['params']>;

Get matched route params.
If decode option is true, it will decode the matched route params using decodeURI.

function getSession

getSession: <T extends SessionDataT = SessionDataT>(
    event: H3Event,
    config: SessionConfig
) => Promise<Session<T>>;

Get the session for the current request.

function getValidatedQuery

getValidatedQuery: <
    T,
    Event extends H3Event<EventHandlerRequest> = H3Event<EventHandlerRequest>,
    _T = InferEventInput<'query', Event, T>
>(
    event: Event,
    validate: ValidateFunction<_T>
) => Promise<_T>;

Get the query param from the request URL parsed with [unjs/ufo](https://ufo.unjs.io) and validated with validate function.

function getValidatedRouterParams

getValidatedRouterParams: <
    T,
    Event extends H3Event<EventHandlerRequest> = H3Event<EventHandlerRequest>,
    _T = InferEventInput<'routerParams', Event, T>
>(
    event: Event,
    validate: ValidateFunction<_T>,
    opts?: { decode?: boolean }
) => Promise<_T>;

Get matched route params and validate with validate function.

function handleCacheHeaders

handleCacheHeaders: (event: H3Event, opts: CacheConditions) => boolean;

Check request caching headers (If-Modified-Since) and add caching headers (Last-Modified, Cache-Control) Note: public cache control will be added by default
Returns
true when cache headers are matching. When true is returned, no reponse should be sent anymore

function handleCors

handleCors: (event: H3Event, options: H3CorsOptions) => boolean;

Handle CORS for the incoming request.
If the incoming request is a CORS preflight request, it will append the CORS preflight headers and send a 204 response.
If return value is true, the request is handled and no further action is needed.

function isCorsOriginAllowed

isCorsOriginAllowed: (
    origin: ReturnType<typeof getRequestHeaders>['origin'],
    options: H3CorsOptions
) => boolean;

Check if the incoming request is a CORS request.

function isError

isError: <DataT = unknown>(input: any) => input is H3Error<DataT>;

Checks if the given input is an instance of H3Error.
Parameter input
The input to check. {boolean} - Returns true if the input is an instance of H3Error, false otherwise.

function isEvent

isEvent: (input: any) => input is H3Event<EventHandlerRequest>;

Checks if the input is an H3Event object.
Parameter input
The input to check.
Returns
True if the input is an H3Event object, false otherwise.
See Also
- H3Event

function isEventHandler

isEventHandler: (input: any) => input is EventHandler<EventHandlerRequest, any>;

Checks if any kind of input is an event handler.
Parameter input
The input to check.
Returns
True if the input is an event handler, false otherwise.

function isMethod

isMethod: (
    event: H3Event,
    expected: HTTPMethod | HTTPMethod[],
    allowHead?: boolean
) => boolean;

Checks if the incoming request method is of the expected type.
If allowHead is true, it will allow HEAD requests to pass if the expected method is GET.

function isPreflightRequest

isPreflightRequest: (event: H3Event) => boolean;

Check if the incoming request is a CORS preflight request.

function isStream

isStream: (data: any) => data is any;

Checks if the data is a stream. (Node.js Readable Stream, React Pipeable Stream, or Web Stream)

function isWebResponse

isWebResponse: (data: any) => data is Response;

Checks if the data is a Response object.

function parseCookies

parseCookies: (event: H3Event) => Record<string, string>;

Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
Parameter event
H3 event or req passed by h3 handler
Returns
Object of cookie name-value pairs
const cookies = parseCookies(event)

function promisifyNodeListener

promisifyNodeListener: (
    handler: NodeListener | NodeMiddleware
) => NodePromisifiedHandler;

function proxyRequest

proxyRequest: (
    event: H3Event,
    target: string,
    opts?: ProxyOptions
) => Promise<any>;

Proxy the incoming request to a target URL.

function readBody

readBody: <
    T,
    Event extends H3Event<EventHandlerRequest> = H3Event<EventHandlerRequest>,
    _T = InferEventInput<'body', Event, T>
>(
    event: Event,
    options?: { strict?: boolean }
) => Promise<_T>;

Reads request body and tries to safely parse using [destr](https://github.com/unjs/destr).
Parameter event
H3 event passed by h3 handler
Parameter encoding
The character encoding to use, defaults to 'utf-8'.
{*} The Object, Array, String, Number, Boolean, or null value corresponding to the request JSON body
Example 1
export default defineEventHandler(async (event) => { const body = await readBody(event); });

function readFormData

readFormData: (event: H3Event) => Promise<FormData>;

Constructs a FormData object from an event, after converting it to a a web request.
Parameter event
The H3Event object to read the form data from.
Example 1
export default defineEventHandler(async (event) => { const formData = await readFormData(event); const email = formData.get("email"); const password = formData.get("password"); });

function readMultipartFormData

readMultipartFormData: (event: H3Event) => Promise<MultiPartData[] | undefined>;

Tries to read and parse the body of a an H3Event as multipart form.
Parameter event
The H3Event object to read multipart form from.
The parsed form data. If no form could be detected because the content type is not multipart/form-data or no boundary could be found.
Example 1
export default defineEventHandler(async (event) => { const formData = await readMultipartFormData(event); // The result could look like: // [ // { // "data": "other", // "name": "baz", // }, // { // "data": "something", // "name": "some-other-data", // }, // ]; });

function readRawBody

readRawBody: <E extends Encoding = 'utf8'>(
    event: H3Event,
    encoding?: E
) => E extends false ? Promise<Buffer | undefined> : Promise<string | undefined>;

Reads body of the request and returns encoded raw string (default), or Buffer if encoding is falsy.
Parameter event
H3 event or req passed by h3 handler
Parameter encoding
encoding="utf-8" - The character encoding to use.
{String|Buffer} Encoded raw string or raw Buffer of the body
Example 1
export default defineEventHandler(async (event) => { const body = await readRawBody(event, "utf-8"); });

function readValidatedBody

readValidatedBody: <
    T,
    Event extends H3Event<EventHandlerRequest> = H3Event<EventHandlerRequest>,
    _T = InferEventInput<'body', Event, T>
>(
    event: Event,
    validate: ValidateFunction<_T>
) => Promise<_T>;

Tries to read the request body via readBody, then uses the provided validation function and either throws a validation error or returns the result.
You can use a simple function to validate the body or use a library like zod to define a schema.
Parameter event
The H3Event passed by the handler.
Parameter validate
The function to use for body validation. It will be called passing the read request body. If the result is not false, the parsed body will be returned.
Throws
If the validation function returns false or throws, a validation error will be thrown. {*} The Object, Array, String, Number, Boolean, or null value corresponding to the request JSON body.
Example 1
export default defineEventHandler(async (event) => { const body = await readValidatedBody(event, (body) => { return typeof body === "object" && body !== null; }); });
Example 2
import { z } from "zod";
export default defineEventHandler(async (event) => { const objectSchema = z.object(); const body = await readValidatedBody(event, objectSchema.safeParse); });
See Also
- {readBody}

function removeResponseHeader

removeResponseHeader: (event: H3Event, name: HTTPHeaderName) => void;

Remove a response header by name.

function sanitizeStatusCode

sanitizeStatusCode: (
    statusCode?: string | number,
    defaultStatusCode?: number
) => number;

Make sure the status code is a valid HTTP status code.

function sanitizeStatusMessage

sanitizeStatusMessage: (statusMessage?: string) => string;

Make sure the status message is safe to use in a response.
Allowed characters: horizontal tabs, spaces or visible ascii characters: https://www.rfc-editor.org/rfc/rfc7230#section-3.1.2

function sealSession

sealSession: <T extends SessionDataT = SessionDataT>(
    event: H3Event,
    config: SessionConfig
) => Promise<string>;

Encrypt and sign the session data for the current request.

function send

send: (event: H3Event, data?: any, type?: string) => Promise<void>;

Directly send a response to the client.
**Note:** This function should be used only when you want to send a response directly without using the h3 event. Normaly you can directly return a value inside event handlers.

function sendError

sendError: (event: H3Event, error: Error | H3Error, debug?: boolean) => void;

Receives an error and returns the corresponding response. H3 internally uses this function to handle unhandled errors. Note that calling this function will close the connection and no other data will be sent to the client afterwards.
Parameter event
H3 event or req passed by h3 handler.
Parameter error
The raised error.
Parameter debug
Whether the application is in debug mode. In the debug mode, the stack trace of errors will be returned in the response.

function sendIterable

sendIterable: <Value = unknown, Return = unknown>(
    event: H3Event,
    iterable: IterationSource<Value, Return>,
    options?: { serializer: IteratorSerializer<Value | Return> }
) => Promise<void>;

Iterate a source of chunks and send back each chunk in order. Supports mixing async work toghether with emitting chunks.
Each chunk must be a string or a buffer.
For generator (yielding) functions, the returned value is treated the same as yielded values.
Parameter event
H3 event
Parameter iterable
Iterator that produces chunks of the response.
Parameter serializer
Function that converts values from the iterable into stream-compatible values. Value - Test
Example 1
sendIterable(event, work()); async function* work() { // Open document body yield "<!DOCTYPE html>\nExecuting...\n"; // Do work ... for (let i = 0; i < 1000) { await delay(1000); // Report progress yield <li>Completed job #; yield i; yield </li>\n; } // Close out the report return </ol></body></html>; } async function delay(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }

function sendNoContent

sendNoContent: (event: H3Event, code?: number) => void;

Respond with an empty payload.
Note that calling this function will close the connection and no other data can be sent to the client afterwards.
Parameter event
H3 event
Parameter code
status code to be send. By default, it is 204 No Content.

function sendProxy

sendProxy: (event: H3Event, target: string, opts?: ProxyOptions) => Promise<any>;

Make a proxy request to a target URL and send the response back to the client.

function sendRedirect

sendRedirect: (event: H3Event, location: string, code?: number) => Promise<void>;

Send a redirect response to the client.
It adds the location header to the response and sets the status code to 302 by default.
In the body, it sends a simple HTML page with a meta refresh tag to redirect the client in case the headers are ignored.

function sendStream

sendStream: (event: H3Event, stream: Readable | ReadableStream) => Promise<void>;

Send a stream response to the client.
Note: You can directly return a stream value inside event handlers alternatively which is recommended.

function sendWebResponse

sendWebResponse: (event: H3Event, response: Response) => void | Promise<void>;

Send a Response object to the client.

function serveStatic

serveStatic: (
    event: H3Event,
    options: ServeStaticOptions
) => Promise<void | false>;

Dynamically serve static assets based on the request path.

function setCookie

setCookie: (
    event: H3Event,
    name: string,
    value: string,
    serializeOptions?: CookieSerializeOptions
) => void;

Set a cookie value by name.
Parameter event
H3 event or res passed by h3 handler
Parameter name
Name of the cookie to set
Parameter value
Value of the cookie to set
Parameter serializeOptions
Options for serializing the cookie
setCookie(res, 'Authorization', '1234567')

function setResponseHeader

setResponseHeader: (
    event: H3Event,
    name: HTTPHeaderName,
    value: Parameters<OutgoingMessage['setHeader']>[1]
) => void;

Set a response header by name.

function setResponseHeaders

setResponseHeaders: (
    event: H3Event,
    headers: Partial<
        Record<HTTPHeaderName, Parameters<OutgoingMessage['setHeader']>[1]>
    >
) => void;

Set the response headers.

function setResponseStatus

setResponseStatus: (event: H3Event, code?: number, text?: string) => void;

Set the response status code and message.

function toEventHandler

toEventHandler: (input: any, _?: any, _route?: string) => EventHandler;

function toNodeListener

toNodeListener: (app: App) => NodeListener;

function toPlainHandler

toPlainHandler: (app: App) => PlainHandler;

Modifiers
- @experimental

function toWebHandler

toWebHandler: (app: App) => WebHandler;

Modifiers
- @experimental

function toWebRequest

toWebRequest: (event: H3Event) => Request;

Convert the H3Event to a WebRequest object.
**NOTE:** This function is not stable and might have edge cases that are not handled properly.

function unsealSession

unsealSession: (
    _event: H3Event,
    config: SessionConfig,
    sealed: string
) => Promise<Partial<Session<SessionDataT>>>;

Decrypt and verify the session data for the current request.

function updateSession

updateSession: <T extends SessionDataT = SessionDataT>(
    event: H3Event,
    config: SessionConfig,
    update?: SessionUpdate<T>
) => Promise<Session<T>>;

Update the session data for the current request.

function use

use: (
    app: App,
    arg1: string | EventHandler | InputLayer | InputLayer[],
    arg2?: Partial<InputLayer> | EventHandler | EventHandler[],
    arg3?: Partial<InputLayer>
) => App;

function useBase

useBase: (base: string, handler: EventHandler) => EventHandler;

Prefixes and executes a handler with a base path.
Parameter base
The base path to prefix. When set to an empty string, the handler will be run as is.
Parameter handler
The event handler to use with the adapted path.
Example 1
const app = createApp(); const router = createRouter();
const apiRouter = createRouter().get( "/hello", defineEventHandler((event) => { return "Hello API!"; }), );
router.use("/api/**", useBase("/api", apiRouter.handler));
app.use(router.handler);

function useSession

useSession: <T extends SessionDataT = SessionDataT>(
    event: H3Event,
    config: SessionConfig
) => Promise<{
    readonly id: string | undefined;
    readonly data: T;
    update: (update: SessionUpdate<T>) => Promise<any>;
    clear: () => Promise<any>;
}>;

Create a session manager for the current request.

function writeEarlyHints

writeEarlyHints: (
    event: H3Event,
    hints: string | string[] | Record<string, string | string[]>,
    cb?: () => void
) => void;

Write HTTP/1.1 103 Early Hints to the client.

Classes

class H3Error

class H3Error<DataT = unknown> extends Error {}

H3 Runtime Error Error {number} statusCode - An integer indicating the HTTP response status code. {string} statusMessage - A string representing the HTTP status message. {boolean} fatal - Indicates if the error is a fatal error. {boolean} unhandled - Indicates if the error was unhandled and auto captured. {DataT} data - An extra data that will be included in the response. This can be used to pass additional information about the error. {boolean} internal - Setting this property to true will mark the error as an internal error.

constructor

constructor(message: string, opts?: { cause?: unknown });

property cause

cause?: {};

property data

data?: {};

property fatal

fatal: boolean;

property statusCode

statusCode: number;

property statusMessage

statusMessage?: string;

property unhandled

unhandled: boolean;

method toJSON

toJSON: () => Pick<
    H3Error<DataT>,
    'data' | 'statusCode' | 'statusMessage' | 'message'
>;

class H3Event

class H3Event<_RequestT extends EventHandlerRequest = EventHandlerRequest>
    implements Pick<FetchEvent, 'respondWith'> {}

constructor

constructor(req: IncomingMessage, res: ServerResponse);

property "__is_event__"

'__is_event__': boolean;

property context

context: H3EventContext;

property handled

readonly handled: boolean;

property headers

readonly headers: Headers;

property method

readonly method: HTTPMethod;

property node

node: NodeEventContext;

property path

readonly path: string;

property req

readonly req: any;

Deprecated
Please use event.node.req instead. *

property res

readonly res: ServerResponse<IncomingMessage>;

Deprecated
Please use event.node.res instead. *

property web

web?: WebEventContext;

method respondWith

respondWith: (response: Response | PromiseLike<Response>) => Promise<void>;

method toJSON

toJSON: () => string;

method toString

toString: () => string;

Interfaces

interface App

interface App {}

property handler

handler: EventHandler;

property options

options: AppOptions;

property resolve

resolve: EventHandlerResolver;

property stack

stack: Stack;

property use

use: AppUse;

property websocket

readonly websocket: WebSocketOptions;

interface AppOptions

interface AppOptions {}

property debug

debug?: boolean;

property onAfterResponse

onAfterResponse?: (
    event: H3Event,
    response?: {
        body?: unknown;
    }
) => void | Promise<void>;

property onBeforeResponse

onBeforeResponse?: (
    event: H3Event,
    response: {
        body?: unknown;
    }
) => void | Promise<void>;

property onError

onError?: (error: H3Error, event: H3Event) => any;

property onRequest

onRequest?: (event: H3Event) => void | Promise<void>;

property websocket

websocket?: WebSocketOptions;

interface AppUse

interface AppUse {}

call signature

(
    route: string | string[],
    handler: EventHandler | EventHandler[],
    options?: Partial<InputLayer>
): App;

call signature

(handler: EventHandler | EventHandler[], options?: Partial<InputLayer>): App;

call signature

(options: InputLayer): App;

interface CacheConditions

interface CacheConditions {}

property cacheControls

cacheControls?: string[];

property etag

etag?: string;

property maxAge

maxAge?: number;

property modifiedTime

modifiedTime?: string | Date;

interface CreateRouterOptions

interface CreateRouterOptions {}

property preemptive

preemptive?: boolean;

property preemtive

preemtive?: boolean;

Deprecated
Please use preemptive instead. *

interface DynamicEventHandler

interface DynamicEventHandler extends EventHandler {}

property set

set: (handler: EventHandler) => void;

interface EventHandler

interface EventHandler<
    Request extends EventHandlerRequest = EventHandlerRequest,
    Response extends EventHandlerResponse = EventHandlerResponse
> {}

call signature

(event: H3Event<Request>): Response;

interface EventHandlerRequest

interface EventHandlerRequest {}

property body

body?: any;

property query

query?: QueryObject;

property routerParams

routerParams?: Record<string, string>;

interface H3CorsOptions

interface H3CorsOptions {}

property allowHeaders

allowHeaders?: '*' | string[];

property credentials

credentials?: boolean;

property exposeHeaders

exposeHeaders?: '*' | string[];

property maxAge

maxAge?: string | false;

property methods

methods?: '*' | HTTPMethod[];

property origin

origin?: '*' | 'null' | (string | RegExp)[] | ((origin: string) => boolean);

property preflight

preflight?: {
    statusCode?: number;
};

interface H3EventContext

interface H3EventContext extends Record<string, any> {}

property clientAddress

clientAddress?: string;

property matchedRoute

matchedRoute?: RouteNode;

Matched router Node
The object structure may change in non-major version.
Modifiers
- @experimental

property params

params?: Record<string, string>;

property sessions

sessions?: Record<string, Session>;

interface InputLayer

interface InputLayer {}

property handler

handler: EventHandler;

property lazy

lazy?: boolean;

property match

match?: Matcher;

property route

route?: string;

interface Layer

interface Layer {}

property handler

handler: EventHandler;

property match

match?: Matcher;

property route

route: string;

interface MultiPartData

interface MultiPartData {}

property data

data: Buffer;

property filename

filename?: string;

property name

name?: string;

property type

type?: string;

interface NodeEventContext

interface NodeEventContext {}

property req

req: IncomingMessage & {
    originalUrl?: string;
};

property res

res: ServerResponse;

interface PlainRequest

interface PlainRequest {}

property body

body?: null | BodyInit;

property context

context?: Record<string, unknown>;

property headers

headers: HeadersInit;

property method

method: string;

property path

path: string;

interface PlainResponse

interface PlainResponse {}

property body

body?: unknown;

property headers

headers: [string, string][];

property status

status: number;

property statusText

statusText: string;

interface ProxyOptions

interface ProxyOptions {}

property cookieDomainRewrite

cookieDomainRewrite?: string | Record<string, string>;

property cookiePathRewrite

cookiePathRewrite?: string | Record<string, string>;

property fetch

fetch?: typeof fetch;

property fetchOptions

fetchOptions?: RequestInit & {
    duplex?: Duplex;
} & {
    ignoreResponseError?: boolean;
};

property headers

headers?: RequestHeaders | HeadersInit;

property onResponse

onResponse?: (event: H3Event, response: Response) => void;

property sendStream

sendStream?: boolean;

property streamRequest

streamRequest?: boolean;

interface RequestFingerprintOptions

interface RequestFingerprintOptions {}

property hash

hash?: false | 'SHA-1';

SHA-1

property ip

ip?: boolean;

true

property method

method?: boolean;

false

property path

path?: boolean;

false

property userAgent

userAgent?: boolean;

false

property xForwardedFor

xForwardedFor?: boolean;

false

interface RouteNode

interface RouteNode {}

property handlers

handlers: Partial<Record<RouterMethod | 'all', EventHandler>>;

property path

path: string;

interface Router

interface Router extends AddRouteShortcuts {}

property add

add: RouterUse;

property handler

handler: EventHandler;

property use

use: RouterUse;

interface ServeStaticOptions

interface ServeStaticOptions {}

property encodings

encodings?: Record<string, string>;

Map of supported encodings (compressions) and their file extensions.
Each extension will be appended to the asset path to find the compressed version of the asset.
Example 1
{ gzip: ".gz", br: ".br" }

property fallthrough

fallthrough?: boolean;

When set to true, the function will not throw 404 error when the asset meta is not found or meta validation failed

property getContents

getContents: (id: string) => unknown | Promise<unknown>;

This function should resolve asset content

property getMeta

getMeta: (
    id: string
) => StaticAssetMeta | undefined | Promise<StaticAssetMeta | undefined>;

This function should resolve asset meta

property indexNames

indexNames?: string[];

Default index file to serve when the path is a directory
["/index.html"]

interface Session

interface Session<T extends SessionDataT = SessionDataT> {}

property [getSessionPromise]

[getSessionPromise]?: Promise<Session<T>>;

property createdAt

createdAt: number;

property data

data: SessionData<T>;

property id

id: string;

interface SessionConfig

interface SessionConfig {}

cookie?: false | CookieSerializeOptions;

Default is secure, httpOnly, /

property crypto

crypto?: Crypto;

property generateId

generateId?: () => string;

Default is Crypto.randomUUID

property maxAge

maxAge?: number;

Session expiration time in seconds

property name

name?: string;

default is h3

property password

password: string;

Private key used to encrypt session tokens

property seal

seal?: SealOptions;

property sessionHeader

sessionHeader?: false | string;

Default is x-h3-session / x-{name}-session

interface StaticAssetMeta

interface StaticAssetMeta {}

property encoding

encoding?: string;

property etag

etag?: string;

property mtime

mtime?: number | string | Date;

property path

path?: string;

property size

size?: number;

property type

type?: string;

interface WebEventContext

interface WebEventContext {}

property request

request?: Request;

property url

url?: URL;

Type Aliases

type AddRouteShortcuts

type AddRouteShortcuts = Record<RouterMethod, RouterUse>;

type Duplex

type Duplex = 'half' | 'full';

type Encoding

type Encoding =
    | false
    | 'ascii'
    | 'utf8'
    | 'utf-8'
    | 'utf16le'
    | 'ucs2'
    | 'ucs-2'
    | 'base64'
    | 'latin1'
    | 'binary'
    | 'hex';

type EventHandlerObject

type EventHandlerObject<
    Request extends EventHandlerRequest = EventHandlerRequest,
    Response extends EventHandlerResponse = EventHandlerResponse
> = {
    onRequest?: _RequestMiddleware<Request> | _RequestMiddleware<Request>[];
    onBeforeResponse?:
        | _ResponseMiddleware<Request, Response>
        | _ResponseMiddleware<Request, Response>[];
    /** @experimental */
    websocket?: Partial<Hooks>;
    handler: EventHandler<Request, Response>;
};

type EventHandlerResolver

type EventHandlerResolver = (path: string) => MaybePromise<
    | undefined
    | {
          route?: string;
          handler: EventHandler;
      }
>;

type EventHandlerResponse

type EventHandlerResponse<T = any> = T | Promise<T>;

type HTTPHeaderName

type HTTPHeaderName = _HTTPHeaderName | Lowercase<_HTTPHeaderName> | (string & {});

type HTTPMethod

type HTTPMethod =
    | 'GET'
    | 'HEAD'
    | 'PATCH'
    | 'POST'
    | 'PUT'
    | 'DELETE'
    | 'CONNECT'
    | 'OPTIONS'
    | 'TRACE';

type InferEventInput

type InferEventInput<
    Key extends keyof EventHandlerRequest,
    Event extends H3Event,
    T
> = void extends T ? (Event extends H3Event<infer E> ? E[Key] : never) : T;

type InputStack

type InputStack = InputLayer[];

type LazyEventHandler

type LazyEventHandler = () => EventHandler | Promise<EventHandler>;

type Matcher

type Matcher = (url: string, event?: H3Event) => boolean;

type NodeListener

type NodeListener = (req: IncomingMessage, res: ServerResponse) => void;

type NodeMiddleware

type NodeMiddleware = (
    req: IncomingMessage,
    res: ServerResponse,
    next: (err?: Error) => any
) => any;

type NodePromisifiedHandler

type NodePromisifiedHandler = (
    req: IncomingMessage,
    res: ServerResponse
) => Promise<any>;

type PlainHandler

type PlainHandler = (request: PlainRequest) => Promise<PlainResponse>;

type RequestHeaders

type RequestHeaders = Partial<Record<HTTPHeaderName, string | undefined>>;

type RouterMethod

type RouterMethod = Lowercase<HTTPMethod>;

type RouterUse

type RouterUse = (
    path: string,
    handler: EventHandler,
    method?: RouterMethod | RouterMethod[]
) => Router;

type SessionData

type SessionData<T extends SessionDataT = SessionDataT> = T;

type Stack

type Stack = Layer[];

type ValidateFunction

type ValidateFunction<T> = (
    data: unknown
) => ValidateResult<T> | Promise<ValidateResult<T>>;

type ValidateResult

type ValidateResult<T> = T | true | false | void;

type WebHandler

type WebHandler = (
    request: Request,
    context?: Record<string, unknown>
) => Promise<Response>;

Modifiers
- @experimental

type WebSocketOptions

type WebSocketOptions = AdapterOptions;

Package Files (1)

dist/index.d.ts

Dependencies (10)

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/h3.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/h3)

HTML

<a href="https://www.jsdocs.io/package/h3"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 1 month ago.
Package analyzed in 6855 ms.
Missing or incorrect documentation? Open an issue for this package.

h3

Install

Overview

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Variables

variable appendHeader

variable appendHeaders

variable eventHandler

variable getHeader

variable getHeaders

variable getSessionPromise

variable H3Headers

Deprecated

variable H3Response

Deprecated

variable lazyEventHandler

variable MIMES

variable setHeader

variable setHeaders

Functions

function appendCorsHeaders

function appendCorsPreflightHeaders

function appendResponseHeader

function appendResponseHeaders

function assertMethod

function callNodeListener

function clearResponseHeaders

Parameter event

Parameter headerNames

function clearSession

function createApp

function createAppEventHandler

function createError

Parameter input

function createEvent

Parameter req

Parameter res

Returns

See Also

function createEventStream

Example 1

Modifiers

function createRouter

function defaultContentType

function defineEventHandler

function defineLazyEventHandler

function defineNodeListener

function defineNodeMiddleware

function defineRequestMiddleware

function defineResponseMiddleware

function defineWebSocket

See Also

function defineWebSocketHandler

See Also

function deleteCookie

Parameter event

Parameter name

Parameter serializeOptions

function dynamicEventHandler

function fetchWithEvent

function fromNodeMiddleware

function fromPlainHandler

Modifiers

function fromWebHandler

Modifiers

function getCookie

Parameter event

Parameter name

Returns

function getMethod

Deprecated

function getProxyRequestHeaders

function getQuery

function getRequestFingerprint

Modifiers