@stacksjs/bun-router 0.0.2

package/dist/types/middleware-types.d.ts

@@ -0,0 +1,315 @@
+import type { RouteHandler, TypedRequest } from './route-inference';
+// Base middleware interface with generic constraints
+export declare interface TypedMiddleware<TInput = any, TOutput = TInput, _TContext = object, TNext = any> {
+  (request: TInput, next: TNext): Promise<TOutput> | TOutput
+}
+// Authentication middleware types
+export declare interface AuthenticatedRequest<TUser = any> {
+  user: TUser
+  isAuthenticated: true
+}
+export declare interface UnauthenticatedRequest {
+  user?: never
+  isAuthenticated: false
+}
+// Authorization middleware types
+export declare interface AuthorizedRequest<TPermissions extends string = string> {
+  permissions: TPermissions[]
+  hasPermission: (permission: TPermissions) => boolean
+}
+// Validation middleware types
+export declare interface ValidatedRequest<TParams = any, TQuery = any, TBody = any> {
+  validatedParams: TParams
+  validatedQuery: TQuery
+  validatedBody: TBody
+}
+// Rate limiting middleware types
+export declare interface RateLimitedRequest {
+  rateLimit: {
+    remaining: number
+    reset: Date
+    limit: number
+  }
+}
+// Caching middleware types
+export declare interface CachedRequest {
+  cache: {
+    key: string
+    ttl: number
+    hit: boolean
+  }
+}
+// Logging middleware types
+export declare interface LoggedRequest {
+  requestId: string
+  startTime: number
+  logger: {
+    info: (message: string, meta?: any) => void
+    warn: (message: string, meta?: any) => void
+    error: (message: string, meta?: any) => void
+  }
+}
+// CORS middleware types
+export declare interface CORSRequest {
+  cors: {
+    origin: string
+    methods: string[]
+    headers: string[]
+    credentials: boolean
+  }
+}
+// File upload middleware types
+export declare interface FileUploadRequest<TFiles extends Record<string, any> = Record<string, File>> {
+  files: TFiles
+  formData: FormData
+}
+// Session middleware types
+export declare interface SessionRequest<TSession = any> {
+  session: TSession & {
+    id: string
+    save: () => Promise<void>
+    destroy: () => Promise<void>
+    regenerate: () => Promise<void>
+  }
+}
+// Middleware factory types
+export declare interface MiddlewareFactory<TOptions = any, TMiddleware extends TypedMiddleware<any, any, any, any> = any> {
+  (options?: TOptions): TMiddleware
+}
+// Middleware group types
+export declare interface MiddlewareGroup<TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[]> {
+  middlewares: TMiddlewares
+  compose: () => MiddlewareChain<TMiddlewares>
+}
+// Error handling middleware types
+export declare interface ErrorHandlingRequest {
+  error?: Error
+  errorHandled: boolean
+}
+// Middleware pipeline types
+export declare interface MiddlewarePipeline<T extends readonly TypedMiddleware<any, any, any, any>[]> {
+  middlewares: T
+  execute: <TRequest>(request: TRequest) => Promise<
+    T extends readonly []
+      ? TRequest
+      : MiddlewareChain<T> extends TypedMiddleware<TRequest, infer Output, any, any>
+        ? Output
+        : never
+  >
+}
+// Advanced middleware constraints
+export declare interface MiddlewareConstraint<T> {
+  input: T extends TypedMiddleware<infer Input, any, any, any> ? Input : never
+  output: T extends TypedMiddleware<any, infer Output, any, any> ? Output : never
+  context: T extends TypedMiddleware<any, any, infer Context, any> ? Context : never
+}
+// Middleware builder interface
+export declare interface MiddlewareBuilder<TContext = object> {
+  use: <TNewContext>(
+    middleware: TypedMiddleware<any, any, TNewContext, any>
+  ) => MiddlewareBuilder<TContext & TNewContext>
+  auth: <TUser>(
+    middleware: AuthMiddleware<TUser>
+  ) => MiddlewareBuilder<TContext & { auth: { user: TUser } }>
+  validate: <TParams, TQuery, TBody>(
+    middleware: ValidationMiddleware<TParams, TQuery, TBody>
+  ) => MiddlewareBuilder<TContext & { validation: { params: TParams, query: TQuery, body: TBody } }>
+  rateLimit: (
+    middleware: RateLimitMiddleware
+  ) => MiddlewareBuilder<TContext & { rateLimit: RateLimitedRequest['rateLimit'] }>
+  cache: (
+    middleware: CacheMiddleware
+  ) => MiddlewareBuilder<TContext & { cache: CachedRequest['cache'] }>
+  cors: (
+    middleware: CORSMiddleware
+  ) => MiddlewareBuilder<TContext & { cors: CORSRequest['cors'] }>
+  session: <TSession>(
+    middleware: SessionMiddleware<TSession>
+  ) => MiddlewareBuilder<TContext & { session: SessionRequest<TSession>['session'] }>
+  build: () => TypedMiddleware<Request, Request & TContext, TContext, any>[]
+}
+// Middleware execution context
+export declare interface MiddlewareExecutionContext<TContext = object> {
+  request: Request
+  response?: Response
+  context: TContext
+  next: () => Promise<Response>
+  skip: () => void
+  abort: (response: Response) => void
+}
+// Middleware hooks
+export declare interface MiddlewareHooks<TContext = object> {
+  beforeExecution?: (context: MiddlewareExecutionContext<TContext>) => Promise<void> | void
+  afterExecution?: (context: MiddlewareExecutionContext<TContext>, result: any) => Promise<void> | void
+  onError?: (context: MiddlewareExecutionContext<TContext>, error: Error) => Promise<Response> | Response
+}
+// Middleware metadata
+export declare interface MiddlewareMetadata {
+  name: string
+  version?: string
+  description?: string
+  dependencies?: string[]
+  tags?: string[]
+  priority?: number
+}
+// Decorated middleware
+export declare interface DecoratedMiddleware<TInput = any, TOutput = TInput, TContext = object, TNext = any> extends TypedMiddleware<TInput, TOutput, TContext, TNext> {
+  metadata: MiddlewareMetadata
+}
+// Middleware registry
+export declare interface MiddlewareRegistry {
+  register: <T extends TypedMiddleware<any, any, any, any>>(
+    name: string,
+    middleware: T,
+    metadata?: Partial<MiddlewareMetadata>
+  ) => void
+  get: <T extends TypedMiddleware<any, any, any, any>>(name: string) => T | undefined
+  list: () => Array<{ name: string, middleware: TypedMiddleware<any, any, any, any>, metadata: MiddlewareMetadata }>
+  resolve: (dependencies: string[]) => TypedMiddleware<any, any, any, any>[]
+}
+// Middleware performance tracking
+export declare interface MiddlewarePerformance {
+  name: string
+  executionTime: number
+  memoryUsage: number
+  callCount: number
+  errorCount: number
+}
+// Middleware context augmentation
+export type AugmentContext<TBase, TAddition> = TBase & TAddition
+// Request augmentation through middleware
+export type AugmentRequest<TRequest, TAugmentation> = TRequest & TAugmentation
+// Middleware chain type inference
+export type MiddlewareChain<T extends readonly any[]> = T extends readonly [
+  infer First,
+  ...infer Rest,
+]
+  ? First extends TypedMiddleware<infer Input, infer Output, infer Context, any>
+    ? Rest extends readonly []
+      ? TypedMiddleware<Input, Output, Context, any>
+      : Rest extends readonly TypedMiddleware<Output, any, any, any>[]
+        ? MiddlewareChain<Rest> extends TypedMiddleware<Output, infer FinalOutput, infer RestContext, any>
+          ? TypedMiddleware<Input, FinalOutput, Context & RestContext, any>
+          : never
+        : never
+    : never
+  : never
+// Middleware composition types
+export type ComposeMiddleware<TFirst extends TypedMiddleware<any, any, any, any>, TSecond extends TypedMiddleware<any, any, any, any>> = TFirst extends TypedMiddleware<infer Input1, infer Output1, infer Context1, any>
+  ? TSecond extends TypedMiddleware<Output1, infer Output2, infer Context2, any>
+    ? TypedMiddleware<Input1, Output2, Context1 & Context2, any>
+    : never
+  : never
+export type AuthMiddleware<TUser = any> = TypedMiddleware<
+  Request,
+  Request & AuthenticatedRequest<TUser>,
+  { auth: { user: TUser } },
+  any
+>
+export type AuthzMiddleware<TPermissions extends string = string> = TypedMiddleware<
+  Request & AuthenticatedRequest,
+  Request & AuthenticatedRequest & AuthorizedRequest<TPermissions>,
+  { authz: { permissions: TPermissions[] } },
+  any
+>
+export type ValidationMiddleware<TParams = any, TQuery = any, TBody = any> = TypedMiddleware<
+  Request,
+  Request & ValidatedRequest<TParams, TQuery, TBody>,
+  { validation: { params: TParams, query: TQuery, body: TBody } },
+  any
+>
+export type RateLimitMiddleware = TypedMiddleware<
+  Request,
+  Request & RateLimitedRequest,
+  { rateLimit: RateLimitedRequest['rateLimit'] },
+  any
+>
+export type CacheMiddleware = TypedMiddleware<
+  Request,
+  Request & CachedRequest,
+  { cache: CachedRequest['cache'] },
+  any
+>
+export type LoggingMiddleware = TypedMiddleware<
+  Request,
+  Request & LoggedRequest,
+  { logging: { requestId: string, logger: LoggedRequest['logger'] } },
+  any
+>
+export type CORSMiddleware = TypedMiddleware<
+  Request,
+  Request & CORSRequest,
+  { cors: CORSRequest['cors'] },
+  any
+>
+export type FileUploadMiddleware<TFiles extends Record<string, any> = Record<string, File>> = TypedMiddleware<
+  Request,
+  Request & FileUploadRequest<TFiles>,
+  { upload: { files: TFiles } },
+  any
+>
+export type SessionMiddleware<TSession = any> = TypedMiddleware<
+  Request,
+  Request & SessionRequest<TSession>,
+  { session: SessionRequest<TSession>['session'] },
+  any
+>
+// Conditional middleware types
+export type ConditionalMiddleware<_TCondition extends (req: any) => boolean, TMiddleware extends TypedMiddleware<any, any, any, any>> = TypedMiddleware<
+  Parameters<TMiddleware>[0],
+  TMiddleware extends TypedMiddleware<any, infer Output, any, any> ? Output : never,
+  TMiddleware extends TypedMiddleware<any, any, infer Context, any> ? Context : object,
+  any
+>
+export type ErrorMiddleware = TypedMiddleware<
+  Request & { error: Error },
+  Response,
+  { error: { handled: boolean } },
+  any
+>
+// Middleware compatibility checking
+export type MiddlewareCompatible<TFirst extends TypedMiddleware<any, any, any, any>, TSecond extends TypedMiddleware<any, any, any, any>> = MiddlewareConstraint<TFirst>['output'] extends MiddlewareConstraint<TSecond>['input']
+  ? true
+  : false
+// Route-specific middleware types
+export type RouteMiddleware<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object> = TypedMiddleware<
+  TypedRequest<TPath, TQuery, TBody, TContext>,
+  TypedRequest<TPath, TQuery, TBody, TContext>,
+  TContext,
+  RouteHandler<TPath, TQuery, TBody, TContext>
+>
+// Async middleware types
+export type AsyncMiddleware<TInput = any, TOutput = TInput, TContext = object, TNext = any> = TypedMiddleware<TInput, Promise<TOutput>, TContext, TNext>
+// Middleware composition utilities
+export type Compose<T extends readonly TypedMiddleware<any, any, any, any>[]> = T extends readonly [infer First, ...infer Rest]
+    ? First extends TypedMiddleware<infer Input, infer Output, infer Context, any>
+      ? Rest extends readonly TypedMiddleware<any, any, any, any>[]
+        ? Rest extends readonly []
+          ? TypedMiddleware<Input, Output, Context, any>
+          : Compose<Rest> extends TypedMiddleware<Output, infer FinalOutput, infer RestContext, any>
+            ? TypedMiddleware<Input, FinalOutput, Context & RestContext, any>
+            : never
+        : never
+      : never
+    : TypedMiddleware<any, any, object, any>
+// Middleware type guards
+export type IsMiddleware<T> = T extends TypedMiddleware<any, any, any, any> ? true : false
+export type IsCompatibleMiddleware<T1, T2> = T1 extends TypedMiddleware<any, infer Output1, any, any>
+    ? T2 extends TypedMiddleware<Output1, any, any, any>
+      ? true
+      : false
+    : false
+// Middleware transformation types
+export type TransformMiddleware<TMiddleware extends TypedMiddleware<any, any, any, any>, TNewInput, TNewOutput = TNewInput> = TMiddleware extends TypedMiddleware<any, any, infer Context, any>
+  ? TypedMiddleware<TNewInput, TNewOutput, Context, any>
+  : never
+// Route-aware middleware
+export type RouteAwareMiddleware<TRoutes extends Record<string, any> = object> = {
+  [K in keyof TRoutes]: TRoutes[K] extends RouteHandler<infer Path, infer Query, infer Body, infer Context>
+    ? RouteMiddleware<Path, Query, Body, Context>
+    : never
+}
+export type PerformanceTrackingMiddleware<T extends TypedMiddleware<any, any, any, any>> = T & {
+    getPerformanceMetrics: () => MiddlewarePerformance
+    resetMetrics: () => void
+  }

package/dist/types/request-response-augmentation.d.ts

@@ -0,0 +1,373 @@
+import type { AuthenticatedRequest, AuthorizedRequest, CachedRequest, CORSRequest, FileUploadRequest, LoggedRequest, RateLimitedRequest, SessionRequest, TypedMiddleware, ValidatedRequest,  } from './middleware-types';
+import type { ExtractQueryParams, ExtractTypedParams, TypedRequest,  } from './route-inference';
+// Base augmentation interface
+export declare interface RequestAugmentation {
+
+}
+export declare interface ResponseAugmentation {
+
+}
+// Enhanced response with middleware augmentations
+export declare interface EnhancedResponse<TAugmentations = object> extends Response {
+  cached?: TAugmentations extends { cache: any }
+    ? boolean
+    : never
+  rateLimited?: TAugmentations extends { rateLimit: any }
+    ? boolean
+    : never
+  requestId?: TAugmentations extends { logging: any }
+    ? string
+    : never
+  executionTime?: TAugmentations extends { logging: any }
+    ? number
+    : never
+}
+// Augmentation builder
+export declare interface AugmentationBuilder<TBase = Request> {
+  withAuth: <TUser>(
+    middleware: TypedMiddleware<any, any, { auth: { user: TUser } }, any>
+  ) => AugmentationBuilder<TBase & AuthenticatedRequest<TUser>>
+  withValidation: <TParams, TQuery, TBody>(
+    middleware: TypedMiddleware<any, any, { validation: { params: TParams, query: TQuery, body: TBody } }, any>
+  ) => AugmentationBuilder<TBase & ValidatedRequest<TParams, TQuery, TBody>>
+  withRateLimit: (
+    middleware: TypedMiddleware<any, any, { rateLimit: RateLimitedRequest['rateLimit'] }, any>
+  ) => AugmentationBuilder<TBase & RateLimitedRequest>
+  withCache: (
+    middleware: TypedMiddleware<any, any, { cache: CachedRequest['cache'] }, any>
+  ) => AugmentationBuilder<TBase & CachedRequest>
+  withLogging: (
+    middleware: TypedMiddleware<any, any, { logging: { requestId: string, logger: LoggedRequest['logger'] } }, any>
+  ) => AugmentationBuilder<TBase & LoggedRequest>
+  withCORS: (
+    middleware: TypedMiddleware<any, any, { cors: CORSRequest['cors'] }, any>
+  ) => AugmentationBuilder<TBase & CORSRequest>
+  withFileUpload: <TFiles extends Record<string, any>>(
+    middleware: TypedMiddleware<any, any, { upload: { files: TFiles } }, any>
+  ) => AugmentationBuilder<TBase & FileUploadRequest<TFiles>>
+  withSession: <TSession>(
+    middleware: TypedMiddleware<any, any, { session: SessionRequest<TSession>['session'] }, any>
+  ) => AugmentationBuilder<TBase & SessionRequest<TSession>>
+  build: () => TBase
+}
+// Route with augmented types
+export declare interface AugmentedRoute<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object, TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = []> {
+  method: string
+  path: TPath
+  handler: AugmentedRouteHandler<TPath, TQuery, TBody, TContext, TMiddlewares>
+  middleware: TMiddlewares
+  augmentedRequest: EnhancedRequest<TPath, TQuery, TBody, TContext, AccumulateContext<TMiddlewares>>
+  augmentedResponse: EnhancedResponse<AccumulateContext<TMiddlewares>>
+}
+// Type-safe route builder with augmentation
+export declare interface AugmentedRouteBuilder<TContext = object> {
+  get: <
+    TPath extends string,
+    TQuery extends Record<string, any> = object,
+    TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = [],
+  >(
+    path: TPath,
+    middleware: TMiddlewares,
+    handler: AugmentedRouteHandler<TPath, TQuery, never, TContext, TMiddlewares>
+  ) => AugmentedRoute<TPath, TQuery, never, TContext, TMiddlewares>
+  post: <
+    TPath extends string,
+    TQuery extends Record<string, any> = object,
+    TBody = unknown,
+    TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = [],
+  >(
+    path: TPath,
+    middleware: TMiddlewares,
+    handler: AugmentedRouteHandler<TPath, TQuery, TBody, TContext, TMiddlewares>
+  ) => AugmentedRoute<TPath, TQuery, TBody, TContext, TMiddlewares>
+  put: <
+    TPath extends string,
+    TQuery extends Record<string, any> = object,
+    TBody = unknown,
+    TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = [],
+  >(
+    path: TPath,
+    middleware: TMiddlewares,
+    handler: AugmentedRouteHandler<TPath, TQuery, TBody, TContext, TMiddlewares>
+  ) => AugmentedRoute<TPath, TQuery, TBody, TContext, TMiddlewares>
+  patch: <
+    TPath extends string,
+    TQuery extends Record<string, any> = object,
+    TBody = unknown,
+    TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = [],
+  >(
+    path: TPath,
+    middleware: TMiddlewares,
+    handler: AugmentedRouteHandler<TPath, TQuery, TBody, TContext, TMiddlewares>
+  ) => AugmentedRoute<TPath, TQuery, TBody, TContext, TMiddlewares>
+  delete: <
+    TPath extends string,
+    TQuery extends Record<string, any> = object,
+    TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = [],
+  >(
+    path: TPath,
+    middleware: TMiddlewares,
+    handler: AugmentedRouteHandler<TPath, TQuery, never, TContext, TMiddlewares>
+  ) => AugmentedRoute<TPath, TQuery, never, TContext, TMiddlewares>
+}
+// Runtime augmentation helpers
+export declare interface RuntimeAugmentation {
+  augmentRequest: <T>(request: Request, augmentation: T) => Request & T
+  extractAugmentation: <T>(request: Request & T) => T
+  hasAugmentation: <T>(request: Request, key: keyof T) => boolean
+  getAugmentation: <T, K extends keyof T>(request: Request & T, key: K) => T[K]
+}
+// Augmentation metadata
+export declare interface AugmentationMetadata {
+  name: string
+  version?: string
+  description?: string
+  dependencies?: string[]
+  provides: string[]
+  requires?: string[]
+}
+// Augmentation registry
+export declare interface AugmentationRegistry {
+  register: (
+    name: string,
+    middleware: TypedMiddleware<any, any, any, any>,
+    metadata: AugmentationMetadata
+  ) => void
+  get: (name: string) => {
+    middleware: TypedMiddleware<any, any, any, any>
+    metadata: AugmentationMetadata
+  } | undefined
+  resolve: (requirements: string[]) => TypedMiddleware<any, any, any, any>[]
+  validate: (middlewares: TypedMiddleware<any, any, any, any>[]) => {
+    valid: boolean
+    errors: string[]
+    warnings: string[]
+  }
+}
+// Middleware augmentation extraction
+export type ExtractMiddlewareAugmentation<T> = T extends TypedMiddleware<infer Input, infer Output, infer Context, any>
+    ? {
+        input: Input
+        output: Output
+        context: Context
+        augmentation: Output extends Input & infer Aug ? Aug : object
+      }
+    : never
+// Request augmentation through middleware chain
+export type AugmentRequestThroughChain<TRequest, TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[]> = TMiddlewares extends readonly [infer First, ...infer Rest]
+  ? First extends TypedMiddleware<TRequest, infer Output, any, any>
+    ? Rest extends readonly TypedMiddleware<any, any, any, any>[]
+      ? AugmentRequestThroughChain<Output, Rest>
+      : Output
+    : TRequest
+  : TRequest
+// Context accumulation through middleware chain
+export type AccumulateContext<TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[]> = TMiddlewares extends readonly [infer First, ...infer Rest]
+  ? First extends TypedMiddleware<any, any, infer Context, any>
+    ? Rest extends readonly TypedMiddleware<any, any, any, any>[]
+      ? Context & AccumulateContext<Rest>
+      : Context
+    : object
+  : object
+// Enhanced request with middleware augmentations
+export type EnhancedRequest<TPath extends string = string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object, TAugmentations = object> = TypedRequest<TPath, TQuery, TBody, TContext> & {
+  // Core request properties
+  params: ExtractTypedParams<TPath>
+  query: ExtractQueryParams<TQuery>
+  body: TBody
+  context: TContext & TAugmentations
+
+  // Middleware augmentations (conditionally added)
+  user?: TAugmentations extends { auth: any }
+    ? TAugmentations['auth']['user']
+    : never
+
+  isAuthenticated?: TAugmentations extends { auth: any }
+    ? boolean
+    : never
+
+  permissions?: TAugmentations extends { authz: any }
+    ? TAugmentations['authz']['permissions']
+    : never
+
+  hasPermission?: TAugmentations extends { authz: any }
+    ? (permission: string) => boolean
+    : never
+
+  validatedParams?: TAugmentations extends { validation: any }
+    ? TAugmentations['validation']['params']
+    : never
+
+  validatedQuery?: TAugmentations extends { validation: any }
+    ? TAugmentations['validation']['query']
+    : never
+
+  validatedBody?: TAugmentations extends { validation: any }
+    ? TAugmentations['validation']['body']
+    : never
+
+  rateLimit?: TAugmentations extends { rateLimit: any }
+    ? TAugmentations['rateLimit']
+    : never
+
+  cache?: TAugmentations extends { cache: any }
+    ? TAugmentations['cache']
+    : never
+
+  requestId?: TAugmentations extends { logging: any }
+    ? string
+    : never
+
+  logger?: TAugmentations extends { logging: any }
+    ? TAugmentations['logging']['logger']
+    : never
+
+  cors?: TAugmentations extends { cors: any }
+    ? TAugmentations['cors']
+    : never
+
+  files?: TAugmentations extends { upload: any }
+    ? TAugmentations['upload']['files']
+    : never
+
+  session?: TAugmentations extends { session: any }
+    ? TAugmentations['session']
+    : never
+}
+// Middleware-aware route handler
+export type AugmentedRouteHandler<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object, TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[] = []> = (
+  request: EnhancedRequest<
+    TPath,
+    TQuery,
+    TBody,
+    TContext,
+    AccumulateContext<TMiddlewares>
+  >
+) => Promise<EnhancedResponse<AccumulateContext<TMiddlewares>>> | EnhancedResponse<AccumulateContext<TMiddlewares>>
+// Type-safe middleware application
+export type ApplyMiddleware<TRequest, TMiddleware extends TypedMiddleware<any, any, any, any>> = TMiddleware extends TypedMiddleware<TRequest, infer Output, infer Context, any>
+  ? {
+      request: Output
+      context: Context
+    }
+  : never
+// Sequential middleware application
+export type ApplyMiddlewareSequence<TRequest, TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[]> = TMiddlewares extends readonly [infer First, ...infer Rest]
+  ? First extends TypedMiddleware<TRequest, infer Output, infer Context, any>
+    ? Rest extends readonly TypedMiddleware<any, any, any, any>[]
+      ? ApplyMiddlewareSequence<Output, Rest> extends {
+        request: infer FinalRequest
+        context: infer RestContext
+      }
+        ? {
+            request: FinalRequest
+            context: Context & RestContext
+          }
+        : {
+            request: Output
+            context: Context
+          }
+      : {
+          request: Output
+          context: Context
+        }
+    : {
+        request: TRequest
+        context: object
+      }
+  : {
+      request: TRequest
+      context: object
+    }
+// Conditional augmentation based on middleware presence
+export type ConditionalAugmentation<TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[], TAugmentation> = TMiddlewares extends readonly []
+  ? object
+  : TAugmentation
+// Authentication augmentation
+export type AuthAugmentation<TUser = any> = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { auth: { user: TUser } }, any>],
+  AuthenticatedRequest<TUser>
+>
+// Authorization augmentation
+export type AuthzAugmentation<TPermissions extends string = string> = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { authz: { permissions: TPermissions[] } }, any>],
+  AuthorizedRequest<TPermissions>
+>
+// Validation augmentation
+export type ValidationAugmentation<TParams = any, TQuery = any, TBody = any> = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { validation: { params: TParams, query: TQuery, body: TBody } }, any>],
+  ValidatedRequest<TParams, TQuery, TBody>
+>
+// Rate limiting augmentation
+export type RateLimitAugmentation = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { rateLimit: RateLimitedRequest['rateLimit'] }, any>],
+  RateLimitedRequest
+>
+// Caching augmentation
+export type CacheAugmentation = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { cache: CachedRequest['cache'] }, any>],
+  CachedRequest
+>
+// Logging augmentation
+export type LoggingAugmentation = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { logging: { requestId: string, logger: LoggedRequest['logger'] } }, any>],
+  LoggedRequest
+>
+// CORS augmentation
+export type CORSAugmentation = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { cors: CORSRequest['cors'] }, any>],
+  CORSRequest
+>
+// File upload augmentation
+export type FileUploadAugmentation<TFiles extends Record<string, any> = Record<string, File>> = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { upload: { files: TFiles } }, any>],
+  FileUploadRequest<TFiles>
+>
+// Session augmentation
+export type SessionAugmentation<TSession = any> = ConditionalAugmentation<
+  [TypedMiddleware<any, any, { session: SessionRequest<TSession>['session'] }, any>],
+  SessionRequest<TSession>
+>
+// Combined augmentations
+export type CombineAugmentations<T extends Record<string, any>[]> = T extends [
+  infer First,
+  ...infer Rest,
+]
+  ? First extends Record<string, any>
+    ? Rest extends Record<string, any>[]
+      ? First & CombineAugmentations<Rest>
+      : First
+    : object
+  : object
+// Middleware type detection
+export type HasAuthMiddleware<T extends readonly TypedMiddleware<any, any, any, any>[]> = T extends readonly [infer First, ...infer Rest]
+    ? First extends TypedMiddleware<any, any, { auth: any }, any>
+      ? true
+      : Rest extends readonly TypedMiddleware<any, any, any, any>[]
+        ? HasAuthMiddleware<Rest>
+        : false
+    : false
+export type HasValidationMiddleware<T extends readonly TypedMiddleware<any, any, any, any>[]> = T extends readonly [infer First, ...infer Rest]
+    ? First extends TypedMiddleware<any, any, { validation: any }, any>
+      ? true
+      : Rest extends readonly TypedMiddleware<any, any, any, any>[]
+        ? HasValidationMiddleware<Rest>
+        : false
+    : false
+export type HasRateLimitMiddleware<T extends readonly TypedMiddleware<any, any, any, any>[]> = T extends readonly [infer First, ...infer Rest]
+    ? First extends TypedMiddleware<any, any, { rateLimit: any }, any>
+      ? true
+      : Rest extends readonly TypedMiddleware<any, any, any, any>[]
+        ? HasRateLimitMiddleware<Rest>
+        : false
+    : false
+// Augmentation validation
+export type ValidateAugmentation<TRequest, TExpectedAugmentation> = TRequest extends TExpectedAugmentation
+  ? true
+  : false
+// Augmentation compatibility checking
+export type AugmentationCompatible<TMiddleware1 extends TypedMiddleware<any, any, any, any>, TMiddleware2 extends TypedMiddleware<any, any, any, any>> = TMiddleware1 extends TypedMiddleware<any, infer Output1, any, any>
+  ? TMiddleware2 extends TypedMiddleware<Output1, any, any, any>
+    ? true
+    : false
+  : false