astro-routify 1.2.1 → 1.4.0

package/README.md

@@ -92,11 +92,15 @@ endpoint system.
 
 ### `defineRoute()`
 
-Declare a single route:
+Declare a single route. Now supports middlewares and metadata:
 
 ```ts
-defineRoute(HttpMethod.GET, "/users/:id", ({params}) => {
-    return ok({userId: params.id});
+defineRoute({
+    method: 'GET',
+    path: '/users/:id',
+    middlewares: [authMiddleware],
+    metadata: { summary: 'Get user by ID' },
+    handler: ({params}) => ok({userId: params.id})
 });
 ```
 
@@ -110,6 +114,125 @@ export const GET = defineRouter([
 ]);
 ```
 
+### Advanced Matching
+
+`astro-routify` supports advanced routing patterns including wildcards and regex constraints.
+
+#### 1. Wildcards
+- `*` matches exactly one segment.
+- `**` matches zero or more segments (catch-all).
+
+```ts
+builder.addGet('/files/*/download', () => ok('one segment'));
+builder.addGet('/static/**', () => ok('all segments'));
+```
+
+#### 2. Regex Constraints
+You can constrain parameters using regex by wrapping the pattern in parentheses: `:param(regex)`.
+
+```ts
+// Matches only numeric IDs
+builder.addGet('/users/:id(\\d+)', ({ params }) => ok(params.id));
+
+// Matches hex colors
+builder.addGet('/color/:hex(^([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$)', ({ params }) => ok(params.hex));
+```
+
+#### 3. Matching Priority
+When multiple routes could match a path, the router follows a deterministic priority order:
+1. **Static Match** (e.g., `/p/static`)
+2. **Regex Match** (e.g., `/p/:id(\\d+)`)
+3. **Param Match** (e.g., `/p/:id`)
+4. **Wildcard Match** (e.g., `/p/*`)
+5. **Catch-all Match** (e.g., `/**`)
+
+### 🛡️ Middleware & Security
+
+`astro-routify` provides a powerful middleware system and built-in security helpers.
+
+#### 1. Middleware Support
+Middleware can be applied globally, to groups, or to individual routes.
+
+```ts
+const builder = new RouterBuilder();
+
+// Global middleware
+builder.use(async (ctx, next) => {
+    const start = performance.now();
+    const res = await next();
+    console.log(`Duration: ${performance.now() - start}ms`);
+    return res;
+});
+
+// Group middleware
+builder.group('/admin')
+    .use(checkAuth)
+    .addGet('/dashboard', (ctx) => ok('Admin only'));
+
+// Route middleware
+builder.addPost('/user', validate(UserSchema), (ctx) => {
+    return ok(ctx.data.body);
+});
+```
+
+#### 2. Request Validation
+Built-in `validate()` middleware works with Zod, Valibot, or any library implementing a `safeParse` method.
+
+```ts
+import { validate } from 'astro-routify';
+import { z } from 'zod';
+
+const UserSchema = z.object({
+    name: z.string(),
+    email: z.string().email()
+});
+
+builder.addPost('/register', validate({ body: UserSchema }), (ctx) => {
+    const user = ctx.data.body; // Fully typed if using TypeScript correctly
+    return ok(user);
+});
+```
+
+#### 3. Security Middlewares (CORS & Headers)
+Protect your API with `cors()` and `securityHeaders()`.
+
+```ts
+import { cors, securityHeaders } from 'astro-routify';
+
+builder.use(cors({ origin: 'https://example.com' }));
+builder.use(securityHeaders());
+```
+
+### 🛠 Advanced Configuration
+
+#### Centralized Error Handling
+Handle all API errors in one place:
+
+```ts
+export const ALL = createRouter({
+    onError: (err, ctx) => {
+        console.error(err);
+        return json({ error: 'Something went wrong' }, 500);
+    }
+});
+```
+
+#### OpenAPI (Swagger) Generation
+Automatically generate API documentation:
+
+```ts
+import { generateOpenAPI } from 'astro-routify';
+
+const router = builder.build();
+const spec = generateOpenAPI(router, {
+    title: 'My API',
+    version: '1.0.0'
+});
+
+// Serve the spec
+builder.addGet('/openapi.json', () => ok(spec));
+```
+
 > 🧠 `defineRouter()` supports all HTTP methods — but Astro only executes the method you export (`GET`, `POST`, etc.)
 
 ### `RouterBuilder` (Catch-All & Fluent Builder)
@@ -130,18 +253,112 @@ builder
 export const ALL = builder.build();
 ```
 
-You can also group routes:
+#### 🏗 Vertical Slices & Auto-Discovery
+
+To avoid a long list of manual registrations, you can use `addModules` combined with Vite's `import.meta.glob`. This allows
+you to define routes anywhere in your project (near your components) and have them automatically registered.
+
+```ts
+// src/pages/api/[...all].ts
+import { RouterBuilder, createRouter } from 'astro-routify';
+
+// 1. Using the builder
+const builder = new RouterBuilder();
+builder.addModules(import.meta.glob('../../**/*.routes.ts', { eager: true }));
+export const ALL = builder.build();
+
+// 2. Or using the one-liner helper
+export const ALL = createRouter(
+    import.meta.glob('../../**/*.routes.ts', { eager: true }),
+    { debug: true } // optional: enable match logging
+);
+```
+
+#### 🛡️ Agnostic Auto-Registration (Global Registry)
+
+If you want to avoid passing glob results or knowing the relative path to your routes, you can use the **global registry**. By setting the `autoRegister` flag or using **decorators**, routes will register themselves as soon as their module is loaded.
+
+##### 1. Enable Auto-Registration in your routes
+
+```ts
+// src/components/User/User.routes.ts
+import { defineRoute, defineGroup, ok, Get } from 'astro-routify';
+
+// Option A: Using the flag
+export const GET_USER = defineRoute('GET', '/users/:id', ({params}) => ok({id: params.id}), true);
+
+// Option B: Using a group flag
+defineGroup('/admin', (g) => {
+    g.addGet('/stats', () => ok({}));
+}, true);
+
+// Option C: Using Decorators (requires experimentalDecorators: true)
+class UserRoutes {
+    @Get('/profile')
+    static getProfile() { return ok({ name: 'Alex' }); }
+}
+```
+
+##### 2. Initialize the router agnostically
+
+In your catch-all endpoint, simply call `import.meta.glob` to trigger the loading of your route files, and then call `createRouter()` without module arguments.
+
+```ts
+// src/pages/api/[...all].ts
+import { createRouter } from 'astro-routify';
+
+// Trigger loading of all route files (agnostic of relative path using /src root alias)
+import.meta.glob('/src/**/*.routes.ts', { eager: true });
+
+// createRouter() will automatically include all auto-registered routes
+export const ALL = createRouter({ debug: true });
+```
+
+You can also use the global `RouterBuilder` instance directly:
+
+```ts
+import { RouterBuilder } from 'astro-routify';
+import.meta.glob('/src/**/*.routes.ts', { eager: true });
+
+export const ALL = RouterBuilder.global.build();
+```
+
+You can also still manually add routes or groups:
 
 ```ts
 const users = defineGroup("/users")
     .addGet("/:id", ({params}) => ok({id: params.id}));
 
 builder.addGroup(users);
+builder.addGet("/ping", () => ok("pong"));
 ```
 
 > 🔁 While `.register()` is still available, it's **deprecated** in favor of `.addGroup()` and `.addRoute()` for better
 > structure and reusability.
 
+Your route files can export single routes, groups, or arrays:
+
+```ts
+// src/components/User/UserList.routes.ts
+import { defineRoute, defineGroup, ok } from 'astro-routify';
+
+export const GET = defineRoute('GET', '/users', () => ok([]));
+
+export const AdminRoutes = defineGroup('/admin')
+    .addPost('/reset', () => ok('done'));
+```
+
+#### 🛠 Development & Debugging
+
+`astro-routify` provides built-in logging to help you see your route table during development.
+
+- **Auto-logging**: In development mode (`NODE_ENV=development`), `RouterBuilder` automatically prints the registered routes to the console when `build()` is called.
+- **Match Tracing**: Set `debug: true` in `RouterOptions` to see a log of every incoming request and which route it matched (or why it failed with 404/405).
+
+```ts
+const router = new RouterBuilder({ debug: true });
+```
+
 ---
 
 ## 🔁 Response Helpers

package/dist/core/RouteTrie.d.ts

@@ -1,14 +1,15 @@
 import { HttpMethod } from './HttpMethod';
-import type { Handler } from './defineHandler';
+import type { Route } from './defineRoute';
 interface RouteMatch {
-    handler: Handler | null;
+    route: Route | null;
     allowed?: HttpMethod[];
     params: Record<string, string | undefined>;
 }
 export declare class RouteTrie {
     private readonly root;
-    insert(path: string, method: HttpMethod, handler: Handler): void;
+    insert(route: Route): void;
     find(path: string, method: HttpMethod): RouteMatch;
+    private matchNode;
     private segmentize;
 }
 export {};

package/dist/core/RouteTrie.js

@@ -1,56 +1,125 @@
 export class RouteTrie {
     constructor() {
-        this.root = { children: new Map(), handlers: new Map() };
+        this.root = { children: new Map(), routes: new Map() };
     }
-    insert(path, method, handler) {
-        const segments = this.segmentize(path);
+    insert(route) {
+        if (!route || typeof route.path !== 'string') {
+            return;
+        }
+        const segments = this.segmentize(route.path);
         let node = this.root;
         for (const segment of segments) {
-            if (segment.startsWith(':')) {
-                if (!node.paramChild) {
-                    node.paramChild = {
-                        children: new Map(),
-                        handlers: new Map(),
-                        paramName: segment.slice(1),
-                    };
+            if (segment === '**') {
+                if (!node.catchAllChild) {
+                    node.catchAllChild = { children: new Map(), routes: new Map() };
+                }
+                node = node.catchAllChild;
+                break;
+            }
+            else if (segment === '*') {
+                if (!node.wildcardChild) {
+                    node.wildcardChild = { children: new Map(), routes: new Map() };
+                }
+                node = node.wildcardChild;
+            }
+            else if (segment.startsWith(':')) {
+                const regexMatch = segment.match(/^:([a-zA-Z0-9_]+)\((.*)\)$/);
+                if (regexMatch) {
+                    const paramName = regexMatch[1];
+                    const regexStr = regexMatch[2];
+                    if (!node.regexChildren)
+                        node.regexChildren = [];
+                    let regexNode = node.regexChildren.find((rc) => rc.regex.source === regexStr && rc.paramName === paramName)?.node;
+                    if (!regexNode) {
+                        regexNode = { children: new Map(), routes: new Map() };
+                        node.regexChildren.push({
+                            regex: new RegExp(regexStr),
+                            paramName,
+                            node: regexNode,
+                        });
+                    }
+                    node = regexNode;
+                }
+                else {
+                    const paramName = segment.slice(1);
+                    if (!node.paramChild) {
+                        node.paramChild = { children: new Map(), routes: new Map(), paramName };
+                    }
+                    node = node.paramChild;
                 }
-                node = node.paramChild;
             }
             else {
                 if (!node.children.has(segment)) {
-                    node.children.set(segment, { children: new Map(), handlers: new Map() });
+                    node.children.set(segment, { children: new Map(), routes: new Map() });
                 }
                 node = node.children.get(segment);
             }
         }
-        node.handlers.set(method, handler);
+        node.routes.set(route.method, route);
     }
     find(path, method) {
         const segments = this.segmentize(path);
-        let node = this.root;
-        const params = {};
-        for (const segment of segments) {
-            if (node?.children.has(segment)) {
-                node = node.children.get(segment);
+        return this.matchNode(this.root, segments, 0, method);
+    }
+    matchNode(node, segments, index, method) {
+        if (index === segments.length) {
+            let route = node.routes.get(method) ?? null;
+            let allowed = route ? undefined : [...node.routes.keys()];
+            // If no route here, check if there's a catch-all that matches "empty" remaining
+            if (!route && node.catchAllChild) {
+                route = node.catchAllChild.routes.get(method) ?? null;
+                allowed = route ? undefined : [...node.catchAllChild.routes.keys()];
             }
-            else if (node?.paramChild) {
-                params[node.paramChild.paramName] = segment;
-                node = node.paramChild;
+            return { route, allowed, params: {} };
+        }
+        const segment = segments[index];
+        // 1. Static Match
+        const staticChild = node.children.get(segment);
+        if (staticChild) {
+            const match = this.matchNode(staticChild, segments, index + 1, method);
+            if (match.route || (match.allowed && match.allowed.length > 0))
+                return match;
+        }
+        // 2. Regex Match
+        if (node.regexChildren) {
+            for (const rc of node.regexChildren) {
+                if (rc.regex.test(segment)) {
+                    const match = this.matchNode(rc.node, segments, index + 1, method);
+                    if (match.route || (match.allowed && match.allowed.length > 0)) {
+                        match.params[rc.paramName] = segment;
+                        return match;
+                    }
+                }
             }
-            else {
-                return { handler: null, params };
+        }
+        // 3. Param Match
+        if (node.paramChild) {
+            const match = this.matchNode(node.paramChild, segments, index + 1, method);
+            if (match.route || (match.allowed && match.allowed.length > 0)) {
+                match.params[node.paramChild.paramName] = segment;
+                return match;
             }
         }
-        if (!node)
-            return { handler: null, params };
-        const handler = node.handlers.get(method) ?? null;
-        return {
-            handler,
-            allowed: handler ? undefined : [...node.handlers.keys()],
-            params,
-        };
+        // 4. Wildcard Match (*)
+        if (node.wildcardChild) {
+            const match = this.matchNode(node.wildcardChild, segments, index + 1, method);
+            if (match.route || (match.allowed && match.allowed.length > 0))
+                return match;
+        }
+        // 5. Catch-all Match (**)
+        if (node.catchAllChild) {
+            const route = node.catchAllChild.routes.get(method) ?? null;
+            return {
+                route,
+                allowed: route ? undefined : [...node.catchAllChild.routes.keys()],
+                params: {},
+            };
+        }
+        return { route: null, params: {} };
     }
     segmentize(path) {
-        return path.replace(/(^\/|\/$)/g, '').split('/');
+        if (typeof path !== 'string')
+            return [];
+        return path.split('/').filter(Boolean);
     }
 }

package/dist/core/RouterBuilder.d.ts

@@ -1,7 +1,8 @@
+import type { APIRoute } from 'astro';
 import { type Route } from './defineRoute';
 import { type RouterOptions } from './defineRouter';
 import { RouteGroup } from './defineGroup';
-import { type Handler } from './defineHandler';
+import { type Middleware } from './defineHandler';
 /**
  * A fluent builder for creating and composing API routes in Astro.
  *
@@ -27,12 +28,72 @@ import { type Handler } from './defineHandler';
  *
  * 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 declare class RouterBuilder {
     private _options;
     private _routes;
+    private _groups;
+    private _middlewares;
+    private _shouldLog;
     private static _registerWarned;
+    /**
+     * A global RouterBuilder instance for easy, centralized route registration.
+     */
+    static readonly global: RouterBuilder;
     constructor(options?: RouterOptions);
+    /**
+     * Adds a global middleware to all routes registered in this builder.
+     *
+     * @param middleware - The middleware function.
+     * @returns The current builder instance.
+     */
+    use(middleware: Middleware): 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: string, configure?: (group: RouteGroup) => void): RouteGroup;
+    /**
+     * Adds all routes and groups that have been auto-registered via `defineRoute(..., true)`
+     * or `defineGroup(..., true)`.
+     *
+     * @returns The current builder instance.
+     */
+    addRegistered(): 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: Record<string, any>): this;
+    /**
+     * Prints all registered routes to the console.
+     * Useful for debugging during development.
+     *
+     * @returns The current builder instance.
+     */
+    logRoutes(): this;
+    /**
+     * Disables the automatic logging of routes that happens in development mode.
+     *
+     * @returns The current builder instance.
+     */
+    disableLogging(): this;
     /**
      * @deprecated Prefer `addGroup()` or `addRoute()` for structured routing.
      *
@@ -71,39 +132,39 @@ export declare class RouterBuilder {
     /**
      * 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: string, handler: Handler): this;
+    addGet(path: string, ...handlers: any[]): this;
     /**
      * 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: string, handler: Handler): this;
+    addPost(path: string, ...handlers: any[]): this;
     /**
      * 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: string, handler: Handler): this;
+    addPut(path: string, ...handlers: any[]): this;
     /**
      * 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: string, handler: Handler): this;
+    addDelete(path: string, ...handlers: any[]): this;
     /**
      * 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: string, handler: Handler): this;
+    addPatch(path: string, ...handlers: any[]): this;
     /**
      * 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).
      */
     private add;
@@ -115,5 +176,27 @@ export declare class RouterBuilder {
      *
      * @returns A fully resolved Astro route handler.
      */
-    build(): import("astro").APIRoute;
+    build(): APIRoute;
 }
+/**
+ * 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 declare function createRouter(modulesOrOptions?: Record<string, any> | RouterOptions, options?: RouterOptions): APIRoute;