astro-routify 1.4.0 → 1.5.0

package/README.md

@@ -16,6 +16,21 @@ Define API routes using clean, flat structures — no folders or boilerplate log
 npm install astro-routify
 ```
 
+## 📋 Contents
+- [Installing](#installing)
+- [Quickstart](#quickstart)
+- [Mental Model](#mental-model)
+- [Which API should I use?](#which-api-should-i-use)
+- [Core Concepts](#core-concepts)
+- [Advanced Matching](#advanced-matching)
+- [Middleware & Security](#middleware--security)
+- [Single-entry Routing](#single-entry-routing)
+- [Auto-Discovery & Scaling](#auto-discovery--scaling)
+- [Advanced Features](#advanced-features)
+- [Response Helpers](#response-helpers)
+- [Performance](#performance)
+- [Non-goals](#non-goals)
+
 ## ⚡️ Quickstart
 
 ```ts
@@ -55,6 +70,40 @@ builder
 export const ALL = builder.build(); // catch-all
 ```
 
+## 🧠 Mental Model
+
+`astro-routify` compiles your route definitions into a **Trie (prefix tree)** at startup.
+At runtime, each request performs a deterministic path + method lookup and executes the matched handler inside Astro’s native API context.
+
+```text
+[Astro Endpoint]
+       |
+   astro-routify
+       |
+   Route Trie
+       |
+    Handler
+```
+
+> ⚡ **Cold-start performance**: Routes are compiled once at startup; there is no per-request route parsing. This makes it ideal for edge and serverless environments.
+
+### Which API should I use?
+
+| Use case | Recommended |
+|----------|-------------|
+| Small / explicit APIs | `defineRouter()` |
+| Single-entry / catch-all | `RouterBuilder` |
+| Vertical slices (glob) | `addModules()` |
+| Large apps / plugins | Global registry |
+
+### 🏗 Trie Invariants
+For architectural stability and predictable performance, the following invariants are enforced:
+- **Single Dynamic Branching**: A node has at most one dynamic parameter child (`paramChild`).
+- **Unified Param Node**: The `paramChild` represents *any* `:param` at that depth; parameter names are bound from route-specific metadata during matching.
+- **Structural Identity**: Two routes differing only by parameter name (e.g., `/u/:id` and `/u/:slug`) are considered structurally identical.
+- **Deterministic Match Order**: Static > Regex (sorted by specificity) > Param > Wildcard > Catch-all.
+- **Terminal Catch-all**: `**` matches are only allowed as the final segment.
+
 ## 💡 Full Example
 
 You can find an implementation example in the [astro-routify-example](https://github.com/oamm/astro-routify-example)
@@ -76,14 +125,10 @@ endpoint system.
 - 🧩 Use middleware, access cookies, headers, and request bodies exactly as you would in a normal Astro endpoint.
 - ✅ Flat-file, code-based routing (no folders required)
 - ✅ Dynamic segments (`:id`)
-- ✅ ALL-mode for monolithic routing (`RouterBuilder`)
+- ✅ ALL-mode for single-entry routing (`RouterBuilder`)
 - ✅ Built-in response helpers (`ok`, `created`, etc.)
 - ✅ Trie-based matcher for fast route lookup
 - ✅ Fully typed — no magic strings
-- 🔁 **Streaming support**
-    - `stream()` — raw streaming with backpressure support (e.g. SSE, logs, custom protocols)
-    - `streamJsonND()` — newline-delimited JSON streaming (NDJSON)
-    - `streamJsonArray()` — server-side streamed JSON arrays
 
 > 🔄 See [CHANGELOG.md](./CHANGELOG.md) for recent updates and improvements.
 ---
@@ -92,18 +137,33 @@ endpoint system.
 
 ### `defineRoute()`
 
-Declare a single route. Now supports middlewares and metadata:
+Declare a single route. Now supports middlewares and metadata. 
+
+> 💡 `defineRoute` supports two signatures: you can pass a full `Route` object, or specify `method`, `path`, and `handler` as separate arguments.
+
+### `RoutifyContext` & `Context`
+
+The context object passed to handlers and middlewares extends Astro's `APIContext`. For better ergonomics, you can use the `Context` type alias:
 
 ```ts
-defineRoute({
-    method: 'GET',
-    path: '/users/:id',
-    middlewares: [authMiddleware],
-    metadata: { summary: 'Get user by ID' },
-    handler: ({params}) => ok({userId: params.id})
-});
+import { type Context } from 'astro-routify';
+
+const handler = (ctx: Context) => ok('hello');
 ```
 
+Properties include:
+
+- `params`: Route parameters (e.g., `:id`). Matching and capture operate on **decoded** path segments. Decoding occurs exactly once per segment prior to matching.
+- `query`: A read-only snapshot of parsed query parameters. Supports multi-value keys (`string | string[]`).
+- `searchParams`: The raw `URLSearchParams` object. Note: Mutations to `searchParams` do not reflect in `ctx.query`.
+- `state`: A shared object container for passing data between middlewares and handlers.
+
+#### Path normalization & basePath stripping
+- `basePath` stripping occurs before decoding and normalization.
+- Stripping happens only on segment boundaries (e.g., `/api/users` matches, `/apiusers` does not).
+- Trailing slashes are normalized by segmentization; `/users` and `/users/` are equivalent.
+- All matching and parameter capture operate on decoded segments.
+
 ### `defineRouter()`
 
 Group multiple routes under one HTTP method handler:
@@ -120,7 +180,8 @@ export const GET = defineRouter([
 
 #### 1. Wildcards
 - `*` matches exactly one segment.
-- `**` matches zero or more segments (catch-all).
+- `**` matches zero or more segments (catch-all). **Must be at the end of the path.**
+  - Captures the remaining path into `ctx.params['*']`.
 
 ```ts
 builder.addGet('/files/*/download', () => ok('one segment'));
@@ -130,6 +191,8 @@ builder.addGet('/static/**', () => ok('all segments'));
 #### 2. Regex Constraints
 You can constrain parameters using regex by wrapping the pattern in parentheses: `:param(regex)`.
 
+> ⚠️ **Specificity Note**: Regex sorting is deterministic (longer pattern first) but heuristic. Users should avoid overlapping regex constraints at the same depth.
+
 ```ts
 // Matches only numeric IDs
 builder.addGet('/users/:id(\\d+)', ({ params }) => ok(params.id));
@@ -171,7 +234,7 @@ builder.group('/admin')
 
 // Route middleware
 builder.addPost('/user', validate(UserSchema), (ctx) => {
-    return ok(ctx.data.body);
+    return ok(ctx.state.body);
 });
 ```
 
@@ -188,7 +251,7 @@ const UserSchema = z.object({
 });
 
 builder.addPost('/register', validate({ body: UserSchema }), (ctx) => {
-    const user = ctx.data.body; // Fully typed if using TypeScript correctly
+    const user = ctx.state.body; // Fully typed if using TypeScript correctly
     return ok(user);
 });
 ```
@@ -203,9 +266,7 @@ builder.use(cors({ origin: 'https://example.com' }));
 builder.use(securityHeaders());
 ```
 
-### 🛠 Advanced Configuration
-
-#### Centralized Error Handling
+### Centralized Error Handling
 Handle all API errors in one place:
 
 ```ts
@@ -217,27 +278,11 @@ export const ALL = createRouter({
 });
 ```
 
-#### 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)
+## 🧱 Single-entry Routing
 
-Use `RouterBuilder` when you want to build routes dynamically, catch all HTTP methods via `ALL`, or organize routes more
+Use `RouterBuilder` when you want to build routes dynamically, catch-all HTTP methods via `ALL`, or organize routes more
 fluently with helpers.
 
 ```ts
@@ -253,11 +298,13 @@ builder
 export const ALL = builder.build();
 ```
 
-#### 🏗 Vertical Slices & Auto-Discovery
+## 📂 Auto-Discovery & Scaling
 
 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.
 
+> 💡 When passing the glob result directly to the router, you **don't** need to set `autoRegister: true` in your routes. The router will automatically discover all exported routes from the modules.
+
 ```ts
 // src/pages/api/[...all].ts
 import { RouterBuilder, createRouter } from 'astro-routify';
@@ -274,7 +321,7 @@ export const ALL = createRouter(
 );
 ```
 
-#### 🛡️ Agnostic Auto-Registration (Global Registry)
+### 🛡️ 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.
 
@@ -301,28 +348,60 @@ class UserRoutes {
 
 ##### 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.
+In your catch-all endpoint (e.g., `src/pages/api/[...slug].ts`), you need to trigger the loading of your route files.
+
+> **Why is the glob needed?**
+> Even with auto-registration, Vite only executes files that are explicitly imported. The `import.meta.glob` call below tells Vite to find and execute your route files so they can register themselves in the global registry. Without this, the registry would remain empty.
+
+###### Using `createRouter()` (Recommended)
+
+The `createRouter` helper is the easiest way to get started. It automatically picks up everything from the global registry.
 
 ```ts
-// src/pages/api/[...all].ts
+// src/pages/api/[...slug].ts
 import { createRouter } from 'astro-routify';
 
-// Trigger loading of all route files (agnostic of relative path using /src root alias)
+// 1. Trigger loading of all route files.
+// We don't need to pass the result to createRouter, but we must call it.
 import.meta.glob('/src/**/*.routes.ts', { eager: true });
 
-// createRouter() will automatically include all auto-registered routes
-export const ALL = createRouter({ debug: true });
+// 2. createRouter() will automatically pick up everything.
+export const ALL = createRouter({ 
+    debug: true,
+    basePath: '/api' 
+});
 ```
 
-You can also use the global `RouterBuilder` instance directly:
+###### Using `RouterBuilder`
+
+If you need more control, you can use `RouterBuilder` manually. You must explicitly call `.addRegistered()` to pull in routes from the global registry.
 
 ```ts
-import { RouterBuilder } from 'astro-routify';
+// src/pages/api/[...slug].ts
+import { RouterBuilder, notFound, internalError } from 'astro-routify';
+
+// 1. Load your routes
+// This triggers Vite to execute the files and populate the global registry.
 import.meta.glob('/src/**/*.routes.ts', { eager: true });
 
-export const ALL = RouterBuilder.global.build();
+// 2. Construct the builder with optional configuration
+const builder = new RouterBuilder({ 
+    basePath: '/api',
+    debug: true, // Enable logging
+    onNotFound: () => notFound('Custom 404'),
+    onError: (err) => internalError(err)
+});
+
+// 3. Add auto-registered routes and build
+export const ALL = builder
+    .addRegistered()
+    .build();
 ```
 
+> 💡 **The Catch-All Slug**: The filename `[...slug].ts` tells Astro to match any path under that directory. For example, if placed in `src/pages/api/[...slug].ts`, it matches `/api/users`, `/api/ping`, etc. `astro-routify` then takes over and matches the rest of the path against your defined routes.
+
+> ⚠️ In production (non-HMR) builds, duplicate route registrations with the same `method:path` MAY emit warnings and the last registration wins. In development/HMR flows, the registry intentionally preserves history and the builder deduplicates using a last-wins policy.
+
 You can also still manually add routes or groups:
 
 ```ts
@@ -333,6 +412,80 @@ builder.addGroup(users);
 builder.addGet("/ping", () => ok("pong"));
 ```
 
+## ⚡ Advanced Features
+
+### 🔄 Streaming responses
+
+#### Lifecycle & Guarantees
+- **Short-circuiting**: Returning a stream result (e.g., from `stream()`) short-circuits the middleware chain; `next()` must not be called after the response starts.
+- **Abort Semantics**: If the client disconnects, the stream closes silently. Any internal controllers are closed via `AbortSignal`. Cleanup hooks should be idempotent.
+
+#### Raw stream (e.g., Server-Sent Events)
+
+`stream()` automatically handles SSE headers and auto-formats string chunks with a `state: ` prefix and double-newlines.
+
+```ts
+stream('/clock', async ({response}) => {
+    const timer = setInterval(() => {
+        // Automatically sent as "state: <iso-date>\n\n"
+        response.write(new Date().toISOString());
+    }, 1000);
+
+    setTimeout(() => {
+        clearInterval(timer);
+        response.close();
+    }, 5000);
+});
+
+```
+
+#### JSON NDStream (newline-delimited)
+
+```ts
+
+streamJsonND('/updates', async ({response}) => {
+    response.send({step: 1});
+    await delay(500);
+    response.send({step: 2});
+    response.close();
+});
+
+```
+
+#### JSON Array stream
+
+```ts
+
+streamJsonArray('/items', async ({response}) => {
+    for (let i = 0; i < 3; i++) {
+        response.send({id: i});
+    }
+    response.close();
+});
+
+```
+
+### 📖 OpenAPI (Swagger) Generation
+
+Automatically generate API documentation from your router instance.
+
+- **Catch-all (`**`)**: Represented as `{rest}` parameter.
+- **Wildcard (`*`)**: Represented as `{any}` parameter.
+- **Regex**: Mapped to a string schema with a `pattern` constraint.
+
+```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));
+```
+
 > 🔁 While `.register()` is still available, it's **deprecated** in favor of `.addGroup()` and `.addRoute()` for better
 > structure and reusability.
 
@@ -363,7 +516,9 @@ const router = new RouterBuilder({ debug: true });
 
 ## 🔁 Response Helpers
 
-Avoid boilerplate `new Response(JSON.stringify(...))`:
+Avoid boilerplate `new Response(JSON.stringify(...))`. 
+
+> 💡 **Header Precedence**: Explicit headers provided via `ResultResponse` (e.g., `ok(data, { 'Content-Type': '...' })`) always take precedence over inferred defaults.
 
 ```ts
 import {fileResponse} from 'astro-routify';
@@ -381,49 +536,7 @@ internalError(err);         // 500
 fileResponse(content, "application/pdf", "report.pdf"); // sets Content-Type and Content-Disposition
 ```
 
-### 🔄 Streaming responses
-
-#### Raw stream (e.g., Server-Sent Events)
-
-```ts
-stream('/clock', async ({response}) => {
-    const timer = setInterval(() => {
-        response.write(new Date().toISOString());
-    }, 1000);
-
-    setTimeout(() => {
-        clearInterval(timer);
-        response.close();
-    }, 5000);
-});
-
-```
-
-#### JSON NDStream (newline-delimited)
-
-```ts
-
-streamJsonND('/updates', async ({response}) => {
-    response.send({step: 1});
-    await delay(500);
-    response.send({step: 2});
-    response.close();
-});
-
-```
-
-#### JSON Array stream
-
-```ts
-
-streamJsonArray('/items', async ({response}) => {
-    for (let i = 0; i < 3; i++) {
-        response.send({id: i});
-    }
-    response.close();
-});
-
-```
+---
 
 ---
 
@@ -566,6 +679,15 @@ Results may vary slightly on different hardware.
 
 ---
 
+## 🎯 Non-goals
+
+- **Not a replacement for Astro pages**: Use it for APIs, not for HTML rendering.
+- **No runtime file watching**: Route discovery happens at startup.
+- **No opinionated auth or ORM layer**: It's a router, not a framework.
+- **No framework lock-in**: Works with any library (Zod, Valibot, etc.).
+
+---
+
 ## 🛠 Designed to Scale
 
 While focused on simplicity and speed today, `astro-routify` is designed to evolve — enabling more advanced routing

package/dist/core/RouteTrie.js

@@ -6,9 +6,11 @@ export class RouteTrie {
         if (!route || typeof route.path !== 'string') {
             return;
         }
-        const segments = this.segmentize(route.path);
+        const segments = this.segmentize(route.path, true);
         let node = this.root;
-        for (const segment of segments) {
+        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() };
@@ -37,13 +39,16 @@ export class RouteTrie {
                             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(), paramName };
+                        node.paramChild = { children: new Map(), routes: new Map() };
                     }
                     node = node.paramChild;
                 }
@@ -55,28 +60,38 @@ export class RouteTrie {
                 node = node.children.get(segment);
             }
         }
-        node.routes.set(route.method, route);
+        node.routes.set(route.method, { route, paramNames });
     }
     find(path, method) {
-        const segments = this.segmentize(path);
-        return this.matchNode(this.root, segments, 0, method);
+        const segments = this.segmentize(path, true);
+        return this.matchNode(this.root, segments, 0, method, {});
     }
-    matchNode(node, segments, index, method) {
+    matchNode(node, segments, index, method, capturedValues) {
         if (index === segments.length) {
-            let route = node.routes.get(method) ?? null;
-            let allowed = route ? undefined : [...node.routes.keys()];
+            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 (!route && node.catchAllChild) {
-                route = node.catchAllChild.routes.get(method) ?? null;
-                allowed = route ? undefined : [...node.catchAllChild.routes.keys()];
+            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: { '*': '' } };
+                }
+            }
+            if (info) {
+                const params = {};
+                for (const [depth, name] of Object.entries(info.paramNames)) {
+                    params[name] = capturedValues[Number(depth)];
+                }
+                return { route: info.route, params };
             }
-            return { route, allowed, 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);
+            const match = this.matchNode(staticChild, segments, index + 1, method, capturedValues);
             if (match.route || (match.allowed && match.allowed.length > 0))
                 return match;
         }
@@ -84,7 +99,7 @@ export class RouteTrie {
         if (node.regexChildren) {
             for (const rc of node.regexChildren) {
                 if (rc.regex.test(segment)) {
-                    const match = this.matchNode(rc.node, segments, index + 1, method);
+                    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;
@@ -94,32 +109,45 @@ export class RouteTrie {
         }
         // 3. Param Match
         if (node.paramChild) {
-            const match = this.matchNode(node.paramChild, segments, index + 1, method);
+            capturedValues[index] = segment;
+            const match = this.matchNode(node.paramChild, segments, index + 1, method, capturedValues);
             if (match.route || (match.allowed && match.allowed.length > 0)) {
-                match.params[node.paramChild.paramName] = segment;
                 return match;
             }
+            delete capturedValues[index];
         }
         // 4. Wildcard Match (*)
         if (node.wildcardChild) {
-            const match = this.matchNode(node.wildcardChild, segments, index + 1, method);
+            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 route = node.catchAllChild.routes.get(method) ?? null;
+            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,
-                allowed: route ? undefined : [...node.catchAllChild.routes.keys()],
-                params: {},
+                route: info ? info.route : null,
+                allowed: info ? undefined : [...node.catchAllChild.routes.keys()],
+                params,
             };
         }
         return { route: null, params: {} };
     }
-    segmentize(path) {
+    segmentize(path, decode = false) {
         if (typeof path !== 'string')
             return [];
-        return path.split('/').filter(Boolean);
+        const segments = path.split('/').filter(Boolean);
+        return decode ? segments.map(s => {
+            try {
+                return decodeURIComponent(s);
+            }
+            catch {
+                return s;
+            }
+        }) : segments;
     }
 }

package/dist/core/RouterBuilder.js

@@ -1,6 +1,6 @@
 import { defineRoute, isRoute } from './defineRoute';
 import { defineRouter } from './defineRouter';
-import { defineGroup, RouteGroup } from './defineGroup';
+import { defineGroup } from './defineGroup';
 import { HttpMethod } from './HttpMethod';
 import { globalRegistry } from './registry';
 /**
@@ -81,12 +81,33 @@ export class RouterBuilder {
      * @returns The current builder instance.
      */
     addRegistered() {
-        globalRegistry.getItems().forEach((item) => {
-            if (item instanceof RouteGroup) {
-                this.addGroup(item);
+        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)) {
-                this.addRoute(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;
@@ -101,8 +122,9 @@ export class RouterBuilder {
      * @returns The current builder instance.
      */
     addModules(modules) {
-        Object.values(modules).forEach((m) => {
-            if (m instanceof RouteGroup) {
+        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)) {
@@ -110,7 +132,7 @@ export class RouterBuilder {
             }
             else if (typeof m === 'object' && m !== null) {
                 Object.values(m).forEach((val) => {
-                    if (val instanceof RouteGroup) {
+                    if (val && typeof val === 'object' && val._routifyType === 'group') {
                         this.addGroup(val);
                     }
                     else if (isRoute(val)) {
@@ -121,7 +143,7 @@ export class RouterBuilder {
                             if (isRoute(item)) {
                                 this.addRoute(item);
                             }
-                            else if (item instanceof RouteGroup) {
+                            else if (item && typeof item === 'object' && item._routifyType === 'group') {
                                 this.addGroup(item);
                             }
                         });
@@ -280,6 +302,17 @@ export class RouterBuilder {
         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,