Context (`ctx`)

The Context object (ctx) is the central interface for handling HTTP requests in Jetpath. It provides:

Access to request data (body, query, params)
Tools for crafting responses
Integration with plugins and validation
State management for the request lifecycle

Usage Examples

Basic Request

// Basic route handler
export const GET_user = async (ctx) => {
  // Access query parameters
  const page = ctx.query.page || '1';
// Get request headers
const authHeader = ctx.get('Authorization');
// Send JSON response
ctx.send({
message: 'Success',
page: parseInt(page)
});
}

File Upload with Validation

// Using ctx.parse() for file uploads with validation
export const POST_upload = async (ctx) => {
  const data = await ctx.parse({
    maxBodySize: 10 * 1024 * 1024, // 10MB limit
    contentType: 'multipart/form-data'
  });
// Validate file data
if (!data.files || !data.files.file) {
ctx.send( 'No file uploaded',400);
return
}
ctx.send({ message: 'Files uploaded successfully' });
}

WebSocket Connection

// WebSocket route handler
export const GET_live = async (ctx) => {
  // Upgrade to WebSocket
  ctx.upgrade();
// Access WebSocket connection
const conn = ctx.connection!;
// Handle WebSocket events
conn.addEventListener('message', (data) => {
// Handle incoming messages
});
conn.addEventListener('close', () => {
// Handle connection close
});
}

Best Practices

Type Safety: Use generics to define expected data shapes
Error Handling: Use ctx.send(error, <http status code>) for HTTP errors
State Management: Use ctx.state for request-scoped data and attach user info if authenticated
Security: Always validate input data and implement proper authentication
Response Handling: Use appropriate methods for different response types and include request ID in headers
Logging: Use ctx.plugins.logger for detailed request logging with request ID and duration
Headers: Add standard response headers including X-Request-ID and X-Response-Time

Key Features

Request Data Access

await ctx.parse(): Parsed request body data
ctx.parseQuery(): URL query parameters
params: Route parameters
All type-safe based on JetData generic
plugins: Returns the plugin object

Response Handling

send(): Send response data
sendStream(): Stream files
download(): Force file download
sendResponse(): Send raw Response object

Navigation

redirect(): Redirect requests
Sets appropriate headers
Ends request cycle

Headers & Cookies

get(): Get request headers
set(): Set response headers
Cookie methods: getCookie(), setCookie(), clearCookie()

WebSocket

upgrade(): Upgrade to WebSocket
connection: WebSocket interface
Handles WebSocket lifecycle

Additional Properties

request: Request object
connection: jet_socket object
code: HTTP status code
path: Request path
payload: Request payload

}

ctx.send(user);

}


### File Upload

```typescript
// Using ctx.parse() for file uploads
export const POST_upload = async (ctx) => {
    const data = await ctx.parse({
      maxBodySize: 10 * 1024 * 1024, // 10MB limit
      contentType: 'multipart/form-data'
    });
    
    // Handle uploaded files
    // data.files contains uploaded files
    ctx.send({ message: 'Files uploaded successfully' });
}

Best Practices

Type Safety: Use generics to define expected data shapes
State Management: Use ctx.state for request-scoped data
Security: Always validate input data
Response Handling: Use appropriate methods for different response types

Next Steps

Learn about Middleware
Explore Error Handling
Review Request Lifecycle

[cite: tests/app.jet.ts]

`plugins: UnionToIntersection<JetPluginTypes[number]> & Record<string, any>`

Type: Dynamic (Based on registered plugins)
Description: Your gateway to functionality added by plugins registered via app.use(). The specific methods available depend entirely on the plugins you’ve installed and registered. Use TypeScript generics (like JetMiddleware<AppState, [typeof PluginA, typeof PluginB]>) to get type hints for available plugin methods.

Example 1: Using an Auth Plugin

// Assuming AuthPlugin provides 'authenticateUser'
// In POST_auth_login handler:
const authResult = ctx.plugins.authenticateUser(username, password);
if (!authResult.authenticated) { /* handle failure */ }

[cite: tests/app.jet.ts]

Example 2: Using a File Upload Plugin

// Assuming jetbusboy plugin provides 'formData'
// In POST_upload handler:
const form = await ctx.plugins.formData(ctx);
const imageFile = form.image; // Access uploaded file data
if (imageFile && imageFile.filename) {
    await imageFile.saveTo(`./public/uploads/${imageFile.filename}`);
}

[cite: tests/app.jet.ts]

`body: Promise<Record<string, any>>`

Type: Inferred from Schema (JetData generic)
Description: Represents the parsed request body. It’s crucial to understand that ctx.body is typically a Promise that will resolve to the parsed validated body, So designed to be a parsed when you want to use it, with support for json, form-data, urlencoded.

Example:

// For a POST request with JSON: { "name": "Fluffy", "age": 3 }
// Define schema: const PetSchema = t.object({ name: t.string(), age: t.number() });
export const POST_pets = async (ctx) => {
  // Assuming NO pre-processing:
  console.log(await ctx.body); // undefined (initially)
  await ctx.json();      // Parse the JSON body
  console.log(await ctx.body); // { name: "Fluffy", age: 3 }
  const name = (await ctx.body).name; // Access data
  // ... validation and logic ...
}

`query: Record<string, string | string[]>`

Type: Inferred from Schema (JetData generic), defaults to Record<string, string | string[]>
Description: An object containing key-value pairs from the URL’s query string (the part after ?). Values are initially strings or arrays of strings (for repeated keys). Use validation to enforce specific types (like numbers or booleans).

Example 1: Basic Access

// URL: /search?term=cats&limit=20
// In handler:
const searchTerm = ctx.query.term;   // "cats"
const limitStr = ctx.query.limit; // "20"

Example 2: Using with Validation

// Schema: const SearchQuerySchema = t.object({ term: t.string(), limit: t.coerce.number().positive().optional().default(10) });
// In handler:
const validatedQuery = ctx.validate(SearchQuerySchema); // Validate ctx.query
const limit = validatedQuery.limit; // 10 (number, default applied)

[cite: tests/app.jet.ts (GET_pets example uses query params)]

`params: Record<string, string>`

Type: Inferred from Schema (JetData generic), defaults to Record<string, string>
Description: An object containing values captured from dynamic segments in the route path (defined using $paramName in file/export names).

Example:

// Route defined for /pets/petBy/:id (e.g., GET_petBy$id)
// Request URL: /pets/petBy/cat-567
// In handler:
const petIdentifier = ctx.params.id; // "cat-567"

// Schema: const PetParamsSchema = t.object({ id: t.string().startsWith("cat-") });
// const validatedParams = ctx.validate(PetParamsSchema); // Validate ctx.params
// const petId = validatedParams.id;

[cite: tests/app.jet.ts (GET_petBy$id, PUT_petBy$id, etc.)]

`connection: jet_socket`

Type: jet_socket
Description: Provides access to the WebSocket connection object. This property is only relevant and available within WebSocket handlers (routes defined with WS_).

Example:

// Route: /live
export const GET_live: JetRoute = (ctx) => {
  ctx.upgrade();
  const conn = ctx.connection!; // Assert non-null for WS routes
  console.log("Client connected via WebSocket");

  conn.addEventListener("open", (socket) => {
    socket.send("Welcome to the live feed!");
  });

  conn.addEventListener("message", (socket, event) => {
    console.log("Received message:", event.data);
    socket.send(`You sent: ${event.data}`);
  });

  conn.addEventListener("close", () => {
    console.log("Client disconnected");
  });
};

[cite: tests/app.jet.ts]

`request: Request`

Type: Request (Web Standard)
Description: Access the underlying standard Request object. Useful for lower-level access to request details like headers map, method, URL object, or potentially reading the raw body stream.

Example:

const method = ctx.request.method; // "GET", "POST", etc.
const url = new URL(ctx.request.url);
const pathname = url.pathname;
// Potentially access raw body: const reader = ctx.request.body?.getReader();

`code: number`

Type: number
Description: Gets or sets the HTTP status code for the outgoing response. Modify this before calling ctx.send or ctx.throw to control the response status. Defaults to 200 if ctx.send is called without errors.

Example 1: Setting Success Code

// After creating a resource:
ctx.code = 201; // Created
ctx.send({ id: newResourceId, message: "Resource created" });

Example 2: Setting Error Code Before Throwing

if (!resource) {
  ctx.code = 404; // Set explicit 404
  ctx.send("Resource not found"); // Middleware will use ctx.code (404)
}

[cite: tests/app.jet.ts (used extensively)]

`path: string`

Type: string
Description: Contains the pathname part of the request URL, excluding the query string.

Example:

// For URL: /users/profile?edit=true
const pathname = ctx.path; // "/users/profile"

Methods

Methods returning never indicate they terminate the request flow.

`eject(): never`

Description: Disconnects Jetpath’s automatic response handling. Use this advanced feature only when you need full manual control over the response stream, often for integrating with libraries that directly pipe to the underlying response (like older versions of busboy on Node.js). After eject(), Jetpath will not send any response automatically; your code is entirely responsible.
Example: (Refer to specific streaming library documentation for usage after ejecting)

`sendStream(stream: ReadableStream | any, ContentType: string): never`

Description: Sends a ReadableStream as the response body. Ideal for large files or dynamically generated content. Requires setting the correct Content-Type.
Example:

ctx.sendStream(file name); ```

`sendResponse(response?: Response): never`

Description: Sends a raw Web Standard Response object directly. Bypasses Jetpath’s content negotiation and serialization. Useful for maximal control, especially in Deno/Bun.
Example:
```
ctx.sendResponse(response);
```

`send(data: unknown, ContentType?: string): never`

Description: The primary method for sending responses. Handles serialization and content type automatically for common types.

Example 1: Sending JSON (Default)

ctx.send({ status: "success", data: { userId: 123 } });
// -> Content-Type: application/json

Example 2: Sending HTML

const html = "<h1>Hello from Jetpath!</h1>";
ctx.send(html, "text/html");
// -> Content-Type: text/html

Example 3: Sending Plain Text
```
ctx.send("OK");
// -> Content-Type: text/plain
```
[cite: tests/app.jet.ts (used extensively)]

`throw(codeOrData?: number | string | Record<string, any> | unknown, message?: string | Record<string, any>): never`

Description: Used to signal errors and interrupt the normal request flow. The thrown error should be caught and handled by your error-handling middleware.

Example 1: Not Found

// If pet with ctx.params.id doesn't exist:
ctx.send(`Pet with ID ${ctx.params.id} not found`, 404);

Example 2: Unauthorized

// If authentication fails:
ctx.set("WWW-Authenticate", "Bearer realm=\"protected area\""); // Add relevant header
ctx.send("Invalid credentials", 401);

Example 3: Internal Server Error

try { /* some risky operation */ }
catch (err) {
  console.error("Unexpected error:", err);
  ctx.send("",500); // Let middleware handle generic message
}

`redirect(url: string, code: number = 302): never` (Assuming optional code)

Description: Sends a redirect response to the client. Sets the Location header to the provided url and sets the status code (defaults typically to 302 Found).

Example:

// After successful login or form submission:
ctx.redirect("/dashboard");

// For a permanent redirect:
// ctx.redirect("/new-location", 301);

`get(field: string): string | undefined`

Description: Reads a request header value (case-insensitive).

Example:

const userAgent = ctx.get("User-Agent");
const acceptEncoding = ctx.get("Accept-Encoding");
const customHeader = ctx.get("X-Custom-ID");

`set(field: string, value: string): void`

Description: Sets a response header value. Can be called multiple times.

Example:

ctx.set("Content-Language", "en-US");
ctx.set("Cache-Control", "public, max-age=3600");
ctx.set("X-Powered-By", "Jetpath"); // Add a custom header

`parse(options?: { maxBodySize?: number; contentType?: string }): Promise<Record<string, any>>`

Description: Asynchronously reads and parses the request body specifically as JSON. Populates ctx.body upon success. Throws if the body is not valid JSON or has already been consumed. It’s often called just before ctx.validate() if not using eager pre-processing.

Example:

// In a POST handler expecting JSON:
async function handler(ctx) {
    try { 
        const name = (await ctx.parse()).name;
        ctx.send({ received: name });
    } catch (err) {
        ctx.send(`Invalid JSON payload: ${err.message}`,400);
    }
}

Next Steps

See how ctx is used throughout the Request Lifecycle.
Learn how Middleware leverages ctx for cross-cutting concerns.
Understand how Validation uses schemas to type and check ctx.parse(), ctx.parseQuery(), and ctx.params.

Context (ctx)

Usage Examples

Basic Request

File Upload with Validation

WebSocket Connection

Best Practices

Key Features

Request Data Access

Response Handling

Navigation

Headers & Cookies

WebSocket

Additional Properties

Best Practices

Next Steps

plugins: UnionToIntersection<JetPluginTypes[number]> & Record<string, any>

body: Promise<Record<string, any>>

query: Record<string, string | string[]>

params: Record<string, string>

connection: jet_socket

request: Request

code: number

path: string

Methods

eject(): never

sendStream(stream: ReadableStream | any, ContentType: string): never

sendResponse(response?: Response): never

send(data: unknown, ContentType?: string): never

throw(codeOrData?: number | string | Record<string, any> | unknown, message?: string | Record<string, any>): never

redirect(url: string, code: number = 302): never (Assuming optional code)

get(field: string): string | undefined

set(field: string, value: string): void

parse(options?: { maxBodySize?: number; contentType?: string }): Promise<Record<string, any>>

Next Steps

Context (`ctx`)

`plugins: UnionToIntersection<JetPluginTypes[number]> & Record<string, any>`

`body: Promise<Record<string, any>>`

`query: Record<string, string | string[]>`

`params: Record<string, string>`

`connection: jet_socket`

`request: Request`

`code: number`

`path: string`

`eject(): never`

`sendStream(stream: ReadableStream | any, ContentType: string): never`

`sendResponse(response?: Response): never`

`send(data: unknown, ContentType?: string): never`

`throw(codeOrData?: number | string | Record<string, any> | unknown, message?: string | Record<string, any>): never`

`redirect(url: string, code: number = 302): never` (Assuming optional code)

`get(field: string): string | undefined`

`set(field: string, value: string): void`

`parse(options?: { maxBodySize?: number; contentType?: string }): Promise<Record<string, any>>`