h3

Variables

• appendHeader
• appendHeaders
• eventHandler
• getHeader
• getHeaders
• getSessionPromise
• H3Headers
• H3Response
• lazyEventHandler
• MIMES
• setHeader
• setHeaders

Functions

• appendCorsHeaders()
• appendCorsPreflightHeaders()
• appendResponseHeader()
• appendResponseHeaders()
• assertMethod()
• callNodeListener()
• clearResponseHeaders()
• clearSession()
• createApp()
• createAppEventHandler()
• createError()
• createEvent()
• createEventStream()
• createRouter()
• defaultContentType()
• defineEventHandler()
• defineLazyEventHandler()
• defineNodeListener()
• defineNodeMiddleware()
• defineRequestMiddleware()
• defineResponseMiddleware()
• defineWebSocket()
• defineWebSocketHandler()
• deleteCookie()
• dynamicEventHandler()
• fetchWithEvent()
• fromNodeMiddleware()
• fromPlainHandler()
• fromWebHandler()
• getCookie()
• getMethod()
• getProxyRequestHeaders()
• getQuery()
• getRequestFingerprint()
• getRequestHeader()
• getRequestHeaders()
• getRequestHost()
• getRequestIP()
• getRequestPath()
• getRequestProtocol()
• getRequestURL()
• getRequestWebStream()
• getResponseHeader()
• getResponseHeaders()
• getResponseStatus()
• getResponseStatusText()
• getRouterParam()
• getRouterParams()
• getSession()
• getValidatedQuery()
• getValidatedRouterParams()
• handleCacheHeaders()
• handleCors()
• isCorsOriginAllowed()
• isError()
• isEvent()
• isEventHandler()
• isMethod()
• isPreflightRequest()
• isStream()
• isWebResponse()
• parseCookies()
• promisifyNodeListener()
• proxyRequest()
• readBody()
• readFormData()
• readMultipartFormData()
• readRawBody()
• readValidatedBody()
• removeResponseHeader()
• sanitizeStatusCode()
• sanitizeStatusMessage()
• sealSession()
• send()
• sendError()
• sendIterable()
• sendNoContent()
• sendProxy()
• sendRedirect()
• sendStream()
• sendWebResponse()
• serveStatic()
• setCookie()
• setResponseHeader()
• setResponseHeaders()
• setResponseStatus()
• toEventHandler()
• toNodeListener()
• toPlainHandler()
• toWebHandler()
• toWebRequest()
• unsealSession()
• updateSession()
• use()
• useBase()
• useSession()
• writeEarlyHints()

Classes

• H3Error

  • cause
  • data
  • fatal
  • statusCode
  • statusMessage
  • toJSON()
  • unhandled
• H3Event

  • "__is_event__"
  • context
  • handled
  • headers
  • method
  • node
  • path
  • req
  • res
  • respondWith()
  • toJSON()
  • toString()
  • web

Interfaces

• App

  • handler
  • options
  • resolve
  • stack
  • use
  • websocket
• AppOptions

  • debug
  • onAfterResponse
  • onBeforeResponse
  • onError
  • onRequest
  • websocket
• AppUse
• CacheConditions

  • cacheControls
  • etag
  • maxAge
  • modifiedTime
• CreateRouterOptions

  • preemptive
  • preemtive
• DynamicEventHandler

  • set
• EventHandler
• EventHandlerRequest

  • body
  • query
  • routerParams
• EventStreamMessage

  • data
  • event
  • id
  • retry
• EventStreamOptions

  • autoclose
• H3CorsOptions

  • allowHeaders
  • credentials
  • exposeHeaders
  • maxAge
  • methods
  • origin
  • preflight
• H3EventContext

  • clientAddress
  • matchedRoute
  • params
  • sessions
• InputLayer

  • handler
  • lazy
  • match
  • route
• Layer

  • handler
  • match
  • route
• MultiPartData

  • data
  • filename
  • name
  • type
• NodeEventContext

  • req
  • res
• PlainRequest

  • body
  • context
  • headers
  • method
  • path
• PlainResponse

  • body
  • headers
  • status
  • statusText
• ProxyOptions

  • cookieDomainRewrite
  • cookiePathRewrite
  • fetch
  • fetchOptions
  • headers
  • onResponse
  • sendStream
  • streamRequest
• RequestFingerprintOptions

  • hash
  • ip
  • method
  • path
  • userAgent
  • xForwardedFor
• RouteNode

  • handlers
  • path
• Router

  • add
  • handler
  • use
• ServeStaticOptions

  • encodings
  • fallthrough
  • getContents
  • getMeta
  • indexNames
• Session

  • [getSessionPromise]
  • createdAt
  • data
  • id
• SessionConfig

  • cookie
  • crypto
  • generateId
  • maxAge
  • name
  • password
  • seal
  • sessionHeader
• StaticAssetMeta

  • encoding
  • etag
  • mtime
  • path
  • size
  • type
• WebEventContext

  • request
  • url

Type Aliases

• AddRouteShortcuts
• Duplex
• Encoding
• EventHandlerObject
• EventHandlerResolver
• EventHandlerResponse
• EventStream
• HTTPHeaderName
• HTTPMethod
• InferEventInput
• InputStack
• LazyEventHandler
• Matcher
• MimeType
• NodeListener
• NodeMiddleware
• NodePromisifiedHandler
• PlainHandler
• RequestHeaders
• RouterMethod
• RouterUse
• SessionData
• Stack
• StatusCode
• TypedHeaders
• ValidateFunction
• ValidateResult
• WebHandler
• WebSocketOptions

variable appendHeader

const appendHeader: <T extends HTTPHeaderName>(
    event: H3Event<EventHandlerRequest>,
    name: T,
    value: TypedHeaders[Lowercase<T>]
) => void;

• Alias for appendResponseHeader.

variable appendHeaders

const appendHeaders: (
    event: H3Event<EventHandlerRequest>,
    headers: TypedHeaders
) => 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: { readonly html: 'text/html'; readonly json: 'application/json' };

variable setHeader

const setHeader: <T extends HTTPHeaderName>(
    event: H3Event<EventHandlerRequest>,
    name: T,
    value: TypedHeaders[Lowercase<T>]
) => void;

• Alias for setResponseHeader.

variable setHeaders

const setHeaders: (
    event: H3Event<EventHandlerRequest>,
    headers: TypedHeaders
) => void;

• Alias for setResponseHeaders.

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: <T extends HTTPHeaderName>(
    event: H3Event,
    name: T,
    value: TypedHeaders[Lowercase<T>]
) => void;

• Append a response header by name.

  Example 1

  export default defineEventHandler((event) => { appendResponseHeader(event, "content-type", "text/html"); });

function appendResponseHeaders

appendResponseHeaders: (event: H3Event, headers: TypedHeaders) => void;

• Append the response headers.

  Example 1

  export default defineEventHandler((event) => { appendResponseHeaders(event, { "content-type": "text/html", "cache-control": "no-cache", }); });

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".

  If allowHead is true, it will allow HEAD requests to pass if the expected method is GET.

  Example 1

  export default defineEventHandler((event) => { assertMethod(event, "GET"); // Handle GET request, otherwise throw 405 error });

function callNodeListener

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

function clearResponseHeaders

clearResponseHeaders: (event: H3Event, headerNames?: HTTPHeaderName[]) => 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

  Example 1

  export default defineEventHandler((event) => { clearResponseHeaders(event, ["content-type", "cache-control"]); // Remove content-type and cache-control headers });

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. If a string is provided, it will be used as the error message.

  Remarks

  - Typically, message contains a brief, human-readable description of the error, while statusMessage is specific to HTTP responses and describes the status text related to the response status code. - In a client-server context, using a short statusMessage is recommended because it can be accessed on the client side. Otherwise, a message passed to createError on the server will not propagate to the client. - Consider avoiding putting dynamic user input in the message to prevent potential security issues.

  Example 1

  // String error where statusCode defaults to 500 throw createError("An error occurred"); // Object error throw createError({ statusCode: 400, statusMessage: "Bad Request", message: "Invalid input", data: { field: "email" } });

  {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$1;

• 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?: MimeType) => 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).

  Example 1

  export default defineEventHandler((event) => { const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] } });

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.

  Example 1

  export default defineEventHandler((event) => { const contentType = getRequestHeader(event, "content-type"); // "application/json" });

function getRequestHeaders

getRequestHeaders: (event: H3Event) => RequestHeaders;

• Get the request headers object.

  Array headers are joined with a comma.

  Example 1

  export default defineEventHandler((event) => { const headers = getRequestHeaders(event); // { "content-type": "application/json", "x-custom-header": "value" } });

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".

  Example 1

  export default defineEventHandler((event) => { const host = getRequestHost(event); // "example.com" });

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.

  If IP cannot be determined, it will default to undefined.

  Example 1

  export default defineEventHandler((event) => { const ip = getRequestIP(event); // "192.0.2.0" });

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".

  Example 1

  export default defineEventHandler((event) => { const protocol = getRequestProtocol(event); // "https" });

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.

  Example 1

  export default defineEventHandler((event) => { const url = getRequestURL(event); // "https://example.com/path" });

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.

  Example 1

  export default defineEventHandler((event) => { const contentType = getResponseHeader(event, "content-type"); // Get the response content-type header });

function getResponseHeaders

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

• Get the response headers object.

  Example 1

  export default defineEventHandler((event) => { const headers = getResponseHeaders(event); });

function getResponseStatus

getResponseStatus: (event: H3Event) => number;

• Get the current response status code.

  Example 1

  export default defineEventHandler((event) => { const status = getResponseStatus(event); return Status: ${status}; });

function getResponseStatusText

getResponseStatusText: (event: H3Event) => string;

• Get the current response status message.

  Example 1

  export default defineEventHandler((event) => { const statusText = getResponseStatusText(event); return Status: ${statusText}; });

function getRouterParam

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

• Get a matched route param by name.

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

  Example 1

  export default defineEventHandler((event) => { const param = getRouterParam(event, "key"); });

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.

  Example 1

  export default defineEventHandler((event) => { const params = getRouterParams(event); // { key: "value" } });

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.

  You can use a simple function to validate the query object or a library like zod to define a schema.

  Example 1

  export default defineEventHandler((event) => { const query = getValidatedQuery(event, (data) => { return "key" in data && typeof data.key === "string"; }); });

  Example 2

  import { z } from "zod";

  export default defineEventHandler((event) => { const query = getValidatedQuery( event, z.object({ key: z.string(), }), ); });

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.

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

  You can use a simple function to validate the params object or a library like zod to define a schema.

  Example 1

  export default defineEventHandler((event) => { const params = getValidatedRouterParams(event, (data) => { return "key" in data && typeof data.key === "string"; }); });

  Example 2

  import { z } from "zod";

  export default defineEventHandler((event) => { const params = getValidatedRouterParams( event, z.object({ key: z.string(), }), ); });

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 response 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.

  Example 1

  const app = createApp(); const router = createRouter(); router.use('/', defineEventHandler(async (event) => { const didHandleCors = handleCors(event, { origin: '*', preflight: { statusCode: 204, }, methods: '*', }); if (didHandleCors) { return; } // Your code here }) );

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.

  Example 1

  export default defineEventHandler((event) => { if (isMethod(event, "GET")) { // Handle GET request } else if (isMethod(event, ["POST", "PUT"])) { // Handle POST or PUT request } });

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.

  Example 1

  export default defineEventHandler((event) => { removeResponseHeader(event, "content-type"); // Remove content-type header });

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?: MimeType) => 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. Normally 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 together 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?: StatusCode) => 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.

  Example 1

  export default defineEventHandler((event) => { return sendNoContent(event); });

  Example 2

  export default defineEventHandler((event) => { sendNoContent(event); // Close the connection console.log("This will not be executed"); });

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?: StatusCode
) => 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.

  Example 1

  export default defineEventHandler((event) => { return sendRedirect(event, "https://example.com"); });

  Example 2

  export default defineEventHandler((event) => { return sendRedirect(event, "https://example.com", 301); // Permanent redirect });

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: <T extends HTTPHeaderName>(
    event: H3Event,
    name: T,
    value: TypedHeaders[Lowercase<T>]
) => void;

• Set a response header by name.

  Example 1

  export default defineEventHandler((event) => { setResponseHeader(event, "content-type", "text/html"); });

function setResponseHeaders

setResponseHeaders: (event: H3Event, headers: TypedHeaders) => void;

• Set the response headers.

  Example 1

  export default defineEventHandler((event) => { setResponseHeaders(event, { "content-type": "text/html", "cache-control": "no-cache", }); });

function setResponseStatus

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

• Set the response status code and message.

  Example 1

  export default defineEventHandler((event) => { setResponseStatus(event, 404, "Not Found"); return "Not Found"; });

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.