deno_http_fns

NOTE: This is still fairly experimental.

A collection of functions for HTTP.

• Based on Request => Response functions
• Works with Deno std lib serve, and the new Deno.serve
• Handlers for routing based on various criteria

Read the blog.

Examples

See the examples.

You can run them after cloning this repo, for example:

deno run -A --import-map=examples/import_map.json examples/logging.ts

or (using a task defined in the deno.json file)

deno task example examples/logging.ts

(NOTE: The above will map the imports to use the local http_fns modules rather than fetching from deno.land)

or directly from deno.land:

deno run -A https://deno.land/x/http_fns/examples/logging.ts

or directly from GitHub:

deno run -A https://raw.githubusercontent.com/jollytoad/deno_http_fns/main/examples/logging.ts

Request Handlers

Most functions could be considered as handler factories, in that they create and return a Request handler function, generally of the form:

(req: Request, data: unknown) => Response

Response can also be in a Promise, and in many case may also be null to indicate that the Request cannot be handled and it should be delegated to another handler.

Here is a very simple example of how the functions can be composed into a server:

await serve(
  handle([
    byPattern(
      "/",
      byMethod({
        GET: () => ok("Hello"),
      }),
    ),
    byPattern(
      "/foo",
      byMethod({
        GET: () => ok("Foo"),
      }),
    ),
  ]),
);

Routing

handle

handle(handlers, fallback) => Handler

This is the top-level function you’ll use to form a router.

You pass it a list of handlers, each handler may return either a Response or a null. If the handler returns null, the next handler is called until a Response is returned, or it will end by calling the optional fallback handler which must return a Response.

The default fallback is to return a 404 Not Found response.

(handle is actually just a shortcut for cascade & withFallback, discussed later)

byPattern

byPattern(pattern, handler) => Handler

Every router needs a way to delegate by actual path or URL. byPattern provides that using the standard URLPattern.

It can take a pattern or array of patterns, and the handler to be called on a successful match.

The pattern can be a string (to match just the path), a URLPatternInit which can declare patterns for other parts of the URL, or a pre-constructed URLPattern itself.

The handler created will attempt to match the Request URL against each given pattern in order until one matches, and then call the delegate handler (passed in the 2nd arg of byPattern), with the Request and the URLPatternResult:

(req: Request, match: URLPatternResult) => Response | null | Promise<Response | null>

If no pattern matches, the handler returns null, allowing the request to cascade to the next handler in the array of handlers passed to handle (or cascade).

byMethod

byMediaType

Delegation

cascade

withFallback

Handlers

staticRoute

Middleware

intercept

interceptResponse

skip

loggers

cors

Utilities

Request

Response