@johnhenry/letterpress 0.0.3 → 0.1.0

package/CHANGELOG.md

@@ -6,6 +6,62 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 This project will adhere to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once it reaches 1.0.0.
 
+## [0.1.0] - 2026-09-28
+
+### Added
+
+- ✨ **`createRewriter`**: `leroute` (the package letterpress was renamed
+  from -- see the README's provenance note) had a `createRewriter` export
+  (`leroute/rewrite`) for request/response rewriting: rewriting an inbound
+  request's target path/headers before it reaches a handler, and rewriting
+  a handler's response headers/status on the way back out. This never got
+  carried over during the leroute -> `@johnhenry/letterpress` rename --
+  it simply wasn't in the initial `@johnhenry/letterpress` source, a gap
+  in that migration rather than an intentional removal. It was discovered
+  while porting a downstream consumer, `prism` (a live HTTP request
+  inspector/proxy), whose proxy mode depends on it for rewriting proxied
+  requests/responses. Ported unchanged in behavior as `rewrite.mjs`
+  (`createRewriter`, plus `rewriteRequest`/`rewriteResponse`/`addRule`/
+  `removeRule`/`getRules`/`middleware`), exposed via a dedicated
+  `@johnhenry/letterpress/rewrite` subpath -- mirroring how
+  `createFSRouter` is isolated on `@johnhenry/letterpress/fs` rather than
+  the main barrel -- with its own `rewrite.d.ts` types wired into
+  `package.json`'s `exports` map and `tsconfig.json`. Tests ported from
+  leroute's `test/rewrite.mjs` into `test/rewrite.mjs`, plus new
+  `./rewrite` subpath-export regression tests in `test/exports.mjs` and
+  `test/types/fixture.ts` coverage, following the same pattern the `./fs`
+  subpath already established.
+
+- ✨ **`router.mount(prefix, subHandler)`**: another `leroute` capability
+  (`create-lerouter.mjs`'s `router.mount`) dropped during the same rename,
+  found via the same `prism` port -- prism's own top-level router uses it
+  to mount its dashboard sub-router under `/inspect`. Delegates every
+  request under `prefix` to `subHandler` with the prefix stripped from the
+  forwarded request's path; `subHandler` may be a plain `(Request) =>
+  Response` function or an object exposing one as `.fetch`, so a `Router`
+  can mount another `Router`. Ported onto the main barrel (`create-router.mjs`,
+  right alongside `router.endpoint`, not an isolated subpath like `rewrite`
+  -- unlike `rewrite`/`fs`, `mount` is core routing behavior every router
+  needs, not an optional extra), dropping only the old implementation's
+  now-obsolete `middleware` and `request.raw` preservation (the current
+  `createRouter` doesn't have either concept). New `Mountable` type in
+  `types.d.ts`; seven new tests in `test/router.mjs` covering delegation,
+  the bare-prefix-with-no-trailing-segment case, 404 fallthrough for
+  non-matching paths, the `.fetch`-object form, query-string/method
+  preservation on the forwarded request, and ctx forwarding (below).
+
+- ✨ **The router's own dispatch now accepts an optional second `ctx`
+  argument** (`router(request, ctx?)`), merged underneath `init` and the
+  matched route's own params so a route's params can't be shadowed by it,
+  and forwarded to `defaultHandler` too. This was also present in `leroute`
+  (`router(request, ctx = {})`) and dropped during the rename; brought back
+  specifically so `mount()` can hand a mounted sub-router its `mountPrefix`
+  (used by `prism` to reconstruct the full request path for display in its
+  captured-request feed, purely cosmetic but a real fidelity gap otherwise)
+  -- caught by testing `mount()` end-to-end against `prism` itself, not by
+  a direct comparison against the old source this time. Existing single-arg
+  `router(request)` callers are unaffected (`ctx` defaults to `{}`).
+
 ## [0.0.3] - 2026-09-26
 
 ### Fixed

package/README.md

@@ -148,6 +148,23 @@ Creates a new router instance.
 - `errorHandler`: Custom error handler function (optional)
 - `cache`: Caching options (optional)
 
+### `router.mount(prefix: string, subHandler: Mountable): Router`
+
+Delegates every request under `prefix` to `subHandler`, with the prefix
+stripped from the forwarded request's path — e.g. `router.mount("/api",
+apiRouter)` sends a request for `/api/users` to `apiRouter` as `/users`.
+`subHandler` may be a plain `(Request) => Response` function or an object
+exposing one as `.fetch` — a `Router` satisfies both, so one router can
+mount another:
+
+```javascript
+const api = createRouter();
+api.endpoint`GET /users``[]`;
+
+const router = createRouter();
+router.mount("/api", api); // GET /api/users -> api's GET /users
+```
+
 ### `createRoute(options?: RouteInit): Route`
 
 Creates a new route handler.
@@ -191,6 +208,47 @@ import { createFSRouter } from "@johnhenry/letterpress/fs";
 > else (`createRouter`, `createRoute`, `createRequest`, `createResponse`,
 > `HTTPExpression`) is pure and safe to bundle for the browser.
 
+### `createRewriter`
+
+Builds a request/response rewriter for target-URL/path rewriting -- e.g.
+rewriting an inbound path before it reaches a route, or rewriting a
+proxied response's headers/status on the way back out. Useful for proxy
+middleware (rewrite the target URL/path of a proxied request, adjust
+headers, force a status code) as well as plain routing (redirect old
+paths to new ones).
+
+```javascript
+import { createRewriter } from "@johnhenry/letterpress/rewrite";
+
+const rewriter = createRewriter([
+  {
+    match: { path: /^\/api\/v1\/(.*)/ },
+    action: { rewritePath: "/api/v2/$1" },
+  },
+]);
+
+// Wrap a handler: the handler receives the rewritten request, and its
+// response is run back through the rewriter before being returned.
+const handler = rewriter.middleware(async (request) => {
+  const url = new URL(request.url);
+  return new Response(`routed to ${url.pathname}`);
+});
+
+// Or call rewriteRequest/rewriteResponse directly, and manage rules with
+// addRule/removeRule/getRules.
+rewriter.addRule({ match: { path: "/teapot" }, action: { setStatus: 418 } });
+```
+
+> `createRewriter` is imported from the `@johnhenry/letterpress/rewrite`
+> subpath, not the main `@johnhenry/letterpress` barrel, mirroring how
+> `createFSRouter` is isolated on `@johnhenry/letterpress/fs` above.
+>
+> This existed in `leroute` (the package letterpress was renamed from --
+> see the provenance note near the top of this README) but was dropped
+> during that rename. It's ported here, discovered missing while porting a
+> downstream consumer (`prism`, a request inspector/proxy) that relies on
+> it for proxy-mode rewriting -- see CHANGELOG.md.
+
 ### `deconstruct`, `cook`
 
 Lower-level utility functions used to parse and process tagged HTTP template literals. See [api.md](./api.md) for details.
@@ -241,6 +299,13 @@ is designed to pair with a sibling package that does.
   `Route`-shaped function works too; `leserve` is the tested, documented
   pairing, not a hard dependency (it's a `devDependency` here, used only in
   the demo scripts).
+- **[`@johnhenry/prism`](https://github.com/johnhenry/prism)** -- a live
+  HTTP request inspector/proxy that uses `createRouter()` as its top-level
+  router. Porting it surfaced two real gaps left over from letterpress's
+  own rename from `leroute`: `router.mount()` (with the `ctx`-forwarding
+  its `mountPrefix` depends on) and `createRewriter`
+  (`@johnhenry/letterpress/rewrite`) -- both closed as part of that port,
+  see CHANGELOG.md.
 
 ## 🤝 Contributing
 

package/create-router.mjs

@@ -11,7 +11,12 @@ export const createRouter = (initial = {}) => {
     ...init
   } = initial;
 
-  const router = async (request) => {
+  // `ctx` is an optional caller-supplied context object (e.g. `.mount()`
+  // uses it to pass `mountPrefix` down to a mounted sub-router) merged
+  // underneath the router's own `init` and the matched route's own params --
+  // so a route's own params can't be shadowed by a mount's ctx, but a
+  // handler can still read whatever the caller passed in.
+  const router = async (request, ctx = {}) => {
     try {
       for (const [matcher, handler] of routes) {
         const match = matcher(request);
@@ -20,10 +25,10 @@ export const createRouter = (initial = {}) => {
           // directly) is required so that a handler that throws inside an
           // async function (i.e. rejects its returned promise) is still
           // caught below and routed to errorHandler.
-          return await handler(request, { ...init, ...match });
+          return await handler(request, { ...ctx, ...init, ...match });
         }
       }
-      return await defaultHandler(request);
+      return await defaultHandler(request, ctx);
     } catch (error) {
       return errorHandler(error, request);
     }
@@ -57,5 +62,47 @@ export const createRouter = (initial = {}) => {
       return router;
     };
   };
+
+  // Delegate every request under `prefix` to `subHandler`, with the prefix
+  // stripped from the forwarded request's path -- e.g. `router.mount("/api",
+  // apiRouter)` sends a request for `/api/users` to `apiRouter` as `/users`.
+  // `subHandler` may be a plain `(Request) => Response` function or an
+  // object exposing one as `.fetch` (matching how `Router` itself works, so
+  // one router can mount another).
+  router.mount = (prefix, subHandler) => {
+    const normalizedPrefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
+
+    const matcher = (request) => {
+      const url = new URL(request.url);
+      if (
+        url.pathname === normalizedPrefix ||
+        url.pathname.startsWith(normalizedPrefix + "/")
+      ) {
+        return { params: {}, method: request.method, headers: {} };
+      }
+      return null;
+    };
+
+    const handler = (request) => {
+      const url = new URL(request.url);
+      const newPath = url.pathname.slice(normalizedPrefix.length) || "/";
+      const newUrl = new URL(newPath + url.search + url.hash, url.origin);
+
+      const hasBody = request.method !== "GET" && request.method !== "HEAD";
+      const newRequest = new Request(newUrl.toString(), {
+        method: request.method,
+        headers: request.headers,
+        body: hasBody ? request.body : undefined,
+        duplex: hasBody ? "half" : undefined,
+      });
+
+      const sub = typeof subHandler === "function" ? subHandler : subHandler.fetch;
+      return sub(newRequest, { mountPrefix: normalizedPrefix });
+    };
+
+    routes.push([matcher, handler]);
+    return router;
+  };
+
   return router;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/letterpress",
-  "version": "0.0.3",
+  "version": "0.1.0",
   "description": "A tagged-template-string HTTP routing library for defining and matching request handlers with plain JavaScript syntax.",
   "main": "index.mjs",
   "types": "types.d.ts",
@@ -13,6 +13,10 @@
       "types": "./fs.d.ts",
       "default": "./fs-router.mjs"
     },
+    "./rewrite": {
+      "types": "./rewrite.d.ts",
+      "default": "./rewrite.mjs"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -58,4 +62,4 @@
   "dependencies": {
     "theres-waldo": "^0.0.0"
   }
-}
+}

package/rewrite.d.ts

@@ -0,0 +1,61 @@
+// Type declarations for the @johnhenry/letterpress/rewrite subpath.
+//
+// createRewriter is a request/response rewriter for target-URL/path
+// rewriting (e.g. rewriting an inbound path before it reaches a route, or
+// rewriting a proxied response's headers/status on the way back out). It
+// existed in `leroute` (the package letterpress was renamed from) but was
+// dropped during that rename; it's kept on its own subpath here (rather
+// than the main barrel) to mirror how `./fs` is isolated -- see
+// rewrite.mjs's top-of-file comment and CHANGELOG.md.
+
+export type RewriteMatch = {
+  path?: string | RegExp;
+  method?: string;
+};
+
+export type RewriteAction = {
+  setHeader?: Record<string, string>;
+  removeHeader?: string[];
+  // Replacement string for the matched path; supports `$1`-style regex
+  // capture group references when `match.path` is a RegExp.
+  rewritePath?: string;
+  // Response only.
+  setStatus?: number;
+};
+
+export type RewriteRule = {
+  match?: RewriteMatch;
+  action?: RewriteAction;
+};
+
+// The shape returned by getRules(): a rule with its index in the rule
+// list, and any RegExp `match.path` normalized back to its `.source`
+// string.
+export type RewriteRuleSnapshot = {
+  index: number;
+  match: {
+    path?: string;
+    method?: string;
+  };
+  action?: RewriteAction;
+};
+
+// Wraps a Route-shaped handler ((request, context) => Response) with
+// request/response rewriting.
+export type RewriterMiddleware = (
+  next: (request: Request, context?: Record<string, any>) => Response | Promise<Response>
+) => (request: Request, context?: Record<string, any>) => Promise<Response>;
+
+export type Rewriter = {
+  middleware: RewriterMiddleware;
+  rewriteRequest: (request: Request) => Request;
+  rewriteResponse: (response: Response, request?: Request) => Response;
+  addRule: (rule: RewriteRule) => void;
+  removeRule: (index: number) => void;
+  getRules: () => RewriteRuleSnapshot[];
+};
+
+export type CreateRewriter = (initialRules?: RewriteRule[]) => Rewriter;
+
+export declare const createRewriter: CreateRewriter;
+export default createRewriter;

package/rewrite.mjs

@@ -0,0 +1,176 @@
+/**
+ * @file rewrite.mjs
+ * @description Create a request/response rewriter for target-URL/path
+ * rewriting -- e.g. rewriting an inbound path before it reaches a route, or
+ * rewriting a proxied response's headers/status on the way back out.
+ *
+ * This existed in `leroute` (the package letterpress was renamed from --
+ * see the README's provenance note) as `createRewriter`, but was dropped
+ * during the leroute -> @johnhenry/letterpress rename. It's ported here
+ * unchanged in behavior, discovered missing while porting a downstream
+ * consumer (`prism`, a request inspector/proxy) that relies on it for
+ * proxy-mode rewriting.
+ *
+ * Rules format:
+ *   {
+ *     match: { path?: string|RegExp, method?: string },
+ *     action: {
+ *       setHeader?: { [name]: value },
+ *       removeHeader?: string[],
+ *       rewritePath?: string,          // replacement string (supports $1 from regex)
+ *       setStatus?: number,            // response only
+ *     }
+ *   }
+ *
+ * @param {Array} [initialRules=[]]
+ */
+export const createRewriter = (initialRules = []) => {
+  const rules = [...initialRules];
+
+  const matches = (rule, request) => {
+    if (!rule.match) return true;
+    const url = new URL(request.url);
+    if (rule.match.method && rule.match.method.toUpperCase() !== request.method) {
+      return false;
+    }
+    if (rule.match.path) {
+      const pattern = rule.match.path;
+      if (pattern instanceof RegExp) {
+        return pattern.test(url.pathname);
+      }
+      // String match — treat as prefix or exact
+      if (!url.pathname.startsWith(pattern)) return false;
+    }
+    return true;
+  };
+
+  const rewriteRequest = (request) => {
+    let url = new URL(request.url);
+    let headers = new Headers(request.headers);
+    let pathChanged = false;
+
+    for (const rule of rules) {
+      if (!matches(rule, request)) continue;
+      const action = rule.action || {};
+
+      if (action.setHeader) {
+        for (const [name, value] of Object.entries(action.setHeader)) {
+          headers.set(name, value);
+        }
+      }
+      if (action.removeHeader) {
+        for (const name of action.removeHeader) {
+          headers.delete(name);
+        }
+      }
+      if (action.rewritePath) {
+        if (rule.match?.path instanceof RegExp) {
+          url.pathname = url.pathname.replace(rule.match.path, action.rewritePath);
+        } else {
+          url.pathname = action.rewritePath;
+        }
+        pathChanged = true;
+      }
+    }
+
+    if (pathChanged || !headersEqual(headers, request.headers)) {
+      return new Request(url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        duplex: "half",
+      });
+    }
+    return request;
+  };
+
+  const rewriteResponse = (response, request) => {
+    let headers = new Headers(response.headers);
+    let status = response.status;
+    let statusText = response.statusText;
+    let changed = false;
+
+    for (const rule of rules) {
+      // When request is provided, filter rules through matches()
+      // Rules with no match clause still apply globally
+      if (request && !matches(rule, request)) continue;
+
+      const action = rule.action || {};
+      if (action.setHeader) {
+        for (const [name, value] of Object.entries(action.setHeader)) {
+          headers.set(name, value);
+        }
+        changed = true;
+      }
+      if (action.removeHeader) {
+        for (const name of action.removeHeader) {
+          headers.delete(name);
+        }
+        changed = true;
+      }
+      if (action.setStatus) {
+        status = action.setStatus;
+        changed = true;
+      }
+    }
+
+    if (changed) {
+      return new Response(response.body, { status, statusText, headers });
+    }
+    return response;
+  };
+
+  /**
+   * Wraps a Route-shaped handler ((request, context) => Response) with
+   * request/response rewriting: the handler receives the rewritten
+   * request, and the handler's response is then run through
+   * rewriteResponse before being returned.
+   * @param {Function} next - The next handler: (request, context) => Response
+   * @returns {Function} Wrapped handler: (request, context) => Response
+   */
+  const middleware = (next) => async (request, context) => {
+    const rewrittenReq = rewriteRequest(request);
+    const response = await next(rewrittenReq, context);
+    return rewriteResponse(response, request);
+  };
+
+  const addRule = (rule) => {
+    // Convert path string to regex if it looks like one
+    if (rule.match?.path && typeof rule.match.path === "string" && rule.match.path.startsWith("/") && rule.match.path.endsWith("/")) {
+      const inner = rule.match.path.slice(1, -1);
+      try {
+        rule.match.path = new RegExp(inner);
+      } catch {
+        throw new Error(`Invalid regex pattern: ${rule.match.path}`);
+      }
+    }
+    rules.push(rule);
+  };
+
+  const removeRule = (index) => {
+    if (index >= 0 && index < rules.length) {
+      rules.splice(index, 1);
+    }
+  };
+
+  const getRules = () =>
+    rules.map((r, i) => ({
+      index: i,
+      match: {
+        path: r.match?.path instanceof RegExp ? r.match.path.source : r.match?.path,
+        method: r.match?.method,
+      },
+      action: r.action,
+    }));
+
+  return { middleware, rewriteRequest, rewriteResponse, addRule, removeRule, getRules };
+};
+
+const headersEqual = (a, b) => {
+  const aEntries = [...a].sort(([k1], [k2]) => k1.localeCompare(k2));
+  const bEntries = [...b].sort(([k1], [k2]) => k1.localeCompare(k2));
+  if (aEntries.length !== bEntries.length) return false;
+  return aEntries.every(([k, v], i) => bEntries[i][0] === k && bEntries[i][1] === v);
+};
+
+export default createRewriter;

package/test/exports.mjs

@@ -67,3 +67,31 @@ test("@johnhenry/letterpress (self-reference) does not carry createFSRouter", as
   const barrel = await import("@johnhenry/letterpress");
   assert.strictEqual("createFSRouter" in barrel, false);
 });
+
+// Regression tests closing the leroute -> @johnhenry/letterpress migration
+// gap: `createRewriter` existed in leroute (see rewrite.mjs's top-of-file
+// comment and CHANGELOG.md) but was never carried over during the rename.
+// It's exposed the same way createFSRouter is -- a dedicated subpath, not
+// the main barrel -- for consistency with that existing precedent.
+
+test("createRewriter is exported from rewrite.mjs directly", async () => {
+  const rewriteModule = await import("../rewrite.mjs");
+  assert.strictEqual(typeof rewriteModule.createRewriter, "function");
+});
+
+test("package.json exposes a ./rewrite subpath export for createRewriter", async () => {
+  const pkg = await import("../package.json", { with: { type: "json" } });
+  const exportsMap = pkg.default.exports;
+  assert.strictEqual(exportsMap["./rewrite"].default, "./rewrite.mjs");
+  assert.strictEqual(exportsMap["./rewrite"].types, "./rewrite.d.ts");
+});
+
+test("@johnhenry/letterpress/rewrite resolves createRewriter via self-reference", async () => {
+  const rewriteSubpath = await import("@johnhenry/letterpress/rewrite");
+  assert.strictEqual(typeof rewriteSubpath.createRewriter, "function");
+});
+
+test("@johnhenry/letterpress (self-reference) does not carry createRewriter", async () => {
+  const barrel = await import("@johnhenry/letterpress");
+  assert.strictEqual("createRewriter" in barrel, false);
+});

package/test/index.mjs

@@ -3,6 +3,7 @@ import "./http-expression.mjs";
 import "./route.mjs";
 import "./req-res.mjs";
 import "./fs-router.mjs";
+import "./rewrite.mjs";
 import "./dynamic-run.mjs";
 import "./exports.mjs";
 import "./types.test.mjs";

package/test/rewrite.mjs

@@ -0,0 +1,202 @@
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { createRewriter } from "../rewrite.mjs";
+
+// Ported from leroute's test/rewrite.mjs. createRewriter existed in
+// leroute (the package letterpress was renamed from) but was dropped
+// during the leroute -> @johnhenry/letterpress rename; this closes that
+// migration gap -- see rewrite.mjs's top-of-file comment and
+// CHANGELOG.md. Test cases are unchanged from the leroute original.
+
+describe("Rewrite", () => {
+  test("should rewrite request path with regex capture groups", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: /^\/api\/v1\/(.*)/ },
+        action: { rewritePath: "/api/v2/$1" },
+      },
+    ]);
+
+    const req = new Request("http://localhost/api/v1/users");
+    const rewritten = rewriter.rewriteRequest(req);
+    const url = new URL(rewritten.url);
+    assert.equal(url.pathname, "/api/v2/users");
+  });
+
+  test("should set and remove request headers", () => {
+    const rewriter = createRewriter([
+      {
+        action: {
+          setHeader: { "x-custom": "hello" },
+          removeHeader: ["x-remove-me"],
+        },
+      },
+    ]);
+
+    const req = new Request("http://localhost/test", {
+      headers: { "x-remove-me": "gone" },
+    });
+    const rewritten = rewriter.rewriteRequest(req);
+    assert.equal(rewritten.headers.get("x-custom"), "hello");
+    assert.equal(rewritten.headers.get("x-remove-me"), null);
+  });
+
+  test("should set and remove response headers", () => {
+    const rewriter = createRewriter([
+      {
+        action: {
+          setHeader: { "x-powered-by": "letterpress" },
+          removeHeader: ["server"],
+        },
+      },
+    ]);
+
+    const res = new Response("ok", {
+      headers: { server: "old" },
+    });
+    const rewritten = rewriter.rewriteResponse(res);
+    assert.equal(rewritten.headers.get("x-powered-by"), "letterpress");
+    assert.equal(rewritten.headers.get("server"), null);
+  });
+
+  test("should set response status", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: "/teapot" },
+        action: { setStatus: 418 },
+      },
+    ]);
+
+    const req = new Request("http://localhost/teapot");
+    const res = new Response("ok", { status: 200 });
+    const rewritten = rewriter.rewriteResponse(res, req);
+    assert.equal(rewritten.status, 418);
+  });
+
+  test("response rules only apply when request matches (bug fix)", () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: "/admin" },
+        action: { setHeader: { "x-admin": "true" } },
+      },
+    ]);
+
+    const req = new Request("http://localhost/public");
+    const res = new Response("ok");
+    const rewritten = rewriter.rewriteResponse(res, req);
+    // Rule should NOT apply because /public doesn't match /admin
+    assert.equal(rewritten.headers.get("x-admin"), null);
+    // Response should be the same object (unchanged)
+    assert.equal(rewritten, res);
+  });
+
+  test("global rules (no match clause) apply to all responses", () => {
+    const rewriter = createRewriter([
+      {
+        action: { setHeader: { "x-global": "yes" } },
+      },
+    ]);
+
+    const req = new Request("http://localhost/anything");
+    const res = new Response("ok");
+    const rewritten = rewriter.rewriteResponse(res, req);
+    assert.equal(rewritten.headers.get("x-global"), "yes");
+  });
+
+  test("middleware wraps handler correctly", async () => {
+    const rewriter = createRewriter([
+      {
+        match: { path: /^\/old\/(.*)/ },
+        action: {
+          rewritePath: "/new/$1",
+          setHeader: { "x-rewritten": "true" },
+        },
+      },
+    ]);
+
+    // A handler that echoes back the pathname it received
+    const handler = async (request) => {
+      const url = new URL(request.url);
+      return new Response(url.pathname, { status: 200 });
+    };
+
+    const wrapped = rewriter.middleware(handler);
+    const req = new Request("http://localhost/old/stuff");
+    const res = await wrapped(req, {});
+
+    // Handler should have received the rewritten path
+    const body = await res.text();
+    assert.equal(body, "/new/stuff");
+    // Response should have the rewritten header
+    assert.equal(res.headers.get("x-rewritten"), "true");
+  });
+
+  test("addRule with /regex/ string conversion", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({
+      match: { path: "/^\\/api\\/(.*)/" },
+      action: { rewritePath: "/v2/$1" },
+    });
+
+    const rules = rewriter.getRules();
+    assert.equal(rules.length, 1);
+    assert.equal(rules[0].match.path, "^\\/api\\/(.*)");
+  });
+
+  test("addRule with invalid regex throws descriptive error", () => {
+    const rewriter = createRewriter();
+    assert.throws(
+      () => {
+        rewriter.addRule({
+          match: { path: "/[invalid/" },
+          action: {},
+        });
+      },
+      (err) => {
+        assert.ok(err.message.includes("Invalid regex pattern"));
+        return true;
+      }
+    );
+  });
+
+  test("removeRule / getRules CRUD", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({ match: { path: "/a" }, action: {} });
+    rewriter.addRule({ match: { path: "/b" }, action: {} });
+    rewriter.addRule({ match: { path: "/c" }, action: {} });
+
+    assert.equal(rewriter.getRules().length, 3);
+
+    rewriter.removeRule(1);
+    const rules = rewriter.getRules();
+    assert.equal(rules.length, 2);
+    assert.equal(rules[0].match.path, "/a");
+    assert.equal(rules[1].match.path, "/c");
+  });
+
+  test("removeRule ignores out-of-bounds index", () => {
+    const rewriter = createRewriter();
+    rewriter.addRule({ match: { path: "/a" }, action: {} });
+    rewriter.removeRule(5);
+    rewriter.removeRule(-1);
+    assert.equal(rewriter.getRules().length, 1);
+  });
+
+  test("method matching", () => {
+    const rewriter = createRewriter([
+      {
+        match: { method: "POST" },
+        action: { setHeader: { "x-method": "post" } },
+      },
+    ]);
+
+    const getReq = new Request("http://localhost/test", { method: "GET" });
+    const postReq = new Request("http://localhost/test", { method: "POST" });
+
+    const getResult = rewriter.rewriteRequest(getReq);
+    const postResult = rewriter.rewriteRequest(postReq);
+
+    assert.equal(getResult.headers.get("x-method"), null);
+    assert.equal(postResult.headers.get("x-method"), "post");
+  });
+});

package/test/router.mjs

@@ -171,6 +171,87 @@ test("Router - Function handler", async () => {
   assert.equal(response.status, 200);
 });
 
+test("Router - mount delegates matching requests with the prefix stripped", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users``sub: ${(_, { params }) => "users"}`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api/users"));
+  assert.equal(response.status, 200);
+  assert.equal(await response.text(), "sub: users");
+});
+
+test("Router - mount forwards mountPrefix to the sub-router's own handlers via ctx", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users`((_, ctx) => new Response(ctx.mountPrefix));
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api/users"));
+  assert.equal(await response.text(), "/api");
+});
+
+test("Router - a caller-supplied ctx reaches matched handlers and defaultHandler alike", async () => {
+  const router = createRouter({
+    defaultHandler: (_, ctx) => new Response(`default:${ctx.tag}`),
+  });
+  router.endpoint`GET /hit`((_, ctx) => new Response(`hit:${ctx.tag}`));
+
+  const hit = await router(new Request("http://example.com/hit"), { tag: "x" });
+  assert.equal(await hit.text(), "hit:x");
+
+  const miss = await router(new Request("http://example.com/miss"), { tag: "y" });
+  assert.equal(await miss.text(), "default:y");
+});
+
+test("Router - mount matches the bare prefix itself (no trailing segment)", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /``root`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/api"));
+  assert.equal(await response.text(), "root");
+});
+
+test("Router - mount falls through to the outer router's 404 for non-matching paths", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /users``sub: users`;
+  router.mount("/api", sub);
+
+  const response = await router(new Request("http://example.com/other"));
+  assert.equal(response.status, 404);
+});
+
+test("Router - mount accepts an object exposing .fetch (so a router can mount another router)", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /ping``pong`;
+  // `sub` is itself callable (Route & RouterExtension), but this exercises
+  // the `.fetch` branch explicitly by wrapping it in a plain object.
+  router.mount("/api", { fetch: sub });
+
+  const response = await router(new Request("http://example.com/api/ping"));
+  assert.equal(await response.text(), "pong");
+});
+
+test("Router - mount preserves query strings and method/body on the forwarded request", async () => {
+  const router = createRouter();
+  const sub = createRouter();
+  sub.endpoint`GET /search`(async (request) => {
+    const url = new URL(request.url);
+    return new Response(url.search);
+  });
+  router.mount("/api", sub);
+
+  const response = await router(
+    new Request("http://example.com/api/search?q=hello")
+  );
+  assert.equal(await response.text(), "?q=hello");
+});
+
 // Commented out tests
 /*
 test("Router - InlineParam", async () => {

package/test/types/fixture.ts

@@ -38,6 +38,7 @@ import {
   HTTPExpression,
 } from "@johnhenry/letterpress";
 import { createFSRouter } from "@johnhenry/letterpress/fs";
+import { createRewriter } from "@johnhenry/letterpress/rewrite";
 
 // createRouter: a Router is a Route (request, context?) => Response, plus
 // an `.endpoint` tagged-template extension that registers routes.
@@ -136,3 +137,36 @@ async function checkFsRouter() {
   return response === null || response instanceof Response;
 }
 void checkFsRouter;
+
+// createRewriter: only reachable via the "/rewrite" subpath (not the main
+// barrel), mirroring createFSRouter's "/fs" subpath precedent. Ported from
+// leroute -- see rewrite.mjs's top-of-file comment and CHANGELOG.md.
+const rewriter = createRewriter([
+  {
+    match: { path: /^\/old\/(.*)/ },
+    action: { rewritePath: "/new/$1", setHeader: { "x-rewritten": "true" } },
+  },
+]);
+const rewrittenRequest: Request = rewriter.rewriteRequest(
+  new Request("http://localhost/old/stuff")
+);
+void rewrittenRequest;
+const rewrittenResponse: Response = rewriter.rewriteResponse(
+  new Response("ok"),
+  new Request("http://localhost/old/stuff")
+);
+void rewrittenResponse;
+rewriter.addRule({ match: { path: "/teapot" }, action: { setStatus: 418 } });
+rewriter.removeRule(0);
+const ruleSnapshots = rewriter.getRules();
+const firstRuleIndex: number = ruleSnapshots[0]?.index ?? -1;
+void firstRuleIndex;
+const wrapped = rewriter.middleware(async (request: Request) => {
+  void request;
+  return new Response("ok");
+});
+async function checkRewriterMiddleware() {
+  const response = await wrapped(new Request("http://localhost/old/stuff"), {});
+  return response instanceof Response;
+}
+void checkRewriterMiddleware;

package/tsconfig.json

@@ -15,6 +15,7 @@
     "include": [
         "types.d.ts",
         "fs.d.ts",
+        "rewrite.d.ts",
         "test/types/**/*.ts"
     ]
 }

package/types.d.ts

@@ -19,12 +19,18 @@ export type RouterEndpointResponder = {
   (handler: Route): Router;
 };
 
+// A handler mountable under a Router prefix: a plain (Request) => Response
+// function, or an object exposing one as `.fetch` (so a Router can mount
+// another Router).
+export type Mountable = Route | { fetch: Route };
+
 // Extension for the Router to add endpoints
 export type RouterExtension = {
   endpoint: (
     template: TemplateStringsArray,
     ...substitutions: any[]
   ) => RouterEndpointResponder;
+  mount: (prefix: string, subHandler: Mountable) => Router;
 };
 
 // Combines Route and RouterExtension