@askrjs/server

createServerApptype

createServerApp: { (router: Router): ServerApp; (options?: ServerAppOptions): ServerApp; }

Creates a transport-neutral server application that dispatches Web Requests to a router's routes and middleware, returning Web Responses. Accepts either a bare {@link Router} or a full {@link ServerAppOptions} object (which may itself reference a router). Builds a path matcher from the combined routes, validates request-size limits, and wraps dispatch with auth resolution, telemetry, and error handling (payload-too-large, malformed path parameters, binding errors, and a fallback onError). Creates a transport-neutral server application. See the {@link Router} overload for details.

const app = createServerApp(router);
export default { fetch: app.fetch };

Handlertype

Handler: {
  bivarianceHack(context: ServerContext<RouteParams>): Response | Promise<Response>;
}["bivarianceHack"]

A route handler function that produces a response for a given {@link ServerContext}.

Middlewaretype

Middleware: {
  bivarianceHack(context: ServerContext<RouteParams>, next: Next): Response | Promise<Response>;
}["bivarianceHack"]

A middleware function that may short-circuit or delegate to next to produce a response.

Nexttype

Next: () => Response | Promise<Response>

Continuation function passed to a {@link Middleware}, invoking the next handler in the chain.

ServerApptype

ServerApp: any

A configured server application, as returned by {@link createServerApp }.

fetch

fetch(request: Request, dispatchOptions?: ServerDispatchOptions): Promise<Response>;

ServerAppOptionstype

ServerAppOptions: any

Options accepted by {@link createServerApp } to configure a server application.

router

router?: Router;

middleware

middleware?: readonly Middleware[];

onError

onError?: (error: unknown, context: ServerContext) => Response | Promise<Response>;

onAccessDenied

onAccessDenied?: AccessDeniedHandler;

auth

auth?: AuthResolver;

fallback

fallback?: Handler;

websocket

websocket?: WebSocketAdapter;

probes

probes?: ProbeOptions;

telemetry

telemetry?: ServerTelemetry;

maxRequestBytes

maxRequestBytes?: number;

ServerContexttype

ServerContext: any

The per-request context passed to handlers and middleware, bundling the incoming request, parsed URL/params/query, auth state, and a family of response-building helper methods (json, ok, notFound, problem, setCookie, upgrade, etc.).

request

request: Request;

url

url: URL;

params

params: RouteParams;

headers

headers: Headers;

query

query: URLSearchParams;

state

state: RequestState;

auth

auth: ServerAuthContext;

signal

signal: AbortSignal;

sse

sse(options?: Omit<EventStreamOptions, "signal">): EventStream;

telemetry

telemetry?: ServerTelemetry;

bind

bind<T extends object = Record<string, unknown>>(): Promise<T>;

json

json(value: JsonValue, init?: ResponseInit): Response;

text

text(value: string, init?: ResponseInit): Response;

redirect

redirect(location: string, status?: 301 | 302 | 303 | 307 | 308): Response;

ok

ok(value?: JsonValue, init?: ResponseInit): Response;

created

created(value?: JsonValue, init?: ResponseInit): Response;

accepted

accepted(value?: JsonValue, init?: ResponseInit): Response;

noContent

noContent(init?: ResponseInit): Response;

badRequest

badRequest(message?: string, init?: ResponseInit): Response;

unauthorized

unauthorized(message?: string, init?: ResponseInit): Response;

forbidden

forbidden(message?: string, init?: ResponseInit): Response;

notFound

notFound(message?: string, init?: ResponseInit): Response;

conflict

conflict(message?: string, init?: ResponseInit): Response;

unprocessableEntity

unprocessableEntity(message?: string, init?: ResponseInit): Response;

tooManyRequests

tooManyRequests(message?: string, init?: ResponseInit): Response;

methodNotAllowed

methodNotAllowed(allow?: string | readonly string[], init?: ResponseInit): Response;

error

error(status?: number, message?: string, init?: ResponseInit): Response;

internalServerError

internalServerError(message?: string, init?: ResponseInit): Response;

notImplemented

notImplemented(message?: string, init?: ResponseInit): Response;

serviceUnavailable

serviceUnavailable(message?: string, init?: ResponseInit): Response;

problem

problem(status: number, detail?: string, options?: ProblemOptions): Response;

challenge

challenge(options?: ChallengeOptions): Response;

setCookie

setCookie(response: Response, name: string, value: string, options?: CookieOptions): Response;

clearCookie

clearCookie(response: Response, name: string, options?: CookieOptions): Response;

upgrade

upgrade(handler: WebSocketHandler): Response | Promise<Response>;

ServerDispatchOptionstype

ServerDispatchOptions: any

Per-request options passed to {@link ServerApp.fetch}.

websocket

websocket?: WebSocketAdapter;

ServerTelemetrytype

ServerTelemetry: any

Telemetry hooks that a {@link ServerAppOptions.telemetry} implementation provides. Each work-wrapping method should run work inside an appropriately named span, propagating its return value.

request

request<T>(fields: ServerTelemetryFields, work: () => T): T;

routeMatch

routeMatch<T>(fields: ServerTelemetryFields, work: () => T): T;

loader

loader?<T>(fields: ServerTelemetryFields, work: () => T): T;

action

action<T>(fields: ServerTelemetryFields, work: () => T): T;

apiOperation

apiOperation<T>(fields: ServerTelemetryFields, work: () => T): T;

queryPrefetch

queryPrefetch?<T>(fields: ServerTelemetryFields, work: () => T): T;

ssrRender

ssrRender?<T>(fields: ServerTelemetryFields, work: () => T): T;

log

log(level: "debug" | "info" | "warn" | "error", event: ServerTelemetryOperation, fields?: ServerTelemetryFields): void;

traceId

traceId(): string | undefined;

extract

extract?<Carrier>(carrier: Carrier, getter: { keys(value: Carrier): string[]; get(value: Carrier, key: string): string | string[] | undefined; }): unknown;

withContext

withContext?<T>(context: unknown, work: () => T): T;

WebSocketAdaptertype

WebSocketAdapter: any

Adapter that performs the transport-specific work of upgrading a request to a WebSocket.

upgrade

upgrade(request: Request, handler: WebSocketHandler, context: ServerContext): Response | Promise<Response>;

WebSocketHandlertype

WebSocketHandler: {
  bivarianceHack(socket: WebSocketLike, context: ServerContext<RouteParams>): void | Promise<void>;
}["bivarianceHack"]

Handler invoked with a live {@link WebSocketLike} once a connection has been upgraded.

WebSocketLiketype

WebSocketLike: any

Transport-neutral interface for an upgraded WebSocket connection.

send

send(data: string | ArrayBufferLike | ArrayBufferView): void;

close

close(code?: number, reason?: string): void;

onMessage

onMessage(listener: (data: string | Uint8Array) => void): () => void;

onClose

onClose(listener: (event: WebSocketCloseEvent) => void): () => void;

onError

onError(listener: (error: unknown) => void): () => void;