@engjts/nexus 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engjts/nexus",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Nexus framework async-first web framework with type-safety and security built-in",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/BENCHMARK_REPORT.md

@@ -1,343 +0,0 @@
-# 📊 Benchmark Report: Nexus vs Express vs Fastify
-
-**Tanggal Test:** 7 Desember 2025  
-**Environment:** macOS  
-**Node.js Runtime:** tsx (TypeScript execution)
-
----
-
-## ⚙️ Konfigurasi Benchmark
-
-| Parameter | Value |
-|-----------|-------|
-| Duration | 10 detik per test |
-| Connections | 100 concurrent |
-| Pipelining | 10 requests per connection |
-| Tool | autocannon v7.15.0 |
-
----
-
-## 🏆 Hasil Overall
-
-| Rank | Server | Avg Req/sec | Avg Latency | Total Errors |
-|------|--------|-------------|-------------|--------------|
-| 🥇 | **Fastify** | 71,578 | 16.5 ms | 0 |
-| 🥈 | **Nexus** | 49,313 | 19.2 ms | 910 |
-| 🥉 | **Express** | 20,277 | 51.6 ms | 0 |
-
----
-
-## 📌 Hasil Per Endpoint
-
-### 1. Simple JSON Response (`GET /json`)
-
-Response: `{ "message": "Hello, World!" }`
-
-| Server | Req/sec | Latency (avg) | Latency (p99) | Throughput |
-|--------|---------|---------------|---------------|------------|
-| **Fastify** | 98,004 | 9.69 ms | 16 ms | 18.51 MB/s |
-| **Nexus** | 96,131 | 9.99 ms | 15 ms | 16.69 MB/s |
-| Express | 27,071 | 36.42 ms | 74 ms | 6.76 MB/s |
-
-**🏆 Winner:** Fastify (+1.9% vs Nexus)
-
-> ✅ **Nexus sangat kompetitif!** Hanya 1.9% lebih lambat dari Fastify untuk simple JSON.
-
----
-
-### 2. Echo with Query Parameter (`GET /echo?name=Benchmark`)
-
-Response: `{ "echo": "Hello, Benchmark!" }`
-
-| Server | Req/sec | Latency (avg) | Latency (p99) | Throughput |
-|--------|---------|---------------|---------------|------------|
-| **Fastify** | 92,023 | 10.44 ms | 19 ms | 17.47 MB/s |
-| **Nexus** | 71,066 | 13.70 ms | 23 ms | 12.40 MB/s |
-| Express | 22,747 | 43.39 ms | 87 ms | 5.71 MB/s |
-
-**🏆 Winner:** Fastify (+29.5% vs Nexus)
-
-> ⚠️ **Gap mulai terlihat** saat ada query parameter parsing.
-
----
-
-### 3. Large Array Response (`GET /users`)
-
-Response: Array of 100 user objects
-
-| Server | Req/sec | Latency (avg) | Latency (p99) | Throughput |
-|--------|---------|---------------|---------------|------------|
-| **Fastify** | 31,896 | 30.83 ms | 54 ms | 218.99 MB/s |
-| **Nexus** | 30,047 | 32.75 ms | 68 ms | 205.84 MB/s |
-| Express | 15,349 | 64.47 ms | 127 ms | 106.37 MB/s |
-
-**🏆 Winner:** Fastify (+6.2% vs Nexus)
-
-> ✅ **Nexus performs well** untuk payload besar, hanya 6% lebih lambat.
-
----
-
-### 4. POST with JSON Body (`POST /data`)
-
-Request Body: `{ "test": "data", "numbers": [1,2,3,4,5] }`
-
-| Server | Req/sec | Latency (avg) | Latency (p99) | Errors |
-|--------|---------|---------------|---------------|--------|
-| **Fastify** | 64,388 | 15.03 ms | 28 ms | 0 |
-| Express | 15,941 | 62.10 ms | 103 ms | 0 |
-| Nexus | 8 | 20.44 ms | 27 ms | **910** |
-
-**🏆 Winner:** Fastify
-
-> 🚨 **CRITICAL ISSUE:** Nexus mengalami 910 timeout errors dan hanya mampu handle 8 req/sec!
-
----
-
-## 🐛 Issue Analysis: Nexus POST Body Parsing
-
-### Problem yang Ditemukan
-
-Saat benchmark POST endpoint, Nexus mengalami:
-- **910 timeout errors**
-- **0 successful 2xx responses** (82 non-2xx responses)
-- Throughput drop dari ~70k req/s ke **8 req/s**
-
-### Root Cause Analysis
-
-Berdasarkan kode server Nexus yang kita gunakan:
-
-```typescript
-app.post('/data', async (ctx) => {
-  const body = await ctx.body();  // ← Potential bottleneck
-  return ctx.json({ received: body, processed: true });
-});
-```
-
-**Kemungkinan penyebab:**
-
-1. **Async Body Parsing Bottleneck**
-   - `ctx.body()` mungkin tidak di-optimize untuk high concurrency
-   - Setiap request harus wait untuk body stream selesai di-parse
-   - Dengan 100 connections × 10 pipelining = 1000 concurrent requests, ini bisa cause blocking
-
-2. **Stream Handling Issue**
-   - Body parsing mungkin tidak properly buffer incoming data
-   - Potential memory pressure saat banyak request bersamaan
-
-3. **Missing Content-Type Handling**
-   - Mungkin perlu explicit JSON parser middleware
-
-4. **Connection Pool Exhaustion**
-   - Async operations yang pending bisa exhaust available resources
-
-### Rekomendasi untuk Nexus
-
-```typescript
-// Option 1: Pre-parse body dengan middleware
-app.use(async (ctx, next) => {
-  if (ctx.method === 'POST' || ctx.method === 'PUT') {
-    ctx.parsedBody = await ctx.body();
-  }
-  return next();
-});
-
-// Option 2: Gunakan built-in JSON middleware jika ada
-app.use(nexus.json()); // seperti express.json()
-
-// Option 3: Batasi concurrent body parsing
-import { Semaphore } from 'async-mutex';
-const bodySemaphore = new Semaphore(50);
-
-app.post('/data', async (ctx) => {
-  const [, release] = await bodySemaphore.acquire();
-  try {
-    const body = await ctx.body();
-    return ctx.json({ received: body, processed: true });
-  } finally {
-    release();
-  }
-});
-```
-
----
-
-## 📈 Performance Gap Analysis: Mengapa Nexus Kalah dari Fastify?
-
-### 1. JSON Serialization
-
-**Fastify** menggunakan `fast-json-stringify` yang pre-compile JSON schema:
-
-```javascript
-// Fastify internal - schema-based serialization
-const stringify = fastJson({
-  type: 'object',
-  properties: {
-    message: { type: 'string' }
-  }
-});
-// Output langsung tanpa JSON.stringify overhead
-```
-
-**Improvement untuk Nexus:**
-- Implement schema-based JSON serialization
-- Cache stringify functions per route
-- Gunakan library seperti `fast-json-stringify` atau `@msgpack/msgpack`
-
----
-
-### 2. Router Performance
-
-**Fastify** menggunakan `find-my-way`, radix tree-based router yang O(log n):
-
-```
-/users/:id → Radix tree lookup (sangat cepat)
-```
-
-**Improvement untuk Nexus:**
-- Evaluate current router implementation
-- Consider menggunakan `find-my-way` atau `trek-router`
-- Implement route caching untuk static routes
-- Pre-compile regex patterns saat startup
-
----
-
-### 3. Request/Response Object Overhead
-
-**Fastify** minimize object creation dan property access:
-
-```javascript
-// Fastify - minimal wrapper
-reply.send({ data }); // Direct write ke socket
-```
-
-**Improvement untuk Nexus:**
-- Reduce Context object properties
-- Lazy-load properties yang jarang dipakai
-- Pool dan reuse context objects
-- Avoid spread operators di hot paths
-
----
-
-### 4. Body Parsing Strategy
-
-**Fastify** parse body secara lazy dan streaming:
-
-```javascript
-// Hanya parse jika diperlukan
-fastify.addContentTypeParser('application/json', 
-  { parseAs: 'buffer' }, 
-  (req, body, done) => {
-    // Efficient buffer-based parsing
-  }
-);
-```
-
-**Improvement untuk Nexus:**
-- Implement streaming body parser
-- Add body size limits untuk prevent DoS
-- Cache parsed bodies
-- Support different content types efficiently
-
----
-
-### 5. Middleware Chain Optimization
-
-**Improvement untuk Nexus:**
-```typescript
-// Instead of array-based middleware
-// Use compiled function chain
-const compiledHandler = compileMiddleware([
-  middleware1,
-  middleware2,
-  routeHandler
-]);
-
-function compileMiddleware(middlewares) {
-  return middlewares.reduceRight(
-    (next, mw) => (ctx) => mw(ctx, next),
-    (ctx) => ctx
-  );
-}
-```
-
----
-
-### 6. HTTP Header Handling
-
-**Improvement untuk Nexus:**
-- Pre-allocate common headers
-- Use header caching
-- Minimize header parsing overhead
-
-```typescript
-// Cache static headers
-const COMMON_HEADERS = {
-  'content-type': 'application/json; charset=utf-8',
-  'x-powered-by': 'Nexus'
-};
-
-// Apply once, not per-request
-response.writeHead(200, COMMON_HEADERS);
-```
-
----
-
-## 🎯 Priority Improvements untuk Nexus
-
-### High Priority (Impact Besar)
-
-| # | Improvement | Expected Gain | Effort |
-|---|-------------|---------------|--------|
-| 1 | Fix POST body parsing | +10,000% untuk POST | Medium |
-| 2 | Schema-based JSON stringify | +15-25% | Medium |
-| 3 | Optimize router | +10-20% | High |
-
-### Medium Priority
-
-| # | Improvement | Expected Gain | Effort |
-|---|-------------|---------------|--------|
-| 4 | Query string parser optimization | +5-15% | Low |
-| 5 | Context object pooling | +5-10% | Medium |
-| 6 | Header caching | +3-5% | Low |
-
-### Low Priority (Nice to Have)
-
-| # | Improvement | Expected Gain | Effort |
-|---|-------------|---------------|--------|
-| 7 | HTTP/2 support | Varies | High |
-| 8 | Cluster mode built-in | Linear scaling | Medium |
-| 9 | Native addon for hot paths | +20-30% | Very High |
-
----
-
-## 📋 Summary
-
-### Kelebihan Nexus Saat Ini
-- ✅ Performa GET request sangat bagus (hampir setara Fastify)
-- ✅ Simple JSON response hanya 1.9% lebih lambat dari Fastify
-- ✅ Large payload handling bagus (6% gap)
-- ✅ Developer Experience yang baik
-
-### Area yang Perlu Diperbaiki
-- 🔴 **CRITICAL:** POST body parsing broken under load
-- 🟡 Query parameter parsing bisa lebih cepat (+29% gap)
-- 🟡 JSON serialization bisa di-optimize
-
-### Rekomendasi Utama
-1. **Immediate:** Fix body parsing untuk POST/PUT requests
-2. **Short-term:** Implement schema-based JSON serialization
-3. **Medium-term:** Optimize router dengan radix tree
-4. **Long-term:** Consider V8 fast-path optimizations
-
----
-
-## 🔗 Resources
-
-- [Fastify Benchmarks](https://fastify.dev/benchmarks/)
-- [fast-json-stringify](https://github.com/fastify/fast-json-stringify)
-- [find-my-way Router](https://github.com/delvedor/find-my-way)
-- [Node.js Performance Best Practices](https://nodejs.org/en/docs/guides/dont-block-the-event-loop/)
-
----
-
-*Report generated by benchmark suite on December 7, 2025*

package/documentation/01-getting-started.md

@@ -1,240 +0,0 @@
-# Getting Started with Nexus Framework
-
-## Installation
-
-### Prerequisites
-
-- Node.js >= 18.0.0
-- TypeScript >= 5.0.0
-
-### Setup
-
-1. **Clone or initialize your project**
-
-```bash
-mkdir my-nexus-app
-cd my-nexus-app
-npm init -y
-```
-
-2. **Install dependencies**
-
-```bash
-npm install typescript @types/node zod
-npm install -D ts-node
-```
-
-3. **Configure TypeScript**
-
-Create `tsconfig.json`:
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "outDir": "./dist"
-  },
-  "include": ["src/**/*"]
-}
-```
-
-## Your First Application
-
-### Basic Server
-
-Create `src/index.ts`:
-
-```typescript
-import { createApp } from './nexus';
-
-const app = createApp();
-
-app.get('/hello', async (ctx) => {
-  return { message: 'Hello, Nexus!' };
-});
-
-app.listen(3000, () => {
-  console.log('Server running on http://localhost:3000');
-});
-```
-
-### Run the Application
-
-```bash
-npx ts-node src/index.ts
-```
-
-Visit `http://localhost:3000/hello` to see your first response!
-
-## Core Concepts
-
-### 1. Unified Context
-
-Unlike Express.js which uses separate `req` and `res` objects, Nexus uses a single **Context** object:
-
-```typescript
-app.get('/user', async (ctx) => {
-  // Access request data
-  const userId = ctx.query.id;
-  const token = ctx.headers.authorization;
-  
-  // Return response (auto-converted to JSON)
-  return { userId, authenticated: !!token };
-});
-```
-
-### 2. Async-First
-
-All handlers are async functions with **automatic error handling**:
-
-```typescript
-app.get('/user/:id', async (ctx) => {
-  // Errors are automatically caught
-  const user = await database.getUser(ctx.params.id);
-  return { user };
-});
-```
-
-No need for try-catch or `next(error)` calls!
-
-### 3. Type Safety
-
-Full TypeScript support with **type inference**:
-
-```typescript
-import { z } from 'zod';
-
-app.post('/users', {
-  schema: {
-    body: z.object({
-      name: z.string(),
-      email: z.string().email()
-    })
-  },
-  handler: async (ctx) => {
-    // ctx.body is typed as { name: string, email: string }
-    const user = await createUser(ctx.body);
-    return { user };
-  }
-});
-```
-
-## HTTP Methods
-
-Nexus supports all standard HTTP methods:
-
-```typescript
-app.get('/resource', async (ctx) => { /* ... */ });
-app.post('/resource', async (ctx) => { /* ... */ });
-app.put('/resource/:id', async (ctx) => { /* ... */ });
-app.patch('/resource/:id', async (ctx) => { /* ... */ });
-app.delete('/resource/:id', async (ctx) => { /* ... */ });
-```
-
-## Response Types
-
-### JSON (Default)
-
-```typescript
-app.get('/data', async (ctx) => {
-  return { key: 'value' }; // Auto-serialized to JSON
-});
-```
-
-### HTML
-
-```typescript
-app.get('/page', async (ctx) => {
-  return ctx.html('<h1>Welcome</h1>');
-});
-```
-
-### Text
-
-```typescript
-app.get('/text', async (ctx) => {
-  return ctx.text('Plain text response');
-});
-```
-
-### Redirect
-
-```typescript
-app.get('/old', async (ctx) => {
-  return ctx.redirect('/new', 301);
-});
-```
-
-### Stream
-
-```typescript
-import { createReadStream } from 'fs';
-
-app.get('/file', async (ctx) => {
-  const stream = createReadStream('./large-file.dat');
-  return ctx.stream(stream);
-});
-```
-
-## Project Structure
-
-Recommended structure for your application:
-
-```
-my-app/
-├── src/
-│   ├── index.ts           # Application entry point
-│   ├── routes/            # Route handlers
-│   │   ├── users.ts
-│   │   └── posts.ts
-│   ├── middleware/        # Custom middleware
-│   │   └── auth.ts
-│   └── config/            # Configuration
-│       └── app.ts
-├── package.json
-└── tsconfig.json
-```
-
-## Next Steps
-
-- 📖 [Context Documentation](./02-context.md) - Learn about the Context API
-- 🛤️ [Routing Guide](./03-routing.md) - Advanced routing patterns
-- 🔌 [Middleware System](./04-middleware.md) - Create custom middleware
-- ✅ [Validation](./05-validation.md) - Schema validation with Zod
-- ⚡ [Performance](./07-performance.md) - Optimization features
-
-## Quick Reference
-
-```typescript
-import { createApp, z, logger, cors } from './nexus';
-
-const app = createApp({
-  debug: true,
-  contextPoolSize: 100
-});
-
-// Global middleware
-app.use(logger());
-app.use(cors());
-
-// Routes
-app.get('/path', handler);
-app.post('/path', { schema, handler });
-app.route({ method, path, handler, middlewares, schema });
-
-// Error handling
-app.onError((error, ctx) => {
-  return { statusCode: 500, body: 'Error' };
-});
-
-// Start server
-app.listen(3000);
-```
-
----
-
-**Need help?** Check the [API Reference](./09-api-reference.md) for detailed documentation.