HazelJS Core v0.2: Production-Ready with Graceful Shutdown & Health Checks

🎉 HazelJS Core is Now Production-Ready!

We're excited to announce HazelJS Core v0.2, a major milestone that brings critical production features, stability improvements, and performance optimizations. After extensive testing and refinement, HazelJS is now ready for production workloads.

What's New in v0.2

1. Memory Leak Prevention ✅

One of the most critical issues in long-running Node.js applications is memory leaks. We've completely eliminated memory leaks in request-scoped providers:

• Automatic cleanup - Request-scoped providers are now automatically cleaned up after each request
• Finally blocks - Cleanup happens even if errors occur
• Memory monitoring - Built-in health check tracks memory usage

// Request-scoped providers are now safe!
@Injectable({ scope: 'request' })
export class RequestContext {
  // Automatically cleaned up after request completes
  // No more memory leaks! 🎉
}

2. Graceful Shutdown 🛑

Production applications need to handle shutdown gracefully. HazelJS now includes a comprehensive shutdown manager:

• Signal handling - Automatically handles SIGTERM, SIGINT, and SIGUSR2
• Ordered shutdown - Custom handlers execute in order with timeouts
• Force shutdown protection - Prevents hanging shutdowns (30s default)
• Exception handling - Catches uncaught exceptions and unhandled rejections

const app = await HazelApp.create(AppModule);

// Register shutdown handlers
app.registerShutdownHandler({
  name: 'database',
  handler: async () => {
    await database.disconnect();
    console.log('Database disconnected');
  },
  timeout: 5000, // 5 second timeout
});

app.registerShutdownHandler({
  name: 'cache',
  handler: async () => {
    await redis.quit();
    console.log('Redis connection closed');
  },
  timeout: 3000,
});

await app.listen(3000);

// On Ctrl+C or SIGTERM:
// 1. HTTP server stops accepting new connections
// 2. Existing requests complete (up to 10s)
// 3. Database disconnects
// 4. Redis connection closes
// 5. Process exits cleanly

3. Health Check System 🏥

Kubernetes and modern deployment platforms require health checks. HazelJS now provides three built-in endpoints:

• GET /health - Liveness probe (is the service alive?)
• GET /ready - Readiness probe (is the service ready for traffic?)
• GET /startup - Startup probe (has the service completed startup?)

// Built-in health checks
app.registerHealthCheck(BuiltInHealthChecks.memoryCheck(500)); // 500MB threshold
app.registerHealthCheck(BuiltInHealthChecks.eventLoopCheck(100)); // 100ms lag threshold

// Custom health checks
app.registerHealthCheck({
  name: 'database',
  check: async () => {
    try {
      await database.ping();
      return { status: 'healthy' };
    } catch (error) {
      return { 
        status: 'unhealthy',
        message: error.message 
      };
    }
  },
  critical: true, // Service is unhealthy if this fails
  timeout: 3000,
});

// Health check response example
// GET /ready
{
  "status": "healthy",
  "timestamp": "2025-12-09T00:00:00.000Z",
  "uptime": 123456,
  "checks": {
    "memory": {
      "status": "healthy",
      "details": {
        "heapUsed": "245.32MB",
        "heapTotal": "512.00MB"
      },
      "responseTime": 2
    },
    "database": {
      "status": "healthy",
      "responseTime": 15
    }
  },
  "version": "0.2.0",
  "environment": "production"
}

4. Performance Optimizations ⚡

We've made significant performance improvements across the board:

• Route matching - Changed from O(n) to O(m) with method-based caching (~80% faster)
• Debug logging - Added guards to avoid unnecessary string operations (~30% CPU reduction)
• Request processing - Removed unnecessary JSON serialization (~15% faster)

// Before: O(n) - search all routes
for (const [routeKey, handlers] of this.routes.entries()) {
  const [routeMethod, routePath] = routeKey.split(' ');
  if (routeMethod === method && this.matchPath(path, routePath)) {
    // Found!
  }
}

// After: O(m) - only search routes for specific HTTP method
const methodRoutes = this.routesByMethod.get(method); // O(1)
for (const [routePath, handlers] of methodRoutes.entries()) {
  if (this.matchPath(path, routePath)) {
    // Found! Much faster!
  }
}

5. Enhanced Error Handling 🐛

Better error detection and debugging capabilities:

• Circular dependency detection - Now catches indirect circular dependencies (A → B → C → A)
• Full dependency chain - Error messages show the complete dependency chain
• Async/await safety - Factory functions properly handle Promises
• Context logging - Errors include request ID, method, URL, and stack traces

// Before: Only detected direct circular dependencies
// Error: Circular dependency detected for: ServiceA

// After: Shows full chain
// Error: Circular dependency detected: ServiceA → ServiceB → ServiceC → ServiceA

// Better error logging
logger.error('Unhandled error:', {
  error: error.message,
  stack: error.stack,
  requestId: 'req-123',
  method: 'POST',
  url: '/api/users',
});

Production Readiness Score

We've significantly improved HazelJS's production readiness:

Getting Started

Upgrade to v0.2 and start using the new features:

# Update to latest version
npm install @hazeljs/core@latest

# Or with yarn
yarn add @hazeljs/core@latest

Basic Usage

import { HazelApp, BuiltInHealthChecks } from '@hazeljs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await HazelApp.create(AppModule);

  // Register health checks
  app.registerHealthCheck(BuiltInHealthChecks.memoryCheck(500));
  app.registerHealthCheck(BuiltInHealthChecks.eventLoopCheck(100));

  // Register shutdown handlers
  app.registerShutdownHandler({
    name: 'database',
    handler: async () => await database.disconnect(),
    timeout: 5000,
  });

  // Start server
  await app.listen(3000);
  
  // Server output:
  // Server listening on:
  //   → Local:    http://localhost:3000
  //   → Network:  http://192.168.1.100:3000
  //
  // Health endpoints:
  //   → /health  - Liveness probe
  //   → /ready   - Readiness probe
  //   → /startup - Startup probe
}

bootstrap();

Kubernetes Integration

HazelJS health checks work seamlessly with Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: hazeljs-app
spec:
  containers:
  - name: app
    image: your-hazeljs-app:latest
    ports:
    - containerPort: 3000
    
    # Liveness probe - restart if unhealthy
    livenessProbe:
      httpGet:
        path: /health
        port: 3000
      initialDelaySeconds: 10
      periodSeconds: 10
    
    # Readiness probe - remove from service if not ready
    readinessProbe:
      httpGet:
        path: /ready
        port: 3000
      initialDelaySeconds: 5
      periodSeconds: 5
    
    # Startup probe - wait for app to start
    startupProbe:
      httpGet:
        path: /startup
        port: 3000
      failureThreshold: 30
      periodSeconds: 10

What's Next?

We're not stopping here! The roadmap for the next releases includes:

• Request Timeout - Prevent hanging requests
• CORS Support - Built-in CORS middleware
• Rate Limiting - Protect against DoS attacks
• Request ID Tracking - Better debugging and tracing
• Lifecycle Hooks - onModuleInit and onModuleDestroy
• Security Headers - Helmet.js integration
• Metrics & Monitoring - Prometheus integration
• Response Compression - gzip/brotli support

Breaking Changes

Good news! There are no breaking changes in v0.2. All improvements are backward compatible.

Performance Benchmarks

Here's how v0.2 performs compared to v0.1:

• Memory Usage - Stable under load (no leaks!)
• Route Matching - 80% faster for apps with 100+ routes
• Request Processing - 15% faster overall
• CPU Usage - 30% reduction in production (debug logging off)
• Shutdown Time - Clean shutdown in <2 seconds

Community Feedback

We'd love to hear your feedback! Try out v0.2 and let us know:

• GitHub Issues: github.com/hazeljs/hazeljs
• Discord: Join our community server
• Twitter: @hazeljs

Conclusion

HazelJS Core v0.2 represents a major step forward in production readiness. With memory leak fixes, graceful shutdown, health monitoring, and significant performance improvements, HazelJS is now ready for production workloads.

We're committed to making HazelJS the best Node.js framework for building scalable, production-ready applications. Thank you for your continued support!

Happy coding! 🚀