astro-routify 1.0.0 → 1.1.0

package/README.md

@@ -3,44 +3,75 @@
 **A high-performance API router for [Astro](https://astro.build/) built on a Trie matcher.**  
 Define API routes using clean, flat structures — no folders or boilerplate logic.
 
+![npm](https://img.shields.io/npm/v/astro-routify)
+![license](https://img.shields.io/npm/l/astro-routify)
+![downloads](https://img.shields.io/npm/dt/astro-routify)
+![feedback-welcome](https://img.shields.io/badge/feedback-welcome-blue)
+
 ---
 
+## Installing
+
+```shell
+npm install astro-routify
+```
+
 ## ⚡️ Quickstart
 
 ```ts
 // src/pages/api/index.ts
-import { defineRoute, defineRouter, HttpMethod, ok } from "astro-routify";
+import {
+  defineRoute,
+  defineRouter,
+  defineGroup,
+  HttpMethod,
+  ok,
+} from 'astro-routify';
+
+const userGroup = defineGroup('/users', (group) => {
+  group.addGet('/:id', ({ params }) => ok({ id: params.id }));
+});
 
 export const GET = defineRouter([
-  defineRoute(HttpMethod.GET, "/ping", () => ok("pong")),
-  defineRoute(HttpMethod.GET, "/users/:id", ({ params }) => ok({ id: params.id }))
+  defineRoute(HttpMethod.GET, '/ping', () => ok('pong')),
+  ...userGroup.getRoutes(),
 ]);
 ```
 
 Or to handle everything in a single place:
 
 ```ts
-import { RouterBuilder, defineRoute, HttpMethod, ok } from "astro-routify";
+import { RouterBuilder, ok } from 'astro-routify';
 
 const builder = new RouterBuilder();
-builder.register([
-  defineRoute(HttpMethod.GET, "/ping", () => ok("pong")),
-  defineRoute(HttpMethod.POST, "/submit", async ({ request }) => {
+
+builder
+  .addGet('/ping', () => ok('pong'))
+  .addPost('/submit', async ({ request }) => {
     const body = await request.json();
     return ok({ received: body });
-  })
-]);
+  });
 
 export const ALL = builder.build(); // catch-all
 ```
 
+## 💡 Full Example
+
+You can find an implementation example in the [astro-routify-example](https://github.com/oamm/astro-routify-example) repository.
+It showcases a minimal Astro app with API endpoints configured under:
+
+```text
+/src/pages/api/[...path].ts
+```
+
+This setup demonstrates how to route requests dynamically using astro-routify, while still leveraging Astro's native endpoint system.
+
 ---
 
 ## 🚀 Features
 
 - ⚡ Fully compatible with Astro’s native APIContext — no extra setup needed.
-- 🧩 Use middleware, access cookies, headers, and request bodies exactly as you would in a normal Astro endpoints.
-
+- 🧩 Use middleware, access cookies, headers, and request bodies exactly as you would in a normal Astro endpoint.
 - ✅ Flat-file, code-based routing (no folders required)
 - ✅ Dynamic segments (`:id`)
 - ✅ ALL-mode for monolithic routing (`RouterBuilder`)
@@ -48,6 +79,8 @@ export const ALL = builder.build(); // catch-all
 - ✅ Trie-based matcher for fast route lookup
 - ✅ Fully typed — no magic strings
 
+> 🔄 See [CHANGELOG.md](./CHANGELOG.md) for recent updates and improvements.
+
 ---
 
 ## 🧠 Core Concepts
@@ -57,8 +90,8 @@ export const ALL = builder.build(); // catch-all
 Declare a single route:
 
 ```ts
-defineRoute(HttpMethod.GET, "/users/:id", ({ params }) => {
-  return ok({ userId: params.id });
+defineRoute(HttpMethod.GET, "/users/:id", ({params}) => {
+  return ok({userId: params.id});
 });
 ```
 
@@ -74,18 +107,34 @@ export const GET = defineRouter([
 
 > 🧠 `defineRouter()` supports all HTTP methods — but Astro only executes the method you export (`GET`, `POST`, etc.)
 
-### `RouterBuilder` (Catch-All)
+### `RouterBuilder` (Catch-All & Fluent Builder)
 
-Designed specifically for `ALL`:
+Use `RouterBuilder` when you want to build routes dynamically, catch all HTTP methods via `ALL`, or organize routes more fluently with helpers.
 
 ```ts
 const builder = new RouterBuilder();
-builder.register([
-  defineRoute(HttpMethod.GET, "/info", () => ok({ app: "astro-routify" }))
-]);
+
+builder
+  .addGet("/ping", () => ok("pong"))
+  .addPost("/submit", async ({request}) => {
+    const body = await request.json();
+    return ok({received: body});
+  });
+
 export const ALL = builder.build();
 ```
 
+You can also group routes:
+
+```ts
+const users = defineGroup("/users")
+  .addGet("/:id", ({params}) => ok({id: params.id}));
+
+builder.addGroup(users);
+```
+
+> 🔁 While `.register()` is still available, it's **deprecated** in favor of `.addGroup()` and `.addRoute()` for better structure and reusability.
+
 ---
 
 ## 🔁 Response Helpers
@@ -93,11 +142,19 @@ export const ALL = builder.build();
 Avoid boilerplate `new Response(JSON.stringify(...))`:
 
 ```ts
-ok(data);                // 200 OK
-created(data);           // 201 Created
-noContent();             // 204
-notFound("Missing");     // 404
-internalError(err);      // 500
+import {fileResponse} from 'astro-routify';
+
+ok(data);                   // 200 OK
+created(data);              // 201 Created
+noContent();                // 204
+notFound("Missing");        // 404
+internalError(err);         // 500
+```
+
+### File downloads
+
+```ts
+fileResponse(content, "application/pdf", "report.pdf"); // sets Content-Type and Content-Disposition
 ```
 
 ---
@@ -107,9 +164,17 @@ internalError(err);      // 500
 Any route param like `:id` is extracted into `ctx.params`:
 
 ```ts
-defineRoute(HttpMethod.GET, "/items/:id", ({ params }) => {
-  return ok({ itemId: params.id });
+const builder = new RouterBuilder();
+
+builder.addGet("/users/:id", ({params}) => ok({userId:  params.id}));
+
+
+//OR
+
+defineRoute(HttpMethod.GET, "/items/:id", ({params}) => {
+    return ok({itemId: params.id});
 });
+
 ```
 
 ---
@@ -121,35 +186,33 @@ defineRoute(HttpMethod.GET, "/items/:id", ({ params }) => {
 ```ts
 // src/pages/api/[...slug].ts
 export const GET = async ({request}) => {
-    const url = new URL(request.url);
-    const path = url.pathname;
-
-    if (path.startsWith('/api/users/')) {
-        // Try to extract ID
-        const id = path.split('/').pop();
-        return new Response(JSON.stringify({id}), {
-            status: 200,
-            headers: {'Content-Type': 'application/json'},
-        });
-    }
-
-    if (path === '/api/users') {
-        return new Response(JSON.stringify([{id: 1}, {id: 2}]), {
-            status: 200,
-            headers: {'Content-Type': 'application/json'},
-        });
-    }
-
-
-    if (path === '/api/ping') {
-        return new Response(JSON.stringify({pong: true}), {
-            status: 200,
-            headers: {'Content-Type': 'application/json'}
-        });
-    }
-
-
-    return new Response('Not Found', {status: 404});
+  const url = new URL(request.url);
+  const path = url.pathname;
+
+  if (path.startsWith('/api/users/')) {
+    // Try to extract ID
+    const id = path.split('/').pop();
+    return new Response(JSON.stringify({id}), {
+      status: 200,
+      headers: {'Content-Type': 'application/json'},
+    });
+  }
+
+  if (path === '/api/users') {
+    return new Response(JSON.stringify([{id: 1}, {id: 2}]), {
+      status: 200,
+      headers: {'Content-Type': 'application/json'},
+    });
+  }
+
+  if (path === '/api/ping') {
+    return new Response(JSON.stringify({pong: true}), {
+      status: 200,
+      headers: {'Content-Type': 'application/json'}
+    });
+  }
+
+  return new Response('Not Found', {status: 404});
 };
 ```
 
@@ -169,11 +232,19 @@ src/
 ### ✅ With `astro-routify`
 
 ```ts
-//src/pages/api/[...slug].ts
+// src/pages/api/[...slug].ts
+
+const builder = new RouterBuilder();
+builder.addGet("/ping", () => ok({pong: true}));
+builder.addGet("/users/:id", ({params}) => ok({userId:  params.id}));
+
+// OR
+
 export const ALL = defineRouter([
-  defineRoute(HttpMethod.GET, "/ping", () => ok({ pong: true })),
-  defineRoute(HttpMethod.GET, "/users/:id", ({ params }) => ok({ id: params.id }))
+  defineRoute(HttpMethod.GET, "/ping", () => ok({pong: true})),
+  defineRoute(HttpMethod.GET, "/users/:id", ({params}) => ok({id: params.id}))
 ]);
+
 ```
 
 ---
@@ -196,11 +267,10 @@ Tests ran on a mid-range development setup:
 - **GPU**: NVIDIA GeForce GTX 1080 (8 GB)
 - **OS**: Windows 10 Pro 64-bit
 - **Node.js**: v20.x
-- **Benchmark Tool**: [Vitest Bench](https://vitest.dev/guide/benchmarks.html)
+- **Benchmark Tool**: [Vitest Bench](https://vitest.dev/guide/features.html#benchmarking)
 
 Results may vary slightly on different hardware.
 
-
 ### 🔬 Realistic route shapes (5000 registered routes):
 
 ```
@@ -225,11 +295,13 @@ Results may vary slightly on different hardware.
 ```
 
 > ⚡ Performance stays consistently fast even with 10k+ routes
+
 ---
 
 ## 🛠 Designed to Scale
 
-While focused on simplicity and speed today, `astro-routify` is designed to evolve — enabling more advanced routing patterns in the future.
+While focused on simplicity and speed today, `astro-routify` is designed to evolve — enabling more advanced routing
+patterns in the future.
 
 ---
 

package/dist/core/RouterBuilder.d.ts

@@ -1,8 +1,119 @@
-import type { Route } from './defineRoute';
+import { type Route } from './defineRoute';
 import { type RouterOptions } from './defineRouter';
+import { RouteGroup } from './defineGroup';
+import { type Handler } from './defineHandler';
+/**
+ * A fluent builder for creating and composing API routes in Astro.
+ *
+ * `RouterBuilder` supports both simple method-based additions (`addGet`, `addPost`, etc.)
+ * and organized groups via `defineGroup()` + `addGroup()` for scalable applications.
+ *
+ * @example Basic usage:
+ * ```ts
+ * const router = new RouterBuilder()
+ *   .addGet('/ping', () => ok('pong'))
+ *   .addPost('/submit', handler);
+ *
+ * export const ALL = router.build();
+ * ```
+ *
+ * @example Using groups:
+ * ```ts
+ * const users = defineGroup('/users')
+ *   .addGet('/:id', userHandler);
+ *
+ * const router = new RouterBuilder({ basePath: '/api' })
+ *   .addGroup(users);
+ *
+ * export const GET = router.build();
+ * ```
+ */
 export declare class RouterBuilder {
-    private routes;
+    private _options;
+    private _routes;
+    private static _registerWarned;
+    constructor(options?: RouterOptions);
+    /**
+     * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
+     *
+     * Registers a single route manually.
+     *
+     * This method is deprecated in favor of a more scalable and organized approach using
+     * `defineGroup()` + `addGroup()` or `addRoute()` for ad-hoc additions.
+     *
+     * @param route A single `Route` object to register.
+     */
     register(route: Route): void;
+    /**
+     * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
+     *
+     * Registers multiple routes at once.
+     *
+     * This method is deprecated and discouraged for larger codebases in favor of group-based composition.
+     *
+     * @param routes An array of `Route` objects to register.
+     */
     register(routes: Route[]): void;
-    build(options?: RouterOptions): import("astro").APIRoute;
+    /**
+     * Adds a single route to the router.
+     *
+     * @param route The route to add.
+     * @returns The current builder instance (for chaining).
+     */
+    addRoute(route: Route): this;
+    /**
+     * Adds a group of pre-defined routes (from `defineGroup()`).
+     *
+     * @param group A `RouteGroup` instance.
+     * @returns The current builder instance (for chaining).
+     */
+    addGroup(group: RouteGroup): this;
+    /**
+     * Adds a GET route.
+     * @param path Route path (e.g., `/items/:id`)
+     * @param handler Request handler function.
+     */
+    addGet(path: string, handler: Handler): this;
+    /**
+     * Adds a POST route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPost(path: string, handler: Handler): this;
+    /**
+     * Adds a PUT route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPut(path: string, handler: Handler): this;
+    /**
+     * Adds a DELETE route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addDelete(path: string, handler: Handler): this;
+    /**
+     * Adds a PATCH route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPatch(path: string, handler: Handler): this;
+    /**
+     * Internal helper to add a route with any HTTP method.
+     *
+     * @param method The HTTP method.
+     * @param subPath Path segment (can be relative or absolute).
+     * @param handler Request handler.
+     * @returns The current builder instance (for chaining).
+     */
+    private add;
+    /**
+     * Finalizes the router and returns an Astro-compatible route handler.
+     *
+     * This function should be used to export a method like `GET`, `POST`, or `ALL`
+     * inside Astro API endpoints.
+     *
+     * @returns A fully resolved Astro route handler.
+     */
+    build(): import("astro").APIRoute;
 }

package/dist/core/RouterBuilder.js

@@ -1,17 +1,144 @@
+import { defineRoute } from './defineRoute';
 import { defineRouter } from './defineRouter';
+import { HttpMethod } from './HttpMethod';
+/**
+ * A fluent builder for creating and composing API routes in Astro.
+ *
+ * `RouterBuilder` supports both simple method-based additions (`addGet`, `addPost`, etc.)
+ * and organized groups via `defineGroup()` + `addGroup()` for scalable applications.
+ *
+ * @example Basic usage:
+ * ```ts
+ * const router = new RouterBuilder()
+ *   .addGet('/ping', () => ok('pong'))
+ *   .addPost('/submit', handler);
+ *
+ * export const ALL = router.build();
+ * ```
+ *
+ * @example Using groups:
+ * ```ts
+ * const users = defineGroup('/users')
+ *   .addGet('/:id', userHandler);
+ *
+ * const router = new RouterBuilder({ basePath: '/api' })
+ *   .addGroup(users);
+ *
+ * export const GET = router.build();
+ * ```
+ */
 export class RouterBuilder {
-    constructor() {
-        this.routes = [];
+    constructor(options) {
+        this._routes = [];
+        this._options = {
+            basePath: 'api',
+            ...options,
+        };
     }
+    /**
+     * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
+     *
+     * Registers one or more routes, supporting both a single `Route` or an array of them.
+     *
+     * Internally used by the two overloads above. Emits a console warning once per runtime.
+     *
+     * @param routeOrRoutes Either a single `Route` or an array of `Route`s.
+     */
     register(routeOrRoutes) {
+        if (!RouterBuilder._registerWarned) {
+            console.warn('[RouterBuilder] register() is deprecated. Use defineGroup() + addGroup() for route grouping and better structure.');
+            RouterBuilder._registerWarned = true;
+        }
         if (Array.isArray(routeOrRoutes)) {
-            this.routes.push(...routeOrRoutes);
+            this._routes.push(...routeOrRoutes);
         }
         else {
-            this.routes.push(routeOrRoutes);
+            this._routes.push(routeOrRoutes);
         }
     }
-    build(options) {
-        return defineRouter(this.routes, options);
+    /**
+     * Adds a single route to the router.
+     *
+     * @param route The route to add.
+     * @returns The current builder instance (for chaining).
+     */
+    addRoute(route) {
+        this._routes.push(route);
+        return this;
+    }
+    /**
+     * Adds a group of pre-defined routes (from `defineGroup()`).
+     *
+     * @param group A `RouteGroup` instance.
+     * @returns The current builder instance (for chaining).
+     */
+    addGroup(group) {
+        this._routes.push(...group.getRoutes());
+        return this;
+    }
+    /**
+     * Adds a GET route.
+     * @param path Route path (e.g., `/items/:id`)
+     * @param handler Request handler function.
+     */
+    addGet(path, handler) {
+        return this.add(HttpMethod.GET, path, handler);
+    }
+    /**
+     * Adds a POST route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPost(path, handler) {
+        return this.add(HttpMethod.POST, path, handler);
+    }
+    /**
+     * Adds a PUT route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPut(path, handler) {
+        return this.add(HttpMethod.PUT, path, handler);
+    }
+    /**
+     * Adds a DELETE route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addDelete(path, handler) {
+        return this.add(HttpMethod.DELETE, path, handler);
+    }
+    /**
+     * Adds a PATCH route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPatch(path, handler) {
+        return this.add(HttpMethod.PATCH, path, handler);
+    }
+    /**
+     * Internal helper to add a route with any HTTP method.
+     *
+     * @param method The HTTP method.
+     * @param subPath Path segment (can be relative or absolute).
+     * @param handler Request handler.
+     * @returns The current builder instance (for chaining).
+     */
+    add(method, subPath, handler) {
+        const normalizedPath = subPath.startsWith('/') ? subPath : `/${subPath}`;
+        this._routes.push(defineRoute(method, normalizedPath, handler));
+        return this;
+    }
+    /**
+     * Finalizes the router and returns an Astro-compatible route handler.
+     *
+     * This function should be used to export a method like `GET`, `POST`, or `ALL`
+     * inside Astro API endpoints.
+     *
+     * @returns A fully resolved Astro route handler.
+     */
+    build() {
+        return defineRouter(this._routes, this._options);
     }
 }
+RouterBuilder._registerWarned = false;

package/dist/core/defineGroup.d.ts

@@ -0,0 +1,87 @@
+import { type Route } from './defineRoute';
+import { Handler } from "./defineHandler";
+/**
+ * Represents a group of routes under a shared base path.
+ *
+ * Use this class to organize related endpoints, applying a consistent prefix
+ * and reducing duplication when defining similar routes.
+ *
+ * @example
+ * const users = new RouteGroup('/users')
+ *   .addGet('/:id', handler)
+ *   .addPost('/', createUser);
+ */
+export declare class RouteGroup {
+    private basePath;
+    private routes;
+    /**
+     * Creates a new route group with the specified base path.
+     * Trailing slashes are automatically removed.
+     *
+     * @param basePath - The common prefix for all routes in the group (e.g. "/users")
+     */
+    constructor(basePath: string);
+    /**
+     * Returns the normalized base path used by the group.
+     */
+    getBasePath(): string;
+    /**
+     * Registers a GET route under the group's base path.
+     *
+     * @param path - Path relative to the base path (e.g. "/:id")
+     * @param handler - The handler function for this route
+     */
+    addGet(path: string, handler: Handler): this;
+    /**
+     * Registers a POST route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPost(path: string, handler: Handler): this;
+    /**
+     * Registers a PUT route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPut(path: string, handler: Handler): this;
+    /**
+     * Registers a DELETE route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addDelete(path: string, handler: Handler): this;
+    /**
+     * Registers a PATCH route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPatch(path: string, handler: Handler): this;
+    /**
+     * Internal method to register a route under the group with any HTTP method.
+     *
+     * @param method - HTTP verb
+     * @param subPath - Route path relative to the base
+     * @param handler - The handler function for this route
+     */
+    private add;
+    /**
+     * Returns all the registered routes in the group.
+     */
+    getRoutes(): Route[];
+}
+/**
+ * Helper to define a `RouteGroup` with optional inline configuration.
+ *
+ * @param basePath - The base path prefix for all routes
+ * @param configure - Optional callback to configure the group inline
+ *
+ * @example
+ * const users = defineGroup('/users', (group) => {
+ *   group.addGet('/:id', handler);
+ * });
+ */
+export declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void): RouteGroup;

package/dist/core/defineGroup.js

@@ -0,0 +1,111 @@
+import { HttpMethod } from './HttpMethod';
+import { defineRoute } from './defineRoute';
+/**
+ * Represents a group of routes under a shared base path.
+ *
+ * Use this class to organize related endpoints, applying a consistent prefix
+ * and reducing duplication when defining similar routes.
+ *
+ * @example
+ * const users = new RouteGroup('/users')
+ *   .addGet('/:id', handler)
+ *   .addPost('/', createUser);
+ */
+export class RouteGroup {
+    /**
+     * Creates a new route group with the specified base path.
+     * Trailing slashes are automatically removed.
+     *
+     * @param basePath - The common prefix for all routes in the group (e.g. "/users")
+     */
+    constructor(basePath) {
+        this.routes = [];
+        this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
+    }
+    /**
+     * Returns the normalized base path used by the group.
+     */
+    getBasePath() {
+        return this.basePath;
+    }
+    /**
+     * Registers a GET route under the group's base path.
+     *
+     * @param path - Path relative to the base path (e.g. "/:id")
+     * @param handler - The handler function for this route
+     */
+    addGet(path, handler) {
+        return this.add(HttpMethod.GET, path, handler);
+    }
+    /**
+     * Registers a POST route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPost(path, handler) {
+        return this.add(HttpMethod.POST, path, handler);
+    }
+    /**
+     * Registers a PUT route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPut(path, handler) {
+        return this.add(HttpMethod.PUT, path, handler);
+    }
+    /**
+     * Registers a DELETE route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addDelete(path, handler) {
+        return this.add(HttpMethod.DELETE, path, handler);
+    }
+    /**
+     * Registers a PATCH route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPatch(path, handler) {
+        return this.add(HttpMethod.PATCH, path, handler);
+    }
+    /**
+     * Internal method to register a route under the group with any HTTP method.
+     *
+     * @param method - HTTP verb
+     * @param subPath - Route path relative to the base
+     * @param handler - The handler function for this route
+     */
+    add(method, subPath, handler) {
+        const normalizedPath = subPath.startsWith('/') ? subPath : `/${subPath}`;
+        this.routes.push(defineRoute(method, `${this.basePath}${normalizedPath}`, handler));
+        return this;
+    }
+    /**
+     * Returns all the registered routes in the group.
+     */
+    getRoutes() {
+        return this.routes;
+    }
+}
+/**
+ * Helper to define a `RouteGroup` with optional inline configuration.
+ *
+ * @param basePath - The base path prefix for all routes
+ * @param configure - Optional callback to configure the group inline
+ *
+ * @example
+ * const users = defineGroup('/users', (group) => {
+ *   group.addGet('/:id', handler);
+ * });
+ */
+export function defineGroup(basePath, configure) {
+    const group = new RouteGroup(basePath);
+    if (configure)
+        configure(group);
+    return group;
+}

package/dist/core/defineHandler.d.ts

@@ -2,3 +2,4 @@ import type { APIContext, APIRoute } from 'astro';
 import { type ResultResponse } from './responseHelpers';
 export type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
 export declare function defineHandler(handler: Handler): APIRoute;
+export declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;

package/dist/core/defineHandler.js

@@ -16,6 +16,17 @@ export function defineHandler(handler) {
                 logResponse(result.status, start);
                 return result;
             }
+            // If it's a file response (manual BodyInit with appropriate headers)
+            if (result?.body instanceof Blob ||
+                result?.body instanceof ArrayBuffer ||
+                isReadableStream(result?.body)) {
+                const res = new Response(result.body, {
+                    status: result.status,
+                    headers: result.headers,
+                });
+                logResponse(res.status, start);
+                return res;
+            }
             const finalResponse = toAstroResponse(result);
             logResponse(finalResponse.status, start);
             return finalResponse;
@@ -28,3 +39,8 @@ export function defineHandler(handler) {
         }
     };
 }
+export function isReadableStream(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.getReader === 'function');
+}

package/dist/core/defineRouter.d.ts

@@ -2,6 +2,7 @@ import type { APIRoute } from 'astro';
 import { notFound } from './responseHelpers';
 import type { Route } from './defineRoute';
 export interface RouterOptions {
+    basePath?: string;
     /** Custom 404 handler */
     onNotFound?: () => ReturnType<typeof notFound>;
 }

package/dist/core/defineRouter.js

@@ -7,9 +7,14 @@ export function defineRouter(routes, options = {}) {
     for (const route of routes) {
         trie.insert(route.path, route.method, route.handler);
     }
-    // Wrap every user handler through defineHandler for uniform logging & error handling
     return async (ctx) => {
-        const path = new URL(ctx.request.url).pathname.replace(/^\/api/, '');
+        const pathname = new URL(ctx.request.url).pathname;
+        let basePath = options.basePath ?? '/api';
+        if (!basePath.startsWith('/')) {
+            basePath = '/' + basePath;
+        }
+        const basePathRegex = new RegExp(`^${basePath}`);
+        const path = pathname.replace(basePathRegex, '');
         const method = normalizeMethod(ctx.request.method);
         const { handler, allowed, params } = trie.find(path, method);
         if (!handler) {

package/dist/core/responseHelpers.d.ts

@@ -1,4 +1,4 @@
-import { HeadersInit } from "undici";
+import { BodyInit, HeadersInit } from "undici";
 export interface ResultResponse<T = unknown> {
     body?: T;
     status: number;
@@ -14,4 +14,5 @@ export declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) =>
 export declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
 export declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
 export declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResponse<string>;
+export declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
 export declare function toAstroResponse(result: ResultResponse | undefined): Response;

package/dist/core/responseHelpers.js

@@ -11,6 +11,20 @@ export const forbidden = (body = 'Forbidden', headers) => createResponse(403, bo
 export const notFound = (body = 'Not Found', headers) => createResponse(404, body, headers);
 export const methodNotAllowed = (body = 'Method Not Allowed', headers) => createResponse(405, body, headers);
 export const internalError = (err, headers) => createResponse(500, err instanceof Error ? err.message : String(err), headers);
+export const fileResponse = (content, contentType, fileName, headers) => {
+    const disposition = fileName
+        ? { 'Content-Disposition': `attachment; filename="${fileName}"` }
+        : {};
+    return {
+        status: 200,
+        body: content,
+        headers: {
+            'Content-Type': contentType,
+            ...disposition,
+            ...headers,
+        },
+    };
+};
 export function toAstroResponse(result) {
     if (!result)
         return new Response(null, { status: 204 });

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as astro from 'astro';
 import { APIContext, APIRoute } from 'astro';
-import { HeadersInit } from 'undici';
+import { HeadersInit, BodyInit } from 'undici';
 
 declare enum HttpMethod {
     GET = "GET",
@@ -31,10 +31,12 @@ declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) => Result
 declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
 declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
 declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResponse<string>;
+declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
 declare function toAstroResponse(result: ResultResponse | undefined): Response;
 
 type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
 declare function defineHandler(handler: Handler): APIRoute;
+declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
 
 interface Route {
     method: HttpMethod;
@@ -45,11 +47,98 @@ declare function defineRoute(route: Route): Route;
 declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;
 
 interface RouterOptions {
+    basePath?: string;
     /** Custom 404 handler */
     onNotFound?: () => ReturnType<typeof notFound>;
 }
 declare function defineRouter(routes: Route[], options?: RouterOptions): APIRoute;
 
+/**
+ * Represents a group of routes under a shared base path.
+ *
+ * Use this class to organize related endpoints, applying a consistent prefix
+ * and reducing duplication when defining similar routes.
+ *
+ * @example
+ * const users = new RouteGroup('/users')
+ *   .addGet('/:id', handler)
+ *   .addPost('/', createUser);
+ */
+declare class RouteGroup {
+    private basePath;
+    private routes;
+    /**
+     * Creates a new route group with the specified base path.
+     * Trailing slashes are automatically removed.
+     *
+     * @param basePath - The common prefix for all routes in the group (e.g. "/users")
+     */
+    constructor(basePath: string);
+    /**
+     * Returns the normalized base path used by the group.
+     */
+    getBasePath(): string;
+    /**
+     * Registers a GET route under the group's base path.
+     *
+     * @param path - Path relative to the base path (e.g. "/:id")
+     * @param handler - The handler function for this route
+     */
+    addGet(path: string, handler: Handler): this;
+    /**
+     * Registers a POST route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPost(path: string, handler: Handler): this;
+    /**
+     * Registers a PUT route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPut(path: string, handler: Handler): this;
+    /**
+     * Registers a DELETE route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addDelete(path: string, handler: Handler): this;
+    /**
+     * Registers a PATCH route under the group's base path.
+     *
+     * @param path - Path relative to the base path
+     * @param handler - The handler function for this route
+     */
+    addPatch(path: string, handler: Handler): this;
+    /**
+     * Internal method to register a route under the group with any HTTP method.
+     *
+     * @param method - HTTP verb
+     * @param subPath - Route path relative to the base
+     * @param handler - The handler function for this route
+     */
+    private add;
+    /**
+     * Returns all the registered routes in the group.
+     */
+    getRoutes(): Route[];
+}
+/**
+ * Helper to define a `RouteGroup` with optional inline configuration.
+ *
+ * @param basePath - The base path prefix for all routes
+ * @param configure - Optional callback to configure the group inline
+ *
+ * @example
+ * const users = defineGroup('/users', (group) => {
+ *   group.addGet('/:id', handler);
+ * });
+ */
+declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void): RouteGroup;
+
 interface RouteMatch {
     handler: Handler | null;
     allowed?: HttpMethod[];
@@ -62,12 +151,121 @@ declare class RouteTrie {
     private segmentize;
 }
 
+/**
+ * A fluent builder for creating and composing API routes in Astro.
+ *
+ * `RouterBuilder` supports both simple method-based additions (`addGet`, `addPost`, etc.)
+ * and organized groups via `defineGroup()` + `addGroup()` for scalable applications.
+ *
+ * @example Basic usage:
+ * ```ts
+ * const router = new RouterBuilder()
+ *   .addGet('/ping', () => ok('pong'))
+ *   .addPost('/submit', handler);
+ *
+ * export const ALL = router.build();
+ * ```
+ *
+ * @example Using groups:
+ * ```ts
+ * const users = defineGroup('/users')
+ *   .addGet('/:id', userHandler);
+ *
+ * const router = new RouterBuilder({ basePath: '/api' })
+ *   .addGroup(users);
+ *
+ * export const GET = router.build();
+ * ```
+ */
 declare class RouterBuilder {
-    private routes;
+    private _options;
+    private _routes;
+    private static _registerWarned;
+    constructor(options?: RouterOptions);
+    /**
+     * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
+     *
+     * Registers a single route manually.
+     *
+     * This method is deprecated in favor of a more scalable and organized approach using
+     * `defineGroup()` + `addGroup()` or `addRoute()` for ad-hoc additions.
+     *
+     * @param route A single `Route` object to register.
+     */
     register(route: Route): void;
+    /**
+     * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
+     *
+     * Registers multiple routes at once.
+     *
+     * This method is deprecated and discouraged for larger codebases in favor of group-based composition.
+     *
+     * @param routes An array of `Route` objects to register.
+     */
     register(routes: Route[]): void;
-    build(options?: RouterOptions): astro.APIRoute;
+    /**
+     * Adds a single route to the router.
+     *
+     * @param route The route to add.
+     * @returns The current builder instance (for chaining).
+     */
+    addRoute(route: Route): this;
+    /**
+     * Adds a group of pre-defined routes (from `defineGroup()`).
+     *
+     * @param group A `RouteGroup` instance.
+     * @returns The current builder instance (for chaining).
+     */
+    addGroup(group: RouteGroup): this;
+    /**
+     * Adds a GET route.
+     * @param path Route path (e.g., `/items/:id`)
+     * @param handler Request handler function.
+     */
+    addGet(path: string, handler: Handler): this;
+    /**
+     * Adds a POST route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPost(path: string, handler: Handler): this;
+    /**
+     * Adds a PUT route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPut(path: string, handler: Handler): this;
+    /**
+     * Adds a DELETE route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addDelete(path: string, handler: Handler): this;
+    /**
+     * Adds a PATCH route.
+     * @param path Route path.
+     * @param handler Request handler function.
+     */
+    addPatch(path: string, handler: Handler): this;
+    /**
+     * Internal helper to add a route with any HTTP method.
+     *
+     * @param method The HTTP method.
+     * @param subPath Path segment (can be relative or absolute).
+     * @param handler Request handler.
+     * @returns The current builder instance (for chaining).
+     */
+    private add;
+    /**
+     * Finalizes the router and returns an Astro-compatible route handler.
+     *
+     * This function should be used to export a method like `GET`, `POST`, or `ALL`
+     * inside Astro API endpoints.
+     *
+     * @returns A fully resolved Astro route handler.
+     */
+    build(): astro.APIRoute;
 }
 
-export { ALLOWED_HTTP_METHODS, HttpMethod, RouteTrie, RouterBuilder, badRequest, created, defineHandler, defineRoute, defineRouter, forbidden, internalError, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, toAstroResponse, unauthorized };
+export { ALLOWED_HTTP_METHODS, HttpMethod, RouteGroup, RouteTrie, RouterBuilder, badRequest, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, internalError, isReadableStream, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, toAstroResponse, unauthorized };
 export type { Handler, ResultResponse, Route, RouterOptions };

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './core/defineRoute';
 export * from './core/defineRouter';
 export * from './core/defineHandler';
+export * from './core/defineGroup';
 export * from './core/RouteTrie';
 export * from './core/HttpMethod';
 export * from './core/responseHelpers';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-routify",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A high-performance API router for Astro using a Trie-based matcher.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,10 +31,10 @@
   },
   "devDependencies": {
     "rimraf": "^6.0.1",
-    "rollup": "^4.45.0",
+    "rollup": "^4.46.2",
     "rollup-plugin-dts": "^6.2.1",
     "typescript": "^5.3.3",
-    "undici": "^7.11.0",
+    "undici": "^7.13.0",
     "vitest": "^3.2.4"
   },
   "engines": {