API REFERENCE

Middleware

import type { Middleware } from '@rasenganjs/futon';
Middleware type
type Middleware = (
  ctx: Context,
  next: () => Promise<Response>
) => Promise<Response>;

See Custom Middleware for the onion-model execution semantics, and compose() below for how an array of middleware is chained into one.

compose()

function compose(middlewares: Middleware[]): Middleware;

Chains an array of Middleware into a single Middleware using the Koa-style onion model. Calling next() more than once inside a single middleware throws "next() called multiple times".

Built-in Middleware Factories

ExportOptions typeDescription
cors(options?)CORSOptionsCORS headers + preflight handling
logger(options?)LoggerOptionsPer-request logging
bodyParser(options?)BodyParserOptionsContent-Type-aware body parsing
basicAuth(options?)BasicAuthOptionsHTTP Basic Auth
bearerToken(options?)BearerTokenOptionsBearer token extraction/validation
compress(options?)CompressOptionsResponse body compression
requestId(options?)RequestIdOptionsPer-request unique ID
bodyLimit(options)BodyLimitOptionsStreaming request size enforcement

Full usage and defaults for each are covered in Built-in Middleware.

CORSOptions

interface CORSOptions {
  origin?: string | string[]; // default "*"
  methods?: string; // default "GET, POST, PUT, PATCH, DELETE, OPTIONS"
  allowedHeaders?: string; // default "Content-Type, Authorization"
  exposedHeaders?: string;
  credentials?: boolean;
  maxAge?: number;
  optionsStatus?: number; // default 204
}

LoggerOptions / LogEntry

interface LoggerOptions {
  log?: (entry: LogEntry) => void;
  skip?: string[];
  methodPadding?: number; // default 6
}
 
interface LogEntry {
  method: string;
  pathname: string;
  search: string;
  status: number; // 0 if downstream threw
  duration: number; // milliseconds
  size: number | null;
}

BodyParserOptions

interface BodyParserOptions {
  key?: string; // default "body"
  maxSize?: number;
  allowedTypes?: string[];
  skipMultipart?: boolean;
}

BasicAuthOptions

interface BasicAuthOptions {
  stateKey?: string; // default "auth"
  realm?: string; // default "Protected"
  verify?: (username: string, password: string) => boolean | Promise<boolean>;
}

BearerTokenOptions

interface BearerTokenOptions {
  stateKey?: string; // default "token"
  verify?: (token: string) => unknown | Promise<unknown>;
}

CompressOptions

interface CompressOptions {
  threshold?: number; // default 1024 (bytes)
  encodings?: string[]; // default ["br", "gzip", "deflate"]
}

RequestIdOptions

interface RequestIdOptions {
  header?: string; // default "X-Request-Id"
  stateKey?: string; // default "requestId"
  generator?: () => string; // default crypto.randomUUID()
}

BodyLimitOptions

interface BodyLimitOptions {
  maxSize: number; // bytes — required, no default
}
Response
Upload