@forinda/kickjs 0.1.4 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,378 +1,613 @@
1
- import { RequestHandler, Request, Response, NextFunction, Application } from 'express';
2
- import { Server } from 'http';
3
- import { Container, ServiceIdentifier } from 'inversify';
1
+ import { Newable, Container, inject, injectable } from 'inversify';
2
+ import * as express from 'express';
3
+ import { Express, Request, Response, NextFunction, Application } from 'express';
4
+ import * as stream from 'stream';
5
+ import * as net from 'net';
6
+ import * as http from 'http';
7
+ import { EventEmitter } from 'events';
4
8
 
5
- type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
6
- interface ControllerOptions {
7
- path?: string;
8
- autoRegister?: boolean;
9
- tags?: string[];
10
- }
11
- type SchemaLike = {
12
- safeParse?: (data: unknown) => {
13
- success: boolean;
14
- data?: unknown;
15
- error?: unknown;
16
- };
17
- parse?: (data: unknown) => unknown;
18
- validate?: (data: unknown, options?: Record<string, unknown>) => {
19
- error?: {
20
- details?: Array<{
21
- message: string;
22
- }>;
23
- };
24
- value: unknown;
25
- };
9
+ /**
10
+ * Represents a controller class that can be instantiated.
11
+ * Used in module creation to register controllers.
12
+ */
13
+ type KickModuleController = Newable<any>;
14
+ /**
15
+ * Represents a middleware class that can be instantiated.
16
+ * Used in module creation to register middlewares.
17
+ */
18
+ type KickModuleMiddleware = Newable<any>;
19
+ /**
20
+ * Options for creating a module.
21
+ * Includes arrays of controllers and middlewares to be registered in the module.
22
+ */
23
+ type KickCreateModuleOptionsType = {
24
+ controllers?: KickModuleController[];
25
+ middlewares?: KickModuleMiddleware[];
26
26
  };
27
- interface RouteValidation {
28
- params?: SchemaLike;
29
- query?: SchemaLike;
30
- body?: SchemaLike;
31
- }
32
- interface RouteOptions {
33
- path?: string;
34
- middlewares?: RequestHandler[];
35
- validate?: RouteValidation;
36
- }
37
- type ControllerConstructor<T = unknown> = new (...args: never[]) => T;
38
- declare function Controller(pathOrOptions?: string | ControllerOptions): <T extends ControllerConstructor>(target: T) => void;
39
- declare function Get(path?: string | RouteOptions, ...middlewares: RequestHandler[]): (target: object, propertyKey: string | symbol) => void;
40
- declare function Post(path?: string | RouteOptions, ...middlewares: RequestHandler[]): (target: object, propertyKey: string | symbol) => void;
41
- declare function Put(path?: string | RouteOptions, ...middlewares: RequestHandler[]): (target: object, propertyKey: string | symbol) => void;
42
- declare function Patch(path?: string | RouteOptions, ...middlewares: RequestHandler[]): (target: object, propertyKey: string | symbol) => void;
43
- declare function Delete(path?: string | RouteOptions, ...middlewares: RequestHandler[]): (target: object, propertyKey: string | symbol) => void;
44
- declare function listRegisteredControllers(): ControllerConstructor[];
45
- declare function registerController(controller: ControllerConstructor): void;
46
- declare function resetControllerRegistry(): void;
47
-
48
- interface AppErrorOptions {
49
- status?: number;
50
- cause?: unknown;
51
- details?: Record<string, unknown>;
52
- }
53
- declare class AppError extends Error {
54
- readonly code: string;
55
- readonly status?: number;
56
- readonly details?: Record<string, unknown>;
57
- constructor(code: string, message: string, options?: AppErrorOptions);
58
- }
59
- declare function createError(code: string, message: string, options?: AppErrorOptions): AppError;
60
- declare function isAppError(error: unknown): error is AppError;
61
-
62
- interface ReactiveChangeDetails<TState> {
63
- property: keyof TState;
64
- value: TState[keyof TState];
65
- previous: TState[keyof TState];
66
- timestamp: number;
67
- }
68
- type ReactiveWatcher<TState> = (state: TState, details: ReactiveChangeDetails<TState>) => void;
69
- interface Reactive<TState> {
70
- readonly id: string;
71
- readonly label?: string;
72
- state: TState;
73
- watch(watcher: ReactiveWatcher<TState>): () => void;
74
- snapshot(): TState;
75
- history(): ReactiveChangeDetails<TState>[];
76
- }
77
- declare class ReactiveRegistry {
78
- private readonly stores;
79
- register<TState>(store: Reactive<TState>): void;
80
- unregister(id: string): void;
81
- get<TState>(id: string): Reactive<TState> | undefined;
82
- list(): {
83
- id: string;
84
- label: string | undefined;
85
- snapshot: unknown;
86
- history: ReactiveChangeDetails<unknown>[];
87
- }[];
88
- }
27
+ /**
28
+ * The result of createModule function.
29
+ * Provides an install method to load the module into a dependency container.
30
+ */
31
+ type KickCreateModuleResultType = {
32
+ install: (container: Container) => void;
33
+ name: string;
34
+ };
35
+ /**
36
+ * Function type for creating a module.
37
+ * Takes `CreateModuleOptionsType` and returns `CreateModuleResultType`.
38
+ * @param {string} name - The name of the module.
39
+ * @param {KickCreateModuleOptionsType} options
40
+ * @returns {KickCreateModuleResultType}
41
+ */
42
+ type CreateModuleFuncType = <N extends string = "BaseModule">(name: N, options: KickCreateModuleOptionsType) => KickCreateModuleResultType;
89
43
 
90
- declare const TYPES: {
91
- readonly AppState: symbol;
92
- readonly Config: symbol;
93
- readonly Diagnostics: symbol;
94
- readonly Logger: symbol;
95
- readonly StateRegistry: symbol;
96
- readonly RequestTracker: symbol;
44
+ type BootstrapContext = {
45
+ modules: any[];
46
+ app: Express;
47
+ middlewares?: any[];
97
48
  };
98
- interface AppState extends Record<string, unknown> {
99
- bootedAt: number;
100
- metadata: Record<string, unknown>;
101
- }
102
- interface RequestLogEntry {
103
- timestamp: number;
104
- level: 'debug' | 'info' | 'warn' | 'error';
105
- message: string;
106
- metadata?: Record<string, unknown>;
107
- }
108
- interface RequestState extends Record<string, unknown> {
109
- id: string;
110
- method: string;
111
- path: string;
112
- status?: number;
113
- startedAt: number;
114
- endedAt?: number;
115
- durationMs?: number;
116
- error?: string;
117
- errorCode?: string;
118
- response?: unknown;
119
- logs: RequestLogEntry[];
120
- metadata: Record<string, unknown>;
121
- }
122
49
 
123
- type LogLevel = 'debug' | 'info' | 'warn' | 'error';
124
- interface LoggerConfig {
125
- level?: LogLevel;
50
+ type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "HEAD" | "PATCH" | "TRACE" | "CONNECT" | "ALL";
51
+ type KickNextFn = NextFunction;
52
+ interface KickRequest extends Request {
126
53
  }
127
- interface AppLogger {
128
- readonly level: LogLevel;
129
- debug(message: string, metadata?: Record<string, unknown>): void;
130
- info(message: string, metadata?: Record<string, unknown>): void;
131
- warn(message: string, metadata?: Record<string, unknown>): void;
132
- error(message: string, metadata?: Record<string, unknown>): void;
54
+ interface KickResponse extends Response {
133
55
  }
56
+ type KickRequestHandler = (req: KickRequest, res: KickResponse, next: KickNextFn) => Promise<void> | void;
134
57
 
135
- interface TelemetryConfig {
136
- trackReactiveHistory?: boolean;
137
- requestHistoryLimit?: number;
138
- }
139
- interface ControllerDiscoveryConfig {
140
- enabled?: boolean;
141
- roots?: string[];
142
- suffix?: string;
143
- extensions?: string[];
144
- baseRoute?: string;
145
- segmentSeparator?: string;
146
- enforceStructure?: boolean;
147
- registerGlobally?: boolean;
148
- ignore?: string[];
149
- tagsFromDirectories?: boolean;
150
- allowStaticRoutes?: boolean;
58
+ type CommandStep = string;
59
+ interface KickCommandDefinition {
60
+ name: string;
61
+ description?: string;
62
+ steps?: CommandStep | CommandStep[];
151
63
  }
152
- interface ApiConfig {
153
- discovery?: ControllerDiscoveryConfig;
64
+ interface KickGeneratorsConfig {
65
+ controllerRoot?: string;
154
66
  }
155
- interface AppConfig {
67
+ interface KickAppConfig {
68
+ name?: string;
69
+ port?: number;
70
+ host?: string;
156
71
  prefix?: string;
157
- healthEndpoint?: string | false;
158
- logging?: LoggerConfig;
159
- telemetry?: TelemetryConfig;
160
- api?: ApiConfig;
161
- }
162
- type AppConfigPath = 'prefix' | 'healthEndpoint' | 'logging.level' | 'telemetry.trackReactiveHistory' | 'telemetry.requestHistoryLimit' | 'api.discovery.enabled' | 'api.discovery.roots' | 'api.discovery.baseRoute';
163
- interface ResolvedControllerDiscoveryConfig {
164
- enabled: boolean;
165
- roots: string[];
166
- suffix: string;
167
- extensions: string[];
168
- baseRoute: string;
169
- segmentSeparator: string;
170
- enforceStructure: boolean;
171
- registerGlobally: boolean;
172
- ignore: string[];
173
- tagsFromDirectories: boolean;
174
- allowStaticRoutes: boolean;
72
+ env?: 'development' | 'production' | string;
175
73
  }
176
- interface ResolvedApiConfig {
177
- discovery: ResolvedControllerDiscoveryConfig;
74
+ interface KickDevConfig {
75
+ port?: number;
76
+ host?: string;
77
+ entry?: string;
78
+ watch?: boolean;
79
+ env?: Record<string, string>;
178
80
  }
179
- interface ResolvedAppConfig {
180
- prefix: string;
181
- healthEndpoint: string | false;
182
- logging: Required<LoggerConfig>;
183
- telemetry: Required<TelemetryConfig>;
184
- api: ResolvedApiConfig;
81
+ interface KickStartConfig {
82
+ port?: number;
83
+ host?: string;
84
+ entry?: string;
85
+ env?: Record<string, string>;
185
86
  }
186
- interface EnvBindingOptions<T = unknown> {
187
- path: AppConfigPath;
188
- transform?: (value: string, env: NodeJS.ProcessEnv) => T;
87
+ interface KickCliConfig {
88
+ commands?: KickCommandDefinition[];
89
+ generators?: KickGeneratorsConfig;
90
+ structure?: KickStructureConfig;
91
+ app?: KickAppConfig;
92
+ dev?: KickDevConfig;
93
+ start?: KickStartConfig;
189
94
  }
190
- type EnvBinding = AppConfigPath | EnvBindingOptions | ((value: string, env: NodeJS.ProcessEnv) => AppConfig);
191
- interface CreateKickConfigOptions {
192
- defaults?: AppConfig;
193
- env?: Record<string, EnvBinding>;
194
- overrides?: AppConfig | ((config: AppConfig) => AppConfig);
195
- envFiles?: string[] | false;
95
+ interface KickStructureConfig {
96
+ domainRoot?: string;
97
+ domainFolders?: string[];
98
+ defaultDomain?: string;
196
99
  }
197
- declare function createKickConfig(options?: CreateKickConfigOptions): AppConfig;
198
- declare function configureApp(config: AppConfig): void;
199
- declare function getAppConfig(): ResolvedAppConfig;
200
- declare function resolveConfig(overrides?: AppConfig): ResolvedAppConfig;
201
- declare function resetAppConfig(): void;
100
+ type KickConfig = KickCliConfig;
202
101
 
203
- declare module 'express-serve-static-core' {
204
- interface Locals {
205
- requestState?: Reactive<RequestState>;
206
- }
102
+ /**
103
+ * The application context interface for KickJS applications.
104
+ * Holds request handlers, middlewares, and the Express application instance.
105
+ */
106
+ interface KickApplicationContext {
107
+ requestHandlers: Record<string, KickRouteMetadata>;
108
+ middlewares: KickAppMiddleware[];
109
+ app: Application;
207
110
  }
208
- declare class RequestTracker {
209
- private readonly registry;
210
- private readonly config;
211
- private readonly logger;
212
- constructor(registry: ReactiveRegistry, config: ResolvedAppConfig, logger: AppLogger);
213
- middleware(): (req: Request, res: Response, next: NextFunction) => void;
214
- get(res: Response): Reactive<RequestState> | undefined;
215
- log(res: Response, message: string, level?: RequestLogEntry['level'], metadata?: Record<string, unknown>): void;
216
- mergeMetadata(res: Response, patch: Record<string, unknown>): void;
217
- recordResponse(res: Response, status: number, payload?: unknown): void;
218
- recordError(res: Response, error: unknown): void;
219
- private finalise;
220
- private dispatchLog;
111
+ /**
112
+ * A middleware handler function that operates on the application context.
113
+ * @param context - The application context.
114
+ * @returns A promise that resolves when the middleware has completed its operation.
115
+ */
116
+ interface KickAppMiddleware {
117
+ use: KickRequestHandler;
221
118
  }
222
-
223
- declare abstract class BaseController {
224
- private injectedTracker?;
225
- private runtimeTracker?;
226
- protected abstract controllerId(): string;
227
- protected ok<T>(res: Response, payload: T): Response<any, Record<string, any>>;
228
- protected created<T>(res: Response, payload: T): Response<any, Record<string, any>>;
229
- protected accepted<T>(res: Response, payload: T): Response<any, Record<string, any>>;
230
- protected noContent(res: Response): Response<any, Record<string, any>>;
231
- protected respond<T>(res: Response, status: number, payload?: T): Response<any, Record<string, any>>;
232
- protected logDebug(res: Response, message: string, metadata?: Record<string, unknown>): void;
233
- protected logInfo(res: Response, message: string, metadata?: Record<string, unknown>): void;
234
- protected logWarn(res: Response, message: string, metadata?: Record<string, unknown>): void;
235
- protected logError(res: Response, message: string, metadata?: Record<string, unknown>): void;
236
- protected mergeRequestMetadata(res: Response, patch: Record<string, unknown>): void;
237
- protected getRequestState(res: Response): RequestState | undefined;
238
- protected fail(code: string, message: string, options?: AppErrorOptions): never;
239
- attachRequestTracker(tracker: RequestTracker): void;
240
- private ensureTracker;
119
+ type KickAppPlugin = {
120
+ install: (context: KickApplicationContext) => void;
121
+ };
122
+ interface KickApplication {
123
+ context: KickApplicationContext;
124
+ name: string;
125
+ config?: KickAppConfig;
241
126
  }
242
127
 
128
+ type CreateRouteType = {
129
+ middlewares?: KickAppMiddleware[];
130
+ };
131
+ type KickRouteMetadata = {
132
+ path: string;
133
+ method: string;
134
+ handlerName: string;
135
+ handler: Function;
136
+ middlewares?: CreateRouteType["middlewares"];
137
+ };
138
+ type KickControllerOptions = {
139
+ middlewares?: KickAppMiddleware[];
140
+ };
141
+
243
142
  /**
244
- * Base class for controllers that target a specific HTTP verb. Each discovered controller
245
- * should extend one of the verb specific classes so that single responsibility is enforced.
143
+ * Request context that gets injected into controller methods
144
+ * Contains all the necessary Express objects and metadata for handling HTTP requests
246
145
  */
247
- declare abstract class HttpVerbController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends BaseController {
146
+ interface KickRequestContext {
248
147
  /**
249
- * Return the HTTP method associated with this controller. Static so discovery can consume it
250
- * without instantiating the controller (which would require container dependencies).
148
+ * Express request object
251
149
  */
252
- static method(): HttpMethod;
253
- /** HTTP method instance mirror for convenience in handlers/tests. */
254
- readonly httpMethod: HttpMethod;
150
+ req: KickRequest;
255
151
  /**
256
- * Optional static override for the route path. When provided, discovery will use this value
257
- * instead of deriving the path from the file-system location.
152
+ * Express response object
258
153
  */
259
- static route?: string;
154
+ res: KickResponse;
260
155
  /**
261
- * Optional static tags collection. These map to the controller metadata and can be used by
262
- * diagnostics tooling.
156
+ * Express next function for middleware chaining
263
157
  */
264
- static tags?: string[];
265
- protected controllerId(): string;
158
+ next: KickNextFn;
266
159
  /**
267
- * Handle the request for the configured HTTP verb.
160
+ * Additional metadata about the request/route
268
161
  */
269
- abstract handle(req: Req, res: Res, next: NextFunction): Result | Promise<Result>;
270
- }
271
- declare abstract class GetController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends HttpVerbController<Req, Res, Result> {
272
- static method(): HttpMethod;
273
- }
274
- declare abstract class PostController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends HttpVerbController<Req, Res, Result> {
275
- static method(): HttpMethod;
276
- }
277
- declare abstract class PutController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends HttpVerbController<Req, Res, Result> {
278
- static method(): HttpMethod;
279
- }
280
- declare abstract class PatchController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends HttpVerbController<Req, Res, Result> {
281
- static method(): HttpMethod;
282
- }
283
- declare abstract class DeleteController<Req extends Request = Request, Res extends Response = Response, Result = unknown> extends HttpVerbController<Req, Res, Result> {
284
- static method(): HttpMethod;
162
+ meta: {
163
+ /**
164
+ * The route path pattern (e.g., "/todos/:id")
165
+ */
166
+ routePath: string;
167
+ /**
168
+ * The HTTP method (GET, POST, etc.)
169
+ */
170
+ method: string;
171
+ /**
172
+ * The controller class name
173
+ */
174
+ controllerName: string;
175
+ /**
176
+ * The handler method name
177
+ */
178
+ handlerName: string;
179
+ /**
180
+ * Timestamp when the request started processing
181
+ */
182
+ startTime: number;
183
+ /**
184
+ * Request ID for tracking/logging
185
+ */
186
+ requestId: string;
187
+ };
285
188
  }
286
189
 
287
- interface DiscoveredController {
288
- controller: ControllerConstructor;
289
- filePath: string;
290
- route: string;
291
- method: HttpMethod;
292
- tags: string[];
293
- }
294
- declare function discoverControllersFromFilesystem(config: ResolvedControllerDiscoveryConfig): DiscoveredController[];
190
+ declare function KickGet<PathName extends string>(path: PathName, options?: CreateRouteType): (target: any, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => void;
191
+ declare function KickPost<PathName extends string>(path: PathName, options?: CreateRouteType): (target: any, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => void;
192
+ declare function KickPut<PathName extends string>(path: PathName, options?: CreateRouteType): (target: any, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => void;
193
+ declare function KickPatch<PathName extends string>(path: PathName, options?: CreateRouteType): (target: any, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => void;
194
+ declare function KickDelete<PathName extends string>(path: PathName, options?: CreateRouteType): (target: any, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => void;
295
195
 
296
- interface StoreSnapshot {
297
- id: string;
298
- label?: string;
299
- snapshot: Record<string, unknown>;
300
- history: ReadonlyArray<unknown>;
301
- }
302
- interface RequestSnapshot extends RequestState {
303
- }
304
- declare class AppDiagnostics {
305
- private readonly registry;
306
- private readonly config;
307
- constructor(registry: ReactiveRegistry, config: ResolvedAppConfig);
308
- settings(): ResolvedAppConfig;
309
- stores(): StoreSnapshot[];
310
- requests(): RequestSnapshot[];
196
+ /**
197
+ * @author Felix Orinda
198
+ * @decorator `KickController`:
199
+ * Decorator to define a controller with a base path and options.
200
+ * Also marks the class as injectable for DI.
201
+ * @param {string} path
202
+ * @param {KickControllerOptions} options
203
+ * @returns
204
+ */
205
+ declare function KickController<PathName extends string>(path: PathName, options?: KickControllerOptions): ClassDecorator;
206
+
207
+ declare function AutoBind(target: any): void;
208
+
209
+ /**
210
+ * KickMiddleware decorator options
211
+ */
212
+ interface KickMiddlewareOptions {
213
+ /**
214
+ * Optional name for the middleware (for logging/debugging)
215
+ */
216
+ name?: string;
217
+ /**
218
+ * Priority for middleware execution order (lower numbers execute first)
219
+ */
220
+ priority?: number;
221
+ /**
222
+ * Whether this middleware should be applied globally
223
+ */
224
+ global?: boolean;
225
+ /**
226
+ * Optional tags for categorizing middleware
227
+ */
228
+ tags?: string[];
311
229
  }
230
+ /**
231
+ * @decorator `KickMiddleware`:
232
+ * Decorator to define a middleware class with automatic property binding and DI registration.
233
+ * This decorator automatically applies AutoBind and makes the class injectable.
234
+ *
235
+ * @param {KickMiddlewareOptions} options - Optional middleware configuration
236
+ * @returns {ClassDecorator}
237
+ *
238
+ * @example
239
+ * ```typescript
240
+ * @KickMiddleware({ name: 'Logger', priority: 1, global: true })
241
+ * export class LoggerMiddleware extends BaseKickMiddleware {
242
+ * use = (req: KickRequest, res: KickResponse, next: KickNextFn) => {
243
+ * console.log(`${req.method} ${req.url}`);
244
+ * next();
245
+ * }
246
+ * }
247
+ * ```
248
+ */
249
+ declare function KickMiddleware(options?: KickMiddlewareOptions): ClassDecorator;
250
+ /**
251
+ * Helper function to check if a class is a KickMiddleware
252
+ */
253
+ declare function isKickMiddleware(target: any): boolean;
254
+ /**
255
+ * Helper function to get middleware metadata from a class
256
+ */
257
+ declare function getMiddlewareMetadata(target: any): KickMiddlewareOptions & {
258
+ className: string;
259
+ } | undefined;
260
+
261
+ declare const KICK_MODULE_KEYS: {
262
+ KickControllerType: symbol;
263
+ KickMiddlewareType: symbol;
264
+ };
265
+ declare const KICK_CONTROLLER_METADATA_KEYS: {
266
+ path: symbol;
267
+ options: symbol;
268
+ routes: symbol;
269
+ middlewares: symbol;
270
+ middlewareOptions: symbol;
271
+ isMiddleware: symbol;
272
+ };
273
+
274
+ /**
275
+ * Map the controller metadata to a route configuration
276
+ * @param {KickModuleController} controller
277
+ * @returns {KickRouteMetadata[]}
278
+ */
279
+ declare function mapController(controller: KickModuleController): {
280
+ path: string;
281
+ middlewares: KickAppMiddleware[];
282
+ method: string;
283
+ handlerName: string;
284
+ handler: Function;
285
+ }[];
312
286
 
313
- interface CreateAppOptions {
314
- controllers?: Array<new (...args: never[]) => unknown>;
315
- container?: Container;
316
- additionalMiddleware?: Array<(req: Request, res: Response, next: NextFunction) => void>;
317
- config?: AppConfig;
318
- configureContainer?: (container: Container) => void;
287
+ /**
288
+ * Normalizes a route path by ensuring it starts with a `'/'` and does not end with a `'/'`.
289
+ * @param {any} path
290
+ * @returns {string}
291
+ */
292
+ declare function normalizeRoutePath(path: any): string;
293
+ /**
294
+ * Combine base path and route path into a full path
295
+ * @param {string} basePath
296
+ * @param {string} routePath
297
+ * @returns {string}
298
+ */
299
+ declare function combineRoutePaths(basePath: string, routePath: string): string;
300
+
301
+ declare const KickInject: typeof inject;
302
+ declare const KickInjectable: typeof injectable;
303
+
304
+ declare function bindClassMethods(instance: any): void;
305
+
306
+ /**
307
+ * Route mapper utility for creating contextual handlers
308
+ */
309
+ declare class RouteMapper {
310
+ /**
311
+ * Creates a contextual handler that injects request context into controller methods
312
+ * @param controller - The controller instance
313
+ * @param route - The route metadata
314
+ * @param prefix - Optional prefix to prepend to route paths
315
+ * @returns Express-compatible handler function
316
+ */
317
+ static createContextualHandler(controller: any, route: KickRouteMetadata, prefix?: string): (req: KickRequest, res: KickResponse, next: KickNextFn) => any;
318
+ /**
319
+ * Builds the full route path by combining prefix and route path
320
+ * @param prefix - The prefix to prepend
321
+ * @param routePath - The route path
322
+ * @returns Combined route path
323
+ */
324
+ static buildRoutePath(prefix: string, routePath: string): string;
325
+ /**
326
+ * Maps a controller to its routes with optional prefix
327
+ * @param controller - The controller instance
328
+ * @param routes - The route metadata array
329
+ * @param prefix - Optional prefix to prepend to all routes
330
+ * @returns Array of mapped route information
331
+ */
332
+ static mapControllerRoutes(controller: any, routes: KickRouteMetadata[], prefix?: string): {
333
+ fullPath: string;
334
+ handler: (req: KickRequest, res: KickResponse, next: KickNextFn) => any;
335
+ controllerName: any;
336
+ path: string;
337
+ method: string;
338
+ handlerName: string;
339
+ middlewares?: CreateRouteType["middlewares"];
340
+ }[];
341
+ /**
342
+ * Logs route registration information
343
+ * @param method - HTTP method
344
+ * @param path - Route path
345
+ * @param handlerName - Handler method name
346
+ * @param controllerName - Controller class name
347
+ * @param prefix - Optional prefix used
348
+ */
349
+ static logRouteRegistration(method: string, path: string, handlerName: string, controllerName: string, prefix?: string): void;
319
350
  }
320
- interface CreateAppResult {
321
- app: Application;
322
- container: Container;
323
- requestTracker: RequestTracker;
324
- diagnostics: AppDiagnostics;
325
- config: ResolvedAppConfig;
326
- discovery: {
327
- controllers: DiscoveredController[];
351
+
352
+ /**
353
+ * Load KickJS app configuration for use in applications
354
+ */
355
+ declare function loadAppConfig(overrides?: Partial<KickAppConfig>): Promise<KickAppConfig>;
356
+ /**
357
+ * Get app configuration from environment variables and config
358
+ */
359
+ declare function getConfigFromEnv(): Partial<KickAppConfig>;
360
+
361
+ declare class KickApp extends EventEmitter implements KickApplication {
362
+ context: KickApplicationContext;
363
+ name: string;
364
+ prefix: string;
365
+ config?: KickAppConfig;
366
+ private container;
367
+ private _isInitialized;
368
+ private _state;
369
+ constructor(context: KickApplicationContext, name?: string, prefix?: string, config?: KickAppConfig);
370
+ get isInitialized(): boolean;
371
+ get controllers(): any[];
372
+ get state(): Readonly<Record<string, any>>;
373
+ setState(key: string, value: any): void;
374
+ getState(key: string): any;
375
+ onStateChange(key: string, listener: (data: {
376
+ value: any;
377
+ oldValue: any;
378
+ }) => void): void;
379
+ offStateChange(key: string, listener: (data: {
380
+ value: any;
381
+ oldValue: any;
382
+ }) => void): void;
383
+ /**
384
+ * Get a configuration value by key path (supports nested access like 'database.host')
385
+ */
386
+ getConfig<T = any>(key?: string): T | undefined;
387
+ /**
388
+ * Check if a configuration key exists
389
+ */
390
+ hasConfig(key: string): boolean;
391
+ /**
392
+ * Get config value with fallback
393
+ */
394
+ getConfigOrDefault<T>(key: string, defaultValue: T): T;
395
+ loadPlugin(plugins: KickAppPlugin | KickAppPlugin[]): this;
396
+ registerMiddleware(middleware: KickAppMiddleware | KickAppMiddleware[]): this;
397
+ mountMiddlewares(): this;
398
+ loadModules(modules: KickCreateModuleResultType[]): this;
399
+ private extractMiddlewaresFromContainer;
400
+ private mapControllers;
401
+ getContainer(): Container;
402
+ getStats(): {
403
+ name: string;
404
+ isInitialized: boolean;
405
+ controllersCount: number;
406
+ middlewaresCount: number;
407
+ routes: string[];
408
+ routesCount: number;
409
+ state: Readonly<Record<string, any>>;
328
410
  };
411
+ addErrorHandler(handler: (error: Error, context?: any) => void): void;
412
+ handleError(error: Error, context?: any): void;
413
+ addRequestInterceptor(interceptor: (req: KickRequest, res: KickResponse, next: KickNextFn) => void): void;
329
414
  }
330
- interface BootstrapOptions extends CreateAppOptions {
331
- port?: number | string;
332
- }
333
- interface BootstrapContext {
334
- app: Application;
335
- server: Server;
336
- container: Container;
337
- requestTracker: RequestTracker;
338
- diagnostics: AppDiagnostics;
339
- config: ResolvedAppConfig;
340
- discovery: {
341
- controllers: DiscoveredController[];
415
+ type CreateKickAppOptions = {
416
+ name?: string;
417
+ prefix?: string;
418
+ config?: KickAppConfig;
419
+ app: KickApplicationContext["app"];
420
+ plugins?: KickAppPlugin[];
421
+ globalMiddlewares?: KickAppMiddleware[];
422
+ modules: KickCreateModuleResultType[];
423
+ };
424
+ declare function createKickApp(options: CreateKickAppOptions): {
425
+ listen: {
426
+ (port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
427
+ (port?: number, hostname?: string, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
428
+ (port?: number, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
429
+ (port?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
430
+ (path: string, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
431
+ (path: string, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
432
+ (options: net.ListenOptions, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
433
+ (handle: any, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
434
+ (handle: any, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
342
435
  };
343
- shutdown(): void;
344
- }
345
- declare function createApp(options?: CreateAppOptions): CreateAppResult;
346
- declare function bootstrap(options?: BootstrapOptions): Promise<BootstrapContext>;
436
+ close: (callback?: (err?: Error) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
437
+ address: () => net.AddressInfo | string | null;
438
+ getConnections: (cb: (error: Error | null, count: number) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
439
+ on: {
440
+ (event: string, listener: (...args: any[]) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
441
+ (event: "close", listener: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
442
+ (event: "connection", listener: (socket: net.Socket) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
443
+ (event: "error", listener: (err: Error) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
444
+ (event: "listening", listener: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
445
+ (event: "checkContinue", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
446
+ (event: "checkExpectation", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
447
+ (event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
448
+ (event: "connect", listener: (req: http.IncomingMessage, socket: stream.Duplex, head: Buffer) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
449
+ (event: "dropRequest", listener: (req: http.IncomingMessage, socket: stream.Duplex) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
450
+ (event: "request", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
451
+ (event: "upgrade", listener: (req: http.IncomingMessage, socket: stream.Duplex, head: Buffer) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
452
+ };
453
+ off: <K>(eventName: string | symbol, listener: (...args: any[]) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
454
+ emit: {
455
+ (event: string, ...args: any[]): boolean;
456
+ (event: "close"): boolean;
457
+ (event: "connection", socket: net.Socket): boolean;
458
+ (event: "error", err: Error): boolean;
459
+ (event: "listening"): boolean;
460
+ (event: "checkContinue", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
461
+ req: http.IncomingMessage;
462
+ }): boolean;
463
+ (event: "checkExpectation", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
464
+ req: http.IncomingMessage;
465
+ }): boolean;
466
+ (event: "clientError", err: Error, socket: stream.Duplex): boolean;
467
+ (event: "connect", req: http.IncomingMessage, socket: stream.Duplex, head: Buffer): boolean;
468
+ (event: "dropRequest", req: http.IncomingMessage, socket: stream.Duplex): boolean;
469
+ (event: "request", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
470
+ req: http.IncomingMessage;
471
+ }): boolean;
472
+ (event: "upgrade", req: http.IncomingMessage, socket: stream.Duplex, head: Buffer): boolean;
473
+ };
474
+ kickApp: KickApp;
475
+ app: express.Application;
476
+ getStats: () => {
477
+ name: string;
478
+ isInitialized: boolean;
479
+ controllersCount: number;
480
+ middlewaresCount: number;
481
+ routes: string[];
482
+ routesCount: number;
483
+ state: Readonly<Record<string, any>>;
484
+ };
485
+ getState: () => Readonly<Record<string, any>>;
486
+ setState: (key: string, value: any) => void;
487
+ onStateChange: (key: string, listener: any) => void;
488
+ onKickEvent: (event: string, listener: any) => KickApp;
489
+ offKickEvent: (event: string, listener: any) => KickApp;
490
+ emitKickEvent: (event: string, data?: any) => boolean;
491
+ addErrorHandler: (handler: any) => void;
492
+ handleError: (error: Error, context?: any) => void;
493
+ };
494
+ /**
495
+ * Create a KickApp with automatic config loading
496
+ */
497
+ declare function createKickAppWithConfig(options: Omit<CreateKickAppOptions, 'config'> & {
498
+ configOverrides?: Partial<KickAppConfig>;
499
+ }): Promise<{
500
+ listen: {
501
+ (port?: number, hostname?: string, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
502
+ (port?: number, hostname?: string, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
503
+ (port?: number, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
504
+ (port?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
505
+ (path: string, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
506
+ (path: string, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
507
+ (options: net.ListenOptions, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
508
+ (handle: any, backlog?: number, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
509
+ (handle: any, listeningListener?: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
510
+ };
511
+ close: (callback?: (err?: Error) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
512
+ address: () => net.AddressInfo | string | null;
513
+ getConnections: (cb: (error: Error | null, count: number) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
514
+ on: {
515
+ (event: string, listener: (...args: any[]) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
516
+ (event: "close", listener: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
517
+ (event: "connection", listener: (socket: net.Socket) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
518
+ (event: "error", listener: (err: Error) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
519
+ (event: "listening", listener: () => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
520
+ (event: "checkContinue", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
521
+ (event: "checkExpectation", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
522
+ (event: "clientError", listener: (err: Error, socket: stream.Duplex) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
523
+ (event: "connect", listener: (req: http.IncomingMessage, socket: stream.Duplex, head: Buffer) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
524
+ (event: "dropRequest", listener: (req: http.IncomingMessage, socket: stream.Duplex) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
525
+ (event: "request", listener: http.RequestListener<typeof http.IncomingMessage, typeof http.ServerResponse>): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
526
+ (event: "upgrade", listener: (req: http.IncomingMessage, socket: stream.Duplex, head: Buffer) => void): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
527
+ };
528
+ off: <K>(eventName: string | symbol, listener: (...args: any[]) => void) => http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
529
+ emit: {
530
+ (event: string, ...args: any[]): boolean;
531
+ (event: "close"): boolean;
532
+ (event: "connection", socket: net.Socket): boolean;
533
+ (event: "error", err: Error): boolean;
534
+ (event: "listening"): boolean;
535
+ (event: "checkContinue", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
536
+ req: http.IncomingMessage;
537
+ }): boolean;
538
+ (event: "checkExpectation", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
539
+ req: http.IncomingMessage;
540
+ }): boolean;
541
+ (event: "clientError", err: Error, socket: stream.Duplex): boolean;
542
+ (event: "connect", req: http.IncomingMessage, socket: stream.Duplex, head: Buffer): boolean;
543
+ (event: "dropRequest", req: http.IncomingMessage, socket: stream.Duplex): boolean;
544
+ (event: "request", req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage> & {
545
+ req: http.IncomingMessage;
546
+ }): boolean;
547
+ (event: "upgrade", req: http.IncomingMessage, socket: stream.Duplex, head: Buffer): boolean;
548
+ };
549
+ kickApp: KickApp;
550
+ app: express.Application;
551
+ getStats: () => {
552
+ name: string;
553
+ isInitialized: boolean;
554
+ controllersCount: number;
555
+ middlewaresCount: number;
556
+ routes: string[];
557
+ routesCount: number;
558
+ state: Readonly<Record<string, any>>;
559
+ };
560
+ getState: () => Readonly<Record<string, any>>;
561
+ setState: (key: string, value: any) => void;
562
+ onStateChange: (key: string, listener: any) => void;
563
+ onKickEvent: (event: string, listener: any) => KickApp;
564
+ offKickEvent: (event: string, listener: any) => KickApp;
565
+ emitKickEvent: (event: string, data?: any) => boolean;
566
+ addErrorHandler: (handler: any) => void;
567
+ handleError: (error: Error, context?: any) => void;
568
+ }>;
347
569
 
348
- type CommandStep = string;
349
- interface KickCommandDefinition {
350
- name: string;
351
- description?: string;
352
- steps?: CommandStep | CommandStep[];
353
- }
354
- interface KickGeneratorsConfig {
355
- controllerRoot?: string;
356
- }
357
- interface KickCliConfig {
358
- commands?: KickCommandDefinition[];
359
- generators?: KickGeneratorsConfig;
360
- structure?: KickStructureConfig;
570
+ declare abstract class BaseKickPlugin implements KickAppPlugin {
571
+ /**
572
+ * Installs the plugin into the application context.
573
+ * The context parameter provides access to the application's components and modules.
574
+ * @param {KickApplicationContext} context
575
+ */
576
+ abstract install(context: KickApplicationContext): void;
361
577
  }
362
- interface KickStructureConfig {
363
- domainRoot?: string;
364
- domainFolders?: string[];
365
- defaultDomain?: string;
578
+
579
+ declare abstract class BaseKickMiddleware implements KickAppMiddleware {
580
+ /**
581
+ * The middleware function to be implemented by subclasses.
582
+ * This function will be called with the request, response, and next function.
583
+ */
584
+ abstract use: KickRequestHandler;
366
585
  }
367
- type KickConfig = KickCliConfig;
368
586
 
369
- type BindingIdentifier<T = unknown> = ServiceIdentifier<T>;
370
- declare function Injectable(): ClassDecorator;
371
- declare function Inject<T = unknown>(identifier: BindingIdentifier<T>): MethodDecorator & ParameterDecorator & PropertyDecorator;
372
- declare function Optional(): MethodDecorator & ParameterDecorator & PropertyDecorator;
373
- declare function MultiInject<T = unknown>(identifier: BindingIdentifier<T>): MethodDecorator & ParameterDecorator & PropertyDecorator;
374
- declare function Named(name: string | number | symbol): MethodDecorator & ParameterDecorator & PropertyDecorator;
375
- declare function Tagged(metadataKey: string | number | symbol, metadataValue: unknown): MethodDecorator & ParameterDecorator & PropertyDecorator;
376
- declare function Unmanaged(): MethodDecorator & ParameterDecorator & PropertyDecorator;
587
+ /**
588
+ * Creates a module with the given options.
589
+ * This module can then be installed into an Inversify container.
590
+ * Helps load controllers and avoid duplicate bindings.
591
+ * @param {KickCreateModuleOptionsType} options
592
+ * @returns
593
+ */
594
+ declare const createModule: CreateModuleFuncType;
595
+
596
+ /**
597
+ * Create a KickJS configuration with TypeScript intellisense support
598
+ */
599
+ declare function createKickConfig(config: KickConfig): KickConfig;
600
+ /**
601
+ * Helper function to create app-specific configuration
602
+ */
603
+ declare function defineAppConfig(config: KickAppConfig): KickAppConfig;
604
+ /**
605
+ * Helper function to create development configuration
606
+ */
607
+ declare function defineDevConfig(config: KickDevConfig): KickDevConfig;
608
+ /**
609
+ * Helper function to create production configuration
610
+ */
611
+ declare function defineStartConfig(config: KickStartConfig): KickStartConfig;
377
612
 
378
- export { type ApiConfig, type AppConfig, type AppConfigPath, AppDiagnostics, AppError, type AppErrorOptions, type AppState, BaseController, type BindingIdentifier, type BootstrapContext, type BootstrapOptions, Controller, type ControllerConstructor, type ControllerDiscoveryConfig, type CreateAppOptions, type CreateAppResult, type CreateKickConfigOptions, Delete, DeleteController, type DiscoveredController, type EnvBinding, type EnvBindingOptions, Get, GetController, HttpVerbController, Inject, Injectable, type KickCliConfig, type KickCommandDefinition, type KickConfig, type KickStructureConfig, MultiInject, Named, Optional, Patch, PatchController, Post, PostController, Put, PutController, type RequestLogEntry, type RequestState, RequestTracker, type ResolvedApiConfig, type ResolvedAppConfig, type ResolvedControllerDiscoveryConfig, type RouteOptions, type RouteValidation, TYPES, Tagged, Unmanaged, bootstrap, configureApp, createApp, createError, createKickConfig, discoverControllersFromFilesystem, getAppConfig, isAppError, listRegisteredControllers, registerController, resetAppConfig, resetControllerRegistry, resolveConfig };
613
+ export { AutoBind, BaseKickMiddleware, BaseKickPlugin, type BootstrapContext, type CreateModuleFuncType, type CreateRouteType, type HttpMethod, KICK_CONTROLLER_METADATA_KEYS, KICK_MODULE_KEYS, KickApp, type KickAppConfig, type KickAppMiddleware, type KickAppPlugin, type KickApplication, type KickApplicationContext, type KickConfig, KickController, type KickControllerOptions, type KickCreateModuleOptionsType, type KickCreateModuleResultType, KickDelete, type KickDevConfig, KickGet, KickInject, KickInjectable, KickMiddleware, type KickMiddlewareOptions, type KickModuleController, type KickModuleMiddleware, type KickNextFn, KickPatch, KickPost, KickPut, type KickRequest, type KickRequestContext, type KickRequestHandler, type KickResponse, type KickRouteMetadata, type KickStartConfig, RouteMapper, bindClassMethods, combineRoutePaths, createKickApp, createKickAppWithConfig, createKickConfig, createModule, defineAppConfig, defineDevConfig, defineStartConfig, getConfigFromEnv, getMiddlewareMetadata, isKickMiddleware, loadAppConfig, mapController, normalizeRoutePath };