astro-routify 1.0.0 → 1.2.0

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

@@ -1,4 +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,21 +1,50 @@
 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;
             }
+            // Direct binary or stream body (file download, etc.)
+            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;
+            }
+            // Structured ResultResponse → native Astro Response
             const finalResponse = toAstroResponse(result);
             logResponse(finalResponse.status, start);
             return finalResponse;
@@ -28,3 +57,14 @@ 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 &&
+        typeof value.getReader === 'function');
+}

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,8 +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 {
-    /** 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
+ */
 export declare function defineRouter(routes: Route[], options?: RouterOptions): APIRoute;

package/dist/core/defineRouter.js

@@ -2,26 +2,55 @@ 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) {
         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) {
-            // 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 {};

package/dist/core/internal/createJsonStreamRoute.js

@@ -0,0 +1,92 @@
+import { defineRoute } from '../defineRoute';
+/**
+ * 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 function createJsonStreamRoute(path, handler, options) {
+    const isNDJSON = options.mode === 'ndjson';
+    return defineRoute(options.method, path, async (ctx) => {
+        const encoder = new TextEncoder();
+        let controllerRef = null;
+        let closed = false;
+        let first = true;
+        const headers = {
+            'Content-Type': isNDJSON ? 'application/x-ndjson; charset=utf-8' : 'application/json; charset=utf-8',
+            ...(isNDJSON ? { 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' } : {}),
+        };
+        const enqueueArray = (chunk) => {
+            if (!controllerRef)
+                return;
+            if (first) {
+                controllerRef.enqueue(encoder.encode('[' + chunk));
+                first = false;
+            }
+            else {
+                controllerRef.enqueue(encoder.encode(',' + chunk));
+            }
+        };
+        const writer = {
+            send(value) {
+                if (closed || !controllerRef)
+                    return;
+                const json = JSON.stringify(value);
+                if (isNDJSON) {
+                    controllerRef.enqueue(encoder.encode(json + '\n'));
+                }
+                else {
+                    enqueueArray(json);
+                }
+            },
+            write(chunk) {
+                if (closed || !controllerRef)
+                    return;
+                const encoded = typeof chunk === 'string' ? encoder.encode(chunk) : chunk;
+                controllerRef.enqueue(encoded);
+            },
+            close() {
+                if (closed)
+                    return;
+                if (!isNDJSON && controllerRef && !first) {
+                    controllerRef.enqueue(encoder.encode(']'));
+                }
+                closed = true;
+                controllerRef?.close();
+            },
+            setHeader(key, value) {
+                headers[key] = value;
+            },
+        };
+        const body = new ReadableStream({
+            start(controller) {
+                controllerRef = controller;
+                ctx.request.signal.addEventListener('abort', () => {
+                    closed = true;
+                    controllerRef?.close();
+                });
+                Promise.resolve(handler({ ...ctx, response: writer })).catch((err) => {
+                    try {
+                        controller.error(err);
+                    }
+                    catch { /* noop */ }
+                });
+            },
+            cancel() {
+                closed = true;
+            },
+        });
+        return new Response(body, {
+            status: 200,
+            headers,
+        });
+    });
+}

package/dist/core/responseHelpers.d.ts

@@ -1,17 +1,79 @@
-import { HeadersInit } from "undici";
+import { BodyInit, HeadersInit } from 'undici';
+/**
+ * A standardized shape for internal route result objects.
+ * These are later converted into native `Response` instances.
+ */
 export 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
+ */
 export declare const ok: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 201 Created
+ */
 export declare const created: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 204 No Content
+ */
 export declare const noContent: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 304 Not Modified
+ */
 export declare const notModified: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 400 Bad Request
+ */
 export declare const badRequest: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 401 Unauthorized
+ */
 export declare const unauthorized: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 403 Forbidden
+ */
 export declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 404 Not Found
+ */
 export declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 405 Method Not Allowed
+ */
 export declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 500 Internal Server Error
+ */
 export 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
+ */
+export 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
+ */
 export declare function toAstroResponse(result: ResultResponse | undefined): Response;