astro-routify 1.2.2 → 1.5.0

package/dist/core/RouteTrie.js

@@ -1,56 +1,153 @@
 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, true);
         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),
-                    };
+        const paramNames = {};
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            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,
+                        });
+                        // Sort regex by specificity (longer source first)
+                        node.regexChildren.sort((a, b) => b.regex.source.length - a.regex.source.length);
+                    }
+                    node = regexNode;
+                }
+                else {
+                    const paramName = segment.slice(1);
+                    paramNames[i] = paramName;
+                    if (!node.paramChild) {
+                        node.paramChild = { children: new Map(), routes: new Map() };
+                    }
+                    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, paramNames });
     }
     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);
+        const segments = this.segmentize(path, true);
+        return this.matchNode(this.root, segments, 0, method, {});
+    }
+    matchNode(node, segments, index, method, capturedValues) {
+        if (index === segments.length) {
+            let info = node.routes.get(method) ?? null;
+            let allowed = info ? undefined : [...node.routes.keys()];
+            // If no route here, check if there's a catch-all that matches "empty" remaining
+            if (!info && node.catchAllChild) {
+                info = node.catchAllChild.routes.get(method) ?? null;
+                allowed = info ? undefined : [...node.catchAllChild.routes.keys()];
+                if (info) {
+                    return { route: info.route, allowed, params: { '*': '' } };
+                }
             }
-            else if (node?.paramChild) {
-                params[node.paramChild.paramName] = segment;
-                node = node.paramChild;
+            if (info) {
+                const params = {};
+                for (const [depth, name] of Object.entries(info.paramNames)) {
+                    params[name] = capturedValues[Number(depth)];
+                }
+                return { route: info.route, params };
             }
-            else {
-                return { handler: null, params };
+            return { route: null, 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, capturedValues);
+            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, capturedValues);
+                    if (match.route || (match.allowed && match.allowed.length > 0)) {
+                        match.params[rc.paramName] = segment;
+                        return match;
+                    }
+                }
+            }
+        }
+        // 3. Param Match
+        if (node.paramChild) {
+            capturedValues[index] = segment;
+            const match = this.matchNode(node.paramChild, segments, index + 1, method, capturedValues);
+            if (match.route || (match.allowed && match.allowed.length > 0)) {
+                return match;
             }
+            delete capturedValues[index];
+        }
+        // 4. Wildcard Match (*)
+        if (node.wildcardChild) {
+            const match = this.matchNode(node.wildcardChild, segments, index + 1, method, capturedValues);
+            if (match.route || (match.allowed && match.allowed.length > 0))
+                return match;
+        }
+        // 5. Catch-all Match (**)
+        if (node.catchAllChild) {
+            const info = node.catchAllChild.routes.get(method) ?? null;
+            const params = {};
+            // Capture the rest of the path
+            const remainder = segments.slice(index).join('/');
+            params['*'] = remainder;
+            return {
+                route: info ? info.route : null,
+                allowed: info ? undefined : [...node.catchAllChild.routes.keys()],
+                params,
+            };
         }
-        if (!node)
-            return { handler: null, params };
-        const handler = node.handlers.get(method) ?? null;
-        return {
-            handler,
-            allowed: handler ? undefined : [...node.handlers.keys()],
-            params,
-        };
+        return { route: null, params: {} };
     }
-    segmentize(path) {
-        return path.replace(/(^\/|\/$)/g, '').split('/');
+    segmentize(path, decode = false) {
+        if (typeof path !== 'string')
+            return [];
+        const segments = path.split('/').filter(Boolean);
+        return decode ? segments.map(s => {
+            try {
+                return decodeURIComponent(s);
+            }
+            catch {
+                return s;
+            }
+        }) : segments;
     }
 }

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;

package/dist/core/RouterBuilder.js

@@ -1,6 +1,8 @@
-import { defineRoute } from './defineRoute';
+import { defineRoute, isRoute } from './defineRoute';
 import { defineRouter } from './defineRouter';
+import { defineGroup } from './defineGroup';
 import { HttpMethod } from './HttpMethod';
+import { globalRegistry } from './registry';
 /**
  * A fluent builder for creating and composing API routes in Astro.
  *
@@ -26,14 +28,156 @@ 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() {
+        const items = globalRegistry.getItems();
+        const lastRouteIndex = new Map();
+        const routesByKey = new Map();
+        const lastGroupIndex = new Map();
+        const groupsByKey = new Map();
+        items.forEach((item, index) => {
+            if (item && typeof item === 'object' && item._routifyType === 'group') {
+                const key = item.getBasePath();
+                lastGroupIndex.set(key, index);
+                groupsByKey.set(key, item);
+            }
+            else if (isRoute(item)) {
+                const key = `${item.method}:${item.path}`;
+                lastRouteIndex.set(key, index);
+                routesByKey.set(key, item);
+            }
+        });
+        items.forEach((item, index) => {
+            if (item && typeof item === 'object' && item._routifyType === 'group') {
+                const key = item.getBasePath();
+                if (lastGroupIndex.get(key) === index)
+                    this.addGroup(groupsByKey.get(key));
+            }
+            else if (isRoute(item)) {
+                const key = `${item.method}:${item.path}`;
+                if (lastRouteIndex.get(key) === index)
+                    this.addRoute(routesByKey.get(key));
+            }
+        });
+        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.keys(modules).sort().forEach((key) => {
+            const m = modules[key];
+            if (m && typeof m === 'object' && m._routifyType === 'group') {
+                this.addGroup(m);
+            }
+            else if (isRoute(m)) {
+                this.addRoute(m);
+            }
+            else if (typeof m === 'object' && m !== null) {
+                Object.values(m).forEach((val) => {
+                    if (val && typeof val === 'object' && val._routifyType === 'group') {
+                        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 && typeof item === 'object' && item._routifyType === 'group') {
+                                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 +217,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 +294,73 @@ 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());
+        }
+        // Detect duplicates in production (warnings)
+        if (!this._shouldLog) {
+            const seen = new Set();
+            for (const route of allRoutes) {
+                const key = `${route.method}:${route.path}`;
+                if (seen.has(key)) {
+                    console.warn(`[RouterBuilder] Duplicate route detected: ${key}. The last one will be used.`);
+                }
+                seen.add(key);
+            }
+        }
+        // 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();
+}