@stacksjs/bun-router 0.0.5 → 0.0.7

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

@@ -0,0 +1,208 @@
+/**
+ * Controller Method Type Checking at Compile Time
+ *
+ * Advanced TypeScript utilities for compile-time controller method validation
+ */
+import type { TypedMiddleware } from './middleware-types';
+import type { ExtractQueryParams, ExtractTypedParams, RouteHandler, RouteMethod, TypedRequest } from './route-inference';
+export interface BaseController {
+    [key: string]: any;
+}
+export interface ControllerMethodMetadata {
+    path: string;
+    method: RouteMethod;
+    middleware?: TypedMiddleware<any, any, any, any>[];
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    operationId?: string;
+}
+export interface MethodDecoratorMetadata extends ControllerMethodMetadata {
+    parameterTypes?: any[];
+    returnType?: any;
+    target: any;
+    propertyKey: string | symbol;
+}
+export type ControllerMethodNames<T> = {
+    [K in keyof T]: T[K] extends (..._args: any[]) => any ? K : never;
+}[keyof T];
+export type ControllerMethods<T> = Pick<T, ControllerMethodNames<T>>;
+export type ValidateControllerMethod<T> = T extends (request: infer TRequest, ...args: any[]) => infer TReturn ? TRequest extends TypedRequest<any, any, any, any> ? TReturn extends Promise<Response> | Response ? T : `Invalid return type: Controller method must return Response or Promise<Response>` : `Invalid parameter type: First parameter must be TypedRequest` : `Invalid method signature: Controller method must be a function`;
+export type InferControllerMethodType<T> = T extends (request: TypedRequest<infer TPath, infer TQuery, infer TBody, infer TContext>, ...args: any[]) => Promise<Response> | Response ? {
+    path: TPath;
+    query: TQuery;
+    body: TBody;
+    context: TContext;
+    params: ExtractTypedParams<TPath>;
+} : never;
+export interface ControllerRoute<TPath extends string = string, TQuery extends Record<string, any> = object, TBody = unknown, TContext = object> {
+    method: RouteMethod;
+    path: TPath;
+    handler: RouteHandler<TPath, TQuery, TBody, TContext>;
+    controllerMethod: string;
+    middleware?: TypedMiddleware<any, any, any, any>[];
+    metadata?: ControllerMethodMetadata;
+}
+export interface ControllerDecorator<TPrefix extends string = ''> {
+    prefix?: TPrefix;
+    middleware?: TypedMiddleware<any, any, any, any>[];
+    tags?: string[];
+    description?: string;
+}
+export type RouteDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = <T extends BaseController>(target: T, propertyKey: keyof T, descriptor: TypedPropertyDescriptor<RouteHandler<TPath, TQuery, TBody, any>>) => void;
+export type GetDecorator<TPath extends string, TQuery extends Record<string, any> = object> = RouteDecorator<TPath, TQuery, never>;
+export type PostDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>;
+export type PutDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>;
+export type PatchDecorator<TPath extends string, TQuery extends Record<string, any> = object, TBody = unknown> = RouteDecorator<TPath, TQuery, TBody>;
+export type DeleteDecorator<TPath extends string, TQuery extends Record<string, any> = object> = RouteDecorator<TPath, TQuery, never>;
+export interface ParameterDecorator<_T = any> {
+    <TController extends BaseController>(target: TController, propertyKey: keyof TController, parameterIndex: number): void;
+}
+export type ParamDecorator<_TName extends string> = ParameterDecorator<string>;
+export type QueryDecorator<_TName extends string> = ParameterDecorator<string>;
+export type BodyDecorator<T = any> = ParameterDecorator<T>;
+export type HeaderDecorator<_TName extends string> = ParameterDecorator<string>;
+export type CookieDecorator<_TName extends string> = ParameterDecorator<string>;
+export type RequestDecorator = ParameterDecorator<Request>;
+export type ResponseDecorator = ParameterDecorator<Response>;
+export type ControllerMethodParams<T> = T extends (...args: infer TParams) => any ? TParams : never;
+export type ValidateControllerParams<T extends any[]> = {
+    [K in keyof T]: T[K] extends TypedRequest<any, any, any, any> ? T[K] : T[K] extends string | number | boolean | object ? T[K] : `Invalid parameter type at index ${K}: ${T[K]}`;
+};
+export interface ControllerDependency<T = any> {
+    token: string | symbol | ((..._args: any[]) => any);
+    value?: T;
+    factory?: () => T;
+    singleton?: boolean;
+}
+export interface DependencyContainer {
+    register: <T>(dependency: ControllerDependency<T>) => void;
+    resolve: <T>(token: string | symbol | ((..._args: any[]) => any)) => T;
+    has: (token: string | symbol | ((..._args: any[]) => any)) => boolean;
+}
+export interface InjectableDecorator {
+    <T extends new (..._args: any[]) => any>(constructor: T): T;
+}
+export interface InjectDecorator<T = any> {
+    (token: string | symbol | ((..._args: any[]) => any)): ParameterDecorator<T>;
+}
+export interface ControllerFactory<T extends BaseController> {
+    create: (container?: DependencyContainer) => T;
+    getRoutes: () => ControllerRoute[];
+    getMetadata: () => ControllerDecorator;
+}
+export interface ControllerRegistry {
+    register: <T extends BaseController>(controller: new (...args: any[]) => T, metadata?: ControllerDecorator) => void;
+    get: <T extends BaseController>(controller: new (...args: any[]) => T) => ControllerFactory<T> | undefined;
+    getAll: () => Array<{
+        controller: new (...args: any[]) => BaseController;
+        factory: ControllerFactory<BaseController>;
+    }>;
+    resolve: (container?: DependencyContainer) => ControllerRoute[];
+}
+export type ValidateController<T extends BaseController> = {
+    [K in keyof T]: T[K] extends (..._args: any[]) => any ? ValidateControllerMethod<T[K]> extends string ? ValidateControllerMethod<T[K]> : T[K] : T[K];
+};
+export type ExtractControllerRoutes<T extends BaseController> = {
+    [K in keyof T]: T[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext> ? ControllerRoute<TPath, TQuery, TBody, TContext> : never;
+}[keyof T];
+export type BindControllerMethod<TController extends BaseController, TMethod extends keyof TController> = TController[TMethod] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext> ? (this: TController, _request: TypedRequest<TPath, TQuery, TBody, TContext>) => Promise<Response> | Response : never;
+export type ControllerInstance<T extends BaseController> = {
+    [K in keyof T]: T[K] extends (..._args: any[]) => any ? BindControllerMethod<T, K> : T[K];
+};
+export type ExtractMethodMetadata<T extends BaseController> = {
+    [K in keyof T]: T[K] extends (..._args: any[]) => any ? InferControllerMethodType<T[K]> extends never ? never : {
+        method: K;
+        route: InferControllerMethodType<T[K]>;
+        metadata?: ControllerMethodMetadata;
+    } : never;
+}[keyof T];
+export type ControllerValidationError<T extends BaseController> = {
+    [K in keyof T]: ValidateController<T>[K] extends string ? {
+        method: K;
+        error: ValidateController<T>[K];
+    } : never;
+}[keyof T];
+export type IsValidController<T> = T extends BaseController ? ControllerValidationError<T> extends never ? true : false : false;
+export type IsValidControllerMethod<T> = ValidateControllerMethod<T> extends string ? false : true;
+export type ComposeControllers<T extends readonly BaseController[]> = T extends readonly [
+    infer First,
+    ...infer Rest
+] ? First extends BaseController ? Rest extends readonly BaseController[] ? First & ComposeControllers<Rest> : First : object : object;
+export type ApplyControllerMiddleware<TController extends BaseController, TMiddleware extends TypedMiddleware<any, any, any, any>> = {
+    [K in keyof TController]: TController[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, infer TContext> ? TMiddleware extends TypedMiddleware<any, any, infer TNewContext, any> ? RouteHandler<TPath, TQuery, TBody, TContext & TNewContext> : TController[K] : TController[K];
+};
+export type DetectControllerConflicts<T extends BaseController> = {
+    [K in keyof T]: {
+        [J in keyof T]: K extends J ? never : T[K] extends RouteHandler<infer Path1, any, any, any> ? T[J] extends RouteHandler<infer Path2, any, any, any> ? Path1 extends Path2 ? `Route conflict in controller: methods "${string & K}" and "${string & J}" both handle "${Path1}"` : never : never : never;
+    }[keyof T];
+}[keyof T];
+export interface GenerateControllerOpenAPI<T extends BaseController> {
+    paths: {
+        [K in keyof T]: T[K] extends RouteHandler<infer TPath, infer TQuery, infer TBody, any> ? {
+            [M in RouteMethod]: {
+                operationId: string & K;
+                parameters: Array<{
+                    name: keyof ExtractTypedParams<TPath>;
+                    in: 'path';
+                    required: true;
+                    schema: {
+                        type: 'string';
+                    };
+                }> | Array<{
+                    name: keyof ExtractQueryParams<TQuery>;
+                    in: 'query';
+                    required: boolean;
+                    schema: {
+                        type: 'string';
+                    };
+                }>;
+                requestBody?: TBody extends never ? never : {
+                    content: {
+                        'application/json': {
+                            schema: any;
+                        };
+                    };
+                };
+                responses: {
+                    200: {
+                        description: 'Success';
+                        content: {
+                            'application/json': {
+                                schema: any;
+                            };
+                        };
+                    };
+                };
+            };
+        } : never;
+    };
+}
+export interface ControllerTestUtils<T extends BaseController> {
+    createInstance: (overrides?: Partial<T>) => T;
+    mockMethod: <K extends keyof T>(method: K, implementation: T[K]) => void;
+    callMethod: <K extends keyof T>(method: K, ..._args: T[K] extends (..._a: infer TArgs) => any ? TArgs : never) => T[K] extends (..._a: any[]) => infer TReturn ? TReturn : never;
+    getRoutes: () => ControllerRoute[];
+    validateRoutes: () => ControllerValidationError<T>[];
+}
+export interface ControllerPerformanceMetrics {
+    controllerName: string;
+    methodName: string;
+    executionTime: number;
+    memoryUsage: number;
+    callCount: number;
+    errorCount: number;
+    lastCalled: Date;
+}
+export type PerformanceTrackingController<T extends BaseController> = T & {
+    getPerformanceMetrics: () => ControllerPerformanceMetrics[];
+    resetMetrics: () => void;
+};
+export interface ControllerLifecycleHooks {
+    onInit?: () => Promise<void> | void;
+    onDestroy?: () => Promise<void> | void;
+    beforeMethod?: (methodName: string, args: any[]) => Promise<void> | void;
+    afterMethod?: (methodName: string, result: any, args: any[]) => Promise<void> | void;
+    onError?: (error: Error, methodName: string, args: any[]) => Promise<void> | void;
+}
+export type LifecycleController<T extends BaseController> = T & ControllerLifecycleHooks;