astro-routify 1.2.1 → 1.4.0

package/dist/core/defineHandler.js

@@ -1,4 +1,4 @@
-import { internalError, toAstroResponse } from './responseHelpers';
+import { internalError, toAstroResponse, isReadableStream } from './responseHelpers';
 /**
  * Logs the incoming request method and path to the console.
  */
@@ -57,14 +57,3 @@ 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,5 +1,5 @@
 import { HttpMethod } from './HttpMethod';
-import type { Handler } from './defineHandler';
+import type { Handler, Middleware } from './defineHandler';
 /**
  * Represents a single route definition.
  */
@@ -16,6 +16,14 @@ export interface Route {
      * The function that handles the request when matched.
      */
     handler: Handler;
+    /**
+     * Optional array of middlewares to run before the handler.
+     */
+    middlewares?: Middleware[];
+    /**
+     * Optional metadata for the route (e.g., for OpenAPI generation).
+     */
+    metadata?: Record<string, any>;
 }
 /**
  * Defines a route using a `Route` object.
@@ -24,9 +32,10 @@ export interface Route {
  * defineRoute({ method: 'GET', path: '/users', handler });
  *
  * @param route - A fully constructed route object
+ * @param autoRegister - If true, registers the route to the global registry
  * @returns The validated Route object
  */
-export declare function defineRoute(route: Route): Route;
+export declare function defineRoute(route: Route, autoRegister?: boolean): Route;
 /**
  * Defines a route by specifying its method, path, and handler explicitly.
  *
@@ -36,6 +45,21 @@ export declare function defineRoute(route: Route): Route;
  * @param method - HTTP method to match
  * @param path - Route path (must start with `/`)
  * @param handler - Function to handle the matched request
+ * @param autoRegister - If true, registers the route to the global registry
  * @returns The validated Route object
  */
-export declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;
+export declare function defineRoute(method: HttpMethod, path: string, handler: Handler, autoRegister?: boolean): 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 `/`
+ */
+export declare function validateRoute({ method, path }: Route): void;
+/**
+ * Checks if an object implements the `Route` interface.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is a valid Route
+ */
+export declare function isRoute(obj: any): obj is Route;

package/dist/core/defineRoute.js

@@ -1,18 +1,27 @@
 import { ALLOWED_HTTP_METHODS } from './HttpMethod';
+import { globalRegistry } from './registry';
 /**
  * Internal route definition logic that supports both overloads.
  */
-export function defineRoute(methodOrRoute, maybePath, maybeHandler) {
+export function defineRoute(methodOrRoute, maybePathOrAutoRegister, maybeHandler, maybeAutoRegister) {
+    let autoRegister = false;
+    let route;
     if (typeof methodOrRoute === 'object') {
-        validateRoute(methodOrRoute);
-        return methodOrRoute;
+        route = methodOrRoute;
+        autoRegister = !!maybePathOrAutoRegister;
+    }
+    else {
+        route = {
+            method: methodOrRoute,
+            path: maybePathOrAutoRegister,
+            handler: maybeHandler,
+        };
+        autoRegister = !!maybeAutoRegister;
     }
-    const route = {
-        method: methodOrRoute,
-        path: maybePath,
-        handler: maybeHandler,
-    };
     validateRoute(route);
+    if (autoRegister) {
+        globalRegistry.register(route);
+    }
     return route;
 }
 /**
@@ -21,7 +30,7 @@ export function defineRoute(methodOrRoute, maybePath, maybeHandler) {
  * @param route - Route to validate
  * @throws If method is unsupported or path doesn't start with `/`
  */
-function validateRoute({ method, path }) {
+export function validateRoute({ method, path }) {
     if (!path.startsWith('/')) {
         throw new Error(`Route path must start with '/': ${path}`);
     }
@@ -29,3 +38,16 @@ function validateRoute({ method, path }) {
         throw new Error(`Unsupported HTTP method in route: ${method}`);
     }
 }
+/**
+ * Checks if an object implements the `Route` interface.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is a valid Route
+ */
+export function isRoute(obj) {
+    return (obj &&
+        typeof obj === 'object' &&
+        typeof obj.method === 'string' &&
+        typeof obj.path === 'string' &&
+        typeof obj.handler === 'function');
+}

package/dist/core/defineRouter.d.ts

@@ -1,5 +1,6 @@
 import type { APIRoute } from 'astro';
-import { notFound } from './responseHelpers';
+import { type RoutifyContext } from './defineHandler';
+import { internalError, notFound } from './responseHelpers';
 import type { Route } from './defineRoute';
 /**
  * Optional configuration for the router instance.
@@ -14,6 +15,15 @@ export interface RouterOptions {
      * Custom handler to return when no route is matched (404).
      */
     onNotFound?: () => ReturnType<typeof notFound>;
+    /**
+     * If true, enables debug logging for route matching.
+     * Useful during development to trace which route is being matched.
+     */
+    debug?: boolean;
+    /**
+     * Custom error handler for the router.
+     */
+    onError?: (error: unknown, ctx: RoutifyContext) => ReturnType<typeof internalError> | Response;
 }
 /**
  * Defines a router that dynamically matches registered routes based on method and path.

package/dist/core/defineRouter.js

@@ -27,19 +27,40 @@ 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.query = Object.fromEntries(url.searchParams.entries());
+        routifyCtx.data = {};
+        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 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) {
+        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'}`);
+        }
+        if (!route) {
             // Method exists but not allowed for this route
             if (allowed && allowed.length) {
                 return toAstroResponse(methodNotAllowed('Method Not Allowed', {
@@ -47,10 +68,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.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 data is stored in `ctx.data.body`, `ctx.data.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 data is stored in `ctx.data.body`, `ctx.data.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.data.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.data.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.data.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,57 @@
+/**
+ * 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}
+        const openApiPath = path.replace(/:([a-zA-Z0-9_]+)(\(.*?\))?/g, '{$1}');
+        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 pathParamMatches = path.matchAll(/:([a-zA-Z0-9_]+)/g);
+        for (const match of pathParamMatches) {
+            const name = match[1];
+            spec.paths[openApiPath][method].parameters.push({
+                name,
+                in: 'path',
+                required: true,
+                schema: { type: 'string' }
+            });
+        }
+    }
+    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

@@ -53,8 +53,18 @@ export declare const notFound: <T = string>(body?: T, headers?: HeadersInit) =>
  * 405 Method Not Allowed
  */
 export declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 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>;
 /**
@@ -67,6 +77,13 @@ export declare const internalError: (err: unknown, headers?: HeadersInit) => Res
  * @returns A ResultResponse for download-ready content
  */
 export declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
+/**
+ * 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` into a native `Response` object
  * for use inside Astro API routes.

package/dist/core/responseHelpers.js

@@ -43,10 +43,23 @@ export const notFound = (body = 'Not Found', headers) => createResponse(404, bod
  * 405 Method Not Allowed
  */
 export const methodNotAllowed = (body = 'Method Not Allowed', headers) => createResponse(405, body, headers);
+/**
+ * 429 Too Many Requests
+ */
+export const tooManyRequests = (body = 'Too Many Requests', headers) => createResponse(429, body, headers);
+/**
+ * Returns a response with JSON body and specified status.
+ */
+export const json = (body, status = 200, headers) => createResponse(status, body, headers);
 /**
  * 500 Internal Server Error
+ *
+ * In production, you might want to avoid leaking error details.
  */
-export const internalError = (err, headers) => createResponse(500, err instanceof Error ? err.message : String(err), headers);
+export const internalError = (err, headers) => {
+    const message = err instanceof Error ? err.message : String(err);
+    return createResponse(500, message, headers);
+};
 /**
  * Sends a binary or stream-based file response with optional content-disposition.
  *
@@ -57,8 +70,9 @@ export const internalError = (err, headers) => createResponse(500, err instanceo
  * @returns A ResultResponse for download-ready content
  */
 export const fileResponse = (content, contentType, fileName, headers) => {
-    const disposition = fileName
-        ? { 'Content-Disposition': `attachment; filename="${fileName}"` }
+    const sanitizedFileName = fileName?.replace(/"/g, '\\"');
+    const disposition = sanitizedFileName
+        ? { 'Content-Disposition': `attachment; filename="${sanitizedFileName}"` }
         : {};
     return {
         status: 200,
@@ -70,6 +84,22 @@ export const fileResponse = (content, contentType, fileName, headers) => {
         },
     };
 };
+function isPlainObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+/**
+ * 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');
+}
 /**
  * Converts an internal `ResultResponse` into a native `Response` object
  * for use inside Astro API routes.
@@ -86,12 +116,12 @@ export function toAstroResponse(result) {
     if (body === undefined || body === null) {
         return new Response(null, { status, headers });
     }
-    const isObject = typeof body === 'object' || Array.isArray(body);
+    const isJson = isPlainObject(body) || Array.isArray(body);
     const finalHeaders = {
         ...(headers ?? {}),
-        ...(isObject ? { 'Content-Type': 'application/json; charset=utf-8' } : {}),
+        ...(isJson ? { 'Content-Type': 'application/json; charset=utf-8' } : {}),
     };
-    return new Response(isObject ? JSON.stringify(body) : body, {
+    return new Response(isJson ? JSON.stringify(body) : body, {
         status,
         headers: finalHeaders,
     });