oak-routing-ctrl

TypeScript Decorators for easy scaffolding API services with the Oak framework (jsr:@oak/oak) 🚗 🐿️ 🦕

Works on Node.js, Bun, Cloudflare Workers, and Deno

@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, 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 which doesn't support Method Parameter Decorator 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

Example: Retrieving path parameters

// 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 });

deno run --allow-env --allow-net main.ts

# in another terminal
curl localhost:1993/v1/hello/world # prints: hello, world

Example: Retrieving path parameters and request body

View Example

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 });

_

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"

Example: Retrieving request query and path parameters

View Example

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 });

_

curl localhost:1993/v1/books/thriller\?page=2
# prints: searching for books in category "thriller" with query "page=2"

Example: Accessing underlying context object

View Example

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 });

_

curl -H"x-foo: lorem" localhost:1993/foo/bar
# prints: request header x-foo has value "lorem"

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.

View Example for Node.js 21 and below

_

You can start with a boilerplate

npm create oak-nodejs-esbuild@latest

_

Or you can start from scratch

friendly note: if something doesn't work as advertised in this section, please file an issue, thanks!

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

_

// 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 });

_

curl http://localhost:1993/v1/hello/world # prints: hello, world

Cloudflare Workers

npm create oak-cloudflare-worker@latest

Live Demo (uptime not guaranteed): https://oak-routing-ctrl-cloudflare.dklab.workers.dev/swagger

View Example

npx jsr add @oak/oak @dklab/oak-routing-ctrl

_

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 };

_

curl http://{your-cloudflare-worker-domain}/hello/world # prints: hello, world

Bun

npm create oak-bun@latest

View Example

bunx jsr i @oak/oak @dklab/oak-routing-ctrl

_

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 });

_

curl http://localhost:1993/v1/hello/world # prints: hello, world

Serving Open API Spec

Serving Open API Spec (both as a JSON doc and as an HTML view) is supported as followed:

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

View Example OAS json doc

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"
                }
              }
            }
          }
        }
      }
    }
  }
}

Documentation

Documentation is hosted on the Javascript Registry: https://jsr.io/@dklab/oak-routing-ctrl/doc

Contributor Resources

Tests

deno test -A --coverage=cov_profile
deno coverage cov_profile

FAQs

Q: can this library support fullstack web development?

A: yes, in fact there's a fullstack web framework on top of this library: FullSoak

Uh oh!

License

Thesephi/oak-routing-ctrl

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Sponsor this project

Uh oh!

Uh oh!

Languages