Modern class-based web framework over Bun

Structured TypeScript APIs at the speed of Bun

bun create soda
Documentation

Decorators

Standard TC39 decorators: no experimentalDecorators, no reflect-metadata, no compiler flags.

Controllers in the docs

Values01 / 07

List what a route needs: it arrives read, converted and validated, or the request gets a 400. Or take the context and read it yourself.

@Get(':id', [param('id', int)])
findOne(id: number) {
  return this.#users.find(id)
}

// or read it from the context
@Get(':id')
findOne(ctx: Context<':id'>) {
  return this.#users.find(ctx.param('id'))
}

Routes02 / 07

A decorator for every HTTP method, @Route for any other. Paths join the controller's.

@Controller('users')
export class UsersController {
  @Get() list() {}
  @Post() create() {}
  @Put(':id') replace() {}
  @Patch(':id') update() {}
  @Delete(':id') remove() {}
  @All('legacy/*') legacy() {}
}

Pipeline03 / 07

Guards decide, interceptors wrap the handler, filters turn errors into responses. On a class or on a method.

@UseGuards(AuthGuard)
@UseInterceptors(TimingInterceptor)
@UseFilters(NotFoundFilter)
export class AdminController {}

Response04 / 07

The status and fixed headers, declared next to the route.

@Delete(':id', [param('id', int)])
@HttpCode(204)
@Header('cache-control', 'no-store')
remove(id: number) {}

Rate limits05 / 07

Per route, over the global limits. Past them, 429 with Retry-After.

@Post('login')
@Throttle({ default: { limit: 5, ttl: 60_000 } })
login() {}

Streams06 / 07

Return an async generator: it is streamed as server-sent events, and stopped when the client leaves.

@Sse('ticks')
async *ticks(): AsyncGenerator<SseMessage> {
  for (let i = 0; ; i++) {
    yield { data: { tick: i } }
    await Bun.sleep(1000)
  }
}

Your own07 / 07

createDecorator() stores a value on a route; a guard reads it with ctx.metadata().

export const Roles = createDecorator<string[]>('Roles')

@Delete(':id', [param('id', int)])
@Roles(['admin'])
@UseGuards(AuthGuard, RolesGuard)
remove(id: number) {}

Modules & DI

Wiring mistakes fail at startup, not on a request.

Modules group controllers and providers. A class asks for what it needs with inject(), typed by its token. The whole graph is checked when the application starts: a missing provider, a cycle or a provider that is not exported stops it with the chain that led there and the fix.

Providers and modules
UsersRepository is not provided
@Module({
  providers: [UsersService],
  controllers: [UsersController],
})
export class UsersModule {}

export class UsersService {
  readonly #repository = inject(UsersRepository)
}
Terminal
$ bun dev
DiError: No provider for UsersRepository in UsersModule
(UsersService → UsersRepository)
Add it to the providers of UsersModule, or import a module that exports it.
    at new UsersService (src/users/users.service.ts:4:24)

Validation

One schema, three jobs.

Any Standard Schema library: zod, valibot, arktype. No DTO classes, no decorators on every field.

Validation
The schema
import { z } from 'zod'

const CreateUser = z.object({
  name: z.string().min(1),
  email: z.email(),
  age: z.number().int().optional(),
})

type CreateUser = z.infer<typeof CreateUser>

@Post([body(CreateUser)])
create(input: CreateUser) {}
  1. Checks the request

    A body the schema refuses gets a 400, every issue listed.

    {
      "statusCode": 400,
      "message": [
        "name: Too small: expected string to have >=1 characters",
        "email: Invalid email address"
      ],
      "error": "Bad Request"
    }
  2. Types the handler

    The type comes from the schema. Nothing to keep in sync.

    create(input) {
      input.name   // string
      input.email  // string
      input.age    // number | undefined
    }
  3. Documents the route

    In /openapi.json and Swagger UI, with no extra decorators.

    POST /users
      body
        name   string    required
        email  string    required
        age    integer

Speed

Routes compile into Bun's native router, Bun.serve({ routes }): a route without guards adds about 0.1 ns to calling its handler.

The benchmark
2×the requests per second of Nest on Fastify, on par with Hono
  • Soda103,774
  • Hono102,663
  • Nest (Fastify)51,661
  • Nest (Express)43,991

Requests per second, average of GET /, GET /id/:id?name=, POST /json. Apple M1, 8 cores, 8 GB; Bun 1.4.3; hono 4.13.18, @nestjs/core 12.5.0, @getsoda/core 0.3.0 from this repository. oha, 100 connections, 5 s per scenario after 3 s of warm-up; median of 3 rounds; successful responses only.

Included

One package, @getsoda/core, with entry points for what an API needs.

Start in one command

bun create soda
Documentation