astro-routify 1.2.2 → 1.5.0

package/dist/core/defineRouter.js

@@ -27,19 +27,56 @@ import { normalizeMethod } from './HttpMethod';
 export function defineRouter(routes, options = {}) {
     const trie = new RouteTrie();
     for (const route of routes) {
-        trie.insert(route.path, route.method, route.handler);
+        trie.insert(route);
     }
-    return async (ctx) => {
-        const pathname = new URL(ctx.request.url).pathname;
-        let basePath = options.basePath ?? '/api';
-        if (!basePath.startsWith('/')) {
-            basePath = '/' + basePath;
+    let basePath = options.basePath ?? '/api';
+    if (basePath !== '' && !basePath.startsWith('/')) {
+        basePath = '/' + basePath;
+    }
+    if (basePath.endsWith('/') && basePath !== '/') {
+        basePath = basePath.slice(0, -1);
+    }
+    if (basePath === '/') {
+        basePath = '';
+    }
+    const handler = defineHandler(async (routifyCtx) => {
+        const url = new URL(routifyCtx.request.url);
+        const pathname = url.pathname;
+        routifyCtx.searchParams = url.searchParams;
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            const existing = query[key];
+            if (existing !== undefined) {
+                if (Array.isArray(existing)) {
+                    existing.push(value);
+                }
+                else {
+                    query[key] = [existing, value];
+                }
+            }
+            else {
+                query[key] = value;
+            }
+        });
+        routifyCtx.query = query;
+        routifyCtx.state = {};
+        let path = pathname;
+        if (basePath !== '') {
+            if (!pathname.startsWith(basePath)) {
+                return toAstroResponse(options.onNotFound ? options.onNotFound() : notFound('Not Found'));
+            }
+            const nextChar = pathname.charAt(basePath.length);
+            if (nextChar !== '' && nextChar !== '/') {
+                return toAstroResponse(options.onNotFound ? options.onNotFound() : notFound('Not Found'));
+            }
+            path = pathname.slice(basePath.length);
+        }
+        const method = normalizeMethod(routifyCtx.request.method);
+        const { route, allowed, params } = trie.find(path, method);
+        if (options.debug) {
+            console.log(`[RouterBuilder] ${method} ${path} -> ${route ? 'matched' : allowed && allowed.length ? '405' : '404'}`);
         }
-        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) {
+        if (!route) {
             // Method exists but not allowed for this route
             if (allowed && allowed.length) {
                 return toAstroResponse(methodNotAllowed('Method Not Allowed', {
@@ -47,10 +84,36 @@ export function defineRouter(routes, options = {}) {
                 }));
             }
             // No route matched at all → 404
-            const notFoundHandler = options.onNotFound ? options.onNotFound() : notFound('Not Found');
-            return toAstroResponse(notFoundHandler);
+            return toAstroResponse(options.onNotFound ? options.onNotFound() : notFound('Not Found'));
+        }
+        // Match found → delegate to handler with middlewares
+        routifyCtx.params = { ...routifyCtx.params, ...params };
+        try {
+            const middlewares = route.middlewares || [];
+            let index = -1;
+            const next = async () => {
+                index++;
+                if (index < middlewares.length) {
+                    const mw = middlewares[index];
+                    const res = await mw(routifyCtx, next);
+                    return res instanceof Response ? res : toAstroResponse(res);
+                }
+                else {
+                    const result = await route.handler(routifyCtx);
+                    return result instanceof Response ? result : toAstroResponse(result);
+                }
+            };
+            return await next();
+        }
+        catch (err) {
+            if (options.onError) {
+                const errorRes = options.onError(err, routifyCtx);
+                return errorRes instanceof Response ? errorRes : toAstroResponse(errorRes);
+            }
+            throw err;
         }
-        // Match found → delegate to handler
-        return defineHandler(handler)({ ...ctx, params: { ...ctx.params, ...params } });
-    };
+    });
+    handler.routes = routes;
+    handler.options = options;
+    return handler;
 }

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

@@ -3,7 +3,7 @@ import { HttpMethod } from '../HttpMethod';
 import { type Route } from '../defineRoute';
 type JsonValue = any;
 /**
- * A writer interface for streaming JSON data to the response body.
+ * A writer interface for streaming JSON state to the response body.
  * Supports both NDJSON and array formats.
  */
 export interface JsonStreamWriter {

package/dist/core/internal/createJsonStreamRoute.js

@@ -69,15 +69,23 @@ export function createJsonStreamRoute(path, handler, options) {
         const body = new ReadableStream({
             start(controller) {
                 controllerRef = controller;
-                ctx.request.signal.addEventListener('abort', () => {
+                const onAbort = () => {
                     closed = true;
-                    controllerRef?.close();
-                });
-                Promise.resolve(handler({ ...ctx, response: writer })).catch((err) => {
+                    try {
+                        controllerRef?.close();
+                    }
+                    catch { /* noop */ }
+                };
+                ctx.request.signal.addEventListener('abort', onAbort, { once: true });
+                Promise.resolve(handler({ ...ctx, response: writer }))
+                    .catch((err) => {
                     try {
                         controller.error(err);
                     }
                     catch { /* noop */ }
+                })
+                    .finally(() => {
+                    ctx.request.signal.removeEventListener('abort', onAbort);
                 });
             },
             cancel() {

package/dist/core/middlewares.d.ts

@@ -0,0 +1,47 @@
+import { type Middleware } from './defineHandler';
+/**
+ * CORS options.
+ */
+export interface CorsOptions {
+    origin?: string | string[] | ((origin: string) => boolean | string);
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+/**
+ * Middleware to enable Cross-Origin Resource Sharing (CORS).
+ */
+export declare function cors(options?: CorsOptions): Middleware;
+/**
+ * Middleware to add common security headers (Helmet-like).
+ */
+export declare function securityHeaders(): Middleware;
+/**
+ * Interface for schemas compatible with Zod, Valibot, etc.
+ */
+export interface Validatable {
+    safeParse: (data: any) => {
+        success: true;
+        data: any;
+    } | {
+        success: false;
+        error: any;
+    };
+}
+/**
+ * Validation schema for request components.
+ */
+export interface ValidationSchema {
+    body?: Validatable;
+    query?: Validatable;
+    params?: Validatable;
+}
+/**
+ * Middleware for request validation.
+ * Supports any schema library with a `safeParse` method (like Zod).
+ *
+ * Validated state is stored in `ctx.state.body`, `ctx.state.query`, etc.
+ */
+export declare function validate(schema: ValidationSchema): Middleware;

package/dist/core/middlewares.js

@@ -0,0 +1,110 @@
+import { badRequest, toAstroResponse } from './responseHelpers';
+/**
+ * Middleware to enable Cross-Origin Resource Sharing (CORS).
+ */
+export function cors(options = {}) {
+    return async (ctx, next) => {
+        const origin = ctx.request.headers.get('Origin');
+        // Handle preflight
+        if (ctx.request.method === 'OPTIONS') {
+            const headers = new Headers();
+            if (origin) {
+                headers.set('Access-Control-Allow-Origin', origin);
+            }
+            if (options.methods) {
+                headers.set('Access-Control-Allow-Methods', options.methods.join(','));
+            }
+            else {
+                headers.set('Access-Control-Allow-Methods', 'GET,POST,PUT,PATCH,DELETE,OPTIONS');
+            }
+            if (options.allowedHeaders) {
+                headers.set('Access-Control-Allow-Headers', options.allowedHeaders.join(','));
+            }
+            else {
+                const requestedHeaders = ctx.request.headers.get('Access-Control-Request-Headers');
+                if (requestedHeaders)
+                    headers.set('Access-Control-Allow-Headers', requestedHeaders);
+            }
+            if (options.credentials) {
+                headers.set('Access-Control-Allow-Credentials', 'true');
+            }
+            if (options.maxAge) {
+                headers.set('Access-Control-Max-Age', String(options.maxAge));
+            }
+            return new Response(null, { status: 204, headers });
+        }
+        const res = await next();
+        const newHeaders = new Headers(res.headers);
+        if (origin) {
+            newHeaders.set('Access-Control-Allow-Origin', origin);
+        }
+        else {
+            newHeaders.set('Access-Control-Allow-Origin', '*');
+        }
+        if (options.credentials) {
+            newHeaders.set('Access-Control-Allow-Credentials', 'true');
+        }
+        if (options.exposedHeaders) {
+            newHeaders.set('Access-Control-Expose-Headers', options.exposedHeaders.join(','));
+        }
+        return new Response(res.body, {
+            status: res.status,
+            statusText: res.statusText,
+            headers: newHeaders
+        });
+    };
+}
+/**
+ * Middleware to add common security headers (Helmet-like).
+ */
+export function securityHeaders() {
+    return async (ctx, next) => {
+        const res = await next();
+        const headers = new Headers(res.headers);
+        headers.set('X-Content-Type-Options', 'nosniff');
+        headers.set('X-Frame-Options', 'SAMEORIGIN');
+        headers.set('X-XSS-Protection', '1; mode=block');
+        headers.set('Referrer-Policy', 'no-referrer-when-downgrade');
+        headers.set('Content-Security-Policy', "default-src 'self'");
+        return new Response(res.body, {
+            status: res.status,
+            statusText: res.statusText,
+            headers
+        });
+    };
+}
+/**
+ * Middleware for request validation.
+ * Supports any schema library with a `safeParse` method (like Zod).
+ *
+ * Validated state is stored in `ctx.state.body`, `ctx.state.query`, etc.
+ */
+export function validate(schema) {
+    return async (ctx, next) => {
+        if (schema.params) {
+            const result = schema.params.safeParse(ctx.params);
+            if (!result.success)
+                return toAstroResponse(badRequest({ error: 'Invalid parameters', details: result.error }));
+            ctx.state.params = result.data;
+        }
+        if (schema.query) {
+            const result = schema.query.safeParse(ctx.query);
+            if (!result.success)
+                return toAstroResponse(badRequest({ error: 'Invalid query string', details: result.error }));
+            ctx.state.query = result.data;
+        }
+        if (schema.body) {
+            try {
+                const body = await ctx.request.clone().json();
+                const result = schema.body.safeParse(body);
+                if (!result.success)
+                    return toAstroResponse(badRequest({ error: 'Invalid request body', details: result.error }));
+                ctx.state.body = result.data;
+            }
+            catch (e) {
+                return toAstroResponse(badRequest({ error: 'Invalid JSON body' }));
+            }
+        }
+        return next();
+    };
+}

package/dist/core/openapi.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Basic options for OpenAPI generation.
+ */
+export interface OpenAPIOptions {
+    title: string;
+    version: string;
+    description?: string;
+    basePath?: string;
+}
+/**
+ * Generates an OpenAPI 3.0.0 specification from a list of Routify routes.
+ *
+ * @param router - The router handler function (returned by builder.build() or createRouter())
+ * @param options - Basic info for the OpenAPI spec
+ * @returns A JSON object representing the OpenAPI specification
+ */
+export declare function generateOpenAPI(router: any, options: OpenAPIOptions): any;

package/dist/core/openapi.js

@@ -0,0 +1,84 @@
+/**
+ * Generates an OpenAPI 3.0.0 specification from a list of Routify routes.
+ *
+ * @param router - The router handler function (returned by builder.build() or createRouter())
+ * @param options - Basic info for the OpenAPI spec
+ * @returns A JSON object representing the OpenAPI specification
+ */
+export function generateOpenAPI(router, options) {
+    const routes = router.routes || [];
+    const routerOptions = router.options || {};
+    const basePath = options.basePath ?? routerOptions.basePath ?? '/api';
+    const spec = {
+        openapi: '3.0.0',
+        info: {
+            title: options.title,
+            version: options.version,
+            description: options.description
+        },
+        servers: [
+            { url: basePath }
+        ],
+        paths: {}
+    };
+    for (const route of routes) {
+        const path = route.path;
+        // OpenAPI paths must start with / and should not include the basePath if it's in servers
+        // Convert :param or :param(regex) to {param}
+        // Convert ** to {rest} and * to {any}
+        let openApiPath = path
+            .replace(/:([a-zA-Z0-9_]+)(\(.*?\))?/g, '{$1}')
+            .replace(/\*\*/g, '{rest}')
+            .replace(/\*/g, '{any}');
+        if (!spec.paths[openApiPath])
+            spec.paths[openApiPath] = {};
+        const method = route.method.toLowerCase();
+        const metadata = route.metadata || {};
+        spec.paths[openApiPath][method] = {
+            summary: metadata.summary || `${route.method} ${path}`,
+            description: metadata.description,
+            tags: metadata.tags,
+            parameters: [],
+            responses: {
+                '200': {
+                    description: 'Successful response'
+                }
+            }
+        };
+        // Extract path parameters
+        const paramRegex = /:([a-zA-Z0-9_]+)(?:\((.*?)\))?/g;
+        let pMatch;
+        while ((pMatch = paramRegex.exec(path)) !== null) {
+            const name = pMatch[1];
+            const pattern = pMatch[2];
+            spec.paths[openApiPath][method].parameters.push({
+                name,
+                in: 'path',
+                required: true,
+                schema: {
+                    type: 'string',
+                    pattern: pattern ? pattern : undefined
+                }
+            });
+        }
+        if (path.includes('**')) {
+            spec.paths[openApiPath][method].parameters.push({
+                name: 'rest',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: 'Catch-all path'
+            });
+        }
+        else if (path.includes('*')) {
+            spec.paths[openApiPath][method].parameters.push({
+                name: 'any',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: 'Wildcard segment'
+            });
+        }
+    }
+    return spec;
+}

package/dist/core/registry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A global registry for routes and groups to support "agnostic" auto-registration.
+ * This allows routes to be defined anywhere in the project and automatically
+ * picked up by the router.
+ */
+export declare class InternalRegistry {
+    private static instance;
+    private items;
+    private constructor();
+    static getInstance(): InternalRegistry;
+    register(item: any): void;
+    getItems(): any[];
+    clear(): void;
+}
+export declare const globalRegistry: InternalRegistry;

package/dist/core/registry.js

@@ -0,0 +1,26 @@
+/**
+ * A global registry for routes and groups to support "agnostic" auto-registration.
+ * This allows routes to be defined anywhere in the project and automatically
+ * picked up by the router.
+ */
+export class InternalRegistry {
+    constructor() {
+        this.items = [];
+    }
+    static getInstance() {
+        if (!InternalRegistry.instance) {
+            InternalRegistry.instance = new InternalRegistry();
+        }
+        return InternalRegistry.instance;
+    }
+    register(item) {
+        this.items.push(item);
+    }
+    getItems() {
+        return [...this.items];
+    }
+    clear() {
+        this.items = [];
+    }
+}
+export const globalRegistry = InternalRegistry.getInstance();

package/dist/core/responseHelpers.d.ts

@@ -1,4 +1,8 @@
 import { BodyInit, HeadersInit } from 'undici';
+/**
+ * Supported types that can be returned from a route handler.
+ */
+export type HandlerResult = Response | ResultResponse | string | number | boolean | object | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | Blob | FormData | URLSearchParams | null | undefined;
 /**
  * A standardized shape for internal route result objects.
  * These are later converted into native `Response` instances.
@@ -57,14 +61,20 @@ export declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersI
  * 429 Too Many Requests
  */
 export declare const tooManyRequests: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * Returns a response with JSON body and specified status.
+ */
+export declare const json: (body: any, status?: number, headers?: HeadersInit) => ResultResponse<any>;
 /**
  * 500 Internal Server Error
+ *
+ * In production, you might want to avoid leaking error details.
  */
 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 content - The file state (Blob, ArrayBuffer, or stream)
  * @param contentType - MIME type of the file
  * @param fileName - Optional download filename
  * @param headers - Optional extra headers
@@ -72,12 +82,19 @@ export declare const internalError: (err: unknown, headers?: HeadersInit) => Res
  */
 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
+ * 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>;
+/**
+ * Converts an internal `ResultResponse` or any `HandlerResult` into a native `Response` object
  * for use inside Astro API routes.
  *
- * Automatically applies `Content-Type: application/json` for object bodies.
+ * Automatically applies appropriate Content-Type headers.
  *
- * @param result - A ResultResponse returned from route handler
+ * @param result - A ResultResponse or other supported type returned from route handler
  * @returns A native Response
  */
-export declare function toAstroResponse(result: ResultResponse | undefined): Response;
+export declare function toAstroResponse(result: HandlerResult): Response;