A tiny decorator-based framework for HTTP, command-line and message applications. Standard decorators, no reflection, the same code on Deno, Node.js, Bun and the edge.
One codebase runs on
Modules group providers and controllers, and decorators say how they fit together. An HTTP service, a command-line tool and a message consumer are the same three things, with a route, a command or a topic on the method.
@chojs/web: routes, typed arguments, validation, server-sent events.@chojs/command: declared flags, generated help, exit codes.@chojs/message: one handler for a topic, acknowledged after it returns.import {
ChoWeb,
type ChoWebContext,
Controller,
Get,
Injectable,
Module,
} from "@chojs/web";
@Injectable()
class UserStore {
find(id: string) {
return { id, name: "Ada" };
}
}
@Controller({ route: "users", dependencies: [UserStore] })
class UsersController {
constructor(readonly store: UserStore) {}
@Get(":id") // GET /users/42
get(ctx: ChoWebContext) {
return this.store.find(ctx.params.id!); // sent as JSON
}
}
@Module({ providers: [UserStore], controllers: [UsersController] })
class App {}
const app = await ChoWeb.create(App);import {
Action,
ChoCommand,
type ChoCommandContext,
Controller,
Help,
Module,
} from "@chojs/command";
@Controller()
class Greeter {
@Help("Say hello")
@Action("hello", { string: ["name"] })
hello(ctx: ChoCommandContext) {
console.log(`Hello, ${ctx.args.name ?? "world"}!`);
}
}
@Module({ controllers: [Greeter] })
class App {}
const app = ChoCommand.create(App, { name: "greet" });
const code = await app.run(Deno.args); // the exit codeimport {
ChoMessage,
type ChoMessageContext,
Controller,
Module,
Subscribe,
} from "@chojs/message";
@Controller({ topic: "orders" })
class OrdersController {
@Subscribe("created") // the topic orders.created
created(ctx: ChoMessageContext) {
console.log(ctx.key, ctx.json());
// returning without an error: the message is handled
}
}
@Module({ controllers: [OrdersController] })
class App {}
const app = await ChoMessage.create(App);
await app.handle("orders.created", { key: "42", value: '{"id":"42"}' });A handler receives the standard Request and answers with a standard Response. What matches the requests underneath is a small adapter you can swap, and the runtime is a line you do not write.
URLPattern.serve(app.handler) picks the server of the runtime it runs on.CHO runs with TC39 decorators, and with the legacy ones of TypeScript and Bun. Dependencies are declared, not guessed from emitted types, and the compiler checks them against the constructor.
reflect-metadata, no emitDecoratorMetadata.const PORT = token<number>("PORT");
@Injectable([Logger, PORT]) // in constructor order
class Server {
constructor(logger: Logger, port: number) {}
}
@Injectable([PORT, Logger])
class Broken {
constructor(logger: Logger, port: number) {}
}Compile error: the constructor of Broken wants (Logger, number).
The whole module graph is validated and linked once, when the application is created. A missing provider, a circular import or a duplicate route never waits for the first request.
await a connection before its value is ready.onInit hook to write.close() releases the instances in reverse order.$ deno run --allow-net main.ts Error: Cannot resolve Database (argument #0) of UserStore in module UsersModule. Provide it there or import a module that exports it. # fixed, and run again $ deno run --allow-net main.ts Error: Duplicate route "GET /users/:id": declared by UsersController.get and AdminController.find # fixed $ deno run --allow-net main.ts listening on http://localhost:3000
What an application needs every day is in the box, and behaves the same on every adapter.
On a module, a controller or one method. As a function, or as a class the injector creates, with dependencies of its own.
app.handler(new Request(…))A request is a function call, and so is a message. Replace any provider with a fake, anywhere in the graph, with overrides.
Declare what a handler reads from the request. A Zod schema, or any object with a parse method, checks it.
A handler is an async generator. Each yield is an event, and a client that leaves ends the loop.
--help is generated from the flags each command declares. run() returns the exit code.
A message is acknowledged after its handler returns. An error handler that only logs leaves it failed.
ChoMessage.from(web.injector)One database pool, one cache, for the requests and for the messages of the same process.
RecipesStreaming, downloads, uploads, forwarding a request and shutting down gracefully, checked on three runtimes.
It brings everything an application needs. A first HTTP application takes one file, and runs the same on every runtime.
deno add jsr:@chojs/webnpx jsr add @chojs/webbunx jsr add @chojs/web