http-router

HTTP request router for standard Request and Response.

• Based on URL pattern API
• Tiny, lean
• Automatically HEAD request handler

Packages

The package supports multiple platforms.

• deno.land/x - https://deno.land/x/http_router/mod.ts
• npm - @httpland/http-router

HTTP router

Create HTTP request router with URL pattern and method handler map.

import { createRouter } from "https://deno.land/x/http_router@$VERSION/mod.ts";
import { serve } from "https://deno.land/std@$VERSION/http/mod.ts";
const router = createRouter({
  "/api/students/:name": {
    GET: (req, ctx) => {
      const greeting = `Hello! ${ctx.params.name!}`;
      return new Response(greeting);
    },
  },
  "/api/status": () => new Response("OK"), // Any HTTP request method
});
await serve(router);

Route handler context

The route handler receives the following context.

URL match pattern

URL patterns can be defined using the URL pattern API.

• Literal strings which will be matched exactly.
• Wildcards (/posts/*) that match any character.
• Named groups (/books/:id) which extract a part of the matched URL.
• Non-capturing groups (/books{/old}?) which make parts of a pattern optional or be matched multiple times.
• RegExp groups (/books/(\\d+)) which make arbitrarily complex regex matches with a few limitations.

HEAD request handler

By default, if a GET request handler is defined, a HEAD request handler is automatically added.

This feature is based on RFC 9110, 9.1

All general-purpose servers MUST support the methods GET and HEAD.

import { createRouter } from "https://deno.land/x/http_router@$VERSION/mod.ts";
import { serve } from "https://deno.land/std@$VERSION/http/mod.ts";
import { assertEquals } from "https://deno.land/std@$VERSION/testing/asserts.ts";
const router = createRouter({
  "/": {
    GET: (req) => {
      const body = `Hello! world`;
      return new Response(body, {
        headers: {
          "content-length": new Blob([body]).size.toString(),
        },
      });
    },
  },
});

const req = new Request("http://localhost", { method: "HEAD" });
const res = await router(req);
assertEquals(res.body, null);
assertEquals(res.headers.get("content-length"), "12");

This can be disabled by setting withHead to false.

import { createRouter } from "https://deno.land/x/http_router@$VERSION/mod.ts";
createRouter({}, { withHead: false });

Handle base path

Change the router base path.

Just as you could use baseURL or base tags on the Web, you can change the basePath of your router.

import { createRouter } from "https://deno.land/x/http_router@$VERSION/mod.ts";
import { assertEquals } from "https://deno.land/std@$VERSION/testing/asserts.ts";
const api = createRouter({
  "/hello": () => new Response("world"),
}, { basePath: "/api" });

const res = await api(new Request("http://localhost/api/hello"));
assertEquals(res.ok, true);

The basePath and route path are merged without overlapping slashes.

Spec

In addition to user-defined responses, routers may return the following responses:

API

All APIs can be found in the deno doc.

Performance

Benchmark script with comparison to several popular routers is available.

deno bench --unstable

License

Copyright © 2022-present httpland.

Released under the MIT license