Context API

app.get('/users/:id', (req, res) => {
  const id = req.params.id; // From req
  const query = req.query; // From req
  res.json({ id, query }); // To res
});

app.use((req, res, next) => {
  req.user = { id: 123 }; // Mutate req
  next();
});

app.get('/users/:id', (ctx) => {
  const id = ctx.params.id; // Request data
  const query = ctx.query; // Request data
  ctx.json({ id, query }); // Response method
});

// Auth middleware
app.use(async (ctx) => {
  ctx.state.user = { id: 123 };
  await ctx.next();
});

// Handler
app.get('/profile', (ctx) => {
  ctx.json({ user: ctx.state.user });
});

┌─────────────────────────────────────────────┐
│                 Context (ctx)                │
├─────────────────────────────────────────────┤
│  ┌─────────────────────────────────────┐    │
│  │  INPUT (Request)                    │    │
│  │  • method, path, url                │    │
│  │  • params, query, headers           │    │
│  │  • body (after parser)              │    │
│  │  • ip                               │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  OUTPUT (Response)                  │    │
│  │  • status                           │    │
│  │  • json(), send(), html()           │    │
│  │  • set(), redirect()                │    │
│  └─────────────────────────────────────┘    │
│  ┌─────────────────────────────────────┐    │
│  │  SHARED (State)                     │    │
│  │  • state.user, state.requestId...   │    │
│  └─────────────────────────────────────┘    │
└─────────────────────────────────────────────┘

ctx.throw(404); // Not Found
ctx.throw(404, 'User not found'); // With custom message
ctx.throw(401, 'Invalid token');

const user = await getUser(id);
ctx.assert(user, 404, 'User not found');
ctx.assert(user.isAdmin, 403, 'Forbidden');

// Equivalent to:
if (!user) {
  ctx.throw(404, 'User not found');
}

app.use(async (ctx) => {
  console.log('Before');
  await ctx.next(); // Call next middleware
  console.log('After');
});

// Auth middleware
app.use(async (ctx) => {
  const token = ctx.get('Authorization');
  if (token) {
    ctx.state.user = await verifyToken(token);
  }
  await ctx.next();
});

// Handler
app.get('/profile', (ctx) => {
  ctx.json({ user: ctx.state.user });
});

// Node.js
ctx.raw.req; // http.IncomingMessage
ctx.raw.res; // http.ServerResponse

// Bun/Deno/Edge
ctx.raw.req; // Web Request object

ctx.runtime;
// 'node' | 'bun' | 'deno' | 'deno-deploy'
// | 'cloudflare-workers' | 'vercel-edge' | 'edge' | 'unknown'

if (ctx.runtime === 'bun') {
  // Bun-specific optimization
}

app.use(async (ctx) => {
  await ctx.next();
  if (!ctx.responded) {
    ctx.status = 404;
    ctx.json({ error: 'Not found' });
  }
});

// In a custom body parser
const text = await ctx.bodySource.text();
const data = JSON.parse(text);

app.use(async (ctx) => {
  const start = Date.now();
  console.log(`→ ${ctx.method} ${ctx.path}`);

  await ctx.next();

  const ms = Date.now() - start;
  console.log(`← ${ctx.status} (${ms}ms)`);
});

app.use(async (ctx) => {
  const requestId = ctx.get('X-Request-Id') || crypto.randomUUID();
  ctx.state.requestId = requestId;
  ctx.set('X-Request-Id', requestId);
  await ctx.next();
});

app.use(async (ctx) => {
  const token = ctx.get('Authorization')?.replace('Bearer ', '');

  if (token) {
    try {
      ctx.state.user = await verifyJWT(token);
    } catch {
      // Invalid token - continue without user
    }
  }

  await ctx.next();
});

// ❌ Wrong: Response may be sent before downstream completes
app.use(async (ctx) => {
  ctx.next(); // Missing await!
  ctx.set('X-After', 'value');
});

// ✅ Correct
app.use(async (ctx) => {
  await ctx.next();
  ctx.set('X-After', 'value');
});

// ❌ Wrong: Two responses
app.use((ctx) => {
  ctx.json({ step: 1 });
  ctx.json({ step: 2 }); // Error or ignored
});

// ✅ Correct: One response
app.use((ctx) => {
  ctx.json({ steps: [1, 2] });
});

// ❌ Wrong: body is undefined
app.post('/users', (ctx) => {
  console.log(ctx.body); // undefined!
});

// ✅ Correct: Add body parser first
import { json } from '@nextrush/body-parser';
app.use(json());
app.post('/users', (ctx) => {
  console.log(ctx.body); // { name: 'Alice', ... }
});

import type { Context, ContextState } from '@nextrush/types';

const handler = (ctx: Context) => {
  ctx.json({ ok: true });
};

// Extend state type
interface AppState extends ContextState {
  user?: { id: string; email: string };
  requestId: string;
}