astro-routify 1.2.1 → 1.4.0

package/dist/core/stream.js

@@ -35,8 +35,8 @@ export function stream(path, handler, options) {
             write: (chunk) => {
                 if (closed || !controllerRef)
                     return;
-                const bytes = typeof chunk === 'string' ?
-                    encoder.encode(`data: ${chunk}\n\n`)
+                const bytes = typeof chunk === 'string'
+                    ? (contentType === 'text/event-stream' ? encoder.encode(`data: ${chunk}\n\n`) : encoder.encode(chunk))
                     : chunk;
                 controllerRef.enqueue(bytes);
             },
@@ -56,17 +56,24 @@ export function stream(path, handler, options) {
         const body = new ReadableStream({
             start(controller) {
                 controllerRef = controller;
+                const onAbort = () => {
+                    closed = true;
+                    try {
+                        controller.close();
+                    }
+                    catch { /* noop */ }
+                    console.debug('Request aborted — streaming stopped.');
+                };
+                ctx.request.signal.addEventListener('abort', onAbort, { once: true });
                 Promise.resolve(handler({ ...ctx, response: writer }))
                     .catch((err) => {
                     try {
                         controller.error(err);
                     }
                     catch { /* noop */ }
-                });
-                ctx.request.signal.addEventListener('abort', () => {
-                    closed = true;
-                    controller.close();
-                    console.debug('Request aborted — streaming stopped.');
+                })
+                    .finally(() => {
+                    ctx.request.signal.removeEventListener('abort', onAbort);
                 });
             },
             cancel() {

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import * as astro from 'astro';
 import { APIContext, APIRoute } from 'astro';
 import { HeadersInit, BodyInit } from 'undici';
 
@@ -70,8 +69,18 @@ declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultR
  * 405 Method Not Allowed
  */
 declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 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>;
 /**
@@ -84,6 +93,13 @@ declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResp
  * @returns A ResultResponse for download-ready content
  */
 declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
+/**
+ * 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` into a native `Response` object
  * for use inside Astro API routes.
@@ -95,13 +111,30 @@ declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8A
  */
 declare function toAstroResponse(result: ResultResponse | undefined): Response;
 
+/**
+ * Enhanced Astro context for Routify.
+ */
+interface RoutifyContext extends APIContext {
+    /**
+     * Parsed query parameters from the URL.
+     */
+    query: Record<string, string>;
+    /**
+     * Shared data container for middlewares and handlers (e.g., validation results).
+     */
+    data: Record<string, any>;
+}
+/**
+ * A middleware function that can modify the context or short-circuit the response.
+ */
+type Middleware = (ctx: RoutifyContext, next: () => Promise<Response>) => Promise<Response> | Response;
 /**
  * A flexible route handler that can return:
  * - a native `Response` object,
  * - a structured `ResultResponse` object,
  * - or a file stream (Blob, ArrayBuffer, or ReadableStream).
  */
-type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+type Handler = (ctx: RoutifyContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,
@@ -113,13 +146,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.
@@ -137,6 +163,14 @@ 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>;
 }
 /**
  * Defines a route using a `Route` object.
@@ -145,9 +179,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.
  *
@@ -157,9 +192,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.
@@ -174,6 +224,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) => ReturnType<typeof internalError> | Response;
 }
 /**
  * Defines a router that dynamically matches registered routes based on method and path.
@@ -213,6 +272,7 @@ declare function defineRouter(routes: Route[], options?: RouterOptions): APIRout
 declare class RouteGroup {
     private basePath;
     private routes;
+    private middlewares;
     /**
      * Creates a new route group with the specified base path.
      * Trailing slashes are automatically removed.
@@ -224,49 +284,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.
      */
@@ -277,23 +349,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;
 }
 
@@ -322,12 +396,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.
      *
@@ -366,39 +500,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;
@@ -410,8 +544,76 @@ 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;
+
+/**
+ * @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 data to the response body.
@@ -575,5 +777,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, 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 data is stored in `ctx.data.body`, `ctx.data.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 { CorsOptions, Handler, 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.1",
+  "version": "1.4.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": {