@veloxts/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Core TypeScript types for the VeloxTS framework
+ * @module types
+ */
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/**
+ * Primitive JSON value types
+ */
+export type JsonPrimitive = string | number | boolean | null;
+/**
+ * JSON-serializable array type
+ */
+export type JsonArray = JsonValue[];
+/**
+ * JSON-serializable object type
+ */
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+/**
+ * Any JSON-serializable value
+ *
+ * Represents values that can be safely serialized to JSON and sent in HTTP responses.
+ * Use this type to ensure handler return values are serializable.
+ *
+ * @example
+ * ```typescript
+ * // Valid JsonValue examples
+ * const str: JsonValue = "hello";
+ * const num: JsonValue = 42;
+ * const arr: JsonValue = [1, 2, 3];
+ * const obj: JsonValue = { name: "John", age: 30 };
+ *
+ * // Invalid - functions are not JSON serializable
+ * // const fn: JsonValue = () => {}; // Error!
+ * ```
+ */
+export type JsonValue = JsonPrimitive | JsonArray | JsonObject;
+/**
+ * Async request handler function signature
+ *
+ * Handlers return JSON-serializable data or void. The response type
+ * can be narrowed for better type safety in specific handlers.
+ *
+ * @template TContext - The context type available in the handler
+ * @template TResponse - The response type (must be JSON serializable or void)
+ * @param request - Fastify request object with context
+ * @param reply - Fastify reply object
+ * @returns Promise resolving to response data or void
+ *
+ * @example
+ * ```typescript
+ * // Handler with inferred response type
+ * const handler: AsyncHandler<BaseContext> = async (request, reply) => {
+ *   return { message: 'Hello World' };
+ * };
+ *
+ * // Handler with explicit response type
+ * type UserResponse = { id: string; name: string };
+ * const getUser: AsyncHandler<BaseContext, UserResponse> = async (request) => {
+ *   return { id: '1', name: 'John' };
+ * };
+ * ```
+ */
+export type AsyncHandler<TContext = unknown, TResponse extends JsonValue | undefined = JsonValue | undefined> = (request: FastifyRequest & {
+    context: TContext;
+}, reply: FastifyReply) => Promise<TResponse>;
+/**
+ * Synchronous request handler function signature
+ *
+ * @template TContext - The context type available in the handler
+ * @template TResponse - The response type (must be JSON serializable or void)
+ * @param request - Fastify request object with context
+ * @param reply - Fastify reply object
+ * @returns Response data or void
+ *
+ * @example
+ * ```typescript
+ * const handler: SyncHandler<BaseContext> = (request, reply) => {
+ *   return { message: 'Hello World' };
+ * };
+ * ```
+ */
+export type SyncHandler<TContext = unknown, TResponse extends JsonValue | undefined = JsonValue | undefined> = (request: FastifyRequest & {
+    context: TContext;
+}, reply: FastifyReply) => TResponse;
+/**
+ * Lifecycle hook function signature
+ * Hooks are called at specific points in the request/response lifecycle
+ *
+ * @param request - Fastify request object
+ * @param reply - Fastify reply object
+ * @returns Promise that resolves when hook processing is complete
+ *
+ * @example
+ * ```typescript
+ * const hook: LifecycleHook = async (request, reply) => {
+ *   console.log('Request received:', request.url);
+ * };
+ * ```
+ */
+export type LifecycleHook = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * Shutdown handler function signature
+ * Called during graceful shutdown to clean up resources
+ *
+ * @returns Promise that resolves when cleanup is complete
+ *
+ * @example
+ * ```typescript
+ * const shutdownHandler: ShutdownHandler = async () => {
+ *   await database.disconnect();
+ *   console.log('Database connection closed');
+ * };
+ * ```
+ */
+export type ShutdownHandler = () => Promise<void>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAM5D;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,EAAE,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEtD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,GAAG,UAAU,CAAC;AAM/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,YAAY,CACtB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,IAC7D,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;AAEjG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,CACrB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,IAC7D,CAAC,OAAO,EAAE,cAAc,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,EAAE,KAAK,EAAE,YAAY,KAAK,SAAS,CAAC;AAMxF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE5F;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core TypeScript types for the VeloxTS framework
+ * @module types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/utils/config.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Configuration types and utilities for VeloxTS application
+ * @module utils/config
+ */
+import type { FastifyLoggerOptions, FastifyServerOptions } from 'fastify';
+/**
+ * Brand symbol for validated port numbers
+ */
+declare const ValidPortBrand: unique symbol;
+/**
+ * Branded type for validated port numbers (0-65535)
+ *
+ * Values of this type have been validated and are guaranteed to be
+ * valid port numbers. Use `isValidPort()` to narrow a number to this type.
+ *
+ * @example
+ * ```typescript
+ * function listen(port: ValidPort) {
+ *   // port is guaranteed to be 0-65535
+ * }
+ *
+ * const port = 3000;
+ * if (isValidPort(port)) {
+ *   listen(port); // TypeScript knows port is ValidPort here
+ * }
+ * ```
+ */
+export type ValidPort = number & {
+    readonly [ValidPortBrand]: typeof ValidPortBrand;
+};
+/**
+ * Brand symbol for validated host strings
+ */
+declare const ValidHostBrand: unique symbol;
+/**
+ * Branded type for validated host strings
+ *
+ * Values of this type have been validated and are guaranteed to be
+ * non-empty strings. Use `isValidHost()` to narrow a string to this type.
+ */
+export type ValidHost = string & {
+    readonly [ValidHostBrand]: typeof ValidHostBrand;
+};
+/**
+ * VeloxTS-specific Fastify options (excluding options VeloxTS controls)
+ *
+ * The `logger` option is excluded because VeloxTS controls logging
+ * through the top-level `logger` configuration option.
+ *
+ * @example
+ * ```typescript
+ * const config: VeloxAppConfig = {
+ *   logger: true, // Use this for logging
+ *   fastify: {
+ *     // logger is NOT allowed here - TypeScript will error
+ *     trustProxy: true,
+ *     maxParamLength: 200,
+ *   }
+ * };
+ * ```
+ */
+export type VeloxFastifyOptions = Omit<FastifyServerOptions, 'logger'>;
+/**
+ * Configuration options for creating a VeloxTS application
+ *
+ * @example
+ * ```typescript
+ * const config: VeloxAppConfig = {
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   logger: true
+ * };
+ * ```
+ */
+export interface VeloxAppConfig {
+    /**
+     * Port to listen on
+     * @default 3000
+     */
+    port?: number;
+    /**
+     * Host to bind to
+     * @default '0.0.0.0'
+     */
+    host?: string;
+    /**
+     * Enable Fastify logger
+     * - `true` enables default logger
+     * - `false` disables logging
+     * - Object provides custom logger configuration
+     *
+     * @default true in development, false in production
+     */
+    logger?: boolean | FastifyLoggerOptions;
+    /**
+     * Custom Fastify options (escape hatch for advanced usage)
+     * Allows full control over Fastify server configuration.
+     *
+     * Note: The `logger` option should be set via the top-level `logger`
+     * config, not here. TypeScript will prevent setting it in `fastify`.
+     *
+     * @default {}
+     */
+    fastify?: VeloxFastifyOptions;
+}
+/**
+ * Deeply readonly version of VeloxAppConfig after merging with defaults
+ *
+ * Configuration is frozen after initialization to prevent accidental mutation.
+ */
+export type FrozenVeloxAppConfig = Readonly<{
+    port: ValidPort;
+    host: ValidHost;
+    logger: boolean | FastifyLoggerOptions;
+    fastify: VeloxFastifyOptions;
+}>;
+/**
+ * Default configuration values
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly port: 3000;
+    readonly host: "0.0.0.0";
+    readonly logger: boolean;
+};
+/**
+ * Type guard that validates and narrows port to ValidPort
+ *
+ * @param port - Port number to validate
+ * @returns true if port is valid (0-65535), narrowing to ValidPort
+ *
+ * @example
+ * ```typescript
+ * const port = 3000;
+ * if (isValidPort(port)) {
+ *   // port is narrowed to ValidPort
+ *   startServer(port);
+ * }
+ * ```
+ */
+export declare function isValidPort(port: number): port is ValidPort;
+/**
+ * Type guard that validates and narrows host to ValidHost
+ *
+ * @param host - Host string to validate
+ * @returns true if host is valid (non-empty string), narrowing to ValidHost
+ */
+export declare function isValidHost(host: string): host is ValidHost;
+/**
+ * Merges user configuration with defaults
+ *
+ * @param userConfig - User-provided configuration
+ * @returns Complete configuration with defaults applied (not yet validated)
+ *
+ * @example
+ * ```typescript
+ * const config = mergeConfig({ port: 4000 });
+ * // Result: { port: 4000, host: '0.0.0.0', logger: true, fastify: {} }
+ * ```
+ */
+export declare function mergeConfig(userConfig?: VeloxAppConfig): Required<VeloxAppConfig>;
+/**
+ * Validates configuration and returns a frozen, type-safe config object
+ *
+ * The returned config has branded types that guarantee validation has occurred.
+ * The object is frozen at runtime to prevent accidental mutation.
+ *
+ * @param config - Configuration to validate
+ * @returns Frozen configuration with branded types
+ * @throws {Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeConfig({ port: 3000 });
+ * const validated = validateConfig(merged);
+ * // validated.port is ValidPort (branded type)
+ * // validated is frozen (immutable at runtime)
+ * ```
+ */
+export declare function validateConfig(config: Required<VeloxAppConfig>): FrozenVeloxAppConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/utils/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAM1E;;GAEG;AACH,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,OAAO,cAAc,CAAA;CAAE,CAAC;AAEtF;;GAEG;AACH,OAAO,CAAC,MAAM,cAAc,EAAE,OAAO,MAAM,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,OAAO,cAAc,CAAA;CAAE,CAAC;AAMtF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;AAMvE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;IAExC;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,OAAO,GAAG,oBAAoB,CAAC;IACvC,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAMX;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,SAAS,CAE3D;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,UAAU,GAAE,cAAmB,GAAG,QAAQ,CAAC,cAAc,CAAC,CAOrF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,GAAG,oBAAoB,CAgBrF"}

package/dist/utils/config.js

@@ -0,0 +1,99 @@
+/**
+ * Configuration types and utilities for VeloxTS application
+ * @module utils/config
+ */
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG = {
+    port: 3000,
+    host: '0.0.0.0',
+    logger: process.env.NODE_ENV !== 'production',
+};
+// ============================================================================
+// Type Guards (Branded Type Validators)
+// ============================================================================
+/**
+ * Type guard that validates and narrows port to ValidPort
+ *
+ * @param port - Port number to validate
+ * @returns true if port is valid (0-65535), narrowing to ValidPort
+ *
+ * @example
+ * ```typescript
+ * const port = 3000;
+ * if (isValidPort(port)) {
+ *   // port is narrowed to ValidPort
+ *   startServer(port);
+ * }
+ * ```
+ */
+export function isValidPort(port) {
+    return Number.isInteger(port) && port >= 0 && port <= 65535;
+}
+/**
+ * Type guard that validates and narrows host to ValidHost
+ *
+ * @param host - Host string to validate
+ * @returns true if host is valid (non-empty string), narrowing to ValidHost
+ */
+export function isValidHost(host) {
+    return typeof host === 'string' && host.length > 0;
+}
+// ============================================================================
+// Configuration Functions
+// ============================================================================
+/**
+ * Merges user configuration with defaults
+ *
+ * @param userConfig - User-provided configuration
+ * @returns Complete configuration with defaults applied (not yet validated)
+ *
+ * @example
+ * ```typescript
+ * const config = mergeConfig({ port: 4000 });
+ * // Result: { port: 4000, host: '0.0.0.0', logger: true, fastify: {} }
+ * ```
+ */
+export function mergeConfig(userConfig = {}) {
+    return {
+        port: userConfig.port ?? DEFAULT_CONFIG.port,
+        host: userConfig.host ?? DEFAULT_CONFIG.host,
+        logger: userConfig.logger ?? DEFAULT_CONFIG.logger,
+        fastify: userConfig.fastify ?? {},
+    };
+}
+/**
+ * Validates configuration and returns a frozen, type-safe config object
+ *
+ * The returned config has branded types that guarantee validation has occurred.
+ * The object is frozen at runtime to prevent accidental mutation.
+ *
+ * @param config - Configuration to validate
+ * @returns Frozen configuration with branded types
+ * @throws {Error} If configuration is invalid
+ *
+ * @example
+ * ```typescript
+ * const merged = mergeConfig({ port: 3000 });
+ * const validated = validateConfig(merged);
+ * // validated.port is ValidPort (branded type)
+ * // validated is frozen (immutable at runtime)
+ * ```
+ */
+export function validateConfig(config) {
+    if (!isValidPort(config.port)) {
+        throw new Error(`Invalid port number: ${config.port}. Must be between 0 and 65535.`);
+    }
+    if (!isValidHost(config.host)) {
+        throw new Error('Host must be a non-empty string.');
+    }
+    // Return frozen config with branded types
+    return Object.freeze({
+        port: config.port, // Already narrowed to ValidPort by isValidPort
+        host: config.host, // Already narrowed to ValidHost by isValidHost
+        logger: config.logger,
+        fastify: config.fastify,
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/utils/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/utils/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqIH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;CACrC,CAAC;AAEX,+EAA+E;AAC/E,wCAAwC;AACxC,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,aAA6B,EAAE;IACzD,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,cAAc,CAAC,IAAI;QAC5C,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,cAAc,CAAC,IAAI;QAC5C,MAAM,EAAE,UAAU,CAAC,MAAM,IAAI,cAAc,CAAC,MAAM;QAClD,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,EAAE;KAClC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAgC;IAC7D,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,CAAC,IAAI,gCAAgC,CAAC,CAAC;IACvF,CAAC;IAED,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IAED,0CAA0C;IAC1C,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,+CAA+C;QAClE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,+CAA+C;QAClE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/lifecycle.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Lifecycle management utilities for VeloxTS application
+ * Handles graceful shutdown and cleanup
+ * @module utils/lifecycle
+ */
+import type { ShutdownHandler } from '../types.js';
+/**
+ * Manages graceful shutdown for the VeloxTS application
+ *
+ * Coordinates cleanup of resources when the application is stopped,
+ * either programmatically or via system signals (SIGINT, SIGTERM)
+ */
+export declare class LifecycleManager {
+    private readonly shutdownHandlers;
+    private readonly signalHandlers;
+    private isShuttingDown;
+    private static readonly MAX_SHUTDOWN_HANDLERS;
+    /**
+     * Adds a shutdown handler to be called during graceful shutdown
+     *
+     * Handlers are called in insertion order. Duplicate handlers are
+     * automatically prevented.
+     *
+     * @param handler - Async function to call during shutdown
+     * @throws {Error} If maximum number of handlers is exceeded
+     *
+     * @example
+     * ```typescript
+     * lifecycleManager.addShutdownHandler(async () => {
+     *   await database.disconnect();
+     *   console.log('Database connection closed');
+     * });
+     * ```
+     */
+    addShutdownHandler(handler: ShutdownHandler): void;
+    /**
+     * Removes a shutdown handler
+     *
+     * @param handler - Handler to remove
+     * @returns true if handler was removed, false if not found
+     */
+    removeShutdownHandler(handler: ShutdownHandler): boolean;
+    /**
+     * Executes all shutdown handlers in sequence
+     *
+     * Called automatically during server stop() or when receiving
+     * termination signals (SIGINT, SIGTERM)
+     *
+     * @internal
+     */
+    executeShutdownHandlers(): Promise<void>;
+    /**
+     * Sets up process signal handlers for graceful shutdown
+     *
+     * Listens for SIGINT (Ctrl+C) and SIGTERM (kill command) and
+     * executes shutdown sequence before exiting
+     *
+     * @param onShutdown - Callback to execute during shutdown
+     *
+     * @internal
+     */
+    setupSignalHandlers(onShutdown: () => Promise<void>): void;
+    /**
+     * Removes all signal handlers
+     *
+     * Should be called during stop() to prevent memory leaks in test environments
+     *
+     * @internal
+     */
+    cleanupSignalHandlers(): void;
+    /**
+     * Clears all registered shutdown handlers
+     *
+     * @internal
+     */
+    clearHandlers(): void;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/utils/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/utils/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmC;IACpE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8C;IAC7E,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IAErD;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAalD;;;;;OAKG;IACH,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO;IAIxD;;;;;;;OAOG;IACG,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB9C;;;;;;;;;OASG;IACH,mBAAmB,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAuB1D;;;;;;OAMG;IACH,qBAAqB,IAAI,IAAI;IAO7B;;;;OAIG;IACH,aAAa,IAAI,IAAI;CAGtB"}

package/dist/utils/lifecycle.js

@@ -0,0 +1,128 @@
+/**
+ * Lifecycle management utilities for VeloxTS application
+ * Handles graceful shutdown and cleanup
+ * @module utils/lifecycle
+ */
+/**
+ * Manages graceful shutdown for the VeloxTS application
+ *
+ * Coordinates cleanup of resources when the application is stopped,
+ * either programmatically or via system signals (SIGINT, SIGTERM)
+ */
+export class LifecycleManager {
+    shutdownHandlers = new Set();
+    signalHandlers = new Map();
+    isShuttingDown = false;
+    static MAX_SHUTDOWN_HANDLERS = 1000;
+    /**
+     * Adds a shutdown handler to be called during graceful shutdown
+     *
+     * Handlers are called in insertion order. Duplicate handlers are
+     * automatically prevented.
+     *
+     * @param handler - Async function to call during shutdown
+     * @throws {Error} If maximum number of handlers is exceeded
+     *
+     * @example
+     * ```typescript
+     * lifecycleManager.addShutdownHandler(async () => {
+     *   await database.disconnect();
+     *   console.log('Database connection closed');
+     * });
+     * ```
+     */
+    addShutdownHandler(handler) {
+        // Prevent memory leaks from unbounded growth
+        if (this.shutdownHandlers.size >= LifecycleManager.MAX_SHUTDOWN_HANDLERS) {
+            throw new Error(`Maximum number of shutdown handlers (${LifecycleManager.MAX_SHUTDOWN_HANDLERS}) exceeded. ` +
+                'This may indicate a memory leak.');
+        }
+        // Set automatically prevents duplicates
+        this.shutdownHandlers.add(handler);
+    }
+    /**
+     * Removes a shutdown handler
+     *
+     * @param handler - Handler to remove
+     * @returns true if handler was removed, false if not found
+     */
+    removeShutdownHandler(handler) {
+        return this.shutdownHandlers.delete(handler);
+    }
+    /**
+     * Executes all shutdown handlers in sequence
+     *
+     * Called automatically during server stop() or when receiving
+     * termination signals (SIGINT, SIGTERM)
+     *
+     * @internal
+     */
+    async executeShutdownHandlers() {
+        if (this.isShuttingDown) {
+            return; // Already shutting down, avoid duplicate execution
+        }
+        this.isShuttingDown = true;
+        for (const handler of this.shutdownHandlers) {
+            try {
+                await handler();
+            }
+            catch (error) {
+                // Log error but continue with other handlers
+                console.error('Error during shutdown handler execution:', error);
+            }
+        }
+        this.isShuttingDown = false;
+    }
+    /**
+     * Sets up process signal handlers for graceful shutdown
+     *
+     * Listens for SIGINT (Ctrl+C) and SIGTERM (kill command) and
+     * executes shutdown sequence before exiting
+     *
+     * @param onShutdown - Callback to execute during shutdown
+     *
+     * @internal
+     */
+    setupSignalHandlers(onShutdown) {
+        const signals = ['SIGINT', 'SIGTERM'];
+        signals.forEach((signal) => {
+            const handler = async () => {
+                console.log(`\nReceived ${signal}, initiating graceful shutdown...`);
+                try {
+                    await onShutdown();
+                    console.log('Graceful shutdown completed');
+                    process.exit(0);
+                }
+                catch (error) {
+                    console.error('Error during graceful shutdown:', error);
+                    process.exit(1);
+                }
+            };
+            // Store handler reference so it can be removed later
+            this.signalHandlers.set(signal, handler);
+            process.once(signal, handler);
+        });
+    }
+    /**
+     * Removes all signal handlers
+     *
+     * Should be called during stop() to prevent memory leaks in test environments
+     *
+     * @internal
+     */
+    cleanupSignalHandlers() {
+        for (const [signal, handler] of this.signalHandlers) {
+            process.removeListener(signal, handler);
+        }
+        this.signalHandlers.clear();
+    }
+    /**
+     * Clears all registered shutdown handlers
+     *
+     * @internal
+     */
+    clearHandlers() {
+        this.shutdownHandlers.clear();
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/utils/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/utils/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACV,gBAAgB,GAAyB,IAAI,GAAG,EAAE,CAAC;IACnD,cAAc,GAAoC,IAAI,GAAG,EAAE,CAAC;IACrE,cAAc,GAAG,KAAK,CAAC;IACvB,MAAM,CAAU,qBAAqB,GAAG,IAAI,CAAC;IAErD;;;;;;;;;;;;;;;;OAgBG;IACH,kBAAkB,CAAC,OAAwB;QACzC,6CAA6C;QAC7C,IAAI,IAAI,CAAC,gBAAgB,CAAC,IAAI,IAAI,gBAAgB,CAAC,qBAAqB,EAAE,CAAC;YACzE,MAAM,IAAI,KAAK,CACb,wCAAwC,gBAAgB,CAAC,qBAAqB,cAAc;gBAC1F,kCAAkC,CACrC,CAAC;QACJ,CAAC;QAED,wCAAwC;QACxC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,qBAAqB,CAAC,OAAwB;QAC5C,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,uBAAuB;QAC3B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,CAAC,mDAAmD;QAC7D,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAE3B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC5C,IAAI,CAAC;gBACH,MAAM,OAAO,EAAE,CAAC;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,6CAA6C;gBAC7C,OAAO,CAAC,KAAK,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC;YACnE,CAAC;QACH,CAAC;QAED,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;IAC9B,CAAC;IAED;;;;;;;;;OASG;IACH,mBAAmB,CAAC,UAA+B;QACjD,MAAM,OAAO,GAAqB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAExD,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE;YACzB,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;gBACzB,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,mCAAmC,CAAC,CAAC;gBAErE,IAAI,CAAC;oBACH,MAAM,UAAU,EAAE,CAAC;oBACnB,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;oBAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;oBACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC,CAAC;YAEF,qDAAqD;YACrD,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACzC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,qBAAqB;QACnB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACpD,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,aAAa;QACX,IAAI,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IAChC,CAAC"}