Usage

import * as oak from "https://deno.land/x/oak@v11.1.0/mod.ts";

A middleware framework for handling HTTP with Deno.

oak works well on both Deno CLI and Deno deploy, and is inspired by koa. It works well with both the Deno CLI and Deno Deploy.

Example server

A minimal router server which responds with content on /. With Deno CLI this will listen on port 8080 and on Deploy, this will simply serve requests received on the application.

import { Application, Router } from "https://deno.land/x/oak/mod.ts";

const router = new Router();
router.get("/", (ctx) => {
  ctx.response.body = `<!DOCTYPE html>
    <html>
      <head><title>Hello oak!</title><head>
      <body>
        <h1>Hello oak!</h1>
      </body>
    </html>
  `;
});

const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());

app.listen({ port: 8080 });

Using Deno's flash server

Currently, Deno's flash server is not the default, even with the --unstable flag. In order to use the flash server, you need to provide the FlashServer to the Application constructor:

import { Application, FlashServer } from "https://deno.land/x/oak/mod.ts";

const app = new Application({ serverConstructor: FlashServer });

// register middleware

app.listen({ port: 8080 });

Note the currently Deno's flash server requires the --unstable flag. If it isn't present, the application will error on listening.

§Namespaces

etag

A collection of APIs for dealing with ETags in requests and responses.

helpers

A collection of APIs to help assist in creating middleware.

testing

A collection of utility APIs which can make testing of an oak application easier.

§Classes

Application

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

Context

Provides context about the current request and response to middleware functions, and the current instance being processed is the first argument provided a Middleware function.

Cookies

An interface which allows setting and accessing cookies related to both the current request and response. Each Context has a property .cookies which is an instance of this class.

FlashServer

A server abstraction which manages requests from Deno's flash server.

FormDataReader

An interface which provides an interface to access the fields of a multipart/form-data body.

HttpError

The base class that all derivative HTTP extend, providing a status and an expose property.

HttpRequest

An abstraction which wraps a Request from Deno's flash server. The constructor takes a {@link Deferred} which it will resolve when the response is ready.

HttpServerNative

The oak abstraction of the Deno native HTTP server which is used internally for handling native HTTP requests. Generally users of oak do not need to worry about this class.

MultiPartStream

A class that takes a file (either a Deno.FsFile or Uint8Array) and bytes and streams the ranges as a multi-part encoded HTTP body.

NativeRequest

An internal oak abstraction for handling a Deno native request. Most users of oak do not need to worry about this abstraction.

Request

An interface which provides information about the current request. The instance related to the current request is available on the Context's .request property.

Response

An interface to control what response will be sent when the middleware finishes processing the request.

Router

An interface for registering middleware that will run when certain HTTP methods and paths are requested, as well as provides a way to parameterize parts of the requested path.

ServerSentEvent

An event which contains information which will be sent to the remote connection and be made available in an EventSource as an event. A server creates new events and dispatches them on the target which will then be sent to a client.

§Enums

Status

Standard HTTP status codes.

§Variables

httpErrors

A map of HttpErrors that are unique instances for each HTTP error status code.

REDIRECT_BACK

A symbol that indicates to response.redirect() to attempt to redirect back to the request referrer. For example:

STATUS_TEXT

A record of all the status codes text.

testing.mockContextState

Allows external parties to modify the context state.

§Functions

composeMiddleware

Compose multiple middleware functions into a single middleware function.

createHttpError

Create an instance of an HttpError based on the status code provided.

etag.calculate

Calculate an ETag value for an entity. If the entity is FileInfo, then the tag will default to a weak ETag. options.weak overrides any default behavior in generating the tag.

etag.factory

Create middleware that will attempt to decode the response.body into something that can be used to generate an ETag and add the ETag header to the response.

etag.getEntity

For a given Context, try to determine the response body entity that an ETag can be calculated from.

etag.ifMatch

A helper function that takes the value from the If-Match header and an entity and returns true if the ETag for the entity matches the supplied value, otherwise false.

etag.ifNoneMatch

A helper function that takes the value from the If-No-Match header and an entity and returns false if the ETag for the entity matches the supplied value, otherwise false.

hasFlash

A function that determines if the current environment supports Deno flash.

helpers.getQuery

Given a context, return the .request.url.searchParams as a Map of keys and values of the params.

ifRange

Determine, by the value of an If-Range header, if a Range header should be applied to a request, returning true if it should or otherwise false.

isErrorStatus

Determines if a HTTP Status is an ErrorStatus (4XX or 5XX).

isHttpError

A type guard that determines if the value is an HttpError or not.

isRedirectStatus

Determines if a HTTP Status is a RedirectStatus (3XX).

parseRange
proxy

Middleware that provides a back-to-back proxy for requests.

send

Asynchronously fulfill a response with a file from the local file system.

testing.createMockApp

Creates a mock of Application.

testing.createMockContext

Create a mock of Context or RouterContext.

testing.createMockNext

Creates a mock next() function which can be used when calling middleware.

§Interfaces

ApplicationOptions

Available options that are used when creating a new instance of Application.

BodyContentTypes
BodyOptions

Options which can be used when accessing the .body() of a request.

BodyOptionsContentTypes

When setting the contentTypes property of BodyOptions, provide additional content types which can influence how the body is decoded. This is specifically designed to allow a server to support custom or specialized media types that are not part of the public database.

ByteRange
ContextSendOptions
CookiesGetOptions
CookiesSetDeleteOptions
etag.ETagOptions
etag.FileInfo

Just the part of Deno.FileInfo that is required to calculate an ETag, so partial or user generated file information can be passed.

FormDataBody

When reading a body in full via .read() from a FormDataReader this is what is what the value is resolved, providing a split between any fields, and multi-part files that were provided.

FormDataFile

A representation of a file that has been read from a form data body. Based on the FormDataReadOptions that were passed when reading will determine if files are written to disk or not and how they are written to disk. When written to disk, the extension of the file will be determined by the content type, with the .filename property containing the full path to the file.

FormDataReadOptions

Options which impact how the form data is decoded for a FormDataReader. All these options have sensible defaults for most applications, but can be modified for different use cases. Many of these options can have an impact on the stability of a server, especially if there is someone attempting a denial of service attack on your server, so be careful when changing the defaults.

ListenOptionsBase
ListenOptionsTls
Middleware

Middleware are functions which are chained together to deal with requests.

ProxyOptions
Route
RouterAllowedMethodsOptions
RouterContext

The context passed router middleware.

RouterMiddleware
RouterOptions
RouterParamMiddleware

Middleware that will be called by the router when handling a specific parameter, which the middleware will be called when a request matches the route parameter.

SendOptions
ServerConstructor
ServerSentEventInit
ServerSentEventTarget
testing.MockContextOptions

Options that can be set in a mock context.

§Type Aliases

BodyBytes

The tagged type for "bytes" bodies.

BodyForm

The tagged type for "form" bodies.

BodyFormData

The tagged type for "form-data" bodies.

BodyJson

The tagged type for "json" bodies.

BodyReader

The tagged type for "reader" bodies.

BodyStream

The tagged type for "stream" bodies.

BodyText

The tagged type for "text" bodies.

BodyType

The type of the body, where:

BodyUndefined

The tagged type for "undefined" bodies.

ErrorStatus

A HTTP status that is an error (4XX and 5XX).

helpers.GetParamsOptions
HTTPMethods
ListenOptions
RedirectStatus

A HTTP status that is a redirect (3XX).

RouteParams
State