astro-routify 1.2.2 → 1.4.0

package/dist/core/RouterBuilder.js

@@ -1,6 +1,8 @@
-import { defineRoute } from './defineRoute';
+import { defineRoute, isRoute } from './defineRoute';
 import { defineRouter } from './defineRouter';
+import { defineGroup, RouteGroup } from './defineGroup';
 import { HttpMethod } from './HttpMethod';
+import { globalRegistry } from './registry';
 /**
  * A fluent builder for creating and composing API routes in Astro.
  *
@@ -26,14 +28,134 @@ import { HttpMethod } from './HttpMethod';
  *
  * export const GET = router.build();
  * ```
+ *
+ * @example Auto-discovering routes via Vite glob:
+ * ```ts
+ * const router = new RouterBuilder()
+ *   .addModules(import.meta.glob('./**\/*.routes.ts', { eager: true }));
+ *
+ * export const ALL = router.build();
+ * ```
  */
 export class RouterBuilder {
     constructor(options) {
         this._routes = [];
+        this._groups = [];
+        this._middlewares = [];
+        this._shouldLog = false;
         this._options = {
             basePath: 'api',
             ...options,
         };
+        if ((typeof process !== 'undefined' && process.env?.NODE_ENV === 'development') ||
+            import.meta.env?.DEV) {
+            this._shouldLog = true;
+        }
+    }
+    /**
+     * Adds a global middleware to all routes registered in this builder.
+     *
+     * @param middleware - The middleware function.
+     * @returns The current builder instance.
+     */
+    use(middleware) {
+        this._middlewares.push(middleware);
+        return this;
+    }
+    /**
+     * Creates and adds a new route group to the builder.
+     *
+     * @param basePath - The base path for the group.
+     * @param configure - Optional callback to configure the group.
+     * @returns The created RouteGroup instance.
+     */
+    group(basePath, configure) {
+        const group = defineGroup(basePath, configure);
+        this.addGroup(group);
+        return group;
+    }
+    /**
+     * Adds all routes and groups that have been auto-registered via `defineRoute(..., true)`
+     * or `defineGroup(..., true)`.
+     *
+     * @returns The current builder instance.
+     */
+    addRegistered() {
+        globalRegistry.getItems().forEach((item) => {
+            if (item instanceof RouteGroup) {
+                this.addGroup(item);
+            }
+            else if (isRoute(item)) {
+                this.addRoute(item);
+            }
+        });
+        return this;
+    }
+    /**
+     * Bulk registers routes and groups from a module collection.
+     * Ideal for use with Vite's `import.meta.glob` (with `{ eager: true }`).
+     *
+     * It will search for both default and named exports that are either `Route` or `RouteGroup`.
+     *
+     * @param modules A record of modules (e.g. from `import.meta.glob`).
+     * @returns The current builder instance.
+     */
+    addModules(modules) {
+        Object.values(modules).forEach((m) => {
+            if (m instanceof RouteGroup) {
+                this.addGroup(m);
+            }
+            else if (isRoute(m)) {
+                this.addRoute(m);
+            }
+            else if (typeof m === 'object' && m !== null) {
+                Object.values(m).forEach((val) => {
+                    if (val instanceof RouteGroup) {
+                        this.addGroup(val);
+                    }
+                    else if (isRoute(val)) {
+                        this.addRoute(val);
+                    }
+                    else if (Array.isArray(val)) {
+                        val.forEach((item) => {
+                            if (isRoute(item)) {
+                                this.addRoute(item);
+                            }
+                            else if (item instanceof RouteGroup) {
+                                this.addGroup(item);
+                            }
+                        });
+                    }
+                });
+            }
+        });
+        return this;
+    }
+    /**
+     * Prints all registered routes to the console.
+     * Useful for debugging during development.
+     *
+     * @returns The current builder instance.
+     */
+    logRoutes() {
+        console.log(`\x1b[36m[RouterBuilder]\x1b[0m Registered routes:`);
+        const limit = 30;
+        this._routes.slice(0, limit).forEach((r) => {
+            console.log(`  \x1b[32m${r.method.padEnd(7)}\x1b[0m ${r.path}`);
+        });
+        if (this._routes.length > limit) {
+            console.log(`  ... and ${this._routes.length - limit} more`);
+        }
+        return this;
+    }
+    /**
+     * Disables the automatic logging of routes that happens in development mode.
+     *
+     * @returns The current builder instance.
+     */
+    disableLogging() {
+        this._shouldLog = false;
+        return this;
     }
     /**
      * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
@@ -73,60 +195,72 @@ export class RouterBuilder {
      * @returns The current builder instance (for chaining).
      */
     addGroup(group) {
-        this._routes.push(...group.getRoutes());
+        this._groups.push(group);
         return this;
     }
     /**
      * Adds a GET route.
      * @param path Route path (e.g., `/items/:id`)
-     * @param handler Request handler function.
+     * @param handlers Middleware(s) followed by a request handler function.
      */
-    addGet(path, handler) {
-        return this.add(HttpMethod.GET, path, handler);
+    addGet(path, ...handlers) {
+        return this.add(HttpMethod.GET, path, ...handlers);
     }
     /**
      * Adds a POST route.
      * @param path Route path.
-     * @param handler Request handler function.
+     * @param handlers Middleware(s) followed by a request handler function.
      */
-    addPost(path, handler) {
-        return this.add(HttpMethod.POST, path, handler);
+    addPost(path, ...handlers) {
+        return this.add(HttpMethod.POST, path, ...handlers);
     }
     /**
      * Adds a PUT route.
      * @param path Route path.
-     * @param handler Request handler function.
+     * @param handlers Middleware(s) followed by a request handler function.
      */
-    addPut(path, handler) {
-        return this.add(HttpMethod.PUT, path, handler);
+    addPut(path, ...handlers) {
+        return this.add(HttpMethod.PUT, path, ...handlers);
     }
     /**
      * Adds a DELETE route.
      * @param path Route path.
-     * @param handler Request handler function.
+     * @param handlers Middleware(s) followed by a request handler function.
      */
-    addDelete(path, handler) {
-        return this.add(HttpMethod.DELETE, path, handler);
+    addDelete(path, ...handlers) {
+        return this.add(HttpMethod.DELETE, path, ...handlers);
     }
     /**
      * Adds a PATCH route.
      * @param path Route path.
-     * @param handler Request handler function.
+     * @param handlers Middleware(s) followed by a request handler function.
      */
-    addPatch(path, handler) {
-        return this.add(HttpMethod.PATCH, path, handler);
+    addPatch(path, ...handlers) {
+        return this.add(HttpMethod.PATCH, path, ...handlers);
     }
     /**
      * 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.
+     * @param args Middleware(s) and handler.
      * @returns The current builder instance (for chaining).
      */
-    add(method, subPath, handler) {
+    add(method, subPath, ...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 = subPath.startsWith('/') ? subPath : `/${subPath}`;
-        this._routes.push(defineRoute(method, normalizedPath, handler));
+        this._routes.push(defineRoute({
+            method,
+            path: normalizedPath,
+            handler,
+            middlewares,
+            metadata
+        }));
         return this;
     }
     /**
@@ -138,7 +272,62 @@ export class RouterBuilder {
      * @returns A fully resolved Astro route handler.
      */
     build() {
-        return defineRouter(this._routes, this._options);
+        if (this._shouldLog) {
+            this.logRoutes();
+        }
+        // Collect all routes from builder and groups
+        const allRoutes = [...this._routes];
+        for (const group of this._groups) {
+            allRoutes.push(...group.getRoutes());
+        }
+        // Apply global middlewares to all routes before building
+        const finalRoutes = allRoutes.map(route => ({
+            ...route,
+            middlewares: [...this._middlewares, ...(route.middlewares || [])]
+        }));
+        return defineRouter(finalRoutes, this._options);
     }
 }
 RouterBuilder._registerWarned = false;
+/**
+ * A global RouterBuilder instance for easy, centralized route registration.
+ */
+RouterBuilder.global = new RouterBuilder();
+/**
+ * A convenience helper to create a router.
+ *
+ * If modules are provided (e.g. from Vite's `import.meta.glob`), they will be registered.
+ * If no modules are provided, it will automatically include all routes that were
+ * registered via the auto-registration flags (`defineRoute(..., true)`).
+ *
+ * @example Auto-discovery via glob:
+ * ```ts
+ * export const ALL = createRouter(import.meta.glob('./**\/*.ts', { eager: true }));
+ * ```
+ *
+ * @example Auto-registration via global registry:
+ * ```ts
+ * export const ALL = createRouter();
+ * ```
+ *
+ * @param modulesOrOptions Either modules to register or router options.
+ * @param options Router options (if first arg is modules).
+ * @returns An Astro-compatible route handler.
+ */
+export function createRouter(modulesOrOptions, options) {
+    let modules;
+    let finalOptions;
+    if (modulesOrOptions && !('basePath' in modulesOrOptions || 'onNotFound' in modulesOrOptions || 'debug' in modulesOrOptions)) {
+        modules = modulesOrOptions;
+        finalOptions = options;
+    }
+    else {
+        finalOptions = modulesOrOptions;
+    }
+    const builder = new RouterBuilder(finalOptions);
+    if (modules) {
+        builder.addModules(modules);
+    }
+    builder.addRegistered();
+    return builder.build();
+}

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.
  *
@@ -14,6 +15,7 @@ import { Handler } from "./defineHandler";
 export declare class RouteGroup {
     private basePath;
     private routes;
+    private middlewares;
     /**
      * Creates a new route group with the specified base path.
      * Trailing slashes are automatically removed.
@@ -25,49 +27,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 +92,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.
  *
@@ -20,6 +21,7 @@ export class RouteGroup {
      */
     constructor(basePath) {
         this.routes = [];
+        this.middlewares = [];
         this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;
     }
     /**
@@ -28,61 +30,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 +135,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,29 @@
 import type { APIContext, APIRoute } from 'astro';
 import { type ResultResponse } from './responseHelpers';
+/**
+ * Enhanced Astro context for Routify.
+ */
+export interface RoutifyContext extends APIContext {
+    /**
+     * Parsed query parameters from the URL.
+     */
+    query: Record<string, string>;
+    /**
+     * Shared data container for middlewares and handlers (e.g., validation results).
+     */
+    data: Record<string, any>;
+}
+/**
+ * A middleware function that can modify the context or short-circuit the response.
+ */
+export type Middleware = (ctx: RoutifyContext, next: () => Promise<Response>) => Promise<Response> | Response;
 /**
  * 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;
+export type Handler = (ctx: RoutifyContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,
@@ -18,10 +35,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>;