ergo-router

v0.1.0 Node.js ≥ 22 Pure ESM

Installation

npm install ergo-router ergo

ergo-router has a peer dependency on ergo.

Overview

ergo-router provides path-based request dispatch built on find-my-way with automatic REST compliance and a declarative pipeline builder.

Automatic REST Behavior

Behavior	Standard	Description
405 + Allow	RFC 9110 §15.5.6	Requests to a known path with an unsupported method receive 405 with an Allow header listing valid methods
HEAD derivation	RFC 9110 §9.3.2	HEAD requests automatically derive from GET handlers
OPTIONS	RFC 9110 §9.3.7	OPTIONS requests return Allow header with supported methods
PATCH required	Custom	Routes with PUT must also register PATCH (or explicitly opt out)

Transport Middleware

Middleware	Description	Standard
Security headers	HSTS, CSP, X-Content-Type-Options	RFC 6797
CORS	Cross-Origin Resource Sharing	Fetch Standard
Rate limiting	Global rate limiter with 429 responses	RFC 6585 §4
Request ID	X-Request-Id generation and propagation	Convention

Pipeline Builder

Declaratively compose ergo middleware for each route:

import createRouter from "ergo-router";

const router = createRouter({
  defaults: {
    accepts: { types: ["application/json"] },
  },
});

router.post("/users", {
  auth: { strategies: [bearerStrategy] },
  validate: { body: userSchema },
  execute: createUser,
});

Graceful Shutdown

import createRouter, { graceful } from "ergo-router";

const router = createRouter({ /* ... */ });

const { server, shutdown } = await graceful(router.handle(), {
  port: 3000,
  onShutdown: async ({ log }) => {
    await disconnectDatabase();
    log.info("Cleanup complete");
  },
});

graceful() handles signal listeners (SIGINT, SIGTERM), connection draining with a configurable timeout, and startup/shutdown lifecycle hooks.

Links

• GitHub
• npm
• Changelog