astro-routify 1.0.0 → 1.2.0

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",
@@ -16,40 +16,275 @@ declare const ALLOWED_HTTP_METHODS: Set<string>;
  */
 declare function normalizeMethod(method: string): HttpMethod;
 
+/**
+ * A standardized shape for internal route result objects.
+ * These are later converted into native `Response` instances.
+ */
 interface ResultResponse<T = unknown> {
+    /**
+     * Optional body content (can be a string, object, or binary).
+     */
     body?: T;
+    /**
+     * HTTP status code (e.g. 200, 404, 500).
+     */
     status: number;
+    /**
+     * Optional response headers.
+     */
     headers?: HeadersInit;
 }
+/**
+ * 200 OK
+ */
 declare const ok: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 201 Created
+ */
 declare const created: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 204 No Content
+ */
 declare const noContent: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 304 Not Modified
+ */
 declare const notModified: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 400 Bad Request
+ */
 declare const badRequest: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 401 Unauthorized
+ */
 declare const unauthorized: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 403 Forbidden
+ */
 declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 404 Not Found
+ */
 declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 405 Method Not Allowed
+ */
 declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 500 Internal Server Error
+ */
 declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResponse<string>;
+/**
+ * Sends a binary or stream-based file response with optional content-disposition.
+ *
+ * @param content - The file data (Blob, ArrayBuffer, or stream)
+ * @param contentType - MIME type of the file
+ * @param fileName - Optional download filename
+ * @param headers - Optional extra headers
+ * @returns A ResultResponse for download-ready content
+ */
+declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
+/**
+ * Converts an internal `ResultResponse` into a native `Response` object
+ * for use inside Astro API routes.
+ *
+ * Automatically applies `Content-Type: application/json` for object bodies.
+ *
+ * @param result - A ResultResponse returned from route handler
+ * @returns A native Response
+ */
 declare function toAstroResponse(result: ResultResponse | undefined): Response;
 
+/**
+ * A flexible route handler that can return:
+ * - a native `Response` object,
+ * - a structured `ResultResponse` object,
+ * - or a file stream (Blob, ArrayBuffer, or ReadableStream).
+ */
 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
+ */
 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
+ */
+declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
 
+/**
+ * Represents a single route definition.
+ */
 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
+ */
 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
+ */
 declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;
 
+/**
+ * Optional configuration for the router instance.
+ */
 interface RouterOptions {
-    /** Custom 404 handler */
+    /**
+     * A base path to strip from the incoming request path (default: `/api`).
+     * Only routes beneath this prefix will be matched.
+     */
+    basePath?: string;
+    /**
+     * 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
+ */
 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 +297,283 @@ 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;
+}
+
+/**
+ * A writer for streaming raw data to the response body.
+ *
+ * This is used inside the `stream()` route handler to emit bytes
+ * or strings directly to the client with backpressure awareness.
+ */
+interface StreamWriter {
+    /**
+     * Write a string or Uint8Array chunk to the response stream.
+     * @param chunk - Text or byte chunk to emit
+     */
+    write: (chunk: string | Uint8Array) => void;
+    /**
+     * Close the stream and signal end-of-response to the client.
+     */
+    close: () => void;
+    /**
+     * Dynamically change the Content-Type header.
+     * Should be called before the first `write()` to take effect.
+     * @param type - MIME type (e.g., `text/html`, `application/json`)
+     */
+    setContentType: (type: string) => void;
+}
+/**
+ * Configuration options for the `stream()` route helper.
+ */
+interface StreamOptions {
+    /**
+     * HTTP method (defaults to GET).
+     */
+    method?: HttpMethod;
+    /**
+     * Content-Type header (defaults to `text/event-stream`).
+     */
+    contentType?: string;
+    /**
+     * Additional custom headers.
+     */
+    headers?: HeadersInit;
+    /**
+     * Enable SSE keep-alive headers (defaults to true for SSE).
+     */
+    keepAlive?: boolean;
+}
+/**
+ * Defines a generic streaming route that can write raw chunks of data
+ * to the response in real time using a `ReadableStream`.
+ *
+ * Suitable for Server-Sent Events (SSE), long-polling, streamed HTML,
+ * logs, LLM output, or NDJSON responses.
+ *
+ * @example
+ * stream('/clock', async ({ response }) => {
+ *   const timer = setInterval(() => {
+ *     response.write(`data: ${new Date().toISOString()}\n\n`);
+ *   }, 1000);
+ *
+ *   setTimeout(() => {
+ *     clearInterval(timer);
+ *     response.close();
+ *   }, 5000);
+ * });
+ *
+ * @param path - The route path (e.g. `/clock`)
+ * @param handler - Handler that receives the API context and response writer
+ * @param options - Optional stream configuration
+ * @returns A Route object ready to be used in `defineRouter()`
+ */
+declare function stream(path: string, handler: (ctx: APIContext & {
+    response: StreamWriter;
+}) => void | Promise<void>, options?: StreamOptions): Route;
+
+type JsonValue = any;
+/**
+ * A writer interface for streaming JSON data to the response body.
+ * Supports both NDJSON and array formats.
+ */
+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;
 }
 
-export { ALLOWED_HTTP_METHODS, HttpMethod, RouteTrie, RouterBuilder, badRequest, created, defineHandler, defineRoute, defineRouter, forbidden, internalError, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, toAstroResponse, unauthorized };
-export type { Handler, ResultResponse, Route, RouterOptions };
+/**
+ * Defines a JSON streaming route using NDJSON (Newline Delimited JSON) format.
+ *
+ * This helper streams individual JSON objects separated by newlines (`\n`)
+ * instead of a single JSON array. It sets the `Content-Type` to
+ * `application/x-ndjson` and disables buffering to allow low-latency
+ * delivery of each item.
+ *
+ * Ideal for real-time updates, event logs, progressive loading, or
+ * integrations with LLMs or dashboards where each object can be processed
+ * as soon as it's received.
+ *
+ * @example
+ * streamJsonND('/events', async ({ response }) => {
+ *   response.send({ type: 'start' });
+ *   await delay(100);
+ *   response.send({ type: 'progress', percent: 25 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/events`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+declare function streamJsonND(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;
+
+/**
+ * Defines a JSON streaming route that emits a valid JSON array.
+ *
+ * This helper returns a valid `application/json` response containing
+ * a streamable array of JSON values. Useful for large data exports
+ * or APIs where the full array can be streamed as it's generated.
+ *
+ * Unlike `streamJsonND()`, this wraps all values in `[` and `]`
+ * and separates them with commas.
+ *
+ * @example
+ * streamJsonArray('/users', async ({ response }) => {
+ *   response.send({ id: 1 });
+ *   response.send({ id: 2 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/users`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+declare function streamJsonArray(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;
+
+export { ALLOWED_HTTP_METHODS, HttpMethod, RouteGroup, RouteTrie, RouterBuilder, badRequest, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, internalError, isReadableStream, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, stream, streamJsonArray, streamJsonND, toAstroResponse, unauthorized };
+export type { Handler, JsonStreamWriter, ResultResponse, Route, RouterOptions, StreamOptions, StreamWriter };

package/dist/index.js

@@ -1,7 +1,11 @@
 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';
 export * from './core/RouterBuilder';
+export * from './core/stream';
+export * from './core/streamJsonND';
+export * from './core/streamJsonArray';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-routify",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A high-performance API router for Astro using a Trie-based matcher.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,13 +16,19 @@
   ],
   "keywords": [
     "astro",
-    "router",
+    "astrojs",
     "api-router",
-    "typescript",
+    "router",
     "routing",
-    "astrojs",
+    "typescript",
     "esm",
-    "trie"
+    "trie",
+    "streaming",
+    "sse",
+    "ndjson",
+    "json-stream",
+    "response-helpers",
+    "astro-api"
   ],
   "author": "Alex Mora",
   "license": "MIT",
@@ -31,10 +37,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": {