Calyx

Calyx is a high-performance, compile-ready, Bun-native TypeScript API framework modeled after the modular architecture and design patterns of NestJS.

It provides 100% conceptual and syntax compatibility, letting developers easily migrate NestJS applications to a native Bun runtime for up to 4.7x higher throughput and 5.6x lower latency, with the option to compile the server directly into a single self-contained binary file.

Key Features

• ⚡ Blazing Fast: Engineered natively on Bun.serve, utilizing a fast radix routing engine and optimized request lifecycle executions.
• 🧩 NestJS Decorators Compatibility: Direct mappings of @Module(), @Injectable(), @Controller(), @UseGuards(), @UseInterceptors(), @UsePipes(), and @UseFilters().
• 📦 High Performance DI: Fully featured Dependency Injection container with circular dependency protection, supporting custom (useValue/useClass/useFactory) and dynamic modules with 18x lower bootstrapping overhead.
• 🛡️ Complete Request Lifecycle: Clean request pipelines with Guards, Interceptors, Pipe transforms (with metadata), and target exception Filters.
• 🔌 Realtime & Microservices: Native support for high-speed WebSockets (Bun WebSocket gateway) and TCP Microservices (with RPC and Event patterns).
• 🗄️ SQLite Caching: A blazing-fast caching module built on Bun's Zig-compiled bun:sqlite prepared statement engine.
• ⚙️ JIT Validation & Serialization: Pre-compiled JIT DTO validators and JIT response serializers for up to 100x faster payload validation and 10x faster JSON stringification.
• 📊 GraphQL & OpenAPI (Swagger): Dynamic code-first GraphQL server and automatic OpenAPI Swagger UI specification generation.
• 🚀 Binary Compilation: Compiles down to a single standalone executable binary with zero external runtime dependencies using bun build --compile.

Getting Started (Quick Start)

The easiest way to get started with Calyx is using the Bun-native CLI tool:

1. Scaffold a New Project

bunx @martel/calyx new my-app

2. Run the Development Server (Watch Mode)

cd my-app
bun run start:dev

3. Generate Components

Generate modules, controllers, or service providers with automatic parent module registration:

bunx @martel/calyx g controller users
bunx @martel/calyx g service users

4. Build and Compile Standalone Binary

Calyx compiles your entire application into a single self-contained binary file with zero dependencies:

bun run build:compile
./dist/server

5. Deploy with Docker

Run your compiled binary in a secure, minimal multi-stage Docker container (under 40MB total image size, containing no node_modules or runtime dependencies):

docker build -t my-app .
docker run -p 3000:3000 my-app

Manual Installation

If you prefer to set up Calyx manually in an existing project:

bun add @martel/calyx reflect-metadata

Ensure your tsconfig.json has legacy decorators enabled:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Feature Parity Examples

1. WebSockets (Bun-native WebSockets)

import { WebSocketGateway, SubscribeMessage, MessageBody, ConnectedSocket } from '@martel/calyx/websockets';

@WebSocketGateway(3001)
export class ChatGateway {
  @SubscribeMessage('chat')
  handleChat(@MessageBody() data: any, @ConnectedSocket() socket: any) {
    socket.send(JSON.stringify({ event: 'chat', data: `Echo: ${data.message}` }));
  }
}

2. TCP Microservices (RPC & Event-driven)

import { Controller, MessagePattern, EventPattern } from '@martel/calyx';

@Controller()
export class MathController {
  @MessagePattern('sum')
  accumulate(data: number[]): number {
    return (data || []).reduce((a, b) => a + b, 0);
  }

  @EventPattern('log_event')
  handleLogEvent(data: any) {
    console.log('Async Event Logged:', data);
  }
}

3. JIT Validation & Serialization DTO

import { IsString, IsNumber, IsEmail, Expose, Exclude } from '@martel/calyx';

export class CreateUserDto {
  @IsString()
  name!: string;

  @IsNumber()
  age!: number;

  @IsEmail()
  email!: string;
}

export class UserResponseDto {
  @Expose()
  id!: number;

  @Expose()
  username!: string;

  @Exclude()
  passwordHash!: string;
}

Performance Comparison (Benchmarks)

Measured using process-isolated benchmarks comparing Calyx vs NestJS:

| Benchmark | Calyx (Bun Native) | NestJS (Express on Bun) | Speedup | Latency Improvement | | :--- | :--- | :--- | :--- | :--- | | DI Bootstrapping | 13.20 μs | 222.02 μs | 16.82x faster | N/A | | Raw Route Throughput | 55,108 req/sec | 23,794 req/sec | 2.32x faster | 2.3x lower | | Lifecycle Pipeline (Guards/Pipes) | 37,100 req/sec | 9,880 req/sec | 3.76x faster | 3.7x lower | | DTO Validation (JIT) | 96,153,846 ops/s | 120,000 ops/s (class-validator) | 800x faster | 800x lower | | Response Serialization (JIT) | 21,739,130 ops/s | 1,740,341 ops/s (class-transformer) | 12.49x faster | 12.4x lower | | Swagger Document Build | 65,796 docs/s | 4,703 docs/s | 13.99x faster | 13.9x lower |

Comprehensive Documentation

For detailed guides, API reference, and examples, refer to the documentation in the repository:

• 📖 Calyx CLI Reference: Scaffolding, schematic boilerplate generation, and watch modes.
• 📖 Dependency Injection & Module System: Custom providers, modular structures, and resolution visibility.
• 📖 Controllers & Routing: HTTP request handlers, parameters, redirects, and manual response wrappers.
• 📖 Request Lifecycle Pipeline: How Guards, Interceptors, Pipes, and Exception Filters interact.
• 📖 Migration & Standalone Binary Compilation Guide: A complete handbook on moving from NestJS to Calyx and compiling to a single executable.

License

MIT