Imported from CodeDynasty-dev/Jetpath (jetpath-backend-framework-skill/SKILL.md). Install upstream with npx skills add CodeDynasty-dev/Jetpath --skill jetpath-backend-framework-skill. Copyright stays with the author.

Jetpath Backend Framework Skill

Overview

Jetpath (v1.13.x) is a performance-first, cross-runtime API framework for Node.js, Bun, and Deno. It uses convention-over-configuration: you export named functions from .jet.ts files, and Jetpath automatically maps them to HTTP routes.

Key principles:

• Zero-router boilerplate: Function export names ARE the routes — no decorators, no config files, no router registration.
• TypeScript-first: Built-in generics for full type safety on body, params, query, and plugins.
• Cross-runtime: Node.js (v18+), Bun (v1.0+), Deno, AWS Lambda, Cloudflare Workers.
• Performance: Trie-based routing with hashmap fast-path for static paths, context pooling (cap: 1024), pre-baked CORS headers.
• Built-in validation: Declarative schemas that auto-enforce AND auto-generate API documentation.

1. Installation & Project Setup

npm install jetpath

Production Project Structure

This is the proven structure from a live production SMS gateway platform:

my-api/
├── src/
│   ├── app/                  # Route handler files (*.jet.ts ONLY)
│   │   ├── auth.jet.ts       # → /auth/*
│   │   ├── users.jet.ts      # → /user/*, /account/*, /admin/users/*
│   │   ├── sms.jet.ts        # → /sms/*, /campaigns/*
│   │   ├── payments.jet.ts   # → /deposits/*, /orders/*
│   │   ├── admin.jet.ts      # → /admin/*
│   │   ├── support.jet.ts    # → /support/*
│   │   ├── analytics.jet.ts  # → /analytics/*
│   │   ├── notification.jet.ts
│   │   ├── monitoring.jet.ts # → /monitoring/*, /health
│   │   ├── hlr.jet.ts        # → /hlr/*
│   │   └── telegram.jet.ts   # → /telegram/*
│   ├── middleware/            # Reusable middleware modules (regular .ts files)
│   │   ├── auth.ts
│   │   └── rate-limit.ts
│   ├── services/             # Business logic
│   ├── db/                   # Database layer (Prisma, etc.)
│   ├── telegram/             # External service integrations
│   ├── types/                # TypeScript type definitions
│   ├── utils/                # Utility functions
│   ├── constants.ts          # App-wide constants & config
│   └── main.jet.ts           # Server entry point + global middleware
├── plugins.ts                # Plugin definitions
├── package.json
└── tsconfig.json

Critical file naming rules:

• .jet.ts files (or .jet.js): Scanned for route exports. ONLY these files are scanned.
• Regular .ts/.js files: NOT scanned. Use for middleware modules, services, utilities. Import them from .jet.ts files.
• The source option in the constructor specifies the root directory for scanning.

2. Server Entry Point

The main entry file MUST be a .jet.ts file. It creates the Jetpath instance, registers plugins, defines the global middleware, and calls listen().

import { Jetpath, type JetContext, type JetMiddleware } from "jetpath";
import { throwingPlugin } from "../plugins.ts";
import { connectDB } from "./db/index.ts";
import { config } from "dotenv";

config();
await connectDB();

const app = new Jetpath({
  source: ".",          // Scan current directory and subdirectories for .jet.ts files
  port: Number(process.env.PORT) || 3000,
  cors: true,
  strictMode: "OFF",    // "ON" | "OFF" | "WARN"
  apiDoc: {
    name: "My API",
    info: "Production API Platform",
    color: "#2563eb",
    display: "HTTP",    // "UI" | "HTTP" | false
  },
  globalHeaders: {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
    "Access-Control-Allow-Headers": "Content-Type, Authorization",
    "Access-Control-Max-Age": "86400",
    "Content-Type": "application/json",
  },
  // upgrade: true,     // Required for WebSocket support
});

// Register plugins BEFORE listen()
app.derivePlugins(throwingPlugin);

app.listen();

Running the Server

# Bun (recommended — fastest startup):
bun src/main.jet.ts

# Node.js (v22+):
node --experimental-strip-types src/main.jet.ts

# Deno:
deno run --allow-all src/main.jet.ts

3. Routing — The Core Convention

3.1 Export Naming Convention

Export named functions from .jet.ts files. The export name determines method and path:

Format: METHOD_segment1_segment2

• METHOD prefix (UPPERCASE): GET_, POST_, PUT_, DELETE_, PATCH_, HEAD_
• Underscores become / separators: GET_api_v1_users → GET /api/v1/users
• Double underscores __ become hyphens -: POST_deposits__2 → POST /deposits-2

import { type JetRoute, use } from "jetpath";

// GET /health
export const GET_health: JetRoute = async function (ctx) {
  ctx.send({ status: "healthy", timestamp: new Date().toISOString() });
};

// GET /monitoring/gateways
export const GET_monitoring_gateways = async (ctx: any) => {
  const gateways = await prisma.smppGateway.findMany({ where: { status: "ACTIVE" } });
  ctx.send({ gateways, totalGateways: gateways.length });
};

// GET /account/balance
export const GET_account_balance: JetRoute = async function (ctx) {
  const user = ctx.state.user;
  ctx.send({
    data: { balance: Number(user.balance), currency: "USD" },
    ok: true,
  });
};

3.2 Path Parameters ($paramName)

Dynamic segments use a $ prefix in the export name. The $ becomes : in the actual route.

// GET /admin/users/:id → e.g., GET /admin/users/abc123
export const GET_admin_users$id: JetRoute<{ params: { id: string } }> = async function (ctx) {
  const { id } = ctx.params;
  const user = await prisma.user.findUnique({ where: { id } });
  if (!user) {
    ctx.send({ message: "User not found", ok: false }, 404);
    return;
  }
  ctx.send({ data: user, ok: true });
};

// PUT /admin/users/:id/status → nested param route
export const PUT_admin_users$id_status: JetRoute<{
  params: { id: string };
  body: { is_active: boolean };
}> = async function (ctx) {
  const { id } = ctx.params;
  const { is_active } = await ctx.parse();
  const updated = await prisma.user.update({
    where: { id },
    data: { is_active },
  });
  ctx.send({ data: updated, ok: true });
};

use(PUT_admin_users$id_status).body((t) => ({
  is_active: t.boolean().required().default(true),
}));

// GET /admin/users/:id/analytics/orders → deep nesting
export const GET_admin_users$id_analytics_orders: JetRoute<{
  params: { id: string };
  query: { days?: string };
}> = async function (ctx) {
  const { id } = ctx.params;
  const { days = "30" } = ctx.parseQuery() || {};
  // ...
};

// PUT /user/notifications/read/:id
export const PUT_user_notifications_read$id: JetRoute<{
  params: { id: string };
}> = async (ctx) => {
  await prisma.notification.update({
    where: { id: ctx.params.id, user_id: ctx.state.user.id },
    data: { is_read: true },
  });
  ctx.send({ ok: true, message: "Notification marked as read" });
};

// POST /admin/send/notification/user/:userId
export const POST_admin_send_notification_user$userId: JetRoute<{
  params: { userId: string };
  body: { title: string; content: string };
}> = async (ctx) => {
  const { userId } = ctx.params;
  const { title, content } = await ctx.parse();
  // ...
};

3.3 Catch-All / Wildcard Routes ($0)

Match all remaining path segments. The wildcard value is accessed as ctx.params["*"].

// GET /files/* → Catches /files/images/photo.jpg, /files/docs/api/v1, etc.
export const GET_files_$0: JetRoute = (ctx) => {
  const filePath = ctx.params["*"];  // e.g., "images/photo.jpg"
  ctx.sendStream(filePath, { folder: "./uploads" });
};

3.4 Route Precedence

Jetpath uses a trie with hashmap fast-path:

1. Exact/static routes → O(1) hashmap lookup (fastest)
2. Parameterized routes (:id) → Trie traversal
3. Wildcard routes (*) → Match last

/users/search always takes priority over /users/:id when path is /users/search.

4. Context Object (ctx)

The ctx object is the central interface for every request. It is pooled and reused.

4.1 Properties

4.2 Methods

ctx.send(data, statusCode?, contentType?)

Primary response method. Objects auto-serialize to JSON.

// JSON response (most common — objects auto-serialize)
ctx.send({ data: result, ok: true });

// With explicit status code
ctx.send({ error: "Not found" }, 404);

// Set code first, then send
ctx.code = 201;
ctx.send({ id: newId, message: "Created" });

// Plain text / CSV with custom content type
ctx.set("Content-Type", "text/csv");
ctx.set("Content-Disposition", `attachment; filename="export.csv"`);
ctx.send(csvContent);

ctx.parse(options?): Promise<Record<string, any>>

Parses request body. Supports JSON, multipart/form-data, URL-encoded. Auto-validates against use(route).body() schema if defined. Results are cached — calling twice returns cached result.

const body = await ctx.parse();

// With size limit:
const body = await ctx.parse({ maxBodySize: 26 * 1024 * 1024 }); // 26MB

CRITICAL: ctx.parse() is async — you MUST await it.

What happens internally:

1. Reads the request body stream
2. Parses based on Content-Type header (JSON, form-data, URL-encoded)
3. If a use(route).body() schema exists, validates and strips unknown fields
4. Returns the parsed (and optionally validated) object

ctx.parseQuery(): Record<string, any>

Parses URL query parameters. Auto-validates against use(route).query() schema if defined. Results are cached.

// URL: /users?status=active&limit=50&offset=0&search=john
const { status, date_from, date_to, limit = "50", offset = "0", search } = ctx.parseQuery() || {};

// Alternative: destructure into variables with defaults
const query = ctx.parseQuery();
const page = parseInt(query.page || "1");
const limit = parseInt(query.limit || "50");

NOTE: ctx.parseQuery() is synchronous — no await needed.

ctx.get(field): string | undefined

Read a request header (case-insensitive).

const auth = ctx.get("authorization");
const origin = ctx.get("origin");
const ip = ctx.get("x-forwarded-for") || ctx.get("x-real-ip");
const userAgent = ctx.get("user-agent");

ctx.set(field, value): void

Set a response header.

ctx.set("Cache-Control", "no-cache");
ctx.set("X-Request-ID", requestId);
ctx.set("X-RateLimit-Limit", "100");
ctx.set("X-RateLimit-Remaining", remaining.toString());

ctx.redirect(url): void

Send a 301 redirect.

ctx.redirect("/dashboard");
ctx.redirect(`${client_link}/login?success=true&token=${token}`);
ctx.redirect(`${client_link}/login?error=oauth_failed`);

ctx.sendStream(streamOrPath, config?): void

Send a file or stream response. Path traversal protection is enforced when using folder.

// Send file by path
ctx.sendStream("photo.jpg", { folder: "./uploads", ContentType: "image/jpeg" });

// Send stream directly
ctx.sendStream(readableStream);

// Serve static files from a folder
ctx.sendStream(ctx.params["*"], { folder: "src/site/" });

ctx.sendResponse(response?: Response): void

Send a raw Web Standard Response object. Only works on Bun and Deno. Used for SSE (Server-Sent Events) and custom streaming.

// SSE stream (production pattern):
const stream = new ReadableStream({
  start(controller) {
    const encoder = new TextEncoder();
    function send(chunk: string) {
      controller.enqueue(encoder.encode(`data: ${chunk}\n\n`));
    }
    // ... register send function, send events ...
  },
});

ctx.sendResponse(
  new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      "X-Accel-Buffering": "no",
      Connection: "keep-alive",
      "Access-Control-Allow-Origin": "*",
    },
  })
);

ctx.upgrade(): void

Upgrade HTTP to WebSocket. Only Bun/Deno. Requires upgrade: true in server options.

ctx.upgrade();
const conn = ctx.connection!;

conn.addEventListener("open", async (socket) => {
  socket.send(JSON.stringify({ type: "welcome" }));
});

conn.addEventListener("message", async (socket, event) => {
  const data = JSON.parse(event.data.toString());
  if (data?.type === "ping") {
    socket.send(JSON.stringify({ type: "pong" }));
    return;
  }
  // Process message...
});

conn.addEventListener("close", () => {
  // Cleanup...
});

Cookie Methods

ctx.setCookie("session", "abc123", {
  httpOnly: true, secure: true, maxAge: 3600,
  sameSite: "strict", path: "/", domain: "example.com",
});
const session = ctx.getCookie("session");
const cookies = ctx.getCookies();
ctx.clearCookie("session", {});

4.3 Type Safety with Generics

import { type JetRoute } from "jetpath";

// Full type safety on body, params, query:
export const POST_sms_send: JetRoute<{
  body: {
    to: string;
    message: string;
    sender_id: string;
    callback_url?: string;
    marker?: string;
  };
}> = async function (ctx) {
  const { to, message, callback_url, sender_id, marker } = await ctx.parse();
  // All fields are typed ↑
};

// With plugin types:
import type { throwingPluginType } from "../plugins.ts";

export const GET_admin: JetRoute<{}, [throwingPluginType]> = (ctx) => {
  ctx.plugins.throw(403, "Admin only"); // typed!
};

5. Middleware

5.1 Global Middleware

A bare MIDDLEWARE_ export (no suffix) applies to ALL routes in the scan tree:

import { type JetMiddleware } from "jetpath";

// This is from a live production API:
export const MIDDLEWARE_: JetMiddleware = async function (ctx) {
  const { url, method } = ctx.request as { url: string; method: string };
  console.log(method, url);

  // Pre-parse body for non-GET/DELETE requests
  if (method !== "GET" && method !== "DELETE") {
    try {
      await ctx.parse({ maxBodySize: 26 * 1024 * 1024 });
    } catch (error: any) {
      ctx.plugins.throw(error.message);
    }
  }

  // Return post-handler for error handling
  return (ctx, err) => {
    if (!err) return;
    if (ctx.code < 400) ctx.code = 400;
    console.error(err);
    ctx.send({
      code: ctx.code,
      ok: false,
      message: String(err?.message || err),
    });
  };
};

5.2 Scoped Middleware — Assigning from External Modules

The production pattern is to define middleware in regular .ts files and assign them via exports in .jet.ts files:

// src/middleware/auth.ts (regular .ts file — NOT scanned for routes)
import { type JetMiddleware } from "jetpath";
import { auth } from "../main.jet.ts";
import { prisma } from "../db/index.ts";

export const authMiddleware: JetMiddleware = async function (ctx) {
  const authHeader = ctx.get("authorization");
  const token = authHeader?.split(" ")[1];
  if (!token) {
    ctx.plugins.throw(401, "Authentication required");
    return;
  }
  const payload = await auth.decode(token);
  if (!payload) ctx.plugins.throw(500, "");
  await auth.verify(token, "access");

  const user = await prisma.user.findUnique({
    where: { id: payload.id as string },
  });
  if (!user || !user.is_active) {
    ctx.plugins.throw(401, "Inaccessible user");
    return;
  }

  ctx.state.user = user;
};

export const adminOrModeratorMiddleware: JetMiddleware = async function (ctx) {
  if (!(ctx.state.user?.is_admin || ctx.state.user?.is_moderator)) {
    ctx.plugins.throw(403, "access required");
    return;
  }
};

export const AdminOnlyMiddleware: JetMiddleware = async function (ctx) {
  if (ctx.state.user?.is_moderator || !ctx.state.user?.is_admin) {
    ctx.plugins.throw(403, "access required");
    return;
  }
};

// src/app/users.jet.ts — assign middleware by exporting
import { authMiddleware } from "../middleware/auth.ts";

// Scopes authMiddleware to /user/* routes AND /account/* routes
export const MIDDLEWARE_user = authMiddleware;
export const MIDDLEWARE_account = authMiddleware;

// Now all GET_user_*, POST_user_*, GET_account_* routes in this file
// automatically have authMiddleware applied
export const GET_user: JetRoute = async function (ctx) {
  const user = ctx.state.user;  // Set by authMiddleware
  ctx.send({ data: user, ok: true });
};

5.3 Middleware Arrays — Stacking Multiple Middleware

Assign an array for multi-step middleware chains:

import { authMiddleware, adminOrModeratorMiddleware, AdminOnlyMiddleware } from "../middleware/auth.ts";

// Admin routes: auth + admin-or-moderator check (two middleware in sequence)
export const MIDDLEWARE_admin = [authMiddleware, adminOrModeratorMiddleware] as any;

// SMPP routes: auth + admin-only check
export const MIDDLEWARE_smpp = [authMiddleware, AdminOnlyMiddleware] as any;

// Prices routes: auth only
export const MIDDLEWARE_prices = [authMiddleware] as any;

5.4 Rate Limiting as Middleware

// src/middleware/rate-limit.ts
export function createRateLimiter(config: { windowMs: number; maxRequests: number }) {
  return async (ctx: any) => {
    const username = ctx.state?.user?.username || "anonymous";
    // ... sliding window rate limit logic ...
    if (isRateLimited) {
      ctx.set("X-RateLimit-Limit", config.maxRequests.toString());
      ctx.set("X-RateLimit-Remaining", "0");
      ctx.set("Retry-After", retryAfter.toString());
      return ctx.send({
        ok: false,
        message: "Rate limit exceeded. Please try again later.",
        code: "RATE_LIMIT_EXCEEDED",
        retryAfter,
      }, 429);
    }
    ctx.set("X-RateLimit-Remaining", remaining.toString());
  };
}

export const rateLimiters = {
  chatMessages: createRateLimiter({ windowMs: 60_000, maxRequests: 10 }),
  aiRequests: createRateLimiter({ windowMs: 60_000, maxRequests: 5 }),
  fileUploads: createRateLimiter({ windowMs: 60_000, maxRequests: 3 }),
};

// src/app/support.jet.ts — assign rate limiter as scoped middleware
import { rateLimiters } from "../middleware/rate-limit.ts";

export const MIDDLEWARE_support_chat_send = [rateLimiters.chatMessages];

5.5 Middleware Execution Order & Short-Circuiting

Request
  → Global MIDDLEWARE_ pre-handler
    → Scoped MIDDLEWARE_prefix pre-handler
      → Route Handler
    ← Scoped post-handler (reverse order)
  ← Global post-handler (reverse order)
Response

Short-circuiting: If a pre-handler calls ctx.send() or ctx.plugins.throw(), the route handler is SKIPPED:

export const MIDDLEWARE_: JetMiddleware = (ctx) => {
  if (!ctx.get("authorization")) {
    ctx.send({ error: "Unauthorized" }, 401);
    return;  // No post-handler → route handler never runs
  }
};

5.6 Middleware Naming Convention

Middleware scoping follows the same underscore-to-slash convention as routes:

• MIDDLEWARE_admin → matches routes starting with /admin
• MIDDLEWARE_api_v1 → matches routes starting with /api/v1
• MIDDLEWARE_sms → matches routes starting with /sms
• MIDDLEWARE_telegram_link → matches routes starting with /telegram/link
• MIDDLEWARE_support_chat_send → matches routes starting with /support/chat/send

6. Validation with use()

6.1 Body Validation

import { type JetRoute, use } from "jetpath";

export const POST_sms_send: JetRoute<{
  body: { to: string; message: string; sender_id: string; callback_url?: string };
}> = async function (ctx) {
  const { to, message, callback_url, sender_id } = await ctx.parse();
  // Validated ↑ — unknown fields stripped, types enforced
  ctx.send({ status: "queued", to });
};

use(POST_sms_send).body((t) => ({
  to: t.string().regex(/^\+?[0-9]{7,15}$/).required(),
  from: t.string().optional().default("vortex"),
  message: t.string().min(1).max(1600).required().default("Hello from SMS Route!"),
  callback_url: t.string().url().optional(),
  marker: t.string().optional(),
}));

6.2 Query Validation

export const GET_admin_users: JetRoute<{
  query: { status?: string; limit?: string; offset?: string; search?: string };
}> = async function (ctx) {
  const { status, limit = "50", offset = "0", search } = ctx.parseQuery() || {};
  // ...
};

use(GET_admin_users).query((t) => ({
  status: t.string().optional(),
  date_from: t.string().optional(),
  date_to: t.string().optional(),
  limit: t.string().optional().default("50"),
  offset: t.string().optional().default("0"),
  search: t.string().optional(),
}));

6.3 Array Validation

use(POST_sms_validate).body((t) => ({
  message: t.string().min(1).max(1600).required(),
  recipients: t.array(t.string().regex(/^\+?[0-9]{7,15}$/)).min(1).required(),
}));

// Array of objects:
use(POST_hlr_export).body((t) => ({
  results: t.array(t.object()).required(),
}));

6.4 Schema Builder Reference (t)

The opts? parameter for t.string() and t.number() accepts { err?: string } for custom error messages:

use(POST_auth_login).body((t) => ({
  email: t.string({ err: "Invalid email format" }).required().default("user@example.com"),
  password: t.string({ err: "Password is required" }).required().default("password123"),
  turnstileToken: t.string().optional().default(""),
}));

6.5 Title & Description (API Docs)

use(GET_users)
  .title("List Users")
  .description("Returns a paginated list of users.");

All use() methods are chainable:

use(POST_users)
  .title("Create User")
  .body((t) => ({ name: t.string().required(), email: t.string().email().required() }));

6.6 Mass-Assignment Protection

The validator only passes through fields defined in the schema. Unknown fields are silently stripped. This prevents clients from sending isAdmin: true or other fields you didn't define.

7. Error Handling

7.1 The Throwing Plugin Pattern (Production Standard)

The standard production pattern is a throwing plugin that sets the response AND throws to trigger the middleware error chain:

// plugins.ts
import { type JetContext } from "jetpath";

export const throwingPlugin = {
  name: "throwingPlugin",
  executor() {
    return {
      throw(this: any, code: any = 400, message: any = "") {
        const self = this as JetContext;
        // Support calling throw("message") without a code
        if (typeof code !== "number") {
          message = code;
          code = 400;
        }
        const payload = {
          ok: false,
          message: String((message as any)?.message || message || ""),
        };
        self.send(payload, Number(code) || 400);
        throw new Error(payload.message);
      },
    };
  },
};

export type throwingPluginType = ReturnType<typeof throwingPlugin.executor>;

Register in main.jet.ts:

import { throwingPlugin } from "../plugins.ts";
app.derivePlugins(throwingPlugin);

7.2 Using ctx.plugins.throw() in Handlers

// With status code + message (most common):
ctx.plugins.throw(400, "Invalid recipient phone number");
ctx.plugins.throw(401, "Authentication required");
ctx.plugins.throw(403, "access required");
ctx.plugins.throw(404, "User not found");
ctx.plugins.throw(500, "Failed to process SMS request");

// With just a message (defaults to 400):
ctx.plugins.throw("Something went wrong");

// With error object:
ctx.plugins.throw(error.message);

// IMPORTANT: After ctx.plugins.throw(), execution continues
// because throw happens inside the plugin — always return after:
if (!user) {
  ctx.plugins.throw(404, "User not found");
  return;  // ← MUST return after throw
}

7.3 Alternative: Direct ctx.send() for Errors

Some production routes use ctx.send() directly with a status code instead of the plugin:

if (!title || !content) {
  ctx.send({ ok: false, message: "Title and content are required." }, 400);
  return;
}

// Or set code first:
ctx.code = 503;
ctx.send({
  data: { status: "unhealthy", error: "Database connection failed" },
  ok: false,
});

7.4 Error Middleware (Post-Handler)

The global middleware post-handler catches all unhandled errors:

return (ctx, err) => {
  if (!err) return;
  if (ctx.code < 400) ctx.code = 400;
  const { code, message } = mapErrorToCode(ctx.code, err);
  console.error(err);
  ctx.send({ code, ok: false, message });
};

7.5 Try/Catch in Handlers

For operations that can fail (DB, external APIs), wrap in try/catch:

export const POST_sms_send: JetRoute = async function (ctx) {
  // ... validation ...

  try {
    const smsId = await prisma.$transaction(async (tx: any) => {
      // Atomic operations...
      return log.id;
    });

    ctx.send({ messageId: smsId, status: "queued" });
  } catch (error) {
    console.error("SMS sending error:", error);
    ctx.plugins.throw(500, "Failed to process SMS request");
  }
};

8. Plugins

8.1 Plugin Structure

export const myPlugin = {
  name: "myPlugin",        // Required: unique string identifier
  executor() {             // Required: returns the public API
    return {
      // Methods here are available on ctx.plugins
      // `this` is bound to the current ctx at runtime
      myMethod(this: any, arg: string) {
        const ctx = this as JetContext;
        // can access ctx.send(), ctx.state, etc.
      },
    };
  },
};

CRITICAL: Plugin methods have this bound to the current ctx at runtime via Function.prototype.bind().

8.2 Registration & Typing

// Register:
app.derivePlugins(throwingPlugin, loggerPlugin);

// Type export for use in handlers:
export type throwingPluginType = ReturnType<typeof throwingPlugin.executor>;

// Use in route generics:
export const GET_admin: JetRoute<{}, [throwingPluginType]> = (ctx) => {
  ctx.plugins.throw(403, "Forbidden"); // typed
};

9. SSE (Server-Sent Events) — Production Pattern

SSE is implemented using ctx.sendResponse() with a ReadableStream:

export const GET_support_chat_stream: JetRoute<{
  query: { sessionId: string };
}> = async (ctx) => {
  const url = new URL(ctx.request.url);
  const sessionId = url.searchParams.get("sessionId") || "";
  if (!sessionId) {
    return ctx.plugins.throw(400, "Missing sessionId");
  }

  const stream = new ReadableStream({
    start(controller) {
      const encoder = new TextEncoder();

      function send(chunk: string) {
        controller.enqueue(encoder.encode(`data: ${chunk}\n\n`));
      }

      // Register this client
      if (!sseClients[sessionId]) sseClients[sessionId] = new Set();
      sseClients[sessionId].add(send);

      // Send initial data
      (async () => {
        const msgs = await prisma.chatMessage.findMany({
          where: { session_id: sessionId },
          orderBy: { timestamp: "asc" },
        });
        send(JSON.stringify({ type: "history", messages: msgs }));
        send(JSON.stringify({ type: "welcome", sessionId }));
      })();

      // Keepalive ping to prevent proxy timeouts
      const keepalive = setInterval(() => {
        try {
          controller.enqueue(encoder.encode(`: keepalive ${Date.now()}\n\n`));
        } catch {}
      }, 15000);

      // Cleanup on disconnect
      const onAbort = () => {
        sseClients[sessionId]?.delete(send);
        if (sseClients[sessionId]?.size === 0) delete sseClients[sessionId];
        clearInterval(keepalive);
        ctx.request.signal.removeEventListener("abort", onAbort);
        try { controller.close(); } catch {}
      };
      ctx.request.signal.addEventListener("abort", onAbort);
    },
  });

  return ctx.sendResponse(
    new Response(stream, {
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache, no-transform",
        "X-Accel-Buffering": "no",
        Connection: "keep-alive",
        "Access-Control-Allow-Origin": "*",
      },
    })
  );
};

10. WebSocket Routes — Production Pattern

WebSocket uses a regular GET_ route + ctx.upgrade(). Requires upgrade: true in server options. Bun/Deno only.

export const GET_support_chat_websocket: JetRoute<{
  query: { sessionId: string; isSupport?: string };
}> = (ctx) => {
  ctx.upgrade();
  const conn = ctx.connection!;

  conn.addEventListener("open", async (socket) => {
    const sessionId = ctx.parseQuery().sessionId || "";
    if (!sessionId) { socket.close(); return; }

    if (!connections[sessionId]) connections[sessionId] = new Set();
    connections[sessionId].add(socket);

    const msgs = await prisma.chatMessage.findMany({
      where: { session_id: sessionId },
      orderBy: { timestamp: "asc" },
    });
    socket.send(JSON.stringify({ type: "history", messages: msgs }));
    socket.send(JSON.stringify({ type: "welcome" }));
  });

  conn.addEventListener("message", async (socket, event) => {
    const data = JSON.parse(event.data.toString());
    if (data?.type === "ping") {
      socket.send(JSON.stringify({ type: "pong" }));
      return;
    }
    // Process message, save to DB, broadcast to session...
  });

  conn.addEventListener("close", () => {
    // Cleanup connection from tracking sets
  });
};

11. Exports from "jetpath"

import { Jetpath } from "jetpath";                // Main class
import { type JetRoute } from "jetpath";           // Route handler type
import { type JetMiddleware } from "jetpath";       // Middleware type
import { type JetContext } from "jetpath";           // Context type
import { type JetFile } from "jetpath";              // File upload type: { fileName, content: Uint8Array, mimeType, size }
import { use } from "jetpath";                       // Validation/docs helper
import { JetServer } from "jetpath";                 // Testing harness

12. Production Patterns

12.1 Project File Organization

One resource domain per .jet.ts file:

• auth.jet.ts — login, register, OAuth
• users.jet.ts — user CRUD, profile, settings
• admin.jet.ts — admin-only operations
• payments.jet.ts — deposits, orders, payment callbacks
• sms.jet.ts — SMS sending, campaigns, bulk operations
• monitoring.jet.ts — gateway status, queue stats, health checks
• support.jet.ts — chat, SSE streaming, WebSocket
• analytics.jet.ts — event tracking, reporting
• notification.jet.ts — user notifications

12.2 Multi-Prefix Middleware in a Single File

A .jet.ts file can export middleware for multiple route prefixes. This is how a single file handles routes under different path prefixes while applying different middleware:

// src/app/sms.jet.ts
export const MIDDLEWARE_sms = authMiddleware;
export const MIDDLEWARE_campaigns = authMiddleware;

// src/app/payments.jet.ts
export const MIDDLEWARE_deposits = authMiddleware;
export const MIDDLEWARE_orders = authMiddleware;

// src/app/admin.jet.ts — with stacked middleware arrays
export const MIDDLEWARE_admin = [authMiddleware, adminOrModeratorMiddleware] as any;
export const MIDDLEWARE_smpp = [authMiddleware, AdminOnlyMiddleware] as any;
export const MIDDLEWARE_prices = [authMiddleware] as any;

12.3 Common Response Shapes

// Success
ctx.send({ data: result, ok: true });
ctx.send({ data: result, ok: true }, 201);

// Success with pagination
ctx.send({
  data: items,
  pagination: {
    total,
    limit: parseInt(limit),
    offset: parseInt(offset),
    has_more: total > parseInt(offset) + parseInt(limit),
  },
  ok: true,
});

// Success with message
ctx.send({ ok: true, message: "Notification marked as read" });

// Error
ctx.plugins.throw(400, "Invalid input");
ctx.plugins.throw(401, "Authentication required");
ctx.plugins.throw(404, "User not found");

// Error without plugin
ctx.send({ ok: false, message: "Title and content are required." }, 400);

12.4 Database Transaction Pattern (Prisma)

Atomic operations with balance checks — a core production pattern:

const smsId = await prisma.$transaction(async (tx: any) => {
  // Atomic balance deduction with optimistic locking
  const updatedUser = await tx.user.updateMany({
    where: {
      id: user.id,
      balance: { gte: totalCost },  // Prevents negative balance
    },
    data: { balance: { decrement: totalCost } },
  });

  if (updatedUser.count === 0) {
    throw new Error(
      `Insufficient balance. Required: €${totalCost.toFixed(4)}, Available: €${Number(user.balance).toFixed(2)}`
    );
  }

  // Create transaction record
  await tx.transaction.create({
    data: {
      user_id: user.id,
      type: "SMS_COST",
      amount: totalCost,
      status: "FINISHED",
      order_id: `sms_${user.id}_${nanoid(10)}`,
    },
  });

  // Create the resource
  const log = await tx.smsLog.create({
    data: { user_id: user.id, recipient_number: to, message_content: message, status: "QUEUED", cost: totalCost },
  });

  return log.id;
});

12.5 Webhook Pattern (No Auth)

External webhooks (Telegram, payment callbacks) skip auth middleware:

// No MIDDLEWARE_ export for /telegram/webhook* prefix = no auth

export const POST_telegram_webhook1: JetRoute<{ body: any }> = async function (ctx) {
  try {
    const update = await ctx.parse();

    // Process asynchronously — respond immediately
    handleTelegramWebhook(update, 1).catch((error) => {
      console.error("Telegram webhook processing error:", error);
    });

    ctx.send({ ok: true });
  } catch (error) {
    console.error("Telegram webhook error:", error);
    ctx.send({ ok: false }, 500);
  }
};

12.6 Auth Route Pattern (Login)

export const POST_auth_login: JetRoute<{
  body: { password: string; email: string; turnstileToken: string };
}> = async function (ctx) {
  const { email, password } = await ctx.parse();
  if (!email || !password) {
    ctx.plugins.throw(400, "Email and password are required");
    return;
  }

  const user = await prisma.user.findUnique({
    where: { email: email.toLowerCase().trim() },
  });
  if (!user) {
    ctx.plugins.throw(400, "Invalid email/username or password");
    return;
  }
  if (!user.is_active) {
    ctx.plugins.throw(400, "Account is not accessible");
    return;
  }

  const isValid = await bcrypt.compare(password, user.password_hash);
  if (!isValid) {
    ctx.plugins.throw(400, "Invalid email/username or password");
    return;
  }

  await prisma.user.update({
    where: { id: user.id },
    data: { last_login_at: new Date() },
  });

  const token = await auth.create({ id: user.id });
  const { password_hash, ...userResponse } = user;

  ctx.send({ data: { user: userResponse, token }, ok: true });
};

use(POST_auth_login).body((t) => ({
  email: t.string({ err: "Invalid email format" }).required().default("user@example.com"),
  password: t.string({ err: "Password is required" }).required().default("password123"),
  turnstileToken: t.string().optional().default(""),
}));

12.7 OAuth Redirect Pattern

export const GET_auth_google: JetRoute = (ctx) => {
  ctx.redirect(googleAuthUrl);
};

export const GET_auth_google_callback: JetRoute<{
  query: { code: string };
}> = async (ctx) => {
  const { code } = ctx.parseQuery();
  try {
    const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, code, redirect_uri: REDIRECT_URI, grant_type: "authorization_code" }),
    });
    if (!tokenResponse.ok) { ctx.redirect(`${client_link}/login?error=oauth_failed`); return; }

    const { access_token } = await tokenResponse.json();
    // ... find/create user, generate token ...

    ctx.redirect(`${client_link}/login?success=true&token=${token}`);
  } catch (error) {
    ctx.redirect(`${client_link}/login?error=oauth_error`);
  }
};

12.8 CSV Export Pattern

export const POST_hlr_export: JetRoute<{ body: { results: any[] } }> = async function (ctx) {
  const { results } = await ctx.parse();
  if (!results || results.length === 0) {
    ctx.plugins.throw(400, "No results to export");
    return;
  }

  const csvLines = ["Phone Number,Number Type,Status"];
  for (const result of results) {
    const row = [result.phone_number, result.number_type, result.status];
    const escaped = row.map((f) => {
      const s = String(f);
      return s.includes(",") || s.includes('"') ? `"${s.replace(/"/g, '""')}"` : s;
    });
    csvLines.push(escaped.join(","));
  }

  ctx.set("Content-Type", "text/csv");
  ctx.set("Content-Disposition", `attachment; filename="export-${new Date().toISOString().replace(/[:.]/g, "-")}.csv"`);
  ctx.send(csvLines.join("\n"));
};

12.9 Async Fire-and-Forget

Use queueMicrotask() for non-blocking background work after responding:

ctx.send({ messageId: smsId, status: "queued" });

// Process SMS queue AFTER response is sent
queueMicrotask(() => {
  processSMSQueue();
});

12.10 Non-Route Exports from .jet.ts Files

.jet.ts files can export regular functions/constants that don't match the METHOD_path pattern. They won't become routes:

// notification.jet.ts — this is just a helper function, not a route
export const sendNotification = async (user_id: string, message: string, title: string) => {
  const notification = await prisma.notification.create({
    data: { user_id, content: message, title },
  });
  return notification;
};

// This IS a route:
export const GET_user_notifications: JetRoute = async (ctx) => { /* ... */ };

12.11 IP Whitelisting Pattern

const ipWhitelist: string[] = (process.env.IP_WHITELIST || "")
  .split(",")
  .map((s) => s.trim())
  .filter(Boolean);

function getClientIp(ctx: any): string {
  const xff = ctx.get("x-forwarded-for");
  const direct = (xff && xff.split(",")[0]) || ctx.request.socket?.remoteAddress || ctx.request.ip || "";
  return String(direct).replace(/^::ffff:/, "");
}

// In handler:
const clientIp = getClientIp(ctx);
if (ipWhitelist.length && !ipWhitelist.includes(clientIp)) {
  ctx.send({ success: true, message: "Access denied", blocked: true });
  return;
}

13. Critical Rules & Gotchas

1. ctx.parse() is async — always await it.
2. ctx.parseQuery() is synchronous — no await.
3. Always return after ctx.plugins.throw() or error ctx.send() — execution continues otherwise.
4. .jet.ts extension is mandatory for route files. Regular .ts files are NOT scanned.
5. use() must be called at module scope (top-level, not inside functions). It attaches schemas to the function object.
6. Validation happens lazily: body validation at ctx.parse() time, query validation at ctx.parseQuery() time.
7. Unknown body fields are stripped by the validator (mass-assignment protection).
8. WebSockets require upgrade: true in constructor. Only Bun/Deno.
9. Plugin executor() methods get this bound to ctx at runtime.
10. Middleware matching is by path prefix: MIDDLEWARE_admin → matches /admin/*.
11. Duplicate routes throw: Each METHOD + path combination must be unique.
12. Context objects are pooled — don't hold references after handler completes.
13. sendResponse() only works on Bun/Deno — not Node.js.
14. Double underscores __ become hyphens - in route paths: POST_deposits__2 → POST /deposits-2.
15. $0 is the wildcard (catch-all) — accessed via ctx.params["*"].
16. $paramName becomes :paramName — accessed via ctx.params.paramName.
17. Middleware can be a single function or an array — use as any for array casting when needed.
18. default() values in validation schemas appear as placeholder values in the auto-generated API documentation.