ShokupanContext

Defined in: src/context.ts:126

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

Defined in: src/context.ts:219

Parameters

request

any

server?

Server<any>

state?

State

app?

Shokupan

signal?

AbortSignal

enableMiddlewareTracking?

boolean = false

requestId?

string

Returns

ShokupanContext<State, Params>

Properties

[$debug]?

optional [$debug]: DebugCollector

Defined in: src/context.ts:135

---

[$finalResponse]?

optional [$finalResponse]: Response

Defined in: src/context.ts:136

---

[$rawBody]?

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

Defined in: src/context.ts:137

---

[$routeMatched]

[$routeMatched]: boolean = false

Defined in: src/context.ts:153

---

app?

readonly optional app: Shokupan

Defined in: src/context.ts:223

---

handlerStack

handlerStack: HandlerStackItem[] = []

Defined in: src/context.ts:132

---

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

---

params

params: Params

Defined in: src/context.ts:130

---

request

readonly request: any

Defined in: src/context.ts:220

---

response

readonly response: ShokupanResponse

Defined in: src/context.ts:134

---

server?

readonly optional server: Server<any>

Defined in: src/context.ts:221

---

session

session: SessionData & object

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

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

---

sessionStore

sessionStore: Store

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

---

signal?

readonly optional signal: AbortSignal

Defined in: src/context.ts:224

---

state

state: State

Defined in: src/context.ts:131

Accessors

cookies

Get Signature

get cookies(): Record<string, string>

Defined in: src/context.ts:316

Request cookies

Returns

Record<string, string>

---

headers

Get Signature

get headers(): any

Defined in: src/context.ts:367

Request headers

Returns

any

---

host

Get Signature

get host(): string

Defined in: src/context.ts:341

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

Returns

string

---

hostname

Get Signature

get hostname(): string

Defined in: src/context.ts:334

Request hostname (e.g. “localhost”)

Returns

string

---

io

Get Signature

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

Defined in: src/context.ts:398

Socket.io server

Returns

Server<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>

---

ip

Get Signature

get ip(): SocketAddress

Defined in: src/context.ts:329

Client IP address

Returns

SocketAddress

---

logger

Get Signature

get logger(): Logger

Defined in: src/context.ts:142

Application logger instance

Returns

Logger

---

method

Get Signature

get method(): any

Defined in: src/context.ts:264

HTTP method

Returns

any

---

nativeStream

Get Signature

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

Defined in: src/context.ts:709

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

---

origin

Get Signature

get origin(): string

Defined in: src/context.ts:360

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

Returns

string

---

path

Get Signature

get path(): any

Defined in: src/context.ts:268

Request path

Returns

any

---

protocol

Get Signature

get protocol(): string

Defined in: src/context.ts:348

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

Returns

string

---

query

Get Signature

get query(): Record<string, any>

Defined in: src/context.ts:303

Request query params

Returns

Record<string, any>

---

req

Get Signature

get req(): any

Defined in: src/context.ts:260

Base request

Returns

any

---

requestId

Get Signature

get requestId(): string

Defined in: src/context.ts:194

Returns

string

---

res

Get Signature

get res(): ShokupanResponse

Defined in: src/context.ts:378

Base response object

Returns

ShokupanResponse

---

responseBody

Get Signature

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

Defined in: src/context.ts:383

Get the raw response body content (if available)

Returns

string | ArrayBuffer | Uint8Array<ArrayBufferLike>

---

secure

Get Signature

get secure(): boolean

Defined in: src/context.ts:355

Whether request is secure (https)

Returns

boolean

---

socket

Get Signature

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

Defined in: src/context.ts:393

Socket.io socket

Returns

Socket<DefaultEventsMap, DefaultEventsMap, DefaultEventsMap, any>

---

url

Get Signature

get url(): URL

Defined in: src/context.ts:248

Returns

URL

---

ws

Get Signature

get ws(): ServerWebSocket<undefined>

Defined in: src/context.ts:388

Raw WebSocket connection

Returns

ServerWebSocket<undefined>

Methods

body()

body<T>(): Promise<T>

Defined in: src/context.ts:672

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>

---

emit()

emit(event, data?): void

Defined in: src/context.ts:843

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

Respond with a file

Parameters

path

string

fileOptions?

BlobPropertyBag

responseOptions?

ResponseInit

Returns

Promise<Response>

---

get()

get(name): any

Defined in: src/context.ts:373

Get a request header

Parameters

name

string

Header name

Returns

any

---

html()

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

Defined in: src/context.ts:922

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

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

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

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

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

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

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

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

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

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

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

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

Parameters

renderer

JSXRenderer

Returns

void

---

status()

status(statusCode): Promise<Response>

Defined in: src/context.ts:977

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

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

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

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

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

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