A small TypeScript layer for controller routing, validation, and OpenAPI—now ready to listen after bootstrap while carrying your Koa state and context types end to end.
import Koa from 'koa';
import {bootstrapControllers} from 'amala';
interface State {
user?: User;
services: Services;
}
interface Context {
requestId: string;
}
const app = new Koa<State, Context>();
async function main() {
await bootstrapControllers({
app,
controllers: [UserController],
});
app.listen(3000);
}
void main();
Still just Koa
Define Koa state and context extensions once. Amala preserves them through middleware, controller creation, error handling, and the app and router it returns.
Compile-time guardrails. Undeclared context properties stop becoming silent any values.
No new runtime model. Koa remains Koa; application middleware still owns application state.
type AppContext = AmalaContext<State, Context>;
const authorize: AmalaMiddleware<State, Context> =
async (ctx, next) => {
ctx.state.user = await authenticate(ctx);
ctx.requestId = crypto.randomUUID();
// Fully typed in middleware, factories,
// error handlers, and returned app/router.
await next();
};
async function main() {
const {app} = await bootstrapControllers<State, Context>({
controllers: [UserController],
flow: [authorize],
});
app.listen(3000);
}
void main();
Small framework surface
A controller prefix and an HTTP decorator become a real Koa route. Bootstrap mounts it and returns the app.
@Controller('/users')
class UserController {
@Get('/:id')
getOne(@Params('id') id: string) {
return {id};
}
}
async function main() {
const {app} = await bootstrapControllers({
controllers: [UserController],
});
app.listen(3000);
}
void main();
Inject only what a handler needs. The method signature documents the request instead of hiding it in context access.
@Controller('/search')
class SearchController {
@Get('/')
find(@Query('q') query?: string) {
return {query};
}
}
async function main() {
const {app} = await bootstrapControllers({
controllers: [SearchController],
});
app.listen(3000);
}
void main();
A decorated class becomes a runtime request boundary, with strict unknown-field handling selected at bootstrap.
class CreateUserInput {
@IsEmail()
email!: string;
}
@Controller('/users')
class UserController {
@Post('/')
create(@Body({required: true}) input: CreateUserInput) {
return input;
}
}
async function main() {
const {app} = await bootstrapControllers({
controllers: [UserController],
validatorOptions: {
forbidNonWhitelisted: true,
whitelist: true,
},
});
app.listen(3000);
}
void main();
Configure the generated OpenAPI document beside the controllers it describes. Swagger stays on the same origin.
async function main() {
const {app} = await bootstrapControllers({
basePath: '/api',
controllers: [UserController],
openAPI: {
spec: {
info: {
title: 'Example API',
version: '1.0.0',
},
},
},
});
app.listen(3000);
}
void main();
Own the boundary
Types prevent accidental access; they do not authenticate users or validate values at runtime. Amala validates request inputs while your middleware owns identity, authorization, and application state.
Review the security guideChoose your path