xanrouter 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Naxrul Ahmed
+
+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.

package/README.md

@@ -1,3 +1,211 @@
-# Temporary Holding Version
+# xanrouter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Tiny router for the web-standard `Request` / `Response` API. Middleware, params, cookies, response headers, static files and a request-scoped context, in one small file. Works on Node 18+, Bun and Deno.
+
+- One dependency: [`regexparam`](https://github.com/lukeed/regexparam)
+- Handlers take a single argument: `next`
+- Request context from anywhere with `route.context()`
+- Express adapter included (`xanrouter/express`)
+
+## Install
+
+```sh
+npm i xanrouter
+```
+
+## Quick start
+
+```ts
+import { Router } from "xanrouter";
+
+const route = Router();
+
+route.use((next) => {
+  // runs for every request
+  return next();
+});
+
+route.use("/api", (next) => {
+  // runs for /api and everything under it
+  return next();
+});
+
+route.get("/", () => new Response("Hello World"));
+
+route.get("/users/:id", () => {
+  const { params } = route.context();
+  return Response.json({ id: params.id });
+});
+
+const res = await route.fetch(new Request("http://localhost/users/42"));
+```
+
+### Use as a server
+
+```ts
+export default route;               // Bun, Cloudflare Workers, `deno serve`
+Bun.serve(route);                   // Bun
+Deno.serve((req) => route.fetch(req)); // Deno
+```
+
+## Routes
+
+`get`, `post`, `put`, `patch`, `delete`, `head`, `options`, `all`.  
+`HEAD` requests fall through to `get` routes. Unmatched requests return `404`; override with `route.notFound(handler)`.
+
+Patterns come from `regexparam`:
+
+```ts
+route.get("/posts/:id?", ...)   // optional param
+route.get("/files/*", ...)      // wildcard -> route.context().params["*"]
+```
+
+Params are URL-decoded.
+
+## Middleware
+
+A handler either returns a `Response` (stops the chain) or calls `next()`.
+
+```ts
+// run code before and after the route
+route.use(async (next) => {
+  const t = Date.now();
+  const res = await next();           // Response, or undefined if no route matched
+  res?.headers.set("x-time", String(Date.now() - t));
+  return res;
+});
+
+// auth on a prefix
+route.use("/admin", (next) => {
+  if (route.context().request.headers.get("authorization") !== "Bearer secret")
+    return new Response("Unauthorized", { status: 401 });
+  return next();
+});
+
+// error handling (uncaught errors otherwise become a plain 500)
+route.use(async (next) => {
+  try { return await next(); }
+  catch (e) { return Response.json({ error: (e as Error).message }, { status: 500 }); }
+});
+```
+
+If a middleware calls `next()` without returning it, the downstream response is still used.
+
+## 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.method;     // "GET"
+ctx.params;     // { id: "42" }
+ctx.query;      // URLSearchParams
+ctx.request;    // the original Request
+```
+
+Calling it outside a request throws.
+
+> **No `AsyncLocalStorage`?** The router falls back to a global "current request". It is only reliable before the first `await` in a handler, so read `route.context()` first and keep the result in a variable.
+
+### Response headers
+
+`ctx.headers()` is a standard `Headers` object for the **response**. It is merged into whatever `Response` your handler returns, and wins over a header with the same name on that response. (Request headers: `ctx.request.headers`.)
+
+```ts
+route.use((next) => {
+  route.context().headers().set("x-request-id", crypto.randomUUID());
+  return next();
+});
+```
+
+### Cookies
+
+```ts
+const cookies = route.context().cookies();
+
+cookies.get("theme");     // from the request Cookie header
+cookies.has("sid");
+cookies.all();            // { theme: "dark", ... }
+
+cookies.set("sid", "abc123", {
+  httpOnly: true,
+  secure: true,
+  sameSite: "lax",        // "lax" | "strict" | "none"
+  maxAge: 3600,           // seconds
+  // path (default "/"), domain, expires, partitioned
+});
+
+cookies.delete("old");    // sends an expired cookie (pass the same path/domain it was set with)
+```
+
+`get` / `has` / `all` reflect changes made earlier in the same request. Setting the same cookie twice sends only the last one. Invalid cookie names, or paths/domains containing `;` or line breaks, throw. `sameSite: "none"` is not checked for `secure`: browsers require it.
+
+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.
+
+## Static files
+
+```ts
+route.static("./public");                                  // serve ./public at /
+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 |
+
+`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.
+
+## Express
+
+```ts
+import express from "express";
+import { Router } from "xanrouter";
+import { expressAdapter } from "xanrouter/express";
+
+const route = Router();
+route.get("/hello/:name", () => new Response("hi " + route.context().params.name));
+
+const app = express();
+app.use(expressAdapter(route, { fallthrough: true })); // 404s continue to later Express handlers
+app.use((req, res) => res.status(404).send("express 404"));
+app.listen(3000);
+```
+
+- Don't put `express.json()` before the adapter; it would consume the request body first.
+- Mounted under a prefix (`app.use("/api", ...)`), your routes must include the prefix: `route.get("/api/users", ...)`.
+- Node 18+, Express 4 or 5.
+
+## API
+
+```ts
+Router(): Router
+
+route.use(handler)
+route.use(path, handler)            // prefix match
+route.get | post | put | patch | delete | head | options | all (path, handler)
+route.static(dir, options?)
+route.notFound(handler)
+route.context(): Context
+route.fetch(request: Request): Promise<Response>
+
+type Handler = (next: () => Promise<Response | undefined>) => Response | void | Promise<Response | void>
+```
+
+All registration methods return the router, so calls can be chained.
+
+## License
+
+MIT

package/dist/express.d.ts

@@ -0,0 +1,7 @@
+import type { Router } from "./index.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>;

package/dist/express.js

@@ -0,0 +1,38 @@
+import { Readable } from "node:stream";
+/** Express (4/5) middleware that serves a Router. */
+export function expressAdapter(route, { fallthrough = false } = {}) {
+    return async (req, res, next) => {
+        try {
+            const hasBody = req.method !== "GET" && req.method !== "HEAD";
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (Array.isArray(v))
+                    v.forEach((x) => headers.append(k, x));
+                else if (v !== undefined)
+                    headers.set(k, String(v));
+            }
+            const request = new Request(`${req.protocol}://${req.get("host")}${req.originalUrl}`, {
+                method: req.method,
+                headers,
+                body: hasBody ? Readable.toWeb(req) : undefined,
+                duplex: "half",
+            });
+            const response = await route.fetch(request);
+            if (fallthrough && response.status === 404)
+                return next();
+            res.status(response.status);
+            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);
+            if (response.body)
+                Readable.fromWeb(response.body).pipe(res);
+            else
+                res.end();
+        }
+        catch (err) {
+            next(err);
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+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;
+export default Router;

package/dist/index.js

@@ -0,0 +1,314 @@
+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;
+}
+export default Router;

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "xanrouter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "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",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "router",
+    "fetch",
+    "request",
+    "response",
+    "middleware",
+    "static",
+    "cookies",
+    "bun",
+    "deno",
+    "express"
+  ],
+  "author": "Naxrul Ahmed (https://github.com/devnax)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/devnax/xanrouter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/devnax/xanrouter/issues"
+  },
+  "homepage": "https://github.com/devnax/xanrouter#readme",
+  "dependencies": {
+    "regexparam": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "express": "^5.0.0",
+    "rimraf": "^6.1.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}