YATTA
Docs
API reference

yatta/api

File-based routing, request context, and validation.

15 exported symbols and 66 members, read from src/types/api.ts.

Construct

createAPI

function

Factory creating a typed router instance.

createAPI<Path extends string>(path?: Path): API<ExtractRouteParams<Path>>

Also accepts

createAPI(): API<RouteParams>
createAPI(_path?: string): API<any>
path
Optional route path pattern to infer typed parameters.

Returns A configured `API` instance.

tsts
// 1. Unparameterized routerconst api = createAPI();api.get((ctx) => API.json({ ok: true })); // 2. Typed parameterized routerconst userApi = createAPI("/users/[id]");userApi.get((ctx) => {  // ctx.params.id is statically typed as string  return API.json({ userId: ctx.params.id });});

routeRequest

async function

Dispatches an incoming HTTP `Request` through Bun's FileSystemRouter to matching backend route files.

routeRequest(req: Request): Promise<Response>
req
Incoming HTTP Request.

Returns Response produced by the matched route handler or 404/500 response.

API

class

Lightweight, high-performance HTTP API router and middleware engine.

class API
tsts
const api = createAPI(); api.use(async (ctx, next) => {  console.log(`${ctx.req.method} ${ctx.url.pathname}`);  return await next();}); api.get(async (ctx) => {  return API.json({ status: "healthy" });}); export default api;

38 members

  • routesproperty
    routes:
  • subRoutesproperty
    subRoutes: Array<{ method: Method; path: string; handler: Handler<any>; }>
  • middlewareStackproperty
    middlewareStack: Middleware<TParams>[]
  • errorHandlerproperty
    errorHandler?: ErrorHandler<TParams>
  • corsOptionsproperty
    corsOptions?: CorsOptions
  • get
    get(handler: Handler<TParams>): this

    Registers a GET route handler for the root endpoint of this route module.

    handler
    Handler function processing the request.
  • get
    get(path: string, handler: Handler<any>): this

    Registers a GET route handler for an explicit sub-path.

    path
    Sub-path string (e.g. `"/details"`).
    handler
    Handler function processing the request.
  • get
    get(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • post
    post(handler: Handler<TParams>): this

    Registers a POST route handler for the root endpoint.

    handler
    Handler function processing the request.
  • post
    post(path: string, handler: Handler<any>): this

    Registers a POST route handler for an explicit sub-path.

    path
    Sub-path string (e.g. `"/checkout"`).
    handler
    Handler function processing the request.
  • post
    post(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • put
    put(handler: Handler<TParams>): this

    Registers a PUT route handler for the root endpoint.

    handler
    Handler function processing the request.
  • put
    put(path: string, handler: Handler<any>): this

    Registers a PUT route handler for an explicit sub-path.

    path
    Sub-path string.
    handler
    Handler function processing the request.
  • put
    put(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • patch
    patch(handler: Handler<TParams>): this

    Registers a PATCH route handler for the root endpoint.

    handler
    Handler function processing the request.
  • patch
    patch(path: string, handler: Handler<any>): this

    Registers a PATCH route handler for an explicit sub-path.

    path
    Sub-path string.
    handler
    Handler function processing the request.
  • patch
    patch(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • delete
    delete(handler: Handler<TParams>): this

    Registers a DELETE route handler for the root endpoint.

    handler
    Handler function processing the request.
  • delete
    delete(path: string, handler: Handler<any>): this

    Registers a DELETE route handler for an explicit sub-path.

    path
    Sub-path string.
    handler
    Handler function processing the request.
  • delete
    delete(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • head
    head(handler: Handler<TParams>): this

    Registers a HEAD route handler for the root endpoint.

    handler
    Handler function processing the request.
  • head
    head(path: string, handler: Handler<any>): this

    Registers a HEAD route handler for an explicit sub-path.

    path
    Sub-path string.
    handler
    Handler function processing the request.
  • head
    head(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • options
    options(handler: Handler<TParams>): this

    Registers an OPTIONS route handler for the root endpoint.

    handler
    Handler function processing the request.
  • options
    options(path: string, handler: Handler<any>): this

    Registers an OPTIONS route handler for an explicit sub-path.

    path
    Sub-path string.
    handler
    Handler function processing the request.
  • options
    options(pathOrHandler: string | Handler<TParams>, maybeHandler?: Handler<any>): this
  • use
    use(middleware: Middleware<TParams>): this

    Attaches an onion-style middleware to the API execution pipeline.

    middleware
    Middleware function receiving `ctx` and `next()`.

    Returns Current API instance for fluent chaining.

    tsts
    api.use(async (ctx, next) => {  const token = ctx.header("Authorization");  if (!token) throw new HttpError(401, "Missing token");  return await next();});
  • onError
    onError(handler: ErrorHandler<TParams>): this

    Registers a custom centralized error handler for this API instance.

    handler
    Error handler function.

    Returns Current API instance for fluent chaining.

    tsts
    api.onError((err, ctx) => {  if (err instanceof ValidationError) {    return API.json({ errors: err.details }, { status: 400 });  }  return API.json({ error: "Internal Error" }, { status: 500 });});
  • cors
    cors(options?: CorsOptions): this

    Enables CORS headers on all route responses and automatically handles OPTIONS preflights.

    options
    Configuration for allowed origins, headers, methods, credentials, and maxAge.

    Returns Current API instance for fluent chaining.

    tsts
    api.cors({  origin: "https://myfrontend.com",  credentials: true,  methods: ["GET", "POST", "DELETE"],});
  • json
    json<T>(data: T, init?: ResponseInit): Response

    Creates a JSON HTTP `Response` with `Content-Type: application/json; charset=utf-8`.

    data
    The JavaScript value or object to JSON-encode.
    init
    Optional response initialization options (status, headers, etc.).

    Returns Standard `Response` object.

    tsts
    return API.json({ success: true, count: 5 }, { status: 200 });
  • text
    text(data: string, init?: ResponseInit): Response

    Creates a plain text HTTP `Response` with `Content-Type: text/plain; charset=utf-8`.

    data
    Text string content.
    init
    Optional response initialization options.

    Returns Standard `Response` object.

    tsts
    return API.text("OK", { status: 200 });
  • stream
    stream(body: ReadableStream, init?: ResponseInit): Response

    Creates a streaming HTTP `Response` from a `ReadableStream`.

    body
    The `ReadableStream` providing streaming data chunks.
    init
    Optional response initialization options (headers, status).

    Returns Standard streaming `Response`.

    tsts
    return API.stream(stream, {  headers: { "Content-Type": "text/event-stream" }});
  • cookie
    cookie(name: string, value: string, options?: CookieOptions): string

    Formats a name-value pair into a standard `Set-Cookie` header value string.

    name
    Cookie name.
    value
    Cookie string value.
    options
    Cookie options (maxAge, path, domain, httpOnly, secure, sameSite).

    Returns Formatted cookie header string.

    tsts
    const cookieStr = API.cookie("auth_token", token, {  httpOnly: true,  secure: true,  maxAge: 3600,  sameSite: "Lax"});
  • withCookies
    withCookies(response: Response, cookies: string[]): Response

    Attaches one or more `Set-Cookie` header strings to an existing `Response`.

    response
    Original `Response` object.
    cookies
    Array of formatted cookie strings (e.g. from `API.cookie()`).

    Returns New `Response` containing the attached `Set-Cookie` headers.

    tsts
    const cookie = API.cookie("session", id, { httpOnly: true });return API.withCookies(API.json({ ok: true }), [cookie]);
  • applyCors
    applyCors(response: Response, req: Request): Response
  • dispatchError
    dispatchError(error: unknown, ctx: Context<TParams>): Promise<Response>
  • handle
    handle(req: Request, params: TParams, basePath?: string): Promise<Response>

    Processes an incoming HTTP `Request`, executes middleware pipeline, matches route handlers,

    req
    The raw incoming HTTP Request.
    params
    Extracted path parameters.
    basePath
    Optional base path prefix if mounted as a sub-router.

    Returns Promise resolving to the final HTTP `Response`.

  • runMiddleware
    runMiddleware(ctx: Context<TParams>, handler: Handler<TParams>): Promise<Response>

Context

class

Encapsulates the incoming HTTP request context for route handlers and middleware.

class Context
tsts
api.get(async (ctx) => {  const query = ctx.query();  const userId = ctx.params.id;  const authUser = ctx.state.user;  return API.json({ query, userId, authUser });});

13 members

  • reqproperty
    req: Request

    The native web-standard object.

  • paramsproperty
    params: TParams

    Strongly-typed route parameters extracted from the URL path.

  • urlproperty
    url: URL

    The parsed of the current request.

  • stateproperty
    state: Record<string, unknown>

    Mutable dictionary for middleware to share request-scoped data

  • cachedCookiesproperty
    cachedCookies?: Record<string, string>
  • rawBodyParsedproperty
    rawBodyParsed:
  • rawBodyDataproperty
    rawBodyData: unknown
  • rawFormDataproperty
    rawFormData?: FormData
  • query
    query(): Record<string, string>

    Returns all query parameters as a key-value dictionary.

    tsts
    // GET /search?q=bun&limit=10const { q, limit } = ctx.query();
  • json
    json<T = unknown>(schema?: Validator<T>): Promise<T>

    Parse and optionally validate the JSON request body.

    schema
    Optional schema validator (Zod, Valibot, ArkType) with a `.parse()` method.

    Returns The parsed and validated body.

    tsts
    // Without schema:const body = await ctx.json<{ name: string }>(); // With Zod schema:import { z } from "zod";const schema = z.object({ email: z.string().email(), age: z.number().min(18) });const data = await ctx.json(schema);
  • formData
    formData<T = FormData>(schema?: Validator<T>): Promise<T>

    Parse and optionally validate `multipart/form-data` or `application/x-www-form-urlencoded`.

    schema
    Optional schema validator with a `.parse()` method.

    Returns Parsed `FormData` or validated output.

    tsts
    const form = await ctx.formData();const avatarFile = form.get("avatar") as File;
  • cookies
    cookies(): Record<string, string>

    Parses and decodes the incoming `Cookie` header into a key-value dictionary.

    Returns Record of cookie names and their decoded values.

    tsts
    const { session_token } = ctx.cookies();
  • header
    header(name: string): string | null

    Retrieves an incoming HTTP request header value by case-insensitive name.

    name
    Header name (e.g. `"authorization"`, `"user-agent"`).

    Returns Header value string or `null` if not present.

    tsts
    const authHeader = ctx.header("Authorization");

HttpError

class

Thrown to immediately abort handler execution with an explicit HTTP status code.

class HttpError extends Error
tsts
if (!user) {  throw new HttpError(404, "User not found", { userId });}

2 members

  • statusproperty
    status: number

    HTTP response status code (e.g. 400, 401, 403, 404, 500).

  • detailsproperty
    details?: unknown

    Optional arbitrary metadata or validation issues attached to the error.

ValidationError

class

Thrown when request body or form parsing/validation fails (HTTP 400 Bad Request).

class ValidationError extends HttpError

1 member

  • causeproperty
    cause: unknown

    The underlying parser or validator error that caused the validation failure.

Types

CookieOptions

interface

Configuration options for generating `Set-Cookie` HTTP response headers.

interface CookieOptions

6 members

  • maxAgeproperty
    maxAge?: number

    Max-Age in seconds determining how long the client should store the cookie.

  • pathproperty
    path?: string

    The URL path that must exist in the requested URL for the cookie to be sent.

  • domainproperty
    domain?: string

    The host/domain to which the cookie will be sent.

  • httpOnlyproperty
    httpOnly?: boolean

    Forbids client-side JavaScript access via `Document.cookie` to prevent XSS theft.

  • secureproperty
    secure?: boolean

    Ensures the cookie is only transmitted over secure HTTPS connections.

  • sameSiteproperty
    sameSite?: "Strict" | "Lax" | "None"

    Controls whether the cookie is sent with cross-site requests to mitigate CSRF attacks.

CorsOptions

interface

Configuration options for Cross-Origin Resource Sharing (CORS).

interface CorsOptions

5 members

  • originproperty
    origin?: string

    Allowed origin header value (e.g. `"https://example.com"` or `"*"`).

  • methodsproperty
    methods?: Method[]

    List of allowed HTTP methods for CORS requests.

  • headersproperty
    headers?: string[]

    List of allowed request headers (e.g. `["Content-Type", "Authorization"]`).

  • credentialsproperty
    credentials?: boolean

    Whether to include `Access-Control-Allow-Credentials: true` to permit cookies/auth tokens.

  • maxAgeproperty
    maxAge?: number

    Maximum duration in seconds that preflight OPTIONS results can be cached by the browser.

Validator

interface

Schema validator interface compatible with Zod, Valibot, ArkType, or custom parsers.

interface Validator<T>
tsts
import { z } from "zod";const userSchema: Validator<{ name: string }> = z.object({ name: z.string() });const user = await ctx.json(userSchema);

1 member

  • parse
    parse(data: unknown): T

    Validates and transforms the incoming data, throwing an error if validation fails.

    data
    Raw unvalidated data.

    Returns Typed and sanitized value.

ErrorHandler

type

Centralized error handler invoked when an uncaught error or is thrown.

type ErrorHandler<TParams extends RouteParams = RouteParams> = (error: unknown, ctx: Context<TParams>) => Response | Promise<Response>
error
The thrown error or exception.
ctx
The typed request context.

Returns A web-standard `Response` formatted for the client.

tsts
api.onError((err, ctx) => {  console.error("Unhandled route error:", err);  return API.json({ error: "Something went wrong" }, { status: 500 });});

ExtractRouteParams

type

Infers typed route parameter dictionary from a path literal string at compile time.

type ExtractRouteParams<Path extends string> = Path extends `${infer _Start}[${infer Param}]${infer Rest}` ? { [K in CleanParam<Param> | keyof ExtractRouteParams<Rest>]: string; } : {}
tsts
type Params = ExtractRouteParams<"/orgs/[orgId]/teams/[teamId]">;// => { orgId: string; teamId: string }

Handler

type

Request handler function executed when an HTTP route is matched.

type Handler<TParams extends RouteParams = RouteParams> = (ctx: Context<TParams>) => Response | Promise<Response>
ctx
The typed request context containing `req`, `params`, `query()`, `json()`, etc.

Returns A web-standard `Response` or a promise resolving to a `Response`.

tsts
const handler: Handler<{ id: string }> = async (ctx) => {  return API.json({ userId: ctx.params.id });};

Method

type

Supported HTTP method strings.

type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS"

Middleware

type

Onion-style middleware function executed in the request pipeline.

type Middleware<TParams extends RouteParams = RouteParams> = (ctx: Context<TParams>, next: () => Response | Promise<Response>) => Response | Promise<Response>
ctx
The typed request context.
next
Function to invoke the next middleware or final route handler in the chain.

Returns A web-standard `Response` or a promise resolving to a `Response`.

tsts
api.use(async (ctx, next) => {  const start = performance.now();  const response = await next();  const duration = performance.now() - start;  response.headers.set("X-Response-Time", `${duration.toFixed(2)}ms`);  return response;});

RouteParams

type

============================================================================

OVERVIEW: Provides lightweight, high-performance HTTP routing, onion middleware pipelines, type-safe route parameter extraction, schema validation (Zod, Valibot, ArkType), spec-compliant CORS preflight, cookie parsing & encoding, and streaming responses. KEY EXPORTS: - `createAPI(path?)`: Factory to instantiate an `API` router instance. - `API`: Class managing HTTP method handlers (`.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`), middleware (`.use()`), error handling (`.onError()`), and CORS (`.cors()`). Supports static response helpers: `API.json()`, `API.text()`, `API.stream()`, `API.cookie()`. - `Context`: Rich request wrapper passed into handlers/middleware offering: - `ctx.req`: Native `Request` object. - `ctx.params`: Typed route parameters inferred from path strings (e.g. `[id]`). - `ctx.query()`: Parsed query string dictionary. - `ctx.json(schema?)`: Safe body parser with optional validator parsing. - `ctx.formData(schema?)`: Multipart/urlencoded parser. - `ctx.cookies()`: Request cookies decoded into key-value map. - `ctx.state`: Mutable context bag for middleware state sharing (e.g. auth user). - `HttpError` & `ValidationError`: Standard status-carrying error classes. - `routeRequest(req)`: FileSystemRouter dispatcher for Next.js-style file-based APIs. QUICKSTART / USAGE: ```ts // src/backend/user/index.ts import { API, createAPI } from "../../types/api"; import { z } from "zod"; const api = createAPI(); // Middleware api.use(async (ctx, next) => { ctx.state.startTime = Date.now(); return await next(); }); // GET /user api.get(async (ctx) => { return API.json({ user: "Alice", query: ctx.query() }); }); // POST /user api.post(async (ctx) => { const body = await ctx.json(z.object({ name: z.string() })); return API.json({ created: body.name }, { status: 201 }); }); export default api; ``` Route parameter map representing key-value pairs extracted from dynamic URL paths.

type RouteParams = Record<string, string>
tsts
// For route "/users/[id]" visited at "/users/42"const params: RouteParams = { id: "42" };
Tip
Most of the types above are inferred. You rarely import AuthConfig or JobPayload — declaring your schema once is enough for the rest to follow. See Typed keys.