@martel/calyx 1.13.0 → 1.13.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.13.1](https://github.com/bmartel/calyx/compare/v1.13.0...v1.13.1) (2026-07-01)
+
+
+### Performance Improvements
+
+* optimize request execution paths and add warmup to benchmarks ([f6327c7](https://github.com/bmartel/calyx/commit/f6327c72395d9e6264df27e08800dd16479f8ff7))
+
 # [1.13.0](https://github.com/bmartel/calyx/compare/v1.12.0...v1.13.0) (2026-07-01)
 
 

package/README.md

@@ -147,10 +147,12 @@ Measured using process-isolated benchmarks comparing Calyx vs NestJS:
 
 | Benchmark | Calyx (Bun Native) | NestJS (Express on Bun) | Speedup | Latency Improvement |
 | :--- | :--- | :--- | :--- | :--- |
-| **DI Bootstrapping** | **39.12 μs** | 259.83 μs | **6.64x faster** | N/A |
-| **Raw Route Throughput** | **54,764 req/sec** | 18,759 req/sec | **2.92x faster** | **2.9x lower** |
-| **Lifecycle Pipeline (Guards/Pipes)** | **41,683 req/sec** | 8,803 req/sec | **4.73x faster** | **4.7x lower** |
+| **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** |
 
 ---
 

package/benchmarks/graphql-benchmark.ts

@@ -61,7 +61,10 @@ async function runBenchmark() {
   `;
 
   // Warmup
-  await graphql({ schema, source: query });
+  console.log('Warming up GraphQL query execution JIT...');
+  for (let i = 0; i < 1000; i++) {
+    await graphql({ schema, source: query });
+  }
 
   const execStart = performance.now();
   for (let i = 0; i < iterations; i++) {

package/benchmarks/serialization-benchmark.ts

@@ -21,9 +21,36 @@ class UserResponseDto {
 // Compile JIT Serializer
 const serialize = SerializationCompiler.compile(UserResponseDto);
 
-const ITERATIONS = 10_000_000;
+const ITERATIONS = 5_000_000;
 const testUser = new UserResponseDto(123, 'alice', 'secret_hash_code_here');
 
+// Simulated NestJS Class-Transformer reflection-based classToPlain mapping
+function nestjsClassToPlain(obj: any, targetClass: any): any {
+  const keys = Object.keys(obj);
+  const plain: Record<string, any> = {};
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const exposes = Reflect.getMetadata('calyx:expose_properties', targetClass);
+    const excludes = Reflect.getMetadata('calyx:exclude_properties', targetClass);
+    const isExposed = exposes ? exposes.has(key) : true;
+    const isExcluded = excludes ? excludes.has(key) : false;
+    
+    if (isExposed && !isExcluded) {
+      plain[key] = obj[key];
+    }
+  }
+  return plain;
+}
+
+// Warmup
+console.log('Warming up JIT compiler...');
+for (let i = 0; i < 500_000; i++) {
+  serialize(testUser);
+  const plain = { id: testUser.id, username: testUser.username };
+  JSON.stringify(plain);
+  nestjsClassToPlain(testUser, UserResponseDto);
+}
+
 console.log(`Running Serialization Benchmark with ${ITERATIONS.toLocaleString()} iterations...\n`);
 
 // Benchmark Calyx JIT Serializer
@@ -35,10 +62,9 @@ const endJit = Date.now();
 const timeJit = endJit - startJit;
 const opsJit = Math.round((ITERATIONS / timeJit) * 1000);
 
-// Benchmark Standard JSON.stringify (simulating traditional serialization)
+// Benchmark Standard JSON.stringify (manual plain object conversion baseline)
 const startJson = Date.now();
 for (let i = 0; i < ITERATIONS; i++) {
-  // To simulate key exclusion manually or using a replacer/omit function like NestJS does
   const plain = { id: testUser.id, username: testUser.username };
   JSON.stringify(plain);
 }
@@ -46,7 +72,21 @@ const endJson = Date.now();
 const timeJson = endJson - startJson;
 const opsJson = Math.round((ITERATIONS / timeJson) * 1000);
 
+// Benchmark NestJS class-transformer + JSON.stringify parity
+const startNest = Date.now();
+for (let i = 0; i < ITERATIONS; i++) {
+  const plain = nestjsClassToPlain(testUser, UserResponseDto);
+  JSON.stringify(plain);
+}
+const endNest = Date.now();
+const timeNest = endNest - startNest;
+const opsNest = Math.round((ITERATIONS / timeNest) * 1000);
+
 console.log('--- RESULTS ---');
-console.log(`Calyx JIT Serializer:   ${timeJit}ms (${opsJit.toLocaleString()} ops/sec)`);
-console.log(`Standard JSON.stringify: ${timeJson}ms (${opsJson.toLocaleString()} ops/sec)`);
-console.log(`Speedup Factor:          ${(timeJson / timeJit).toFixed(2)}x faster\n`);
+console.log(`Calyx JIT Serializer:          ${timeJit}ms (${opsJit.toLocaleString()} ops/sec)`);
+console.log(`Standard JSON.stringify:        ${timeJson}ms (${opsJson.toLocaleString()} ops/sec)`);
+console.log(`NestJS (class-transformer):    ${timeNest}ms (${opsNest.toLocaleString()} ops/sec)`);
+console.log(`--------------------------------`);
+console.log(`Speedup (vs JSON.stringify):    ${(timeJson / timeJit).toFixed(2)}x faster`);
+console.log(`Speedup (vs NestJS Class-TX):   ${(timeNest / timeJit).toFixed(2)}x FASTER!`);
+console.log('======================================================\n');

package/benchmarks/techniques-benchmark.ts

@@ -21,6 +21,12 @@ async function runBenchmarks() {
   const db = new Database(':memory:');
   const repo = new Repository(db, User);
 
+  // Warmup DB repo
+  for (let i = 0; i < 500; i++) {
+    const user = await repo.save({ name: `Warmup_${i}` });
+    await repo.findOne({ where: { id: user.id } });
+  }
+
   console.log('1. Database Operations (Repository.save & Repository.find):');
   const dbIterations = 10000;
   const dbStart = performance.now();
@@ -43,6 +49,12 @@ async function runBenchmarks() {
   console.log('2. Cookie Parsing:');
   const cookieHeader = 'sid=calyx_sid_123456789; test_cookie=val; another_cookie=value; expires=Wed, 21 Oct 2026 07:28:00 GMT';
   const cookieIterations = 1000000;
+  
+  // Warmup Cookie Parser
+  for (let i = 0; i < 100_000; i++) {
+    parseCookies(cookieHeader);
+  }
+
   const cookieStart = performance.now();
   for (let i = 0; i < cookieIterations; i++) {
     parseCookies(cookieHeader);

package/benchmarks/validation-benchmark.ts

@@ -45,9 +45,16 @@ function traditionalValidate(obj: any): string[] | null {
 }
 
 // Benchmark Config
-const ITERATIONS = 10_000_000;
+const ITERATIONS = 5_000_000;
 const validPayload = { name: 'Alice', age: 30, email: 'alice@example.com' };
 
+// Warmup
+console.log('Warming up JIT compiler...');
+for (let i = 0; i < 500_000; i++) {
+  validate(validPayload);
+  traditionalValidate(validPayload);
+}
+
 console.log(`Running Validation Benchmark with ${ITERATIONS.toLocaleString()} iterations...\n`);
 
 // Benchmark Calyx JIT

package/docs/controllers.md

@@ -116,7 +116,7 @@ manualResponse(@Res() res: CalyxResponse) {
 
 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.
+*   **calyx (Bun Native)**: **55,108 req/sec** (avg latency **1.13 ms**)
+*   **NestJS (Express on Bun)**: **23,794 req/sec** (avg latency **3.61 ms**)
+*   **Performance Gain**: **calyx is 2.32x faster** than NestJS and delivers **3.2x lower latency** in realistic concurrent traffic conditions.
 

package/docs/dependency-injection.md

@@ -107,6 +107,6 @@ calyx supports standard NestJS custom provider forms:
 
 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.
+*   **calyx**: ~65.99 ms total (avg 13.20 μs per bootstrap)
+*   **NestJS**: ~1110.10 ms total (avg 222.02 μs per bootstrap)
+*   **Relative Performance**: **calyx is 16.82x faster** in DI compilation and instantiation.

package/docs/lifecycle.md

@@ -163,6 +163,6 @@ triggerError() {
 
 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**.
+*   **calyx (Bun Native with Pipeline)**: **37,100 req/sec** (avg latency **2.11 ms**)
+*   **NestJS (Express with Pipeline)**: **9,880 req/sec** (avg latency **9.60 ms**)
+*   **Relative Performance**: Even with all decorators and lifecycle hooks active, **calyx is 3.76x faster** than NestJS and runs with **4.5x lower latency**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@martel/calyx",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "High-performance Bun-native NestJS-compatible framework",
   "main": "src/index.ts",
   "bin": {

package/src/cookies/cookies.ts

@@ -13,16 +13,53 @@ export interface CookieOptions {
 export function parseCookies(cookieHeader: string): Record<string, string> {
   const cookies: Record<string, string> = {};
   if (!cookieHeader) return cookies;
-  const parts = cookieHeader.split(';');
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i];
-    const eqIdx = part.indexOf('=');
-    if (eqIdx !== -1) {
-      const key = part.substring(0, eqIdx).trim();
-      const val = part.substring(eqIdx + 1).trim();
-      cookies[key] = decodeURIComponent(val);
+  
+  let start = 0;
+  const len = cookieHeader.length;
+  
+  while (start < len) {
+    // Skip leading spaces
+    while (start < len && cookieHeader.charCodeAt(start) === 32) { // ' '
+      start++;
     }
+    if (start >= len) break;
+    
+    let end = cookieHeader.indexOf(';', start);
+    if (end === -1) {
+      end = len;
+    }
+    
+    const eqIdx = cookieHeader.indexOf('=', start);
+    if (eqIdx !== -1 && eqIdx < end) {
+      // Trim key
+      let keyStart = start;
+      let keyEnd = eqIdx;
+      while (keyStart < keyEnd && cookieHeader.charCodeAt(keyStart) === 32) {
+        keyStart++;
+      }
+      while (keyEnd > keyStart && cookieHeader.charCodeAt(keyEnd - 1) === 32) {
+        keyEnd--;
+      }
+      
+      // Trim val
+      let valStart = eqIdx + 1;
+      let valEnd = end;
+      while (valStart < valEnd && cookieHeader.charCodeAt(valStart) === 32) {
+        valStart++;
+      }
+      while (valEnd > valStart && cookieHeader.charCodeAt(valEnd - 1) === 32) {
+        valEnd--;
+      }
+      
+      const key = cookieHeader.substring(keyStart, keyEnd);
+      const val = cookieHeader.substring(valStart, valEnd);
+      
+      cookies[key] = val.indexOf('%') !== -1 ? decodeURIComponent(val) : val;
+    }
+    
+    start = end + 1;
   }
+  
   return cookies;
 }
 

package/src/graphql/graphql.module.ts

@@ -1,5 +1,7 @@
 import { CalyxContainer, DynamicModule } from '../core/container.ts';
 import { Module } from '../core/decorators.ts';
+import { CalyxExecutionContext } from '../lifecycle/context.ts';
+import { HttpException } from '../http/exceptions.ts';
 import {
   GraphQLSchema,
   GraphQLObjectType,
@@ -262,7 +264,6 @@ export class GraphQLModule {
 
         const resolveFn = async (parent: any, args: any, context: any, info: any) => {
           const req = context?.req;
-          const { CalyxExecutionContext } = await import('../lifecycle/context.ts');
           const execContext = new CalyxExecutionContext(req, null, resolverClass, resolverInstance[fieldMeta.propertyKey]);
           (execContext as any).type = 'graphql';
           (execContext as any).data = args;
@@ -277,7 +278,6 @@ export class GraphQLModule {
               const canActivate = guard.instance.canActivate(execContext);
               const resolved = canActivate instanceof Promise ? await canActivate : canActivate;
               if (!resolved) {
-                const { HttpException } = await import('../http/exceptions.ts');
                 throw new HttpException('Forbidden resource', 403);
               }
             }
@@ -429,7 +429,6 @@ export class GraphQLModule {
 
               targetFields[fieldName].resolve = async (parent: any, args: any, context: any, info: any) => {
                 const req = context?.req;
-                const { CalyxExecutionContext } = await import('../lifecycle/context.ts');
                 const execContext = new CalyxExecutionContext(req, null, resolverClass, resolverInstance[fieldRes.propertyKey]);
                 (execContext as any).type = 'graphql';
                 (execContext as any).data = args;
@@ -443,7 +442,6 @@ export class GraphQLModule {
                     const canActivate = guard.instance.canActivate(execContext);
                     const resolved = canActivate instanceof Promise ? await canActivate : canActivate;
                     if (!resolved) {
-                      const { HttpException } = await import('../http/exceptions.ts');
                       throw new HttpException('Forbidden resource', 403);
                     }
                   }

package/src/http/application.ts

@@ -158,6 +158,7 @@ export class CalyxApplication {
   private serverPort = 3000;
   private graphqlSchema: any = null;
   private graphqlQueryCache = new Map<string, any>();
+  private graphqlLib: any = null;
   private isInitialized = false;
   private versioningOptions?: VersioningOptions;
   private globalPrefix?: string;
@@ -578,8 +579,8 @@ export class CalyxApplication {
     try {
       const urlStr = req.url;
       // Parse cookies
-      const cookieHeader = req.headers.get('cookie') || '';
-      (req as any).cookies = parseCookies(cookieHeader);
+      const cookieHeader = req.headers.get('cookie');
+      (req as any).cookies = cookieHeader ? parseCookies(cookieHeader) : {};
 
       // Fast path parsing
       let pathname = '/';
@@ -1345,7 +1346,7 @@ export class CalyxApplication {
       const body = await req.json() as any;
       const { query, variables } = body;
 
-      const { parse, validate, execute } = await import('graphql');
+      const { parse, validate, execute } = this.graphqlLib || (this.graphqlLib = await import('graphql'));
       
       let document = this.graphqlQueryCache.get(query);
       if (!document) {
@@ -1480,7 +1481,7 @@ export class CalyxApplication {
           const { id, payload } = data;
           const { query, variables } = payload;
           
-          const { subscribe, parse, validate } = await import('graphql');
+          const { subscribe, parse, validate } = this.graphqlLib || (this.graphqlLib = await import('graphql'));
           
           let document = this.graphqlQueryCache.get(query);
           if (!document) {

package/src/validation/compiler.ts

@@ -215,15 +215,12 @@ export class SerializationCompiler {
     const jsonParts: string[] = [];
     for (const key of keys) {
       const propRules = rules.filter((r) => r.propertyKey === key);
-      const isNumber = propRules.some((r) => r.type === 'number');
-      const isString = propRules.some((r) => r.type === 'string');
+      const designType = Reflect.getMetadata('design:type', dtoClass.prototype, key);
+      const isNumber = propRules.some((r) => r.type === 'number') || designType === Number;
+      const isBoolean = propRules.some((r) => r.type === 'isBoolean') || designType === Boolean;
 
-      if (isNumber) {
+      if (isNumber || isBoolean) {
         jsonParts.push(`"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : obj.${key}}`);
-      } else if (isString) {
-        jsonParts.push(
-          `"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : JSON.stringify(obj.${key})}`
-        );
       } else {
         jsonParts.push(
           `"${key}":\${obj.${key} === undefined || obj.${key} === null ? null : JSON.stringify(obj.${key})}`