@engjts/nexus 0.1.0

package/documentation/28-lifecycle-hooks.md

@@ -0,0 +1,521 @@
+# Lifecycle Hooks
+
+Nexus Framework menyediakan sistem **Lifecycle Hooks** untuk intercept dan memodifikasi request/response di berbagai tahap request lifecycle.
+
+## Quick Start
+
+```typescript
+import { createApp } from 'nexus';
+
+const app = createApp();
+
+app.hooks({
+    onRequest: async (ctx) => {
+        ctx.requestId = crypto.randomUUID();
+        console.log(`[${ctx.requestId}] ${ctx.method} ${ctx.path}`);
+    },
+    
+    afterHandler: async (ctx, result) => {
+        return {
+            ...result,
+            meta: { requestId: ctx.requestId, timestamp: Date.now() }
+        };
+    },
+    
+    onError: async (ctx, error) => {
+        console.error(`[${ctx.requestId}] Error:`, error.message);
+        // Log to Sentry, etc.
+    }
+});
+```
+
+## Hook Lifecycle Order
+
+```
+Request masuk
+     │
+     ▼
+┌─────────────────┐
+│   onRequest     │  ← Request received, sebelum processing
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ beforeValidation│  ← Sebelum schema validation
+└────────┬────────┘
+         │
+         ▼
+    [Validation]     ← Schema validation (jika ada)
+         │
+         ▼
+┌─────────────────┐
+│ afterValidation │  ← Setelah validation sukses
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│  beforeHandler  │  ← Sebelum handler dijalankan
+└────────┬────────┘
+         │
+         ▼
+    [Handler]        ← Route handler execution
+         │
+         ▼
+┌─────────────────┐
+│  afterHandler   │  ← Setelah handler, bisa transform result
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│   onResponse    │  ← Sebelum response dikirim
+└────────┬────────┘
+         │
+         ▼
+   Response sent
+
+
+     [Error?]
+         │
+         ▼
+┌─────────────────┐
+│    onError      │  ← Ketika error terjadi
+└─────────────────┘
+```
+
+## API Reference
+
+### `app.hooks(hooks)`
+
+Register lifecycle hooks untuk request processing.
+
+```typescript
+interface LifecycleHooks {
+    onRequest?: (ctx: Context) => Promise<void | Response>;
+    beforeValidation?: (ctx: Context) => Promise<void | Response>;
+    afterValidation?: (ctx: Context) => Promise<void | Response>;
+    beforeHandler?: (ctx: Context) => Promise<void | Response>;
+    afterHandler?: (ctx: Context, result: any) => Promise<any>;
+    onError?: (ctx: Context, error: Error) => Promise<void | Response>;
+    onResponse?: (ctx: Context, response: Response) => Promise<void | Response>;
+}
+
+app.hooks(hooks: LifecycleHooks): Application
+```
+
+**Returns:** `Application` (chainable)
+
+## Hook Details
+
+### 1. `onRequest`
+
+Dipanggil pertama kali ketika request masuk, sebelum processing apapun.
+
+**Use cases:**
+- Generate request ID
+- Start timing/profiling
+- Early request logging
+- Rate limiting check
+
+```typescript
+app.hooks({
+    onRequest: async (ctx) => {
+        ctx.requestId = crypto.randomUUID();
+        ctx.startTime = Date.now();
+        console.log(`🚀 [${ctx.requestId}] ${ctx.method} ${ctx.path}`);
+        
+        // Early return untuk block request
+        if (isBlacklisted(ctx.headers['x-forwarded-for'])) {
+            return ctx.response.status(403).json({ error: 'Forbidden' });
+        }
+    }
+});
+```
+
+### 2. `beforeValidation`
+
+Dipanggil sebelum schema validation. Berguna untuk transform body sebelum divalidasi.
+
+**Use cases:**
+- Unwrap nested body
+- Normalize input data
+- Add default values
+
+```typescript
+app.hooks({
+    beforeValidation: async (ctx) => {
+        // Unwrap jika body dibungkus dalam "data"
+        if (ctx.body?.data) {
+            ctx.body = ctx.body.data;
+        }
+        
+        // Normalize email ke lowercase
+        if (ctx.body?.email) {
+            ctx.body.email = ctx.body.email.toLowerCase().trim();
+        }
+    }
+});
+```
+
+### 3. `afterValidation`
+
+Dipanggil setelah validation sukses. Body sudah tervalidasi dan aman digunakan.
+
+**Use cases:**
+- Authorization check
+- Load related data
+- Business rule validation
+
+```typescript
+app.hooks({
+    afterValidation: async (ctx) => {
+        // Check authorization untuk admin routes
+        if (ctx.path.startsWith('/admin')) {
+            const token = ctx.headers.authorization?.replace('Bearer ', '');
+            if (!token || !isAdmin(token)) {
+                return ctx.response.status(401).json({ error: 'Unauthorized' });
+            }
+        }
+    }
+});
+```
+
+### 4. `beforeHandler`
+
+Dipanggil tepat sebelum route handler dijalankan.
+
+**Use cases:**
+- Load user dari token
+- Set up request context
+- Pre-load data
+
+```typescript
+app.hooks({
+    beforeHandler: async (ctx) => {
+        const token = ctx.headers.authorization?.replace('Bearer ', '');
+        if (token) {
+            ctx.user = await getUserFromToken(token);
+        }
+        
+        // Load tenant untuk multi-tenant app
+        const tenantId = ctx.headers['x-tenant-id'];
+        if (tenantId) {
+            ctx.tenant = await loadTenant(tenantId);
+        }
+    }
+});
+```
+
+### 5. `afterHandler`
+
+Dipanggil setelah handler sukses. **Bisa transform/modify result.**
+
+**Use cases:**
+- Add metadata ke response
+- Transform response format
+- Add pagination info
+- Logging response
+
+```typescript
+app.hooks({
+    afterHandler: async (ctx, result) => {
+        const duration = Date.now() - ctx.startTime;
+        
+        // Add metadata ke semua response
+        return {
+            ...result,
+            meta: {
+                requestId: ctx.requestId,
+                duration: `${duration}ms`,
+                timestamp: new Date().toISOString(),
+                version: 'v1'
+            }
+        };
+    }
+});
+```
+
+### 6. `onError`
+
+Dipanggil ketika error terjadi di manapun dalam request lifecycle.
+
+**Use cases:**
+- Error logging ke external service
+- Custom error response
+- Alert/notification
+
+```typescript
+app.hooks({
+    onError: async (ctx, error) => {
+        // Log ke Sentry
+        await sentry.captureException(error, {
+            extra: {
+                requestId: ctx.requestId,
+                path: ctx.path,
+                method: ctx.method,
+                body: ctx.body
+            }
+        });
+        
+        // Slack notification untuk critical errors
+        if (error.message.includes('database')) {
+            await slack.notify(`🚨 Database error: ${error.message}`);
+        }
+        
+        // Return custom error response
+        return ctx.response.status(500).json({
+            error: 'Something went wrong',
+            requestId: ctx.requestId,
+            support: 'Please contact support with this requestId'
+        });
+    }
+});
+```
+
+### 7. `onResponse`
+
+Dipanggil sebelum response dikirim ke client. Bisa modify final response.
+
+**Use cases:**
+- Final logging
+- Add security headers
+- Response timing
+
+```typescript
+app.hooks({
+    onResponse: async (ctx, response) => {
+        const duration = Date.now() - ctx.startTime;
+        
+        console.log(
+            `✨ [${ctx.requestId}] ${ctx.method} ${ctx.path} → ${response.statusCode} (${duration}ms)`
+        );
+        
+        // Add security headers
+        response.headers['X-Request-ID'] = ctx.requestId;
+        response.headers['X-Response-Time'] = `${duration}ms`;
+    }
+});
+```
+
+## Complete Example
+
+```typescript
+import { createApp } from 'nexus';
+
+const app = createApp({ debug: true });
+
+// Generate unique request ID
+const generateRequestId = () => Math.random().toString(36).substring(2, 10);
+
+// Register all hooks
+app.hooks({
+    // 1. Request received
+    onRequest: async (ctx) => {
+        ctx.requestId = generateRequestId();
+        ctx.startTime = Date.now();
+        console.log(`\n🚀 [${ctx.requestId}] ${ctx.method} ${ctx.path}`);
+    },
+
+    // 2. Before validation
+    beforeValidation: async (ctx) => {
+        console.log(`   📋 [${ctx.requestId}] Before validation`);
+        
+        // Transform wrapped body
+        if (ctx.body?.wrapped) {
+            ctx.body = ctx.body.wrapped;
+        }
+    },
+
+    // 3. After validation
+    afterValidation: async (ctx) => {
+        console.log(`   ✅ [${ctx.requestId}] Validation passed`);
+        
+        // Authorization check
+        if (ctx.path.startsWith('/admin') && !ctx.headers.authorization) {
+            return ctx.response.status(401).json({ error: 'Unauthorized' });
+        }
+    },
+
+    // 4. Before handler
+    beforeHandler: async (ctx) => {
+        console.log(`   ⚡ [${ctx.requestId}] Before handler`);
+        
+        // Load user from token
+        const token = ctx.headers.authorization?.replace('Bearer ', '');
+        if (token) {
+            ctx.user = { id: 1, name: 'John' }; // await getUserFromToken(token)
+        }
+    },
+
+    // 5. After handler - transform result
+    afterHandler: async (ctx, result) => {
+        const duration = Date.now() - ctx.startTime;
+        console.log(`   📦 [${ctx.requestId}] Handler completed (${duration}ms)`);
+        
+        // Add metadata to all responses
+        return {
+            ...result,
+            meta: {
+                requestId: ctx.requestId,
+                duration: `${duration}ms`,
+                timestamp: new Date().toISOString()
+            }
+        };
+    },
+
+    // 6. Error handling
+    onError: async (ctx, error) => {
+        console.error(`   ❌ [${ctx.requestId}] Error:`, error.message);
+        
+        // Log to external service
+        // await sentry.captureException(error);
+    },
+
+    // 7. Before response sent
+    onResponse: async (ctx, response) => {
+        const duration = Date.now() - ctx.startTime;
+        console.log(`   ✨ [${ctx.requestId}] Response: ${response.statusCode} (${duration}ms)\n`);
+    }
+});
+
+// Routes
+app.get('/hello', async (ctx) => {
+    return { message: 'Hello World!' };
+});
+
+app.get('/error', async (ctx) => {
+    throw new Error('Something went wrong!');
+});
+
+app.listen(3000);
+```
+
+**Output di terminal:**
+```
+🚀 [abc123] GET /hello
+   📋 [abc123] Before validation
+   ✅ [abc123] Validation passed
+   ⚡ [abc123] Before handler
+   📦 [abc123] Handler completed (1ms)
+   ✨ [abc123] Response: 200 (2ms)
+```
+
+**Response:**
+```json
+{
+    "message": "Hello World!",
+    "meta": {
+        "requestId": "abc123",
+        "duration": "1ms",
+        "timestamp": "2025-12-04T10:30:00.000Z"
+    }
+}
+```
+
+## Early Return
+
+Semua hooks (kecuali `afterHandler`) bisa return `Response` untuk short-circuit request:
+
+```typescript
+app.hooks({
+    onRequest: async (ctx) => {
+        // Rate limit check
+        if (await isRateLimited(ctx.ip)) {
+            return ctx.response.status(429).json({ 
+                error: 'Too many requests' 
+            });
+        }
+    },
+    
+    afterValidation: async (ctx) => {
+        // Business rule check
+        if (ctx.body.amount > 10000 && !ctx.user.verified) {
+            return ctx.response.status(403).json({ 
+                error: 'Verify your account for large transactions' 
+            });
+        }
+    }
+});
+```
+
+## Combining with Middleware
+
+Hooks dan middleware bekerja bersama:
+
+```
+Request → onRequest → [Middleware Chain] → beforeValidation → ... → Handler
+```
+
+```typescript
+import { logger, cors } from 'nexus';
+
+const app = createApp();
+
+// Global middleware (runs after onRequest)
+app.use(logger());
+app.use(cors());
+
+// Hooks
+app.hooks({
+    onRequest: async (ctx) => {
+        // Runs BEFORE middleware
+        ctx.requestId = generateId();
+    },
+    beforeHandler: async (ctx) => {
+        // Runs AFTER middleware, before handler
+        ctx.user = await loadUser(ctx);
+    }
+});
+```
+
+## Use Cases
+
+### Request Tracing
+```typescript
+app.hooks({
+    onRequest: async (ctx) => {
+        ctx.traceId = ctx.headers['x-trace-id'] || generateTraceId();
+        ctx.spanId = generateSpanId();
+    },
+    onResponse: async (ctx, response) => {
+        response.headers['X-Trace-ID'] = ctx.traceId;
+        response.headers['X-Span-ID'] = ctx.spanId;
+    }
+});
+```
+
+### Performance Monitoring
+```typescript
+app.hooks({
+    onRequest: async (ctx) => {
+        ctx.metrics = { start: process.hrtime.bigint() };
+    },
+    onResponse: async (ctx, response) => {
+        const duration = Number(process.hrtime.bigint() - ctx.metrics.start) / 1e6;
+        await prometheus.histogram('http_request_duration_ms', duration, {
+            method: ctx.method,
+            path: ctx.path,
+            status: response.statusCode
+        });
+    }
+});
+```
+
+### Multi-tenant
+```typescript
+app.hooks({
+    onRequest: async (ctx) => {
+        const tenantId = ctx.headers['x-tenant-id'] || ctx.query.tenant;
+        if (!tenantId) {
+            return ctx.response.status(400).json({ error: 'Tenant ID required' });
+        }
+        ctx.tenant = await loadTenant(tenantId);
+        ctx.db = getTenantDatabase(tenantId);
+    }
+});
+```
+
+## See Also
+
+- [Dependency Injection](./27-dependency-injection.md) - Inject services ke handlers
+- [Middleware](./04-middleware.md) - Middleware system
+- [Error Handling](./06-error-handling.md) - Error handling patterns

package/documentation/29-package-structure.md

@@ -0,0 +1,196 @@
+# Nexus Framework - Package Structure
+
+Nexus Framework mendukung tree-shaking dan optional imports melalui subpath exports.
+
+## Quick Start
+
+```typescript
+// Full framework (includes all features)
+import { Application, Router, createApp } from '@engjts/server';
+
+// Core only (minimal, no optional deps)
+import { Application, Router, createApp } from '@engjts/server/core';
+```
+
+## Available Subpath Imports
+
+### Core (No Optional Dependencies)
+```typescript
+import { 
+    Application, 
+    createApp, 
+    Router,
+    MiddlewareExecutor,
+    ContextStore,
+    RequestStore,
+    // Plugin System
+    definePlugin,
+    createPlugin,
+    PluginManager
+} from '@engjts/server/core';
+```
+
+### Database
+```typescript
+import { 
+    Database, 
+    QueryBuilder, 
+    Schema, 
+    Migration 
+} from '@engjts/server/database';
+```
+
+### GraphQL (requires `graphql` peer dependency)
+```typescript
+// npm install graphql
+import { 
+    GraphQLServer, 
+    SimpleDataLoader 
+} from '@engjts/server/graphql';
+```
+
+### Cache
+```typescript
+import { 
+    MultiTierCache, 
+    InMemoryCacheStore,
+    RedisCacheStore  // requires ioredis
+} from '@engjts/server/cache';
+```
+
+### Jobs (Background Processing)
+```typescript
+import { 
+    JobQueue, 
+    InMemoryQueueStore,
+    RedisQueueStore  // requires ioredis
+} from '@engjts/server/jobs';
+```
+
+### Sentry (Error Tracking & APM)
+```typescript
+import { 
+    SentryClient, 
+    initSentry, 
+    captureException 
+} from '@engjts/server/sentry';
+```
+
+### Realtime (WebSocket) (requires `ws` peer dependency)
+```typescript
+// npm install ws
+import { 
+    WebSocketGateway 
+} from '@engjts/server/realtime';
+```
+
+### Testing
+```typescript
+import { 
+    TestClient, 
+    Factory, 
+    MockFn, 
+    MockDatabase,
+    NexusTestRunner 
+} from '@engjts/server/testing';
+```
+
+### Security
+```typescript
+import { 
+    RateLimiter, 
+    CSRFProtection, 
+    JWTAuth,
+    SecurityHeaders 
+} from '@engjts/server/security';
+```
+
+### Deployment
+```typescript
+import { 
+    GracefulShutdownManager, 
+    ClusterManager, 
+    ConfigManager,
+    DockerGenerator 
+} from '@engjts/server/deployment';
+```
+
+### API Documentation
+
+```typescript
+// Swagger
+import { swagger, SwaggerGenerator } from '@engjts/server/swagger';
+
+// Postman
+import { postman } from '@engjts/server/postman';
+
+// Playground
+import { playground } from '@engjts/server/playground';
+```
+
+## Peer Dependencies
+
+These dependencies are optional and only needed if you use specific features:
+
+| Package | Required For |
+|---------|-------------|
+| `graphql` | GraphQL module |
+| `ws` | WebSocket/Realtime module |
+| `ioredis` | Redis cache & job queue stores |
+
+## Installation Examples
+
+### Minimal (Core Only)
+```bash
+npm install @engjts/server
+```
+
+### With GraphQL
+```bash
+npm install @engjts/server graphql
+```
+
+### With WebSocket
+```bash
+npm install @engjts/server ws
+```
+
+### With Redis Support
+```bash
+npm install @engjts/server ioredis
+```
+
+### Full Installation (All Optional Features)
+```bash
+npm install @engjts/server graphql ws ioredis
+```
+
+## Bundle Size Optimization
+
+By using subpath imports, you can significantly reduce bundle size:
+
+```typescript
+// ❌ Imports everything (larger bundle)
+import { Application, GraphQLServer, WebSocketGateway } from '@engjts/server';
+
+// ✅ Tree-shakeable imports (smaller bundle)
+import { Application } from '@engjts/server/core';
+import { GraphQLServer } from '@engjts/server/graphql';
+import { WebSocketGateway } from '@engjts/server/realtime';
+```
+
+## Migration from Single Import
+
+If you were previously using:
+```typescript
+import { Application, Database, GraphQLServer } from '@engjts/server';
+```
+
+You can either:
+1. Keep using it (backwards compatible)
+2. Or switch to subpath imports for better tree-shaking:
+```typescript
+import { Application } from '@engjts/server/core';
+import { Database } from '@engjts/server/database';
+import { GraphQLServer } from '@engjts/server/graphql';
+```