Introduction to HazelJS

Agent OS for TypeScript backends — durable AI agents inside the same DI/HTTP app as your APIs. DNA packages, crash-safe HITL, Skillgate, and local apply. Framework packages (HCEL, RAG, workflows) when you need them — they are not the wedge.

Start here: Clone Meridian (store:sync → platform:sync → npm run dev), then read the Agent OS guide.

What is HazelJS?

HazelJS is a TypeScript Node framework whose primary product is Agent OS: durable agent runs, DNA packaging, Skillgate-governed REST skills, and local apply/reconcile — not a Nest clone and not “47 packages” as the story. Decorators and DI stay familiar; agents are backend jobs, not a chat widget bolted onto Express.

🏗️Architecture

HazelJS follows a modular, decorator-based architecture that promotes separation of concerns and code reusability. The framework is built on top of a powerful dependency injection system and uses metadata reflection for configuration.

graph TD
    A["HTTP Request"] --> B["Routing Layer<br/>(@Controller, @Get, @Post)"]
    B --> C["Middleware Pipeline<br/>(Global & Route-specific)"]
    C --> D["Guards<br/>(Authentication & Authorization)"]
    D --> E["Interceptors<br/>(Request/Response Transformation)"]
    E --> F["Pipes<br/>(Validation & Transformation)"]
    F --> G["Controller Handler<br/>(Business Logic)"]
    G --> H["Services<br/>(Dependency Injection)"]
    H --> I["Data Layer<br/>(Prisma, Cache, External APIs)"]
    I --> J["Response"]
    
    style A fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style B fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style C fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff
    style D fill:#f59e0b,stroke:#fbbf24,stroke-width:2px,color:#fff
    style E fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style F fill:#ec4899,stroke:#f472b6,stroke-width:2px,color:#fff
    style G fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style H fill:#06b6d4,stroke:#22d3ee,stroke-width:2px,color:#fff
    style I fill:#14b8a6,stroke:#2dd4bf,stroke-width:2px,color:#fff
    style J fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff

graph LR
    A["AppModule<br/>(Root Module)"] --> B["Feature Modules"]
    B --> C["UsersModule"]
    B --> D["ProductsModule"]
    B --> E["AuthModule"]
    
    C --> F["Controllers<br/>Services<br/>Providers"]
    D --> F
    E --> F
    
    F --> G["DI Container<br/>(Automatic Resolution)"]
    
    style A fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style B fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff
    style C fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style D fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style E fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style F fill:#f59e0b,stroke:#fbbf24,stroke-width:2px,color:#fff
    style G fill:#06b6d4,stroke:#22d3ee,stroke-width:2px,color:#fff

⚙️Technical Details

@Controller('users')
export class UsersController {
  constructor(private usersService: UsersService) {}
  
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Injectable()
export class UsersService {
  constructor(
    private prisma: PrismaService,
    private cache: CacheService
  ) {}
  
  // Dependencies automatically injected
}

💡Why HazelJS?

HazelJS combines the best features of modern Node.js frameworks with a focus on simplicity, performance, and developer experience.

✨Key Features

🚀Getting Started

Ready to start building with HazelJS? Follow these steps to get up and running in minutes.

💻Quick Example

Here's a simple example to show how easy it is to build with HazelJS:

import { HazelApp, HazelModule, Controller, Get, Injectable } from '@hazeljs/core';

@Injectable()
export class AppService {
  getHello() {
    return 'Hello from HazelJS!';
  }
}

@Controller('hello')
export class HelloController {
  constructor(private appService: AppService) {}
  
  @Get()
  hello() {
    return { message: this.appService.getHello() };
  }
}

@HazelModule({
  controllers: [HelloController],
  providers: [AppService],
})
export class AppModule {}

async function bootstrap() {
  const app = new HazelApp(AppModule);
  await app.listen(3000);
  console.log('🚀 Application running on http://localhost:3000');
}

bootstrap();

This example demonstrates dependency injection, routing, and module organization. Visit http://localhost:3000/hello to see it in action.

🤝Community

Join our growing community of developers building with HazelJS. We welcome contributions of all kinds, from bug reports to feature requests and pull requests.