@stacksjs/bun-router 0.0.5 → 0.0.6

package/dist/response/macros.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Request/Response Enhancements - Response Macros
+ *
+ * Laravel-style response macros for common response patterns
+ */
+export interface ResponseMacro {
+    name: string;
+    handler: (...args: any[]) => Response;
+}
+export interface ApiResponse<T = any> {
+    data?: T;
+    message?: string;
+    error?: string;
+    errors?: Record<string, string[]>;
+    meta?: Record<string, any>;
+    links?: Record<string, string>;
+    timestamp?: string;
+}
+export interface PaginatedResponse<T = any> extends ApiResponse<T[]> {
+    meta: {
+        current_page: number;
+        per_page: number;
+        total: number;
+        last_page: number;
+        from: number;
+        to: number;
+        path: string;
+        first_page_url: string;
+        last_page_url: string;
+        next_page_url?: string;
+        prev_page_url?: string;
+    };
+}
+/**
+ * Response macro registry
+ */
+declare class ResponseMacroRegistry {
+    private macros;
+    /**
+     * Register a response macro
+     */
+    register(name: string, handler: (...args: any[]) => Response): void;
+    /**
+     * Get a registered macro
+     */
+    get(name: string): ResponseMacro | undefined;
+    /**
+     * Check if macro exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered macros
+     */
+    all(): ResponseMacro[];
+    /**
+     * Remove a macro
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all macros
+     */
+    clear(): void;
+}
+/**
+ * Global response macro registry
+ */
+export declare const responseMacroRegistry: ResponseMacroRegistry;
+/**
+ * Response class with macro support
+ */
+export declare class ResponseWithMacros extends Response {
+    /**
+     * Register a response macro
+     */
+    static macro(name: string, handler: (...args: any[]) => Response): void;
+    /**
+     * Call a registered macro
+     */
+    static callMacro(name: string, ...args: any[]): Response;
+    /**
+     * Check if macro exists
+     */
+    static hasMacro(name: string): boolean;
+}
+/**
+ * Built-in response macros
+ */
+export declare const BuiltInResponseMacros: {
+    /**
+     * Success response with data
+     */
+    success: (data?: any, message?: string, status?: number) => Response;
+    /**
+     * Error response with message and errors
+     */
+    error: (message: string, errors?: Record<string, string[]>, status?: number) => Response;
+    /**
+     * Validation error response
+     */
+    validationError: (errors: Record<string, string[]>, message?: string) => Response;
+    /**
+     * Not found response
+     */
+    notFound: (message?: string) => Response;
+    /**
+     * Unauthorized response
+     */
+    unauthorized: (message?: string) => Response;
+    /**
+     * Forbidden response
+     */
+    forbidden: (message?: string) => Response;
+    /**
+     * Internal server error response
+     */
+    serverError: (message?: string) => Response;
+    /**
+     * Created response
+     */
+    created: (data?: any, message?: string) => Response;
+    /**
+     * Updated response
+     */
+    updated: (data?: any, message?: string) => Response;
+    /**
+     * Deleted response
+     */
+    deleted: (message?: string) => Response;
+    /**
+     * No content response
+     */
+    noContent: () => Response;
+    /**
+     * Accepted response
+     */
+    accepted: (data?: any, message?: string) => Response;
+    /**
+     * Paginated response
+     */
+    paginated: <T>(data: T[], pagination: {
+        current_page: number;
+        per_page: number;
+        total: number;
+        path: string;
+    }, message?: string) => Response;
+    /**
+     * JSON response with custom headers
+     */
+    json: (data: any, status?: number, headers?: Record<string, string>) => Response;
+    /**
+     * HTML response
+     */
+    html: (content: string, status?: number, headers?: Record<string, string>) => Response;
+    /**
+     * Plain text response
+     */
+    text: (content: string, status?: number, headers?: Record<string, string>) => Response;
+    /**
+     * XML response
+     */
+    xml: (content: string, status?: number, headers?: Record<string, string>) => Response;
+    /**
+     * Redirect response
+     */
+    redirect: (url: string, status?: number) => Response;
+    /**
+     * Permanent redirect response
+     */
+    permanentRedirect: (url: string) => Response;
+    /**
+     * Download response
+     */
+    download: (data: ArrayBuffer | Uint8Array | string, filename: string, contentType?: string) => Response;
+    /**
+     * Stream response
+     */
+    stream: (stream: ReadableStream, contentType?: string, headers?: Record<string, string>) => Response;
+    /**
+     * Cache response with headers
+     */
+    cache: (data: any, maxAge?: number, isPublic?: boolean, etag?: string) => Response;
+    /**
+     * CORS response
+     */
+    cors: (data: any, origin?: string, methods?: string, headers?: string) => Response;
+    /**
+     * Server-Sent Events response
+     */
+    sse: (data: string, event?: string, id?: string) => Response;
+    /**
+     * Health check response
+     */
+    health: (status?: "healthy" | "unhealthy" | "degraded", checks?: Record<string, any>) => Response;
+};
+/**
+ * Register all built-in macros
+ */
+export declare function registerBuiltInResponseMacros(): void;
+/**
+ * Response macro factory functions
+ */
+export declare const ResponseMacroFactory: {
+    /**
+     * Create API response macro
+     */
+    api: (defaultMeta?: Record<string, any>) => (data?: any, message?: string, status?: number) => Response;
+    /**
+     * Create versioned API response macro
+     */
+    versionedApi: (version: string) => (data?: any, message?: string, status?: number) => Response;
+    /**
+     * Create custom error response macro
+     */
+    customError: (defaultStatus?: number, defaultMessage?: string) => (message?: string, errors?: Record<string, string[]>, status?: number) => Response;
+};
+/**
+ * Response helper utilities
+ */
+export declare const ResponseHelpers: {
+    /**
+     * Check if response is successful
+     */
+    isSuccess: (response: Response) => boolean;
+    /**
+     * Check if response is error
+     */
+    isError: (response: Response) => boolean;
+    /**
+     * Get response body as JSON
+     */
+    getJson: (response: Response) => Promise<any>;
+    /**
+     * Get response body as text
+     */
+    getText: (response: Response) => Promise<string>;
+    /**
+     * Clone response with new headers
+     */
+    withHeaders: (response: Response, headers: Record<string, string>) => Response;
+    /**
+     * Clone response with new status
+     */
+    withStatus: (response: Response, status: number, statusText?: string) => Response;
+};
+export {};

package/dist/response/response-factory.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Response Factory
+ *
+ * Implements fluent response helpers with full TypeScript support
+ */
+import type { ContentType, ResponseStatus } from '../types';
+/**
+ * JSON response options
+ */
+export interface JsonResponseOptions {
+    status?: ResponseStatus;
+    headers?: Record<string, string>;
+    pretty?: boolean;
+}
+/**
+ * Download response options
+ */
+export interface DownloadOptions {
+    filename?: string;
+    headers?: Record<string, string>;
+    disposition?: 'attachment' | 'inline';
+}
+/**
+ * Stream download options
+ */
+export interface StreamDownloadOptions extends DownloadOptions {
+    contentType?: ContentType;
+}
+/**
+ * Cookie options for response
+ */
+export interface ResponseCookieOptions {
+    maxAge?: number;
+    expires?: Date;
+    httpOnly?: boolean;
+    secure?: boolean;
+    path?: string;
+    domain?: string;
+    sameSite?: 'strict' | 'lax' | 'none';
+}
+export interface ResponseFactory {
+    json: <T>(data: T, options?: JsonResponseOptions) => Response;
+    noContent: (headers?: Record<string, string>) => Response;
+    download: (filePath: string, filename?: string, headers?: Record<string, string>) => Promise<Response>;
+    file: (filePath: string, headers?: Record<string, string>) => Promise<Response>;
+    streamDownload: (generator: () => AsyncGenerator<string | Uint8Array, void, unknown>, filename: string, options?: StreamDownloadOptions) => Response;
+    redirect: (url: string, status?: 301 | 302 | 303 | 307 | 308) => Response;
+    redirectPermanent: (url: string) => Response;
+    redirectTemporary: (url: string) => Response;
+    back: (request: Request, fallback?: string) => Response;
+    view: (html: string, status?: ResponseStatus, headers?: Record<string, string>) => Response;
+    text: (text: string, status?: ResponseStatus, headers?: Record<string, string>) => Response;
+    xml: (xml: string, status?: ResponseStatus, headers?: Record<string, string>) => Response;
+    success: <T>(data?: T, message?: string, status?: ResponseStatus) => Response;
+    error: (message: string, status?: ResponseStatus, errors?: Record<string, string[]>) => Response;
+    paginate: <T>(data: T[], options: {
+        page: number;
+        perPage: number;
+        total: number;
+        path: string;
+    }) => Response;
+    created: <T>(data?: T, location?: string) => Response;
+    accepted: <T>(data?: T) => Response;
+    notFound: (message?: string) => Response;
+    unauthorized: (message?: string) => Response;
+    forbidden: (message?: string) => Response;
+    badRequest: (message?: string, errors?: Record<string, string[]>) => Response;
+    validationError: (errors: Record<string, string[]>, message?: string) => Response;
+    unprocessableEntity: (message?: string, errors?: Record<string, string[]>) => Response;
+    serverError: (message?: string) => Response;
+    tooManyRequests: (message?: string, retryAfter?: number) => Response;
+}
+/**
+ * Response factory with common response helpers
+ */
+export declare const response: ResponseFactory;
+/**
+ * Fluent response builder
+ */
+export declare class ResponseBuilder {
+    private _status;
+    private _headers;
+    private _cookies;
+    private _deleteCookies;
+    /**
+     * Set response status
+     */
+    status(code: ResponseStatus): this;
+    /**
+     * Add a header
+     */
+    header(name: string, value: string): this;
+    /**
+     * Add multiple headers
+     */
+    withHeaders(headers: Record<string, string>): this;
+    /**
+     * Add a cookie
+     */
+    cookie(name: string, value: string, options?: ResponseCookieOptions): this;
+    /**
+     * Remove a cookie
+     */
+    withoutCookie(name: string, options?: Pick<ResponseCookieOptions, 'path' | 'domain'>): this;
+    /**
+     * Build JSON response
+     */
+    json<T>(data: T): Response;
+    /**
+     * Build text response
+     */
+    text(content: string): Response;
+    /**
+     * Build HTML response
+     */
+    html(content: string): Response;
+    /**
+     * Build no content response
+     */
+    noContent(): Response;
+    /**
+     * Apply cookies to response
+     */
+    private applyCookies;
+    /**
+     * Serialize cookie to string
+     */
+    private serializeCookie;
+}
+/**
+ * Create a new response builder
+ */
+export declare function responseBuilder(): ResponseBuilder;

package/dist/router/api-routes.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Register the API route auto-discovery feature on the Router class.
+ */
+export declare function registerApiRoutes(RouterClass: typeof Router): void;

package/dist/router/file-based-routing.d.ts

@@ -0,0 +1,118 @@
+import type { EnhancedRequest } from '../types';
+import type { Router } from './router';
+/**
+ * File-based routing configuration
+ */
+export interface FileBasedRoutingConfig {
+    /**
+     * Whether automatic file-based routing is enabled
+     * Default: true (auto-enabled when views directory is detected)
+     */
+    enabled?: boolean;
+    /**
+     * Directory containing view files for automatic routing
+     * Default: auto-detected from 'src/views', 'views', 'resources/views'
+     */
+    viewsPath?: string;
+    /**
+     * File extensions to treat as routable pages
+     * Default: ['.stx', '.html']
+     */
+    extensions?: string[];
+    /**
+     * Files/directories to exclude from routing
+     * Default: ['_', 'components', 'layouts', 'partials', 'scripts', 'styles']
+     */
+    exclude?: string[];
+    /**
+     * Directory containing component files for STX rendering
+     * Default: join(viewsPath, 'components')
+     */
+    componentsDir?: string;
+    /**
+     * Directory containing layout files for STX rendering
+     * Default: join(viewsPath, 'layouts')
+     */
+    layoutsDir?: string;
+    /**
+     * Directory containing partial files for STX rendering
+     * Default: join(viewsPath, 'partials')
+     */
+    partialsDir?: string;
+    /**
+     * Custom render function for view files
+     * If not provided, attempts to use STX renderer or serves raw content
+     */
+    render?: (filePath: string, data: Record<string, unknown>, request: EnhancedRequest) => Promise<Response>;
+}
+interface DiscoveredRoute {
+    filePath: string;
+    routePath: string;
+    params: string[];
+    isIndex: boolean;
+    isDynamic: boolean;
+}
+/**
+ * Default directories to scan for views (in order of priority)
+ */
+declare const DEFAULT_VIEW_DIRECTORIES: string[];
+/**
+ * Default exclusion patterns for non-routable files/directories
+ */
+declare const DEFAULT_EXCLUDES: string[];
+/**
+ * Default routable file extensions
+ */
+declare const DEFAULT_EXTENSIONS: string[];
+/**
+ * Auto-detect the views directory from common conventions
+ */
+declare function detectViewsDirectory(cwd?: string): string | null;
+/**
+ * Recursively discovers all routable files in a directory
+ */
+declare function discoverRoutes(dir: string, viewsDir: string, extensions: string[], exclude: string[]): DiscoveredRoute[];
+/**
+ * Registers file-based routing extension on the Router class
+ */
+export declare function registerFileBasedRouting(RouterClass: typeof Router): void;
+declare module './router' {
+    interface Router {
+        _viewsDir?: string | null;
+        _fileRoutingConfig?: FileBasedRoutingConfig | null;
+        _fileBasedRoutes?: DiscoveredRoute[];
+        _fileRoutesInitialized?: boolean;
+        /**
+         * Internal: Initialize file-based routing (called by serve())
+         */
+        _initFileRoutes(): Promise<void>;
+        /**
+         * Configure file-based routing
+         * @param config - Path to views directory or full configuration object
+         * @example
+         * router.views('src/views')
+         * router.views({ viewsPath: 'src/views', extensions: ['.stx'] })
+         */
+        views(config: FileBasedRoutingConfig | string): Router;
+        /**
+         * Disable automatic file-based routing
+         */
+        disableFileRouting(): Router;
+        /**
+         * Get the list of discovered file-based routes
+         */
+        getFileRoutes(): DiscoveredRoute[];
+        /**
+         * Manually trigger file-based route discovery
+         * @param viewsPath - Optional path to views directory
+         * @param options - Additional configuration options
+         */
+        fileRoutes(viewsPath?: string, options?: Omit<FileBasedRoutingConfig, 'viewsPath'>): Promise<Router>;
+        /**
+         * Legacy: Load file-based routes with configuration
+         */
+        loadFileRoutes(config?: FileBasedRoutingConfig): Promise<Router>;
+    }
+}
+export type { DiscoveredRoute };
+export { detectViewsDirectory, discoverRoutes, DEFAULT_VIEW_DIRECTORIES, DEFAULT_EXCLUDES, DEFAULT_EXTENSIONS };

package/dist/router/file-streaming.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * File streaming extension for Router class
+ */
+export declare function registerFileStreaming(RouterClass: typeof Router): void;