astro-routify 1.0.0 → 1.2.0

package/README.md

@@ -3,50 +3,89 @@
 **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 }) => {
-    const body = await request.json();
-    return ok({ received: body });
-  })
-]);
+
+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`)
 - ✅ Built-in response helpers (`ok`, `created`, etc.)
 - ✅ Trie-based matcher for fast route lookup
 - ✅ Fully typed — no magic strings
+- 🔁 **Streaming support**
+    - `stream()` — raw streaming with backpressure support (e.g. SSE, logs, custom protocols)
+    - `streamJsonND()` — newline-delimited JSON streaming (NDJSON)
+    - `streamJsonArray()` — server-side streamed JSON arrays
+
+> 🔄 See [CHANGELOG.md](./CHANGELOG.md) for recent updates and improvements.
 
 ---
 
@@ -57,8 +96,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});
 });
 ```
 
@@ -68,24 +107,42 @@ Group multiple routes under one HTTP method handler:
 
 ```ts
 export const GET = defineRouter([
-  defineRoute(HttpMethod.GET, "/health", () => ok("ok"))
+    defineRoute(HttpMethod.GET, "/health", () => ok("ok"))
 ]);
 ```
 
 > 🧠 `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 +150,63 @@ 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
+```
+
+### 🔄 Streaming responses
+
+#### Raw stream (e.g., Server-Sent Events)
+
+```ts
+stream('/clock', async ({response}) => {
+    const timer = setInterval(() => {
+        response.write(`data: ${new Date().toISOString()}\n\n`);
+    }, 1000);
+
+    setTimeout(() => {
+        clearInterval(timer);
+        response.close();
+    }, 5000);
+});
+
+```
+
+#### JSON NDStream (newline-delimited)
+
+```ts
+
+streamJsonND('/updates', async ({response}) => {
+    response.send({step: 1});
+    await delay(500);
+    response.send({step: 2});
+    response.close();
+});
+
+```
+
+#### JSON Array stream
+
+```ts
+
+streamJsonArray('/items', async ({response}) => {
+    for (let i = 0; i < 3; i++) {
+        response.send({id: i});
+    }
+    response.close();
+});
+
 ```
 
 ---
@@ -107,9 +216,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});
 });
+
 ```
 
 ---
@@ -140,7 +257,6 @@ export const GET = async ({request}) => {
         });
     }
 
-
     if (path === '/api/ping') {
         return new Response(JSON.stringify({pong: true}), {
             status: 200,
@@ -148,7 +264,6 @@ export const GET = async ({request}) => {
         });
     }
 
-
     return new Response('Not Found', {status: 404});
 };
 ```
@@ -169,11 +284,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 +319,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 +347,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;