astro-routify 1.1.0 → 1.2.0

package/README.md

@@ -21,50 +21,52 @@ npm install astro-routify
 ```ts
 // src/pages/api/index.ts
 import {
-  defineRoute,
-  defineRouter,
-  defineGroup,
-  HttpMethod,
-  ok,
+    defineRoute,
+    defineRouter,
+    defineGroup,
+    HttpMethod,
+    ok,
 } from 'astro-routify';
 
 const userGroup = defineGroup('/users', (group) => {
-  group.addGet('/:id', ({ params }) => ok({ id: params.id }));
+    group.addGet('/:id', ({params}) => ok({id: params.id}));
 });
 
 export const GET = defineRouter([
-  defineRoute(HttpMethod.GET, '/ping', () => ok('pong')),
-  ...userGroup.getRoutes(),
+    defineRoute(HttpMethod.GET, '/ping', () => ok('pong')),
+    ...userGroup.getRoutes(),
 ]);
 ```
 
 Or to handle everything in a single place:
 
 ```ts
-import { RouterBuilder, ok } from 'astro-routify';
+import {RouterBuilder, ok} from 'astro-routify';
 
 const builder = new RouterBuilder();
 
 builder
-  .addGet('/ping', () => ok('pong'))
-  .addPost('/submit', async ({ request }) => {
-    const body = await request.json();
-    return ok({ received: body });
-  });
+    .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.
+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.
+This setup demonstrates how to route requests dynamically using astro-routify, while still leveraging Astro's native
+endpoint system.
 
 ---
 
@@ -78,6 +80,10 @@ This setup demonstrates how to route requests dynamically using astro-routify, w
 - ✅ 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.
 
@@ -91,7 +97,7 @@ Declare a single route:
 
 ```ts
 defineRoute(HttpMethod.GET, "/users/:id", ({params}) => {
-  return ok({userId: params.id});
+    return ok({userId: params.id});
 });
 ```
 
@@ -101,7 +107,7 @@ 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"))
 ]);
 ```
 
@@ -109,17 +115,18 @@ export const GET = defineRouter([
 
 ### `RouterBuilder` (Catch-All & Fluent Builder)
 
-Use `RouterBuilder` when you want to build routes dynamically, catch all HTTP methods via `ALL`, or organize routes more fluently with helpers.
+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
-  .addGet("/ping", () => ok("pong"))
-  .addPost("/submit", async ({request}) => {
-    const body = await request.json();
-    return ok({received: body});
-  });
+    .addGet("/ping", () => ok("pong"))
+    .addPost("/submit", async ({request}) => {
+        const body = await request.json();
+        return ok({received: body});
+    });
 
 export const ALL = builder.build();
 ```
@@ -128,12 +135,13 @@ You can also group routes:
 
 ```ts
 const users = defineGroup("/users")
-  .addGet("/:id", ({params}) => ok({id: params.id}));
+    .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.
+> 🔁 While `.register()` is still available, it's **deprecated** in favor of `.addGroup()` and `.addRoute()` for better
+> structure and reusability.
 
 ---
 
@@ -151,12 +159,56 @@ notFound("Missing");        // 404
 internalError(err);         // 500
 ```
 
-### File downloads
+### 📄 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();
+});
+
+```
+
 ---
 
 ## 🔍 Param Matching
@@ -166,7 +218,7 @@ Any route param like `:id` is extracted into `ctx.params`:
 ```ts
 const builder = new RouterBuilder();
 
-builder.addGet("/users/:id", ({params}) => ok({userId:  params.id}));
+builder.addGet("/users/:id", ({params}) => ok({userId: params.id}));
 
 
 //OR
@@ -186,33 +238,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});
 };
 ```
 
@@ -236,13 +288,13 @@ src/
 
 const builder = new RouterBuilder();
 builder.addGet("/ping", () => ok({pong: true}));
-builder.addGet("/users/:id", ({params}) => ok({userId:  params.id}));
+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}))
 ]);
 
 ```

package/dist/core/defineHandler.d.ts

@@ -1,5 +1,27 @@
 import type { APIContext, APIRoute } from 'astro';
 import { type ResultResponse } from './responseHelpers';
+/**
+ * A flexible route handler that can return:
+ * - a native `Response` object,
+ * - a structured `ResultResponse` object,
+ * - or a file stream (Blob, ArrayBuffer, or ReadableStream).
+ */
 export type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+/**
+ * Wraps a `Handler` function into an `APIRoute` that:
+ * - logs requests and responses,
+ * - supports all valid `ResultResponse` return formats,
+ * - auto-converts structured responses into Astro `Response`s,
+ * - handles errors with standardized 500 output.
+ *
+ * @param handler - A handler function returning a `Response` or `ResultResponse`
+ * @returns An Astro-compatible `APIRoute` function
+ */
 export declare function defineHandler(handler: Handler): APIRoute;
+/**
+ * Type guard to detect ReadableStreams, used for streamed/binary responses.
+ *
+ * @param value - Any value to test
+ * @returns True if it looks like a ReadableStream
+ */
 export declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;

package/dist/core/defineHandler.js

@@ -1,22 +1,39 @@
 import { internalError, toAstroResponse } from './responseHelpers';
+/**
+ * Logs the incoming request method and path to the console.
+ */
 function logRequest(ctx) {
     const { method, url } = ctx.request;
     console.info(`[astro-routify] → ${method} ${new URL(url).pathname}`);
 }
+/**
+ * Logs the response status and time taken.
+ */
 function logResponse(status, start) {
     console.info(`[astro-routify] ← responded ${status} in ${Math.round(performance.now() - start)}ms`);
 }
+/**
+ * Wraps a `Handler` function into an `APIRoute` that:
+ * - logs requests and responses,
+ * - supports all valid `ResultResponse` return formats,
+ * - auto-converts structured responses into Astro `Response`s,
+ * - handles errors with standardized 500 output.
+ *
+ * @param handler - A handler function returning a `Response` or `ResultResponse`
+ * @returns An Astro-compatible `APIRoute` function
+ */
 export function defineHandler(handler) {
     return async (ctx) => {
         const start = performance.now();
         try {
             logRequest(ctx);
             const result = await handler(ctx);
+            // Native Response shortcut
             if (result instanceof Response) {
                 logResponse(result.status, start);
                 return result;
             }
-            // If it's a file response (manual BodyInit with appropriate headers)
+            // Direct binary or stream body (file download, etc.)
             if (result?.body instanceof Blob ||
                 result?.body instanceof ArrayBuffer ||
                 isReadableStream(result?.body)) {
@@ -27,6 +44,7 @@ export function defineHandler(handler) {
                 logResponse(res.status, start);
                 return res;
             }
+            // Structured ResultResponse → native Astro Response
             const finalResponse = toAstroResponse(result);
             logResponse(finalResponse.status, start);
             return finalResponse;
@@ -39,6 +57,12 @@ export function defineHandler(handler) {
         }
     };
 }
+/**
+ * Type guard to detect ReadableStreams, used for streamed/binary responses.
+ *
+ * @param value - Any value to test
+ * @returns True if it looks like a ReadableStream
+ */
 export function isReadableStream(value) {
     return (typeof value === 'object' &&
         value !== null &&

package/dist/core/defineRoute.d.ts

@@ -1,9 +1,41 @@
 import { HttpMethod } from './HttpMethod';
 import type { Handler } from './defineHandler';
+/**
+ * Represents a single route definition.
+ */
 export interface Route {
+    /**
+     * HTTP method to match (GET, POST, PUT, etc.).
+     */
     method: HttpMethod;
+    /**
+     * Path pattern, starting with `/`, supporting static or param segments (e.g., `/users/:id`).
+     */
     path: string;
+    /**
+     * The function that handles the request when matched.
+     */
     handler: Handler;
 }
+/**
+ * Defines a route using a `Route` object.
+ *
+ * @example
+ * defineRoute({ method: 'GET', path: '/users', handler });
+ *
+ * @param route - A fully constructed route object
+ * @returns The validated Route object
+ */
 export declare function defineRoute(route: Route): Route;
+/**
+ * Defines a route by specifying its method, path, and handler explicitly.
+ *
+ * @example
+ * defineRoute('POST', '/login', handler);
+ *
+ * @param method - HTTP method to match
+ * @param path - Route path (must start with `/`)
+ * @param handler - Function to handle the matched request
+ * @returns The validated Route object
+ */
 export declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;

package/dist/core/defineRoute.js

@@ -1,13 +1,26 @@
 import { ALLOWED_HTTP_METHODS } from './HttpMethod';
+/**
+ * Internal route definition logic that supports both overloads.
+ */
 export function defineRoute(methodOrRoute, maybePath, maybeHandler) {
     if (typeof methodOrRoute === 'object') {
         validateRoute(methodOrRoute);
         return methodOrRoute;
     }
-    const route = { method: methodOrRoute, path: maybePath, handler: maybeHandler };
+    const route = {
+        method: methodOrRoute,
+        path: maybePath,
+        handler: maybeHandler,
+    };
     validateRoute(route);
     return route;
 }
+/**
+ * Ensures the route is properly formed and uses a valid method + path format.
+ *
+ * @param route - Route to validate
+ * @throws If method is unsupported or path doesn't start with `/`
+ */
 function validateRoute({ method, path }) {
     if (!path.startsWith('/')) {
         throw new Error(`Route path must start with '/': ${path}`);

package/dist/core/defineRouter.d.ts

@@ -1,9 +1,40 @@
 import type { APIRoute } from 'astro';
 import { notFound } from './responseHelpers';
 import type { Route } from './defineRoute';
+/**
+ * Optional configuration for the router instance.
+ */
 export interface RouterOptions {
+    /**
+     * A base path to strip from the incoming request path (default: `/api`).
+     * Only routes beneath this prefix will be matched.
+     */
     basePath?: string;
-    /** Custom 404 handler */
+    /**
+     * Custom handler to return when no route is matched (404).
+     */
     onNotFound?: () => ReturnType<typeof notFound>;
 }
+/**
+ * Defines a router that dynamically matches registered routes based on method and path.
+ *
+ * This allows building a clean, centralized API routing system with features like:
+ * - Trie-based fast route lookup
+ * - Per-method matching with 405 fallback
+ * - Parameter extraction (e.g. `/users/:id`)
+ * - Customizable basePath and 404 behavior
+ *
+ * @example
+ * defineRouter([
+ *   defineRoute('GET', '/users', handler),
+ *   defineRoute('POST', '/login', loginHandler),
+ * ], {
+ *   basePath: '/api',
+ *   onNotFound: () => notFound('No such route')
+ * });
+ *
+ * @param routes - An array of route definitions (see `defineRoute`)
+ * @param options - Optional router config (basePath, custom 404)
+ * @returns An Astro-compatible APIRoute handler
+ */
 export declare function defineRouter(routes: Route[], options?: RouterOptions): APIRoute;

package/dist/core/defineRouter.js

@@ -2,6 +2,28 @@ import { defineHandler } from './defineHandler';
 import { methodNotAllowed, notFound, toAstroResponse } from './responseHelpers';
 import { RouteTrie } from './RouteTrie';
 import { normalizeMethod } from './HttpMethod';
+/**
+ * Defines a router that dynamically matches registered routes based on method and path.
+ *
+ * This allows building a clean, centralized API routing system with features like:
+ * - Trie-based fast route lookup
+ * - Per-method matching with 405 fallback
+ * - Parameter extraction (e.g. `/users/:id`)
+ * - Customizable basePath and 404 behavior
+ *
+ * @example
+ * defineRouter([
+ *   defineRoute('GET', '/users', handler),
+ *   defineRoute('POST', '/login', loginHandler),
+ * ], {
+ *   basePath: '/api',
+ *   onNotFound: () => notFound('No such route')
+ * });
+ *
+ * @param routes - An array of route definitions (see `defineRoute`)
+ * @param options - Optional router config (basePath, custom 404)
+ * @returns An Astro-compatible APIRoute handler
+ */
 export function defineRouter(routes, options = {}) {
     const trie = new RouteTrie();
     for (const route of routes) {
@@ -18,15 +40,17 @@ export function defineRouter(routes, options = {}) {
         const method = normalizeMethod(ctx.request.method);
         const { handler, allowed, params } = trie.find(path, method);
         if (!handler) {
-            // No handler for this method – but maybe other methods exist → 405
+            // Method exists but not allowed for this route
             if (allowed && allowed.length) {
                 return toAstroResponse(methodNotAllowed('Method Not Allowed', {
                     Allow: allowed.join(', '),
                 }));
             }
+            // No route matched at all → 404
             const notFoundHandler = options.onNotFound ? options.onNotFound() : notFound('Not Found');
             return toAstroResponse(notFoundHandler);
         }
+        // Match found → delegate to handler
         return defineHandler(handler)({ ...ctx, params: { ...ctx.params, ...params } });
     };
 }

package/dist/core/internal/createJsonStreamRoute.d.ts

@@ -0,0 +1,64 @@
+import type { APIContext } from 'astro';
+import { HttpMethod } from '../HttpMethod';
+import { type Route } from '../defineRoute';
+type JsonValue = any;
+/**
+ * A writer interface for streaming JSON data to the response body.
+ * Supports both NDJSON and array formats.
+ */
+export interface JsonStreamWriter {
+    /**
+     * Send a JSON-serializable value to the response stream.
+     * - In `ndjson` mode: appends a newline after each object.
+     * - In `array` mode: adds commas and wraps with brackets.
+     * @param value - Any serializable object or array item
+     */
+    send: (value: JsonValue) => void;
+    /**
+     * Write raw text or bytes to the stream.
+     * Used for low-level control if needed.
+     */
+    write: (chunk: string | Uint8Array) => void;
+    /**
+     * Close the stream. In `array` mode, it writes the closing `]`.
+     */
+    close: () => void;
+    /**
+     * Override response headers dynamically before the response is sent.
+     * Only safe before the first write.
+     * @param key - Header name
+     * @param value - Header value
+     */
+    setHeader: (key: string, value: string) => void;
+}
+/**
+ * Internal configuration options for `createJsonStreamRoute`.
+ */
+interface JsonStreamOptions {
+    /**
+     * Streaming mode: 'ndjson' or 'array'.
+     */
+    mode: 'ndjson' | 'array';
+    /**
+     * HTTP method to define (e.g. GET, POST).
+     */
+    method: HttpMethod;
+}
+/**
+ * Creates a streaming JSON route that supports both NDJSON and JSON array formats.
+ *
+ * - Sets appropriate `Content-Type` headers
+ * - Supports cancellation via `AbortSignal`
+ * - Provides a `response` object with `send`, `close`, `write`, `setHeader` methods
+ *
+ * Use this function inside `streamJsonND()` or `streamJsonArray()` to avoid duplication.
+ *
+ * @param path - The route path (e.g. `/logs`)
+ * @param handler - A function that receives Astro `ctx` and a `JsonStreamWriter`
+ * @param options - Streaming options (`mode`, `method`)
+ * @returns A streaming-compatible Route
+ */
+export declare function createJsonStreamRoute(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options: JsonStreamOptions): Route;
+export {};