Decorators
Standard TC39 decorators: no experimentalDecorators, no reflect-metadata, no compiler flags.
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.
@Module({
providers: [UsersService],
controllers: [UsersController],
})
export class UsersModule {}
export class UsersService {
readonly #repository = inject(UsersRepository)
}$ 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.
Validationimport { 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) {}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" }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 }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.
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.
@getsoda/core/openapiOpenAPIThe document and a Swagger UI page from the parsers and schemas that already validate your routes. Nothing written twice.@getsoda/core/jwtJWTSigns and verifies with WebCrypto, without dependencies. The algorithm comes from the options, never from the token.@getsoda/core/throttlerRate limitingPer client and route, 429 with Retry-After.@getsoda/core/cqrsCQRSCommand, query and event buses. execute() resolves with the type the command declares.@getsoda/core/testingTestingThe app on a free port, any provider replaced.@getsoda/coreWebSocketsGateways on Bun's native WebSockets and pub/sub.@getsoda/coreServer-sent eventsAn async generator, streamed as text/event-stream.@getsoda/coreConfigurationThe environment as a schema, validated at startup, injected with its type.@getsoda/coreCookiesBun's CookieMap, and signed cookies a client can read but not forge.@getsoda/coreLoggingAn injectable Logger with levels and contexts, lines or JSON.@getsoda/coreGraceful shutdownRequests in flight finish before services are destroyed.@getsoda/coreCORSMiddleware that runs before routing, preflights included.bun devHot reloadRuns with bun --hot: changes apply without a restart.
Start in one command
bun create soda