@martel/calyx 0.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun test
+
+      - name: Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: 'OIDC' # Dummy token to bypass semantic-release check; npm CLI uses the OIDC id-token
+        run: bunx semantic-release

package/.releaserc.json

@@ -0,0 +1,27 @@
+{
+  "branches": [
+    "main"
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    [
+      "@semantic-release/npm",
+      {
+        "npmPublish": true
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "CHANGELOG.md"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/benchmarks/di-benchmark.ts

@@ -0,0 +1,114 @@
+import 'reflect-metadata';
+import { performance } from 'perf_hooks';
+// Import NestJS
+import { Module as NestModule, Injectable as NestInjectable } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+// Import calyx
+import { Module as calyxModule, Injectable as calyxInjectable, calyxContainer } from '../src/index.ts';
+
+// ----------------------------------------------------
+// Setup Dependency Tree classes
+// ----------------------------------------------------
+
+// calyx classes
+@calyxInjectable()
+class calyxService5 {}
+
+@calyxInjectable()
+class calyxService4 {
+  constructor(public s5: calyxService5) {}
+}
+
+@calyxInjectable()
+class calyxService3 {
+  constructor(public s4: calyxService4) {}
+}
+
+@calyxInjectable()
+class calyxService2 {
+  constructor(public s3: calyxService3) {}
+}
+
+@calyxInjectable()
+class calyxService1 {
+  constructor(public s2: calyxService2) {}
+}
+
+@calyxModule({
+  providers: [calyxService1, calyxService2, calyxService3, calyxService4, calyxService5],
+})
+class calyxAppModule {}
+
+// NestJS classes
+@NestInjectable()
+class NestService5 {}
+
+@NestInjectable()
+class NestService4 {
+  constructor(public s5: NestService5) {}
+}
+
+@NestInjectable()
+class NestService3 {
+  constructor(public s4: NestService4) {}
+}
+
+@NestInjectable()
+class NestService2 {
+  constructor(public s3: NestService3) {}
+}
+
+@NestInjectable()
+class NestService1 {
+  constructor(public s2: NestService2) {}
+}
+
+@NestModule({
+  providers: [NestService1, NestService2, NestService3, NestService4, NestService5],
+})
+class NestAppModule {}
+
+// ----------------------------------------------------
+// Benchmarking Logic
+// ----------------------------------------------------
+
+async function runBenchmark() {
+  console.log('=============================================');
+  console.log('calyx vs NestJS DI Container Benchmark');
+  console.log('=============================================');
+
+  const iterations = 5000;
+
+  // 1. Benchmark calyx Bootstrap
+  console.log(`Bootstrapping calyx container ${iterations} times...`);
+  const calyxStart = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    const container = new calyxContainer();
+    container.bootstrap(calyxAppModule);
+    // Resolve one
+    container.getGlobalOrAnyInstance(calyxService1);
+  }
+  const calyxEnd = performance.now();
+  const calyxTime = calyxEnd - calyxStart;
+  console.log(`calyx: ${calyxTime.toFixed(2)} ms (avg ${(calyxTime / iterations * 1000).toFixed(2)} μs per bootstrap)`);
+
+  // 2. Benchmark NestJS Bootstrap
+  console.log(`Bootstrapping NestJS container ${iterations} times...`);
+  const nestStart = performance.now();
+  for (let i = 0; i < iterations; i++) {
+    const app = await NestFactory.createApplicationContext(NestAppModule, { logger: false });
+    // Resolve one
+    app.get(NestService1);
+    await app.close();
+  }
+  const nestEnd = performance.now();
+  const nestTime = nestEnd - nestStart;
+  console.log(`NestJS: ${nestTime.toFixed(2)} ms (avg ${(nestTime / iterations * 1000).toFixed(2)} μs per bootstrap)`);
+
+  console.log('---------------------------------------------');
+  const speedup = nestTime / calyxTime;
+  console.log(`calyx is ${speedup.toFixed(2)}x FASTER than NestJS in Dependency Injection bootstrapping.`);
+  console.log('=============================================');
+}
+
+runBenchmark().catch(console.error);

package/benchmarks/http-benchmark.ts

@@ -0,0 +1,103 @@
+import autocannon from 'autocannon';
+import { join } from 'path';
+
+async function runAutocannon(port: number, name: string): Promise<autocannon.Result> {
+  console.log(`Running autocannon benchmark against ${name}...`);
+  return new Promise((resolve, reject) => {
+    autocannon(
+      {
+        url: `http://localhost:${port}/hello`,
+        connections: 100,
+        pipelining: 1,
+        duration: 8, // 8 seconds to get stable results
+      },
+      (err, result) => {
+        if (err) reject(err);
+        else resolve(result);
+      }
+    );
+  });
+}
+
+async function main() {
+  const calyxPath = join(import.meta.dir, 'run-calyx.ts');
+  const nestPath = join(import.meta.dir, 'run-nest.ts');
+
+  console.log('Spawning calyx server...');
+  const calyxProc = Bun.spawn(['bun', calyxPath], {
+    stdout: 'pipe',
+    stderr: 'inherit',
+  });
+
+  // Wait for calyx server to print ready message
+  const calyxReader = calyxProc.stdout.getReader();
+  const decoder = new TextDecoder();
+  while (true) {
+    const { value, done } = await calyxReader.read();
+    if (done) break;
+    const chunk = decoder.decode(value);
+    if (chunk.includes('calyx listening')) {
+      break;
+    }
+  }
+  calyxReader.releaseLock();
+  console.log('calyx server is ready.');
+
+  console.log('Spawning NestJS server...');
+  const nestProc = Bun.spawn(['bun', nestPath], {
+    stdout: 'pipe',
+    stderr: 'inherit',
+  });
+
+  const nestReader = nestProc.stdout.getReader();
+  while (true) {
+    const { value, done } = await nestReader.read();
+    if (done) break;
+    const chunk = decoder.decode(value);
+    if (chunk.includes('NestJS listening')) {
+      break;
+    }
+  }
+  nestReader.releaseLock();
+  console.log('NestJS server is ready.');
+
+  try {
+    // Warmup
+    console.log('Warming up connections...');
+    for (let i = 0; i < 50; i++) {
+      await fetch('http://localhost:4001/hello');
+      await fetch('http://localhost:4002/hello');
+    }
+
+    // Run benchmarks
+    const calyxResult = await runAutocannon(4001, 'calyx (Bun Native, separate process)');
+    const nestResult = await runAutocannon(4002, 'NestJS (Express on Bun, separate process)');
+
+    console.log('\n======================================================');
+    console.log('HTTP Throughput & Latency Comparison (Multi-Process)');
+    console.log('======================================================');
+    console.log(`calyx (Bun Native):`);
+    console.log(`  Requests/Sec (Avg): ${calyxResult.requests.average.toFixed(0)}`);
+    console.log(`  Latency (Avg ms):   ${calyxResult.latency.average.toFixed(2)}`);
+    console.log(`  Throughput (Mb/s):  ${(calyxResult.throughput.average / 1024 / 1024).toFixed(2)}`);
+    console.log(`------------------------------------------------------`);
+    console.log(`NestJS (Express on Bun):`);
+    console.log(`  Requests/Sec (Avg): ${nestResult.requests.average.toFixed(0)}`);
+    console.log(`  Latency (Avg ms):   ${nestResult.latency.average.toFixed(2)}`);
+    console.log(`  Throughput (Mb/s):  ${(nestResult.throughput.average / 1024 / 1024).toFixed(2)}`);
+    console.log(`------------------------------------------------------`);
+    
+    const speedup = calyxResult.requests.average / nestResult.requests.average;
+    console.log(`calyx is ${speedup.toFixed(2)}x FASTER in requests/sec than NestJS!`);
+    console.log('======================================================\n');
+
+  } finally {
+    // Kill processes
+    console.log('Shutting down server processes...');
+    calyxProc.kill();
+    nestProc.kill();
+    console.log('Servers shut down successfully.');
+  }
+}
+
+main().catch(console.error);

package/benchmarks/lifecycle-benchmark.ts

@@ -0,0 +1,102 @@
+import autocannon from 'autocannon';
+import { join } from 'path';
+
+async function runAutocannon(port: number, name: string): Promise<autocannon.Result> {
+  console.log(`Running autocannon benchmark against ${name}...`);
+  return new Promise((resolve, reject) => {
+    autocannon(
+      {
+        url: `http://localhost:${port}/hello?num=42`,
+        connections: 100,
+        pipelining: 1,
+        duration: 8, // 8 seconds to get stable results
+      },
+      (err, result) => {
+        if (err) reject(err);
+        else resolve(result);
+      }
+    );
+  });
+}
+
+async function main() {
+  const calyxPath = join(import.meta.dir, 'run-calyx-lifecycle.ts');
+  const nestPath = join(import.meta.dir, 'run-nest-lifecycle.ts');
+
+  console.log('Spawning calyx lifecycle server...');
+  const calyxProc = Bun.spawn(['bun', calyxPath], {
+    stdout: 'pipe',
+    stderr: 'inherit',
+  });
+
+  const decoder = new TextDecoder();
+  const calyxReader = calyxProc.stdout.getReader();
+  while (true) {
+    const { value, done } = await calyxReader.read();
+    if (done) break;
+    const chunk = decoder.decode(value);
+    if (chunk.includes('calyx lifecycle listening')) {
+      break;
+    }
+  }
+  calyxReader.releaseLock();
+  console.log('calyx lifecycle server is ready.');
+
+  console.log('Spawning NestJS lifecycle server...');
+  const nestProc = Bun.spawn(['bun', nestPath], {
+    stdout: 'pipe',
+    stderr: 'inherit',
+  });
+
+  const nestReader = nestProc.stdout.getReader();
+  while (true) {
+    const { value, done } = await nestReader.read();
+    if (done) break;
+    const chunk = decoder.decode(value);
+    if (chunk.includes('NestJS lifecycle listening')) {
+      break;
+    }
+  }
+  nestReader.releaseLock();
+  console.log('NestJS lifecycle server is ready.');
+
+  try {
+    // Warmup
+    console.log('Warming up connections...');
+    for (let i = 0; i < 50; i++) {
+      await fetch('http://localhost:4003/hello?num=42');
+      await fetch('http://localhost:4004/hello?num=42');
+    }
+
+    // Run benchmarks
+    const calyxResult = await runAutocannon(4003, 'calyx (Bun Native with Guards/Pipes/Interceptors)');
+    const nestResult = await runAutocannon(4004, 'NestJS (Express with Guards/Pipes/Interceptors)');
+
+    console.log('\n======================================================');
+    console.log('HTTP Lifecycle Pipeline (Guards/Pipes/Interceptors) Comparison');
+    console.log('======================================================');
+    console.log(`calyx (Bun Native):`);
+    console.log(`  Requests/Sec (Avg): ${calyxResult.requests.average.toFixed(0)}`);
+    console.log(`  Latency (Avg ms):   ${calyxResult.latency.average.toFixed(2)}`);
+    console.log(`  Throughput (Mb/s):  ${(calyxResult.throughput.average / 1024 / 1024).toFixed(2)}`);
+    console.log(`------------------------------------------------------`);
+    console.log(`NestJS (Express on Bun):`);
+    console.log(`  Requests/Sec (Avg): ${nestResult.requests.average.toFixed(0)}`);
+    console.log(`  Latency (Avg ms):   ${nestResult.latency.average.toFixed(2)}`);
+    console.log(`  Throughput (Mb/s):  ${(nestResult.throughput.average / 1024 / 1024).toFixed(2)}`);
+    console.log(`------------------------------------------------------`);
+    
+    const speedup = calyxResult.requests.average / nestResult.requests.average;
+    console.log(`calyx is ${speedup.toFixed(2)}x FASTER in requests/sec than NestJS with full pipeline!`);
+    console.log('======================================================\n');
+
+  } finally {
+    // Kill processes
+    console.log('Shutting down server processes...');
+    calyxProc.kill();
+    nestProc.kill();
+    console.log('Servers shut down successfully.');
+  }
+}
+
+main().catch(console.error);

package/benchmarks/run-calyx-lifecycle.ts

@@ -0,0 +1,58 @@
+import 'reflect-metadata';
+import {
+  Module,
+  Controller,
+  Get,
+  Query,
+  UseGuards,
+  UseInterceptors,
+  UsePipes,
+  CanActivate,
+  NestInterceptor,
+  CallHandler,
+  PipeTransform,
+  ExecutionContext,
+  calyxFactory,
+} from '../src/index.ts';
+
+class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    return true; // dummy guard
+  }
+}
+
+class TransformInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    const res = await next.handle();
+    return { ...res, intercepted: true };
+  }
+}
+
+class ParseIntPipe implements PipeTransform {
+  transform(value: any) {
+    return Number(value);
+  }
+}
+
+@Controller('hello')
+@UseGuards(AuthGuard)
+@UseInterceptors(TransformInterceptor)
+class HelloController {
+  @Get()
+  getHello(@Query('num', ParseIntPipe) num: number) {
+    return { value: num };
+  }
+}
+
+@Module({
+  controllers: [HelloController],
+})
+class AppModule {}
+
+async function main() {
+  const app = await calyxFactory.create(AppModule);
+  await app.listen(4003);
+  console.log('calyx lifecycle listening on 4003');
+}
+
+main().catch(console.error);

package/benchmarks/run-calyx.ts

@@ -0,0 +1,23 @@
+import 'reflect-metadata';
+import { Module, Controller, Get, calyxFactory } from '../src/index.ts';
+
+@Controller('hello')
+class HelloController {
+  @Get()
+  getHello() {
+    return { message: 'hello' };
+  }
+}
+
+@Module({
+  controllers: [HelloController],
+})
+class AppModule {}
+
+async function main() {
+  const app = await calyxFactory.create(AppModule);
+  await app.listen(4001);
+  console.log('calyx listening on 4001');
+}
+
+main().catch(console.error);

package/benchmarks/run-nest-lifecycle.ts

@@ -0,0 +1,60 @@
+import 'reflect-metadata';
+import {
+  Module,
+  Controller,
+  Get,
+  Query,
+  UseGuards,
+  UseInterceptors,
+  UsePipes,
+  CanActivate,
+  NestInterceptor,
+  CallHandler,
+  PipeTransform,
+  ExecutionContext,
+} from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+
+class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    return true; // dummy guard
+  }
+}
+
+class TransformInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    // Note: NestJS interceptor handle() returns RxJS Observable, which we must import to run the map operator
+    // To keep it simple, since RxJS is installed in our devDependencies, we can do it:
+    const { map } = await import('rxjs/operators');
+    return next.handle().pipe(map((res: any) => ({ ...res, intercepted: true })));
+  }
+}
+
+class ParseIntPipe implements PipeTransform {
+  transform(value: any) {
+    return Number(value);
+  }
+}
+
+@Controller('hello')
+@UseGuards(AuthGuard)
+@UseInterceptors(TransformInterceptor)
+class HelloController {
+  @Get()
+  getHello(@Query('num', ParseIntPipe) num: number) {
+    return { value: num };
+  }
+}
+
+@Module({
+  controllers: [HelloController],
+})
+class AppModule {}
+
+async function main() {
+  const app = await NestFactory.create(AppModule, { logger: false });
+  await app.listen(4004);
+  console.log('NestJS lifecycle listening on 4004');
+}
+
+main().catch(console.error);

package/benchmarks/run-nest.ts

@@ -0,0 +1,24 @@
+import 'reflect-metadata';
+import { Module, Controller, Get } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+
+@Controller('hello')
+class HelloController {
+  @Get()
+  getHello() {
+    return { message: 'hello' };
+  }
+}
+
+@Module({
+  controllers: [HelloController],
+})
+class AppModule {}
+
+async function main() {
+  const app = await NestFactory.create(AppModule, { logger: false });
+  await app.listen(4002);
+  console.log('NestJS listening on 4002');
+}
+
+main().catch(console.error);

package/docs/controllers.md

@@ -0,0 +1,122 @@
+# Controllers & Routing
+
+calyx's controller layer allows routing HTTP requests to class methods using decorators. It mirrors NestJS's request-mapping syntax but operates natively on Bun's ultra-fast HTTP server, bypassing Node.js compatibility wrappers or middleware overhead.
+
+## Creating a Controller
+
+Controllers are decorated with `@Controller(prefix?: string)`. Each method handles a specific route defined by HTTP method decorators.
+
+```typescript
+import { Controller, Get, Post, Body } from '@martel/calyx';
+
+@Controller('items')
+export class ItemsController {
+  @Get()
+  findAll() {
+    return ['item1', 'item2'];
+  }
+
+  @Post()
+  create(@Body() createDto: any) {
+    return { success: true, data: createDto };
+  }
+}
+```
+
+---
+
+## HTTP Method Decorators
+
+calyx supports the standard HTTP verbs matching NestJS:
+
+*   `@Get(path?: string)`
+*   `@Post(path?: string)`
+*   `@Put(path?: string)`
+*   `@Delete(path?: string)`
+*   `@Patch(path?: string)`
+*   `@Options(path?: string)`
+*   `@Head(path?: string)`
+*   `@All(path?: string)`
+
+---
+
+## Route Parameters and Request Decorators
+
+Method arguments can extract parts of the request payload using parameter decorators:
+
+| Decorator | NestJS Match | Description |
+| :--- | :--- | :--- |
+| `@Req()` / `@Request()` | `req` | Exposes the raw Bun `Request` object. |
+| `@Res()` / `@Response()` | `res` | Exposes the `calyxResponse` wrapper for manual responses. |
+| `@Param(key?: string)` | `params[key]` | Extracts path parameters (e.g. `@Param('id')`). |
+| `@Query(key?: string)` | `query[key]` | Extracts query parameters (e.g. `@Query('limit')`). |
+| `@Body(key?: string)` | `body[key]` | Extracts request body payload (parsed JSON/urlencoded). |
+| `@Headers(key?: string)` | `headers[key]` | Extracts request headers. |
+
+### Example
+```typescript
+@Get(':userId/posts/:postId')
+getPost(
+  @Param('userId') userId: string,
+  @Param('postId') postId: string,
+  @Query('verbose') verbose?: string
+) {
+  return { userId, postId, verbose: verbose === 'true' };
+}
+```
+
+---
+
+## Response Customization
+
+### Status Codes (`@HttpCode`)
+By default, the response status code is `200` (except `POST` requests which default to `201`). Override this with `@HttpCode(code)`:
+```typescript
+@Post()
+@HttpCode(204)
+create() {
+  // Returns HTTP 204 No Content
+}
+```
+
+### Custom Headers (`@Header`)
+Define custom static response headers:
+```typescript
+@Get('custom-header')
+@Header('Cache-Control', 'none')
+getWithHeader() {
+  return 'No Cache';
+}
+```
+
+### Redirects (`@Redirect`)
+Redirects request to a specified URL with an optional status code (defaults to `302` Found):
+```typescript
+@Get('legacy-path')
+@Redirect('/new-path', 301)
+legacy() {}
+```
+
+---
+
+## Manual Response Processing
+
+If you need full control over the response, inject `@Res()`:
+```typescript
+@Get('manual')
+manualResponse(@Res() res: calyxResponse) {
+  res.status(202).set('X-Manual', 'true').json({ success: true });
+}
+```
+*Note: If you use `@Res()`, you are responsible for calling `res.send()` or `res.json()`. Otherwise, the request will hang.*
+
+---
+
+## Performance Benchmarks
+
+HTTP routing performance is measured using `autocannon` (100 concurrent connections, 8-second test duration, no pipelining) running in separate OS processes to eliminate CPU resource contention.
+
+*   **calyx (Bun Native)**: **62,164 req/sec** (avg latency **1.05 ms**)
+*   **NestJS (Express on Bun)**: **23,694 req/sec** (avg latency **3.66 ms**)
+*   **Performance Gain**: **calyx is ~2.6x faster** than NestJS and delivers **3.5x lower latency** in realistic concurrent traffic conditions.
+