Quick start

This page builds a small users API from an empty folder: three routes, a validated body, an error of your own and a test. It needs only Bun.

Create the project

mkdir users-api && cd users-api
bun init -y
bun add @tetsujs/core zod

bun init already sets up TypeScript the way Tetsu needs. To add Tetsu to an existing project, see Installation.

Declare the routes

A controller is a name and a function from its dependencies to its routes. Here a Map stands in for a database:

src/users.ts

import { controller, httpError, route } from "@tetsujs/core";
import { z } from "zod";

export interface User {
  id: number;
  name: string;
  email: string;
}

const NewUser = z.object({ name: z.string().min(1), email: z.email() });
const UserId = z.object({ id: z.coerce.number().int().positive() });

export const usersController = controller("Users", (users: Map<number, User>) => ({
  list: route({
    method: "GET",
    path: "/users",
    handler: () => [...users.values()],
  }),

  get: route({
    method: "GET",
    path: "/users/:id",
    schema: { params: UserId },
    handler: (ctx) => {
      const user = users.get(ctx.params.id);
      if (!user) throw httpError(404, "USER_NOT_FOUND", "No such user");
      return user;
    },
  }),

  create: route({
    method: "POST",
    path: "/users",
    schema: { body: NewUser },
    handler: (ctx) => {
      const user = { id: users.size + 1, ...ctx.body };
      users.set(user.id, user);
      ctx.out.status = 201;
      return user;
    },
  }),
}));

• ctx.params.id is a number: the schema converts the :id segment before the handler runs, and /users/abc never reaches it.
• ctx.body exists only on create, the route with a body schema, and has the schema’s type.
• httpError(404, "USER_NOT_FOUND", …) is your own error, in the same shape as the framework’s.

Serve it

createApp turns the routes into plain data that Bun.serve takes as it is:

index.ts

import { createApp } from "@tetsujs/core";
import type { User } from "./src/users";
import { usersController } from "./src/users";

const users = new Map<number, User>();

const app = createApp({ routes: usersController(users) });

Bun.serve({ ...app, port: 3000 });

console.log("Listening on http://localhost:3000");

bun --watch index.ts

Try it

curl -X POST localhost:3000/users -d '{"name":"Ada","email":"ada@example.com"}'

{ "id": 1, "name": "Ada", "email": "ada@example.com" }

The body is parsed as JSON, the route’s default, whatever content-type the client sends (curl’s -d sends a form type). A request the schema refuses gets a 422 with every issue at once:

curl -X POST localhost:3000/users -d '{"name":"","email":"nope"}'

{
  "status": 422,
  "message": "Validation failed",
  "error": "VALIDATION_FAILED",
  "issues": [
    { "message": "Too small: expected string to have >=1 characters", "path": ["body", "name"] },
    { "message": "Invalid email address", "path": ["body", "email"] }
  ]
}

Your own error has the same shape:

curl localhost:3000/users/7

{ "status": 404, "message": "No such user", "error": "USER_NOT_FOUND" }

Test it

Routing is Bun’s, and only a real socket reaches it. serve() from @tetsujs/core/testing starts the application on a free port and stops it when the test file finishes:

src/users.test.ts

import { createApp } from "@tetsujs/core";
import { serve } from "@tetsujs/core/testing";
import { expect, test } from "bun:test";
import { usersController } from "./users";

const request = serve(createApp({ routes: usersController(new Map()) }));

test("creates a user and reads it back", async () => {
  const created = await request("/users", {
    method: "POST",
    body: JSON.stringify({ name: "Ada", email: "ada@example.com" }),
  });

  expect(created.status).toBe(201);
  expect(await (await request("/users/1")).json()).toEqual({
    id: 1,
    name: "Ada",
    email: "ada@example.com",
  });
});

bun test

Where to go next

• Key concepts — the whole model on one page.
• Lifecycle hooks — authentication, logging and whatever else runs around a handler.
• Structuring an application — where things go once there is more than one controller.