ShokupanContext

Shokupan Request Context

The context object passed to all middleware and route handlers. Provides access to request data, response helpers, and typed state management.

Examples

app.get('/hello', (ctx) => {
  return ctx.json({ message: 'Hello' });
});

interface AppState {
  userId: string;
  requestId: string;
}

const app = new Shokupan<AppState>();

app.use((ctx, next) => {
  ctx.state.requestId = crypto.randomUUID(); // ✓ Type-safe
  return next();
});

app.get('/users/:userId/posts/:postId', (ctx) => {
  // ctx.params is automatically typed as { userId: string; postId: string }
  const { userId, postId } = ctx.params;
  return ctx.json({ userId, postId });
});

interface RequestState {
  userId: string;
  permissions: string[];
}

const app = new Shokupan<RequestState>();

app.get('/admin/users/:userId', (ctx) => {
  // Both typed!
  const { userId } = ctx.params;        // ✓ From path
  const { permissions } = ctx.state;     // ✓ From state

  if (!permissions.includes('admin')) {
    return ctx.json({ error: 'Forbidden' }, 403);
  }
  return ctx.json({ userId });
});

Type Parameters

State

State extends Record<string, any> = Record<string, any>

The shape of ctx.state for type-safe state access across middleware.

Params

Params extends Record<string, string> = Record<string, string>

The shape of ctx.params based on the route path pattern.

Constructors

Constructor

new ShokupanContext<State, Params>(request, server?, state?, app?, signal?, enableMiddlewareTracking?): ShokupanContext<State, Params>

Defined in: src/context.ts:146

Parameters

request

any

server?

Server

state?

State

app?

Shokupan

signal?

AbortSignal

enableMiddlewareTracking?

boolean = false

Returns

ShokupanContext<State, Params>

Properties

_bodyParseError?

optional _bodyParseError: Error

Defined in: src/context.ts:126

_debug?

optional _debug: DebugCollector

Defined in: src/context.ts:117

_finalResponse?

optional _finalResponse: Response

Defined in: src/context.ts:118

_rawBody?

optional _rawBody: string | ArrayBuffer | Uint8Array<ArrayBufferLike>

Defined in: src/context.ts:119

_routeMatched

_routeMatched: boolean = false

Defined in: src/context.ts:128

app?

readonly optional app: Shokupan

Defined in: src/context.ts:150

handlerStack

handlerStack: HandlerStackItem[] = []

Defined in: src/context.ts:114

params

params: Params

Defined in: src/context.ts:112

request

readonly request: any

Defined in: src/context.ts:147

response

readonly response: ShokupanResponse

Defined in: src/context.ts:116

server?

readonly optional server: Server

Defined in: src/context.ts:148

session

session: SessionData & object

Defined in: src/plugins/middleware/session.ts:294

Type Declaration

id

id: string

destroy()

destroy(callback): void

Parameters

callback

(err) => void

Returns

void

regenerate()

regenerate(callback): void

Parameters

callback

(err) => void

Returns

void

reload()

reload(callback): void

Parameters

callback

(err) => void

Returns

void

save()

save(callback): void

Parameters

callback

(err) => void

Returns

void

touch()

touch(): void

Returns

void

sessionID

sessionID: string

Defined in: src/plugins/middleware/session.ts:295

sessionStore

sessionStore: Store

Defined in: src/plugins/middleware/session.ts:296

signal?

readonly optional signal: AbortSignal

Defined in: src/context.ts:151

state

state: State

Defined in: src/context.ts:113

Accessors

headers

Get Signature

get headers(): any

Defined in: src/context.ts:299

Request headers

Returns

any

host

Get Signature

get host(): string

Defined in: src/context.ts:273

Request host (e.g. “localhost:3000”)

Returns

string

hostname

Get Signature

get hostname(): string

Defined in: src/context.ts:266

Request hostname (e.g. “localhost”)

Returns

string

ip

Get Signature

get ip(): SocketAddress

Defined in: src/context.ts:261

Client IP address

Returns

SocketAddress

method

Get Signature

get method(): any

Defined in: src/context.ts:188

HTTP method

Returns

any

origin

Get Signature

get origin(): string

Defined in: src/context.ts:292

Request origin (e.g. “http://localhost:3000”)

Returns

string

path

Get Signature

get path(): any

Defined in: src/context.ts:192

Request path

Returns

any

protocol

Get Signature

get protocol(): string

Defined in: src/context.ts:280

Request protocol (e.g. “http:”, “https:“)

Returns

string

query

Get Signature

get query(): Record<string, any>

Defined in: src/context.ts:227

Request query params

Returns

Record<string, any>

req

Get Signature

get req(): any

Defined in: src/context.ts:184

Base request

Returns

any

res

Get Signature

get res(): ShokupanResponse

Defined in: src/context.ts:310

Base response object

Returns

ShokupanResponse

secure

Get Signature

get secure(): boolean

Defined in: src/context.ts:287

Whether request is secure (https)

Returns

boolean

url

Get Signature

get url(): URL

Defined in: src/context.ts:172

Returns

URL

Methods

body()

body<T>(): Promise<T>

Defined in: src/context.ts:406

Read request body with caching to avoid double parsing. The body is only parsed once and cached for subsequent reads.

Type Parameters

T

T = any

Returns

Promise<T>

file()

file(path, fileOptions?, responseOptions?): Promise<Response>

Defined in: src/context.ts:663

Respond with a file

Parameters

path

string

fileOptions?

BlobPropertyBag

responseOptions?

ResponseInit

Returns

Promise<Response>

get()

get(name): any

Defined in: src/context.ts:305

Get a request header

Parameters

name

string

Header name

Returns

any

html()

html(html, status?, headers?): Response

Defined in: src/context.ts:612

Respond with HTML content

Parameters

html

string

status?

number

headers?

HeadersInit

Returns

Response

json()

json(data, status?, headers?): Response

Defined in: src/context.ts:551

Respond with a JSON object

Parameters

data

any

status?

number

headers?

HeadersInit

Returns

Response

jsx()

jsx(element, args?, status?, headers?): Promise<Response>

Defined in: src/context.ts:695

Render a JSX element

Parameters

element

any

JSX Element

args?

unknown

status?

number

HTTP Status

headers?

HeadersInit

HTTP Headers

Returns

Promise<Response>

parseBody()

parseBody(): Promise<void>

Defined in: src/context.ts:463

Pre-parse the request body before handler execution. This improves performance and enables Node.js compatibility for large payloads. Errors are deferred until the body is actually accessed in the handler.

Returns

Promise<void>

redirect()

redirect(url, status): Response

Defined in: src/context.ts:633

Respond with a redirect

Parameters

url

string

status

number = 302

Returns

Response

send()

send(body?, options?): Response

Defined in: src/context.ts:530

Send a response

Parameters

body?

BodyInit

Response body

options?

ResponseInit

Response options

Returns

Response

Response

set()

set(key, value): ShokupanContext<State, Params>

Defined in: src/context.ts:317

Helper to set a header on the response

Parameters

key

string

Header key

value

string

Header value

Returns

ShokupanContext<State, Params>

setCookie()

setCookie(name, value, options): ShokupanContext<State, Params>

Defined in: src/context.ts:328

Set a cookie

Parameters

name

string

Cookie name

value

string

Cookie value

options

CookieOptions = {}

Cookie options

Returns

ShokupanContext<State, Params>

setRenderer()

setRenderer(renderer): void

Defined in: src/context.ts:142

Parameters

renderer

JSXRenderer

Returns

void

status()

status(status): Response

Defined in: src/context.ts:649

Respond with a status code DOES NOT CHAIN!

Parameters

status

number

Returns

Response

text()

text(data, status?, headers?): Response

Defined in: src/context.ts:582

Respond with a text string

Parameters

data

string

status?

number

headers?

HeadersInit

Returns

Response