@engjts/nexus 0.1.7 → 0.1.9

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.

package/documentation/02-context.md

@@ -1,335 +0,0 @@
-# Context API
-
-## Overview
-
-The **Context** is the heart of Nexus Framework. It replaces the traditional `req` and `res` pattern with a single, unified, immutable object that contains all request and response data.
-
-## Why Context?
-
-### Traditional Express.js
-```javascript
-app.get('/user/:id', (req, res) => {
-  const id = req.params.id;
-  const user = getUser(id);
-  res.json({ user });
-});
-```
-
-### Nexus Framework
-```typescript
-app.get('/user/:id', async (ctx) => {
-  const user = await getUser(ctx.params.id);
-  return { user }; // Auto-converted to JSON
-});
-```
-
-**Benefits:**
-- ✅ Single source of truth
-- ✅ Immutability enables better testing
-- ✅ Type inference works naturally
-- ✅ Easier to extend with custom properties
-
-## Context Properties
-
-### Request Data
-
-#### `ctx.method`
-HTTP method of the request.
-
-```typescript
-app.get('/info', async (ctx) => {
-  return { method: ctx.method }; // "GET"
-});
-```
-
-#### `ctx.path`
-Path of the request (without query string).
-
-```typescript
-app.get('/api/users', async (ctx) => {
-  return { path: ctx.path }; // "/api/users"
-});
-```
-
-#### `ctx.url`
-Full URL object.
-
-```typescript
-app.get('/info', async (ctx) => {
-  return {
-    host: ctx.url.host,
-    protocol: ctx.url.protocol
-  };
-});
-```
-
-#### `ctx.params`
-Route parameters extracted from the path.
-
-```typescript
-app.get('/users/:id/posts/:postId', async (ctx) => {
-  const { id, postId } = ctx.params;
-  return { userId: id, postId };
-});
-```
-
-#### `ctx.query`
-Query string parameters.
-
-```typescript
-// GET /search?q=nexus&limit=10
-app.get('/search', async (ctx) => {
-  const { q, limit } = ctx.query;
-  return { query: q, limit: parseInt(limit) };
-});
-```
-
-#### `ctx.body`
-Parsed request body (POST, PUT, PATCH).
-
-```typescript
-app.post('/users', async (ctx) => {
-  const { name, email } = ctx.body;
-  return { received: { name, email } };
-});
-```
-
-**Automatic parsing for:**
-- `application/json`
-- `application/x-www-form-urlencoded`
-- `text/*`
-
-#### `ctx.headers`
-Request headers.
-
-```typescript
-app.get('/auth', async (ctx) => {
-  const token = ctx.headers.authorization;
-  const userAgent = ctx.headers['user-agent'];
-  return { token, userAgent };
-});
-```
-
-#### `ctx.cookies`
-Cookie management.
-
-```typescript
-app.get('/profile', async (ctx) => {
-  // Get cookie
-  const sessionId = ctx.cookies.get('session');
-  
-  // Set cookie
-  ctx.cookies.set('visited', 'true', {
-    maxAge: 86400, // 1 day in seconds
-    httpOnly: true,
-    secure: true,
-    sameSite: 'strict'
-  });
-  
-  // Delete cookie
-  ctx.cookies.delete('old-cookie');
-  
-  return { sessionId };
-});
-```
-
-## Response Methods
-
-### `ctx.json(data)`
-Return JSON response.
-
-```typescript
-app.get('/user', async (ctx) => {
-  return ctx.json({ 
-    name: 'John',
-    email: 'john@example.com'
-  });
-});
-
-// Or simply return the object (auto-converted)
-app.get('/user', async (ctx) => {
-  return { name: 'John', email: 'john@example.com' };
-});
-```
-
-### `ctx.html(content)`
-Return HTML response.
-
-```typescript
-app.get('/page', async (ctx) => {
-  return ctx.html(`
-    <!DOCTYPE html>
-    <html>
-      <head><title>My Page</title></head>
-      <body><h1>Welcome!</h1></body>
-    </html>
-  `);
-});
-```
-
-### `ctx.text(content)`
-Return plain text response.
-
-```typescript
-app.get('/robots.txt', async (ctx) => {
-  return ctx.text('User-agent: *\nDisallow: /admin/');
-});
-```
-
-### `ctx.redirect(url, status?)`
-Redirect to another URL.
-
-```typescript
-app.get('/old-page', async (ctx) => {
-  return ctx.redirect('/new-page', 301); // Permanent redirect
-});
-
-app.get('/login', async (ctx) => {
-  return ctx.redirect('/auth/login'); // Default 302
-});
-```
-
-### `ctx.stream(readable)`
-Stream a response (for large files).
-
-```typescript
-import { createReadStream } from 'fs';
-
-app.get('/download', async (ctx) => {
-  const stream = createReadStream('./large-file.zip');
-  return ctx.stream(stream);
-});
-```
-
-## Response Builder
-
-Use the response builder for custom status codes and headers:
-
-```typescript
-app.get('/custom', async (ctx) => {
-  return ctx.response
-    .status(201)
-    .header('X-Custom-Header', 'value')
-    .json({ created: true });
-});
-```
-
-## Raw Node.js Objects
-
-Access raw Node.js objects when needed:
-
-```typescript
-app.get('/raw', async (ctx) => {
-  // Access raw request
-  const req = ctx.raw.req;
-  const contentLength = req.headers['content-length'];
-  
-  // Access raw response
-  const res = ctx.raw.res;
-  res.setHeader('X-Custom', 'value');
-  
-  return { contentLength };
-});
-```
-
-## Custom Context Properties
-
-Middleware can add custom properties to the context:
-
-```typescript
-// Middleware adds user
-const auth = async (ctx: any, next: any) => {
-  ctx.user = await authenticateUser(ctx.headers.authorization);
-  return next(ctx);
-};
-
-app.get('/profile', {
-  middlewares: [auth],
-  handler: async (ctx: any) => {
-    // ctx.user is now available
-    return { user: ctx.user };
-  }
-});
-```
-
-For type-safe custom properties, see [Middleware Documentation](./04-middleware.md).
-
-## Context Pooling
-
-Nexus automatically pools context objects for performance. You don't need to do anything - it's built-in!
-
-**Performance benefit:** ~60-80% reduction in object allocations.
-
-```typescript
-// Get pool statistics
-const app = createApp();
-// ... after some requests
-const stats = app.getPoolStats();
-console.log(stats);
-// {
-//   poolSize: 50,
-//   maxSize: 100,
-//   created: 150,
-//   reused: 100,
-//   hitRate: 0.67
-// }
-```
-
-## Best Practices
-
-### ✅ DO: Return data directly
-
-```typescript
-app.get('/users', async (ctx) => {
-  const users = await getUsers();
-  return { users };
-});
-```
-
-### ❌ DON'T: Mutate the context
-
-```typescript
-// BAD - context is immutable
-app.get('/bad', async (ctx) => {
-  ctx.path = '/new-path'; // Won't work!
-});
-```
-
-### ✅ DO: Use typed custom properties
-
-```typescript
-interface AuthContext extends Context {
-  user: User;
-}
-
-const handler = async (ctx: AuthContext) => {
-  return { userId: ctx.user.id }; // Type-safe!
-};
-```
-
-### ✅ DO: Use cookies for session management
-
-```typescript
-app.post('/login', async (ctx) => {
-  const user = await authenticate(ctx.body);
-  
-  ctx.cookies.set('session', user.sessionId, {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'strict',
-    maxAge: 86400
-  });
-  
-  return { success: true };
-});
-```
-
-## Next Steps
-
-- 🛤️ [Routing Guide](./03-routing.md) - Learn about routing
-- 🔌 [Middleware](./04-middleware.md) - Extend context with middleware
-- ✅ [Validation](./05-validation.md) - Validate context data
-
----
-
-[← Getting Started](./01-getting-started.md) | [API Reference →](./09-api-reference.md)