@stacksjs/bun-router 0.0.5 → 0.0.7

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

@@ -0,0 +1,227 @@
+/**
+ * Middleware Type Safety with Generic Constraints
+ *
+ * Advanced TypeScript utilities for type-safe middleware with generic constraints
+ */
+import type { RouteHandler, TypedRequest } from './route-inference';
+export interface TypedMiddleware<TInput = any, TOutput = TInput, _TContext = object, TNext = any> {
+    (request: TInput, next: TNext): Promise<TOutput> | TOutput;
+}
+export type AugmentContext<TBase, TAddition> = TBase & TAddition;
+export type AugmentRequest<TRequest, TAugmentation> = TRequest & TAugmentation;
+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;
+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 interface AuthenticatedRequest<TUser = any> {
+    user: TUser;
+    isAuthenticated: true;
+}
+export interface UnauthenticatedRequest {
+    user?: never;
+    isAuthenticated: false;
+}
+export type AuthMiddleware<TUser = any> = TypedMiddleware<Request, Request & AuthenticatedRequest<TUser>, {
+    auth: {
+        user: TUser;
+    };
+}, any>;
+export interface AuthorizedRequest<TPermissions extends string = string> {
+    permissions: TPermissions[];
+    hasPermission: (permission: TPermissions) => boolean;
+}
+export type AuthzMiddleware<TPermissions extends string = string> = TypedMiddleware<Request & AuthenticatedRequest, Request & AuthenticatedRequest & AuthorizedRequest<TPermissions>, {
+    authz: {
+        permissions: TPermissions[];
+    };
+}, any>;
+export interface ValidatedRequest<TParams = any, TQuery = any, TBody = any> {
+    validatedParams: TParams;
+    validatedQuery: TQuery;
+    validatedBody: TBody;
+}
+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 interface RateLimitedRequest {
+    rateLimit: {
+        remaining: number;
+        reset: Date;
+        limit: number;
+    };
+}
+export type RateLimitMiddleware = TypedMiddleware<Request, Request & RateLimitedRequest, {
+    rateLimit: RateLimitedRequest['rateLimit'];
+}, any>;
+export interface CachedRequest {
+    cache: {
+        key: string;
+        ttl: number;
+        hit: boolean;
+    };
+}
+export type CacheMiddleware = TypedMiddleware<Request, Request & CachedRequest, {
+    cache: CachedRequest['cache'];
+}, any>;
+export 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;
+    };
+}
+export type LoggingMiddleware = TypedMiddleware<Request, Request & LoggedRequest, {
+    logging: {
+        requestId: string;
+        logger: LoggedRequest['logger'];
+    };
+}, any>;
+export interface CORSRequest {
+    cors: {
+        origin: string;
+        methods: string[];
+        headers: string[];
+        credentials: boolean;
+    };
+}
+export type CORSMiddleware = TypedMiddleware<Request, Request & CORSRequest, {
+    cors: CORSRequest['cors'];
+}, any>;
+export interface FileUploadRequest<TFiles extends Record<string, any> = Record<string, File>> {
+    files: TFiles;
+    formData: FormData;
+}
+export type FileUploadMiddleware<TFiles extends Record<string, any> = Record<string, File>> = TypedMiddleware<Request, Request & FileUploadRequest<TFiles>, {
+    upload: {
+        files: TFiles;
+    };
+}, any>;
+export interface SessionRequest<TSession = any> {
+    session: TSession & {
+        id: string;
+        save: () => Promise<void>;
+        destroy: () => Promise<void>;
+        regenerate: () => Promise<void>;
+    };
+}
+export type SessionMiddleware<TSession = any> = TypedMiddleware<Request, Request & SessionRequest<TSession>, {
+    session: SessionRequest<TSession>['session'];
+}, any>;
+export interface MiddlewareFactory<TOptions = any, TMiddleware extends TypedMiddleware<any, any, any, any> = any> {
+    (options?: TOptions): TMiddleware;
+}
+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 interface MiddlewareGroup<TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[]> {
+    middlewares: TMiddlewares;
+    compose: () => MiddlewareChain<TMiddlewares>;
+}
+export interface ErrorHandlingRequest {
+    error?: Error;
+    errorHandled: boolean;
+}
+export type ErrorMiddleware = TypedMiddleware<Request & {
+    error: Error;
+}, Response, {
+    error: {
+        handled: boolean;
+    };
+}, any>;
+export interface MiddlewarePipeline<T extends readonly TypedMiddleware<any, any, any, any>[]> {
+    readonly middlewares: T;
+    execute: <TRequest>(request: TRequest) => Promise<T extends readonly [] ? TRequest : MiddlewareChain<T> extends TypedMiddleware<TRequest, infer Output, any, any> ? Output : never>;
+}
+export 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;
+}
+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;
+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>>;
+export 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>[];
+}
+export interface MiddlewareExecutionContext<TContext = object> {
+    request: Request;
+    response?: Response;
+    context: TContext;
+    next: () => Promise<Response>;
+    skip: () => void;
+    abort: (response: Response) => void;
+}
+export 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;
+}
+export type AsyncMiddleware<TInput = any, TOutput = TInput, TContext = object, TNext = any> = TypedMiddleware<TInput, Promise<TOutput>, TContext, TNext>;
+export interface MiddlewareMetadata {
+    name: string;
+    version?: string;
+    description?: string;
+    dependencies?: string[];
+    tags?: string[];
+    priority?: number;
+}
+export interface DecoratedMiddleware<TInput = any, TOutput = TInput, TContext = object, TNext = any> extends TypedMiddleware<TInput, TOutput, TContext, TNext> {
+    metadata: MiddlewareMetadata;
+}
+export 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>[];
+}
+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>;
+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;
+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;
+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 interface MiddlewarePerformance {
+    name: string;
+    executionTime: number;
+    memoryUsage: number;
+    callCount: number;
+    errorCount: number;
+}
+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,261 @@
+/**
+ * Request/Response Type Augmentation Based on Middleware
+ *
+ * Advanced TypeScript utilities for augmenting request/response types through middleware
+ */
+import type { AuthenticatedRequest, AuthorizedRequest, CachedRequest, CORSRequest, FileUploadRequest, LoggedRequest, RateLimitedRequest, SessionRequest, TypedMiddleware, ValidatedRequest } from './middleware-types';
+import type { ExtractQueryParams, ExtractTypedParams, TypedRequest } from './route-inference';
+export interface RequestAugmentation {
+    [key: string]: any;
+}
+export interface ResponseAugmentation {
+    [key: string]: any;
+}
+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;
+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;
+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;
+export type EnhancedRequest<TPath extends string = string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object, TAugmentations = object> = TypedRequest<TPath, TQuery, TBody, TContext> & {
+    params: ExtractTypedParams<TPath>;
+    query: ExtractQueryParams<TQuery>;
+    body: TBody;
+    context: TContext & TAugmentations;
+    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;
+};
+export 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;
+}
+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>>;
+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;
+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;
+};
+export type ConditionalAugmentation<TMiddlewares extends readonly TypedMiddleware<any, any, any, any>[], TAugmentation> = TMiddlewares extends readonly [] ? object : TAugmentation;
+export type AuthAugmentation<TUser = any> = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        auth: {
+            user: TUser;
+        };
+    }, any>
+], AuthenticatedRequest<TUser>>;
+export type AuthzAugmentation<TPermissions extends string = string> = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        authz: {
+            permissions: TPermissions[];
+        };
+    }, any>
+], AuthorizedRequest<TPermissions>>;
+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>>;
+export type RateLimitAugmentation = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        rateLimit: RateLimitedRequest['rateLimit'];
+    }, any>
+], RateLimitedRequest>;
+export type CacheAugmentation = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        cache: CachedRequest['cache'];
+    }, any>
+], CachedRequest>;
+export type LoggingAugmentation = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        logging: {
+            requestId: string;
+            logger: LoggedRequest['logger'];
+        };
+    }, any>
+], LoggedRequest>;
+export type CORSAugmentation = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        cors: CORSRequest['cors'];
+    }, any>
+], CORSRequest>;
+export type FileUploadAugmentation<TFiles extends Record<string, any> = Record<string, File>> = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        upload: {
+            files: TFiles;
+        };
+    }, any>
+], FileUploadRequest<TFiles>>;
+export type SessionAugmentation<TSession = any> = ConditionalAugmentation<[
+    TypedMiddleware<any, any, {
+        session: SessionRequest<TSession>['session'];
+    }, any>
+], SessionRequest<TSession>>;
+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;
+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;
+export 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;
+}
+export 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>>;
+}
+export 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>;
+}
+export type ValidateAugmentation<TRequest, TExpectedAugmentation> = TRequest extends TExpectedAugmentation ? true : false;
+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;
+export 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];
+}
+export interface AugmentationMetadata {
+    name: string;
+    version?: string;
+    description?: string;
+    dependencies?: string[];
+    provides: string[];
+    requires?: string[];
+}
+export 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[];
+    };
+}

package/dist/types/route-inference.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Route Parameter Type Inference
+ *
+ * Advanced TypeScript utilities for inferring route parameter types from URL patterns
+ */
+export type ExtractRouteParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param]: string;
+} & ExtractRouteParams<`/${Rest}`> : T extends `${infer _Start}:${infer Param}?${infer Rest}` ? {
+    [K in Param]?: string;
+} & ExtractRouteParams<Rest> : T extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : T extends `${infer _Start}*${infer Rest}` ? {
+    '*': string;
+} & ExtractRouteParams<Rest> : Record<string, never>;
+export type ExtractTypedParams<T extends string> = T extends `${infer _Start}:${infer Param}<${infer Type}>${infer Rest}` ? {
+    [K in Param]: ParseParamType<Type>;
+} & ExtractTypedParams<Rest> : T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param]: string;
+} & ExtractTypedParams<`/${Rest}`> : T extends `${infer _Start}:${infer Param}?${infer Rest}` ? {
+    [K in Param]?: string;
+} & ExtractTypedParams<Rest> : T extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<string, never>;
+export type ParseParamType<T extends string> = T extends 'number' | 'int' | 'integer' ? number : T extends 'boolean' | 'bool' ? boolean : T extends 'date' ? Date : T extends 'uuid' ? string : T extends 'email' ? string : T extends 'url' ? string : T extends `enum(${infer Values})` ? ParseEnumValues<Values> : T extends `range(${infer _Min},${infer _Max})` ? number : T extends `length(${infer _MinMax})` ? string : T extends `pattern(${infer _Pattern})` ? string : string;
+export type ParseEnumValues<T extends string> = T extends `${infer First}|${infer Rest}` ? First | ParseEnumValues<Rest> : T;
+export type ExtractQueryParams<T extends Record<string, any>> = {
+    [K in keyof T]: T[K] extends 'string' ? string : T[K] extends 'number' ? number : T[K] extends 'boolean' ? boolean : T[K] extends 'string[]' ? string[] : T[K] extends 'number[]' ? number[] : T[K] extends {
+        type: infer Type;
+        required: true;
+    } ? Type extends 'string' ? string : Type extends 'number' ? number : Type extends 'boolean' ? boolean : string : T[K] extends {
+        type: infer Type;
+        required: false;
+    } ? Type extends 'string' ? string | undefined : Type extends 'number' ? number | undefined : Type extends 'boolean' ? boolean | undefined : string | undefined : string;
+};
+export type ValidateRoutePattern<T extends string> = T extends `${infer _}:${infer _Param}:${infer _}` ? `Invalid route pattern: consecutive parameters not allowed in "${T}"` : T extends `${infer _}::${infer _}` ? `Invalid route pattern: empty parameter name in "${T}"` : T extends `${infer _}:${infer Param}` ? Param extends `${infer Name}${infer Rest}` ? Name extends '' ? `Invalid route pattern: empty parameter name in "${T}"` : Rest extends `<${infer Type}>` ? ValidateParamType<Type> extends never ? `Invalid parameter type "${Type}" in route "${T}"` : T : T : T : T;
+export type ValidateParamType<T extends string> = T extends 'string' | 'number' | 'int' | 'integer' | 'boolean' | 'bool' | 'date' | 'uuid' | 'email' | 'url' ? T : T extends `enum(${infer Values})` ? Values extends '' ? never : T : T extends `range(${infer Min},${infer Max})` ? Min extends `${number}` ? Max extends `${number}` ? T : never : never : T extends `length(${infer MinMax})` ? MinMax extends `${number}` | `${number},${number}` ? T : never : T extends `pattern(${infer Pattern})` ? Pattern extends '' ? never : T : never;
+export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type RouteHandler<TPath extends string, TQuery extends Record<string, any> = Record<string, never>, TBody = unknown, TContext = Record<string, never>> = (_request: TypedRequest<TPath, TQuery, TBody, TContext>) => Promise<Response> | Response;
+export interface TypedRequest<TPath extends string = string, TQuery extends Record<string, any> = Record<string, never>, TBody = unknown, TContext = Record<string, never>> extends Omit<Request, 'body'> {
+    params: ExtractTypedParams<TPath>;
+    query: ExtractQueryParams<TQuery>;
+    body: TBody;
+    context: TContext;
+}
+export interface TypedRoute<TPath extends string, TQuery extends Record<string, any> = Record<string, never>, TBody = unknown, TContext = Record<string, never>> {
+    method: RouteMethod;
+    path: ValidateRoutePattern<TPath>;
+    handler: RouteHandler<TPath, TQuery, TBody, TContext>;
+    middleware?: TypedMiddleware<any, any, any, TContext>[];
+    schema?: {
+        params?: RouteParamSchema<ExtractTypedParams<TPath>>;
+        query?: TQuery;
+        body?: BodySchema<TBody>;
+        response?: ResponseSchema;
+    };
+}
+export type RouteParamSchema<T extends Record<string, any>> = {
+    [K in keyof T]: {
+        type: T[K] extends string ? 'string' : T[K] extends number ? 'number' : T[K] extends boolean ? 'boolean' : T[K] extends Date ? 'date' : 'string';
+        required?: boolean;
+        pattern?: string;
+        min?: number;
+        max?: number;
+        enum?: T[K][];
+        transform?: (value: string) => T[K];
+        validate?: (value: T[K]) => boolean | string;
+    };
+};
+export interface BodySchema<T = unknown> {
+    type: 'json' | 'form' | 'text' | 'buffer' | 'stream';
+    schema?: T extends object ? {
+        [K in keyof T]: {
+            type: T[K] extends string ? 'string' : T[K] extends number ? 'number' : T[K] extends boolean ? 'boolean' : T[K] extends Date ? 'date' : T[K] extends Array<infer _U> ? 'array' : 'object';
+            required?: boolean;
+            items?: T[K] extends Array<infer _U> ? BodySchema<_U> : never;
+            properties?: T[K] extends object ? BodySchema<T[K]> : never;
+        };
+    } : never;
+    required?: (keyof T)[];
+    additionalProperties?: boolean;
+}
+export interface ResponseSchema {
+    [statusCode: number]: {
+        description?: string;
+        headers?: Record<string, string>;
+        content?: {
+            'application/json'?: any;
+            'text/plain'?: string;
+            'text/html'?: string;
+            'application/octet-stream'?: ArrayBuffer;
+        };
+    };
+}
+export type InferRouteParams<T> = T extends TypedRoute<infer Path, any, any, any> ? ExtractTypedParams<Path> : never;
+export type InferRouteQuery<T> = T extends TypedRoute<any, infer Query, any, any> ? ExtractQueryParams<Query> : never;
+export type InferRouteBody<T> = T extends TypedRoute<any, any, infer Body, any> ? Body : never;
+export type InferRouteContext<T> = T extends TypedRoute<any, any, any, infer Context> ? Context : never;
+export interface RouteGroup<TPrefix extends string = '', TContext = object> {
+    prefix: TPrefix;
+    middleware?: TypedMiddleware<any, any, any, TContext>[];
+    routes: TypedRoute<any, any, any, TContext>[];
+}
+export interface TypedMiddleware<TRequest = any, TResponse = any, TNext = any, _TContext = Record<string, never>> {
+    (request: TRequest, next: TNext): Promise<TResponse> | TResponse;
+}
+export interface RouteBuilder<TContext = object> {
+    get: <TPath extends string, TQuery extends Record<string, any> = object>(path: ValidateRoutePattern<TPath>, handler: RouteHandler<TPath, TQuery, never, TContext>) => TypedRoute<TPath, TQuery, never, TContext>;
+    post: <TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown>(path: ValidateRoutePattern<TPath>, handler: RouteHandler<TPath, TQuery, TBody, TContext>) => TypedRoute<TPath, TQuery, TBody, TContext>;
+    put: <TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown>(path: ValidateRoutePattern<TPath>, handler: RouteHandler<TPath, TQuery, TBody, TContext>) => TypedRoute<TPath, TQuery, TBody, TContext>;
+    patch: <TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown>(path: ValidateRoutePattern<TPath>, handler: RouteHandler<TPath, TQuery, TBody, TContext>) => TypedRoute<TPath, TQuery, TBody, TContext>;
+    delete: <TPath extends string, TQuery extends Record<string, any> = object>(path: ValidateRoutePattern<TPath>, handler: RouteHandler<TPath, TQuery, never, TContext>) => TypedRoute<TPath, TQuery, never, TContext>;
+}
+export type MatchRoute<TPattern extends string, TPath extends string> = TPattern extends `${infer Start}:${infer _Param}/${infer Rest}` ? TPath extends `${Start}${infer Value}/${infer PathRest}` ? Value extends '' ? false : MatchRoute<`/${Rest}`, `/${PathRest}`> : false : TPattern extends `${infer Start}:${infer _Param}` ? TPath extends `${Start}${infer Value}` ? Value extends '' ? false : true : false : TPattern extends TPath ? true : false;
+export type ExtractParamsFromPath<TPattern extends string, TPath extends string> = TPattern extends `${infer Start}:${infer _Param}/${infer Rest}` ? TPath extends `${Start}${infer Value}/${infer PathRest}` ? {
+    [K in _Param]: Value;
+} & ExtractParamsFromPath<`/${Rest}`, `/${PathRest}`> : Record<string, never> : TPattern extends `${infer Start}:${infer _Param}` ? TPath extends `${Start}${infer Value}` ? {
+    [K in _Param]: Value;
+} : Record<string, never> : Record<string, never>;
+export interface TypeSafeRouter<TContext = object> {
+    register: <TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown>(route: TypedRoute<TPath, TQuery, TBody, TContext>) => void;
+    group: <TPrefix extends string>(prefix: TPrefix, configure: (builder: RouteBuilder<TContext>) => void) => RouteGroup<TPrefix, TContext>;
+    use: <TNewContext>(middleware: TypedMiddleware<any, any, any, TNewContext>) => TypeSafeRouter<TContext & TNewContext>;
+}
+export type ValidateRoutes<T extends readonly TypedRoute<any, any, any, any>[]> = {
+    [K in keyof T]: T[K] extends TypedRoute<infer Path, any, any, any> ? ValidateRoutePattern<Path> extends `Invalid ${string}` ? ValidateRoutePattern<Path> : T[K] : T[K];
+};
+export type DetectRouteConflicts<T extends readonly TypedRoute<any, any, any, any>[]> = {
+    [K in keyof T]: {
+        [J in keyof T]: K extends J ? never : T[K] extends TypedRoute<infer Path1, any, any, any> ? T[J] extends TypedRoute<infer Path2, any, any, any> ? Path1 extends Path2 ? `Route conflict: "${Path1}" is defined multiple times` : never : never : never;
+    }[keyof T];
+}[keyof T];
+export interface GenerateOpenAPISchema<T extends TypedRoute<any, any, any, any>> {
+    paths: {
+        [K in T extends TypedRoute<infer Path, any, any, any> ? Path : never]: {
+            [M in T extends TypedRoute<any, any, any, any> ? Lowercase<T['method']> : never]: {
+                parameters?: Array<{
+                    name: string;
+                    in: 'path' | 'query';
+                    required: boolean;
+                    schema: {
+                        type: string;
+                        format?: string;
+                    };
+                }>;
+                requestBody?: {
+                    content: {
+                        'application/json': {
+                            schema: any;
+                        };
+                    };
+                };
+                responses: {
+                    [status: number]: {
+                        description: string;
+                        content?: {
+                            'application/json': {
+                                schema: any;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+}
+export type AssertEqual<T, U> = T extends U ? U extends T ? true : false : false;
+export type AssertExtends<T, U> = T extends U ? true : false;
+export type AssertNotEqual<T, U> = AssertEqual<T, U> extends true ? false : true;