astro-routify 1.4.0 → 1.5.0

package/dist/core/defineGroup.d.ts

@@ -13,6 +13,7 @@ import { Middleware } from "./defineHandler";
  *   .addPost('/', createUser);
  */
 export declare class RouteGroup {
+    readonly _routifyType = "group";
     private basePath;
     private routes;
     private middlewares;

package/dist/core/defineGroup.js

@@ -20,6 +20,7 @@ export class RouteGroup {
      * @param basePath - The common prefix for all routes in the group (e.g. "/users")
      */
     constructor(basePath) {
+        this._routifyType = 'group';
         this.routes = [];
         this.middlewares = [];
         this.basePath = basePath.endsWith('/') ? basePath.slice(0, -1) : basePath;

package/dist/core/defineHandler.d.ts

@@ -1,29 +1,37 @@
 import type { APIContext, APIRoute } from 'astro';
-import { type ResultResponse } from './responseHelpers';
+import { type HandlerResult } from './responseHelpers';
 /**
  * Enhanced Astro context for Routify.
  */
-export interface RoutifyContext extends APIContext {
+export 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>;
+    query: Record<string, string | string[]>;
     /**
-     * Shared data container for middlewares and handlers (e.g., validation results).
+     * Full URLSearchParams object for the incoming request.
      */
-    data: Record<string, any>;
+    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.
+ */
+export type Context<State = Record<string, any>> = RoutifyContext<State>;
 /**
  * A middleware function that can modify the context or short-circuit the response.
  */
-export type Middleware = (ctx: RoutifyContext, next: () => Promise<Response>) => Promise<Response> | Response;
+export 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.
  */
-export type Handler = (ctx: RoutifyContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+export type Handler<State = any> = (ctx: RoutifyContext<State>) => Promise<HandlerResult> | HandlerResult;
 /**
  * Wraps a `Handler` function into an `APIRoute` that:
  * - logs requests and responses,

package/dist/core/defineHandler.js

@@ -1,4 +1,4 @@
-import { internalError, toAstroResponse, isReadableStream } from './responseHelpers';
+import { internalError, toAstroResponse } from './responseHelpers';
 /**
  * Logs the incoming request method and path to the console.
  */
@@ -33,18 +33,7 @@ export function defineHandler(handler) {
                 logResponse(result.status, start);
                 return result;
             }
-            // Direct binary or stream body (file download, etc.)
-            if (result?.body instanceof Blob ||
-                result?.body instanceof ArrayBuffer ||
-                isReadableStream(result?.body)) {
-                const res = new Response(result.body, {
-                    status: result.status,
-                    headers: result.headers,
-                });
-                logResponse(res.status, start);
-                return res;
-            }
-            // Structured ResultResponse → native Astro Response
+            // Structured ResultResponse or other HandlerResult → native Astro Response
             const finalResponse = toAstroResponse(result);
             logResponse(finalResponse.status, start);
             return finalResponse;

package/dist/core/defineRoute.d.ts

@@ -21,9 +21,14 @@ export 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.

package/dist/core/defineRoute.js

@@ -18,6 +18,7 @@ export function defineRoute(methodOrRoute, maybePathOrAutoRegister, maybeHandler
         };
         autoRegister = !!maybeAutoRegister;
     }
+    route._routifyType = 'route';
     validateRoute(route);
     if (autoRegister) {
         globalRegistry.register(route);
@@ -37,6 +38,9 @@ export function validateRoute({ method, path }) {
     if (!ALLOWED_HTTP_METHODS.has(method)) {
         throw new Error(`Unsupported HTTP method in route: ${method}`);
     }
+    if (path.includes('**') && !path.endsWith('**')) {
+        throw new Error(`Catch-all '**' is only allowed at the end of a path: ${path}`);
+    }
 }
 /**
  * Checks if an object implements the `Route` interface.
@@ -47,7 +51,8 @@ export function validateRoute({ method, path }) {
 export function isRoute(obj) {
     return (obj &&
         typeof obj === 'object' &&
-        typeof obj.method === 'string' &&
-        typeof obj.path === 'string' &&
-        typeof obj.handler === 'function');
+        (obj._routifyType === 'route' ||
+            (typeof obj.method === 'string' &&
+                typeof obj.path === 'string' &&
+                typeof obj.handler === 'function')));
 }

package/dist/core/defineRouter.d.ts

@@ -1,6 +1,6 @@
 import type { APIRoute } from 'astro';
 import { type RoutifyContext } from './defineHandler';
-import { internalError, notFound } from './responseHelpers';
+import { notFound, type HandlerResult } from './responseHelpers';
 import type { Route } from './defineRoute';
 /**
  * Optional configuration for the router instance.
@@ -23,7 +23,7 @@ export 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.

package/dist/core/defineRouter.js

@@ -42,8 +42,24 @@ export function defineRouter(routes, options = {}) {
     const handler = defineHandler(async (routifyCtx) => {
         const url = new URL(routifyCtx.request.url);
         const pathname = url.pathname;
-        routifyCtx.query = Object.fromEntries(url.searchParams.entries());
-        routifyCtx.data = {};
+        routifyCtx.searchParams = url.searchParams;
+        const query = {};
+        url.searchParams.forEach((value, key) => {
+            const existing = query[key];
+            if (existing !== undefined) {
+                if (Array.isArray(existing)) {
+                    existing.push(value);
+                }
+                else {
+                    query[key] = [existing, value];
+                }
+            }
+            else {
+                query[key] = value;
+            }
+        });
+        routifyCtx.query = query;
+        routifyCtx.state = {};
         let path = pathname;
         if (basePath !== '') {
             if (!pathname.startsWith(basePath)) {

package/dist/core/internal/createJsonStreamRoute.d.ts

@@ -3,7 +3,7 @@ import { HttpMethod } from '../HttpMethod';
 import { type Route } from '../defineRoute';
 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.
  */
 export interface JsonStreamWriter {

package/dist/core/middlewares.d.ts

@@ -42,6 +42,6 @@ export 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.
  */
 export declare function validate(schema: ValidationSchema): Middleware;

package/dist/core/middlewares.js

@@ -77,7 +77,7 @@ export function securityHeaders() {
  * 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.
  */
 export function validate(schema) {
     return async (ctx, next) => {
@@ -85,13 +85,13 @@ export function validate(schema) {
             const result = schema.params.safeParse(ctx.params);
             if (!result.success)
                 return toAstroResponse(badRequest({ error: 'Invalid parameters', details: result.error }));
-            ctx.data.params = result.data;
+            ctx.state.params = result.data;
         }
         if (schema.query) {
             const result = schema.query.safeParse(ctx.query);
             if (!result.success)
                 return toAstroResponse(badRequest({ error: 'Invalid query string', details: result.error }));
-            ctx.data.query = result.data;
+            ctx.state.query = result.data;
         }
         if (schema.body) {
             try {
@@ -99,7 +99,7 @@ export function validate(schema) {
                 const result = schema.body.safeParse(body);
                 if (!result.success)
                     return toAstroResponse(badRequest({ error: 'Invalid request body', details: result.error }));
-                ctx.data.body = result.data;
+                ctx.state.body = result.data;
             }
             catch (e) {
                 return toAstroResponse(badRequest({ error: 'Invalid JSON body' }));

package/dist/core/openapi.js

@@ -25,7 +25,11 @@ export function generateOpenAPI(router, options) {
         const path = route.path;
         // OpenAPI paths must start with / and should not include the basePath if it's in servers
         // Convert :param or :param(regex) to {param}
-        const openApiPath = path.replace(/:([a-zA-Z0-9_]+)(\(.*?\))?/g, '{$1}');
+        // Convert ** to {rest} and * to {any}
+        let openApiPath = path
+            .replace(/:([a-zA-Z0-9_]+)(\(.*?\))?/g, '{$1}')
+            .replace(/\*\*/g, '{rest}')
+            .replace(/\*/g, '{any}');
         if (!spec.paths[openApiPath])
             spec.paths[openApiPath] = {};
         const method = route.method.toLowerCase();
@@ -42,14 +46,37 @@ export function generateOpenAPI(router, options) {
             }
         };
         // Extract path parameters
-        const pathParamMatches = path.matchAll(/:([a-zA-Z0-9_]+)/g);
-        for (const match of pathParamMatches) {
-            const name = match[1];
+        const paramRegex = /:([a-zA-Z0-9_]+)(?:\((.*?)\))?/g;
+        let pMatch;
+        while ((pMatch = paramRegex.exec(path)) !== null) {
+            const name = pMatch[1];
+            const pattern = pMatch[2];
             spec.paths[openApiPath][method].parameters.push({
                 name,
                 in: 'path',
                 required: true,
-                schema: { type: 'string' }
+                schema: {
+                    type: 'string',
+                    pattern: pattern ? pattern : undefined
+                }
+            });
+        }
+        if (path.includes('**')) {
+            spec.paths[openApiPath][method].parameters.push({
+                name: 'rest',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: 'Catch-all path'
+            });
+        }
+        else if (path.includes('*')) {
+            spec.paths[openApiPath][method].parameters.push({
+                name: 'any',
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+                description: 'Wildcard segment'
             });
         }
     }

package/dist/core/responseHelpers.d.ts

@@ -1,4 +1,8 @@
 import { BodyInit, HeadersInit } from 'undici';
+/**
+ * Supported types that can be returned from a route handler.
+ */
+export 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.
@@ -70,7 +74,7 @@ export declare const internalError: (err: unknown, headers?: HeadersInit) => Res
 /**
  * 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
@@ -85,12 +89,12 @@ export declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream
  */
 export 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
  */
-export declare function toAstroResponse(result: ResultResponse | undefined): Response;
+export declare function toAstroResponse(result: HandlerResult): Response;

package/dist/core/responseHelpers.js

@@ -63,7 +63,7 @@ export const internalError = (err, headers) => {
 /**
  * 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,28 +101,103 @@ export function isReadableStream(value) {
         typeof value.getReader === 'function');
 }
 /**
- * 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
  */
 export function toAstroResponse(result) {
-    if (!result)
+    if (result instanceof Response)
+        return result;
+    if (result === undefined) {
         return new Response(null, { status: 204 });
-    const { status, body, headers } = result;
-    if (body === undefined || body === null) {
-        return new Response(null, { status, headers });
     }
-    const isJson = isPlainObject(body) || Array.isArray(body);
-    const finalHeaders = {
-        ...(headers ?? {}),
-        ...(isJson ? { 'Content-Type': 'application/json; charset=utf-8' } : {}),
-    };
-    return new Response(isJson ? JSON.stringify(body) : body, {
-        status,
-        headers: finalHeaders,
-    });
+    if (result === null) {
+        return new Response('null', {
+            status: 200,
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+        });
+    }
+    // If it's a ResultResponse object (has status)
+    if (typeof result === 'object' &&
+        'status' in result &&
+        typeof result.status === 'number') {
+        const { status, body, headers } = result;
+        if (body === undefined) {
+            return new Response(null, { status, headers });
+        }
+        if (body === null) {
+            const finalHeaders = new Headers();
+            finalHeaders.set('Content-Type', 'application/json; charset=utf-8');
+            if (headers) {
+                const h = new Headers(headers);
+                h.forEach((value, key) => finalHeaders.set(key, value));
+            }
+            return new Response('null', { status, headers: finalHeaders });
+        }
+        if (body instanceof Response)
+            return body;
+        const isJson = typeof body === 'number' ||
+            typeof body === 'boolean' ||
+            isPlainObject(body) ||
+            Array.isArray(body);
+        const isBinary = body instanceof ArrayBuffer ||
+            body instanceof Uint8Array ||
+            body instanceof Blob ||
+            isReadableStream(body);
+        const finalHeaders = new Headers();
+        // 1. Apply inferred defaults
+        if (isJson) {
+            finalHeaders.set('Content-Type', 'application/json; charset=utf-8');
+        }
+        else if (isBinary) {
+            finalHeaders.set('Content-Type', 'application/octet-stream');
+        }
+        // 2. Explicit headers take precedence
+        if (headers) {
+            const h = new Headers(headers);
+            h.forEach((value, key) => {
+                finalHeaders.set(key, value);
+            });
+        }
+        return new Response(isJson ? JSON.stringify(body) : body, {
+            status,
+            headers: finalHeaders,
+        });
+    }
+    // Direct values
+    if (typeof result === 'string') {
+        return new Response(result, {
+            status: 200,
+            headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+        });
+    }
+    if (typeof result === 'number' || typeof result === 'boolean') {
+        return new Response(JSON.stringify(result), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+        });
+    }
+    if (result instanceof ArrayBuffer ||
+        result instanceof Uint8Array ||
+        result instanceof Blob ||
+        isReadableStream(result)) {
+        return new Response(result, {
+            status: 200,
+            headers: { 'Content-Type': 'application/octet-stream' },
+        });
+    }
+    if (result instanceof FormData || result instanceof URLSearchParams) {
+        return new Response(result, { status: 200 });
+    }
+    if (Array.isArray(result) || isPlainObject(result)) {
+        return new Response(JSON.stringify(result), {
+            status: 200,
+            headers: { 'Content-Type': 'application/json; charset=utf-8' },
+        });
+    }
+    return new Response(null, { status: 204 });
 }

package/dist/core/stream.d.ts

@@ -3,7 +3,7 @@ import { type Route } from './defineRoute';
 import { HttpMethod } from './HttpMethod';
 import { HeadersInit } from 'undici';
 /**
- * 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.
@@ -47,7 +47,7 @@ export 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,
@@ -56,7 +56,7 @@ export 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(() => {

package/dist/core/stream.js

@@ -1,7 +1,7 @@
 import { defineRoute } from './defineRoute';
 import { HttpMethod } from './HttpMethod';
 /**
- * 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,
@@ -10,7 +10,7 @@ import { HttpMethod } from './HttpMethod';
  * @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(() => {
@@ -36,7 +36,7 @@ export function stream(path, handler, options) {
                 if (closed || !controllerRef)
                     return;
                 const bytes = typeof chunk === 'string'
-                    ? (contentType === 'text/event-stream' ? encoder.encode(`data: ${chunk}\n\n`) : encoder.encode(chunk))
+                    ? (contentType === 'text/event-stream' ? encoder.encode(`state: ${chunk}\n\n`) : encoder.encode(chunk))
                     : chunk;
                 controllerRef.enqueue(bytes);
             },

package/dist/core/streamJsonArray.d.ts

@@ -6,7 +6,7 @@ import { JsonStreamWriter } from './internal/createJsonStreamRoute';
  * 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 `]`

package/dist/core/streamJsonArray.js

@@ -4,7 +4,7 @@ import { createJsonStreamRoute } from './internal/createJsonStreamRoute';
  * 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 `]`