expediate 1.0.0 → 1.0.1

package/src/router.ts

@@ -0,0 +1,736 @@
+/* Copyright 2021 Fabien Bavent
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+'use strict';
+
+import * as http from 'http';
+import * as https from 'https';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A key-value map of arbitrary string values. */
+type StringMap = Record<string, string>;
+
+/**
+ * Extended HTTP incoming message that carries parsed routing metadata.
+ * Augments the standard `http.IncomingMessage` with fields populated by
+ * the router before any middleware is invoked.
+ */
+interface RouterRequest extends http.IncomingMessage {
+  /** The original, unmodified URL string from the HTTP request. */
+  originalUrl: string;
+  /**
+   * The current path being matched. Prefix-style layers (`use`)
+   * rewrite this field after matching so that nested routers only see the
+   * remaining suffix. Exact-method layers (`all`, `get`, `post`, etc.) leave it
+   * untouched so that chained middlewares sharing the same path each match.
+   */
+  path: string;
+  /**
+   * Aggregated parameters from all sources.
+   * URL query parameters are merged first; named route parameters (from both
+   * plain-string and RegExp patterns) override them when a route matches.
+   */
+  params: StringMap;
+  /**
+   * Structured query buckets:
+   * - `url`   — parameters parsed from the query string.
+   * - `route` — named parameters captured from the route pattern.
+   */
+  queries: {
+    url?: StringMap;
+    route?: StringMap;
+  };
+  /** Parsed cookies sent with the request. */
+  cookies: StringMap;
+}
+
+/**
+ * Extended HTTP server response with convenience helpers.
+ * Augments the standard `http.ServerResponse`.
+ */
+interface RouterResponse extends http.ServerResponse {
+  /**
+   * Write `data` (if provided) and end the response.
+   * Equivalent to `res.write(data); res.end()`.
+   */
+  send(data?: string): void;
+  /**
+   * Set the HTTP status code and optional response headers, then return
+   * `this` so calls can be chained (e.g. `res.status(404).end(...)`).
+   */
+  status(code: number, headers?: StringMap): this;
+  /** Redirect the client to `url` with a 302 Found response. */
+  redirect(url: string): void;
+  /**
+   * Append a `Set-Cookie` header for the given `name`/`value` pair.
+   * Returns `this` to allow chaining.
+   */
+  cookie(name: string, value: string | object, options?: CookieOptions): this;
+}
+
+/** Options accepted by `res.cookie()`. */
+interface CookieOptions {
+  /** Sign the cookie value (requires a secret on the request). */
+  signed?: boolean;
+  /** Expiry date for the cookie. */
+  expires?: Date;
+  /** Max age in milliseconds; converted to seconds in the `Set-Cookie` header. */
+  maxAge?: number;
+  /** Cookie path (defaults to `'/'`). */
+  path?: string;
+}
+
+/** Options for HTTPS servers passed to `router.listen()`. */
+interface TlsOptions {
+  key: string | Buffer;
+  cert: string | Buffer;
+  [key: string]: unknown;
+}
+
+/**
+ * A middleware function. Receives the current request and response objects
+ * and a `next` callback to hand control to the next registered middleware.
+ */
+type Middleware = (
+  req: RouterRequest,
+  res: RouterResponse,
+  next: NextFunction,
+) => void;
+
+/** Callback used to pass control to the next matching middleware. */
+type NextFunction = () => void;
+
+/**
+ * A value that can be registered as a route handler: a single `Middleware`
+ * function, a `Router` instance (whose `listener` will be used), or an array
+ * of either. Arrays may not be nested.
+ */
+type MiddlewareArg = Middleware | Router | (Middleware | Router)[];
+
+/**
+ * Internal representation of a single registered route.
+ * One layer is created per middleware function for every `router.get(...)` /
+ * `router.use(...)` etc. call, and stored in the route table.
+ */
+interface Layer {
+  /** HTTP method this layer is restricted to, or `null` for any method. */
+  method: string | null;
+  /** The original path pattern supplied by the caller. */
+  path: string | RegExp;
+  /**
+   * The compiled `RegExp` used for matching, regardless of whether the
+   * original `path` was a plain string, a glob, or already a `RegExp`.
+   *
+   * - Plain strings (e.g. `'/users/:id'`) are compiled with named capture
+   *   groups so that `:id` becomes `(?<id>[^/]+)`.
+   * - Glob strings (e.g. `'/**\/*.php'`) are compiled following `.gitignore`
+   *   wildcard rules.
+   * - `RegExp` values are stored as-is; named groups are surfaced directly
+   *   as route parameters.
+   */
+  regex: RegExp;
+  /**
+   * When `true`, the portion of `req.path` consumed by `layer.regex` is
+   * stripped before invoking the middleware, exposing only the remaining
+   * suffix to nested routers.
+   *
+   * Set to `true` for prefix-style registrations (`use`) and
+   * `false` for exact-method routes (`all`, `get`, `post`, etc.). Stripping on
+   * exact-match routes would break chained middlewares sharing the same path,
+   * because each subsequent layer would see a truncated path that no longer
+   * matches its own pattern.
+   */
+  stripPath: boolean;
+  /** The middleware function to invoke when the layer matches. */
+  middleware: Middleware;
+}
+
+/**
+ * The public interface of the object returned by `createRouter()`.
+ *
+ * All route-registration methods share the same uniform signature: a mandatory
+ * `path` argument followed by any number of `MiddlewareArg` values.
+ * A `MiddlewareArg` may be a `Middleware` function, a `Router` instance
+ * (whose `listener` is used automatically), or an array of either.
+ */
+interface Router {
+  /**
+   * Register middleware for all HTTP methods, scoped to `path`.
+   * The matched path prefix is stripped from `req.path` before the middleware
+   * is invoked, so nested routers only see the remaining suffix.
+   * Equivalent to Express's `app.use()`.
+   */
+  use(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /**
+   * Register middleware for all HTTP methods.
+   * Unlike `use`, it doesn't strips the matched prefix from `req.path`.
+   */
+  all(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /** Register middleware for `GET` requests. */
+  get(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /** Register middleware for `PUT` requests. */
+  put(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /** Register middleware for `POST` requests. */
+  post(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /** Register middleware for `DELETE` requests. */
+  delete(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /** Register middleware for `PATCH` requests. */
+  patch(path: string | RegExp, ...args: MiddlewareArg[]): void;
+  /**
+   * Start listening on the given port.
+   * When `opts` contains both `key` and `cert`, an HTTPS server is created;
+   * otherwise a plain HTTP server is used.
+   */
+  listen(port: number, opts?: TlsOptions | (() => void), cb?: () => void): void;
+  /**
+   * The underlying `(req, res, next)` function, allowing this router to be
+   * mounted as middleware inside another router:
+   * `parent.use('/api', child)`.
+   */
+  readonly listener: Middleware;
+}
+
+// ---------------------------------------------------------------------------
+// Pattern compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Determine whether a path string contains glob characters (`*` or `?`).
+ *
+ * A pattern is considered a glob when it contains at least one unescaped
+ * `*` or `?` character, following the same convention as `.gitignore`.
+ *
+ * @param pattern - The path string to inspect.
+ * @returns `true` if the pattern should be treated as a glob.
+ */
+function isGlobPattern(pattern: string): boolean {
+  return /(?<!\\)[*?]/.test(pattern);
+}
+
+/**
+ * Compile a `.gitignore`-style glob string into a prefix-anchored `RegExp`.
+ *
+ * Supported wildcard syntax:
+ * - `?`  — matches exactly one character that is not `/`.
+ * - `*`  — matches zero or more characters that are not `/`.
+ * - `**` — matches zero or more path segments (any characters including `/`).
+ *
+ * The returned expression is anchored at the start (`^`) so it always matches
+ * a prefix of the current path; the matched portion is stripped by
+ * `matchRouteLayer` when `layer.stripPath` is `true`.
+ *
+ * @param glob - The glob pattern to compile.
+ * @returns A prefix-anchored `RegExp`.
+ *
+ * @example
+ * ```ts
+ * compileGlob('/**\/*.php').test('/admin/index.php'); // true
+ * compileGlob('/api/*')    .test('/api/users');       // true
+ * compileGlob('/api/*')    .test('/api/users/123');   // false
+ * ```
+ */
+function compileGlob(glob: string): RegExp {
+  // Escape all regex special characters, leaving our wildcard characters intact.
+  let src = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+  // Replace in order: `**` must be handled before `*`.
+  src = src
+    .replace(/\*\*/g, '\x00GLOBSTAR\x00') // temporary placeholder
+    .replace(/\*/g, '[^/]*')              // single-segment wildcard
+    .replace(/\?/g, '[^/]')              // single-character wildcard
+    .replace(/\x00GLOBSTAR\x00/g, '.*'); // cross-segment wildcard
+
+  return new RegExp('^' + src);
+}
+
+/**
+ * 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.
+ *
+ * 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'`.
+ * @returns A prefix-anchored `RegExp` with named groups for each parameter.
+ *
+ * @example
+ * ```ts
+ * const re = compilePlainPath('/users/:id');
+ * re.exec('/users/42/comments')?.groups; // { id: '42' }
+ * ```
+ */
+function compilePlainPath(path: string): RegExp {
+  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, '\\$&'), // escaped literal
+    )
+    .join('/');
+
+  // Allow a trailing slash or an additional path segment after the prefix.
+  return new RegExp('^/?' + src + '(?=/|$)');
+}
+
+/**
+ * Convert any supported path pattern into the single canonical `RegExp`
+ * used by `matchRouteLayer`.
+ *
+ * | Input type   | Strategy                                              |
+ * |--------------|-------------------------------------------------------|
+ * | Glob string  | {@link compileGlob} — `.gitignore`-style wildcards    |
+ * | Plain string | {@link compilePlainPath} — `:name` → 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: string | RegExp): RegExp {
+  if (path instanceof RegExp) return path;
+  if (isGlobPattern(path))    return compileGlob(path);
+  return compilePlainPath(path);
+}
+
+// ---------------------------------------------------------------------------
+// Layer construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a `Layer` that represents a single registered route entry.
+ *
+ * The `path` argument may be a plain string with `:name` parameters, a glob
+ * string, or a `RegExp`. In all three cases the pattern is pre-compiled into
+ * a single `RegExp` stored as `layer.regex`.
+ *
+ * @param method     - HTTP method to restrict this layer to (uppercased), or
+ *                     `null` to match any method.
+ * @param path       - URL path pattern (plain string, glob, or `RegExp`).
+ * @param middleware - The middleware function to invoke on a match.
+ * @param stripPath  - When `true`, the matched prefix is stripped from
+ *                     `req.path` before the middleware runs. Pass `true` for
+ *                     prefix/`use` registrations and `false` for exact-method
+ *                     routes so that chained middlewares sharing the same path
+ *                     can each match in turn.
+ * @returns A fully initialised `Layer` ready to be pushed into the route table.
+ * @throws {TypeError} When `middleware` is not a callable function.
+ */
+function buildRouteLayer(
+  method: string | null,
+  path: string | RegExp,
+  middleware: Middleware,
+  stripPath: boolean,
+): Layer {
+  if (typeof middleware !== 'function')
+    throw new TypeError('Incorrect middleware type: expected a function');
+
+  return { method, path, regex: compilePattern(path), stripPath, middleware };
+}
+
+// ---------------------------------------------------------------------------
+// Layer matching
+// ---------------------------------------------------------------------------
+
+/**
+ * Test whether an incoming request matches the given layer and, on success,
+ * mutate `req` to reflect the match.
+ *
+ * All pattern types (plain string, glob, `RegExp`) are handled identically
+ * through `layer.regex`. Named capture groups in the match result are merged
+ * into `req.params` and `req.queries.route`.
+ *
+ * Path stripping is conditional on `layer.stripPath`:
+ * - `true`  (prefix routes) — the matched prefix is removed from `req.path`
+ *   so nested routers only see the remaining suffix.
+ * - `false` (exact-method routes) — `req.path` is left unchanged so that
+ *   subsequent chained middlewares sharing the same pattern can still match.
+ *
+ * @param layer - The layer to test.
+ * @param req   - The incoming request (mutated in-place on a successful match).
+ * @param path  - The current value of `req.path` to test against.
+ * @returns `true` if the layer matches and `req` has been updated;
+ *          `false` otherwise.
+ */
+function matchRouteLayer(
+  layer: Layer,
+  req: RouterRequest,
+  path: string,
+): boolean {
+  if (layer.method && layer.method !== req.method) return false;
+
+  const m = layer.regex.exec(path);
+  if (m === null) return false;
+
+  const captured: StringMap = (m.groups as StringMap | undefined) ?? {};
+
+  // 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.
+  if (layer.stripPath) {
+    req.path = path.slice(m[0].length) || '/';
+  }
+
+  req.queries.route = captured;
+  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.
+ */
+function updateHttpObjects(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): void {
+  const rReq = req as RouterRequest;
+  const rRes = res as RouterResponse;
+
+  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: StringMap = {};
+  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
+      }
+    }
+  }
+
+  rRes.setHeader('X-Powered-By', 'Expediate');
+
+  rRes.send = (data?: string): void => {
+    if (data) res.write(data);
+    res.end();
+  };
+
+  rRes.status = (code: number, headers?: StringMap): typeof rRes => {
+    res.statusCode = code;
+    if (headers)
+      for (const [k, v] of Object.entries(headers)) res.setHeader(k, v);
+    return rRes;
+  };
+
+  rRes.redirect = (url: string): void => {
+    res.setHeader('location', url);
+    res.writeHead(302);
+    res.write(`Found. Redirecting to ${url}`);
+    res.end();
+  };
+
+  rRes.cookie = (
+    name: string,
+    value: string | object,
+    options?: CookieOptions,
+  ): typeof rRes => {
+    const opts: CookieOptions = options ?? {};
+
+    if (opts.signed && !(req as any).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;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route registration
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively resolve a `MiddlewareArg` value down to individual `Middleware`
+ * functions and push one `Layer` per function into the route table.
+ *
+ * Accepted input shapes (processed recursively):
+ * - A `Middleware` function → pushed directly as a layer.
+ * - A `Router` instance    → its `listener` is unwrapped and pushed.
+ * - An array of either     → each element is processed recursively.
+ *
+ * @param routes    - The mutable route table to push into.
+ * @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.
+ * @throws {TypeError} When `arg` contains a value that cannot be resolved to
+ *                     a `Middleware` function.
+ */
+function registerRoute(
+  routes: Layer[],
+  method: string | null,
+  path: string | RegExp,
+  arg: MiddlewareArg,
+  stripPath: boolean,
+): void {
+  if (Array.isArray(arg)) {
+    for (const item of arg) registerRoute(routes, method, path, item, stripPath);
+  } else if (typeof arg === 'function') {
+    routes.push(buildRouteLayer(method, path, arg, stripPath));
+  } else if (arg && typeof (arg as Router).listener === 'function') {
+    // Router instance — unwrap its listener.
+    routes.push(buildRouteLayer(method, path, (arg as Router).listener, stripPath));
+  } else {
+    throw new TypeError(
+      'Unexpected value registered as middleware: expected a Middleware ' +
+      'function, a Router instance, or an array of either',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create and return a new `Router` instance.
+ *
+ * The returned object exposes an Express-compatible routing API and doubles
+ * as a middleware function itself (via `router.listener`), so it can be
+ * mounted inside another router:
+ * ```ts
+ * parent.use('/api', child);
+ * ```
+ *
+ * **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.
+ *
+ * **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()`.
+ *
+ * @returns A fully initialised `Router` ready to register routes and
+ *          optionally start an HTTP or HTTPS server.
+ *
+ * @example
+ * ```ts
+ * const auth = createRouter();
+ * auth.post('/login',  handleLogin);
+ * auth.post('/logout', handleLogout);
+ *
+ * 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.listen(3000, () => console.log('Listening on :3000'));
+ * ```
+ */
+function createRouter(): Router {
+  const routes: Layer[] = [];
+
+  /**
+   * 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.
+   */
+  const listener: Middleware = (
+    req: RouterRequest,
+    res: RouterResponse,
+    done?: NextFunction,
+  ): void => {
+    const method = req.method;
+    const url = req.url;
+    let idx = 0;
+
+    updateHttpObjects(req, res);
+
+    const next: NextFunction = (): void => {
+      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();
+            });
+          }
+          return layer.middleware(req, res, next);
+        }
+      }
+      if (done) return done();
+      res.status(404).end(`Cannot ${method} ${url}`);
+    };
+
+    try {
+      next();
+    } catch (e) {
+      console.warn(e);
+      res.status(500).end(`Error ${method} ${url}`);
+    }
+  };
+
+  // -------------------------------------------------------------------------
+  // Internal helper — produce the uniform registration function for a method.
+  // -------------------------------------------------------------------------
+
+  /**
+   * 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.
+   */
+  function makeRegister(method: string | null, stripPath: boolean) {
+    return (path: string | RegExp, ...args: MiddlewareArg[]): void => {
+      for (const arg of args) registerRoute(routes, method, path, arg, stripPath);
+    };
+  }
+
+  // -------------------------------------------------------------------------
+  // Public router API
+  // -------------------------------------------------------------------------
+
+  const router: Router = {
+    listener,
+    use:    makeRegister(null,     true),   // prefix — strip path
+    all:    makeRegister(null,     false),  // exact  — keep path
+    get:    makeRegister('GET',    false),
+    put:    makeRegister('PUT',    false),
+    post:   makeRegister('POST',   false),
+    delete: makeRegister('DELETE', false),
+    patch:  makeRegister('PATCH',  false),
+
+    listen(
+      port: number,
+      opts?: TlsOptions | (() => void),
+      cb?: () => void,
+    ): void {
+      if (typeof opts === 'function') {
+        cb = opts;
+        opts = undefined;
+      }
+      const rawListener = listener as unknown as http.RequestListener;
+      if (opts && (opts as TlsOptions).key && (opts as TlsOptions).cert)
+        https.createServer(opts as TlsOptions, rawListener).listen(port, cb);
+      else
+        http.createServer(rawListener).listen(port, cb);
+    },
+  };
+
+  return router;
+}
+
+export default createRouter;
+export type {
+  Router,
+  RouterRequest,
+  RouterResponse,
+  Middleware,
+  MiddlewareArg,
+  NextFunction,
+  Layer,
+  CookieOptions,
+  TlsOptions,
+  StringMap,
+};