astro-routify 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -15,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.
@@ -86,7 +90,7 @@ declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResp
 /**
  * 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
@@ -101,40 +105,48 @@ declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8A
  */
 declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
 /**
- * Converts an internal `ResultResponse` into a native `Response` object
+ * 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;
 
 /**
  * Enhanced Astro context for Routify.
  */
-interface RoutifyContext extends APIContext {
+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.
      */
-    query: Record<string, string>;
+    searchParams: URLSearchParams;
     /**
-     * Shared data container for middlewares and handlers (e.g., validation results).
+     * Shared state container for middlewares and handlers (e.g., validation results).
+     * This is where middlewares can store information for subsequent handlers.
      */
-    data: Record<string, any>;
+    state: State;
 }
+/**
+ * Convenience type alias for RoutifyContext.
+ */
+type Context<State = Record<string, any>> = RoutifyContext<State>;
 /**
  * A middleware function that can modify the context or short-circuit the response.
  */
-type Middleware = (ctx: RoutifyContext, next: () => Promise<Response>) => Promise<Response> | Response;
+type Middleware<State = any> = (ctx: RoutifyContext<State>, 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).
+ * A flexible route handler that can return various types.
  */
-type Handler = (ctx: RoutifyContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+type Handler<State = any> = (ctx: RoutifyContext<State>) => Promise<HandlerResult> | HandlerResult;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,
@@ -168,9 +180,14 @@ interface Route {
      */
     middlewares?: Middleware[];
     /**
-     * Optional metadata for the route (e.g., for OpenAPI generation).
+     * 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.
@@ -232,7 +249,7 @@ interface RouterOptions {
     /**
      * Custom error handler for the router.
      */
-    onError?: (error: unknown, ctx: RoutifyContext) => ReturnType<typeof internalError> | Response;
+    onError?: (error: unknown, ctx: RoutifyContext) => HandlerResult | Response;
 }
 /**
  * Defines a router that dynamically matches registered routes based on method and path.
@@ -270,6 +287,7 @@ declare function defineRouter(routes: Route[], options?: RouterOptions): APIRout
  *   .addPost('/', createUser);
  */
 declare class RouteGroup {
+    readonly _routifyType = "group";
     private basePath;
     private routes;
     private middlewares;
@@ -616,7 +634,7 @@ declare const Patch: (path: string) => (target: any, propertyKey: string, descri
 declare function Group(basePath: string): (constructor: Function) => void;
 
 /**
- * A writer for streaming raw data to the response body.
+ * 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.
@@ -660,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,
@@ -669,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(() => {
@@ -689,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 {
@@ -753,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 `]`
@@ -820,7 +838,7 @@ interface ValidationSchema {
  * 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.
+ * Validated state is stored in `ctx.state.body`, `ctx.state.query`, etc.
  */
 declare function validate(schema: ValidationSchema): Middleware;
 
@@ -843,4 +861,4 @@ interface OpenAPIOptions {
 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 };
+export type { Context, CorsOptions, Handler, HandlerResult, JsonStreamWriter, Middleware, OpenAPIOptions, ResultResponse, Route, RouterOptions, RoutifyContext, StreamOptions, StreamWriter, Validatable, ValidationSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-routify",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A high-performance API router for Astro using a Trie-based matcher.",
   "type": "module",
   "main": "./dist/index.js",