@martel/calyx 0.1.0

package/docs/dependency-injection.md

@@ -0,0 +1,112 @@
+# Dependency Injection System
+
+calyx features a native, compile-safe, high-performance Dependency Injection (DI) system modeled after NestJS. It provides identical configuration syntax to support frictionless migration, but operates with ~25x-30x lower bootstrapping overhead.
+
+## Decoupled Architecture
+
+The DI system is composed of:
+1. **Modules (`@Module`)**: Encapsulated scopes organizing providers and controllers.
+2. **Providers (`@Injectable`)**: Classes, factories, or static values that can be injected into constructor functions.
+3. **Container (`calyxContainer`)**: The core registry that parses metadata, detects circular dependencies, and instantiates services.
+
+---
+
+## Decorators Reference
+
+### `@Module(metadata: ModuleMetadata)`
+Declares a module scope.
+```typescript
+import { Module } from '@martel/calyx';
+
+@Module({
+  imports: [DatabaseModule],
+  providers: [UsersService],
+  exports: [UsersService], // Export to make visible to modules importing this module
+})
+export class UsersModule {}
+```
+
+### `@Injectable()`
+Marks a class as available for injection. Required on all provider/controller classes using constructor injection.
+```typescript
+import { Injectable } from '@martel/calyx';
+
+@Injectable()
+export class UsersService {}
+```
+
+### `@Inject(token: InjectionToken)`
+Explicitly injection token override. Useful for injecting non-class tokens (like string-based config values or custom providers).
+```typescript
+import { Injectable, Inject } from '@martel/calyx';
+
+@Injectable()
+export class UsersService {
+  constructor(@Inject('DATABASE_CONNECTION') private db: DbConnection) {}
+}
+```
+
+### `@Optional()`
+Marks a constructor parameter as optional. If the provider token cannot be resolved, the container will inject `undefined` instead of throwing an error.
+```typescript
+import { Injectable, Optional, Inject } from '@martel/calyx';
+
+@Injectable()
+export class UsersService {
+  constructor(@Optional() @Inject('ANALYTICS_KEY') private apiKey?: string) {}
+}
+```
+
+### `@Global()`
+Makes a module's exports globally visible, meaning they can be injected into any module without explicitly importing the parent module.
+```typescript
+import { Module, Global } from '@martel/calyx';
+
+@Global()
+@Module({
+  providers: [ConfigService],
+  exports: [ConfigService],
+})
+export class ConfigModule {}
+```
+
+---
+
+## Custom Providers
+
+calyx supports standard NestJS custom provider forms:
+
+### Value Providers (`useValue`)
+```typescript
+{
+  provide: 'CONFIG',
+  useValue: { port: 3000 }
+}
+```
+
+### Class Providers (`useClass`)
+```typescript
+{
+  provide: LoggerService,
+  useClass: BunLoggerService
+}
+```
+
+### Factory Providers (`useFactory`)
+```typescript
+{
+  provide: 'DB_CONNECTION',
+  useFactory: (config: ConfigService) => new Connection(config),
+  inject: [ConfigService]
+}
+```
+
+---
+
+## Performance Benchmarks
+
+Benchmarks measure the instantiation time of a 5-layer deep dependency tree (15 provider modules) over 5,000 iterations:
+
+*   **calyx**: ~41.45 ms total (avg 8.29 μs per bootstrap)
+*   **NestJS**: ~1104.36 ms total (avg 220.87 μs per bootstrap)
+*   **Relative Performance**: **calyx is ~26x faster** in DI compilation and instantiation.

package/docs/lifecycle.md

@@ -0,0 +1,168 @@
+# Request Lifecycle Pipeline
+
+calyx provides a complete NestJS-compatible request lifecycle pipeline consisting of Guards, Interceptors, Pipes, and Exception Filters. It exposes an identical API structure, letting you inject dependencies into lifecycle components using constructor injection, but runs at a fraction of the performance overhead.
+
+---
+
+## Execution Order
+
+When an HTTP request is received, calyx processes it through the lifecycle stages in the following order:
+
+```mermaid
+graph TD
+    A[Incoming Request] --> B[Guards]
+    B -- Allow --> C[Interceptors - Pre-handler]
+    C --> D[Pipes - Argument Validation/Transformation]
+    D --> E[Controller Handler Method]
+    E --> F[Interceptors - Post-handler]
+    F --> G[Response Sent]
+    B -- Block --> H[Exception Filter]
+    D -- Invalid --> H
+    E -- Error --> H
+    H --> G
+```
+
+---
+
+## Execution Context & ArgumentsHost
+
+Lifecycle components receive metadata about the executing process via:
+*   `ArgumentsHost`: Exposes request/response contexts.
+*   `ExecutionContext` (extends `ArgumentsHost`): Exposes the target Controller class and the method handler function.
+
+### Reference
+```typescript
+export interface ArgumentsHost {
+  getArgs<T extends any[]>(): T;
+  getArgByIndex<T>(index: number): T;
+  switchToHttp(): HttpArgumentsHost;
+}
+
+export interface ExecutionContext extends ArgumentsHost {
+  getClass<T = any>(): Type<T>;
+  getHandler(): Function;
+}
+```
+
+---
+
+## Guards (`@UseGuards`)
+
+Guards implement the `CanActivate` interface. They return `boolean` (or a Promise resolving to `boolean`) indicating whether the request should proceed. If `false` is returned, calyx throws a `403 Forbidden` exception.
+
+```typescript
+import { CanActivate, ExecutionContext, UseGuards, Controller, Get } from '@martel/calyx';
+
+class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext): boolean {
+    const req = context.switchToHttp().getRequest<Request>();
+    return req.headers.get('Authorization') === 'allow-secret';
+  }
+}
+
+@Controller('admin')
+@UseGuards(AuthGuard) // Applies to all routes in the controller
+export class AdminController {
+  @Get()
+  getDashboard() {
+    return 'Admin Dashboard';
+  }
+}
+```
+
+---
+
+## Interceptors (`@UseInterceptors`)
+
+Interceptors implement `NestInterceptor`. They allow you to bind extra logic before and after method execution.
+
+```typescript
+import { NestInterceptor, CallHandler, ExecutionContext, UseInterceptors, Get } from '@martel/calyx';
+
+class TransformInterceptor implements NestInterceptor {
+  async intercept(context: ExecutionContext, next: CallHandler): Promise<any> {
+    // 1. Pre-handler logic
+    const start = Date.now();
+    
+    // 2. Execute inner handlers/controller method
+    const result = await next.handle();
+    
+    // 3. Post-handler logic
+    const ms = Date.now() - start;
+    return { ...result, executionTimeMs: ms };
+  }
+}
+
+@Get('data')
+@UseInterceptors(TransformInterceptor)
+getData() {
+  return { data: 'payload' };
+}
+```
+
+---
+
+## Pipes (`@UsePipes`)
+
+Pipes implement `PipeTransform`. They are used for validation or data transformation. Pipes can be bound at:
+1.  **Class / Method Level**: Using `@UsePipes()`.
+2.  **Parameter Level**: Inside `@Body()`, `@Query()`, or `@Param()`.
+
+```typescript
+import { PipeTransform, Query, Get, BadRequestException } from '@martel/calyx';
+
+class ParseIntPipe implements PipeTransform {
+  transform(value: any): number {
+    const parsed = Number(value);
+    if (isNaN(parsed)) {
+      throw new BadRequestException('Validation failed: value must be numeric');
+    }
+    return parsed;
+  }
+}
+
+@Get('square')
+square(@Query('num', ParseIntPipe) num: number) {
+  // num is guaranteed to be a number type
+  return { result: num * num };
+}
+```
+
+---
+
+## Exception Filters (`@UseFilters` / `@Catch`)
+
+Filters catch unhandled exceptions thrown during request execution. Use `@Catch(...Exceptions)` to declare which exceptions the filter catches.
+
+```typescript
+import { ExceptionFilter, Catch, ArgumentsHost, UseFilters, calyxResponse } from '@martel/calyx';
+
+class CustomError extends Error {}
+
+@Catch(CustomError)
+class TeapotFilter implements ExceptionFilter {
+  catch(exception: CustomError, host: ArgumentsHost) {
+    const res = host.switchToHttp().getResponse<calyxResponse>();
+    res.status(418).json({
+      error: 'Teapot',
+      message: exception.message,
+    });
+  }
+}
+
+@Get('error')
+@UseFilters(TeapotFilter)
+triggerError() {
+  throw new CustomError('Failed operation');
+}
+```
+
+---
+
+## Performance Benchmarks
+
+Overhead benchmarks run the full request lifecycle (with a Class Guard, Method Interceptor, and Parameter Query Pipe) using `autocannon` (100 concurrent connections, 8-second test duration, no pipelining) running in separate OS processes:
+
+*   **calyx (Bun Native with Pipeline)**: **25,152 req/sec** (avg latency **3.25 ms**)
+*   **NestJS (Express with Pipeline)**: **10,274 req/sec** (avg latency **9.28 ms**)
+*   **Relative Performance**: Even with all decorators and lifecycle hooks active, **calyx is ~2.4x faster** than NestJS and runs with **3x lower latency**.

package/docs/migration.md

@@ -0,0 +1,108 @@
+# Migration Guide: NestJS to calyx
+
+calyx is built to offer direct syntax and concept compatibility with NestJS. If you have an existing NestJS application, migrating to calyx is straightforward.
+
+This document outlines the steps required to transition your codebase to calyx and compile it to a standalone binary.
+
+---
+
+## 1. Project Configuration
+
+### package.json
+Remove NestJS dependencies and install `@martel/calyx` (with `reflect-metadata` which is required for legacy decorator reflection):
+
+```json
+{
+  "dependencies": {
+    "@martel/calyx": "^0.1.0",
+    "reflect-metadata": "^0.2.2"
+  }
+}
+```
+
+### tsconfig.json
+Ensure your TypeScript options enable legacy decorators:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "moduleResolution": "Bundler"
+  }
+}
+```
+
+---
+
+## 2. Import Mappings
+
+NestJS divides code across several packages (`@nestjs/common`, `@nestjs/core`, etc.). calyx exposes all components from a single package.
+
+Replace all NestJS imports with `@martel/calyx`:
+
+```typescript
+// BEFORE (NestJS)
+import { Module, Injectable, Controller, Get, Param } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+
+// AFTER (calyx)
+import { Module, Injectable, Controller, Get, Param, calyxFactory } from '@martel/calyx';
+```
+
+---
+
+## 3. Bootstrap Changes
+
+In NestJS, applications are bootstrapped using `NestFactory.create`. In calyx, use `calyxFactory.create` which returns a `calyxApplication` instance backed by Bun's native HTTP server:
+
+```typescript
+// BEFORE (NestJS)
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+
+// AFTER (calyx)
+import { calyxFactory } from '@martel/calyx';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await calyxFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+---
+
+## 4. Execution Lifecycle Components
+
+calyx implements identical decorators and interfaces for lifecycle elements:
+
+*   **Guards**: Change `import { CanActivate } from '@nestjs/common'` to `@martel/calyx`.
+*   **Interceptors**: Change `import { NestInterceptor } from '@nestjs/common'` to `@martel/calyx`.
+    *   *Note: In NestJS, `next.handle()` returns an RxJS `Observable`. In calyx, it returns a standard native `Promise` or an `Observable` based on developer preference. If migrating RxJS interceptors, you can map the result or rewrite to simple async-await.*
+*   **Pipes**: Change `import { PipeTransform } from '@nestjs/common'` to `@martel/calyx`.
+*   **Exception Filters**: Change `import { ExceptionFilter, Catch } from '@nestjs/common'` to `@martel/calyx`.
+    *   *Note: Expose `host.switchToHttp().getResponse()` which returns calyx's Express-compatible `calyxResponse` wrapper to make calls like `res.status(code).json(body)` compatible without modifications.*
+
+---
+
+## 5. Compiling to a Standalone Binary
+
+One of the major benefits of moving to calyx is the ability to package the entire server, including TypeScript files, routing, DI, and the Bun runtime, into a single, high-performance standalone binary:
+
+```bash
+bun build --compile src/main.ts --outfile build/server
+```
+
+You can then run the output directly on any matching machine with no Node.js, Bun, or `node_modules` dependencies:
+
+```bash
+./build/server
+```

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@martel/calyx",
+  "version": "0.1.0",
+  "description": "High-performance Bun-native NestJS-compatible framework",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "test": "bun test",
+    "benchmark": "bun run benchmarks/index.ts"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27",
+    "@nestjs/platform-express": "^11.1.27",
+    "@types/autocannon": "^7.12.7",
+    "@types/bun": "latest",
+    "autocannon": "^8.0.0",
+    "rxjs": "^7.8.2",
+    "semantic-release": "^24.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^10.0.0",
+    "@semantic-release/npm": "^12.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}