Context (ctx)

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

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

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

1. Type Safety: Use generics to define expected data shapes
2. State Management: Use ctx.state for request-scoped data
3. Security: Always validate input data
4. 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: JetData["body"]

• Type: Inferred from Schema (JetData generic)
• Description: Represents the parsed request body. It’s crucial to understand that ctx.body is typically undefined until you explicitly parse the request body using a method like await ctx.json(), await ctx.plugins.formData(ctx), or implicitly via ctx.validate() if it handles parsing, unless you have enabled opt-in eager pre-processing for the route.
• 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(ctx.body); // undefined (initially)
    await ctx.json();      // Parse the JSON body
    console.log(ctx.body); // { name: "Fluffy", age: 3 }
    const name = ctx.body.name; // Access data
    // ... validation and logic ...
  }
  

query: JetData["query"]

• 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: JetData["params"]

• 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
  

json(): 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 {
          await ctx.json(); // Parse the body
          const name = ctx.body.name;
          // Now validate ctx.body or use it directly if validation not needed
          ctx.send({ received: ctx.body });
      } 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.body, ctx.query, and ctx.params.