ShokupanContext

Defined in: src/context.ts:137

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> = GlobalShokupanState

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?, requestId?): ShokupanContext<State, Params>

Defined in: src/context.ts:240

Parameters

request

any

server?

Server<any>

state?

State

app?

Shokupan<any>

signal?

AbortSignal

enableMiddlewareTracking?

boolean = false

requestId?

string

Returns

ShokupanContext<State, Params>

Properties

[$debug]?

optional [$debug]: DebugCollector

Defined in: src/context.ts:146

---

[$finalResponse]?

optional [$finalResponse]: Response

Defined in: src/context.ts:147

---

[$onWsMessage]()?

optional [$onWsMessage]: (msg) => void

Defined in: src/context.ts:174

Parameters

msg

any

Returns

void

---

[$rawBody]?

optional [$rawBody]: string | ArrayBuffer | Uint8Array<ArrayBufferLike>

Defined in: src/context.ts:148

---

[$routeMatched]

[$routeMatched]: boolean = false

Defined in: src/context.ts:172

---

[$ws]?

optional [$ws]: ServerWebSocket<any>

Defined in: src/context.ts:202

---

[$wsMessages]?

optional [$wsMessages]: any[]

Defined in: src/context.ts:173

---

app?

readonly optional app: Shokupan<any>

Defined in: src/context.ts:244

---

handlerStack

handlerStack: HandlerStackItem[] = []

Defined in: src/context.ts:143

---

isHtmx

isHtmx: boolean

Defined in: src/plugins/application/htmx/index.ts:14

Checks if the request is an HTMX request.

---

isHtmxBoosted

isHtmxBoosted: boolean

Defined in: src/plugins/application/htmx/index.ts:18

Checks if the request is boosting.

---

isUpgraded

isUpgraded: boolean = false

Defined in: src/context.ts:430

---

matchedRoute?

optional matchedRoute: ShokupanRoute

Defined in: src/context.ts:175

---

params

params: Params

Defined in: src/context.ts:141

---

request

readonly request: any

Defined in: src/context.ts:241

---

server?

readonly optional server: Server<any>

Defined in: src/context.ts:242

---

session

session: SessionData & object

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

Type Declaration

id

id: string

destroy()

destroy(): Promise<void>

Returns

Promise<void>

regenerate()

regenerate(): Promise<void>

Returns

Promise<void>

reload()

reload(): Promise<void>

Returns

Promise<void>

save()

save(): Promise<void>

Returns

Promise<void>

touch()

touch(): void

Returns

void

---

sessionID

sessionID: string

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

---

sessionStore

sessionStore: Store

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

---

signal?

readonly optional signal: AbortSignal

Defined in: src/context.ts:245

---

state

state: State

Defined in: src/context.ts:142

Accessors

cookies

Get Signature

get cookies(): Record<string, string>

Defined in: src/context.ts:336

Request cookies

Returns

Record<string, string>

---

headers

Get Signature

get headers(): any

Defined in: src/context.ts:387

Request headers

Returns

any

---

host

Get Signature

get host(): string

Defined in: src/context.ts:361

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

Returns

string

---

hostname

Get Signature

get hostname(): string

Defined in: src/context.ts:354

Request hostname (e.g. “localhost”)

Returns

string

---

io

Get Signature

get io(): Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any> | undefined

Defined in: src/context.ts:418

Socket.io server

Returns

Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any> | undefined

---

ip

Get Signature

get ip(): SocketAddress | null | undefined

Defined in: src/context.ts:349

Client IP address

Returns

SocketAddress | null | undefined

---

logger

Get Signature

get logger(): Logger | undefined

Defined in: src/context.ts:153

Application logger instance

Returns

Logger | undefined

---

method

Get Signature

get method(): any

Defined in: src/context.ts:284

HTTP method

Returns

any

---

nativeStream

Get Signature

get nativeStream(): ReadableStream<Uint8Array<ArrayBufferLike>> | null

Defined in: src/context.ts:721

Exposes the raw, unread incoming ReadableStream of the HTTP request body. Use this if you want to manually process chunks (e.g., custom streaming parsers) without anything being buffered to memory or disk first.

Returns

ReadableStream<Uint8Array<ArrayBufferLike>> | null

---

origin

Get Signature

get origin(): string

Defined in: src/context.ts:380

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

Returns

string

---

path

Get Signature

get path(): any

Defined in: src/context.ts:288

Request path

Returns

any

---

protocol

Get Signature

get protocol(): string

Defined in: src/context.ts:368

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

Returns

string

---

query

Get Signature

get query(): Record<string, any>

Defined in: src/context.ts:323

Request query params

Returns

Record<string, any>

---

req

Get Signature

get req(): any

Defined in: src/context.ts:280

Base request

Returns

any

---

requestBody

Get Signature

get requestBody(): any

Defined in: src/context.ts:701

Gets the parsed request body if it has been read.

Returns

any

---

requestId

Get Signature

get requestId(): string

Defined in: src/context.ts:215

Returns

string

---

res

Get Signature

get res(): ShokupanResponse

Defined in: src/context.ts:398

Base response object

Returns

ShokupanResponse

---

response

Get Signature

get response(): ShokupanResponse

Defined in: src/context.ts:160

Response object (lazy-initialized)

Returns

ShokupanResponse

---

responseBody

Get Signature

get responseBody(): string | ArrayBuffer | Uint8Array<ArrayBufferLike> | undefined

Defined in: src/context.ts:403

Get the raw response body content (if available)

Returns

string | ArrayBuffer | Uint8Array<ArrayBufferLike> | undefined

---

secure

Get Signature

get secure(): boolean

Defined in: src/context.ts:375

Whether request is secure (https)

Returns

boolean

---

socket

Get Signature

get socket(): Socket<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any> | undefined

Defined in: src/context.ts:413

Socket.io socket

Returns

Socket<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any> | undefined

---

url

Get Signature

get url(): URL

Defined in: src/context.ts:268

Returns

URL

---

ws

Get Signature

get ws(): ServerWebSocket<any> | undefined

Defined in: src/context.ts:408

Raw WebSocket connection

Returns

ServerWebSocket<any> | undefined

Methods

body()

body<T>(): Promise<T>

Defined in: src/context.ts:677

Type Parameters

T

T = any

Returns

Promise<T>

---

emit()

emit(event, data?): void

Defined in: src/context.ts:854

Emit an event to the client (WebSocket only)

Parameters

event

string

Event name

data?

any

Event data (Must be JSON serializable)

Returns

void

---

file()

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

Defined in: src/context.ts:1007

Respond with a file

Parameters

path

string

fileOptions?

BlobPropertyBag

responseOptions?

ResponseInit

Returns

Promise<Response>

---

get()

get(name): any

Defined in: src/context.ts:393

Get a request header

Parameters

name

string

Header name

Returns

any

---

html()

html(html, status?, headers?): Promise<Response>

Defined in: src/context.ts:933

Respond with HTML content

Parameters

html

string | Promise<string>

status?

number

headers?

HeadersInit

Returns

Promise<Response>

---

htmxRedirect()

htmxRedirect(url): void

Defined in: src/plugins/application/htmx/index.ts:30

Sets the HX-Redirect header.

Parameters

url

string

Returns

void

---

json()

json(data, status?, headers?): Promise<Response>

Defined in: src/context.ts:865

Respond with a JSON object

Parameters

data

object | Promise<object>

status?

number

headers?

HeadersInit

Returns

Promise<Response>

---

jsx()

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

Defined in: src/context.ts:1069

Render a JSX element

Parameters

element

any

JSX Element

args?

unknown

JSX Element Args/Props

status?

number

HTTP Status

headers?

HeadersInit

HTTP Headers

Returns

Promise<Response>

---

nativeFormData()

nativeFormData(): Promise<FormData>

Defined in: src/context.ts:712

Bypasses the configured maxBodySize and memory buffering, directly invoking the underlying native runtime’s FormData parser.

In Bun, this handles large files by seamlessly backing them up to disk, keeping memory usage extremely low. Use this when handling large file uploads.

Returns

Promise<FormData>

---

onSocketDisconnect()

onSocketDisconnect(callback): void

Defined in: src/context.ts:191

Registers a callback to be executed when the associated WebSocket disconnects. This is only applicable for requests that are part of a WebSocket interaction or upgrade.

Parameters

callback

() => void | Promise<void>

Returns

void

---

parseBody()

parseBody(): Promise<void>

Defined in: src/context.ts:730

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>

---

pipe()

pipe(stream, options?): Response

Defined in: src/context.ts:1089

Pipe a ReadableStream to the response

Parameters

stream

ReadableStream

ReadableStream to pipe

options?

ResponseInit

Response options (status, headers)

Returns

Response

---

pushUrl()

pushUrl(url): void

Defined in: src/plugins/application/htmx/index.ts:26

Sets the HX-Push-Url header.

Parameters

url

string | false

Returns

void

---

redirect()

redirect(url, status): Promise<Response>

Defined in: src/context.ts:955

Respond with a redirect

Parameters

url

string | Promise<string>

status

number = 302

Returns

Promise<Response>

---

refresh()

refresh(): void

Defined in: src/plugins/application/htmx/index.ts:34

Sets the HX-Refresh header.

Returns

void

---

respond()

respond(data, status?, headers?): Promise<Response>

Defined in: src/context.ts:778

Respond with automatic content negotiation Uses Accept header to determine the best response format

Parameters

data

any

Data to respond with

status?

number

HTTP status code

headers?

HeadersInit

Additional headers

Returns

Promise<Response>

---

send()

send(body?, options?): Response

Defined in: src/context.ts:832

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:425

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:603

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:210

Parameters

renderer

JSXRenderer

Returns

void

---

status()

status(statusCode): Promise<Response>

Defined in: src/context.ts:991

Respond with a status code DOES NOT CHAIN!

Parameters

statusCode

number | Promise<number>

Returns

Promise<Response>

---

stream()

stream(callback, onError?): Response

Defined in: src/context.ts:1246

Generic streaming helper for binary/text data

Parameters

callback

(stream) => void | Promise<void>

Callback function that receives a StreamHelper

onError?

StreamErrorHandler

Optional error handler

Returns

Response

---

streamSSE()

streamSSE(callback, onError?): Response

Defined in: src/context.ts:1324

Server-Sent Events (SSE) streaming helper

Parameters

callback

(stream) => void | Promise<void>

Callback function that receives an SSEStreamHelper

onError?

SSEStreamErrorHandler

Optional error handler

Returns

Response

---

streamText()

streamText(callback, onError?): Response

Defined in: src/context.ts:1287

Text streaming helper with proper headers

Parameters

callback

(stream) => void | Promise<void>

Callback function that receives a TextStreamHelper

onError?

TextStreamErrorHandler

Optional error handler

Returns

Response

---

text()

text(data, status?, headers?): Promise<Response>

Defined in: src/context.ts:902

Respond with a text string

Parameters

data

string | Promise<string>

status?

number

headers?

HeadersInit

Returns

Promise<Response>

---

trigger()

trigger(event, options?): void

Defined in: src/plugins/application/htmx/index.ts:22

Sets the HX-Trigger header.

Parameters

event

string | Record<string, any>

options?

after?

"receive" | "settle" | "swap"

Returns

void

---

upgrade()

upgrade(options?): boolean

Defined in: src/context.ts:452

Upgrades the request to a WebSocket connection.

Parameters

options?

Upgrade options or inline WebSocket handlers

[Request, ...options: ([State] extends [undefined] ? [options?: { data?: undefined; headers?: HeadersInit }] : [options: { data: State; headers?: HeadersInit }])[]][1] | InlineWebSocketHandlers<State> & object

Returns

boolean

true if upgraded, false otherwise

This method will link the WebSocket connection to the context object, allowing you to access the connection in your handlers.

Example

app.get('/ws', (ctx) => {
  ctx.upgrade({
    open: (ctx, ws) => ws.send("Connected"),
    message: (ctx, ws, msg) => ws.send(msg),
    close: (ctx, ws) => console.log("Disconnected")
  });
});