Context | /context.ts | oak@v17.1.2

class Context

import { Context } from "https://deno.land/x/oak@v17.1.2/context.ts";

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.

Typically this is only used as a type annotation and shouldn't be constructed directly.

Example

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

const app = new Application();

app.use((ctx) => {
  // information about the request is here:
  ctx.request;
  // information about the response is here:
  ctx.response;
  // the cookie store is here:
  ctx.cookies;
});

// Needs a type annotation because it cannot be inferred.
function mw(ctx: Context) {
  // process here...
}

app.use(mw);

Constructors

new

Context(

app: Application<AS>,

serverRequest: ServerRequest,

state: S,

unnamed 3?: ContextOptions<S, AS>,

)

Type Parameters

optional

S extends AS = State

the state which extends the application state (AS)

optional

AS extends State = Record<string, any>

the type of the state derived from the application

Properties

app: Application<AS>

A reference to the current application.

cookies: SecureCookieMap

An object which allows access to cookies, mediating both the request and response.

readonly

isUpgradable: boolean

Is true if the current connection is upgradeable to a web socket. Otherwise the value is false. Use .upgrade() to upgrade the connection and return the web socket.

request: Request

An object which contains information about the current request.

respond: boolean

Determines if the request should be responded to. If false when the middleware completes processing, the response will not be sent back to the requestor. Typically this is used if the middleware will take over low level processing of requests and responses, for example if using web sockets. This automatically gets set to false when the context is upgraded to a web socket via the .upgrade() method.

The default is true.

response: Response

An object which contains information about the response that will be sent when the middleware finishes processing.

readonly

socket: WebSocket | undefined

If the the current context has been upgraded, then this will be set to with the current web socket, otherwise it is undefined.

state: S

The object to pass state to front-end views. This can be typed by supplying the generic state argument when creating a new app. For example:

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" } });

On each request/response cycle, the context's state is cloned from the application state. This means changes to the context's .state will be dropped when the request drops, but "defaults" can be applied to the application's state. Changes to the application's state though won't be reflected until the next request in the context's state.

Methods

assert(

condition: unknown,

errorStatus?: ErrorStatus,

message?: string,

props?: Record<string, unknown> & Omit<HttpErrorOptions, "status">,

): asserts condition

Asserts the condition and if the condition fails, creates an HTTP error with the provided status (which defaults to 500). The error status by default will be set on the .response.status.

Because of limitation of TypeScript, any assertion type function requires specific type annotations, so the Context type should be used even if it can be inferred from the context.

Example

import { Context, Status } from "jsr:@oak/oak/";

export function mw(ctx: Context) {
  const body = ctx.request.body();
  ctx.assert(body.type === "json", Status.NotAcceptable);
  // process the body and send a response...
}

send(options: ContextSendOptions): Promise<string | undefined>

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

If the options.path is not supplied, the file to be sent will default to this .request.url.pathname.

Requires Deno read permission.

sendEvents(options?: ServerSentEventTargetOptions): Promise<ServerSentEventTarget>

Convert the connection to stream events, resolving with an event target for sending server sent events. Events dispatched on the returned target will be sent to the client and be available in the client's EventSource that initiated the connection.

Invoking this will cause the a response to be sent to the client immediately to initialize the stream of events, and therefore any further changes to the response, like headers will not reach the client.

throw(

errorStatus: ErrorStatus,

message?: string,

props?: Record<string, unknown>,

): never

Create and throw an HTTP Error, which can be used to pass status information which can be caught by other middleware to send more meaningful error messages back to the client. The passed error status will be set on the .response.status by default as well.

upgrade(options?: UpgradeWebSocketOptions): WebSocket

Take the current request and upgrade it to a web socket, resolving with the a web standard WebSocket object. This will set .respond to false. If the socket cannot be upgraded, this method will throw.

[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