exisjs 0.5.9 → 0.5.11

package/dist/docs/content/requests.mdx

@@ -0,0 +1,293 @@
+---
+nextUrl: "/docs/responses"
+nextTitle: "Responses"
+---
+
+# Requests
+
+ExisJS wraps the native Node.js `IncomingMessage` object into an `ExisRequest` instance. It abstracts away the complexities of stream parsing, multipart form processing, and header normalization, giving you a typed interface.
+
+---
+
+## 1. Body, Query, and Params
+
+The most common request properties are automatically parsed and strongly typed (especially when using the [Schema Validation](/docs/middleware#8-schema-validation) middleware).
+
+- **`req.body`**: The parsed body of the request (JSON, URL-encoded, or Multipart).
+- **`req.query`**: An object containing the URL query string parameters (e.g., `?id=123`).
+- **`req.params`**: An object containing route parameters (e.g., `/:id`).
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+export default controller({
+  updateUser: route.post('/users/:id', {
+    handle(req, res) {
+      const id = req.params.id          // "123"
+      const force = req.query.force     // "true"
+      const payload = req.body          // { email: "alice@exisjs.com" }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Post, Param, Query, Body } from 'exisjs/decorators'
+
+@Controller()
+export default class UsersController {
+  @Post('/users/:id')
+  async updateUser(
+    @Param('id') id: string,
+    @Query('force') force: string,
+    @Body() payload: any
+  ) {
+    // Variables are automatically injected
+  }
+}
+```
+
+---
+
+## 2. On-Demand Parsing
+
+To maximize performance, ExisJS does not parse the request body immediately for every route. If you aren't using the Validation middleware, you can manually trigger parsing on-demand.
+
+#### Functional Paradigm
+
+```typescript
+export default controller({
+  processData: route.post('/process', {
+    async handle(req, res) {
+      // Parses application/json
+      const data = await req.json<{ key: string }>()
+      
+      // Parses raw text (text/plain)
+      const text = await req.text()
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Post, Req } from 'exisjs/decorators'
+
+@Controller()
+export default class ProcessController {
+  @Post('/process')
+  async processData(@Req() req: any) {
+    // Parses application/json
+    const data = await req.json<{ key: string }>()
+    
+    // Parses raw text (text/plain)
+    const text = await req.text()
+  }
+}
+```
+
+---
+
+## 3. File Uploads & Form Data
+
+Handling `multipart/form-data` in Node.js can be difficult. ExisJS provides a stream parser out-of-the-box.
+
+Calling `req.formData()` returns both the standard text fields and the uploaded files. ExisJS also attaches a `.saveToDisk()` helper to every uploaded file, which automatically handles writing the buffer and generating collision-free filenames.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  uploadAvatar: route.post('/avatar', {
+    async handle(req, res) {
+      // 1. Parse the multipart form data
+      const { fields, files } = await req.formData()
+      
+      // 2. Access the file (e.g., from an input named "profile_pic")
+      const uploadedFile = files['profile_pic']
+      
+      if (uploadedFile) {
+        // 3. Save it to disk safely. Returns the absolute saved path.
+        const savedPath = await uploadedFile.saveToDisk('./uploads/avatars')
+        return { success: true, path: savedPath }
+      }
+      
+      return { success: false, error: "No file uploaded" }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, UploadedFile } from 'exisjs/decorators'
+
+@Controller()
+export default class UploadController {
+  @Post('/avatar')
+  async uploadAvatar(@UploadedFile('profile_pic') profilePic: any) {
+    if (profilePic) {
+      // Save it to disk safely. Returns the absolute saved path.
+      const savedPath = await profilePic.saveToDisk('./uploads/avatars')
+      return { success: true, path: savedPath }
+    }
+    
+    return { success: false, error: "No file uploaded" }
+  }
+}
+```
+
+#### Streaming (`streamUpload`)
+
+If you are dealing with large files and don't want to buffer *anything* in memory, ExisJS provides a direct streaming helper. It pipes the multipart chunks directly to the disk in real-time.
+
+#### Functional Paradigm
+
+```typescript
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  uploadCover: route.post('/cover', {
+    async handle(req, res) {
+      // 1. Using the method on the request object
+      // const { fields, files } = await req.streamUpload('./uploads/covers')
+
+      // 2. Or using the exported helper from exisjs/storage
+      const { streamUpload } = await import('exisjs/storage')
+      const { fields, files } = await streamUpload(req, { dest: './uploads/covers' })
+      
+      return { 
+        success: true, 
+        uploadedFiles: files.map(f => f.filename),
+        customFields: fields 
+      }
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript
+import { Controller, Post, Req } from 'exisjs/decorators'
+import { streamUpload } from 'exisjs/storage'
+
+@Controller()
+export default class UploadController {
+  @Post('/cover')
+  async uploadCover(@Req() req: any) {
+    // Both req.streamUpload() and the exported helper from exisjs/storage work.
+    const { fields, files } = await streamUpload(req, { dest: './uploads/covers' })
+    
+    return { 
+      success: true, 
+      uploadedFiles: files.map(f => f.filename),
+      customFields: fields 
+    }
+  }
+}
+```
+
+---
+
+## 4. HTTP Headers & Content Negotiation
+
+```typescript
+// Get a specific header (case-insensitive)
+const authHeader = req.get('Authorization')
+// or
+const authHeader = req.header('authorization')
+
+// Check the Content-Type
+if (req.is('application/json')) { ... }
+
+// Content Negotiation (returns the best match)
+const format = req.accepts('html', 'json', 'text')
+const language = req.acceptsLanguages('en', 'es', 'fr')
+```
+
+---
+
+## 5. Network Information
+
+ExisJS handles trust-proxies. If you are behind Cloudflare, Nginx, or an AWS Load Balancer, simply set `trustProxy: true` in your `exis()` config, and these properties will automatically resolve the true client IP from `X-Forwarded-For`.
+
+- **`req.ip`**: The client's IP address.
+- **`req.ips`**: An array of IPs if multiple proxies were traversed.
+- **`req.hostname`**: The resolved hostname (from `Host` or `X-Forwarded-Host`).
+- **`req.protocol`**: Returns `'http'` or `'https'`.
+- **`req.secure`**: A boolean (true if `req.protocol === 'https'`).
+
+---
+
+## 6. Context & Metadata
+
+As your request moves through ExisJS Middlewares, various properties are attached to `req` for your convenience:
+
+- **`req.log`**: A request-scoped instance of the Pino logger (via `requestLogger`).
+- **`req.requestId`**: The unique Trace ID (via `requestId`).
+- **`req.user`**: The authenticated user payload (via `JWT` auth middleware).
+- **`req.session`**: The stateful session object (via `session` middleware).
+- **`req.fresh`**: Returns `true` if the client's cache is still valid (ETag match), meaning you can send a 304 response.
+
+### Inline Context Typing (Per-Route)
+
+If you don't want to create a globally typed router with `createRouter`, ExisJS natively types `req.user` as `any` by default so you never get annoying compiler errors (e.g. `req.user.userId` just works!). 
+
+However, if you want **strict** type safety on a specific route without global configuration, you can pass your custom context directly to the route's 4th generic parameter:
+
+```typescript
+import { route } from "exisjs/router";
+
+export default route.get<any, any, any, { user: { userId: string } }>("/", {
+  async handle({ req }) {
+    // Typed. No "as any" needed.
+    const id = req.user.userId; 
+  }
+})
+```
+
+### Strongly-Typed Context & Native Destructuring (App-Wide)
+
+To provide a better developer experience, ExisJS allows you to define a **custom typed context** for your application. This completely eliminates the need for global `.d.ts` augmentations and `as any` casts.
+
+To do this, create a custom router factory (e.g., `src/http/router.ts`) and define the exact shape of your application's context (like the user object, workspace, tenant ID, etc).
+
+```typescript filename="src/http/router.ts"
+import { createRouter } from "exisjs/router";
+
+// 1. Define everything your middlewares will attach to the request
+interface AppContext {
+  user: { id: string; role: string };
+  workspace: string;
+}
+
+// 2. Export a custom typed route and controller
+export const { route, controller } = createRouter<AppContext>();
+```
+
+Now, instead of importing from `exisjs/router`, import from your **local** router. Your handlers can natively destructure your custom properties.
+
+```typescript filename="src/http/users/route.ts"
+import { route, controller } from "../../router.ts";
+
+export default controller({
+  getProfile: route.get("/", {
+    async handle({ user, workspace }) {
+      // Strongly typed. 
+      // No more `req.user`, no more `as any`.
+      console.log(user.role, workspace);
+    }
+  })
+});
+```
+
+<Warning>
+**Important Middleware Rule:** In order for destructuring to work (e.g. `handle({ user })`), the `user` property MUST be populated **before** the handler executes. This means you must populate it inside a `middleware` instead of calling an inline function inside the handler.
+</Warning>

package/dist/docs/content/responses.mdx

@@ -0,0 +1,271 @@
+---
+nextUrl: "/docs/prisma"
+nextTitle: "Prisma Integration"
+---
+
+# Responses
+
+Unlike standard Node.js `ServerResponse` objects, ExisJS wraps every response in an `ExisResponse` class. It provides a chainable API while maintaining the raw performance of native Node.
+
+While ExisJS routes allow you to simply `return { data: ... }` (which automatically serializes to JSON), the `res` object gives you granular control over headers, cookies, streams, and file downloads.
+
+---
+
+## 1. Returning Data vs Sending Data
+
+The most common way to respond to a request in ExisJS is to simply **return an object or array**. ExisJS intercepts the return value, automatically serializes it to JSON, sets the `Content-Type`, calculates the `Content-Length`, and sends it down the wire.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  getUsers: route.get('/', {
+    handle(req, res) {
+      // ExisJS automatically handles JSON serialization
+      return [{ id: 1, name: "Alice" }] 
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  async getUsers() {
+    // ExisJS automatically handles JSON serialization
+    return [{ id: 1, name: "Alice" }] 
+  }
+}
+```
+
+However, you can completely bypass this and use the `res` object manually:
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+export default controller({
+  getUsers: route.get('/', {
+    handle(req, res) {
+      // Chainable response API
+      res.status(201).json([{ id: 1, name: "Alice" }])
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Get, Res } from 'exisjs/decorators'
+
+@Controller()
+export default class UsersController {
+  @Get('/')
+  async getUsers(@Res() res: any) {
+    // Chainable response API
+    res.status(201).json([{ id: 1, name: "Alice" }])
+  }
+}
+```
+
+---
+
+## 2. Standardized JSON Responses (`exisjs/response`)
+
+To keep your APIs consistent, ExisJS exports standard `success()` and `error()` builders. 
+Using these ensures your entire application adheres to a unified `{ success: boolean, data?: any, error?: any }` structure, which frontend teams love.
+
+#### Functional Paradigm
+
+```typescript filename="src/http/route.ts"
+import { controller, route } from 'exisjs/router'
+import { success, error } from 'exisjs/response'
+
+export default controller({
+  getUser: route.get('/:id', {
+    handle(req, res) {
+      const user = db.users.find(req.params.id)
+      
+      if (!user) {
+        res.status(404)
+        // Generates: { success: false, error: { message: "User not found", code: "NOT_FOUND" } }
+        return error("User not found", "NOT_FOUND")
+      }
+      
+      // Generates: { success: true, data: { id: 1, name: "Alice" }, message: "Found user" }
+      return success(user, "Found user")
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript filename="src/http/route.ts"
+import { Controller, Get, Param, Res } from 'exisjs/decorators'
+import { success, error } from 'exisjs/response'
+
+@Controller()
+export default class UsersController {
+  @Get('/:id')
+  async getUser(@Param('id') id: string, @Res() res: any) {
+    const user = db.users.find(id)
+    
+    if (!user) {
+      res.status(404)
+      // Generates: { success: false, error: { message: "User not found", code: "NOT_FOUND" } }
+      return error("User not found", "NOT_FOUND")
+    }
+    
+    // Generates: { success: true, data: { id: 1, name: "Alice" }, message: "Found user" }
+    return success(user, "Found user")
+  }
+}
+```
+
+---
+
+## 3. Setting Headers & Status
+
+The `ExisResponse` object implements a chainable API for HTTP headers and status codes.
+
+```typescript
+res.status(404)
+   .set('X-Custom-Header', 'exis-is-awesome')
+   .append('Set-Cookie', 'foo=bar')
+   .json({ error: 'Not Found' })
+```
+
+### Supported Header Methods
+- `res.status(code)`: Sets the HTTP status code.
+- `res.set(key, value)` (or `res.header()`): Sets an HTTP header.
+- `res.append(key, value)`: Appends to an existing header (e.g., multiple `Set-Cookie` directives).
+- `res.removeHeader(key)`: Deletes a header.
+- `res.type(mimeType)`: A shorthand for setting the `Content-Type` header (e.g., `res.type('html')` becomes `text/html`).
+- `res.vary(field)`: Adds a field to the `Vary` header for caching.
+
+---
+
+## 3. Cookies
+
+ExisJS provides native helper methods for setting and clearing cookies safely.
+
+```typescript
+// Set a secure, HTTP-only cookie
+res.cookie('session_id', '123456', {
+  maxAge: 86400, // 1 day in seconds
+  httpOnly: true,
+  secure: true,
+  sameSite: 'Strict'
+})
+
+// Clear a cookie
+res.clearCookie('session_id')
+```
+
+---
+
+## 4. File Downloads & Streaming
+
+ExisJS makes streaming files simple, bypassing V8 memory bottlenecks by piping native Node streams directly to the socket.
+
+### `res.download()`
+Automatically reads a file from disk, sets the `Content-Disposition` header to force a download in the browser, and infers the correct MIME type based on the file extension.
+
+#### Functional Paradigm
+
+```typescript
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  downloadReport: route.get('/report', {
+    handle(req, res) {
+      res.download('/absolute/path/to/report.pdf', 'Q4-Report.pdf')
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript
+import { Controller, Get, Res } from 'exisjs/decorators'
+
+@Controller()
+export default class ReportController {
+  @Get('/report')
+  async downloadReport(@Res() res: any) {
+    res.download('/absolute/path/to/report.pdf', 'Q4-Report.pdf')
+  }
+}
+```
+
+### `res.sendStream()`
+If you are fetching data from an external source (like AWS S3) or generating data on the fly, you can pipe any `ReadableStream` directly to the client.
+
+#### Functional Paradigm
+
+```typescript
+import { controller, route } from 'exisjs/router'
+import fs from 'node:fs'
+
+export default controller({
+  streamVideo: route.get('/video', {
+    handle(req, res) {
+      const videoStream = fs.createReadStream('/path/to/video.mp4')
+      
+      res.type('video/mp4')
+      res.sendStream(videoStream)
+    }
+  })
+})
+```
+
+#### Class-Based (OOP) Paradigm
+
+```typescript
+import { Controller, Get, Res } from 'exisjs/decorators'
+import fs from 'node:fs'
+
+@Controller()
+export default class VideoController {
+  @Get('/video')
+  async streamVideo(@Res() res: any) {
+    const videoStream = fs.createReadStream('/path/to/video.mp4')
+    
+    res.type('video/mp4')
+    res.sendStream(videoStream)
+  }
+}
+```
+
+---
+
+## 5. Redirects
+
+You can instantly redirect users to another URL using `res.redirect()`. It defaults to a `302 Found` temporary redirect, but you can override the status code.
+
+```typescript
+// Temporary Redirect (302)
+res.redirect('/login')
+
+// Permanent Redirect (301)
+res.redirect('https://google.com', 301)
+```
+
+---
+
+## 6. ETags & Conditional Requests (304 Not Modified)
+
+ExisJS features native, automatic ETag generation. 
+
+If the client sends an `If-None-Match` header matching the ETag of the current response, ExisJS will immediately abort serialization and send a `304 Not Modified` header with an empty body, saving bandwidth and CPU cycles.
+
+*Note: ETag generation is disabled by default, but can be enabled globally in your `exis()` config, or manually per-route via `res.etagEnabled = true`.*