xanrouter 1.0.0 → 1.0.1

package/README.md

@@ -91,13 +91,37 @@ route.use(async (next) => {
 
 If a middleware calls `next()` without returning it, the downstream response is still used.
 
+## Sub-routers
+
+Pass another `Router` to `use`, or to any method, to mount it. The sub-router sees paths with the mount prefix removed.
+
+```ts
+const api = Router();
+api.use((next) => next());                          // only runs for /api/...
+api.get("/users/:id", () => Response.json({ id: route.context().params.id }));
+
+const route = Router();
+route.use("/api", api);                             // GET /api/users/42
+route.use("/orgs/:org", membersRouter);             // params from the prefix are available in the sub-router
+route.post("/users", usersRouter);                  // only POST requests reach usersRouter
+route.use(otherRouter);                             // mount at the root
+```
+
+- If the sub-router doesn't handle the request, or its middleware calls `next()` past its last layer, routing continues with the parent's next routes.
+- Sub-routers share the request's context, cookies and headers, so `route.context()` works in any of them.
+- Inside a sub-router, `ctx.pathname` is relative to it and `ctx.basePath` is the prefix removed so far (full path = `basePath + pathname`; `ctx.request.url` is the original).
+- A sub-router's `notFound` is ignored when it is mounted; the top-level router's `notFound` is used. `sub.fetch()` still uses its own when called directly.
+- `route.static()` inside a sub-router is relative to its mount: `sub.static("./public", { prefix: "/assets" })` mounted at `/v1` serves `/v1/assets/...`.
+- A router can't be mounted on itself.
+
 ## Context
 
 `route.context()` returns the context of the request being handled. It is correct across `await` and overlapping requests when `AsyncLocalStorage` is available (Node, Bun, Deno, Cloudflare Workers with `nodejs_compat`).
 
 ```ts
 const ctx = route.context();
-ctx.pathname;   // "/users/42"
+ctx.pathname;   // "/users/42" (relative to the router handling it)
+ctx.basePath;   // mount prefix removed so far, "" at the top level
 ctx.method;     // "GET"
 ctx.params;     // { id: "42" }
 ctx.query;      // URLSearchParams
@@ -143,6 +167,26 @@ cookies.delete("old");    // sends an expired cookie (pass the same path/domain
 
 Headers and cookies are applied to your handler's response, a custom `notFound` response, and immutable responses such as `Response.redirect()`. A request that ends in an uncaught error gets a plain 500 without them.
 
+### Cookie helpers
+
+`Cookie.parse` and `Cookie.serialize` work on their own, with or without a router.
+
+```ts
+import { Cookie } from "xanrouter";
+
+Cookie.parse("theme=dark; sid=abc%20123");
+// { theme: "dark", sid: "abc 123" }
+
+Cookie.serialize("sid", "abc 123", { httpOnly: true, sameSite: "lax", maxAge: 3600 });
+// "sid=abc%20123; Path=/; Max-Age=3600; HttpOnly; SameSite=Lax"
+
+// e.g. in your own response
+new Response("ok", { headers: { "Set-Cookie": Cookie.serialize("a", "1") } });
+```
+
+- `parse(header)` accepts `null` or `undefined` (returns `{}`). Values are URL-decoded, and the first occurrence of a name wins.
+- `serialize(name, value, options?)` takes the same options as `cookies.set()` and throws on an invalid name.
+
 ## Static files
 
 ```ts
@@ -152,19 +196,19 @@ route.static("./dist", { prefix: "/assets", maxAge: 31536000, immutable: true })
 
 When no file matches, the request continues to the next route. Directories serve `index.html`. Supports `ETag` / `If-None-Match` (304), `Range` requests, `HEAD`, and about 30 common content types. Path traversal is blocked, and dotfiles are hidden.
 
-| Option | Meaning | Default |
-|---|---|---|
-| `prefix` | URL prefix to mount under | `"/"` |
-| `index` | Directory index file, or `false` | `"index.html"` |
-| `dotfiles` | Serve files/folders starting with `.` | `false` |
-| `maxAge` | `Cache-Control: max-age` (seconds) | `0` |
-| `sMaxAge` | `s-maxage` (CDNs) | none |
-| `immutable` | add `immutable` | `false` |
-| `visibility` | `"public"` or `"private"` | `"public"` |
-| `noCache` | add `no-cache` | `false` |
-| `noStore` | send only `no-store` | `false` |
-| `mustRevalidate` | add `must-revalidate` | `false` |
-| `staleWhileRevalidate` | `stale-while-revalidate` (seconds) | none |
+| Option                 | Meaning                               | Default        |
+| ---------------------- | ------------------------------------- | -------------- |
+| `prefix`               | URL prefix to mount under             | `"/"`          |
+| `index`                | Directory index file, or `false`      | `"index.html"` |
+| `dotfiles`             | Serve files/folders starting with `.` | `false`        |
+| `maxAge`               | `Cache-Control: max-age` (seconds)    | `0`            |
+| `sMaxAge`              | `s-maxage` (CDNs)                     | none           |
+| `immutable`            | add `immutable`                       | `false`        |
+| `visibility`           | `"public"` or `"private"`             | `"public"`     |
+| `noCache`              | add `no-cache`                        | `false`        |
+| `noStore`              | send only `no-store`                  | `false`        |
+| `mustRevalidate`       | add `must-revalidate`                 | `false`        |
+| `staleWhileRevalidate` | `stale-while-revalidate` (seconds)    | none           |
 
 `route.static` needs Node-style `fs` (Node, Bun, Deno). It is not available on Cloudflare Workers or in the browser. Symlinks inside the served folder are followed.
 
@@ -173,7 +217,7 @@ When no file matches, the request continues to the next route. Directories serve
 ```ts
 import express from "express";
 import { Router } from "xanrouter";
-import { expressAdapter } from "xanrouter/express";
+import expressAdapter from "xanrouter/express";
 
 const route = Router();
 route.get("/hello/:name", () => new Response("hi " + route.context().params.name));
@@ -193,9 +237,9 @@ app.listen(3000);
 ```ts
 Router(): Router
 
-route.use(handler)
-route.use(path, handler)            // prefix match
-route.get | post | put | patch | delete | head | options | all (path, handler)
+route.use(handlerOrRouter)
+route.use(path, handlerOrRouter)    // prefix match; a Router is mounted under the prefix
+route.get | post | put | patch | delete | head | options | all (path, handlerOrRouter)
 route.static(dir, options?)
 route.notFound(handler)
 route.context(): Context
@@ -208,4 +252,4 @@ All registration methods return the router, so calls can be chained.
 
 ## License
 
-MIT
+MIT

package/dist/cookies.d.ts

@@ -0,0 +1,24 @@
+import type { CookieOptions, Cookies } from "./types.js";
+export type CookieJar = Cookies & {
+    /** Set-Cookie header values queued during this request (internal). */
+    _out(): string[];
+};
+/**
+ * Parse a `Cookie` request header (`"a=1; b=x%20y"`) into a name -> value object.
+ * Values are URL-decoded; if decoding fails the raw value is kept. When a name appears
+ * twice, the first one wins. Accepts null/undefined and returns `{}`.
+ * (The result has no prototype, so a cookie named `__proto__` is harmless.)
+ */
+declare function parse(header: string | null | undefined): Record<string, string>;
+/**
+ * Build a `Set-Cookie` header value. The value is URL-encoded and `Path` defaults to "/".
+ * Throws a TypeError for an invalid cookie name, or a path/domain containing `;` or a line break.
+ */
+declare function serialize(name: string, value: string, o?: CookieOptions): string;
+/** Cookie helpers usable on their own, outside a router. */
+export declare const Cookie: {
+    parse: typeof parse;
+    serialize: typeof serialize;
+};
+export declare function createCookies(header: string | null): CookieJar;
+export {};

package/dist/cookies.js

@@ -0,0 +1,85 @@
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const UNSAFE_ATTR = /[;\r\n]/;
+/**
+ * Parse a `Cookie` request header (`"a=1; b=x%20y"`) into a name -> value object.
+ * Values are URL-decoded; if decoding fails the raw value is kept. When a name appears
+ * twice, the first one wins. Accepts null/undefined and returns `{}`.
+ * (The result has no prototype, so a cookie named `__proto__` is harmless.)
+ */
+function parse(header) {
+    const out = Object.create(null);
+    if (!header)
+        return out;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq < 0)
+            continue;
+        const name = part.slice(0, eq).trim();
+        if (!name || name in out)
+            continue; // first occurrence wins
+        let v = part.slice(eq + 1).trim();
+        if (v.length > 1 && v.startsWith('"') && v.endsWith('"'))
+            v = v.slice(1, -1);
+        try {
+            out[name] = decodeURIComponent(v);
+        }
+        catch {
+            out[name] = v;
+        }
+    }
+    return out;
+}
+/**
+ * Build a `Set-Cookie` header value. The value is URL-encoded and `Path` defaults to "/".
+ * Throws a TypeError for an invalid cookie name, or a path/domain containing `;` or a line break.
+ */
+function serialize(name, value, o = {}) {
+    if (!TOKEN.test(name))
+        throw new TypeError(`Invalid cookie name: ${JSON.stringify(name)}`);
+    const path = o.path ?? "/";
+    if (UNSAFE_ATTR.test(path) || (o.domain && UNSAFE_ATTR.test(o.domain)))
+        throw new TypeError("Invalid cookie path/domain");
+    let c = `${name}=${encodeURIComponent(value)}; Path=${path}`;
+    if (o.domain)
+        c += `; Domain=${o.domain}`;
+    if (o.maxAge !== undefined)
+        c += `; Max-Age=${Math.floor(o.maxAge)}`;
+    if (o.expires)
+        c += `; Expires=${o.expires.toUTCString()}`;
+    if (o.httpOnly)
+        c += "; HttpOnly";
+    if (o.secure)
+        c += "; Secure";
+    if (o.sameSite)
+        c += `; SameSite=${o.sameSite[0].toUpperCase()}${o.sameSite.slice(1)}`;
+    if (o.partitioned)
+        c += "; Partitioned";
+    return c;
+}
+/** Cookie helpers usable on their own, outside a router. */
+export const Cookie = { parse, serialize };
+export function createCookies(header) {
+    let base;
+    const read = () => (base ??= parse(header));
+    const view = new Map(); // undefined = deleted this request
+    const out = new Map(); // name;domain;path -> Set-Cookie (later set replaces earlier)
+    const key = (n, o) => `${n};${o.domain ?? ""};${o.path ?? "/"}`;
+    const jar = {
+        get: (n) => (view.has(n) ? view.get(n) : read()[n]),
+        has: (n) => jar.get(n) !== undefined,
+        all: () => {
+            const o = { ...read() };
+            for (const [k, v] of view)
+                v === undefined ? delete o[k] : (o[k] = v);
+            return o;
+        },
+        set: (n, v, o = {}) => (out.set(key(n, o), serialize(n, v, o)),
+            view.set(n, v),
+            jar),
+        delete: (n, o = {}) => (out.set(key(n, o), serialize(n, "", { ...o, maxAge: 0, expires: new Date(0) })),
+            view.set(n, undefined),
+            jar),
+        _out: () => [...out.values()],
+    };
+    return jar;
+}

package/dist/express.d.ts

@@ -1,7 +1,7 @@
-import type { Router } from "./index.js";
+import type { Router } from "./router.js";
 export interface AdapterOptions {
     /** On a 404 from the router, call next() so later Express handlers run. Default false. */
     fallthrough?: boolean;
 }
 /** Express (4/5) middleware that serves a Router. */
-export declare function expressAdapter(route: Router, { fallthrough }?: AdapterOptions): (req: any, res: any, next: (err?: unknown) => void) => Promise<void>;
+export default function expressAdapter(route: Router, { fallthrough }?: AdapterOptions): (req: any, res: any, next: (err?: unknown) => void) => Promise<void>;

package/dist/express.js

@@ -1,6 +1,6 @@
 import { Readable } from "node:stream";
 /** Express (4/5) middleware that serves a Router. */
-export function expressAdapter(route, { fallthrough = false } = {}) {
+export default function expressAdapter(route, { fallthrough = false } = {}) {
     return async (req, res, next) => {
         try {
             const hasBody = req.method !== "GET" && req.method !== "HEAD";
@@ -21,8 +21,10 @@ export function expressAdapter(route, { fallthrough = false } = {}) {
             if (fallthrough && response.status === 404)
                 return next();
             res.status(response.status);
-            response.headers.forEach((v, k) => { if (k !== "set-cookie")
-                res.setHeader(k, v); });
+            response.headers.forEach((v, k) => {
+                if (k !== "set-cookie")
+                    res.setHeader(k, v);
+            });
             const cookies = response.headers.getSetCookie();
             if (cookies.length)
                 res.setHeader("set-cookie", cookies);

package/dist/finalize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Merge ctx.headers() and the cookies queued by ctx.cookies() into the final Response.
+ * Context headers win over same-named headers on the response.
+ */
+export declare function mergeIntoResponse(res: Response, resHeaders: Headers, cookies: string[]): Response;

package/dist/finalize.js

@@ -0,0 +1,38 @@
+/**
+ * Merge ctx.headers() and the cookies queued by ctx.cookies() into the final Response.
+ * Context headers win over same-named headers on the response.
+ */
+export function mergeIntoResponse(res, resHeaders, cookies) {
+    const extraCookies = resHeaders.getSetCookie();
+    let has = cookies.length > 0 || extraCookies.length > 0;
+    resHeaders.forEach((_v, k) => {
+        if (k !== "set-cookie")
+            has = true;
+    });
+    if (!has)
+        return res;
+    const apply = (h) => {
+        resHeaders.forEach((v, k) => {
+            if (k !== "set-cookie")
+                h.set(k, v);
+        });
+        for (const c of extraCookies)
+            h.append("set-cookie", c);
+        for (const c of cookies)
+            h.append("set-cookie", c);
+    };
+    try {
+        apply(res.headers);
+        return res;
+    }
+    catch {
+        // immutable headers (Response.redirect(), fetch() results): rebuild
+        const h = new Headers(res.headers);
+        apply(h);
+        return new Response(res.body, {
+            status: res.status,
+            statusText: res.statusText,
+            headers: h,
+        });
+    }
+}

package/dist/index.d.ts

@@ -1,83 +1,5 @@
-export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-export type Next = () => Promise<Response | undefined>;
-export interface CookieOptions {
-    /** Default "/". */
-    path?: string;
-    domain?: string;
-    /** Seconds. */
-    maxAge?: number;
-    expires?: Date;
-    httpOnly?: boolean;
-    secure?: boolean;
-    sameSite?: "lax" | "strict" | "none";
-    partitioned?: boolean;
-}
-export interface Cookies {
-    /** Request cookie, or the value set/deleted earlier in this request. */
-    get(name: string): string | undefined;
-    has(name: string): boolean;
-    /** All cookies as the client will see them after this response. */
-    all(): Record<string, string>;
-    /** Queue a Set-Cookie on the response. */
-    set(name: string, value: string, options?: CookieOptions): Cookies;
-    /** Queue an expiring Set-Cookie. Pass the same path/domain the cookie was set with. */
-    delete(name: string, options?: Pick<CookieOptions, "path" | "domain">): Cookies;
-}
-export interface Context {
-    pathname: string;
-    method: string;
-    params: Record<string, string>;
-    request: Request;
-    query: URLSearchParams;
-    /** Read request cookies and queue response cookies. */
-    cookies(): Cookies;
-    /** RESPONSE headers: merged into whatever Response the handler returns. (Request headers: ctx.request.headers) */
-    headers(): Headers;
-}
-type Result = Response | void | undefined | Promise<Response | void | undefined>;
-export type Handler = (next: Next) => Result;
-export interface StaticOptions {
-    /** URL prefix to mount under (default "/"). e.g. "/assets" */
-    prefix?: string;
-    /** Index file for directories (default "index.html"; false disables). */
-    index?: string | false;
-    /** Cache-Control max-age in seconds (default 0). */
-    maxAge?: number;
-    /** Cache-Control s-maxage in seconds (shared caches / CDNs). */
-    sMaxAge?: number;
-    /** Add "immutable": file never changes, skip revalidation (use with hashed filenames). */
-    immutable?: boolean;
-    /** "public" (default) or "private". */
-    visibility?: "public" | "private";
-    /** Add "no-cache": store, but revalidate every time. */
-    noCache?: boolean;
-    /** Send only "no-store": never cache. Overrides every other cache option. */
-    noStore?: boolean;
-    /** Add "must-revalidate". */
-    mustRevalidate?: boolean;
-    /** Add "stale-while-revalidate=<seconds>". */
-    staleWhileRevalidate?: number;
-    /** Serve files/folders starting with "." (default false). */
-    dotfiles?: boolean;
-}
-export interface Router {
-    use(handler: Handler): Router;
-    use(path: string, handler: Handler): Router;
-    get(path: string, handler: Handler): Router;
-    post(path: string, handler: Handler): Router;
-    put(path: string, handler: Handler): Router;
-    patch(path: string, handler: Handler): Router;
-    delete(path: string, handler: Handler): Router;
-    head(path: string, handler: Handler): Router;
-    options(path: string, handler: Handler): Router;
-    all(path: string, handler: Handler): Router;
-    /** Serve static files from a directory. Falls through to next() when no file matches. */
-    static(dir: string, options?: StaticOptions): Router;
-    notFound(handler: Handler): Router;
-    /** Context of the request currently being handled (safe under concurrency). */
-    context(): Context;
-    /** Handle a web Request; method and path are read from it. */
-    fetch(request: Request): Promise<Response>;
-}
-export declare function Router(): Router;
+import { Router } from "./router.js";
+export type * from "./types.js";
+export { Router } from "./router.js";
+export { Cookie } from "./cookies.js";
 export default Router;

package/dist/index.js

@@ -1,314 +1,4 @@
-import { parse } from "regexparam";
-const ANY = /^\/?.*$/;
-let store;
-try {
-    const g = globalThis;
-    const mod = g.process?.getBuiltinModule?.("node:async_hooks") ??
-        (await import(/* @vite-ignore */ /* webpackIgnore: true */ ["node:async", "hooks"].join("_")));
-    store = new mod.AsyncLocalStorage();
-}
-catch {
-    store = undefined;
-}
-let current;
-const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
-const UNSAFE_ATTR = /[;\r\n]/;
-function parseCookies(header) {
-    const out = Object.create(null);
-    if (!header)
-        return out;
-    for (const part of header.split(";")) {
-        const eq = part.indexOf("=");
-        if (eq < 0)
-            continue;
-        const name = part.slice(0, eq).trim();
-        if (!name || name in out)
-            continue; // first occurrence wins
-        let v = part.slice(eq + 1).trim();
-        if (v.length > 1 && v.startsWith('"') && v.endsWith('"'))
-            v = v.slice(1, -1);
-        try {
-            out[name] = decodeURIComponent(v);
-        }
-        catch {
-            out[name] = v;
-        }
-    }
-    return out;
-}
-function serializeCookie(name, value, o) {
-    if (!TOKEN.test(name))
-        throw new TypeError(`Invalid cookie name: ${JSON.stringify(name)}`);
-    const path = o.path ?? "/";
-    if (UNSAFE_ATTR.test(path) || (o.domain && UNSAFE_ATTR.test(o.domain)))
-        throw new TypeError("Invalid cookie path/domain");
-    let c = `${name}=${encodeURIComponent(value)}; Path=${path}`;
-    if (o.domain)
-        c += `; Domain=${o.domain}`;
-    if (o.maxAge !== undefined)
-        c += `; Max-Age=${Math.floor(o.maxAge)}`;
-    if (o.expires)
-        c += `; Expires=${o.expires.toUTCString()}`;
-    if (o.httpOnly)
-        c += "; HttpOnly";
-    if (o.secure)
-        c += "; Secure";
-    if (o.sameSite)
-        c += `; SameSite=${o.sameSite[0].toUpperCase()}${o.sameSite.slice(1)}`;
-    if (o.partitioned)
-        c += "; Partitioned";
-    return c;
-}
-function createCookies(header) {
-    let base;
-    const read = () => (base ??= parseCookies(header));
-    const view = new Map(); // undefined = deleted this request
-    const out = new Map(); // name;domain;path -> Set-Cookie (later set replaces earlier)
-    const key = (n, o) => `${n};${o.domain ?? ""};${o.path ?? "/"}`;
-    const jar = {
-        get: (n) => (view.has(n) ? view.get(n) : read()[n]),
-        has: (n) => jar.get(n) !== undefined,
-        all: () => {
-            const o = { ...read() };
-            for (const [k, v] of view)
-                v === undefined ? delete o[k] : (o[k] = v);
-            return o;
-        },
-        set: (n, v, o = {}) => (out.set(key(n, o), serializeCookie(n, v, o)), view.set(n, v), jar),
-        delete: (n, o = {}) => (out.set(key(n, o), serializeCookie(n, "", { ...o, maxAge: 0, expires: new Date(0) })), view.set(n, undefined), jar),
-        _out: () => [...out.values()],
-    };
-    return jar;
-}
-const MIME = {
-    html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8", css: "text/css; charset=utf-8",
-    js: "text/javascript; charset=utf-8", mjs: "text/javascript; charset=utf-8", json: "application/json; charset=utf-8",
-    map: "application/json; charset=utf-8", txt: "text/plain; charset=utf-8", csv: "text/csv; charset=utf-8",
-    xml: "application/xml; charset=utf-8", svg: "image/svg+xml", png: "image/png", jpg: "image/jpeg",
-    jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", avif: "image/avif", ico: "image/x-icon",
-    woff: "font/woff", woff2: "font/woff2", ttf: "font/ttf", otf: "font/otf", mp4: "video/mp4",
-    webm: "video/webm", mp3: "audio/mpeg", wav: "audio/wav", pdf: "application/pdf", wasm: "application/wasm",
-};
-// Lazy Node builtin loader: keeps the router importable where node: modules don't exist.
-const nodeMod = async (name) => globalThis.process?.getBuiltinModule?.(name) ??
-    (await import(/* @vite-ignore */ /* webpackIgnore: true */ name));
-export function Router() {
-    const layers = [];
-    let notFoundHandler = () => new Response("Not Found", { status: 404 });
-    const add = (method, path, handler, loose) => {
-        if (path === null) {
-            layers.push({ method, keys: [], pattern: ANY, handler });
-        }
-        else {
-            const { keys, pattern } = parse(path, loose);
-            layers.push({ method, keys, pattern, handler });
-        }
-    };
-    const router = {};
-    router.use = ((a, b) => {
-        typeof a === "function" ? add(null, null, a, true) : add(null, a, b, true);
-        return router;
-    });
-    const verb = (m) => (path, handler) => {
-        add(m, path, handler, false);
-        return router;
-    };
-    router.get = verb("GET");
-    router.post = verb("POST");
-    router.put = verb("PUT");
-    router.patch = verb("PATCH");
-    router.delete = verb("DELETE");
-    router.head = verb("HEAD");
-    router.options = verb("OPTIONS");
-    router.all = (path, handler) => (add("*", path, handler, false), router);
-    router.static = (dir, options = {}) => {
-        const index = options.index === undefined ? "index.html" : options.index;
-        const cc = [];
-        if (options.noStore)
-            cc.push("no-store");
-        else {
-            cc.push(options.visibility ?? "public");
-            if (options.noCache)
-                cc.push("no-cache");
-            cc.push(`max-age=${options.maxAge ?? 0}`);
-            if (options.sMaxAge !== undefined)
-                cc.push(`s-maxage=${options.sMaxAge}`);
-            if (options.staleWhileRevalidate !== undefined)
-                cc.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
-            if (options.mustRevalidate)
-                cc.push("must-revalidate");
-            if (options.immutable)
-                cc.push("immutable");
-        }
-        const cacheControl = cc.join(", ");
-        let prefix = "/" + (options.prefix ?? "").replace(/^\/+|\/+$/g, "");
-        if (prefix === "/")
-            prefix = "";
-        add("GET", prefix || null, async (next) => {
-            const { pathname, method, request } = router.context(); // read before any await (fallback-safe)
-            const [fs, path] = await Promise.all([nodeMod("node:fs"), nodeMod("node:path")]);
-            let rel;
-            try {
-                rel = decodeURIComponent(pathname.slice(prefix.length));
-            }
-            catch {
-                return next();
-            }
-            if (rel.includes("\0"))
-                return next();
-            if (!options.dotfiles && rel.split(/[\\/]/).some((seg) => seg.startsWith(".")))
-                return next();
-            const root = path.resolve(dir);
-            let file = path.resolve(root, "." + path.sep + rel);
-            if (file !== root && !file.startsWith(root + path.sep))
-                return next(); // path traversal guard
-            let st = await fs.promises.stat(file).catch(() => null);
-            if (st?.isDirectory()) {
-                if (!index)
-                    return next();
-                file = path.join(file, index);
-                st = await fs.promises.stat(file).catch(() => null);
-            }
-            if (!st?.isFile())
-                return next();
-            const ext = path.extname(file).slice(1).toLowerCase();
-            const headers = new Headers({
-                "Content-Type": MIME[ext] ?? "application/octet-stream",
-                "Accept-Ranges": "bytes",
-                "Cache-Control": cacheControl,
-                "Last-Modified": st.mtime.toUTCString(),
-                ETag: `W/"${st.size.toString(16)}-${Math.floor(st.mtimeMs).toString(16)}"`,
-            });
-            if (request.headers.get("if-none-match") === headers.get("ETag"))
-                return new Response(null, { status: 304, headers });
-            let status = 200, start = 0, end = st.size - 1;
-            const range = request.headers.get("range");
-            if (range) {
-                const m = /^bytes=(\d*)-(\d*)$/.exec(range);
-                if (m && (m[1] || m[2])) {
-                    if (m[1]) {
-                        start = +m[1];
-                        if (m[2])
-                            end = Math.min(+m[2], end);
-                    }
-                    else {
-                        start = Math.max(st.size - +m[2], 0);
-                    }
-                    if (start > end || start >= st.size) {
-                        return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${st.size}` } });
-                    }
-                    status = 206;
-                    headers.set("Content-Range", `bytes ${start}-${end}/${st.size}`);
-                }
-            }
-            headers.set("Content-Length", String(st.size === 0 ? 0 : end - start + 1));
-            if (method === "HEAD" || st.size === 0)
-                return new Response(null, { status, headers });
-            const { Readable } = await nodeMod("node:stream");
-            const body = Readable.toWeb(fs.createReadStream(file, { start, end }));
-            return new Response(body, { status, headers });
-        }, true);
-        return router;
-    };
-    router.notFound = (h) => ((notFoundHandler = h), router);
-    router.context = () => {
-        const c = store ? store.getStore() : current;
-        if (!c)
-            throw new Error("route.context() called outside of a request");
-        return c;
-    };
-    router.fetch = async (request) => {
-        const url = new URL(request.url);
-        const method = request.method.toUpperCase();
-        const pathname = url.pathname;
-        const jar = createCookies(request.headers.get("cookie"));
-        const resHeaders = new Headers();
-        const ctx = {
-            pathname, method, params: {}, request, query: url.searchParams,
-            cookies: () => jar,
-            headers: () => resHeaders,
-        };
-        // Merge ctx.headers() and ctx.cookies() changes into the final Response.
-        const finalize = (res) => {
-            const cookies = jar._out();
-            const extraCookies = resHeaders.getSetCookie();
-            let has = cookies.length > 0 || extraCookies.length > 0;
-            resHeaders.forEach((_v, k) => { if (k !== "set-cookie")
-                has = true; });
-            if (!has)
-                return res;
-            const apply = (h) => {
-                resHeaders.forEach((v, k) => { if (k !== "set-cookie")
-                    h.set(k, v); });
-                for (const c of extraCookies)
-                    h.append("set-cookie", c);
-                for (const c of cookies)
-                    h.append("set-cookie", c);
-            };
-            try {
-                apply(res.headers);
-                return res;
-            }
-            catch {
-                // immutable headers (Response.redirect(), fetch() results): rebuild
-                const h = new Headers(res.headers);
-                apply(h);
-                return new Response(res.body, { status: res.status, statusText: res.statusText, headers: h });
-            }
-        };
-        const run = async (i) => {
-            for (; i < layers.length; i++) {
-                const l = layers[i];
-                if (l.method && l.method !== "*" && l.method !== method && !(l.method === "GET" && method === "HEAD"))
-                    continue;
-                const m = l.pattern.exec(pathname);
-                if (!m)
-                    continue;
-                const params = {};
-                l.keys.forEach((k, idx) => {
-                    if (m[idx + 1] !== undefined)
-                        params[k] = decodeURIComponent(m[idx + 1]);
-                });
-                ctx.params = params;
-                const idx = i;
-                let downstream;
-                const next = () => (downstream ??= run(idx + 1).then((r) => {
-                    return r;
-                }));
-                if (!store)
-                    current = ctx; // fallback mode: point global at this request
-                const out = await l.handler(next);
-                if (out instanceof Response)
-                    return out;
-                if (downstream)
-                    return downstream; // middleware called next() without returning
-                return undefined; // handler ended chain without a response
-            }
-            return undefined;
-        };
-        try {
-            const exec = async () => {
-                const res = await run(0);
-                if (res)
-                    return finalize(res);
-                ctx.params = {};
-                if (!store)
-                    current = ctx;
-                return finalize((await notFoundHandler(async () => undefined)));
-            };
-            try {
-                return await (store ? store.run(ctx, exec) : exec());
-            }
-            finally {
-                if (current === ctx)
-                    current = undefined; // fallback mode: don't leak a finished request
-            }
-        }
-        catch (err) {
-            console.error(err);
-            return new Response("Internal Server Error", { status: 500 });
-        }
-    };
-    return router;
-}
+import { Router } from "./router.js";
+export { Router } from "./router.js";
+export { Cookie } from "./cookies.js";
 export default Router;

package/dist/mime.d.ts

@@ -0,0 +1 @@
+export declare const MIME: Record<string, string>;

package/dist/mime.js

@@ -0,0 +1,30 @@
+export const MIME = {
+    html: "text/html; charset=utf-8",
+    htm: "text/html; charset=utf-8",
+    css: "text/css; charset=utf-8",
+    js: "text/javascript; charset=utf-8",
+    mjs: "text/javascript; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    map: "application/json; charset=utf-8",
+    txt: "text/plain; charset=utf-8",
+    csv: "text/csv; charset=utf-8",
+    xml: "application/xml; charset=utf-8",
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    ico: "image/x-icon",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    pdf: "application/pdf",
+    wasm: "application/wasm",
+};

package/dist/router.d.ts

@@ -0,0 +1,23 @@
+import type { Context, Handler, StaticOptions } from "./types.js";
+export interface Router {
+    /** Middleware, or mount another Router at the root. */
+    use(handler: Handler | Router): Router;
+    /** Middleware for a path prefix, or mount a Router under it (prefix is stripped for the sub-router). */
+    use(path: string, handler: Handler | Router): Router;
+    get(path: string, handler: Handler | Router): Router;
+    post(path: string, handler: Handler | Router): Router;
+    put(path: string, handler: Handler | Router): Router;
+    patch(path: string, handler: Handler | Router): Router;
+    delete(path: string, handler: Handler | Router): Router;
+    head(path: string, handler: Handler | Router): Router;
+    options(path: string, handler: Handler | Router): Router;
+    all(path: string, handler: Handler | Router): Router;
+    /** Serve static files from a directory. Falls through to next() when no file matches. */
+    static(dir: string, options?: StaticOptions): Router;
+    notFound(handler: Handler): Router;
+    /** Context of the request currently being handled (safe under concurrency). */
+    context(): Context;
+    /** Handle a web Request; method and path are read from it. */
+    fetch(request: Request): Promise<Response>;
+}
+export declare function Router(): Router;

package/dist/router.js

@@ -0,0 +1,144 @@
+import { parse } from "regexparam";
+import { createCookies } from "./cookies.js";
+import { mergeIntoResponse } from "./finalize.js";
+import { createStatic } from "./static.js";
+import { currentContext, point, release, runInContext } from "./store.js";
+// Symbol.for so two copies of the package can still mount each other.
+const DISPATCH = Symbol.for("xanrouter.dispatch");
+const ANY = /^\/?.*$/;
+export function Router() {
+    const layers = [];
+    let notFoundHandler = () => new Response("Not Found", { status: 404 });
+    const add = (method, path, handler, loose) => {
+        const mount = typeof handler === "function" ? undefined : handler?.[DISPATCH];
+        if (typeof handler !== "function" && typeof mount !== "function") {
+            throw new TypeError("Expected a handler function or a Router");
+        }
+        if (handler === router)
+            throw new Error("A router cannot be mounted on itself");
+        const h = typeof handler === "function" ? handler : undefined;
+        if (path === null) {
+            layers.push({ method, keys: [], pattern: ANY, handler: h, mount });
+        }
+        else {
+            // a mounted Router matches by prefix
+            const { keys, pattern } = parse(path, loose || !!mount);
+            layers.push({ method, keys, pattern, handler: h, mount });
+        }
+    };
+    const router = {};
+    router.use = ((a, b) => {
+        typeof a === "string"
+            ? add(null, a, b, true)
+            : add(null, null, a, true);
+        return router;
+    });
+    const verb = (m) => (path, handler) => {
+        add(m, path, handler, false);
+        return router;
+    };
+    router.get = verb("GET");
+    router.post = verb("POST");
+    router.put = verb("PUT");
+    router.patch = verb("PATCH");
+    router.delete = verb("DELETE");
+    router.head = verb("HEAD");
+    router.options = verb("OPTIONS");
+    router.all = (path, handler) => (add("*", path, handler, false), router);
+    router.static = (dir, options) => {
+        const { prefix, handler } = createStatic(dir, options);
+        add("GET", prefix || null, handler, true);
+        return router;
+    };
+    router.notFound = (h) => ((notFoundHandler = h), router);
+    router.context = currentContext;
+    // Runs this router's layers against `path`. Used by fetch() and when mounted in another router.
+    const dispatch = (ctx, path, base, baseParams, tail) => {
+        const run = async (i) => {
+            for (; i < layers.length; i++) {
+                const l = layers[i];
+                if (l.method &&
+                    l.method !== "*" &&
+                    l.method !== ctx.method &&
+                    !(l.method === "GET" && ctx.method === "HEAD"))
+                    continue;
+                const m = l.pattern.exec(path);
+                if (!m)
+                    continue;
+                const params = { ...baseParams };
+                l.keys.forEach((k, idx) => {
+                    if (m[idx + 1] !== undefined)
+                        params[k] = decodeURIComponent(m[idx + 1]);
+                });
+                // (Re)point the context at this layer. Also restores it after downstream layers have run.
+                const enter = () => {
+                    ctx.pathname = path;
+                    ctx.basePath = base;
+                    ctx.params = params;
+                    point(ctx);
+                };
+                const idx = i;
+                let downstream;
+                const next = () => (downstream ??= run(idx + 1).finally(enter));
+                if (l.mount) {
+                    const consumed = l.pattern === ANY ? 0 : m[0].length;
+                    let rest = path.slice(consumed);
+                    if (!rest.startsWith("/"))
+                        rest = "/" + rest;
+                    return l.mount(ctx, rest, base + path.slice(0, consumed), params, next);
+                }
+                enter();
+                const out = await l.handler(next);
+                if (out instanceof Response)
+                    return out;
+                if (downstream)
+                    return downstream; // middleware called next() without returning
+                return undefined; // handler ended chain without a response
+            }
+            return tail(); // nothing here handled it: continue in the parent router (or end)
+        };
+        return run(0);
+    };
+    router[DISPATCH] = dispatch;
+    router.fetch = async (request) => {
+        const url = new URL(request.url);
+        const method = request.method.toUpperCase();
+        const pathname = url.pathname;
+        const jar = createCookies(request.headers.get("cookie"));
+        const resHeaders = new Headers();
+        const ctx = {
+            pathname,
+            basePath: "",
+            method,
+            params: {},
+            request,
+            query: url.searchParams,
+            cookies: () => jar,
+            headers: () => resHeaders,
+        };
+        const finalize = (res) => mergeIntoResponse(res, resHeaders, jar._out());
+        try {
+            const exec = async () => {
+                const res = await dispatch(ctx, pathname, "", {}, async () => undefined);
+                if (res)
+                    return finalize(res);
+                ctx.params = {};
+                ctx.pathname = pathname;
+                ctx.basePath = "";
+                point(ctx);
+                return finalize((await notFoundHandler(async () => undefined)));
+            };
+            try {
+                return await runInContext(ctx, exec);
+            }
+            finally {
+                release(ctx);
+            }
+        }
+        catch (err) {
+            console.error(err);
+            return new Response("Internal Server Error", { status: 500 });
+        }
+    };
+    return router;
+}

package/dist/static.d.ts

@@ -0,0 +1,9 @@
+import type { Handler, StaticOptions } from "./types.js";
+/**
+ * Build a GET handler that serves files from `dir`.
+ * `prefix` is "" for the root, otherwise "/something" (no trailing slash).
+ */
+export declare function createStatic(dir: string, options?: StaticOptions): {
+    prefix: string;
+    handler: Handler;
+};

package/dist/static.js

@@ -0,0 +1,108 @@
+import { MIME } from "./mime.js";
+import { currentContext } from "./store.js";
+// Lazy Node builtin loader: keeps the router importable where node: modules don't exist.
+const nodeMod = async (name) => globalThis.process?.getBuiltinModule?.(name) ??
+    (await import(/* @vite-ignore */ /* webpackIgnore: true */ name));
+function cacheControlHeader(options) {
+    const cc = [];
+    if (options.noStore)
+        cc.push("no-store");
+    else {
+        cc.push(options.visibility ?? "public");
+        if (options.noCache)
+            cc.push("no-cache");
+        cc.push(`max-age=${options.maxAge ?? 0}`);
+        if (options.sMaxAge !== undefined)
+            cc.push(`s-maxage=${options.sMaxAge}`);
+        if (options.staleWhileRevalidate !== undefined)
+            cc.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+        if (options.mustRevalidate)
+            cc.push("must-revalidate");
+        if (options.immutable)
+            cc.push("immutable");
+    }
+    return cc.join(", ");
+}
+/**
+ * Build a GET handler that serves files from `dir`.
+ * `prefix` is "" for the root, otherwise "/something" (no trailing slash).
+ */
+export function createStatic(dir, options = {}) {
+    const index = options.index === undefined ? "index.html" : options.index;
+    const cacheControl = cacheControlHeader(options);
+    let prefix = "/" + (options.prefix ?? "").replace(/^\/+|\/+$/g, "");
+    if (prefix === "/")
+        prefix = "";
+    const handler = async (next) => {
+        const { pathname, method, request } = currentContext(); // read before any await (fallback-safe)
+        const [fs, path] = await Promise.all([
+            nodeMod("node:fs"),
+            nodeMod("node:path"),
+        ]);
+        let rel;
+        try {
+            rel = decodeURIComponent(pathname.slice(prefix.length));
+        }
+        catch {
+            return next();
+        }
+        if (rel.includes("\0"))
+            return next();
+        if (!options.dotfiles &&
+            rel.split(/[\\/]/).some((seg) => seg.startsWith(".")))
+            return next();
+        const root = path.resolve(dir);
+        let file = path.resolve(root, "." + path.sep + rel);
+        if (file !== root && !file.startsWith(root + path.sep))
+            return next(); // path traversal guard
+        let st = await fs.promises.stat(file).catch(() => null);
+        if (st?.isDirectory()) {
+            if (!index)
+                return next();
+            file = path.join(file, index);
+            st = await fs.promises.stat(file).catch(() => null);
+        }
+        if (!st?.isFile())
+            return next();
+        const ext = path.extname(file).slice(1).toLowerCase();
+        const headers = new Headers({
+            "Content-Type": MIME[ext] ?? "application/octet-stream",
+            "Accept-Ranges": "bytes",
+            "Cache-Control": cacheControl,
+            "Last-Modified": st.mtime.toUTCString(),
+            ETag: `W/"${st.size.toString(16)}-${Math.floor(st.mtimeMs).toString(16)}"`,
+        });
+        if (request.headers.get("if-none-match") === headers.get("ETag"))
+            return new Response(null, { status: 304, headers });
+        let status = 200, start = 0, end = st.size - 1;
+        const range = request.headers.get("range");
+        if (range) {
+            const m = /^bytes=(\d*)-(\d*)$/.exec(range);
+            if (m && (m[1] || m[2])) {
+                if (m[1]) {
+                    start = +m[1];
+                    if (m[2])
+                        end = Math.min(+m[2], end);
+                }
+                else {
+                    start = Math.max(st.size - +m[2], 0);
+                }
+                if (start > end || start >= st.size) {
+                    return new Response(null, {
+                        status: 416,
+                        headers: { "Content-Range": `bytes */${st.size}` },
+                    });
+                }
+                status = 206;
+                headers.set("Content-Range", `bytes ${start}-${end}/${st.size}`);
+            }
+        }
+        headers.set("Content-Length", String(st.size === 0 ? 0 : end - start + 1));
+        if (method === "HEAD" || st.size === 0)
+            return new Response(null, { status, headers });
+        const { Readable } = await nodeMod("node:stream");
+        const body = Readable.toWeb(fs.createReadStream(file, { start, end }));
+        return new Response(body, { status, headers });
+    };
+    return { prefix, handler };
+}

package/dist/store.d.ts

@@ -0,0 +1,9 @@
+import type { Context } from "./types.js";
+/** Run `fn` with `ctx` as the current request context. */
+export declare function runInContext<R>(ctx: Context, fn: () => R): R;
+/** Fallback mode only: point the global at this request. No-op when AsyncLocalStorage is available. */
+export declare function point(ctx: Context): void;
+/** Fallback mode only: don't leak a finished request. */
+export declare function release(ctx: Context): void;
+/** The context of the request currently being handled. Throws outside a request. */
+export declare function currentContext(): Context;

package/dist/store.js

@@ -0,0 +1,33 @@
+let store;
+try {
+    const g = globalThis;
+    const mod = g.process?.getBuiltinModule?.("node:async_hooks") ??
+        (await import(
+        /* @vite-ignore */ /* webpackIgnore: true */ ["node:async", "hooks"].join("_")));
+    store = new mod.AsyncLocalStorage();
+}
+catch {
+    store = undefined;
+}
+let current;
+/** Run `fn` with `ctx` as the current request context. */
+export function runInContext(ctx, fn) {
+    return store ? store.run(ctx, fn) : fn();
+}
+/** Fallback mode only: point the global at this request. No-op when AsyncLocalStorage is available. */
+export function point(ctx) {
+    if (!store)
+        current = ctx;
+}
+/** Fallback mode only: don't leak a finished request. */
+export function release(ctx) {
+    if (current === ctx)
+        current = undefined;
+}
+/** The context of the request currently being handled. Throws outside a request. */
+export function currentContext() {
+    const c = store ? store.getStore() : current;
+    if (!c)
+        throw new Error("route.context() called outside of a request");
+    return c;
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+export type Next = () => Promise<Response | undefined>;
+export interface CookieOptions {
+    /** Default "/". */
+    path?: string;
+    domain?: string;
+    /** Seconds. */
+    maxAge?: number;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+    partitioned?: boolean;
+}
+export interface Cookies {
+    /** Request cookie, or the value set/deleted earlier in this request. */
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    /** All cookies as the client will see them after this response. */
+    all(): Record<string, string>;
+    /** Queue a Set-Cookie on the response. */
+    set(name: string, value: string, options?: CookieOptions): Cookies;
+    /** Queue an expiring Set-Cookie. Pass the same path/domain the cookie was set with. */
+    delete(name: string, options?: Pick<CookieOptions, "path" | "domain">): Cookies;
+}
+export interface Context {
+    /** Path as seen by the router handling the request: any mount prefix is removed. */
+    pathname: string;
+    /** Mount prefix removed so far ("" at the top level). Full path = basePath + pathname. */
+    basePath: string;
+    method: string;
+    params: Record<string, string>;
+    request: Request;
+    query: URLSearchParams;
+    /** Read request cookies and queue response cookies. */
+    cookies(): Cookies;
+    /** RESPONSE headers: merged into whatever Response the handler returns. (Request headers: ctx.request.headers) */
+    headers(): Headers;
+}
+type Result = Response | void | undefined | Promise<Response | void | undefined>;
+export type Handler = (next: Next) => Result;
+export interface StaticOptions {
+    /** URL prefix to mount under (default "/"). e.g. "/assets" */
+    prefix?: string;
+    /** Index file for directories (default "index.html"; false disables). */
+    index?: string | false;
+    /** Cache-Control max-age in seconds (default 0). */
+    maxAge?: number;
+    /** Cache-Control s-maxage in seconds (shared caches / CDNs). */
+    sMaxAge?: number;
+    /** Add "immutable": file never changes, skip revalidation (use with hashed filenames). */
+    immutable?: boolean;
+    /** "public" (default) or "private". */
+    visibility?: "public" | "private";
+    /** Add "no-cache": store, but revalidate every time. */
+    noCache?: boolean;
+    /** Send only "no-store": never cache. Overrides every other cache option. */
+    noStore?: boolean;
+    /** Add "must-revalidate". */
+    mustRevalidate?: boolean;
+    /** Add "stale-while-revalidate=<seconds>". */
+    staleWhileRevalidate?: number;
+    /** Serve files/folders starting with "." (default false). */
+    dotfiles?: boolean;
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xanrouter",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Tiny Request/Response router with middleware, cookies, headers, static files and a global context. Works on Node, Bun and Deno.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,18 +19,17 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE",
-    "package.json"
+    "LICENSE"
   ],
   "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
   "scripts": {
-    "build": "rimraf -rf dist && tsc -p tsconfig.json",
-    "test": "tsx test/router.test.ts && tsx test/static.test.ts && tsx test/context.test.ts && tsx test/express.test.ts",
+    "build": "rimraf dist && tsc -p tsconfig.json",
+    "test": "tsx test/router.test.ts && tsx test/static.test.ts && tsx test/context.test.ts && tsx test/mount.test.ts && tsx test/cookie.test.ts && tsx test/express.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
     "router",
@@ -60,7 +59,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "express": "^5.0.0",
-    "rimraf": "^6.1.4",
+    "rimraf": "^5.0.10",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0"
   }