expediate 1.0.4 → 1.0.6

package/dist/router.js

@@ -19,43 +19,10 @@
  * DEALINGS IN THE SOFTWARE.
  */
 'use strict';
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-const http = __importStar(require("http"));
-const https = __importStar(require("https"));
-const misc_1 = require("./misc");
+import * as http from 'http';
+import * as https from 'https';
+import * as http2 from 'http2';
+import { updateHttpObjects } from './http-objects.js';
 // ---------------------------------------------------------------------------
 // Pattern compilation
 // ---------------------------------------------------------------------------
@@ -69,7 +36,43 @@ const misc_1 = require("./misc");
  * @returns `true` if the pattern should be treated as a glob.
  */
 function isGlobPattern(pattern) {
-    return /(?<!\\)[*?]/.test(pattern);
+    // Walk character-by-character, skipping over :name(constraint) segments so
+    // that regex metacharacters (e.g. '?') inside inline constraints are not
+    // mistaken for glob wildcards.
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '\\') {
+            i += 2;
+            continue;
+        } // escaped — skip next char
+        if (ch === ':') {
+            i++;
+            while (i < pattern.length && /\w/.test(pattern[i]))
+                i++; // skip param name
+            if (i < pattern.length && pattern[i] === '(') {
+                // Skip balanced constraint parens so their '?' / '*' are not counted.
+                let depth = 1;
+                i++;
+                while (i < pattern.length && depth > 0) {
+                    if (pattern[i] === '\\') {
+                        i += 2;
+                        continue;
+                    }
+                    if (pattern[i] === '(')
+                        depth++;
+                    else if (pattern[i] === ')')
+                        depth--;
+                    i++;
+                }
+            }
+            continue;
+        }
+        if (ch === '*' || ch === '?')
+            return true;
+        i++;
+    }
+    return false;
 }
 /**
  * Compile a `.gitignore`-style glob string into a prefix-anchored `RegExp`.
@@ -93,7 +96,7 @@ function isGlobPattern(pattern) {
  * compileGlob('/api/*')    .test('/api/users/123');   // false
  * ```
  */
-function compileGlob(glob) {
+function compileGlob(glob, exact = false) {
     // Escape all regex special characters, leaving our wildcard characters intact.
     let src = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
     // Replace in order: `**` must be handled before `*`.
@@ -102,37 +105,118 @@ function compileGlob(glob) {
         .replace(/\*/g, '[^/]*') // single-segment wildcard
         .replace(/\?/g, '[^/]') // single-character wildcard
         .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
-    return new RegExp('^' + src);
+    return new RegExp('^' + src + (exact ? '$' : ''));
+}
+/**
+/**
+ * Extract the content between a balanced pair of parentheses starting at
+ * `openIdx` in `str`, skipping backslash-escaped characters.
+ *
+ * Returns the inner pattern and the index of the closing `)` so callers can
+ * inspect any literal suffix that follows the constraint (e.g. `\.txt` in
+ * `:name([\w-]+)\.txt`).
+ *
+ * @param str     - The full segment string, e.g. `':id(\\d+)'`.
+ * @param openIdx - Index of the opening `(`.
+ * @returns `{ pattern, closeIdx }` — the inner pattern string and the index
+ *   of the matching `)`.
+ * @throws {SyntaxError} When parentheses are unbalanced.
+ */
+function extractInlinePattern(str, openIdx) {
+    let depth = 0;
+    let i = openIdx;
+    for (; i < str.length; i++) {
+        if (str[i] === '\\') {
+            i++;
+            continue;
+        } // skip escape sequences
+        if (str[i] === '(') {
+            depth++;
+            continue;
+        }
+        if (str[i] === ')') {
+            depth--;
+            if (depth === 0)
+                break;
+        }
+    }
+    if (depth !== 0)
+        throw new SyntaxError(`Unbalanced parentheses in route segment '${str}'`);
+    return { pattern: str.slice(openIdx + 1, i), closeIdx: i };
 }
 /**
  * Compile a plain path string with optional `:name` parameter segments into a
  * prefix-anchored `RegExp` that uses named capture groups.
  *
- * Each `:name` segment is converted to `(?<name>[^/]+)`, making named
- * captures available directly on the `RegExp` match result.
- * Literal segments are escaped and matched exactly.
+ * **Basic parameters** — Each `:name` segment is converted to
+ * `(?<name>[^/]+)`, matching any non-slash sequence.
  *
- * The expression matches up to a segment boundary (`/` or end-of-string) so
- * that `/users` never inadvertently matches `/users-admin`.
+ * **Inline constraints** — A parameter may optionally be followed by a
+ * parenthesised regex pattern: `:name(pattern)`. The pattern replaces the
+ * default `[^/]+` body, so only paths where that segment matches the
+ * constraint will be routed to the handler.
  *
- * @param path - A plain path string such as `'/users/:id/posts'`.
+ * ```
+ * :id          →  (?<id>[^/]+)      (any non-slash value)
+ * :id(\d+)     →  (?<id>\d+)        (digits only)
+ * :slug([\w-]+) → (?<slug>[\w-]+)   (word chars and hyphens)
+ * ```
+ *
+ * Literal segments are regex-escaped and matched exactly. The expression
+ * matches up to a segment boundary (`/` or end-of-string) so that `/users`
+ * never inadvertently matches `/users-admin`.
+ *
+ * @param path - A plain path string such as `'/users/:id(\d+)/posts'`.
  * @returns A prefix-anchored `RegExp` with named groups for each parameter.
+ * @throws {SyntaxError} When an inline constraint is malformed, contains
+ *   named capture groups (which conflict with the outer wrapper), or produces
+ *   an invalid `RegExp`.
  *
  * @example
  * ```ts
- * const re = compilePlainPath('/users/:id');
- * re.exec('/users/42/comments')?.groups; // { id: '42' }
+ * const re = compilePlainPath('/users/:id(\\d+)');
+ * re.test('/users/42');  // true
+ * re.test('/users/abc'); // false
+ * re.exec('/users/7')?.groups; // { id: '7' }
  * ```
  */
-function compilePlainPath(path) {
+function compilePlainPath(path, exact = false) {
     const segments = path.split('/').filter((s) => s.length > 0);
     const src = segments
-        .map((seg) => seg.startsWith(':')
-        ? `(?<${seg.slice(1)}>[^/]+)` // named parameter segment
-        : seg.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .map((seg) => {
+        if (!seg.startsWith(':'))
+            return seg.replace(/[.+^${}()|[\]\\]/g, '\\$&'); // escaped literal
+        // Parameter segment: extract name and optional inline constraint.
+        const parenIdx = seg.indexOf('(', 1);
+        if (parenIdx === -1) {
+            // Plain :name — match any non-slash sequence.
+            return `(?<${seg.slice(1)}>[^/]+)`;
+        }
+        // :name(pattern) — optionally followed by a literal suffix, e.g. \.txt
+        const name = seg.slice(1, parenIdx);
+        if (!name)
+            throw new SyntaxError(`Route parameter missing name before '(' in segment '${seg}'`);
+        const { pattern, closeIdx } = extractInlinePattern(seg, parenIdx);
+        // Named capture groups inside the constraint conflict with the outer
+        // (?<name>…) wrapper and would cause duplicate-group errors.
+        if (/\(\?<[^>]+>/.test(pattern))
+            throw new SyntaxError(`Inline constraint for ':${name}' must not contain named capture groups.`);
+        // Any literal characters after the closing ')' are regex-escaped and
+        // appended — e.g. ':name([\\w-]+)\\.txt' → '(?<name>[\\w-]+)\\.txt'.
+        const suffix = seg.slice(closeIdx + 1);
+        const escapedSuffix = suffix.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        return `(?<${name}>${pattern})${escapedSuffix}`;
+    })
         .join('/');
-    // Allow a trailing slash or an additional path segment after the prefix.
-    return new RegExp('^/?' + src + '(?=/|$)');
+    // Validate and return — surface any regex syntax errors as SyntaxError.
+    try {
+        return new RegExp(exact
+            ? '^/?' + src + (src ? '/?' : '') + '$'
+            : '^/?' + src + '(?=/|$)');
+    }
+    catch (e) {
+        throw new SyntaxError(`Invalid inline regex constraint in path '${path}': ${e.message}`, { cause: e });
+    }
 }
 /**
  * Convert any supported path pattern into the single canonical `RegExp`
@@ -141,18 +225,18 @@ function compilePlainPath(path) {
  * | Input type   | Strategy                                              |
  * |--------------|-------------------------------------------------------|
  * | Glob string  | {@link compileGlob} — `.gitignore`-style wildcards    |
- * | Plain string | {@link compilePlainPath} — `:name` → named groups     |
+ * | Plain string | {@link compilePlainPath} — `:name` or `:name(re)` → named groups |
  * | `RegExp`     | Used as-is; named groups are surfaced as params       |
  *
  * @param path - The raw path pattern supplied by the caller.
  * @returns A `RegExp` suitable for use in `matchRouteLayer`.
  */
-function compilePattern(path) {
+function compilePattern(path, exact = false) {
     if (path instanceof RegExp)
         return path;
     if (isGlobPattern(path))
-        return compileGlob(path);
-    return compilePlainPath(path);
+        return compileGlob(path, exact);
+    return compilePlainPath(path, exact);
 }
 // ---------------------------------------------------------------------------
 // Layer construction
@@ -179,7 +263,15 @@ function compilePattern(path) {
 function buildRouteLayer(method, path, middleware, stripPath) {
     if (typeof middleware !== 'function')
         throw new TypeError('Incorrect middleware type: expected a function');
-    return { method, path, regex: compilePattern(path), stripPath, middleware };
+    // Reject RegExp patterns with the global (g) or sticky (y) flag.
+    // Both flags make RegExp.exec()/test() stateful: lastIndex advances after
+    // each match, so the same regex object alternates match/no-match across
+    // requests, causing intermittent 404s that are nearly impossible to debug.
+    // Express 4 silently allowed this (a known footgun); we reject it early.
+    if (path instanceof RegExp && (path.global || path.sticky))
+        throw new TypeError(`Route RegExp /${path.source}/${path.flags} must not use the g (global) or y (sticky) flag — ` +
+            'these flags make exec() stateful and cause intermittent routing failures.');
+    return { method, path, regex: compilePattern(path, !stripPath), stripPath, middleware };
 }
 // ---------------------------------------------------------------------------
 // Layer matching
@@ -205,12 +297,17 @@ function buildRouteLayer(method, path, middleware, stripPath) {
  *          `false` otherwise.
  */
 function matchRouteLayer(layer, req, path) {
-    if (layer.method && layer.method !== req.method)
+    // A HEAD request is served by a matching GET layer (RFC 7231 §4.3.2); Node
+    // suppresses the response body for HEAD automatically, so the GET handler can
+    // run unchanged.
+    if (layer.method &&
+        layer.method !== req.method &&
+        !(req.method === 'HEAD' && layer.method === 'GET'))
         return false;
     const m = layer.regex.exec(path);
     if (m === null)
         return false;
-    const captured = m.groups ?? {};
+    const captured = (m.groups) ?? {};
     // Only rewrite req.path for prefix-style (use) registrations.
     // Exact-method routes leave req.path intact so chained middlewares
     // sharing the same path each see the full, unmodified path.
@@ -221,123 +318,25 @@ function matchRouteLayer(layer, req, path) {
     Object.assign(req.params, captured);
     return true;
 }
-// ---------------------------------------------------------------------------
-// HTTP object augmentation
-// ---------------------------------------------------------------------------
 /**
- * Augment a raw `http.IncomingMessage` / `http.ServerResponse` pair with the
- * additional fields and helpers expected by router middleware.
- *
- * This function is idempotent — it exits immediately when `req.queries` is
- * already defined, so it is safe to call multiple times on the same pair.
- *
- * **Fields added to `req`:**
- * - `originalUrl` — the unmodified URL string.
- * - `path`        — the pathname portion of the URL.
- * - `params`      — merged map initialised from URL query parameters.
- * - `queries`     — structured query buckets (`url`, `route`).
- * - `cookies`     — parsed `Cookie` header values.
- *
- * **Helpers added to `res`:**
- * - `send(data?)`             — write `data` and end the response.
- * - `status(code, headers?)`  — set the status code and optional headers.
- * - `redirect(url)`           — issue a 302 redirect.
- * - `cookie(name, val, opts)` — append a `Set-Cookie` header.
- *
- * @param req - The raw incoming message to augment.
- * @param res - The raw server response to augment.
+ * Test whether a layer's path pattern matches the given path string,
+ * **ignoring the HTTP method**.  Does NOT mutate `req`.
+ *
+ * Used exclusively for **405 Method Not Allowed** detection: when
+ * `matchRouteLayer` returns `false` due to a method mismatch, calling this
+ * function lets the dispatcher confirm that the path itself is registered
+ * (just under a different method) so it can respond with 405 and an
+ * `Allow` header instead of the generic 404.
+ *
+ * @param layer - The layer whose path pattern to test.
+ * @param path  - The current value of `req.path`.
+ * @returns `true` when the path pattern matches, regardless of method.
  */
-function updateHttpObjects(req, res) {
-    const rReq = req;
-    const rRes = res;
-    if (rReq.queries)
-        return; // Already augmented.
-    rReq.queries = {};
-    const qry = new URL(`http://${req.headers.host}${req.url}`);
-    rReq.originalUrl = req.url;
-    rReq.path = qry.pathname;
-    // Parse URL query parameters.
-    const urlParams = {};
-    for (const [key, value] of qry.searchParams.entries())
-        urlParams[key] = value;
-    rReq.queries.url = urlParams;
-    rReq.params = { ...urlParams };
-    // Parse cookies.
-    if (rReq.cookies == null) {
-        rReq.cookies = {};
-        if (req.headers.cookie) {
-            for (const raw of req.headers.cookie.split(';')) {
-                const eqIdx = raw.indexOf('=');
-                if (eqIdx === -1)
-                    continue;
-                rReq.cookies[raw.slice(0, eqIdx).trim()] = raw.slice(eqIdx + 1).trim();
-                // TODO: 's:' prefix → signed cookie, 'j:' prefix → JSON cookie
-            }
-        }
-    }
-    rReq.json = (opts) => {
-        return new Promise((resolve, reject) => {
-            (0, misc_1.readReqBody)(rReq, { limit: opts?.limit ?? '100kb', inflate: opts?.inflate ?? true, reviver: null, strict: false }, 'application/json')
-                .then(ret => {
-                if (ret == null)
-                    return resolve(null);
-                const charset = (0, misc_1.extractCharset)(ret.mimetype);
-                try {
-                    rReq.body = JSON.parse(ret.content.toString(charset), opts?.reviver ?? undefined);
-                    return resolve(rReq.body);
-                }
-                catch (ex) {
-                    reject({ status: 500, message: ex.message });
-                }
-            })
-                .catch(err => reject(err));
-        });
-    };
-    rRes.setHeader('X-Powered-By', 'Expediate');
-    rRes.send = (data) => {
-        if (data)
-            res.write(data);
-        res.end();
-    };
-    rRes.json = (data) => {
-        res.write(JSON.stringify(data));
-        res.end();
-    };
-    rRes.status = (code, headers) => {
-        res.statusCode = code;
-        if (headers)
-            for (const [k, v] of Object.entries(headers))
-                res.setHeader(k, v);
-        return rRes;
-    };
-    rRes.redirect = (url) => {
-        res.setHeader('location', url);
-        res.writeHead(302);
-        res.write(`Found. Redirecting to ${url}`);
-        res.end();
-    };
-    rRes.cookie = (name, value, options) => {
-        const opts = options ?? {};
-        if (opts.signed && !req.secret)
-            throw new Error('cookieParser("secret") required for signed cookies');
-        let val = typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value);
-        if (opts.signed)
-            val = 's:' + val; // sign() integration point
-        let txt = `${name}=${val}`;
-        if (opts.maxAge != null) {
-            opts.expires = new Date(Date.now() + opts.maxAge);
-            opts.maxAge = Math.floor(opts.maxAge / 1000);
-            txt += `; Max-Age=${opts.maxAge}`;
-        }
-        if (opts.expires)
-            txt += `; Expires=${opts.expires.toUTCString()}`;
-        txt += `; Path=${opts.path ?? '/'}`;
-        res.setHeader('Set-Cookie', txt);
-        return rRes;
-    };
+function pathMatchesLayer(layer, path) {
+    return layer.regex.test(path);
 }
 // ---------------------------------------------------------------------------
-// Route registration
+// Route registration helpers
 // ---------------------------------------------------------------------------
 /**
  * Recursively resolve a `MiddlewareArg` value down to individual `Middleware`
@@ -352,11 +351,7 @@ function updateHttpObjects(req, res) {
  * @param method    - HTTP method string or `null` for method-agnostic layers.
  * @param path      - URL pattern (plain string, glob, or `RegExp`).
  * @param arg       - The middleware value(s) to register.
- * @param stripPath - Forwarded to `buildRouteLayer`. Pass `true` for prefix-
- *                    style registrations (`use`) so the matched prefix
- *                    is stripped from `req.path`, and `false` for exact-method
- *                    routes so that chained middlewares sharing the same path
- *                    each see the unmodified path.
+ * @param stripPath - Forwarded to `buildRouteLayer`.
  * @throws {TypeError} When `arg` contains a value that cannot be resolved to
  *                     a `Middleware` function.
  */
@@ -368,15 +363,34 @@ function registerRoute(routes, method, path, arg, stripPath) {
     else if (typeof arg === 'function') {
         routes.push(buildRouteLayer(method, path, arg, stripPath));
     }
-    else if (arg && typeof arg.listener === 'function') {
+    else if (arg && typeof (arg).listener === 'function') {
         // Router instance — unwrap its listener.
-        routes.push(buildRouteLayer(method, path, arg.listener, stripPath));
+        routes.push(buildRouteLayer(method, path, (arg).listener, stripPath));
     }
     else {
         throw new TypeError('Unexpected value registered as middleware: expected a Middleware ' +
             'function, a Router instance, or an array of either');
     }
 }
+/**
+ * If `arg` is a `Router` instance, return its configured {@link Router.prefix};
+ * otherwise return `undefined`.
+ *
+ * Used by `router.use()` to infer the mount path when no explicit path is
+ * provided:
+ * ```ts
+ * const v1 = createRouter('/api/v1');
+ * app.use(v1); // prefix '/api/v1' is inferred automatically
+ * ```
+ *
+ * @param arg - The first argument passed to `router.use()`.
+ * @returns The router's prefix string, or `undefined`.
+ */
+function extractRouterPrefix(arg) {
+    if (Array.isArray(arg) || typeof arg === 'function')
+        return undefined;
+    return (arg).prefix;
+}
 // ---------------------------------------------------------------------------
 // Router factory
 // ---------------------------------------------------------------------------
@@ -388,79 +402,231 @@ function registerRoute(routes, method, path, arg, stripPath) {
  * mounted inside another router:
  * ```ts
  * parent.use('/api', child);
+ * // or, if child has a prefix:
+ * parent.use(child);
+ * ```
+ *
+ * **Prefix shorthand:**
+ * Pass a path string as the first argument to associate a prefix with this
+ * router.  The prefix is used automatically when the router is mounted via
+ * `parent.use(child)`:
+ * ```ts
+ * const v1 = createRouter('/api/v1');
+ * v1.get('/users', handler);   // handler is reached at /api/v1/users
+ * app.use(v1);                  // same as app.use('/api/v1', v1)
  * ```
  *
  * **Path patterns** accepted by all route-registration methods:
  * - Plain strings with optional `:name` segments — e.g. `'/users/:id'`.
- *   Each `:name` is compiled to a named capture group and exposed in
- *   `req.params` on a match.
  * - Glob strings following `.gitignore` rules — e.g. `'/**\/*.php'`.
- *   Supported wildcards: `?` (one non-slash char), `*` (any non-slash chars),
- *   `**` (any chars, including slashes).
  * - `RegExp` objects — used directly; named groups become route parameters.
  *
- * **Middleware arguments** accept any number of variadic `MiddlewareArg`
- * values, each of which may be:
- * - A `Middleware` function.
- * - A `Router` instance (its `listener` is registered automatically).
- * - An array of either of the above.
+ * **Error handling:**
+ * Register a global error handler with `router.onError()`.  It is called
+ * when any middleware throws, rejects, or calls `next(err)`.
  *
- * **Path stripping behaviour:**
- * - `use` — strip the matched path prefix from `req.path` before
- *   invoking middleware. Nested routers therefore only see the remaining suffix.
- * - `all` / `get` / `post` / `put` / `delete` / `patch` — leave `req.path` intact
- *   so that multiple middlewares registered for the same exact path can each
- *   match and be invoked in sequence via `next()`.
+ * **Graceful shutdown:**
+ * Call `router.shutdown()` to stop the server created by `router.listen()`.
  *
- * @returns A fully initialised `Router` ready to register routes and
- *          optionally start an HTTP or HTTPS server.
+ * @param prefixOrOpts - Optional path prefix string (e.g. `'/api/v1'`) **or**
+ *                       an {@link RouterOptions} object.
+ * @param opts         - Options when `prefixOrOpts` is a string.
+ * @returns A fully initialised `Router`.
  *
  * @example
  * ```ts
- * const auth = createRouter();
- * auth.post('/login',  handleLogin);
- * auth.post('/logout', handleLogout);
+ * const app = createRouter({ secret: process.env.COOKIE_SECRET, timeout: 30_000 });
+ *
+ * const v1 = createRouter('/api/v1');
+ * v1.get('/users', handler);
  *
- * const app = createRouter();
- * app.use('/auth', auth);                              // mount a sub-router
- * app.get('/users/:id', requireAuth, getUser);         // multiple middleware
- * app.get('/**\/*.php', (req, res) =>                 // glob pattern
- *   res.status(403).send('Forbidden'));
+ * app.use(v1);
+ * app.onError((err, _req, res) => res.status(500).json({ error: String(err) }));
  *
- * app.listen(3000, () => console.log('Listening on :3000'));
+ * // Custom 404: register a catch-all as the LAST layer. Because layers match
+ * // in registration order, it only runs when nothing earlier claimed the
+ * // request. Use `all('/**', …)` (glob) to match any method and path.
+ * app.all('/**', (_req, res) => res.status(404).json({ error: 'Not Found' }));
+ *
+ * app.listen(3000, () => console.log('Listening'));
+ * process.on('SIGTERM', () => app.shutdown(10_000));
  * ```
  */
-function createRouter() {
+function createRouter(prefixOrOpts, opts) {
+    // Resolve overloaded first argument.
+    const routerPrefix = typeof prefixOrOpts === 'string' ? prefixOrOpts : undefined;
+    const options = typeof prefixOrOpts === 'object' ? prefixOrOpts : (opts ?? {});
+    const secret = options.secret;
+    const timeoutMs = options.timeout;
+    const trustProxy = options.trustProxy ?? false;
     const routes = [];
+    /** Ordered error-handling middlewares registered via `router.error()`. */
+    const errorHandlers = [];
+    /** Terminal fallback registered via `router.onError()`, or `undefined`. */
+    let errorHandler;
+    /** Server created by `router.listen()`, used by `router.shutdown()`. */
+    let activeServer = null;
+    /** All open sockets tracked for forced teardown on shutdown. */
+    const activeSockets = new Set();
+    // ──────────────────────────────────────────────────────────────────────────
+    // Core dispatch listener
+    // ──────────────────────────────────────────────────────────────────────────
     /**
      * Core dispatch function. Walks the route table in registration order and
-     * invokes the first layer that matches the current request. Falls back to a
-     * 404 response when no layer matches and no upstream `done` callback is set.
+     * invokes the first layer that matches the current request.
+     *
+     * - **404** — no layer's path matched (register a catch-all last to customise).
+     * - **405 Method Not Allowed** — a layer's path matched but no layer
+     *   accepted the HTTP method.  The `Allow` header lists all registered methods.
+     * - **500** (or custom `onError` handler) — a middleware threw or rejected,
+     *   or `next(err)` was called with a non-null error.
      */
     const listener = (req, res, done) => {
         const method = req.method;
         const url = req.url;
         let idx = 0;
-        updateHttpObjects(req, res);
-        const next = () => {
+        updateHttpObjects(req, res, secret, trustProxy);
+        // ── Optional per-request timeout ──────────────────────────────────────
+        // Uses both a socket-level idle timeout (as the transport boundary) and a
+        // wall-clock setTimeout guard.  The wall-clock timer is the primary
+        // mechanism because it is unaffected by the OS socket buffer state;
+        // socket.setTimeout is set in addition so the idle signal propagates down
+        // to keep-alive connections that would otherwise hold the socket open.
+        if (timeoutMs) {
+            if (req.socket)
+                req.socket.setTimeout(timeoutMs);
+            const timer = setTimeout(() => {
+                if (!res.writableEnded)
+                    res.status(408).end('Request Timeout');
+            }, timeoutMs);
+            res.once('finish', () => {
+                clearTimeout(timer);
+                if (req.socket)
+                    req.socket.setTimeout(0);
+            });
+        }
+        // ── Centralised error dispatch ─────────────────────────────────────────
+        // Invoked for sync throws, async rejections, and next(err) calls.
+        //
+        // Resolution order:
+        //   1. Each error() middleware in turn (it may end the response or forward).
+        //   2. The onError() terminal fallback, if registered.
+        //   3. Bubble to the parent router's error channel via done(err).
+        //   4. Top-level router with no handler → default 500.
+        const invokeErrorHandler = (e) => {
+            if (res.writableEnded)
+                return;
+            let i = 0;
+            const runNext = (err) => {
+                if (res.writableEnded)
+                    return;
+                // 1. Ordered error() middleware chain.
+                if (i < errorHandlers.length) {
+                    const handler = errorHandlers[i++];
+                    try {
+                        // `next()` forwards the same error; `next(newErr)` replaces it.
+                        handler(err, req, res, (nextErr) => runNext(nextErr ?? err));
+                    }
+                    catch (e2) {
+                        runNext(e2);
+                    }
+                    return;
+                }
+                // 2. onError() terminal fallback for this router.
+                if (errorHandler) {
+                    try {
+                        errorHandler(err, req, res);
+                    }
+                    catch {
+                        if (!res.writableEnded)
+                            res.status(500).end(`Error ${method} ${url}`);
+                    }
+                    return;
+                }
+                // 3. Bubble to the parent router's error channel (when mounted via use()).
+                if (done) {
+                    done(err);
+                    return;
+                }
+                // 4. Top-level router with no handler: default 500.
+                res.status(500).end(`Error ${method} ${url}`);
+            };
+            runNext(e);
+        };
+        // ── Safe middleware invocation ─────────────────────────────────────────
+        // Catches sync throws AND async rejections, routing both to invokeErrorHandler.
+        const invoke = (mw, nextFn) => {
+            try {
+                const ret = mw(req, res, nextFn);
+                if (ret instanceof Promise)
+                    ret.catch(invokeErrorHandler);
+            }
+            catch (e) {
+                invokeErrorHandler(e);
+            }
+        };
+        // Accumulate methods from layers whose path matched but whose method
+        // did not, for a 405 response with an accurate Allow header.
+        const allowedMethods = new Set();
+        // ── Main dispatch loop ─────────────────────────────────────────────────
+        const next = (err) => {
+            // If an error is passed, skip remaining routes and call error handler.
+            if (err != null) {
+                invokeErrorHandler(err);
+                return;
+            }
             while (idx < routes.length) {
                 const layer = routes[idx++];
                 const pathBefore = req.path;
                 if (matchRouteLayer(layer, req, req.path)) {
                     if (layer.stripPath) {
-                        // For prefix layers (use), save the pre-strip path so we can
-                        // restore it if the sub-router calls done() and control returns here.
-                        // Without restoration, subsequent layers in this router would see
-                        // the truncated path and fail to match their own patterns.
-                        const strippedPath = req.path;
-                        return layer.middleware(req, res, () => {
-                            req.path = pathBefore; // restore for the next sibling layer
-                            next();
+                        // For prefix layers (use), restore req.path and req.baseUrl after
+                        // the sub-router calls done() so subsequent sibling layers see the
+                        // original values.
+                        const baseUrlBefore = req.baseUrl;
+                        const strippedPrefix = pathBefore.slice(0, pathBefore.length - req.path.length);
+                        req.baseUrl = baseUrlBefore + strippedPrefix;
+                        // The continuation doubles as the sub-router's `done`: it runs both
+                        // when the sub-router falls through (no error) and when it bubbles an
+                        // error up. Forward `err` so a bubbled error reaches this router's
+                        // error channel instead of being silently dropped.
+                        invoke(layer.middleware, (err) => {
+                            req.path = pathBefore;
+                            req.baseUrl = baseUrlBefore;
+                            next(err);
                         });
+                        return;
                     }
-                    return layer.middleware(req, res, next);
+                    invoke(layer.middleware, next);
+                    return;
                 }
+                // Path matched but method did not → remember for 405 detection.
+                if (layer.method !== null && pathMatchesLayer(layer, pathBefore)) {
+                    allowedMethods.add(layer.method);
+                }
+            }
+            // All layers exhausted without a full match.
+            if (allowedMethods.size > 0) {
+                // The path is registered, just not for this method.  Build the Allow
+                // header, advertising HEAD (served by GET) and OPTIONS (handled here)
+                // alongside the explicitly registered methods.
+                if (allowedMethods.has('GET'))
+                    allowedMethods.add('HEAD');
+                allowedMethods.add('OPTIONS');
+                const allow = [...allowedMethods].sort().join(', ');
+                // Automatic OPTIONS: when nothing claimed the request (no explicit
+                // OPTIONS route, no cors() middleware), reply 204 with the Allow header.
+                if (method === 'OPTIONS') {
+                    res.status(204, { Allow: allow }).end();
+                    return;
+                }
+                // Otherwise the method is genuinely not allowed for this path.
+                res.status(405, { Allow: allow }).end(`Cannot ${method} ${url}`);
+                return;
             }
+            // Genuine 404 — delegate to the parent router, or send the default 404.
+            // To customise, register a catch-all layer last (e.g. `app.all('/**', …)`);
+            // it matches in registration order after every real route.
             if (done)
                 return done();
             res.status(404).end(`Cannot ${method} ${url}`);
@@ -469,25 +635,17 @@ function createRouter() {
             next();
         }
         catch (e) {
-            console.warn(e);
-            res.status(500).end(`Error ${method} ${url}`);
+            invokeErrorHandler(e);
         }
     };
-    // -------------------------------------------------------------------------
-    // Internal helper — produce the uniform registration function for a method.
-    // -------------------------------------------------------------------------
+    // ──────────────────────────────────────────────────────────────────────────
+    // Registration helper for method-specific routes
+    // ──────────────────────────────────────────────────────────────────────────
     /**
      * Return the route-registration function used by all HTTP-method helpers.
      *
-     * The produced function accepts a mandatory `path` followed by any number
-     * of `MiddlewareArg` values (functions, `Router` instances, or arrays
-     * thereof), and delegates each to `registerRoute`.
-     *
      * @param method    - HTTP method to restrict layers to, or `null` for any.
-     * @param stripPath - Whether the matched path prefix should be stripped from
-     *                    `req.path` before middleware is invoked. `true` for
-     *                    prefix-style registrations, `false` for exact-method ones.
-     * @returns A variadic route-registration function.
+     * @param stripPath - Whether the matched path prefix should be stripped.
      */
     function makeRegister(method, stripPath) {
         return (path, ...args) => {
@@ -495,31 +653,131 @@ function createRouter() {
                 registerRoute(routes, method, path, arg, stripPath);
         };
     }
-    // -------------------------------------------------------------------------
-    // Public router API
-    // -------------------------------------------------------------------------
+    // ──────────────────────────────────────────────────────────────────────────
+    // `use()` — supports both path-first and no-path (Router-first) forms
+    // ──────────────────────────────────────────────────────────────────────────
+    /**
+     * Register prefix-style middleware.  Accepts:
+     * 1. `use(path, ...middlewares)` — explicit path.
+     * 2. `use(routerOrMiddleware, ...more)` — infers path from Router.prefix or '/'.
+     */
+    const use = (pathOrFirst, ...args) => {
+        if (typeof pathOrFirst === 'string' || pathOrFirst instanceof RegExp) {
+            // Normal form: explicit path string or RegExp.
+            for (const arg of args)
+                registerRoute(routes, null, pathOrFirst, arg, true);
+        }
+        else {
+            // No explicit path: the first argument is itself a middleware / Router.
+            // Infer mount path from the Router's prefix, or default to '/'.
+            const inferredPath = extractRouterPrefix(pathOrFirst) ?? '/';
+            registerRoute(routes, null, inferredPath, pathOrFirst, true);
+            for (const arg of args)
+                registerRoute(routes, null, '/', arg, true);
+        }
+    };
+    // ──────────────────────────────────────────────────────────────────────────
+    // Public router object
+    // ──────────────────────────────────────────────────────────────────────────
     const router = {
+        prefix: routerPrefix,
         listener,
-        use: makeRegister(null, true), // prefix — strip path
-        all: makeRegister(null, false), // exact  — keep path
+        use,
+        all: makeRegister(null, false),
         get: makeRegister('GET', false),
         put: makeRegister('PUT', false),
         post: makeRegister('POST', false),
         delete: makeRegister('DELETE', false),
         patch: makeRegister('PATCH', false),
+        head: makeRegister('HEAD', false),
+        options: makeRegister('OPTIONS', false),
+        // ── route ────────────────────────────────────────────────────────────────
+        route(path) {
+            // Each method forwards to the router's own registration helper with the
+            // cached path and returns the builder so calls can be chained.
+            const builder = {
+                all(...args) { router.all(path, ...args); return builder; },
+                get(...args) { router.get(path, ...args); return builder; },
+                put(...args) { router.put(path, ...args); return builder; },
+                post(...args) { router.post(path, ...args); return builder; },
+                delete(...args) { router.delete(path, ...args); return builder; },
+                patch(...args) { router.patch(path, ...args); return builder; },
+                head(...args) { router.head(path, ...args); return builder; },
+                options(...args) { router.options(path, ...args); return builder; },
+            };
+            return builder;
+        },
+        // ── onError ─────────────────────────────────────────────────────────────
+        onError(handler) {
+            errorHandler = handler;
+        },
+        // ── error ────────────────────────────────────────────────────────────────
+        error(handler) {
+            errorHandlers.push(handler);
+        },
+        // ── routes ───────────────────────────────────────────────────────────────
+        routes() {
+            return routes.map((l) => ({
+                method: l.method,
+                path: l.path,
+                stripPath: l.stripPath,
+            }));
+        },
+        // ── shutdown ─────────────────────────────────────────────────────────────
+        shutdown(timeout = 5000) {
+            if (!activeServer)
+                return Promise.resolve();
+            return new Promise((resolve, reject) => {
+                // Stop accepting new connections.  Resolves when all existing
+                // connections have been closed (or when forcibly destroyed below).
+                activeServer.close((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+                // Forcibly destroy any remaining idle sockets after the grace period.
+                if (timeout > 0) {
+                    setTimeout(() => {
+                        for (const socket of activeSockets)
+                            socket.destroy();
+                        activeSockets.clear();
+                    }, timeout);
+                }
+            });
+        },
+        // ── listen ───────────────────────────────────────────────────────────────
         listen(port, opts, cb) {
             if (typeof opts === 'function') {
                 cb = opts;
                 opts = undefined;
             }
             const rawListener = listener;
-            if (opts && opts.key && opts.cert)
-                https.createServer(opts, rawListener).listen(port, cb);
-            else
-                http.createServer(rawListener).listen(port, cb);
+            let server;
+            const tlsOpts = opts;
+            if (tlsOpts?.key && tlsOpts?.cert) {
+                if (tlsOpts.http2) {
+                    // HTTP/2 secure server — same TLS options, different factory.
+                    server = http2.createSecureServer(tlsOpts, rawListener);
+                }
+                else {
+                    server = https.createServer(tlsOpts, rawListener);
+                }
+            }
+            else {
+                server = http.createServer(rawListener);
+            }
+            // Track open sockets so shutdown() can forcibly destroy them.
+            server.on('connection', (socket) => {
+                activeSockets.add(socket);
+                socket.once('close', () => activeSockets.delete(socket));
+            });
+            activeServer = server;
+            server.listen(port, cb);
+            return server;
         },
     };
     return router;
 }
-exports.default = createRouter;
+export default createRouter;
 //# sourceMappingURL=router.js.map