@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/router/fluent-router.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Fluent Routing Extensions
+ *
+ * Implements fluent routing patterns with full TypeScript support
+ */
+import type { EnhancedRequest, MiddlewareHandler, Route, RouteHandler } from '../types';
+import type { Router } from './router';
+/**
+ * Controller class interface
+ */
+export interface ControllerClass {
+    new (): Controller;
+}
+/**
+ * Base controller interface
+ */
+export interface Controller {
+    [key: string]: RouteHandler | unknown;
+}
+/**
+ * Resource controller methods
+ */
+export type ResourceMethod = 'index' | 'create' | 'store' | 'show' | 'edit' | 'update' | 'destroy';
+/**
+ * API resource methods (no create/edit views)
+ */
+export type ApiResourceMethod = 'index' | 'store' | 'show' | 'update' | 'destroy';
+/**
+ * Singleton resource methods
+ */
+export type SingletonMethod = 'show' | 'edit' | 'update';
+/**
+ * Resource configuration
+ */
+export interface ResourceOptions {
+    only?: ResourceMethod[];
+    except?: ResourceMethod[];
+    middleware?: (string | MiddlewareHandler)[];
+    names?: Partial<Record<ResourceMethod, string>>;
+    parameters?: Record<string, string>;
+    shallow?: boolean;
+}
+/**
+ * Route builder for fluent API
+ */
+export interface FluentRoute {
+    name: (name: string) => FluentRoute;
+    middleware: (...middleware: (string | MiddlewareHandler)[]) => FluentRoute;
+    withoutMiddleware: (...middleware: string[]) => FluentRoute;
+    where: (param: string, pattern: string | RegExp) => FluentRoute;
+    whereNumber: (param: string) => FluentRoute;
+    whereAlpha: (param: string) => FluentRoute;
+    whereAlphaNumeric: (param: string) => FluentRoute;
+    whereUuid: (param: string) => FluentRoute;
+    whereSlug: (param: string) => FluentRoute;
+    can: (ability: string, model?: string) => FluentRoute;
+    missing: (handler: (req: EnhancedRequest) => Response) => FluentRoute;
+    withTrashed: () => FluentRoute;
+    scopeBindings: () => FluentRoute;
+}
+/**
+ * Group builder for fluent API
+ */
+export interface GroupBuilder {
+    prefix: (prefix: string) => GroupBuilder;
+    name: (name: string) => GroupBuilder;
+    middleware: (...middleware: (string | MiddlewareHandler)[]) => GroupBuilder;
+    domain: (domain: string) => GroupBuilder;
+    controller: (controller: ControllerClass) => GroupBuilder;
+    routes: (callback: (router: FluentRouter) => void) => void;
+}
+/**
+ * Fluent router with chainable API
+ */
+export declare class FluentRouter {
+    private router;
+    private currentPrefix;
+    private currentNamePrefix;
+    private currentMiddleware;
+    private currentDomain;
+    private currentController;
+    private excludedMiddleware;
+    constructor(router: Router);
+    /**
+     * Register a GET route
+     */
+    get(path: string, handler: RouteHandler | string | Response): FluentRouteBuilder;
+    /**
+     * Register a POST route
+     */
+    post(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a PUT route
+     */
+    put(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a PATCH route
+     */
+    patch(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a DELETE route
+     */
+    delete(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register an OPTIONS route
+     */
+    options(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a route for any HTTP method
+     */
+    any(path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a route for multiple HTTP methods
+     */
+    match(methods: string[], path: string, handler: RouteHandler | string): FluentRouteBuilder;
+    /**
+     * Register a resource controller
+     */
+    resource(name: string, Controller: ControllerClass, options?: ResourceOptions): this;
+    /**
+     * Register an API resource controller (no create/edit views)
+     */
+    apiResource(name: string, controller: ControllerClass, options?: ResourceOptions): this;
+    /**
+     * Register a singleton resource (no index, create, store, destroy)
+     */
+    singleton(name: string, Controller: ControllerClass, options?: ResourceOptions): this;
+    /**
+     * Create a route group with prefix
+     */
+    prefix(prefix: string): GroupBuilderImpl;
+    /**
+     * Create a route group with name prefix
+     */
+    name(namePrefix: string): GroupBuilderImpl;
+    /**
+     * Create a route group with middleware
+     */
+    middleware(...middleware: (string | MiddlewareHandler)[]): GroupBuilderImpl;
+    /**
+     * Create a route group for a domain
+     */
+    domain(domain: string): GroupBuilderImpl;
+    /**
+     * Create a route group with a controller
+     */
+    controller(controller: ControllerClass): GroupBuilderImpl;
+    /**
+     * Create a route group
+     */
+    group(options: GroupOptions, callback: (router: FluentRouter) => void): this;
+    /**
+     * Check if a named route exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get the current route (from request context)
+     */
+    current(): Route | null;
+    /**
+     * Get the current route name
+     */
+    currentRouteName(): string | null;
+    /**
+     * Get URL for a named route
+     */
+    route(name: string, params?: Record<string, string | number>): string;
+    /**
+     * Register a fallback route
+     */
+    fallback(handler: RouteHandler): this;
+    private addRoute;
+    /**
+     * Create a pattern object for route matching
+     */
+    private createPattern;
+    private buildPath;
+    private buildMiddleware;
+    private resolveHandler;
+    private resolveMiddleware;
+    private getResourceMethods;
+    private getResourceRoute;
+    private getSingletonRoute;
+}
+/**
+ * Fluent route builder for chaining route configuration
+ */
+export declare class FluentRouteBuilder implements FluentRoute {
+    private router;
+    private path;
+    private method;
+    private routeName;
+    private routeMiddleware;
+    private excludedMiddleware;
+    private constraints;
+    private missingHandler;
+    private includeTrashed;
+    private scopeBindingsEnabled;
+    private ability;
+    private abilityModel;
+    constructor(router: Router, path: string, method: string);
+    /**
+     * Set the route name
+     */
+    name(name: string): this;
+    /**
+     * Add middleware to the route
+     */
+    middleware(...middleware: (string | MiddlewareHandler)[]): this;
+    /**
+     * Exclude middleware from the route
+     */
+    withoutMiddleware(...middleware: string[]): this;
+    /**
+     * Add a parameter constraint
+     */
+    where(param: string, pattern: string | RegExp): this;
+    /**
+     * Constrain parameter to numbers
+     */
+    whereNumber(param: string): this;
+    /**
+     * Constrain parameter to letters
+     */
+    whereAlpha(param: string): this;
+    /**
+     * Constrain parameter to alphanumeric
+     */
+    whereAlphaNumeric(param: string): this;
+    /**
+     * Constrain parameter to UUID
+     */
+    whereUuid(param: string): this;
+    /**
+     * Constrain parameter to slug format
+     */
+    whereSlug(param: string): this;
+    /**
+     * Add authorization check
+     */
+    can(ability: string, model?: string): this;
+    /**
+     * Handle missing model binding
+     */
+    missing(handler: (req: EnhancedRequest) => Response): this;
+    /**
+     * Include soft-deleted models
+     */
+    withTrashed(): this;
+    /**
+     * Enable scoped bindings
+     */
+    scopeBindings(): this;
+    private findRoute;
+}
+interface GroupOptions {
+    prefix?: string;
+    as?: string;
+    middleware?: (string | MiddlewareHandler)[];
+    domain?: string;
+    controller?: ControllerClass;
+}
+declare class GroupBuilderImpl implements GroupBuilder {
+    private fluentRouter;
+    private options;
+    constructor(router: FluentRouter);
+    prefix(prefix: string): this;
+    name(name: string): this;
+    middleware(...middleware: (string | MiddlewareHandler)[]): this;
+    domain(domain: string): this;
+    controller(controller: ControllerClass): this;
+    routes(callback: (router: FluentRouter) => void): void;
+}
+/**
+ * Extend Router with fluent routing methods
+ */
+export declare function registerFluentRouting(RouterClass: typeof import('./router').Router): void;
+declare module './router' {
+    interface Router {
+        /**
+         * Get fluent router instance
+         */
+        fluent: () => FluentRouter;
+        /**
+         * Register a controller-based resource
+         * Note: Use `resourceController` to avoid conflict with existing `resource` method
+         */
+        resourceController: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
+        /**
+         * Register an API resource controller (no create/edit views)
+         */
+        apiResourceController: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
+        /**
+         * Register a singleton resource
+         */
+        singletonResource: (name: string, controller: ControllerClass, options?: ResourceOptions) => Router;
+        /**
+         * Check if a named route exists
+         */
+        hasRoute: (name: string) => boolean;
+        /**
+         * Get the current route
+         */
+        currentRoute: () => Route | null;
+        /**
+         * Get the current route name
+         */
+        currentRouteName: () => string | null;
+        /**
+         * Get URL for a named route
+         */
+        routeUrl: (name: string, params?: Record<string, string | number>) => string;
+    }
+}
+export {};

package/dist/router/fluent-routing.d.ts

@@ -0,0 +1,271 @@
+import type { BunQueryBuilderModel } from '../model-binding';
+import type { RouteCacheConfig } from '../routing/route-caching';
+import type { ThrottleConfig } from '../routing/route-throttling';
+import type { EnhancedRequest, MiddlewareHandler, RouteHandler, ThrottlePattern } from '../types';
+import { RouteCacheFactory } from '../routing/route-caching';
+import { ThrottleFactory } from '../routing/route-throttling';
+/**
+ * Fluent route builder with chainable API
+ */
+export declare class FluentRouteBuilder {
+    private method;
+    private path;
+    private handler;
+    private middleware;
+    private cacheConfig?;
+    private throttleConfig?;
+    private routeName?;
+    private modelBindings;
+    constructor(method: string, path: string, handler: RouteHandler);
+    /**
+     * Add middleware to route
+     */
+    addMiddleware(middleware: MiddlewareHandler | MiddlewareHandler[]): this;
+    /**
+     * Add route caching with tags
+     */
+    cached(tags?: string[], config?: Partial<RouteCacheConfig>): this;
+    /**
+     * Add route throttling with narrow type checking
+     */
+    throttle(limit: ThrottlePattern | ThrottleConfig, _name?: string): this;
+    /**
+     * Set route name
+     */
+    name(name: string): this;
+    /**
+     * Bind models to route parameters
+     */
+    model(parameter: string, model: BunQueryBuilderModel): this;
+    /**
+     * Build the final route configuration
+     */
+    build(): {
+        method: string;
+        path: string;
+        handler: RouteHandler;
+        middleware: MiddlewareHandler[];
+        name?: string;
+    };
+}
+/**
+ * Middleware condition function type
+ */
+export type MiddlewareCondition = (_request: EnhancedRequest) => boolean | Promise<boolean>;
+/**
+ * Conditional middleware wrapper
+ */
+export interface ConditionalMiddleware {
+    condition: MiddlewareCondition;
+    middleware: MiddlewareHandler[];
+}
+/**
+ * Builder for conditional middleware
+ */
+export declare class FluentConditionalBuilder {
+    private router;
+    private condition;
+    constructor(router: FluentRouter, condition: MiddlewareCondition);
+    middleware(middlewareName: string): this;
+}
+/**
+ * Builder for middleware with parameters
+ */
+export declare class FluentMiddlewareBuilder {
+    private router;
+    private middleware;
+    constructor(router: FluentRouter, middleware: MiddlewareHandler[]);
+    get(path: string, handler: RouteHandler): FluentRouteBuilder;
+    post(path: string, handler: RouteHandler): FluentRouteBuilder;
+    put(path: string, handler: RouteHandler): FluentRouteBuilder;
+    delete(path: string, handler: RouteHandler): FluentRouteBuilder;
+    patch(path: string, handler: RouteHandler): FluentRouteBuilder;
+}
+/**
+ * Builder for route groups with middleware
+ */
+export declare class FluentRouteGroupBuilder {
+    private router;
+    private groupMiddleware;
+    constructor(router: FluentRouter, groupMiddleware: MiddlewareHandler[]);
+    get(path: string, handler: RouteHandler): FluentRouteBuilder;
+    post(path: string, handler: RouteHandler): FluentRouteBuilder;
+    put(path: string, handler: RouteHandler): FluentRouteBuilder;
+    delete(path: string, handler: RouteHandler): FluentRouteBuilder;
+    patch(path: string, handler: RouteHandler): FluentRouteBuilder;
+}
+/**
+ * Fluent router with chainable API and advanced features
+ */
+export declare class FluentRouter {
+    private routes;
+    private globalMiddleware;
+    private subdomainRouter;
+    private routeGroups;
+    private middlewareGroups;
+    private namedMiddleware;
+    private conditionalMiddleware;
+    constructor();
+    /**
+     * Setup default named middleware with parameter support
+     */
+    private setupDefaultMiddleware;
+    /**
+     * Register a middleware group
+     */
+    middlewareGroup(name: string, middlewareNames: string[]): this;
+    /**
+     * Apply middleware group to routes
+     */
+    middlewareGroupRoutes(name: string): FluentRouteGroupBuilder;
+    /**
+     * Conditional middleware execution
+     */
+    when(condition: MiddlewareCondition): FluentConditionalBuilder;
+    /**
+     * Apply middleware with parameters
+     */
+    middleware(middlewareName: string): FluentMiddlewareBuilder;
+    /**
+     * Add global middleware
+     */
+    use(middleware: MiddlewareHandler): this;
+    /**
+     * Create a GET route
+     */
+    get(path: string, handler: RouteHandler): FluentRouteBuilder;
+    /**
+     * Create a POST route
+     */
+    post(path: string, handler: RouteHandler): FluentRouteBuilder;
+    /**
+     * Create a PUT route
+     */
+    put(path: string, handler: RouteHandler): FluentRouteBuilder;
+    /**
+     * Create a DELETE route
+     */
+    delete(path: string, handler: RouteHandler): FluentRouteBuilder;
+    /**
+     * Create a PATCH route
+     */
+    patch(path: string, handler: RouteHandler): FluentRouteBuilder;
+    /**
+     * Register a built route
+     */
+    register(builder: FluentRouteBuilder): this;
+    /**
+     * Create a cached route
+     */
+    cached(tags?: string[], config?: Partial<RouteCacheConfig>): {
+        get: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        post: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        put: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        delete: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        patch: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+    };
+    /**
+     * Create a throttled route
+     */
+    throttled(limit: ThrottlePattern | ThrottleConfig): {
+        get: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        post: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        put: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        delete: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+        patch: (path: string, handler: RouteHandler) => FluentRouteBuilder;
+    };
+    /**
+     * Create route group with shared attributes
+     */
+    group(config: {
+        prefix?: string;
+        middleware?: MiddlewareHandler[];
+        name?: string;
+        domain?: string;
+    }, callback: (router: FluentRouter) => void): this;
+    /**
+     * Create subdomain routing group
+     */
+    domain(pattern: string): {
+        routes: (callback: (router: FluentRouter) => void) => FluentRouter;
+    };
+    /**
+     * Create resource routes (Laravel-style)
+     */
+    resource(name: string, controller: any, options?: {
+        only?: string[];
+        except?: string[];
+        model?: BunQueryBuilderModel;
+    }): this;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): Array<{
+        method: string;
+        path: string;
+        handler: RouteHandler;
+        middleware: MiddlewareHandler[];
+        name?: string;
+    }>;
+    /**
+     * Handle incoming request
+     */
+    handle(request: EnhancedRequest): Promise<Response | null>;
+    /**
+     * Check if route matches request
+     */
+    private matchesRoute;
+    /**
+     * Execute route with middleware
+     */
+    private executeRoute;
+}
+/** API route options */
+export interface ApiRouteOptions {
+    method?: string;
+    cache?: string[];
+    throttle?: string;
+}
+/** Protected route options */
+export interface ProtectedRouteOptions {
+    method?: string;
+    roles?: string[];
+}
+/** Upload route options */
+export interface UploadRouteOptions {
+    maxSize?: number;
+    allowedTypes?: string[];
+}
+/**
+ * Factory functions for common route patterns
+ */
+export declare const RouteFactory: {
+    api: (path: string, handler: RouteHandler, options?: ApiRouteOptions) => FluentRouteBuilder;
+    protected: (path: string, handler: RouteHandler, options?: ProtectedRouteOptions) => FluentRouteBuilder;
+    upload: (path: string, handler: RouteHandler, options?: UploadRouteOptions) => FluentRouteBuilder;
+};
+/**
+ * Utility functions
+ */
+export declare const RouterUtils: {
+    /**
+     * Generate route URL with parameters
+     */
+    route: (name: string, params?: Record<string, string>, query?: Record<string, string>) => string;
+    /**
+     * Redirect response
+     */
+    redirect: (url: string, status?: number) => Response;
+    /**
+     * JSON response
+     */
+    json: (data: any, status?: number) => Response;
+};
+/**
+ * Global router instance
+ */
+export declare const router: FluentRouter;
+/**
+ * Export commonly used factory functions
+ */
+export { RouteCacheFactory, ThrottleFactory };

package/dist/router/group-organization.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from './router';
+/**
+ * Route grouping and organization extension for Router class
+ */
+export declare function registerGroupOrganization(RouterClass: typeof Router): void;

package/dist/router/handler-resolver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Handler Resolver
+ *
+ * Resolves route handlers from various formats:
+ * - Functions returning Response
+ * - Functions returning strings/objects (auto-wrapped)
+ * - String file paths like 'UserAction.ts' or './actions/UserAction'
+ * - Controller@method patterns like 'UserController@index'
+ * - Class constructors with handle() method
+ * - Class instances with handle() method
+ */
+import type { EnhancedRequest, RouterConfig } from '../types';
+/**
+ * Wraps a value in a Response object if it's not already a Response
+ */
+export declare function wrapResponse(value: unknown): Response;
+/**
+ * Resolves and executes a handler, returning a Response
+ */
+export declare function resolveHandler(handler: unknown, req: EnhancedRequest, config: RouterConfig): Promise<Response>;
+/**
+ * Creates a handler resolver bound to a specific config
+ */
+export declare function createHandlerResolver(config: RouterConfig): (handler: unknown, req: EnhancedRequest) => Promise<Response>;

package/dist/router/http-methods.d.ts

@@ -0,0 +1,10 @@
+import type { Router } from './router';
+/**
+ * HTTP methods extension for Router class
+ * Uses a class extension pattern instead of prototype manipulation
+ */
+export declare function registerHttpMethods(RouterClass: typeof Router): void;
+/**
+ * Register redirect methods on the Router class
+ */
+export declare function registerRedirectMethods(RouterClass: typeof Router): void;