@stacksjs/bun-router 0.0.5 → 0.0.6

package/dist/request/enhanced-request.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Enhanced Request Methods
+ *
+ * Implements fluent request methods with full TypeScript support
+ */
+import type { EnhancedRequest, RequestInput } from '../types';
+/**
+ * Validation rules type
+ */
+export type ValidationRules = Record<string, string | ValidationRule[]>;
+/**
+ * Validation rule interface
+ */
+export interface ValidationRule {
+    name: string;
+    validate: (value: unknown, parameters: string[], field: string, data: Record<string, unknown>) => Promise<boolean> | boolean;
+    message: string | ((_field: string, _parameters: string[]) => string);
+}
+/**
+ * Safe validated data wrapper
+ */
+export interface SafeData<T extends Record<string, unknown> = Record<string, unknown>> {
+    only: <K extends keyof T>(keys: K[]) => Pick<T, K>;
+    except: <K extends keyof T>(keys: K[]) => Omit<T, K>;
+    merge: <U extends Record<string, unknown>>(data: U) => T & U;
+    all: () => T;
+    has: (key: keyof T) => boolean;
+    get: <K extends keyof T>(key: K) => T[K];
+}
+/**
+ * Collection interface for array data
+ */
+export interface Collection<T> {
+    items: T[];
+    count: () => number;
+    first: () => T | undefined;
+    last: () => T | undefined;
+    map: <U>(fn: (item: T, index: number) => U) => Collection<U>;
+    filter: (fn: (item: T, index: number) => boolean) => Collection<T>;
+    find: (fn: (item: T, index: number) => boolean) => T | undefined;
+    reduce: <U>(fn: (acc: U, item: T, index: number) => U, initial: U) => U;
+    forEach: (fn: (item: T, index: number) => void) => void;
+    toArray: () => T[];
+    isEmpty: () => boolean;
+    isNotEmpty: () => boolean;
+    pluck: <K extends keyof T>(key: K) => Collection<T[K]>;
+    unique: () => Collection<T>;
+    sortBy: <K extends keyof T>(key: K, direction?: 'asc' | 'desc') => Collection<T>;
+    groupBy: <K extends keyof T>(key: K) => Map<T[K], Collection<T>>;
+    chunk: (size: number) => Collection<Collection<T>>;
+    take: (count: number) => Collection<T>;
+    skip: (count: number) => Collection<T>;
+    reverse: () => Collection<T>;
+    sum: (key?: keyof T) => number;
+    avg: (key?: keyof T) => number;
+    min: (key?: keyof T) => T | undefined;
+    max: (key?: keyof T) => T | undefined;
+}
+/**
+ * Collection class for array manipulation
+ */
+export declare class CollectionImpl<T> implements Collection<T> {
+    items: T[];
+    constructor(items: T[]);
+    count(): number;
+    first(): T | undefined;
+    last(): T | undefined;
+    map<U>(fn: (item: T, index: number) => U): Collection<U>;
+    filter(fn: (item: T, index: number) => boolean): Collection<T>;
+    find(fn: (item: T, index: number) => boolean): T | undefined;
+    reduce<U>(fn: (acc: U, item: T, index: number) => U, initial: U): U;
+    forEach(fn: (item: T, index: number) => void): void;
+    toArray(): T[];
+    isEmpty(): boolean;
+    isNotEmpty(): boolean;
+    pluck<K extends keyof T>(key: K): Collection<T[K]>;
+    unique(): Collection<T>;
+    sortBy<K extends keyof T>(key: K, direction?: 'asc' | 'desc'): Collection<T>;
+    groupBy<K extends keyof T>(key: K): Map<T[K], Collection<T>>;
+    chunk(size: number): Collection<Collection<T>>;
+    take(count: number): Collection<T>;
+    skip(count: number): Collection<T>;
+    reverse(): Collection<T>;
+    sum(key?: keyof T): number;
+    avg(key?: keyof T): number;
+    min(key?: keyof T): T | undefined;
+    max(key?: keyof T): T | undefined;
+}
+/**
+ * Create a safe data wrapper
+ */
+export declare function createSafeData<T extends Record<string, unknown>>(data: T): SafeData<T>;
+/**
+ * Enhanced request methods interface
+ */
+export interface EnhancedRequestMethods {
+    /**
+     * Validate the request data
+     */
+    validate: <T extends Record<string, unknown> = Record<string, unknown>>(rules: ValidationRules, messages?: Record<string, string>) => Promise<T>;
+    /**
+     * Get validated data as typed object
+     */
+    getValidated: <T extends Record<string, unknown> = Record<string, unknown>>() => T;
+    /**
+     * Get safe validated data wrapper
+     */
+    safe: <T extends Record<string, unknown> = Record<string, unknown>>() => SafeData<T>;
+    /**
+     * Execute callback when input has a value
+     */
+    whenHas: <T>(key: string, callback: (value: T) => void, defaultCallback?: () => void) => void;
+    /**
+     * Execute callback when input is filled (not empty)
+     */
+    whenFilled: <T>(key: string, callback: (value: T) => void, defaultCallback?: () => void) => void;
+    /**
+     * Parse date input
+     */
+    date: (key: string, format?: string) => Date | null;
+    /**
+     * Parse enum input
+     */
+    enum: <T extends Record<string, string | number>>(key: string, enumType: T) => T[keyof T] | null;
+    /**
+     * Get input as collection
+     */
+    collect: <T = unknown>(key: string) => Collection<T>;
+    /**
+     * Get all input keys
+     */
+    keys: () => string[];
+    /**
+     * Get input with type casting
+     */
+    string: (key: string, defaultValue?: string) => string;
+    integer: (key: string, defaultValue?: number) => number;
+    float: (key: string, defaultValue?: number) => number;
+    boolean: (key: string, defaultValue?: boolean) => boolean;
+    /**
+     * Check if input matches a value
+     */
+    isValue: (key: string, value: unknown) => boolean;
+    /**
+     * Get old input (for form repopulation)
+     */
+    old: <T = unknown>(key: string, defaultValue?: T) => T;
+    /**
+     * Flash input to session for form repopulation
+     */
+    flashInput: (keys?: string[]) => void;
+    /**
+     * Flash only specific keys
+     */
+    flashInputOnly: (keys: string[]) => void;
+    /**
+     * Flash except specific keys
+     */
+    flashInputExcept: (keys: string[]) => void;
+    /**
+     * Get input as array
+     */
+    array: <T = unknown>(key: string) => T[];
+    /**
+     * Get input value from any source (query, body, params)
+     * Laravel-style request.get()
+     */
+    get: <T = unknown>(key: string, defaultValue?: T) => T;
+    /**
+     * Get all input data
+     */
+    all: () => RequestInput;
+    /**
+     * Get only specified keys
+     */
+    only: <T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]) => T;
+    /**
+     * Get all except specified keys
+     */
+    except: <T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]) => T;
+    /**
+     * Check if input has a key
+     */
+    has: (key: string | string[]) => boolean;
+    /**
+     * Check if input has any of the keys
+     */
+    hasAny: (keys: string[]) => boolean;
+    /**
+     * Check if input is filled (not empty)
+     */
+    filled: (key: string | string[]) => boolean;
+    /**
+     * Check if input is missing
+     */
+    missing: (key: string | string[]) => boolean;
+    /**
+     * Merge additional data into input
+     */
+    merge: (data: Record<string, unknown>) => void;
+    /**
+     * Get input value or fail
+     */
+    input: <T = unknown>(key: string, defaultValue?: T) => T;
+}
+/**
+ * Enhance request with additional methods
+ */
+export declare function enhanceRequestWithMethods(request: EnhancedRequest): EnhancedRequest & EnhancedRequestMethods;
+/**
+ * Middleware to enhance request with additional methods
+ */
+export declare function enhancedRequestMiddleware(): (req: EnhancedRequest, next: () => Promise<Response | null>) => Promise<Response | null>;

package/dist/request/macros.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Request/Response Enhancements - Request Macros
+ *
+ * Laravel-style request macros for enhanced request functionality
+ */
+import type { EnhancedRequest } from '../types';
+export interface RequestMacro {
+    name: string;
+    handler: (this: EnhancedRequest, ...args: any[]) => any;
+}
+/**
+ * Request macro registry
+ */
+declare class RequestMacroRegistry {
+    private macros;
+    /**
+     * Register a request macro
+     */
+    register(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any): void;
+    /**
+     * Get a registered macro
+     */
+    get(name: string): RequestMacro | undefined;
+    /**
+     * Check if macro exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered macros
+     */
+    all(): RequestMacro[];
+    /**
+     * Remove a macro
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all macros
+     */
+    clear(): void;
+}
+/**
+ * Global request macro registry
+ */
+export declare const requestMacroRegistry: RequestMacroRegistry;
+/**
+ * Request class with macro support
+ */
+export declare class RequestWithMacros {
+    /**
+     * Register a request macro
+     */
+    static macro(name: string, handler: (this: EnhancedRequest, ...args: any[]) => any): void;
+    /**
+     * Apply macros to a request object
+     */
+    static applyMacros(request: EnhancedRequest): EnhancedRequest;
+    /**
+     * Check if macro exists
+     */
+    static hasMacro(name: string): boolean;
+}
+/**
+ * Built-in request macros
+ */
+export declare const BuiltInRequestMacros: {
+    /**
+     * Check if request wants JSON response
+     */
+    wantsJson(this: EnhancedRequest): boolean;
+    /**
+     * Check if request wants HTML response
+     */
+    wantsHtml(this: EnhancedRequest): boolean;
+    /**
+     * Check if request wants XML response
+     */
+    wantsXml(this: EnhancedRequest): boolean;
+    /**
+     * Check if request expects JSON response
+     */
+    expectsJson(this: EnhancedRequest): boolean;
+    /**
+     * Check if request is AJAX
+     */
+    isAjax(this: EnhancedRequest): boolean;
+    /**
+     * Check if request is PJAX
+     */
+    isPjax(this: EnhancedRequest): boolean;
+    /**
+     * Check if request is from mobile device
+     */
+    isMobile(this: EnhancedRequest): boolean;
+    /**
+     * Check if request is from bot/crawler
+     */
+    isBot(this: EnhancedRequest): boolean;
+    /**
+     * Check if request is secure (HTTPS)
+     */
+    isSecure(this: EnhancedRequest): boolean;
+    /**
+     * Get client IP address
+     */
+    ip(this: EnhancedRequest): string;
+    /**
+     * Get all client IPs (including proxies)
+     */
+    ips(this: EnhancedRequest): string[];
+    /**
+     * Get user agent
+     */
+    userAgent(this: EnhancedRequest): string;
+    /**
+     * Get referer URL
+     */
+    referer(this: EnhancedRequest): string | null;
+    /**
+     * Get authorization header
+     */
+    bearerToken(this: EnhancedRequest): string | null;
+    /**
+     * Get basic auth credentials
+     */
+    basicAuth(this: EnhancedRequest): {
+        username: string;
+        password: string;
+    } | null;
+    /**
+     * Check if request has specific header
+     */
+    hasHeader(this: EnhancedRequest, name: string): boolean;
+    /**
+     * Get header value with default
+     */
+    header(this: EnhancedRequest, name: string, defaultValue?: string): string | null;
+    /**
+     * Get all headers as object
+     */
+    allHeaders(this: EnhancedRequest): Record<string, string>;
+    /**
+     * Get input value from query, body, or params
+     */
+    input(this: EnhancedRequest, key: string, defaultValue?: any): any;
+    /**
+     * Get all input data
+     */
+    all(this: EnhancedRequest): Record<string, unknown>;
+    /**
+     * Get only specified input keys
+     */
+    only(this: EnhancedRequest, keys: string[]): Record<string, any>;
+    /**
+     * Get all input except specified keys
+     */
+    except(this: EnhancedRequest, keys: string[]): Record<string, any>;
+    /**
+     * Check if input has specific key
+     */
+    has(this: EnhancedRequest, key: string): boolean;
+    /**
+     * Check if input has any of the specified keys
+     */
+    hasAny(this: EnhancedRequest, keys: string[]): boolean;
+    /**
+     * Check if input is missing specific key
+     */
+    missing(this: EnhancedRequest, key: string): boolean;
+    /**
+     * Check if input is filled (not empty)
+     */
+    filled(this: EnhancedRequest, key: string): boolean;
+    /**
+     * Get query parameter
+     */
+    getQuery(this: EnhancedRequest, key?: string, defaultValue?: any): any;
+    /**
+     * Get route parameter
+     */
+    param(this: EnhancedRequest, key: string, defaultValue?: any): any;
+    /**
+     * Get cookie value
+     */
+    cookie(this: EnhancedRequest, name: string, defaultValue?: string): string | null;
+    /**
+     * Get all cookies
+     */
+    cookies(this: EnhancedRequest): Record<string, string>;
+    /**
+     * Get file from upload
+     */
+    file(this: EnhancedRequest, name: string): any;
+    /**
+     * Check if request has file upload
+     */
+    hasFile(this: EnhancedRequest, name: string): boolean;
+    /**
+     * Get request path without query string
+     */
+    path(this: EnhancedRequest): string;
+    /**
+     * Get request URL
+     */
+    fullUrl(this: EnhancedRequest): string;
+    /**
+     * Get request root URL
+     */
+    root(this: EnhancedRequest): string;
+    /**
+     * Check if path matches pattern
+     */
+    is(this: EnhancedRequest, pattern: string): boolean;
+    /**
+     * Get route name (if available)
+     */
+    route(this: EnhancedRequest): string | null;
+    /**
+     * Get request fingerprint for caching
+     */
+    fingerprint(this: EnhancedRequest): string;
+    /**
+     * Get request signature for security
+     */
+    signature(this: EnhancedRequest, secret: string): string;
+    /**
+     * Merge additional data into request
+     */
+    merge(this: EnhancedRequest, data: Record<string, any>): void;
+    /**
+     * Replace request data
+     */
+    replace(this: EnhancedRequest, data: Record<string, any>): void;
+    /**
+     * Get request age in milliseconds
+     */
+    age(this: EnhancedRequest): number;
+    /**
+     * Check if request is from trusted proxy
+     */
+    isFromTrustedProxy(this: EnhancedRequest, trustedProxies?: string[]): boolean;
+    /**
+     * Get request content length
+     */
+    contentLength(this: EnhancedRequest): number;
+    /**
+     * Get request content type
+     */
+    contentType(this: EnhancedRequest): string | null;
+    /**
+     * Check if request content type matches
+     */
+    isContentType(this: EnhancedRequest, type: string): boolean;
+};
+/**
+ * Register all built-in macros
+ */
+export declare function registerBuiltInRequestMacros(): void;
+/**
+ * Request macro factory functions
+ */
+export declare const RequestMacroFactory: {
+    /**
+     * Create input validation macro
+     */
+    validateInput: (_rules: Record<string, string>) => (this: EnhancedRequest) => boolean;
+    /**
+     * Create custom header checker macro
+     */
+    hasCustomHeader: (headerName: string) => (this: EnhancedRequest) => boolean;
+    /**
+     * Create role checker macro
+     */
+    hasRole: (role: string) => (this: EnhancedRequest) => boolean;
+    /**
+     * Create permission checker macro
+     */
+    can: (permission: string) => (this: EnhancedRequest) => boolean;
+};
+/**
+ * Request helper utilities
+ */
+export declare const RequestHelpers: {
+    /**
+     * Apply macros to request
+     */
+    withMacros: (request: EnhancedRequest) => EnhancedRequest;
+    /**
+     * Create request from URL and options
+     */
+    create: (url: string, options?: RequestInit) => EnhancedRequest;
+    /**
+     * Parse query string to object
+     */
+    parseQuery: (queryString: string) => Record<string, string>;
+    /**
+     * Parse cookies from header
+     */
+    parseCookies: (cookieHeader: string) => Record<string, string>;
+};
+export {};