Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/oak/application.ts>Application

A middleware framework for handling HTTP with Deno, Node, Bun and Cloudflare Workers 🐿️ 🦕
Very Popular
Latest
class Application
extends EventTarget
import { Application } from "https://deno.land/x/oak@v17.1.2/application.ts";

A class which registers middleware (via .use()) and then processes inbound requests against that middleware (via .listen()).

The context.state can be typed via passing a generic argument when constructing an instance of Application. It can also be inferred by setting the ApplicationOptions.state option when constructing the application.

Basic example

import { Application } from "jsr:@oak/oak/application";

const app = new Application();

app.use((ctx, next) => {
  // called on each request with the context (`ctx`) of the request,
  // response, and other data.
  // `next()` is use to modify the flow control of the middleware stack.
});

app.listen({ port: 8080 });

Constructors

new
Application(options?: ApplicationOptions<AS, ServerRequest>)

Type Parameters

optional
AS extends State = Record<string, any>

the type of the application state which extends State and defaults to a simple string record.

Properties

fetch: CloudflareFetchHandler

A method that is compatible with the Cloudflare Worker Fetch Handler and can be exported to handle Cloudflare Worker fetch requests.

Example

import { Application } from "@oak/oak";

const app = new Application();
app.use((ctx) => {
  ctx.response.body = "hello world!";
});

export default { fetch: app.fetch };
handle: HandleMethod

Handle an individual server request, returning the server response. This is similar to .listen(), but opening the connection and retrieving requests are not the responsibility of the application. If the generated context gets set to not to respond, then the method resolves with undefined, otherwise it resolves with a request that is compatible with std/http/server.

keys: KeyStack | Key[] | undefined

A set of keys, or an instance of KeyStack which will be used to sign cookies read and set by the application to avoid tampering with the cookies.

proxy: boolean

If true, proxy headers will be trusted when processing requests. This defaults to false.

state: AS

Generic state of the application, which can be specified by passing the generic argument when constructing:

  const app = new Application<{ foo: string }>();

Or can be contextually inferred based on setting an initial state object:

  const app = new Application({ state: { foo: "bar" } });

When a new context is created, the application's state is cloned and the state is unique to that request/response. Changes can be made to the application state that will be shared with all contexts.

Methods

addEventListener<S extends AS>(
type: "close",
listener: ApplicationCloseEventListenerOrEventListenerObject | null,
options?: boolean | AddEventListenerOptions,
): void

Add an event listener for a "close" event which occurs when the application is closed and no longer listening or handling requests.

addEventListener<S extends AS>(
type: "error",
listener: ApplicationErrorEventListenerOrEventListenerObject<S, AS> | null,
options?: boolean | AddEventListenerOptions,
): void

Add an event listener for an "error" event which occurs when an un-caught error occurs when processing the middleware or during processing of the response.

addEventListener(
type: "listen",
listener: ApplicationListenEventListenerOrEventListenerObject | null,
options?: boolean | AddEventListenerOptions,
): void

Add an event listener for a "listen" event which occurs when the server has successfully opened but before any requests start being processed.

listen(addr: string): Promise<void>

Start listening for requests, processing registered middleware on each request. If the options .secure is undefined or false, the listening will be over HTTP. If the options .secure property is true, a .certFile and a .keyFile property need to be supplied and requests will be processed over HTTPS.

listen(options?: ListenOptions): Promise<void>

Start listening for requests, processing registered middleware on each request. If the options .secure is undefined or false, the listening will be over HTTP. If the options .secure property is true, a .certFile and a .keyFile property need to be supplied and requests will be processed over HTTPS.

Omitting options will default to { port: 0 } which allows the operating system to select the port.

use<S extends State = AS>(middleware: MiddlewareOrMiddlewareObject<S, Context<S, AS>>, ...middlewares: MiddlewareOrMiddlewareObject<S, Context<S, AS>>[]): Application<S extends AS ? S : (S & AS)>

Register middleware to be used with the application. Middleware will be processed in the order it is added, but middleware can control the flow of execution via the use of the next() function that the middleware function will be called with. The context object provides information about the current state of the application.

Basic usage:

const import { Application } from "jsr:@oak/oak/application";

const app = new Application();

app.use((ctx, next) => {
  ctx.request; // contains request information
  ctx.response; // setups up information to use in the response;
  await next(); // manages the flow control of the middleware execution
});

await app.listen({ port: 80 });
[Symbol.for("Deno.customInspect")](inspect: (value: unknown) => string): string
[Symbol.for("nodejs.util.inspect.custom")](
depth: number,
options: any,
inspect: (value: unknown, options?: unknown) => string,
): any