han-framework

v1.0.0

Published

9 months ago

**A modern, developer-friendly Node.js framework inspired by NestJS**

0High
0Medium
0Low

emeritussoftdev

🚀 Han Framework

A modern, developer-friendly Node.js framework inspired by NestJS

Han Framework eliminates configuration complexity while providing powerful features out of the box. Built for developers who want to focus on building great applications, not wrestling with setup.

✨ Why Han Framework?

| Feature | Han Framework | NestJS | |---------|---------------|---------| | Setup Time | 2 minutes | 15+ minutes | | Configuration | Zero config needed | Manual setup required | | Shutdown Hooks | Automatic | Manual enableShutdownHooks() | | Security | Built-in CORS + Helmet | Manual configuration | | Environment Detection | Automatic | Manual setup | | Route Analytics | Built-in visual dashboard | Not included |

🏃‍♂️ Quick Start

Installation

npm install han-framework
# or
yarn add han-framework

Create Your First App

// app.module.ts
import { Module } from 'han-framework';
import { AppController } from './app.controller';

@Module({
  controllers: [AppController]
})
export class AppModule {}

// app.controller.ts
import { Controller, Get } from 'han-framework';

@Controller()
export class AppController {
  @Get()
  hello() {
    return { message: 'Hello Han Framework!' };
  }
}

// index.ts
import 'reflect-metadata';
import { HanFactory } from 'han-framework';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await HanFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

Run Your App

npm start

That's it! 🎉 Your app is running with:

✅ CORS enabled
✅ Security headers (Helmet)
✅ Request logging
✅ Graceful shutdown
✅ Route analytics dashboard

🎯 Core Features

Zero Configuration

No setup required - everything works out of the box with sensible defaults.

// This gives you a production-ready app
const app = await HanFactory.create(AppModule);
await app.listen(3000);

Smart Environment Detection

Automatically configures based on your deployment environment.

Development: Binds to localhost, enhanced logging
Production: Binds to 0.0.0.0, optimized performance
Containers: Auto-detects Docker/Kubernetes, configures accordingly

Automatic Lifecycle Management

Graceful shutdown and cleanup happen automatically - no manual setup needed.

// Automatically handles SIGINT/SIGTERM
// Provides graceful shutdown with timeout protection
// Cleans up resources properly

Built-in Security

Security best practices are enabled by default.

CORS: Configured automatically with smart defaults
Helmet: Security headers enabled out of the box
Request Validation: Built-in input sanitization

Request/Response Interceptors

Simple, intuitive hooks for request lifecycle management.

// Add global interceptors
app.useGlobalInterceptors(LoggingInterceptor);
app.useGlobalInterceptors(new PerformanceInterceptor(200));

Visual Route Analytics

Beautiful route dashboard displayed on startup.

🚀 Han Framework - Application Started
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Route Analytics Dashboard:
   🎯 Total Routes: 4
   🏛️  Controllers: 2
   📅 Generated: 9/29/2025, 10:38:18 PM

   🔢 HTTP Methods Breakdown:
      📖 GET   : 3 routes (75.0%)
      📝 POST  : 1 routes (25.0%)

📍 Route Mappings by Controller:

┌─ [AppController] (2 routes)
├─ 📖 GET    /api/health
└─ 📖 GET    /api/info

┌─ [WebhookController] (2 routes)
├─ 📝 POST   🛡️ /api/webhook/github [+2 middleware]
└─ 📖 GET    /api/webhook/status

🛠️ Configuration (When You Need It)

Basic Configuration

const app = await HanFactory.create(AppModule, {
  globalPrefix: '/api/v1',    // Add API prefix
  cors: true,                 // Enable CORS (default: true)
  helmet: true,               // Enable security headers (default: true)
  bodyParser: true            // Enable body parsing (default: true)
});

Advanced Configuration

const app = await HanFactory.create(AppModule, {
  // CORS Configuration
  cors: {
    origin: ['https://yourdomain.com'],
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'DELETE']
  },

  // Security Configuration
  helmet: {
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'", "'unsafe-inline'"]
      }
    }
  },

  // Shutdown Configuration
  shutdownHooks: {
    enabled: true,              // Enable graceful shutdown (default: true)
    gracefulTimeout: 15000,     // 15 second timeout (default: 10000)
    signals: ['SIGINT', 'SIGTERM'] // Signals to handle
  }
});

🔧 Advanced Features

Custom Shutdown Hooks

// Database cleanup
app.onApplicationShutdown(async () => {
  await database.close();
  console.log('Database connections closed');
});

// Cache cleanup
app.onApplicationShutdown(() => {
  cache.clear();
  console.log('Cache cleared');
});

Global Interceptors

Add request/response processing that applies to all routes.

// Built-in interceptors
app.useGlobalInterceptors(LoggingInterceptor);
app.useGlobalInterceptors(new PerformanceInterceptor(200));

// Custom interceptor
class AuthInterceptor {
  beforeHandle(context) {
    // Pre-request logic
  }

  afterHandle(context, response) {
    // Post-request logic
  }

  onError(context, error) {
    // Error handling
  }
}

app.useGlobalInterceptors(new AuthInterceptor());

Dependency Injection

Full dependency injection support with automatic resolution.

@Injectable()
export class UserService {
  findAll() {
    return [{ id: 1, name: 'John' }];
  }
}

@Controller('users')
export class UserController {
  constructor(private userService: UserService) {}

  @Get()
  getUsers() {
    return this.userService.findAll();
  }
}

Module System

Organize your application with a modular architecture.

@Module({
  imports: [DatabaseModule, AuthModule],
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService]
})
export class UserModule {}

🚀 Deployment

Development

const app = await HanFactory.create(AppModule);
await app.listen(3000);
// Automatically configures for development environment

Production

const app = await HanFactory.create(AppModule, {
  shutdownHooks: {
    gracefulTimeout: 30000  // Longer timeout for production
  }
});

const port = process.env.PORT || 3000;
await app.listen(port);
// Automatically configures for production environment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]
# Han Framework automatically detects container environment

📖 Examples

REST API

@Controller('users')
export class UserController {
  @Get()
  findAll() {
    return [{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }];
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return { id, name: 'John' };
  }

  @Post()
  create(@Body() user: CreateUserDto) {
    return { id: 3, ...user };
  }
}

WebSocket Support

@Controller()
export class EventsController {
  @WebSocketGateway()
  handleConnection(client: any) {
    console.log('Client connected:', client.id);
  }

  @SubscribeMessage('message')
  handleMessage(client: any, payload: any) {
    return { event: 'message', data: payload };
  }
}

Microservices

// Create a microservice instead of HTTP server
const microservice = await HanFactory.createMicroservice(AppModule, {
  transport: Transport.TCP,
  options: { port: 3001 }
});

await microservice.listen();

🆚 Comparison with NestJS

Migration from NestJS

Han Framework is designed to be compatible with NestJS applications. Most NestJS code works without changes:

// Your existing NestJS controllers work as-is
@Controller('users')
export class UserController {
  @Get()
  findAll() {
    return this.userService.findAll();
  }
}

// Your existing modules work as-is
@Module({
  imports: [UserModule],
  controllers: [AppController]
})
export class AppModule {}

Key Differences

| Aspect | Han Framework | NestJS | |--------|---------------|---------| | Setup | Zero config | Manual config | | Shutdown | Automatic | Manual | | Security | Built-in | Manual setup | | Interceptors | Simple hooks | RxJS observables | | Environment | Auto-detection | Manual configuration | | Performance | Built-in monitoring | External packages |

📚 Documentation

Core Guides

Getting Started - Step-by-step setup guide
Architecture - Framework design and concepts
Configuration - All configuration options
Deployment - Production deployment guide

Advanced Topics

Lifecycle Management - Graceful shutdown and cleanup
Interceptors - Request/response lifecycle hooks
Dependency Injection - DI container usage
Microservices - Building microservice applications

Examples

REST API - Complete REST API example
WebSocket - Real-time communication
Microservice - Microservice architecture
Database Integration - Database setup and usage

🏗️ Project Structure

src/
├── controllers/           # Route handlers
│   ├── app.controller.ts
│   └── user.controller.ts
├── services/             # Business logic
│   ├── app.service.ts
│   └── user.service.ts
├── modules/              # Feature modules
│   ├── user.module.ts
│   └── auth.module.ts
├── interceptors/         # Request/response hooks
│   ├── logging.interceptor.ts
│   └── auth.interceptor.ts
├── app.module.ts        # Root module
└── index.ts            # Application entry point

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/your-org/han-framework
cd han-framework
npm install
npm run dev

Running Tests

npm test              # Unit tests
npm run test:e2e     # End-to-end tests
npm run test:coverage # Coverage report

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Inspired by the excellent work of the NestJS team. Han Framework builds upon their concepts while focusing on developer experience and automation.

Ready to build something amazing? 🚀

Get started with Han Framework today and experience the joy of zero-configuration development with enterprise-grade features built-in.

npm install han-framework

Built with ❤️ for developers who want to focus on building, not configuring.