@martel/calyx 0.1.0 → 1.0.0

package/.github/workflows/release.yml

@@ -21,6 +21,11 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
@@ -35,5 +40,4 @@ jobs:
       - 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
+        run: npx semantic-release

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 1.0.0 (2026-07-01)
+
+
+### Features
+
+* achieve full NestJS parity and compile request execution pipelines for performance ([ddc5b6b](https://github.com/bmartel/calyx/commit/ddc5b6bd24ff3c505b7a004c058f00535b1f2695))

package/README.md

@@ -0,0 +1,130 @@
+# 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 **~2.5x higher throughput** and **3.5x 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 **29x lower bootstrapping overhead**.
+*   **🛡️ Complete Request Lifecycle**: Clean request pipelines with Guards, Interceptors, Pipe transforms (with metadata), and target exception Filters.
+*   **🚀 Binary Compilation**: Compiles down to a single standalone executable binary with zero external runtime dependencies using `bun build --compile`.
+
+---
+
+## Installation
+
+Initialize your project and install Calyx with your package manager:
+
+```bash
+bun add @martel/calyx reflect-metadata
+```
+
+Ensure your `tsconfig.json` has legacy decorators enabled:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+---
+
+## Quick Start
+
+```typescript
+import 'reflect-metadata';
+import { Module, Injectable, Controller, Get, Query, UseGuards, CanActivate, ExecutionContext, VerdantFactory } from '@martel/calyx';
+
+// 1. Define a Guard
+@Injectable()
+class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request>();
+    return req.headers.get('Authorization') === 'secret-token';
+  }
+}
+
+// 2. Define a Controller
+@Controller('items')
+class ItemsController {
+  @Get()
+  @UseGuards(AuthGuard)
+  getItems(@Query('limit') limit?: string) {
+    return { data: ['item1', 'item2'], limit: limit ? Number(limit) : 10 };
+  }
+}
+
+// 3. Define a Module
+@Module({
+  controllers: [ItemsController],
+})
+class AppModule {}
+
+// 4. Bootstrap Server
+async function bootstrap() {
+  const app = await CalyxFactory.create(AppModule);
+  await app.listen(3000);
+  console.log('Calyx application is running on port 3000');
+}
+bootstrap();
+```
+
+---
+
+## Performance Comparison (Benchmarks)
+
+Measured using process-isolated `autocannon` benchmarks (100 connections, 8s, no pipelining) comparing Calyx vs NestJS (Express adapter under Bun):
+
+| Benchmark | Calyx (Bun Native) | NestJS (Express on Bun) | Speedup | Latency Improvement |
+| :--- | :--- | :--- | :--- | :--- |
+| **DI Bootstrapping** | **7.81 μs** | 227.56 μs | **~29x faster** | N/A |
+| **Raw Route Throughput** | **59,408 req/sec** | 23,148 req/sec | **2.57x faster** | **3.5x lower** (1.10ms vs 3.88ms) |
+| **Lifecycle Pipeline (Guards/Pipes)** | **25,152 req/sec** | 10,274 req/sec | **2.45x faster** | **2.8x lower** (3.25ms vs 9.28ms) |
+
+---
+
+## Comprehensive Documentation
+
+For detailed guides, API reference, and examples, refer to the documentation in the repository:
+
+*   📖 **[Dependency Injection & Module System](file:///e:/code/verdant/docs/dependency-injection.md)**: Custom providers, modular structures, and resolution visibility.
+*   📖 **[Controllers & Routing](file:///e:/code/verdant/docs/controllers.md)**: HTTP request handlers, parameters, redirects, and manual response wrappers.
+*   📖 **[Request Lifecycle Pipeline](file:///e:/code/verdant/docs/lifecycle.md)**: How Guards, Interceptors, Pipes, and Exception Filters interact.
+*   📖 **[Migration & Standalone Binary Compilation Guide](file:///e:/code/verdant/docs/migration.md)**: A complete handbook on moving from NestJS to Calyx and compiling to a single executable.
+
+---
+
+## Commands
+
+### Run Unit Tests
+```bash
+bun test
+```
+
+### Run Performance Benchmarks
+```bash
+# DI container benchmark
+bun benchmarks/di-benchmark.ts
+
+# HTTP server benchmark (compares Calyx vs NestJS)
+bun benchmarks/http-benchmark.ts
+```
+
+### Build Binary
+```bash
+bun build --compile src/index.ts --outfile build/server
+```
+
+---
+
+## License
+
+MIT

package/benchmarks/di-benchmark.ts

@@ -4,7 +4,7 @@ import { performance } from 'perf_hooks';
 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';
+import { Module as calyxModule, Injectable as calyxInjectable, CalyxContainer } from '../src/index.ts';
 
 // ----------------------------------------------------
 // Setup Dependency Tree classes
@@ -12,32 +12,32 @@ import { Module as calyxModule, Injectable as calyxInjectable, calyxContainer }
 
 // calyx classes
 @calyxInjectable()
-class calyxService5 {}
+class CalyxService5 {}
 
 @calyxInjectable()
-class calyxService4 {
-  constructor(public s5: calyxService5) {}
+class CalyxService4 {
+  constructor(public s5: CalyxService5) {}
 }
 
 @calyxInjectable()
-class calyxService3 {
-  constructor(public s4: calyxService4) {}
+class CalyxService3 {
+  constructor(public s4: CalyxService4) {}
 }
 
 @calyxInjectable()
-class calyxService2 {
-  constructor(public s3: calyxService3) {}
+class CalyxService2 {
+  constructor(public s3: CalyxService3) {}
 }
 
 @calyxInjectable()
-class calyxService1 {
-  constructor(public s2: calyxService2) {}
+class CalyxService1 {
+  constructor(public s2: CalyxService2) {}
 }
 
 @calyxModule({
-  providers: [calyxService1, calyxService2, calyxService3, calyxService4, calyxService5],
+  providers: [CalyxService1, CalyxService2, CalyxService3, CalyxService4, CalyxService5],
 })
-class calyxAppModule {}
+class CalyxAppModule {}
 
 // NestJS classes
 @NestInjectable()
@@ -83,10 +83,10 @@ async function runBenchmark() {
   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);
+    const container = new CalyxContainer();
+    container.bootstrap(CalyxAppModule);
     // Resolve one
-    container.getGlobalOrAnyInstance(calyxService1);
+    container.getGlobalOrAnyInstance(CalyxService1);
   }
   const calyxEnd = performance.now();
   const calyxTime = calyxEnd - calyxStart;

package/benchmarks/run-calyx-lifecycle.ts

@@ -12,7 +12,7 @@ import {
   CallHandler,
   PipeTransform,
   ExecutionContext,
-  calyxFactory,
+  CalyxFactory,
 } from '../src/index.ts';
 
 class AuthGuard implements CanActivate {
@@ -50,7 +50,7 @@ class HelloController {
 class AppModule {}
 
 async function main() {
-  const app = await calyxFactory.create(AppModule);
+  const app = await CalyxFactory.create(AppModule);
   await app.listen(4003);
   console.log('calyx lifecycle listening on 4003');
 }

package/benchmarks/run-calyx.ts

@@ -1,5 +1,5 @@
 import 'reflect-metadata';
-import { Module, Controller, Get, calyxFactory } from '../src/index.ts';
+import { Module, Controller, Get, CalyxFactory } from '../src/index.ts';
 
 @Controller('hello')
 class HelloController {
@@ -15,7 +15,7 @@ class HelloController {
 class AppModule {}
 
 async function main() {
-  const app = await calyxFactory.create(AppModule);
+  const app = await CalyxFactory.create(AppModule);
   await app.listen(4001);
   console.log('calyx listening on 4001');
 }