expediate 1.0.3 → 1.0.5

package/dist/router.js

@@ -19,42 +19,14 @@
  * 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"));
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as http from 'http';
+import * as https from 'https';
+import * as http2 from 'http2';
+import * as path from 'path';
+import { parseMultipartBody, extractCharset, readReqBody } from './misc.js';
+import { serveFile } from './static.js';
 // ---------------------------------------------------------------------------
 // Pattern compilation
 // ---------------------------------------------------------------------------
@@ -68,7 +40,43 @@ const https = __importStar(require("https"));
  * @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`.
@@ -103,35 +111,114 @@ function compileGlob(glob) {
         .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
     return new RegExp('^' + src);
 }
+/**
+/**
+ * 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.
+ *
+ * **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.
+ *
+ * ```
+ * :id          →  (?<id>[^/]+)      (any non-slash value)
+ * :id(\d+)     →  (?<id>\d+)        (digits only)
+ * :slug([\w-]+) → (?<slug>[\w-]+)   (word chars and hyphens)
+ * ```
  *
- * The expression matches up to a segment boundary (`/` or end-of-string) so
- * that `/users` never inadvertently matches `/users-admin`.
+ * 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/posts'`.
+ * @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) {
     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('^/?' + src + '(?=/|$)');
+    }
+    catch (e) {
+        throw new SyntaxError(`Invalid inline regex constraint in path '${path}': ${e.message}`);
+    }
 }
 /**
  * Convert any supported path pattern into the single canonical `RegExp`
@@ -140,7 +227,7 @@ 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.
@@ -221,6 +308,78 @@ function matchRouteLayer(layer, req, path) {
     return true;
 }
 // ---------------------------------------------------------------------------
+// Cookie helpers
+// ---------------------------------------------------------------------------
+/**
+ * Decode a raw cookie value, stripping the `j:` prefix and JSON-parsing the
+ * payload when present.  Plain string values are returned unchanged.
+ *
+ * @param raw - The raw cookie value as it appears after the `=` in the header.
+ * @returns The decoded value: a JS value for `j:` cookies, or the raw string.
+ */
+function decodeJsonCookie(raw) {
+    if (!raw.startsWith('j:'))
+        return raw;
+    try {
+        return JSON.parse(raw.slice(2));
+    }
+    catch {
+        return raw; // malformed JSON — fall back to raw string
+    }
+}
+/**
+ * Sign a cookie value with HMAC-SHA256.
+ *
+ * The produced string follows the `cookie-signature` wire format:
+ * `s:<value>.<base64url-HMAC>`, where `<value>` is the raw (possibly
+ * `j:`-prefixed) string and the HMAC is computed over that raw string.
+ *
+ * @param value  - The raw cookie value to sign (may include a `j:` prefix).
+ * @param secret - The HMAC secret.
+ * @returns The signed cookie string with the `s:` prefix.
+ */
+function signCookieValue(value, secret) {
+    const sig = crypto
+        .createHmac('sha256', secret)
+        .update(value)
+        .digest('base64url');
+    return `s:${value}.${sig}`;
+}
+/**
+ * Verify and decode a signed cookie value.
+ *
+ * The input must start with `s:` and follow the format produced by
+ * {@link signCookieValue}: `s:<value>.<base64url-HMAC>`.
+ *
+ * Uses `crypto.timingSafeEqual` to prevent timing-based signature attacks.
+ *
+ * @param signed - The raw `Set-Cookie` value including the `s:` prefix.
+ * @param secret - The HMAC secret to verify against.
+ * @returns The inner value string on success, or `false` when the signature
+ *          is absent or does not match (indicating a tampered cookie).
+ */
+function verifyCookieValue(signed, secret) {
+    if (!signed.startsWith('s:'))
+        return false;
+    const withoutPrefix = signed.slice(2);
+    const lastDot = withoutPrefix.lastIndexOf('.');
+    if (lastDot === -1)
+        return false;
+    const value = withoutPrefix.slice(0, lastDot);
+    const received = withoutPrefix.slice(lastDot + 1);
+    const expected = crypto
+        .createHmac('sha256', secret)
+        .update(value)
+        .digest('base64url');
+    const receivedBuf = Buffer.from(received, 'base64url');
+    const expectedBuf = Buffer.from(expected, 'base64url');
+    if (receivedBuf.length !== expectedBuf.length)
+        return false;
+    if (!crypto.timingSafeEqual(receivedBuf, expectedBuf))
+        return false;
+    return value;
+}
+// ---------------------------------------------------------------------------
 // HTTP object augmentation
 // ---------------------------------------------------------------------------
 /**
@@ -239,47 +398,159 @@ function matchRouteLayer(layer, req, path) {
  *
  * **Helpers added to `res`:**
  * - `send(data?)`             — write `data` and end the response.
+ * - `json(data)`              — serialise to JSON and end.
  * - `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.
+ * @param req         - The raw incoming message to augment.
+ * @param res         - The raw server response to augment.
+ * @param secret      - Optional cookie-signing secret.
+ * @param trustProxy  - When `true`, resolve `req.ip` from `X-Forwarded-For`.
  */
-function updateHttpObjects(req, res) {
+function updateHttpObjects(req, res, secret, trustProxy) {
     const rReq = req;
     const rRes = res;
     if (rReq.queries)
         return; // Already augmented.
     rReq.queries = {};
+    // Resolve the client IP address.
+    // When trustProxy is true the leftmost value in X-Forwarded-For is used
+    // (the originating client behind the proxy chain).  Otherwise we read the
+    // raw TCP remote address directly from the socket, which cannot be spoofed.
+    if (trustProxy) {
+        const xff = req.headers['x-forwarded-for'];
+        const first = Array.isArray(xff) ? xff[0] : xff;
+        rReq.ip = (first ? first.split(',')[0].trim() : req.socket?.remoteAddress) ?? '';
+    }
+    else {
+        rReq.ip = req.socket?.remoteAddress ?? '';
+    }
     const qry = new URL(`http://${req.headers.host}${req.url}`);
     rReq.originalUrl = req.url;
     rReq.path = qry.pathname;
     // Parse URL query parameters.
+    // FEAT-03: repeated keys (e.g. ?tag=a&tag=b) accumulate into arrays.
     const urlParams = {};
-    for (const [key, value] of qry.searchParams.entries())
-        urlParams[key] = value;
+    for (const [key, value] of qry.searchParams.entries()) {
+        const existing = urlParams[key];
+        if (existing === undefined) {
+            urlParams[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            urlParams[key] = [existing, value];
+        }
+    }
     rReq.queries.url = urlParams;
-    rReq.params = { ...urlParams };
+    // params stays StringMap — use first value for repeated keys.
+    const flatParams = {};
+    for (const [key, value] of Object.entries(urlParams)) {
+        flatParams[key] = Array.isArray(value) ? value[0] : value;
+    }
+    rReq.params = flatParams;
     // Parse cookies.
     if (rReq.cookies == null) {
         rReq.cookies = {};
         if (req.headers.cookie) {
-            for (const raw of req.headers.cookie.split(';')) {
-                const eqIdx = raw.indexOf('=');
+            for (const part of req.headers.cookie.split(';')) {
+                const eqIdx = part.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
+                const name = part.slice(0, eqIdx).trim();
+                const rawVal = part.slice(eqIdx + 1).trim();
+                if (rawVal.startsWith('s:')) {
+                    // Signed cookie — verify the HMAC signature.
+                    if (secret) {
+                        const inner = verifyCookieValue(rawVal, secret);
+                        if (inner === false)
+                            continue; // tampered — silently omit
+                        rReq.cookies[name] = decodeJsonCookie(inner);
+                    }
+                    else {
+                        // No secret configured — include the raw value so the application
+                        // can at least inspect that a signed cookie was sent.
+                        rReq.cookies[name] = rawVal;
+                    }
+                }
+                else {
+                    // Plain or JSON-encoded cookie.
+                    rReq.cookies[name] = decodeJsonCookie(rawVal);
+                }
             }
         }
     }
+    const resolvedReqOpts = (opts) => ({
+        limit: opts?.limit ?? '100kb',
+        inflate: opts?.inflate ?? true,
+        reviver: null,
+        strict: opts?.strict ?? false,
+    });
+    rReq.json = (opts) => {
+        // If a body-parsing middleware already consumed the stream, return the cached value.
+        if ('body' in rReq)
+            return Promise.resolve(rReq.body ?? null);
+        return readReqBody(rReq, resolvedReqOpts(opts), 'application/json')
+            .then(ret => {
+            if (ret == null)
+                return null;
+            const charset = extractCharset(ret.mimetype);
+            try {
+                const parsed = JSON.parse(ret.content.toString(charset), opts?.reviver ?? undefined);
+                rReq.body = parsed;
+                return parsed;
+            }
+            catch (ex) {
+                return Promise.reject({ status: 400, message: 'Bad Request: ' + ex.message });
+            }
+        });
+    };
+    rReq.text = (opts) => {
+        // If a body-parsing middleware already consumed the stream, return the cached string.
+        const cached = rReq.body;
+        if (typeof cached === 'string')
+            return Promise.resolve(cached);
+        return readReqBody(rReq, resolvedReqOpts(opts), null)
+            .then(ret => {
+            if (ret == null)
+                return null;
+            const charset = extractCharset(ret.mimetype);
+            return ret.content.toString(charset);
+        });
+    };
+    rReq.formData = (opts) => {
+        // If a body-parsing middleware already consumed the stream, return the cached parts.
+        const cached = rReq.body;
+        if (Array.isArray(cached))
+            return Promise.resolve(cached);
+        return readReqBody(rReq, resolvedReqOpts(opts), 'multipart/form-data')
+            .then(ret => {
+            if (ret == null)
+                return null;
+            try {
+                const parts = parseMultipartBody(ret.mimetype, ret.content);
+                rReq.body = parts;
+                return parts;
+            }
+            catch (ex) {
+                // console.error('Body Err', ex)
+                return Promise.reject({ status: ex.status ?? 500, message: ex.message ?? String(ex) });
+            }
+        });
+    };
     rRes.setHeader('X-Powered-By', 'Expediate');
     rRes.send = (data) => {
         if (data)
             res.write(data);
         res.end();
     };
+    rRes.json = (data) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.write(JSON.stringify(data));
+        res.end();
+    };
     rRes.status = (code, headers) => {
         res.statusCode = code;
         if (headers)
@@ -295,26 +566,88 @@ function updateHttpObjects(req, res) {
     };
     rRes.cookie = (name, value, options) => {
         const opts = options ?? {};
-        if (opts.signed && !req.secret)
-            throw new Error('cookieParser("secret") required for signed cookies');
+        // Serialise: objects get the j: prefix so the reader can JSON-decode them.
         let val = typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value);
-        if (opts.signed)
-            val = 's:' + val; // sign() integration point
+        if (opts.signed) {
+            if (!secret)
+                throw new Error('Signed cookies require a secret — pass { secret } to createRouter()');
+            val = signCookieValue(val, secret);
+        }
         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}`;
+            const maxAgeMs = opts.maxAge;
+            const maxAgeSec = Math.floor(maxAgeMs / 1000);
+            opts.expires = new Date(Date.now() + maxAgeMs);
+            txt += `; Max-Age=${maxAgeSec}`;
         }
         if (opts.expires)
             txt += `; Expires=${opts.expires.toUTCString()}`;
         txt += `; Path=${opts.path ?? '/'}`;
-        res.setHeader('Set-Cookie', txt);
+        if (opts.httpOnly)
+            txt += '; HttpOnly';
+        if (opts.secure)
+            txt += '; Secure';
+        if (opts.sameSite)
+            txt += `; SameSite=${opts.sameSite}`;
+        // Append rather than overwrite so multiple cookies can be set on the same
+        // response.  res.setHeader() would replace any previously set Set-Cookie
+        // header; instead, accumulate into an array.
+        const existing = res.getHeader('Set-Cookie');
+        if (existing == null) {
+            res.setHeader('Set-Cookie', txt);
+        }
+        else if (Array.isArray(existing)) {
+            res.setHeader('Set-Cookie', [...existing, txt]);
+        }
+        else {
+            res.setHeader('Set-Cookie', [existing, txt]);
+        }
+        return rRes;
+    };
+    rRes.download = (filepath, filename) => {
+        const name = filename ?? path.basename(filepath);
+        // Use double-quotes and escape any double-quote in the filename per RFC 6266.
+        const safeName = name.replace(/"/g, '\\"');
+        res.setHeader('Content-Disposition', `attachment; filename="${safeName}"`);
+        // Guard: return 404 when the file does not exist (serveFile would send 500
+        // for any stat error; we want the conventional 404 for downloads).
+        fs.access(filepath, fs.constants.F_OK, (err) => {
+            if (err) {
+                if (!rRes.writableEnded)
+                    rRes.status(404).end('Not Found');
+                return;
+            }
+            serveFile(filepath)(rReq, rRes, () => { });
+        });
+    };
+    rRes.type = (mime) => {
+        res.setHeader('Content-Type', mime);
+        return rRes;
+    };
+    rRes.etag = (value, strong = false) => {
+        res.setHeader('ETag', strong ? `"${value}"` : `W/"${value}"`);
         return rRes;
     };
 }
+/**
+ * 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 pathMatchesLayer(layer, path) {
+    return layer.regex.test(path);
+}
 // ---------------------------------------------------------------------------
-// Route registration
+// Route registration helpers
 // ---------------------------------------------------------------------------
 /**
  * Recursively resolve a `MiddlewareArg` value down to individual `Middleware`
@@ -329,11 +662,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.
  */
@@ -354,6 +683,25 @@ function registerRoute(routes, method, path, arg, stripPath) {
             '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
 // ---------------------------------------------------------------------------
@@ -365,106 +713,204 @@ 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 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'));
+ * const v1 = createRouter('/api/v1');
+ * v1.get('/users', handler);
  *
- * app.listen(3000, () => console.log('Listening on :3000'));
+ * app.use(v1);
+ * app.onError((err, _req, res) => res.status(500).json({ error: String(err) }));
+ * app.setNotFound((_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 = [];
+    /** Currently registered error handler, or `undefined` for the default 500. */
+    let errorHandler;
+    /** Currently registered not-found handler, or `undefined` for the default 404. */
+    let notFoundHandler;
+    /** 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** (or custom `setNotFound` handler) — no layer's path matched.
+     * - **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.
+        const invokeErrorHandler = (e) => {
+            if (res.writableEnded)
+                return;
+            if (errorHandler) {
+                try {
+                    errorHandler(e, req, res);
+                }
+                catch (e2) {
+                    // console.error('Root Err', e2)
+                    if (!res.writableEnded)
+                        res.status(500).end(`Error ${method} ${url}`);
+                }
+            }
+            else {
+                console.warn(e);
+                res.status(500).end(`Error ${method} ${url}`);
+            }
+        };
+        // ── 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
+                        // For prefix layers (use), restore req.path after the sub-router
+                        // calls done() so that subsequent sibling layers see the original path.
+                        invoke(layer.middleware, () => {
+                            req.path = pathBefore;
                             next();
                         });
+                        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) {
+                // Path is registered, but not for this method.
+                const allow = [...allowedMethods].sort().join(', ');
+                res.status(405, { Allow: allow }).end(`Cannot ${method} ${url}`);
+                return;
             }
+            // Genuine 404 — delegate to parent router, not-found handler, or default.
             if (done)
                 return done();
+            if (notFoundHandler) {
+                try {
+                    notFoundHandler(req, res, () => { });
+                }
+                catch (e) {
+                    invokeErrorHandler(e);
+                }
+                return;
+            }
             res.status(404).end(`Cannot ${method} ${url}`);
         };
         try {
             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) => {
@@ -472,31 +918,113 @@ 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),
+        // ── onError ─────────────────────────────────────────────────────────────
+        onError(handler) {
+            errorHandler = handler;
+        },
+        // ── setNotFound ──────────────────────────────────────────────────────────
+        setNotFound(handler) {
+            notFoundHandler = 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