This release is 2 versions behind 0.14.0 — the latest version of @dklab/oak-routing-ctrl. Jump to latest
@dklab/oak-routing-ctrl@0.12.2Built and signed on GitHub ActionsBuilt and signed on GitHub Actions
Built and signed on GitHub Actions
TypeScript Decorators for easy scaffolding API services with the oak framework (jsr:@oak/oak)
This package works with Cloudflare Workers, Node.js, Deno, Bun



JSR Score
100%
Published
2 months ago (0.12.2)
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488# oak-routing-ctrl [](https://jsr.io/@dklab/oak-routing-ctrl) [](https://jsr.io/@dklab/oak-routing-ctrl) [](https://jsr.io/@std) [](https://snyk.io/test/github/thesephi/oak-routing-ctrl) [](https://codecov.io/github/Thesephi/oak-routing-ctrl) [](https://github.com/Thesephi/oak-routing-ctrl/actions/workflows/runtime-tests.yml) TypeScript Decorators for easy scaffolding API services with the [Oak](https://jsr.io/@oak/oak) framework (`jsr:@oak/oak`) 🚗 🐿️ 🦕 Works on Node.js, Bun, Cloudflare Workers, and Deno ```ts @Controller("/api/v1/pokemon") class MyPokedex { @Get("/:id") viewEntry(ctx) { if (ctx.params.id === "0025") return "Pikachu"; } } ```  ## Forewords If you're familiar with the [npm library routing-controllers](https://www.npmjs.com/package/routing-controllers), you'll find yourself very much at home. However, please note that this libray is **not** meant to be a drop-in replacement for routing-controllers, as it attempts to conform to [TC39 Decorators proposal](https://github.com/tc39/proposal-decorators) which [doesn't support Method Parameter Decorator](https://github.com/tc39/proposal-decorators?tab=readme-ov-file#comparison-with-typescript-experimental-decorators) yet. There's currently no plan to support TypeScript "experimental" decorators, but if you feel strongly for it, please feel free to fork this repo! ## Heads up For easy reading, the examples below do not specify any explicit version when installing library dependencies. But in your production code, it's advisable to pin every dependency to a specific version. ## Deno runtime Prerequisite: [Deno](https://docs.deno.com/runtime/manual/getting_started/installation) ### Example: Retrieving path parameters ```ts // main.ts import { Application } from "jsr:@oak/oak/application"; import { Controller, ControllerMethodArgs, Get, useOakServer, } from "jsr:@dklab/oak-routing-ctrl"; const app = new Application(); @Controller("/v1") class MyController { @Get("/hello/:name") @ControllerMethodArgs("param") hello(param) { return `hello, ${param.name}`; } } useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` ```bash deno run --allow-env --allow-net main.ts ``` ```bash # in another terminal curl localhost:1993/v1/hello/world # prints: hello, world ``` ### Example: Retrieving path parameters and request body <details> <summary>View Example</summary> ```ts import { Application } from "jsr:@oak/oak/application"; import { Controller, ControllerMethodArgs, Post, useOakServer, } from "jsr:@dklab/oak-routing-ctrl"; @Controller("/v1") class MyController { @Post("/tell/:name") @ControllerMethodArgs("param", "body") tell(param, body) { return `telling ${param.name} that "${body.message}"`; } } const app = new Application(); useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` _ ```bash curl -H"Content-Type: application/json" localhost:1993/v1/tell/alice -d'{"message": "all we need is love"}' # prints: telling alice that "all we need is love" ``` </details> ### Example: Retrieving request query and path parameters <details> <summary>View Example</summary> ```ts import { Application } from "jsr:@oak/oak/application"; import { Controller, ControllerMethodArgs, Get, useOakServer, } from "jsr:@dklab/oak-routing-ctrl"; @Controller("/v1") class MyController { @Get("/books/:category") @ControllerMethodArgs("query", "param") search(query, param) { return `searching for books in category "${param.category}" with query "page=${query.page}"`; } } const app = new Application(); useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` _ ```bash curl localhost:1993/v1/books/thriller\?page=2 # prints: searching for books in category "thriller" with query "page=2" ``` </details> ### Example: Accessing underlying context object <details> <summary>View Example</summary> ```ts import { Application } from "jsr:@oak/oak/application"; import { Controller, Get, useOakServer } from "jsr:@dklab/oak-routing-ctrl"; @Controller() class MyController { @Get("/foo/bar") fooBar(ctx) { return `request header x-foo has value "${ ctx.request.headers.get("x-foo") }"`; } } const app = new Application(); useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` _ ```bash curl -H"x-foo: lorem" localhost:1993/foo/bar # prints: request header x-foo has value "lorem" ``` </details> ## Other runtimes ### Node.js If you're on Node.js 22 (or above), please consult this example boilerplate: https://replit.com/@0x97FB9/auto-swagger-node-alpha If you're on Node.js 21 (or below), then the example workflow below may apply to you. <details> <summary>View Example for Node.js 21 and below</summary> _ You can start with a boilerplate ```bash npm create oak-nodejs-esbuild@latest ``` _ Or you can start from scratch <small>friendly note: if something doesn't work as advertised in this section, please file an issue, thanks!</small> ```bash npm i @jsr/oak__oak @jsr/dklab__oak-routing-ctrl # note that `npx jsr i {package}` also works, but # installing directly from the `@jsr` scope might result # in better dependency resolutions ``` _ ```ts // alternatively imported from "@oak/oak/application" import { Application } from "@jsr/oak__oak/application"; // alternatively imported from "@dklab/oak-routing-ctrl" import { Controller, ControllerMethodArgs, Get, useOakServer, } from "@jsr/dklab__oak-routing-ctrl"; @Controller("/v1") export class MyController { @Get("/hello/:name") @ControllerMethodArgs("param") hello(param: Record<string, string>) { return `hello, ${param.name}`; } } const app = new Application(); useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` _ ```bash curl http://localhost:1993/v1/hello/world # prints: hello, world ``` </details> ### Cloudflare Workers ```bash npm create oak-cloudflare-worker@latest ``` Live Demo (uptime <ins>not</ins> guaranteed): https://oak-routing-ctrl-cloudflare.dklab.workers.dev/swagger <details> <summary>View Example</summary> ```bash npx jsr add @oak/oak @dklab/oak-routing-ctrl ``` _ ```ts import { Application } from "@oak/oak/application"; import { Controller, ControllerMethodArgs, Get, useOakServer, } from "@dklab/oak-routing-ctrl/mod"; @Controller() class MyCloudflareWorkerController { @Get("/hello/:name") @ControllerMethodArgs("param") hello(param: { name: string }) { return `hello, ${param.name}`; } } const app = new Application(); useOakServer(app, [MyCloudflareWorkerController]); export default { fetch: app.fetch }; ``` _ ```bash curl http://{your-cloudflare-worker-domain}/hello/world # prints: hello, world ``` </details> ### Bun ```bash npm create oak-bun@latest ``` <details> <summary>View Example</summary> ```bash bunx jsr i @oak/oak @dklab/oak-routing-ctrl ``` _ ```ts import { Application, type RouterContext } from "@oak/oak"; import { Controller, Get, useOakServer } from "@dklab/oak-routing-ctrl"; @Controller("/v1") class MyController { @Get("/hello/:name") hello(ctx: RouterContext<"/hello/:name">) { return `hello, ${ctx.params.name}`; } } const app = new Application(); useOakServer(app, [MyController]); await app.listen({ port: 1993 }); ``` _ ```bash curl http://localhost:1993/v1/hello/world # prints: hello, world ``` </details> ## Serving Open API Spec Serving Open API Spec (both as a JSON doc and as an HTML view) is supported as followed: ```ts import { Application } from "@oak/oak"; import { Controller, ControllerMethodArgs, Get, useOakServer, useOas, z, type zInfer, } from "@dklab/oak-routing-ctrl"; const HelloNamePathParamsSchema = z.object({ name: z.string() }); const OpenApiSpecForHelloName = { // using `zod` to express Open API Spec for this route // e.g. `request` and `responses` request: { params: HelloNamePathParamsSchema }, responses: { "200": { description: "Success", content: { "text/html": { schema: z.string() } }, }, }, }; @Controller("/v1") class MyController { @Get( "/hello/:name", OpenApiSpecForHelloName, // API spec is entirely optional ) @ControllerMethodArgs("param") hello( param: zInfer<typeof HelloNamePathParamsSchema>, // or type it however else you like ) { return `hello, ${param.name}`; // intellisense should just work ™ } } useOakServer(app, [MyController]); useOas(app, { // optionally declare OAS info as per your project needs info: { version: "0.1.0", title: "My awesome API", description: "This is an awesome API", }, }); await app.listen({ port: 1993 }); ``` The following OAS resources are now served: - UI: http://localhost:1993/swagger - JSON doc: http://localhost:1993/oas.json <details> <summary>View Example OAS json doc</summary> ```bash curl localhost:1993/oas.json { "openapi": "3.0.0", "info": { "version": "0.1.0", "title": "My awesome API", "description": "This is an awesome API" }, "servers": [ { "url": "http://localhost:1993" } ], "components": { "schemas": {}, "parameters": {} }, "paths": { "/hello/{name}": { "get": { "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "name", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } } } ``` </details> ## Documentation Documentation is hosted on the Javascript Registry: https://jsr.io/@dklab/oak-routing-ctrl/doc ## Contributor Resources ### Tests ```bash deno test -A --coverage=cov_profile deno coverage cov_profile ``` [](https://codecov.io/github/Thesephi/oak-routing-ctrl)