@stacksjs/bun-router 0.0.2

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

@@ -0,0 +1,143 @@
+import type { EnhancedRequest, RequestInput,  } from '../types';
+/**
+ * Create a safe data wrapper
+ */
+export declare function createSafeData<T extends Record<string, unknown>>(data: T): SafeData<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(): void;
+/**
+ * Validation rule interface
+ */
+export declare 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 declare 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 declare 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
+}
+/**
+ * Enhanced request methods interface
+ */
+export declare interface EnhancedRequestMethods {
+  validate: <T extends Record<string, unknown> = Record<string, unknown>>(
+    rules: ValidationRules,
+    messages?: Record<string, string>,
+  ) => Promise<T>
+  getValidated: <T extends Record<string, unknown> = Record<string, unknown>>() => T
+  safe: <T extends Record<string, unknown> = Record<string, unknown>>() => SafeData<T>
+  whenHas: <T>(
+    key: string,
+    callback: (value: T) => void,
+    defaultCallback?: () => void,
+  ) => void
+  whenFilled: <T>(
+    key: string,
+    callback: (value: T) => void,
+    defaultCallback?: () => void,
+  ) => void
+  date: (key: string, format?: string) => Date | null
+  enum: <T extends Record<string, string | number>>(
+    key: string,
+    enumType: T,
+  ) => T[keyof T] | null
+  collect: <T = unknown>(key: string) => Collection<T>
+  keys: () => string[]
+  string: (key: string, defaultValue?: string) => string
+  integer: (key: string, defaultValue?: number) => number
+  float: (key: string, defaultValue?: number) => number
+  boolean: (key: string, defaultValue?: boolean) => boolean
+  isValue: (key: string, value: unknown) => boolean
+  old: <T = unknown>(key: string, defaultValue?: T) => T
+  flashInput: (keys?: string[]) => void
+  flashInputOnly: (keys: string[]) => void
+  flashInputExcept: (keys: string[]) => void
+  array: <T = unknown>(key: string) => T[]
+  get: <T = unknown>(key: string, defaultValue?: T) => T
+  all: () => RequestInput
+  only: <T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]) => T
+  except: <T extends Record<string, unknown> = Record<string, unknown>>(keys: string[]) => T
+  has: (key: string | string[]) => boolean
+  hasAny: (keys: string[]) => boolean
+  filled: (key: string | string[]) => boolean
+  missing: (key: string | string[]) => boolean
+  merge: (data: Record<string, unknown>) => void
+  input: <T = unknown>(key: string, defaultValue?: T) => T
+}
+/**
+ * Validation rules type
+ */
+export type ValidationRules = Record<string, string | ValidationRule[]>
+/**
+ * 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;
+}

package/dist/request/macros.d.ts

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

package/dist/response/macros.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Register all built-in macros
+ */
+export declare function registerBuiltInResponseMacros(): void;
+/**
+ * Global response macro registry
+ */
+export declare const responseMacroRegistry: ResponseMacroRegistry;
+/**
+ * Built-in response macros
+ */
+export declare const BuiltInResponseMacros: {
+  /**
+   * Success response with data
+   */
+  success: (data?: any, message?: string, status?) => any;
+  /**
+   * Error response with message and errors
+   */
+  error: (message: string, errors?: Record<string, string[]>, status?) => any;
+  /**
+   * Validation error response
+   */
+  validationError: (errors: Record<string, string[]>, message?) => any;
+  /**
+   * Not found response
+   */
+  notFound: (message?) => any;
+  /**
+   * Unauthorized response
+   */
+  unauthorized: (message?) => any;
+  /**
+   * Forbidden response
+   */
+  forbidden: (message?) => any;
+  /**
+   * Internal server error response
+   */
+  serverError: (message?) => any;
+  /**
+   * Created response
+   */
+  created: (data?: any, message?) => any;
+  /**
+   * Updated response
+   */
+  updated: (data?: any, message?) => any;
+  /**
+   * Deleted response
+   */
+  deleted: (message?) => any;
+  /**
+   * No content response
+   */
+  noContent: () => any;
+  /**
+   * Accepted response
+   */
+  accepted: (data?: any, message?) => any;
+  /**
+   * Paginated response
+   */
+  paginated: unknown;
+  /**
+   * JSON response with custom headers
+   */
+  json: (data: any, status?, headers: Record<string, string> = {}) => any;
+  /**
+   * HTML response
+   */
+  html: (content: string, status?, headers: Record<string, string> = {}) => any;
+  /**
+   * Plain text response
+   */
+  text: (content: string, status?, headers: Record<string, string> = {}) => any;
+  /**
+   * XML response
+   */
+  xml: (content: string, status?, headers: Record<string, string> = {}) => any;
+  /**
+   * Redirect response
+   */
+  redirect: (url: string, status?) => any;
+  /**
+   * Permanent redirect response
+   */
+  permanentRedirect: (url: string) => any;
+  /**
+   * Download response
+   */
+  download: ( data: ArrayBuffer | Uint8Array | string, filename: string, contentType?, ) => any;
+  /**
+   * Stream response
+   */
+  stream: ( stream: ReadableStream, contentType?, headers: Record<string, string> = {}, ) => any;
+  /**
+   * Cache response with headers
+   */
+  cache: ( data: any, maxAge?, isPublic?, etag?: string, ) => any;
+  /**
+   * CORS response
+   */
+  cors: ( data: any, origin?, methods?,POST,PUT,DELETE,OPTIONS', headers?,Authorization', ) => any;
+  /**
+   * Server-Sent Events response
+   */
+  sse: (data: string, event?: string, id?: string) => any;
+  /**
+   * Health check response
+   */
+  health: (status: 'healthy' | 'unhealthy' | 'degraded' = 'healthy', checks: Record<string, any> = {}) => any
+};
+/**
+ * Response macro factory functions
+ */
+export declare const ResponseMacroFactory: {
+  /**
+   * Create API response macro
+   */
+  api: (defaultMeta?: Record<string, any>) => unknown;
+  /**
+   * Create versioned API response macro
+   */
+  versionedApi: (version: string) => unknown;
+  /**
+   * Create custom error response macro
+   */
+  customError: (defaultStatus: number?, defaultMessage: string?) => (message?: string, errors?: Record<string, string[]>, status?: number) => any
+};
+/**
+ * Response helper utilities
+ */
+export declare const ResponseHelpers: {
+  /**
+   * Check if response is successful
+   */
+  isSuccess: (response: Response) => any;
+  /**
+   * Check if response is error
+   */
+  isError: (response: Response) => any;
+  /**
+   * 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>) => any;
+  /**
+   * Clone response with new status
+   */
+  withStatus: (response: Response, status: number, statusText?: string) => any
+};
+export declare interface ResponseMacro {
+  name: string
+  handler: (...args: any[]) => Response
+}
+export declare 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 declare 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: Map<string, ResponseMacro>;
+  register(name: string, handler: (...args: any[]) => Response): void;
+  get(name: string): ResponseMacro | undefined;
+  has(name: string): boolean;
+  all(): ResponseMacro[];
+  remove(name: string): boolean;
+  clear(): void;
+}
+/**
+ * Response class with macro support
+ */
+export declare class ResponseWithMacros extends Response {
+  static macro(name: string, handler: (...args: any[]) => Response): void;
+  static callMacro(name: string, args: any[]): Response;
+  static hasMacro(name: string): boolean;
+}

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

@@ -0,0 +1,93 @@
+import type { ContentType, ResponseStatus } from '../types';
+/**
+ * Create a new response builder
+ */
+export declare function responseBuilder(): ResponseBuilder;
+/**
+ * Response factory with common response helpers
+ */
+export declare const response: ResponseFactory;
+/**
+ * JSON response options
+ */
+export declare interface JsonResponseOptions {
+  status?: ResponseStatus
+  headers?: Record<string, string>
+  pretty?: boolean
+}
+/**
+ * Download response options
+ */
+export declare interface DownloadOptions {
+  filename?: string
+  headers?: Record<string, string>
+  disposition?: 'attachment' | 'inline'
+}
+/**
+ * Stream download options
+ */
+export declare interface StreamDownloadOptions extends DownloadOptions {
+  contentType?: ContentType
+}
+/**
+ * Cookie options for response
+ */
+export declare interface ResponseCookieOptions {
+  maxAge?: number
+  expires?: Date
+  httpOnly?: boolean
+  secure?: boolean
+  path?: string
+  domain?: string
+  sameSite?: 'strict' | 'lax' | 'none'
+}
+// ============================================================================
+// Response Factory Interface
+// ============================================================================
+export declare 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
+}
+/**
+ * Fluent response builder
+ */
+export declare class ResponseBuilder {
+  private _status: ResponseStatus;
+  private _headers: Record<string, string>;
+  private _cookies: Array<{ name: string, value: string, options: ResponseCookieOptions }>;
+  private _deleteCookies: Array<{ name: string, options: Pick<ResponseCookieOptions, 'path' | 'domain'> }>;
+  status(code: ResponseStatus): this;
+  header(name: string, value: string): this;
+  withHeaders(headers: Record<string, string>): this;
+  cookie(name: string, value: string, options?: ResponseCookieOptions): this;
+  withoutCookie(name: string, options?: Pick<ResponseCookieOptions, 'path' | 'domain'>): this;
+  json<T>(data: T): Response;
+  text(content: string): Response;
+  html(content: string): Response;
+  noContent(): Response;
+  private applyCookies(res: Response): Response;
+  private serializeCookie(name: string, value: string, options: ResponseCookieOptions): string;
+}