@stacksjs/bun-router 0.0.5 → 0.0.7

package/dist/url.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Named-route URL generation
+ *
+ * A module-level registry of `name → path` populated by both `Router` and
+ * `FluentRouter` whenever a route is given a name. `url(name, params)`
+ * resolves a registered name into a URL with path parameters substituted
+ * and unmatched params appended as a query string.
+ */
+/**
+ * Register a named-route path. Called by Router/FluentRouter when a route
+ * gets a `.name()`.
+ */
+export declare function registerNamedRoute(name: string, path: string): void;
+/**
+ * Look up a registered named-route path without parameter substitution.
+ * Mostly useful for tests and tooling.
+ */
+export declare function getNamedRoutePath(name: string): string | undefined;
+/**
+ * Returns a snapshot of every registered named-route. The map itself is not
+ * exposed so callers can't mutate the registry.
+ */
+export declare function getNamedRoutes(): ReadonlyMap<string, string>;
+/**
+ * Clear the registry. Provided for tests; production code should not need it.
+ */
+export declare function clearNamedRoutes(): void;
+export interface UrlOptions {
+    /**
+     * Return a fully-qualified URL using `process.env.APP_URL` (falling back to
+     * `http://localhost`) instead of a path. Defaults to `false`.
+     */
+    absolute?: boolean;
+    /**
+     * Override the base used for `absolute: true`. Wins over `APP_URL`.
+     */
+    base?: string;
+}
+/**
+ * Generate a URL for a named route.
+ *
+ * @example
+ * ```ts
+ * router.get('/users/{id}', handler).name('users.show')
+ *
+ * url('users.show', { id: 42 })
+ * // → '/users/42'
+ *
+ * url('users.show', { id: 42, tab: 'profile' })
+ * // → '/users/42?tab=profile'
+ *
+ * url('users.show', { id: 42 }, { absolute: true })
+ * // → 'https://app.example/users/42'  (when APP_URL=https://app.example)
+ * ```
+ */
+export declare function url(name: string, params?: Record<string, string | number | boolean>, options?: UrlOptions): string;

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './query-preservation';

package/dist/utils/query-preservation.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Query Parameter Preservation
+ *
+ * Automatically preserves specified query parameters across navigation.
+ * This is useful for maintaining state like siteId, theme, locale, etc.
+ */
+export interface QueryPreservationConfig {
+    /**
+     * Whether query preservation is enabled
+     * Default: true when preserve array is non-empty
+     */
+    enabled?: boolean;
+    /**
+     * Query parameters to preserve across navigation
+     * Example: ['siteId', 'theme', 'locale']
+     */
+    preserve?: string[];
+    /**
+     * Query parameters to never preserve (takes precedence over preserve)
+     * Example: ['_t', 'utm_source']
+     */
+    exclude?: string[];
+    /**
+     * URL patterns where preservation should apply
+     * Default: all internal links (same origin)
+     * Example: ['/dashboard/*', '/admin/*']
+     */
+    routes?: string[];
+}
+/**
+ * Default configuration
+ */
+export declare const defaultQueryPreservationConfig: QueryPreservationConfig;
+/**
+ * Generate the client-side script for query preservation
+ * This script intercepts link clicks and preserves specified query params
+ */
+export declare function generateQueryPreservationScript(config: QueryPreservationConfig): string;
+/**
+ * Inject the query preservation script into HTML content
+ * Inserts before </head> or </body> if </head> not found
+ */
+export declare function injectQueryPreservationScript(html: string, config: QueryPreservationConfig): string;
+/**
+ * Build a URL with preserved query parameters
+ * Server-side utility for generating links
+ */
+export declare function buildUrlWithPreservedParams(path: string, currentUrl: string | URL, config: QueryPreservationConfig, additionalParams?: Record<string, string>): string;

package/dist/utils.d.ts

@@ -0,0 +1,69 @@
+import type { ActionHandler, ActionHandlerClass, RouteHandler } from './types';
+export * from './utils/query-preservation';
+/**
+ * Normalizes a path by ensuring it starts with a forward slash and has no trailing slash
+ * @param path The path to normalize
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * Converts a string path to an action path for dynamic imports
+ * @param path The path to convert (e.g., 'Actions/Home/IndexAction')
+ */
+export declare function toActionPath(path: string): string;
+/**
+ * Checks if a handler is a class constructor implementing ActionHandlerClass
+ * @param handler The handler to check
+ */
+export declare function isActionClass(handler: ActionHandler): handler is new () => ActionHandlerClass;
+/**
+ * Checks if a handler is a route handler function
+ * @param handler The handler to check
+ */
+export declare function isRouteHandler(handler: ActionHandler): handler is RouteHandler;
+/**
+ * Extracts named parameters from a path pattern
+ * @param pattern The path pattern (e.g., '/users/{id}/posts/{postId}')
+ */
+export declare function extractParamNames(pattern: string): string[];
+/**
+ * Creates a regex pattern from a path pattern
+ * @param pattern The path pattern
+ */
+export declare function createPathRegex(pattern: string): RegExp;
+/**
+ * Matches a path against a pattern and extracts parameters
+ * @param pattern The path pattern (e.g., '/users/{id}')
+ * @param path The actual path (e.g., '/users/123')
+ * @param params Output parameter object that will contain extracted parameters
+ * @param constraints Optional constraints for route parameters
+ * @returns Boolean indicating whether the path matches the pattern
+ */
+export declare function matchPath(pattern: string, path: string, params: Record<string, string>, constraints?: Record<string, string>): boolean;
+/**
+ * Joins path segments ensuring proper formatting
+ * @param segments Path segments to join
+ */
+export declare function joinPaths(...segments: string[]): string;
+/**
+ * Validates a route path format
+ * @param path The path to validate
+ */
+export declare function validatePath(path: string): boolean;
+/**
+ * Check if a file exists at the given path
+ * @param path The file path to check
+ */
+export declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Resolve a view name to an actual file path
+ * @param viewName The view name (without extension)
+ * @param viewsPath The base path for views
+ * @param extensions File extensions to try
+ */
+export declare function resolveViewPath(viewName: string, viewsPath: string, extensions: string[]): Promise<string | null>;
+/**
+ * Basic HTML template processing - replaces {{ varName }} with the corresponding value
+ * @param template The HTML template string
+ * @param data The data to inject into the template
+ */
+export declare function processHtmlTemplate(template: string, data: Record<string, any>): string;

package/dist/validation/validator.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Request/Response Enhancements - Validation System
+ *
+ * Laravel-style validation with custom rules and error handling
+ */
+import type { EnhancedRequest, NextFunction } from '../types';
+export interface ValidationRule {
+    name: string;
+    validate: (value: any, parameters: string[], field: string, data: Record<string, any>) => Promise<boolean> | boolean;
+    message: string | ((_field: string, _parameters: string[]) => string);
+}
+export interface ValidationRules {
+    [field: string]: string | ValidationRule[];
+}
+export interface ValidationErrors {
+    [field: string]: string[];
+}
+export interface ValidatorConfig {
+    stopOnFirstFailure?: boolean;
+    customMessages?: Record<string, string>;
+    customAttributes?: Record<string, string>;
+    bail?: boolean;
+}
+/**
+ * Built-in validation rules
+ */
+export declare const BuiltInRules: Record<string, ValidationRule>;
+/**
+ * Database validation rules (require external implementation)
+ */
+export declare const DatabaseRules: Record<string, ValidationRule>;
+/**
+ * Main validator class
+ */
+export declare class Validator {
+    private rules;
+    private config;
+    constructor(config?: ValidatorConfig);
+    /**
+     * Register validation rules
+     */
+    registerRule(rule: ValidationRule): void;
+    /**
+     * Register multiple validation rules
+     */
+    registerRules(rules: Record<string, ValidationRule>): void;
+    /**
+     * Parse validation rule string
+     */
+    private parseRuleString;
+    /**
+     * Validate data against rules
+     */
+    validate(data: Record<string, any>, rules: ValidationRules): Promise<ValidationErrors>;
+    /**
+     * Validate and throw exception if validation fails
+     */
+    validateOrFail(data: Record<string, any>, rules: ValidationRules): Promise<void>;
+    /**
+     * Get nested value from object using dot notation
+     */
+    private getNestedValue;
+    /**
+     * Format error message
+     */
+    private formatErrorMessage;
+    /**
+     * Replace placeholders in error messages
+     */
+    private replacePlaceholders;
+}
+/**
+ * Global validator instance
+ */
+export declare const globalValidator: Validator;
+/**
+ * Validation middleware factory
+ */
+export declare function createValidationMiddleware(rules: ValidationRules, config?: ValidatorConfig): (req: EnhancedRequest, next: NextFunction) => Promise<Response | null>;
+/**
+ * Validation rule builder for fluent API
+ */
+export declare class ValidationRuleBuilder {
+    private rules;
+    required(): this;
+    string(): this;
+    number(): this;
+    integer(): this;
+    boolean(): this;
+    email(): this;
+    url(): this;
+    min(value: number): this;
+    max(value: number): this;
+    between(min: number, max: number): this;
+    in(...values: string[]): this;
+    notIn(...values: string[]): this;
+    regex(pattern: string): this;
+    alpha(): this;
+    alphaNum(): this;
+    alphaDash(): this;
+    date(): this;
+    after(date: string): this;
+    before(date: string): this;
+    confirmed(field?: string): this;
+    same(field: string): this;
+    different(field: string): this;
+    json(): this;
+    uuid(): this;
+    array(): this;
+    object(): this;
+    unique(table: string, column?: string): this;
+    exists(table: string, column?: string): this;
+    custom(ruleName: string, ...parameters: string[]): this;
+    build(): string;
+}
+/**
+ * Factory function to create validation rule builder
+ */
+export declare function rule(): ValidationRuleBuilder;
+/**
+ * Validation helper functions
+ */
+export declare const ValidationHelpers: {
+    /**
+     * Create validation rules object
+     */
+    rules(rules: Record<string, string | ValidationRuleBuilder>): ValidationRules;
+    /**
+     * Validate single value
+     */
+    validateValue(value: any, rules: string, field?: string): Promise<string[]>;
+    /**
+     * Check if value passes validation
+     */
+    passes(value: any, rules: string): Promise<boolean>;
+    /**
+     * Check if value fails validation
+     */
+    fails(value: any, rules: string): Promise<boolean>;
+};

package/dist/websocket/clustering.d.ts

@@ -0,0 +1,185 @@
+/**
+ * WebSocket Clustering
+ *
+ * Native WebSocket clustering across workers with high-performance optimizations
+ */
+import type { ServerWebSocket } from 'bun';
+import type { Buffer } from 'node:buffer';
+export interface WebSocketClusterConfig {
+    workers?: number;
+    maxConnections?: number;
+    heartbeatInterval?: number;
+    compression?: boolean;
+    backpressureLimit?: number;
+    closeOnBackpressureLimit?: boolean;
+    idleTimeout?: number;
+    maxPayloadLength?: number;
+}
+export interface ClusterMessage {
+    type: 'broadcast' | 'direct' | 'join' | 'leave' | 'heartbeat' | 'stats';
+    workerId?: string;
+    targetId?: string;
+    roomId?: string;
+    data?: any;
+    timestamp: number;
+}
+export interface WebSocketConnection {
+    id: string;
+    workerId: string;
+    socket: ServerWebSocket<any>;
+    rooms: Set<string>;
+    metadata: Record<string, any>;
+    lastHeartbeat: number;
+    connected: boolean;
+}
+export interface WebSocketRoom {
+    id: string;
+    connections: Set<string>;
+    metadata: Record<string, any>;
+    created: number;
+}
+export interface ClusterStats {
+    totalConnections: number;
+    totalRooms: number;
+    workerStats: Record<string, {
+        connections: number;
+        rooms: number;
+        memoryUsage: number;
+        uptime: number;
+    }>;
+    messagesSent: number;
+    messagesReceived: number;
+    bytesTransferred: number;
+}
+/**
+ * WebSocket cluster manager for distributing connections across workers
+ */
+export declare class WebSocketCluster {
+    private config;
+    private workers;
+    private connections;
+    private rooms;
+    private messageHandlers;
+    private stats;
+    private heartbeatTimer?;
+    private isMainWorker;
+    private workerId;
+    constructor(config?: WebSocketClusterConfig);
+    /**
+     * Create WebSocket server with clustering support
+     */
+    createServer(options?: {
+        port?: number;
+        hostname?: string;
+        onConnection?: (ws: ServerWebSocket<any>, request: Request) => void;
+        onMessage?: (ws: ServerWebSocket<any>, message: string | Buffer) => void;
+        onClose?: (ws: ServerWebSocket<any>, code?: number, reason?: string) => void;
+        onError?: (ws: ServerWebSocket<any>, error: Error) => void;
+    }): any;
+    /**
+     * Join a connection to a room
+     */
+    joinRoom(connectionId: string, roomId: string, metadata?: Record<string, any>): boolean;
+    /**
+     * Remove a connection from a room
+     */
+    leaveRoom(connectionId: string, roomId: string): boolean;
+    /**
+     * Broadcast message to all connections in a room
+     */
+    broadcastToRoom(roomId: string, message: string | Buffer, excludeConnectionId?: string): number;
+    /**
+     * Send message to specific connection
+     */
+    sendToConnection(connectionId: string, message: string | Buffer): boolean;
+    /**
+     * Get cluster statistics
+     */
+    getStats(): ClusterStats;
+    /**
+     * Get connections in a room
+     */
+    getRoomConnections(roomId: string): string[];
+    /**
+     * Get rooms for a connection
+     */
+    getConnectionRooms(connectionId: string): string[];
+    /**
+     * Close connection
+     */
+    closeConnection(connectionId: string, code?: number, reason?: string): boolean;
+    /**
+     * Shutdown cluster
+     */
+    shutdown(): void;
+    /**
+     * Generate unique connection ID
+     */
+    private generateConnectionId;
+    /**
+     * Generate unique worker ID
+     */
+    private generateWorkerId;
+    /**
+     * Initialize statistics
+     */
+    private initializeStats;
+    /**
+     * Setup worker communication
+     */
+    private setupWorkerCommunication;
+    /**
+     * Handle messages from other workers
+     */
+    private handleWorkerMessage;
+    /**
+     * Handle cluster messages from connections
+     */
+    private handleClusterMessage;
+    /**
+     * Broadcast message to all workers
+     */
+    private broadcastToWorkers;
+    /**
+     * Start heartbeat timer
+     */
+    private startHeartbeat;
+    /**
+     * Update worker statistics
+     */
+    private updateWorkerStats;
+}
+/**
+ * WebSocket cluster factory
+ */
+export declare class WebSocketClusterFactory {
+    /**
+     * Create WebSocket cluster with default configuration
+     */
+    static create(config?: WebSocketClusterConfig): WebSocketCluster;
+    /**
+     * Create high-performance cluster for production
+     */
+    static createHighPerformance(): WebSocketCluster;
+    /**
+     * Create development cluster with debugging
+     */
+    static createDevelopment(): WebSocketCluster;
+}
+/**
+ * WebSocket cluster helpers
+ */
+export declare const WebSocketClusterHelpers: {
+    /**
+     * Create room-based chat system
+     */
+    createChatSystem: (cluster: WebSocketCluster) => any;
+    /**
+     * Create real-time notifications system
+     */
+    createNotificationSystem: (cluster: WebSocketCluster) => any;
+    /**
+     * Create presence system
+     */
+    createPresenceSystem: (cluster: WebSocketCluster) => any;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/bun-router",
   "type": "module",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "A fast, type-safe router for Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -54,7 +54,8 @@
   },
   "files": [
     "README.md",
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "bun --bun build.ts && bun run compile",