astro-routify 1.2.2 → 1.5.0

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import * as astro from 'astro';
 import { APIContext, APIRoute } from 'astro';
 import { HeadersInit, BodyInit } from 'undici';
 
@@ -16,6 +15,10 @@ declare const ALLOWED_HTTP_METHODS: Set<string>;
  */
 declare function normalizeMethod(method: string): HttpMethod;
 
+/**
+ * Supported types that can be returned from a route handler.
+ */
+type HandlerResult = Response | ResultResponse | string | number | boolean | object | ArrayBuffer | Uint8Array | ReadableStream<Uint8Array> | Blob | FormData | URLSearchParams | null | undefined;
 /**
  * A standardized shape for internal route result objects.
  * These are later converted into native `Response` instances.
@@ -74,14 +77,20 @@ declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) =>
  * 429 Too Many Requests
  */
 declare const tooManyRequests: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * Returns a response with JSON body and specified status.
+ */
+declare const json: (body: any, status?: number, headers?: HeadersInit) => ResultResponse<any>;
 /**
  * 500 Internal Server Error
+ *
+ * In production, you might want to avoid leaking error details.
  */
 declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResponse<string>;
 /**
  * Sends a binary or stream-based file response with optional content-disposition.
  *
- * @param content - The file data (Blob, ArrayBuffer, or stream)
+ * @param content - The file state (Blob, ArrayBuffer, or stream)
  * @param contentType - MIME type of the file
  * @param fileName - Optional download filename
  * @param headers - Optional extra headers
@@ -89,23 +98,55 @@ declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResp
  */
 declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
 /**
- * Converts an internal `ResultResponse` into a native `Response` object
+ * Type guard to detect ReadableStreams, used for streamed/binary responses.
+ *
+ * @param value - Any value to test
+ * @returns True if it looks like a ReadableStream
+ */
+declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
+/**
+ * Converts an internal `ResultResponse` or any `HandlerResult` into a native `Response` object
  * for use inside Astro API routes.
  *
- * Automatically applies `Content-Type: application/json` for object bodies.
+ * Automatically applies appropriate Content-Type headers.
  *
- * @param result - A ResultResponse returned from route handler
+ * @param result - A ResultResponse or other supported type returned from route handler
  * @returns A native Response
  */
-declare function toAstroResponse(result: ResultResponse | undefined): Response;
+declare function toAstroResponse(result: HandlerResult): Response;
 
 /**
- * A flexible route handler that can return:
- * - a native `Response` object,
- * - a structured `ResultResponse` object,
- * - or a file stream (Blob, ArrayBuffer, or ReadableStream).
+ * Enhanced Astro context for Routify.
+ */
+interface RoutifyContext<State = Record<string, any>> extends APIContext {
+    /**
+     * Parsed query parameters from the URL.
+     * Note: If multiple parameters have the same key, only the last one is included.
+     * Use `searchParams` for full multi-value support.
+     */
+    query: Record<string, string | string[]>;
+    /**
+     * Full URLSearchParams object for the incoming request.
+     */
+    searchParams: URLSearchParams;
+    /**
+     * Shared state container for middlewares and handlers (e.g., validation results).
+     * This is where middlewares can store information for subsequent handlers.
+     */
+    state: State;
+}
+/**
+ * Convenience type alias for RoutifyContext.
  */
-type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+type Context<State = Record<string, any>> = RoutifyContext<State>;
+/**
+ * A middleware function that can modify the context or short-circuit the response.
+ */
+type Middleware<State = any> = (ctx: RoutifyContext<State>, next: () => Promise<Response>) => Promise<Response> | Response;
+/**
+ * A flexible route handler that can return various types.
+ */
+type Handler<State = any> = (ctx: RoutifyContext<State>) => Promise<HandlerResult> | HandlerResult;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,
@@ -117,13 +158,6 @@ type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultR
  * @returns An Astro-compatible `APIRoute` function
  */
 declare function defineHandler(handler: Handler): APIRoute;
-/**
- * Type guard to detect ReadableStreams, used for streamed/binary responses.
- *
- * @param value - Any value to test
- * @returns True if it looks like a ReadableStream
- */
-declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
 
 /**
  * Represents a single route definition.
@@ -141,6 +175,19 @@ interface Route {
      * The function that handles the request when matched.
      */
     handler: Handler;
+    /**
+     * Optional array of middlewares to run before the handler.
+     */
+    middlewares?: Middleware[];
+    /**
+     * Optional metadata for the route (e.g. for OpenAPI generation).
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Internal marker to identify the object type during module discovery.
+     * @internal
+     */
+    _routifyType?: 'route';
 }
 /**
  * Defines a route using a `Route` object.
@@ -149,9 +196,10 @@ interface Route {
  * defineRoute({ method: 'GET', path: '/users', handler });
  *
  * @param route - A fully constructed route object
+ * @param autoRegister - If true, registers the route to the global registry
  * @returns The validated Route object
  */
-declare function defineRoute(route: Route): Route;
+declare function defineRoute(route: Route, autoRegister?: boolean): Route;
 /**
  * Defines a route by specifying its method, path, and handler explicitly.
  *
@@ -161,9 +209,24 @@ declare function defineRoute(route: Route): Route;
  * @param method - HTTP method to match
  * @param path - Route path (must start with `/`)
  * @param handler - Function to handle the matched request
+ * @param autoRegister - If true, registers the route to the global registry
  * @returns The validated Route object
  */
-declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;
+declare function defineRoute(method: HttpMethod, path: string, handler: Handler, autoRegister?: boolean): Route;
+/**
+ * Ensures the route is properly formed and uses a valid method + path format.
+ *
+ * @param route - Route to validate
+ * @throws If method is unsupported or path doesn't start with `/`
+ */
+declare function validateRoute({ method, path }: Route): void;
+/**
+ * Checks if an object implements the `Route` interface.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is a valid Route
+ */
+declare function isRoute(obj: any): obj is Route;
 
 /**
  * Optional configuration for the router instance.
@@ -178,6 +241,15 @@ interface RouterOptions {
      * Custom handler to return when no route is matched (404).
      */
     onNotFound?: () => ReturnType<typeof notFound>;
+    /**
+     * If true, enables debug logging for route matching.
+     * Useful during development to trace which route is being matched.
+     */
+    debug?: boolean;
+    /**
+     * Custom error handler for the router.
+     */
+    onError?: (error: unknown, ctx: RoutifyContext) => HandlerResult | Response;
 }
 /**
  * Defines a router that dynamically matches registered routes based on method and path.
@@ -215,8 +287,10 @@ declare function defineRouter(routes: Route[], options?: RouterOptions): APIRout
  *   .addPost('/', createUser);
  */
 declare class RouteGroup {
+    readonly _routifyType = "group";
     private basePath;
     private routes;
+    private middlewares;
     /**
      * Creates a new route group with the specified base path.
      * Trailing slashes are automatically removed.
@@ -228,49 +302,61 @@ declare class RouteGroup {
      * Returns the normalized base path used by the group.
      */
     getBasePath(): string;
+    /**
+     * Adds a middleware to all routes in this group.
+     *
+     * @param middleware - The middleware function to add
+     * @returns The current group instance
+     */
+    use(middleware: Middleware): this;
     /**
      * Registers a GET route under the group's base path.
      *
      * @param path - Path relative to the base path (e.g. "/:id")
-     * @param handler - The handler function for this route
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addGet(path: string, handler: Handler): this;
+    addGet(path: string, ...handlers: any[]): this;
     /**
      * Registers a POST route under the group's base path.
      *
      * @param path - Path relative to the base path
-     * @param handler - The handler function for this route
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPost(path: string, handler: Handler): this;
+    addPost(path: string, ...handlers: any[]): this;
     /**
      * Registers a PUT route under the group's base path.
      *
      * @param path - Path relative to the base path
-     * @param handler - The handler function for this route
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPut(path: string, handler: Handler): this;
+    addPut(path: string, ...handlers: any[]): this;
     /**
      * Registers a DELETE route under the group's base path.
      *
      * @param path - Path relative to the base path
-     * @param handler - The handler function for this route
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addDelete(path: string, handler: Handler): this;
+    addDelete(path: string, ...handlers: any[]): this;
     /**
      * Registers a PATCH route under the group's base path.
      *
      * @param path - Path relative to the base path
-     * @param handler - The handler function for this route
+     * @param handlers - Middleware(s) followed by a handler function
      */
-    addPatch(path: string, handler: Handler): this;
+    addPatch(path: string, ...handlers: any[]): this;
     /**
-     * Internal method to register a route under the group with any HTTP method.
+     * Registers a route under the group's base path.
      *
      * @param method - HTTP verb
-     * @param subPath - Route path relative to the base
-     * @param handler - The handler function for this route
+     * @param path - Path relative to the base path
+     * @param args - Middleware(s) and handler
+     * @returns The current group instance
      */
-    private add;
+    add(method: HttpMethod, path: string, ...args: any[]): this;
+    /**
+     * Registers the group and all its current routes to the global registry.
+     */
+    register(): this;
     /**
      * Returns all the registered routes in the group.
      */
@@ -281,23 +367,25 @@ declare class RouteGroup {
  *
  * @param basePath - The base path prefix for all routes
  * @param configure - Optional callback to configure the group inline
+ * @param autoRegister - If true, registers the group to the global registry
  *
  * @example
  * const users = defineGroup('/users', (group) => {
  *   group.addGet('/:id', handler);
- * });
+ * }, true);
  */
-declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void): RouteGroup;
+declare function defineGroup(basePath: string, configure?: (group: RouteGroup) => void, autoRegister?: boolean): RouteGroup;
 
 interface RouteMatch {
-    handler: Handler | null;
+    route: Route | null;
     allowed?: HttpMethod[];
     params: Record<string, string | undefined>;
 }
 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;
 }
 
@@ -326,12 +414,72 @@ declare class RouteTrie {
  *
  * 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();
+ * ```
  */
 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.
      *
@@ -370,39 +518,39 @@ 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;
@@ -414,11 +562,79 @@ declare class RouterBuilder {
      *
      * @returns A fully resolved Astro route handler.
      */
-    build(): 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.
+ */
+declare function createRouter(modulesOrOptions?: Record<string, any> | RouterOptions, options?: RouterOptions): APIRoute;
+
+/**
+ * A global registry for routes and groups to support "agnostic" auto-registration.
+ * This allows routes to be defined anywhere in the project and automatically
+ * picked up by the router.
+ */
+declare class InternalRegistry {
+    private static instance;
+    private items;
+    private constructor();
+    static getInstance(): InternalRegistry;
+    register(item: any): void;
+    getItems(): any[];
+    clear(): void;
 }
+declare const globalRegistry: InternalRegistry;
 
 /**
- * A writer for streaming raw data to the response body.
+ * @Get decorator - auto-registers a GET route.
+ */
+declare const Get: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Post decorator - auto-registers a POST route.
+ */
+declare const Post: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Put decorator - auto-registers a PUT route.
+ */
+declare const Put: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Delete decorator - auto-registers a DELETE route.
+ */
+declare const Delete: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @Patch decorator - auto-registers a PATCH route.
+ */
+declare const Patch: (path: string) => (target: any, propertyKey: string, descriptor?: PropertyDescriptor) => void;
+/**
+ * @RouteGroup decorator - can be used on classes to auto-register a group.
+ * Note: This requires the class to have a static method or property that returns the routes,
+ * or it can be used in conjunction with method decorators.
+ *
+ * For now, we'll implement a simple version that can be used on a class
+ * if the class is intended to be a group.
+ */
+declare function Group(basePath: string): (constructor: Function) => void;
+
+/**
+ * A writer for streaming raw state to the response body.
  *
  * This is used inside the `stream()` route handler to emit bytes
  * or strings directly to the client with backpressure awareness.
@@ -462,7 +678,7 @@ interface StreamOptions {
     keepAlive?: boolean;
 }
 /**
- * Defines a generic streaming route that can write raw chunks of data
+ * Defines a generic streaming route that can write raw chunks of state
  * to the response in real time using a `ReadableStream`.
  *
  * Suitable for Server-Sent Events (SSE), long-polling, streamed HTML,
@@ -471,7 +687,7 @@ interface StreamOptions {
  * @example
  * stream('/clock', async ({ response }) => {
  *   const timer = setInterval(() => {
- *     response.write(`data: ${new Date().toISOString()}\n\n`);
+ *     response.write(`state: ${new Date().toISOString()}\n\n`);
  *   }, 1000);
  *
  *   setTimeout(() => {
@@ -491,7 +707,7 @@ declare function stream(path: string, handler: (ctx: APIContext & {
 
 type JsonValue = any;
 /**
- * A writer interface for streaming JSON data to the response body.
+ * A writer interface for streaming JSON state to the response body.
  * Supports both NDJSON and array formats.
  */
 interface JsonStreamWriter {
@@ -555,7 +771,7 @@ declare function streamJsonND(path: string, handler: (ctx: APIContext & {
  * Defines a JSON streaming route that emits a valid JSON array.
  *
  * This helper returns a valid `application/json` response containing
- * a streamable array of JSON values. Useful for large data exports
+ * a streamable array of JSON values. Useful for large state exports
  * or APIs where the full array can be streamed as it's generated.
  *
  * Unlike `streamJsonND()`, this wraps all values in `[` and `]`
@@ -579,5 +795,70 @@ declare function streamJsonArray(path: string, handler: (ctx: APIContext & {
     method?: HttpMethod;
 }): Route;
 
-export { ALLOWED_HTTP_METHODS, HttpMethod, RouteGroup, RouteTrie, RouterBuilder, badRequest, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, internalError, isReadableStream, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, stream, streamJsonArray, streamJsonND, toAstroResponse, tooManyRequests, unauthorized };
-export type { Handler, JsonStreamWriter, ResultResponse, Route, RouterOptions, StreamOptions, StreamWriter };
+/**
+ * CORS options.
+ */
+interface CorsOptions {
+    origin?: string | string[] | ((origin: string) => boolean | string);
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAge?: number;
+}
+/**
+ * Middleware to enable Cross-Origin Resource Sharing (CORS).
+ */
+declare function cors(options?: CorsOptions): Middleware;
+/**
+ * Middleware to add common security headers (Helmet-like).
+ */
+declare function securityHeaders(): Middleware;
+/**
+ * Interface for schemas compatible with Zod, Valibot, etc.
+ */
+interface Validatable {
+    safeParse: (data: any) => {
+        success: true;
+        data: any;
+    } | {
+        success: false;
+        error: any;
+    };
+}
+/**
+ * Validation schema for request components.
+ */
+interface ValidationSchema {
+    body?: Validatable;
+    query?: Validatable;
+    params?: Validatable;
+}
+/**
+ * Middleware for request validation.
+ * Supports any schema library with a `safeParse` method (like Zod).
+ *
+ * Validated state is stored in `ctx.state.body`, `ctx.state.query`, etc.
+ */
+declare function validate(schema: ValidationSchema): Middleware;
+
+/**
+ * Basic options for OpenAPI generation.
+ */
+interface OpenAPIOptions {
+    title: string;
+    version: string;
+    description?: string;
+    basePath?: string;
+}
+/**
+ * Generates an OpenAPI 3.0.0 specification from a list of Routify routes.
+ *
+ * @param router - The router handler function (returned by builder.build() or createRouter())
+ * @param options - Basic info for the OpenAPI spec
+ * @returns A JSON object representing the OpenAPI specification
+ */
+declare function generateOpenAPI(router: any, options: OpenAPIOptions): any;
+
+export { ALLOWED_HTTP_METHODS, Delete, Get, Group, HttpMethod, Patch, Post, Put, RouteGroup, RouteTrie, RouterBuilder, badRequest, cors, createRouter, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, generateOpenAPI, globalRegistry, internalError, isReadableStream, isRoute, json, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, securityHeaders, stream, streamJsonArray, streamJsonND, toAstroResponse, tooManyRequests, unauthorized, validate, validateRoute };
+export type { Context, CorsOptions, Handler, HandlerResult, JsonStreamWriter, Middleware, OpenAPIOptions, ResultResponse, Route, RouterOptions, RoutifyContext, StreamOptions, StreamWriter, Validatable, ValidationSchema };

package/dist/index.js

@@ -5,7 +5,11 @@ export * from './core/defineGroup';
 export * from './core/RouteTrie';
 export * from './core/HttpMethod';
 export * from './core/responseHelpers';
-export * from './core/RouterBuilder';
+export { RouterBuilder, createRouter } from './core/RouterBuilder';
+export { globalRegistry } from './core/registry';
+export * from './core/decorators';
 export * from './core/stream';
 export * from './core/streamJsonND';
 export * from './core/streamJsonArray';
+export * from './core/middlewares';
+export * from './core/openapi';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-routify",
-  "version": "1.2.2",
+  "version": "1.5.0",
   "description": "A high-performance API router for Astro using a Trie-based matcher.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,9 @@
     "ndjson",
     "json-stream",
     "response-helpers",
-    "astro-api"
+    "astro-api",
+    "withastro",
+    "utils"
   ],
   "author": "Alex Mora",
   "license": "MIT",
@@ -40,7 +42,7 @@
     "rollup": "^4.46.2",
     "rollup-plugin-dts": "^6.2.1",
     "typescript": "^5.3.3",
-    "undici": "^7.13.0",
+    "undici": "^7.20.0",
     "vitest": "^3.2.4"
   },
   "engines": {