Skip to main content

@oak/oak@17.1.0
Built and signed on GitHub Actions

A middleware framework for handling HTTP with Deno, Node.js, Bun and Cloudflare Workers 🐿️🦕🥟⚙️

This package works with Cloudflare Workers, Node.js, Deno, Bun
This package works with Cloudflare Workers
This package works with Node.js
This package works with Deno
This package works with Bun
JSR Score
100%
Published
a week ago (17.1.0)
class Application
extends EventTarget

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

AS extends State = Record<string, any>

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

Properties

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

writeonly
keys:
KeyStack
| Key[]
| undefined
readonly
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.

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

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

[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

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>(): 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.

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>(
...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 });

Add Package

deno add jsr:@oak/oak

Import symbol

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

---- OR ----

Import directly with a jsr specifier

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

Add Package

npx jsr add @oak/oak

Import symbol

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

Add Package

yarn dlx jsr add @oak/oak

Import symbol

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

Add Package

pnpm dlx jsr add @oak/oak

Import symbol

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

Add Package

bunx jsr add @oak/oak

Import symbol

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