Summary

Classes

Functions

API Reference

Classes

AppContext

Properties

app: App

request: HttpServer.ServerRequest

response: ServerResponse.ServerResponse

params: Params

query: QueryTable

cookies: { [string]: string | { string } }

Parsed request cookies from the Cookie header.

session: any?

state: { [string]: any }

route: { method: string, path: string }?

mountPath: string?

pathWithinMount: string

originalPath: string

errorStatus: number?

errorData: { [string]: any }?

AppContext:json

AppContext:json() → any

AppContext:form

AppContext:form() → QueryTable?

AppContext:multipart

AppContext:multipart() → { any }?

AppContext:cookie

Returns the first parsed request cookie value by name.

AppContext:cookie(name: string) → string?

AppContext:send

AppContext:send(status: number, body: string?, headers: Headers?) → ()

AppContext:text

AppContext:text(body: string, status: number?, headers: Headers?) → ()

AppContext:html

AppContext:html(body: string, status: number?, headers: Headers?) → ()

AppContext:jsonResponse

AppContext:jsonResponse(data: any, status: number?, headers: Headers?) → ()

AppContext:redirect

AppContext:redirect(location: string, status: number?, headers: Headers?) → ()

AppContext:setCookie

Appends a Set-Cookie response header.

AppContext:setCookie(name: string, value: string, options: CookieOptions?) → ()

AppContext:clearCookie

Clears a cookie with an expired Set-Cookie response header.

AppContext:clearCookie(name: string, options: CookieOptions?) → ()

AppContext:sendFile

Streams a file as the response body.

AppContext:sendFile(path: string, options: SendFileOptions?) → ()

App

Properties

_routes: { Route }

_mounts: { Mount }

_middleware: { Middleware }

_statusHandlers: { RouteHandler }

_exceptionHandler: ExceptionHandler?

_serverOptions: HttpServer.HttpServerOptions?

_server: HttpServer.HttpServer?

state: { [string]: any }

App.new

A higher-level HTTP app/router layer built on top of HttpServer.

Use App.get, App.post, middleware, groups, and mounts to build Flask/FastAPI-style request routing without dropping to the low-level request-handler callback for every endpoint.

App.new(options: HttpServer.HttpServerOptions?) → App

App:route

Registers a route handler for a method/path pair.

App:route(method: string, path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

method: string

HTTP method such as "GET" or "POST".

path: string

Route pattern beginning with /. Supports :param and trailing *splat.

handler: RouteHandler

Request handler for matching requests.

options: RouteOptions?

Optional route metadata such as a route name or route-local middleware.

Returns

App

Self, for chaining.

App:use

Registers middleware that wraps every route and mounted child app.

App:use(middleware: Middleware) → App

Parameters

middleware: Middleware

Middleware callback receiving (ctx, next).

Returns

App

App

App:useSessions

Registers server-side session middleware and exposes ctx.session.

App:useSessions(options: any?) → App

Parameters

options: any?

Session middleware options.

Returns

App

App

App:error

Registers a handler for framework-generated status responses such as 404 or 405.

App:error(status: number, handler: RouteHandler) → App

Parameters

status: number

HTTP status code to intercept.

handler: RouteHandler

Handler that returns the replacement response.

Returns

App

App

App:onError

Registers a catch-all exception handler for uncaught route or middleware errors.

App:onError(handler: ExceptionHandler) → App

Parameters

handler: ExceptionHandler

Recovery handler receiving (ctx, err).

Returns

App

App

App:mount

Mounts another app or router under a URL prefix.

Parent middleware runs before child middleware, and child routes see ctx.mountPath / ctx.pathWithinMount.

App:mount(prefix: string, child: App) → App

Parameters

prefix: string

URL prefix such as "/api".

child: App

Child app/router to mount.

Returns

App

App

App:group

Creates and mounts a child router under a prefix, then optionally configures it.

App:group(prefix: string, configure: (((group: App) → ()))?) → App

Parameters

prefix: string

URL prefix such as "/api".

configure: (((group: App) → ()))?

Optional callback invoked with the new child router.

Returns

App

The new child router.

App:urlFor

Builds a URL for a named route.

App:urlFor(name: string, params: { [string]: any }?, query: { [string]: string | number | boolean | { string | number | boolean } }?) → string

Parameters

name: string

Route name registered through options.name.

params: { [string]: any }?

Optional path parameters to substitute into the route.

query: { [string]: string | number | boolean | { string | number | boolean } }?

Optional query-string parameters to append.

Returns

string

The generated relative URL.

App:static

Mounts a static directory under a URL prefix.

Files are served for GET/HEAD requests only. Requests that attempt path traversal are rejected. When fallthrough is true, missing files continue to later routes instead of immediately returning 404.

App:static(prefix: string, directory: string, options: StaticOptions?) → App

Parameters

prefix: string

URL prefix such as "/assets".

directory: string

Filesystem directory to expose.

options: StaticOptions?

Static file options.

Returns

App

App

App:get

Registers a GET route.

App:get(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:post

Registers a POST route.

App:post(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:put

Registers a PUT route.

App:put(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:delete

Registers a DELETE route.

App:delete(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:patch

Registers a PATCH route.

App:patch(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:head

Registers a HEAD route.

App:head(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:options

Registers an OPTIONS route.

App:options(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:any

Registers a route that matches any method.

App:any(path: string, handler: RouteHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: RouteHandler

Handler for matching requests.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:websocket

Registers a WebSocket endpoint.

App:websocket(path: string, handler: WebSocketHandler, options: RouteOptions?) → App

Parameters

path: string

Route pattern beginning with /.

handler: WebSocketHandler

Handler receiving (ctx, ws) after a successful upgrade.

options: RouteOptions?

Optional route metadata.

Returns

App

App

App:_match

App:_match(requestMethod: string, pathname: string) → MatchResult

App:_execute

App:_execute(request: HttpServer.ServerRequest, response: ServerResponse.ServerResponse, pathname: string, sharedState: { [string]: any }, mountPath: string?) → (AppContext, { any })

App:_handle

App:_handle(request: HttpServer.ServerRequest, response: ServerResponse.ServerResponse) → ()

App:handler

Returns a low-level HttpServer-compatible handler for this app.

App:handler() → ((HttpServer.ServerRequest, ServerResponse.ServerResponse) → ())

Returns

((HttpServer.ServerRequest, ServerResponse.ServerResponse) → ())

(HttpServer.ServerRequest, ServerResponse.ServerResponse) -> ()

App:createServer

Creates a low-level HttpServer that dispatches through this app.

App:createServer(options: HttpServer.HttpServerOptions?) → HttpServer.HttpServer

Parameters

options: HttpServer.HttpServerOptions?

Optional server options overriding app defaults.

Returns

HttpServer.HttpServer

HttpServer

App:listen

Starts listening with this app's handler.

This is a convenience wrapper around App.createServer followed by HttpServer.listen.

App:listen(callback: (((host: string, port: number) → ()))?, options: HttpServer.HttpServerOptions?) → ()

Parameters

callback: (((host: string, port: number) → ()))?

Optional listener-ready callback receiving (host, port).

options: HttpServer.HttpServerOptions?

Optional server options overriding app defaults.

App:close

Closes the underlying server if this app is currently listening.

App:close() → ()

Functions

AppContextMethods:json

AppContextMethods:json() → any

AppContextMethods:form

AppContextMethods:form() → QueryTable?

AppContextMethods:multipart

AppContextMethods:multipart() → { any }?

AppContextMethods:cookie

Returns the first parsed request cookie value for the given cookie name.

AppContextMethods:cookie(name: string) → string?

Parameters

name: string

Cookie name.

Returns

string?

string?

AppContextMethods:send

AppContextMethods:send(status: number, body: string?, headers: Headers?) → ()

AppContextMethods:text

AppContextMethods:text(body: string, status: number?, headers: Headers?) → ()

AppContextMethods:html

AppContextMethods:html(body: string, status: number?, headers: Headers?) → ()

AppContextMethods:jsonResponse

AppContextMethods:jsonResponse(data: any, status: number?, headers: Headers?) → ()

AppContextMethods:redirect

AppContextMethods:redirect(location: string, status: number?, headers: Headers?) → ()

AppContextMethods:setCookie

Appends a Set-Cookie response header.

AppContextMethods:setCookie(name: string, value: string, options: CookieOptions?) → ()

Parameters

name: string

Cookie name.

value: string

Cookie value.

options: CookieOptions?

Cookie attributes.

AppContextMethods:clearCookie

Clears a cookie by setting it to an empty value with an expired timestamp.

AppContextMethods:clearCookie(name: string, options: CookieOptions?) → ()

Parameters

name: string

Cookie name.

options: CookieOptions?

Cookie attributes such as path or domain to target the existing cookie.

AppContextMethods:sendFile

Streams a file as the HTTP response body.

AppContextMethods:sendFile(path: string, options: SendFileOptions?) → ()

Parameters

path: string

Filesystem path to the file.

options: SendFileOptions?

Optional response overrides.

Types

ResponseSpec

status: number?

headers: Headers?

contentType: string?

body: any?

text: string?

html: string?

json: any?

location: string?

RouteOptions

Optional metadata for route registration helpers like App.get.

name: string?

middleware: { Middleware }?

Route-local middleware that runs inside app/group middleware but before the handler.

websocket: any?

WebSocket upgrade options, used by App.websocket.

StaticOptions

Options for App.static.

indexFile: string?

fallthrough: boolean?

headers: Headers?

SendFileOptions

Options for AppContext.sendFile.

contentType: string?

filename: string?

headers: Headers?

status: number?

CookieOptions

Options for setting response cookies from the app layer.

path: string?

domain: string?

expires: number?

maxAge: number?

secure: boolean?

httpOnly: boolean?

sameSite: "Strict" | "Lax" | "None"?

RouteHandler

type RouteHandler = ((ctx: AppContext) → any)

Middleware

type Middleware = ((ctx: AppContext, next: (() → any)) → any)

ExceptionHandler

type ExceptionHandler = ((ctx: AppContext, err: any) → any)

WebSocketHandler

type WebSocketHandler = ((ctx: AppContext, ws: any) → any)