astro-routify 1.2.2 → 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,14 +137,33 @@ endpoint system.
 
 ### `defineRoute()`
 
-Declare a single route:
+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(HttpMethod.GET, "/users/:id", ({params}) => {
-    return 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:
@@ -110,11 +174,115 @@ 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). **Must be at the end of the path.**
+  - Captures the remaining path into `ctx.params['*']`.
+
+```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)`.
+
+> ⚠️ **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));
+
+// 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.state.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.state.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());
+```
+
+### 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);
+    }
+});
+```
+
 > 🧠 `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
@@ -130,47 +298,136 @@ builder
 export const ALL = builder.build();
 ```
 
-You can also group routes:
+## 📂 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
-const users = defineGroup("/users")
-    .addGet("/:id", ({params}) => ok({id: params.id}));
+// src/pages/api/[...all].ts
+import { RouterBuilder, createRouter } from 'astro-routify';
 
-builder.addGroup(users);
+// 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
+);
 ```
 
-> 🔁 While `.register()` is still available, it's **deprecated** in favor of `.addGroup()` and `.addRoute()` for better
-> structure and reusability.
+### 🛡️ 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.
 
-## 🔁 Response Helpers
+##### 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 (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)
 
-Avoid boilerplate `new Response(JSON.stringify(...))`:
+The `createRouter` helper is the easiest way to get started. It automatically picks up everything from the global registry.
 
 ```ts
-import {fileResponse} from 'astro-routify';
+// src/pages/api/[...slug].ts
+import { createRouter } from 'astro-routify';
 
-ok(data);                   // 200 OK
-created(data);              // 201 Created
-noContent();                // 204
-notFound("Missing");        // 404
-internalError(err);         // 500
+// 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 });
+
+// 2. createRouter() will automatically pick up everything.
+export const ALL = createRouter({ 
+    debug: true,
+    basePath: '/api' 
+});
 ```
 
-### 📄 File downloads
+###### 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
-fileResponse(content, "application/pdf", "report.pdf"); // sets Content-Type and Content-Disposition
+// 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 });
+
+// 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
+const users = defineGroup("/users")
+    .addGet("/:id", ({params}) => ok({id: params.id}));
+
+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);
 
@@ -208,6 +465,79 @@ streamJsonArray('/items', async ({response}) => {
 
 ```
 
+### 📖 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.
+
+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
+
+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';
+
+ok(data);                   // 200 OK
+created(data);              // 201 Created
+noContent();                // 204
+notFound("Missing");        // 404
+internalError(err);         // 500
+```
+
+### 📄 File downloads
+
+```ts
+fileResponse(content, "application/pdf", "report.pdf"); // sets Content-Type and Content-Disposition
+```
+
+---
+
 ---
 
 ## 🔍 Param Matching
@@ -349,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.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 {};