astro-routify 1.2.2 → 1.5.0

package/dist/core/decorators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @Get decorator - auto-registers a GET route.
+ */
+export declare const Get: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Post decorator - auto-registers a POST route.
+ */
+export declare const Post: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Put decorator - auto-registers a PUT route.
+ */
+export declare const Put: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Delete decorator - auto-registers a DELETE route.
+ */
+export declare const Delete: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Patch decorator - auto-registers a PATCH route.
+ */
+export declare const Patch: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @RouteGroup decorator - can be used on classes to auto-register a group.
+ * Note: This requires the class to have a static method or property that returns the routes,
+ * or it can be used in conjunction with method decorators.
+ *
+ * For now, we'll implement a simple version that can be used on a class
+ * if the class is intended to be a group.
+ */
+export declare function Group(basePath: string): (constructor: Function) => void;

package/dist/core/decorators.js

@@ -0,0 +1,49 @@
+import { HttpMethod } from './HttpMethod';
+import { defineRoute } from './defineRoute';
+/**
+ * Decorator factory for HTTP methods.
+ */
+function createMethodDecorator(method) {
+    return function (path) {
+        return function (target, propertyKey, descriptor) {
+            const handler = descriptor ? descriptor.value : target[propertyKey];
+            if (typeof handler === 'function') {
+                defineRoute(method, path, handler, true);
+            }
+        };
+    };
+}
+/**
+ * @Get decorator - auto-registers a GET route.
+ */
+export const Get = createMethodDecorator(HttpMethod.GET);
+/**
+ * @Post decorator - auto-registers a POST route.
+ */
+export const Post = createMethodDecorator(HttpMethod.POST);
+/**
+ * @Put decorator - auto-registers a PUT route.
+ */
+export const Put = createMethodDecorator(HttpMethod.PUT);
+/**
+ * @Delete decorator - auto-registers a DELETE route.
+ */
+export const Delete = createMethodDecorator(HttpMethod.DELETE);
+/**
+ * @Patch decorator - auto-registers a PATCH route.
+ */
+export const Patch = createMethodDecorator(HttpMethod.PATCH);
+/**
+ * @RouteGroup decorator - can be used on classes to auto-register a group.
+ * Note: This requires the class to have a static method or property that returns the routes,
+ * or it can be used in conjunction with method decorators.
+ *
+ * For now, we'll implement a simple version that can be used on a class
+ * if the class is intended to be a group.
+ */
+export function Group(basePath) {
+    return function (constructor) {
+        // In a more advanced implementation, we could collect all methods
+        // and register them as a group. For now, we'll keep it simple.
+    };
+}

package/dist/core/defineGroup.d.ts

@@ -1,5 +1,6 @@
+import { HttpMethod } from './HttpMethod';
 import { type Route } from './defineRoute';
-import { Handler } from "./defineHandler";
+import { Middleware } from "./defineHandler";
 /**
  * Represents a group of routes under a shared base path.
  *
@@ -12,8 +13,10 @@ import { Handler } from "./defineHandler";
  *   .addPost('/', createUser);
  */
 export declare class RouteGroup {
+    readonly _routifyType = "group";
     private basePath;
     private routes;
+    private middlewares;
     /**
      * Creates a new route group with the specified base path.
      * Trailing slashes are automatically removed.
@@ -25,49 +28,61 @@ export declare class RouteGroup {
      * Returns the normalized base path used by the group.
      */
     getBasePath(): string;
+    /**
+     * Adds a middleware to all routes in this group.
+     *
+     * @param middleware - The middleware function to add
+     * @returns The current group instance
+     */
+    use(middleware: Middleware): this;
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addGet(path: string, handler: Handler): this;
+    addGet(path: string, ...handlers: any[]): 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPost(path: string, handler: Handler): this;
+    addPost(path: string, ...handlers: any[]): 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPut(path: string, handler: Handler): this;
+    addPut(path: string, ...handlers: any[]): 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addDelete(path: string, handler: Handler): this;
+    addDelete(path: string, ...handlers: any[]): 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPatch(path: string, handler: Handler): this;
+    addPatch(path: string, ...handlers: any[]): this;
     /**
-     * Internal method to register a route under the group with any HTTP method.
+     * Registers a route under the group's base path.
      *
      * @param method - HTTP verb
-     * @param subPath - Route path relative to the base
-     * @param handler - The handler function for this route
+     * @param path - Path relative to the base path
+     * @param args - Middleware(s) and handler
+     * @returns The current group instance
+     */
+    add(method: HttpMethod, path: string, ...args: any[]): this;
+    /**
+     * Registers the group and all its current routes to the global registry.
      */
-    private add;
+    register(): this;
     /**
      * Returns all the registered routes in the group.
      */
@@ -78,10 +93,11 @@ export declare class RouteGroup {
  *
  * @param basePath - The base path prefix for all routes
  * @param configure - Optional callback to configure the group inline
+ * @param autoRegister - If true, registers the group to the global registry
  *
  * @example
  * const users = defineGroup('/users', (group) => {
  *   group.addGet('/:id', handler);
- * });
+ * }, true);
  */
-export declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void): RouteGroup;
+export declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void, autoRegister?: boolean): RouteGroup;

package/dist/core/defineGroup.js

@@ -1,5 +1,6 @@
 import { HttpMethod } from './HttpMethod';
 import { defineRoute } from './defineRoute';
+import { globalRegistry } from './registry';
 /**
  * Represents a group of routes under a shared base path.
  *
@@ -19,7 +20,9 @@ export class RouteGroup {
      * @param basePath - The common prefix for all routes in the group (e.g. "/users")
      */
     constructor(basePath) {
+        this._routifyType = 'group';
         this.routes = [];
+        this.middlewares = [];
         this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
     }
     /**
@@ -28,61 +31,97 @@ export class RouteGroup {
     getBasePath() {
         return this.basePath;
     }
+    /**
+     * Adds a middleware to all routes in this group.
+     *
+     * @param middleware - The middleware function to add
+     * @returns The current group instance
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        // Apply to already registered routes in this group
+        for (const route of this.routes) {
+            if (!route.middlewares)
+                route.middlewares = [];
+            route.middlewares.push(middleware);
+        }
+        return this;
+    }
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addGet(path, handler) {
-        return this.add(HttpMethod.GET, path, handler);
+    addGet(path, ...handlers) {
+        return this.add(HttpMethod.GET, path, ...handlers);
     }
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPost(path, handler) {
-        return this.add(HttpMethod.POST, path, handler);
+    addPost(path, ...handlers) {
+        return this.add(HttpMethod.POST, path, ...handlers);
     }
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPut(path, handler) {
-        return this.add(HttpMethod.PUT, path, handler);
+    addPut(path, ...handlers) {
+        return this.add(HttpMethod.PUT, path, ...handlers);
     }
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addDelete(path, handler) {
-        return this.add(HttpMethod.DELETE, path, handler);
+    addDelete(path, ...handlers) {
+        return this.add(HttpMethod.DELETE, path, ...handlers);
     }
     /**
      * 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
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPatch(path, handler) {
-        return this.add(HttpMethod.PATCH, path, handler);
+    addPatch(path, ...handlers) {
+        return this.add(HttpMethod.PATCH, path, ...handlers);
     }
     /**
-     * Internal method to register a route under the group with any HTTP method.
+     * Registers a route under the group's base path.
      *
      * @param method - HTTP verb
-     * @param subPath - Route path relative to the base
-     * @param handler - The handler function for this route
+     * @param path - Path relative to the base path
+     * @param args - Middleware(s) and handler
+     * @returns The current group instance
      */
-    add(method, subPath, handler) {
-        const normalizedPath = subPath.startsWith('/') ? subPath : `/${subPath}`;
-        this.routes.push(defineRoute(method, `${this.basePath}${normalizedPath}`, handler));
+    add(method, path, ...args) {
+        let metadata;
+        if (args.length > 1 && typeof args[args.length - 1] === 'object' && typeof args[args.length - 2] === 'function') {
+            metadata = args.pop();
+        }
+        const handler = args.pop();
+        const middlewares = args;
+        const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+        this.routes.push(defineRoute({
+            method,
+            path: `${this.basePath}${normalizedPath}`,
+            handler,
+            middlewares: [...this.middlewares, ...middlewares],
+            metadata
+        }));
+        return this;
+    }
+    /**
+     * Registers the group and all its current routes to the global registry.
+     */
+    register() {
+        globalRegistry.register(this);
         return this;
     }
     /**
@@ -97,15 +136,19 @@ export class RouteGroup {
  *
  * @param basePath - The base path prefix for all routes
  * @param configure - Optional callback to configure the group inline
+ * @param autoRegister - If true, registers the group to the global registry
  *
  * @example
  * const users = defineGroup('/users', (group) => {
  *   group.addGet('/:id', handler);
- * });
+ * }, true);
  */
-export function defineGroup(basePath, configure) {
+export function defineGroup(basePath, configure, autoRegister) {
     const group = new RouteGroup(basePath);
     if (configure)
         configure(group);
+    if (autoRegister) {
+        globalRegistry.register(group);
+    }
     return group;
 }

package/dist/core/defineHandler.d.ts

@@ -1,12 +1,37 @@
 import type { APIContext, APIRoute } from 'astro';
-import { type ResultResponse } from './responseHelpers';
+import { type HandlerResult } 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).
+ * Enhanced Astro context for Routify.
  */
-export type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+export interface RoutifyContext<State = Record<string, any>> extends APIContext {
+    /**
+     * Parsed query parameters from the URL.
+     * Note: If multiple parameters have the same key, only the last one is included.
+     * Use `searchParams` for full multi-value support.
+     */
+    query: Record<string, string | string[]>;
+    /**
+     * Full URLSearchParams object for the incoming request.
+     */
+    searchParams: URLSearchParams;
+    /**
+     * Shared state container for middlewares and handlers (e.g., validation results).
+     * This is where middlewares can store information for subsequent handlers.
+     */
+    state: State;
+}
+/**
+ * Convenience type alias for RoutifyContext.
+ */
+export type Context<State = Record<string, any>> = RoutifyContext<State>;
+/**
+ * A middleware function that can modify the context or short-circuit the response.
+ */
+export type Middleware<State = any> = (ctx: RoutifyContext<State>, next: () => Promise<Response>) => Promise<Response> | Response;
+/**
+ * A flexible route handler that can return various types.
+ */
+export type Handler<State = any> = (ctx: RoutifyContext<State>) => Promise<HandlerResult> | HandlerResult;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,
@@ -18,10 +43,3 @@ export type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> |
  * @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

@@ -33,18 +33,7 @@ export function defineHandler(handler) {
                 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
+            // Structured ResultResponse or other HandlerResult → native Astro Response
             const finalResponse = toAstroResponse(result);
             logResponse(finalResponse.status, start);
             return finalResponse;
@@ -57,14 +46,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,19 @@ 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>;
+    /**
+     * Internal marker to identify the object type during module discovery.
+     * @internal
+     */
+    _routifyType?: 'route';
 }
 /**
  * Defines a route using a `Route` object.
@@ -24,9 +37,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 +50,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,28 @@
 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;
     }
-    const route = {
-        method: methodOrRoute,
-        path: maybePath,
-        handler: maybeHandler,
-    };
+    else {
+        route = {
+            method: methodOrRoute,
+            path: maybePathOrAutoRegister,
+            handler: maybeHandler,
+        };
+        autoRegister = !!maybeAutoRegister;
+    }
+    route._routifyType = 'route';
     validateRoute(route);
+    if (autoRegister) {
+        globalRegistry.register(route);
+    }
     return route;
 }
 /**
@@ -21,11 +31,28 @@ 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}`);
     }
     if (!ALLOWED_HTTP_METHODS.has(method)) {
         throw new Error(`Unsupported HTTP method in route: ${method}`);
     }
+    if (path.includes('**') && !path.endsWith('**')) {
+        throw new Error(`Catch-all '**' is only allowed at the end of a path: ${path}`);
+    }
+}
+/**
+ * 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' &&
+        (obj._routifyType === 'route' ||
+            (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 { notFound, type HandlerResult } 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) => HandlerResult | Response;
 }
 /**
  * Defines a router that dynamically matches registered routes based on method and path.