h3

  • Version 0.7.15
  • Published
  • 60.3 kB
  • 4 dependencies
  • MIT license

Install

npm i h3
yarn add h3
pnpm add h3

Overview

Tiny JavaScript Server

Index

Variables

Functions

Classes

Interfaces

Type Aliases

Variables

variable appendHeader

const appendHeader: (event: CompatibilityEvent, name: string, value: string) => void;

    variable appendHeaders

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

      variable eventHandler

      const eventHandler: <T = any>(handler: EventHandler<T>) => EventHandler<T>;

        variable getHeader

        const getHeader: (event: CompatibilityEvent, name: string) => any;

          variable getHeaders

          const getHeaders: (event: CompatibilityEvent) => any;

            variable lazyEventHandler

            const lazyEventHandler: (factory: LazyEventHandler) => EventHandler<any>;

              variable lazyHandle

              const lazyHandle: (handler: LazyHandler, promisify?: boolean) => Handler<any, {}>;
              • Deprecated

                Use defineLazyHandler

              variable MIMES

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

                variable promisifyHandle

                const promisifyHandle: (
                handler: Handler<any, {}> | Middleware
                ) => PromisifiedHandler;
                • Deprecated

                  Use defineHandler

                variable setHeader

                const setHeader: (event: CompatibilityEvent, name: string, value: unknown) => void;

                  variable setHeaders

                  const setHeaders: (
                  event: CompatibilityEvent,
                  headers: Record<string, unknown>
                  ) => void;

                    variable useBody

                    const useBody: <T = any>(event: CompatibilityEvent) => Promise<T>;
                    • Deprecated

                      Use h3.readBody

                    variable useCookie

                    const useCookie: (event: CompatibilityEvent, name: string) => string;
                    • Deprecated

                      Use h3.getCookie

                    variable useCookies

                    const useCookies: (event: CompatibilityEvent) => Record<string, string>;
                    • Deprecated

                      Use h3.parseCookies

                    variable useMethod

                    const useMethod: (
                    event: CompatibilityEvent,
                    defaultMethod?: HTTPMethod
                    ) => HTTPMethod;
                    • Deprecated

                      Use h3.getMethod

                    variable useQuery

                    const useQuery: (event: CompatibilityEvent) => ufo.QueryObject;
                    • Deprecated

                      Use h3.getQuery

                    variable useRawBody

                    const useRawBody: (event: CompatibilityEvent, encoding?: Encoding) => Promise<any>;
                    • Deprecated

                      Use h3.readRawBody

                    Functions

                    function appendResponseHeader

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

                      function appendResponseHeaders

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

                        function assertMethod

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

                          function callHandler

                          callHandler: (
                          handler: Middleware,
                          req: IncomingMessage,
                          res: ServerResponse
                          ) => Promise<unknown>;

                            function createApp

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

                              function createAppEventHandler

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

                                function createError

                                createError: (input: string | Partial<H3Error>) => H3Error;
                                • Creates new Error that can be used to handle both internal and runtime errors.

                                  Parameter input

                                  {H3Error} An instance of the H3Error

                                function createEvent

                                createEvent: (
                                req: http.IncomingMessage,
                                res: http.ServerResponse
                                ) => CompatibilityEvent;

                                  function createRouter

                                  createRouter: () => Router;

                                    function defaultContentType

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

                                      function defineEventHandler

                                      defineEventHandler: <T = any>(handler: EventHandler<T>) => EventHandler<T>;

                                        function defineHandle

                                        defineHandle: <T>(handler: Handler<T, {}>) => Handler<T, {}>;
                                        • Deprecated

                                          Use defineHandler

                                        function defineHandler

                                        defineHandler: <T>(handler: Handler<T, {}>) => Handler<T, {}>;

                                          function defineLazyEventHandler

                                          defineLazyEventHandler: (factory: LazyEventHandler) => EventHandler;

                                            function defineLazyHandler

                                            defineLazyHandler: (handler: LazyHandler, promisify?: boolean) => Handler;

                                              function defineMiddleware

                                              defineMiddleware: (middleware: Middleware) => Middleware;

                                                function deleteCookie

                                                deleteCookie: (
                                                event: CompatibilityEvent,
                                                name: 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 delete

                                                  Parameter serializeOptions

                                                  Cookie options

                                                  deleteCookie(res, 'SessionId')

                                                function dynamicEventHandler

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

                                                  function getCookie

                                                  getCookie: (event: CompatibilityEvent, 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 = useCookie(request, 'Authorization')

                                                  function getMethod

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

                                                    function getQuery

                                                    getQuery: (event: CompatibilityEvent) => ufo.QueryObject;

                                                      function getRequestHeader

                                                      getRequestHeader: (event: CompatibilityEvent, name: string) => any;

                                                        function getRequestHeaders

                                                        getRequestHeaders: (event: CompatibilityEvent) => any;

                                                          function getResponseHeader

                                                          getResponseHeader: (
                                                          event: CompatibilityEvent,
                                                          name: string
                                                          ) => ReturnType<CompatibilityEvent['res']['getHeader']>;

                                                            function getResponseHeaders

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

                                                              function getRouterParam

                                                              getRouterParam: (
                                                              event: CompatibilityEvent,
                                                              name: string
                                                              ) => CompatibilityEvent['context'][string];

                                                                function getRouterParams

                                                                getRouterParams: (event: CompatibilityEvent) => CompatibilityEvent['context'];

                                                                  function handleCacheHeaders

                                                                  handleCacheHeaders: (
                                                                  event: CompatibilityEvent,
                                                                  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 isError

                                                                  isError: (input: any) => input is H3Error;

                                                                    function isEvent

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

                                                                      function isEventHandler

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

                                                                        function isMethod

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

                                                                          function isStream

                                                                          isStream: (data: any) => any;

                                                                            function parseCookies

                                                                            parseCookies: (event: CompatibilityEvent) => 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 promisifyHandler

                                                                            promisifyHandler: (handler: Handler | Middleware) => PromisifiedHandler;

                                                                              function readBody

                                                                              readBody: <T = any>(event: CompatibilityEvent) => Promise<T>;
                                                                              • Reads request body and try to safely parse using [destr](https://github.com/unjs/destr)

                                                                                Parameter event

                                                                                H3 event or req passed by h3 handler

                                                                                Parameter encoding

                                                                                encoding="utf-8" - The character encoding to use.

                                                                                {*} The Object, Array, String, Number, Boolean, or null value corresponding to the request JSON body

                                                                                const body = await useBody(req)

                                                                              function readRawBody

                                                                              readRawBody: (
                                                                              event: CompatibilityEvent,
                                                                              encoding?: Encoding
                                                                              ) => Encoding extends false ? Buffer : Promise<string | Buffer>;
                                                                              • Reads body of the request and returns encoded raw string (default) or Buffer if encoding if 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

                                                                              function send

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

                                                                                function sendError

                                                                                sendError: (
                                                                                event: CompatibilityEvent,
                                                                                error: Error | H3Error,
                                                                                debug?: boolean
                                                                                ) => void;
                                                                                • Receive an error and return 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 client afterwards.

                                                                                  Parameter event

                                                                                  H3 event or req passed by h3 handler

                                                                                  Parameter error

                                                                                  Raised error

                                                                                  Parameter debug

                                                                                  Whether application is in debug mode. In the debug mode the stack trace of errors will be return in response.

                                                                                function sendRedirect

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

                                                                                  function sendStream

                                                                                  sendStream: (event: CompatibilityEvent, data: any) => Promise<void>;

                                                                                    function setCookie

                                                                                    setCookie: (
                                                                                    event: CompatibilityEvent,
                                                                                    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: CompatibilityEvent,
                                                                                    name: string,
                                                                                    value: Parameters<OutgoingMessage['setHeader']>[1]
                                                                                    ) => void;

                                                                                      function setResponseHeaders

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

                                                                                        function toEventHandler

                                                                                        toEventHandler: (handler: CompatibilityEventHandler) => EventHandler;

                                                                                          function use

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

                                                                                            function useBase

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

                                                                                              Classes

                                                                                              class H3Error

                                                                                              class H3Error 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 {String} fatal Indicates if the error is a fatal error. {String} unhandled Indicates if the error was unhandled and auto captured. {Any} data An extra data that will includes in the response. This can be used to pass additional information about the error. {Boolean} internal Setting this property to true will mark error as an internal error

                                                                                              property data

                                                                                              data?: any;

                                                                                                property fatal

                                                                                                fatal: boolean;

                                                                                                  property statusCode

                                                                                                  statusCode: number;

                                                                                                    property statusMessage

                                                                                                    statusMessage: string;

                                                                                                      property unhandled

                                                                                                      unhandled: boolean;

                                                                                                        Interfaces

                                                                                                        interface App

                                                                                                        interface App extends NodeHandler {}

                                                                                                          property handler

                                                                                                          handler: EventHandler;

                                                                                                            property nodeHandler

                                                                                                            nodeHandler: NodeHandler;

                                                                                                              property stack

                                                                                                              stack: Stack;

                                                                                                                property use

                                                                                                                use: AppUse;

                                                                                                                  interface AppOptions

                                                                                                                  interface AppOptions {}

                                                                                                                    property debug

                                                                                                                    debug?: boolean;

                                                                                                                      property onError

                                                                                                                      onError?: (error: Error, event: CompatibilityEvent) => any;

                                                                                                                        interface AppUse

                                                                                                                        interface AppUse {}

                                                                                                                          call signature

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

                                                                                                                            call signature

                                                                                                                            (
                                                                                                                            handler: CompatibilityEventHandler | CompatibilityEventHandler[],
                                                                                                                            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 DynamicEventHandler

                                                                                                                                          interface DynamicEventHandler extends EventHandler {}

                                                                                                                                            property set

                                                                                                                                            set: (handler: EventHandler) => void;

                                                                                                                                              interface EventHandler

                                                                                                                                              interface EventHandler<T = any> {}

                                                                                                                                                property '__is_handler__'

                                                                                                                                                __is_handler__?: true;

                                                                                                                                                  call signature

                                                                                                                                                  (event: CompatibilityEvent): H3Response<T>;

                                                                                                                                                    interface H3Event

                                                                                                                                                    interface H3Event {}

                                                                                                                                                      property '__is_event__'

                                                                                                                                                      __is_event__: true;

                                                                                                                                                        property context

                                                                                                                                                        context: H3EventContext;

                                                                                                                                                          property event

                                                                                                                                                          event: H3Event;

                                                                                                                                                            property req

                                                                                                                                                            req: IncomingMessage;

                                                                                                                                                              property res

                                                                                                                                                              res: ServerResponse;

                                                                                                                                                                interface H3EventContext

                                                                                                                                                                interface H3EventContext extends Record<string, any> {}

                                                                                                                                                                  interface IncomingMessage

                                                                                                                                                                  interface IncomingMessage extends http.IncomingMessage, CompatibilityRequestProps {}

                                                                                                                                                                    property req

                                                                                                                                                                    req: H3Event['req'];

                                                                                                                                                                      property res

                                                                                                                                                                      res: H3Event['res'];

                                                                                                                                                                        interface InputLayer

                                                                                                                                                                        interface InputLayer {}

                                                                                                                                                                          property handle

                                                                                                                                                                          handle?: Handler;
                                                                                                                                                                          • Deprecated

                                                                                                                                                                          property handler

                                                                                                                                                                          handler: Handler | LazyHandler | EventHandler | LazyEventHandler;

                                                                                                                                                                            property lazy

                                                                                                                                                                            lazy?: boolean;

                                                                                                                                                                              property match

                                                                                                                                                                              match?: Matcher;

                                                                                                                                                                                property promisify

                                                                                                                                                                                promisify?: boolean;
                                                                                                                                                                                • Deprecated

                                                                                                                                                                                property route

                                                                                                                                                                                route?: string;

                                                                                                                                                                                  interface Layer

                                                                                                                                                                                  interface Layer {}

                                                                                                                                                                                    property handler

                                                                                                                                                                                    handler: EventHandler;

                                                                                                                                                                                      property match

                                                                                                                                                                                      match?: Matcher;

                                                                                                                                                                                        property route

                                                                                                                                                                                        route: string;

                                                                                                                                                                                          interface Router

                                                                                                                                                                                          interface Router extends AddRouteShortcuts {}

                                                                                                                                                                                            property add

                                                                                                                                                                                            add: RouterUse;

                                                                                                                                                                                              property handler

                                                                                                                                                                                              handler: EventHandler;

                                                                                                                                                                                                property use

                                                                                                                                                                                                use: RouterUse;

                                                                                                                                                                                                  interface ServerResponse

                                                                                                                                                                                                  interface ServerResponse extends http.ServerResponse {}

                                                                                                                                                                                                    property event

                                                                                                                                                                                                    event: H3Event;

                                                                                                                                                                                                      property req

                                                                                                                                                                                                      req: http.ServerResponse['req'] & CompatibilityRequestProps;

                                                                                                                                                                                                        property res

                                                                                                                                                                                                        res: H3Event['res'];

                                                                                                                                                                                                          Type Aliases

                                                                                                                                                                                                          type AddRouteShortcuts

                                                                                                                                                                                                          type AddRouteShortcuts = Record<RouterMethod, RouterUse>;

                                                                                                                                                                                                            type CompatibilityEvent

                                                                                                                                                                                                            type CompatibilityEvent = H3Event | IncomingMessage;

                                                                                                                                                                                                              type CompatibilityEventHandler

                                                                                                                                                                                                              type CompatibilityEventHandler = EventHandler | Handler | Middleware;

                                                                                                                                                                                                                type Encoding

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

                                                                                                                                                                                                                  type H3Response

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

                                                                                                                                                                                                                    type Handler

                                                                                                                                                                                                                    type Handler<T = any, ReqT = {}> = (
                                                                                                                                                                                                                    req: IncomingMessage & ReqT,
                                                                                                                                                                                                                    res: ServerResponse
                                                                                                                                                                                                                    ) => T;

                                                                                                                                                                                                                      type HTTPMethod

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

                                                                                                                                                                                                                        type InputStack

                                                                                                                                                                                                                        type InputStack = InputLayer[];

                                                                                                                                                                                                                          type LazyEventHandler

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

                                                                                                                                                                                                                            type LazyHandler

                                                                                                                                                                                                                            type LazyHandler = () => Handler | Promise<Handler>;

                                                                                                                                                                                                                              type Matcher

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

                                                                                                                                                                                                                                type Middleware

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

                                                                                                                                                                                                                                  type NodeHandler

                                                                                                                                                                                                                                  type NodeHandler = (
                                                                                                                                                                                                                                  req: http.IncomingMessage,
                                                                                                                                                                                                                                  res: http.ServerResponse
                                                                                                                                                                                                                                  ) => Promise<void>;

                                                                                                                                                                                                                                    type PromisifiedHandler

                                                                                                                                                                                                                                    type PromisifiedHandler = Handler<Promise<any>>;

                                                                                                                                                                                                                                      type RouterMethod

                                                                                                                                                                                                                                      type RouterMethod = Lowercase<HTTPMethod>;

                                                                                                                                                                                                                                        type RouterUse

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

                                                                                                                                                                                                                                          type Stack

                                                                                                                                                                                                                                          type Stack = Layer[];

                                                                                                                                                                                                                                            Package Files (1)

                                                                                                                                                                                                                                            Dependencies (4)

                                                                                                                                                                                                                                            Dev Dependencies (19)

                                                                                                                                                                                                                                            Peer Dependencies (0)

                                                                                                                                                                                                                                            No peer dependencies.

                                                                                                                                                                                                                                            Badge

                                                                                                                                                                                                                                            To add a badge like this onejsDocs.io badgeto 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>