@veloxts/core 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @veloxts/core
 
+## 0.7.2
+
+### Patch Changes
+
+- chore(auth,core,create,cli,client,orm,mcp,router,validation,web): simplify code for clarity and maintainability
+
+## 0.7.1
+
+### Patch Changes
+
+- security audit, bumps dependency packages
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/app.d.ts

@@ -79,20 +79,12 @@ export declare class VeloxApp {
      */
     get address(): string | null;
     /**
-     * Async initialization (called by factory function)
-     *
-     * @internal - This method is public for factory access but should not be called directly.
-     * Use createVeloxApp() instead.
-     */
-    initialize(): Promise<void>;
-    /**
-     * Sets up request context decorator
-     *
-     * Adds `request.context` property to all requests via onRequest hook
+     * Async initialization hook for factory function.
+     * Empty because Fastify's ready() must be called in start() after plugin registration.
      *
      * @internal
      */
-    private _setupContext;
+    initialize(): Promise<void>;
     /**
      * Sets up global error handling
      *
@@ -101,12 +93,6 @@ export declare class VeloxApp {
      * @internal
      */
     private _setupErrorHandling;
-    /**
-     * Sets up graceful shutdown handlers for process signals
-     *
-     * @internal
-     */
-    private _setupGracefulShutdown;
     /**
      * Registers a plugin with the application
      *
@@ -293,5 +279,6 @@ export declare function veloxApp(config?: VeloxAppConfig): Promise<VeloxApp>;
  *
  * const app = await velox({ port: 3030 });
  * ```
+ * @deprecated Use veloxApp() instead.
  */
 export declare const velox: typeof veloxApp;

package/dist/app.js

@@ -13,6 +13,8 @@ import { registerStatic } from './plugins/static.js';
 import { printBanner } from './utils/banner.js';
 import { mergeConfig, validateConfig } from './utils/config.js';
 import { LifecycleManager } from './utils/lifecycle.js';
+import { createLogger } from './utils/logger.js';
+const log = createLogger('core');
 /**
  * Main VeloxTS application instance
  *
@@ -46,25 +48,18 @@ export class VeloxApp {
      * @internal
      */
     constructor(config) {
-        // Merge user config with defaults and validate
         const merged = mergeConfig(config);
-        // Validate and freeze configuration
         this._config = validateConfig(merged);
-        // Create Fastify instance
-        const fastifyOptions = {
+        this._server = fastify({
             logger: this._config.logger,
             ...this._config.fastify,
-        };
-        this._server = fastify(fastifyOptions);
-        // Initialize lifecycle manager
+        });
         this._lifecycle = new LifecycleManager();
-        // Set up context decorator
-        this._setupContext();
-        // Set up error handling
+        setupContextHook(this._server);
         this._setupErrorHandling();
-        // Set up graceful shutdown
-        this._setupGracefulShutdown();
-        // Register request logger if enabled via environment
+        this._lifecycle.setupSignalHandlers(async () => {
+            await this.stop();
+        });
         if (process.env.VELOX_REQUEST_LOGGING === 'true') {
             this._server.register(requestLogger);
         }
@@ -108,24 +103,13 @@ export class VeloxApp {
         return this._address;
     }
     /**
-     * Async initialization (called by factory function)
-     *
-     * @internal - This method is public for factory access but should not be called directly.
-     * Use createVeloxApp() instead.
-     */
-    async initialize() {
-        // Keep empty - ready() must be called in start() after plugins are registered
-        // This is a Fastify constraint: plugins must be registered before ready()
-    }
-    /**
-     * Sets up request context decorator
-     *
-     * Adds `request.context` property to all requests via onRequest hook
+     * Async initialization hook for factory function.
+     * Empty because Fastify's ready() must be called in start() after plugin registration.
      *
      * @internal
      */
-    _setupContext() {
-        setupContextHook(this._server);
+    async initialize() {
+        // Intentionally empty - ready() is called in start()
     }
     /**
      * Sets up global error handling
@@ -137,8 +121,7 @@ export class VeloxApp {
     _setupErrorHandling() {
         this._server.setErrorHandler(async (error, request, reply) => {
             try {
-                // Handle ZodError (validation errors) - return 400
-                if (error instanceof Error && error.name === 'ZodError' && 'issues' in error) {
+                if (error.name === 'ZodError' && 'issues' in error) {
                     const zodError = error;
                     return reply.status(400).send({
                         error: 'ValidationError',
@@ -150,9 +133,7 @@ export class VeloxApp {
                         })),
                     });
                 }
-                // Handle Prisma unique constraint errors - return 409 Conflict
-                if (error instanceof Error &&
-                    error.name === 'PrismaClientKnownRequestError' &&
+                if (error.name === 'PrismaClientKnownRequestError' &&
                     'code' in error &&
                     error.code === 'P2002') {
                     const prismaError = error;
@@ -163,22 +144,21 @@ export class VeloxApp {
                         statusCode: 409,
                     });
                 }
-                // Only log server errors (5xx), not client errors (4xx)
-                const statusCode = isVeloxError(error)
-                    ? error.statusCode
-                    : typeof error === 'object' && error !== null && 'statusCode' in error
-                        ? error.statusCode
-                        : 500;
+                let statusCode = 500;
+                if (isVeloxError(error)) {
+                    statusCode = error.statusCode;
+                }
+                else if (typeof error === 'object' && error !== null && 'statusCode' in error) {
+                    statusCode = error.statusCode;
+                }
                 if (statusCode >= 500) {
                     request.log.error(error);
                 }
-                // Handle VeloxError instances (fast path - most common case)
                 if (isVeloxError(error)) {
                     return reply.status(error.statusCode).send(error.toJSON());
                 }
-                // Handle other errors
-                const message = error instanceof Error ? error.message : 'Internal Server Error';
-                const name = error instanceof Error ? error.name : 'Error';
+                const message = error.message ?? 'Internal Server Error';
+                const name = error.name ?? 'Error';
                 return reply.status(statusCode).send({
                     error: name,
                     message,
@@ -186,8 +166,7 @@ export class VeloxApp {
                 });
             }
             catch (handlerError) {
-                // Last resort error handling - prevents unhandled rejections
-                console.error('Critical error in error handler:', handlerError);
+                log.error('Critical error in error handler:', handlerError);
                 if (!reply.sent) {
                     return reply.status(500).send({
                         error: 'InternalServerError',
@@ -198,16 +177,6 @@ export class VeloxApp {
             }
         });
     }
-    /**
-     * Sets up graceful shutdown handlers for process signals
-     *
-     * @internal
-     */
-    _setupGracefulShutdown() {
-        this._lifecycle.setupSignalHandlers(async () => {
-            await this.stop();
-        });
-    }
     /**
      * Registers a plugin with the application
      *
@@ -237,17 +206,13 @@ export class VeloxApp {
      * ```
      */
     async register(plugin, options) {
-        // Handle VeloxPlugin objects (with name, version, register)
         if (isVeloxPlugin(plugin)) {
-            // Validate plugin metadata
             validatePluginMetadata(plugin);
-            // Wrap plugin with fastify-plugin for proper encapsulation
             const wrappedPlugin = fp(plugin.register, {
                 name: plugin.name,
                 dependencies: plugin.dependencies,
                 fastify: '5.x',
             });
-            // Register with Fastify
             try {
                 await this._server.register(wrappedPlugin, options ?? {});
             }
@@ -256,7 +221,6 @@ export class VeloxApp {
             }
             return;
         }
-        // Handle FastifyPluginAsync functions (standard Fastify plugins)
         if (isFastifyPlugin(plugin)) {
             try {
                 await this._server.register(plugin, options ?? {});
@@ -266,7 +230,6 @@ export class VeloxApp {
             }
             return;
         }
-        // Invalid plugin type
         throw new VeloxError('Invalid plugin: must be a VeloxPlugin object or FastifyPluginAsync function', 500, 'INVALID_PLUGIN_TYPE');
     }
     /**
@@ -354,16 +317,13 @@ export class VeloxApp {
         }
         const startTime = performance.now();
         try {
-            // Ensure Fastify is ready before listening (must be after plugin registration)
             await this._server.ready();
-            // Start listening
             const address = await this._server.listen({
                 port: this._config.port,
                 host: this._config.host,
             });
             this._isRunning = true;
             this._address = address;
-            // Print startup banner unless silent
             if (!options.silent) {
                 printBanner(this._server, {
                     address,
@@ -397,11 +357,8 @@ export class VeloxApp {
             throw new VeloxError('Server is not running', 500, 'SERVER_NOT_RUNNING');
         }
         try {
-            // Execute shutdown handlers
             await this._lifecycle.executeShutdownHandlers();
-            // Clean up signal handlers to prevent memory leaks in tests
             this._lifecycle.cleanupSignalHandlers();
-            // Close server
             await this._server.close();
             this._isRunning = false;
             this._address = null;
@@ -483,5 +440,6 @@ export async function veloxApp(config = {}) {
  *
  * const app = await velox({ port: 3030 });
  * ```
+ * @deprecated Use veloxApp() instead.
  */
 export const velox = veloxApp;

package/dist/context.js

@@ -38,17 +38,13 @@ export function createContext(request, reply) {
  * ```
  */
 export function isContext(value) {
-    // Early return for non-objects
     if (typeof value !== 'object' || value === null) {
         return false;
     }
-    // Check properties exist using 'in' operator
     if (!('request' in value) || !('reply' in value)) {
         return false;
     }
-    // After 'in' checks, safely access properties
     const ctx = value;
-    // Verify request and reply are non-null objects
     return (typeof ctx.request === 'object' &&
         ctx.request !== null &&
         typeof ctx.reply === 'object' &&
@@ -65,12 +61,7 @@ export function isContext(value) {
  * @internal
  */
 export function setupContextHook(server) {
-    // Create context for each request via direct assignment
-    // TypeScript's declaration merging provides type safety
     server.addHook('onRequest', async (request, reply) => {
-        // Direct assignment is ~100-400ns faster than Object.defineProperty
-        // We use a mutable type assertion here because this is the framework's
-        // initialization code - the readonly constraint is for user code safety
         request.context = createContext(request, reply);
     });
 }

package/dist/errors/fail.d.ts

@@ -33,6 +33,17 @@ export type ErrorCode = keyof typeof ERROR_CATALOG;
  * Variables for template interpolation
  */
 export type InterpolationVars = Record<string, string | number | boolean | undefined>;
+/**
+ * JSON representation of a VeloxFailure for API responses
+ */
+interface VeloxFailureJson {
+    error: string;
+    message: string;
+    statusCode: number;
+    code: string;
+    fix?: string;
+    docs?: string;
+}
 /**
  * Fluent error builder that provides catalog-driven errors
  * with optional customization.
@@ -111,14 +122,7 @@ export declare class VeloxFailure extends Error {
     /**
      * Convert to JSON for API responses
      */
-    toJSON(): {
-        error: string;
-        message: string;
-        statusCode: number;
-        code: string;
-        fix?: string;
-        docs?: string;
-    };
+    toJSON(): VeloxFailureJson;
     /**
      * Interpolate variables into a template string
      */
@@ -161,3 +165,4 @@ export declare function fail(code: string, vars?: InterpolationVars): VeloxFailu
  * @returns true if error is a VeloxFailure
  */
 export declare function isVeloxFailure(error: unknown): error is VeloxFailure;
+export {};

package/dist/errors/fail.js

@@ -54,7 +54,6 @@ export class VeloxFailure extends Error {
         this.code = code;
         this.statusCode = entry.statusCode;
         this.entry = entry;
-        // Maintains proper stack trace
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, VeloxFailure);
         }
@@ -142,11 +141,9 @@ export class VeloxFailure extends Error {
             statusCode: this.statusCode,
             code: this.code,
         };
-        // Include fix in development
         if (process.env.NODE_ENV !== 'production' && this.suggestion) {
             json.fix = this.suggestion;
         }
-        // Always include docs URL
         if (this.docsUrl) {
             json.docs = this.docsUrl;
         }

package/dist/errors/formatter.js

@@ -6,7 +6,9 @@
  *
  * @module errors/formatter
  */
+import { createLogger } from '../utils/logger.js';
 import { getErrorEntry } from './catalog.js';
+const log = createLogger('core');
 // ============================================================================
 // ANSI Color Codes (for terminal output)
 // ============================================================================
@@ -260,15 +262,12 @@ export function formatErrorForApi(error, catalogCode) {
         statusCode: error.statusCode ?? entry?.statusCode ?? 500,
         code: catalogCode ?? error.code,
     };
-    // Include field errors for validation
     if (error.fields) {
         response.fields = error.fields;
     }
-    // Include fix suggestion in development
     if (process.env.NODE_ENV !== 'production' && entry?.fix) {
         response.fix = entry.fix.suggestion;
     }
-    // Include docs link
     if (entry?.docsUrl) {
         response.docs = entry.docsUrl;
     }
@@ -298,7 +297,7 @@ export function formatErrorOneLine(error, catalogCode) {
  * @param catalogCode - Optional catalog error code
  */
 export function logError(error, catalogCode) {
-    console.error(formatError(error, catalogCode));
+    log.error(formatError(error, catalogCode));
 }
 /**
  * Log a warning with pretty formatting
@@ -314,7 +313,7 @@ export function logWarning(message, suggestion) {
         lines.push(`   ${color('→', 'gray')} ${suggestion}`);
     }
     lines.push('');
-    console.warn(lines.join('\n'));
+    log.warn(lines.join('\n'));
 }
 /**
  * Log a deprecation warning

package/dist/errors/index.js

@@ -9,9 +9,6 @@
  *
  * @module errors
  */
-// Re-export catalog
 export { ERROR_CATALOG, ERROR_DOMAINS, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, } from './catalog.js';
-// Re-export fail() - the elegant error creation API
 export { fail, isVeloxFailure, VeloxFailure, } from './fail.js';
-// Re-export formatter
 export { extractErrorLocation, formatError, formatErrorForApi, formatErrorOneLine, logDeprecation, logError, logWarning, } from './formatter.js';

package/dist/errors.js

@@ -3,10 +3,10 @@
  * Provides base error classes with HTTP status codes and discriminated unions
  * @module errors
  */
-// Import catalog for use in error classes
 import { ERROR_CATALOG } from './errors/catalog.js';
 import { formatError as _formatError } from './errors/formatter.js';
-// Re-export the enhanced error catalog, formatter, and fail()
+import { createLogger } from './utils/logger.js';
+const log = createLogger('core');
 export { ERROR_CATALOG, ERROR_DOMAINS, extractErrorLocation, fail, formatError, formatErrorForApi, formatErrorOneLine, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, isVeloxFailure, logDeprecation, logError, logWarning, VeloxFailure, } from './errors/index.js';
 /**
  * Type guard for validation error responses
@@ -79,7 +79,6 @@ export class VeloxError extends Error {
         this.name = 'VeloxError';
         this.statusCode = statusCode;
         this.code = code;
-        // Look up catalog entry for enhanced error info
         if (code != null && String(code).startsWith('VELOX-')) {
             const entry = ERROR_CATALOG[code];
             if (entry) {
@@ -87,7 +86,6 @@ export class VeloxError extends Error {
                 this.docsUrl = entry.docsUrl;
             }
         }
-        // Maintains proper stack trace for where error was thrown (V8 only)
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, VeloxError);
         }
@@ -104,11 +102,9 @@ export class VeloxError extends Error {
             statusCode: this.statusCode,
             code: this.code,
         };
-        // Include fix suggestion in development only
         if (process.env.NODE_ENV !== 'production' && this.fix) {
             response.fix = this.fix;
         }
-        // Always include docs URL if available
         if (this.docsUrl) {
             response.docs = this.docsUrl;
         }
@@ -126,7 +122,7 @@ export class VeloxError extends Error {
      * Log this error with pretty formatting
      */
     log() {
-        console.error(this.format());
+        log.error(this.format());
     }
 }
 /**
@@ -296,7 +292,7 @@ export class NotFoundError extends VeloxError {
  * ```
  */
 export function isVeloxError(error) {
-    return error != null && error instanceof VeloxError;
+    return error instanceof VeloxError;
 }
 /**
  * Type guard to check if an error is a ValidationError

package/dist/index.d.ts

@@ -32,3 +32,5 @@ export type { AuthContextExtension, CombineContexts, ContextExtension, CoreConte
 export type { CacheControl, StaticOptions } from './plugins/static.js';
 export { registerStatic } from './plugins/static.js';
 export { requestLogger } from './plugins/request-logger.js';
+export type { Logger, LogLevel } from './utils/logger.js';
+export { createLogger } from './utils/logger.js';

package/dist/index.js

@@ -15,19 +15,13 @@
  * @module @veloxts/core
  */
 import { createRequire } from 'node:module';
-// Read version from package.json dynamically
 const require = createRequire(import.meta.url);
 const packageJson = require('../package.json');
 /** VeloxTS framework version */
 export const VELOX_VERSION = packageJson.version ?? '0.0.0-unknown';
 export { VeloxApp, velox, veloxApp } from './app.js';
 export { createContext, isContext, setupContextHook, setupTestContext } from './context.js';
-export { assertNever, ConfigurationError, 
-// Elegant error creation API
-fail, isConfigurationError, isNotFoundError, isNotFoundErrorResponse, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, 
-// Developer experience utilities
-logDeprecation, logWarning, NotFoundError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
-// Plugin system
+export { assertNever, ConfigurationError, fail, isConfigurationError, isNotFoundError, isNotFoundErrorResponse, isValidationError, isValidationErrorResponse, isVeloxError, isVeloxFailure, logDeprecation, logWarning, NotFoundError, ValidationError, VeloxError, VeloxFailure, } from './errors.js';
 export { definePlugin, isFastifyPlugin, isVeloxPlugin, validatePluginMetadata } from './plugin.js';
 export { isValidHost, isValidPort } from './utils/config.js';
 export { registerStatic } from './plugins/static.js';
@@ -35,3 +29,4 @@ export { registerStatic } from './plugins/static.js';
 // Request Logging (Development)
 // ============================================================================
 export { requestLogger } from './plugins/request-logger.js';
+export { createLogger } from './utils/logger.js';

package/dist/plugin.js

@@ -78,7 +78,6 @@ export function validatePluginMetadata(plugin) {
     if (!plugin.register || typeof plugin.register !== 'function') {
         throw new VeloxError(`Plugin "${plugin.name}" must have a register function`, 500, 'INVALID_PLUGIN_METADATA');
     }
-    // Validate dependencies array if provided
     if (plugin.dependencies !== undefined) {
         if (!Array.isArray(plugin.dependencies)) {
             throw new VeloxError(`Plugin "${plugin.name}" dependencies must be an array`, 500, 'INVALID_PLUGIN_METADATA');
@@ -110,7 +109,6 @@ export function isVeloxPlugin(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
     }
-    // Use 'in' operator for safe property access without type assertions
     return ('name' in value &&
         'version' in value &&
         'register' in value &&

package/dist/plugins/request-logger.js

@@ -93,17 +93,13 @@ function formatDuration(ms) {
  * @param server - Fastify instance
  */
 async function requestLoggerPlugin(server) {
-    // Skip if request logging not enabled via environment
     if (process.env.VELOX_REQUEST_LOGGING !== 'true') {
         return;
     }
-    // Track request start time
     server.addHook('onRequest', async (request) => {
         request._veloxStartTime = performance.now();
     });
-    // Log on response with timing
     server.addHook('onResponse', async (request, reply) => {
-        // Wrap in try-catch to ensure logging never breaks request handling
         try {
             const startTime = request._veloxStartTime;
             const duration = startTime ? performance.now() - startTime : 0;
@@ -115,7 +111,7 @@ async function requestLoggerPlugin(server) {
             console.log(`${COLORS.dim}${timestamp}${COLORS.reset}  ${color}${method}${COLORS.reset} ${url} ${color}${status}${COLORS.reset} ${COLORS.dim}${formatDuration(duration)}${COLORS.reset}`);
         }
         catch {
-            // Silently fail - logging should never affect application behavior
+            // Logging failures must not affect request handling
         }
     });
 }

package/dist/plugins/static.js

@@ -83,9 +83,7 @@ function buildCacheControl(options) {
  */
 export async function registerStatic(server, path, options = {}) {
     const { spa = false, prefix = '/', cache = {}, exclude = [], index = 'index.html' } = options;
-    // Resolve to absolute path
     const absoluteRoot = resolve(process.cwd(), path);
-    // Dynamically import @fastify/static (optional peer dependency)
     let fastifyStatic;
     try {
         const module = await import('@fastify/static');
@@ -94,9 +92,7 @@ export async function registerStatic(server, path, options = {}) {
     catch {
         throw new Error('To serve static files, please install @fastify/static:\n\n  pnpm add @fastify/static');
     }
-    // Build cache control header
     const cacheControl = buildCacheControl(cache);
-    // Register static plugin
     await server.register(fastifyStatic, {
         root: absoluteRoot,
         prefix,
@@ -106,10 +102,8 @@ export async function registerStatic(server, path, options = {}) {
             res.setHeader('Cache-Control', cacheControl);
         },
     });
-    // SPA fallback: serve index.html for non-file routes
     if (spa) {
         server.setNotFoundHandler(async (request, reply) => {
-            // Skip excluded paths (API routes, etc.)
             for (const excludePath of exclude) {
                 if (request.url.startsWith(excludePath)) {
                     return reply.status(404).send({
@@ -119,7 +113,6 @@ export async function registerStatic(server, path, options = {}) {
                     });
                 }
             }
-            // Skip requests for files (have extensions)
             if (/\.\w+$/.test(request.url)) {
                 return reply.status(404).send({
                     error: 'NotFound',
@@ -127,7 +120,6 @@ export async function registerStatic(server, path, options = {}) {
                     statusCode: 404,
                 });
             }
-            // Serve index.html for SPA routes
             return reply.sendFile(index, absoluteRoot);
         });
     }

package/dist/utils/banner.js

@@ -17,11 +17,9 @@ export function printBanner(server, options) {
     const { address, env, startTime } = options;
     const elapsed = Math.round(performance.now() - startTime);
     if (env === 'production') {
-        // Production: single line, minimal, machine-parseable
         console.log(`  VeloxTS v${VELOX_VERSION} | ${env} | ${address}`);
         return;
     }
-    // Development: detailed banner with route information
     const routes = collectRoutes(server);
     console.log('');
     console.log(`  ${pc.bold('VeloxTS')} v${VELOX_VERSION}`);
@@ -62,11 +60,7 @@ function formatMethod(method) {
  */
 function collectRoutes(server) {
     const routes = [];
-    // Fastify exposes routes via printRoutes or we can iterate
-    // Using the internal routes map after ready()
     const routesList = server.printRoutes({ commonPrefix: false });
-    // Parse the route tree output
-    // Format: "└── /api (GET, HEAD)\n    └── /users (GET, POST, HEAD)"
     const lines = routesList.split('\n');
     for (const line of lines) {
         const match = line.match(/([/][^\s(]*)\s*\(([^)]+)\)/);

package/dist/utils/config.js

@@ -38,7 +38,7 @@ export function isValidPort(port) {
  * @returns true if host is valid (non-empty string), narrowing to ValidHost
  */
 export function isValidHost(host) {
-    return typeof host === 'string' && host.length > 0;
+    return host.length > 0;
 }
 // ============================================================================
 // Configuration Functions
@@ -88,10 +88,9 @@ export function validateConfig(config) {
     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
+        port: config.port,
+        host: config.host,
         logger: config.logger,
         fastify: config.fastify,
     });

package/dist/utils/lifecycle.js

@@ -3,6 +3,8 @@
  * Handles graceful shutdown and cleanup
  * @module utils/lifecycle
  */
+import { createLogger } from './logger.js';
+const log = createLogger('core');
 /**
  * Manages graceful shutdown for the VeloxTS application
  *
@@ -32,12 +34,10 @@ export class LifecycleManager {
      * ```
      */
     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);
     }
     /**
@@ -68,7 +68,7 @@ export class LifecycleManager {
             }
             catch (error) {
                 // Log error but continue with other handlers
-                console.error('Error during shutdown handler execution:', error);
+                log.error('Error during shutdown handler execution:', error);
             }
         }
         this.isShuttingDown = false;
@@ -85,23 +85,22 @@ export class LifecycleManager {
      */
     setupSignalHandlers(onShutdown) {
         const signals = ['SIGINT', 'SIGTERM'];
-        signals.forEach((signal) => {
+        for (const signal of signals) {
             const handler = async () => {
-                console.log(`\nReceived ${signal}, initiating graceful shutdown...`);
+                log.info(`\nReceived ${signal}, initiating graceful shutdown...`);
                 try {
                     await onShutdown();
-                    console.log('Graceful shutdown completed');
+                    log.info('Graceful shutdown completed');
                     process.exit(0);
                 }
                 catch (error) {
-                    console.error('Error during graceful shutdown:', error);
+                    log.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

package/dist/utils/logger.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Structured Logger
+ *
+ * Minimal logging utility that respects VELOX_LOG_LEVEL environment variable.
+ * Replaces raw console.* calls in library code with namespaced, level-aware logging.
+ */
+/** Supported log levels, ordered by verbosity. */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** Logger instance returned by createLogger. */
+export interface Logger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Create a namespaced logger that respects VELOX_LOG_LEVEL.
+ *
+ * @param namespace - Logger namespace (e.g. 'router', 'auth')
+ * @returns Logger with debug/info/warn/error methods
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@veloxts/core';
+ *
+ * const log = createLogger('router');
+ * log.info('Route registered:', method, path);
+ * log.warn('Deprecated route pattern detected');
+ * log.error('Failed to register route:', error);
+ * ```
+ */
+export declare function createLogger(namespace: string): Logger;

package/dist/utils/logger.js

@@ -0,0 +1,59 @@
+/**
+ * Structured Logger
+ *
+ * Minimal logging utility that respects VELOX_LOG_LEVEL environment variable.
+ * Replaces raw console.* calls in library code with namespaced, level-aware logging.
+ */
+const LEVEL_PRIORITY = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+function getLogLevel() {
+    const env = (process.env.VELOX_LOG_LEVEL ?? 'warn').toLowerCase();
+    if (env in LEVEL_PRIORITY)
+        return env;
+    return 'warn';
+}
+/**
+ * Create a namespaced logger that respects VELOX_LOG_LEVEL.
+ *
+ * @param namespace - Logger namespace (e.g. 'router', 'auth')
+ * @returns Logger with debug/info/warn/error methods
+ *
+ * @example
+ * ```typescript
+ * import { createLogger } from '@veloxts/core';
+ *
+ * const log = createLogger('router');
+ * log.info('Route registered:', method, path);
+ * log.warn('Deprecated route pattern detected');
+ * log.error('Failed to register route:', error);
+ * ```
+ */
+export function createLogger(namespace) {
+    const prefix = `[@veloxts/${namespace}]`;
+    function shouldLog(level) {
+        return LEVEL_PRIORITY[level] <= LEVEL_PRIORITY[getLogLevel()];
+    }
+    return {
+        debug: (...args) => {
+            if (shouldLog('debug'))
+                console.debug(prefix, ...args);
+        },
+        info: (...args) => {
+            if (shouldLog('info'))
+                console.info(prefix, ...args);
+        },
+        warn: (...args) => {
+            if (shouldLog('warn'))
+                console.warn(prefix, ...args);
+        },
+        error: (...args) => {
+            if (shouldLog('error'))
+                console.error(prefix, ...args);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Fastify wrapper and plugin system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -43,7 +43,7 @@
   },
   "devDependencies": {
     "@fastify/static": "9.0.0",
-    "@types/node": "25.1.0",
+    "@types/node": "25.2.3",
     "@vitest/coverage-v8": "4.0.18",
     "typescript": "5.9.3",
     "vitest": "4.0.18"