exisjs 0.5.10 → 0.5.12

package/dist/docs/reference/router.mdx

@@ -0,0 +1,248 @@
+---
+title: "Router & Controllers"
+description: "API Reference for defining routes and controllers in ExisJS."
+---
+
+# Router & Controllers
+
+ExisJS provides two distinct ways to build your API: **Functional Routing** (using `route` and `controller`) and **Class-Based Routing** (using standard decorators). You can use either paradigm, or even mix both in the same application.
+
+---
+
+## 1. Functional Routing
+
+The functional router provides a lightweight, type-safe API via the `route` and `controller` exports from `exisjs/router`. 
+
+These utilities allow you to define HTTP endpoints with built-in validation schemas, automatically typed execution contexts, and file-level configuration.
+
+### `controller()`
+
+The `controller` function wraps a collection of routes and configuration options (like middleware or CORS) inside a single file. 
+
+### Usage
+
+```typescript
+import { controller, route } from 'exisjs/router'
+import { authMiddleware } from '../../middleware/auth'
+
+export default controller({
+  // Global config applied to all routes in this controller
+  cors: true,
+  middleware: [authMiddleware],
+
+  // Your individual routes
+  getUser: route.get('/user', {
+    async handle({ req }) {
+      return { user: req.user }
+    }
+  })
+})
+```
+
+### Options (`ControllerConfig`)
+- `cors` (`boolean | CorsConfig`): Enables or configures CORS for all routes in this file.
+- `middleware` (`Handler[]`): Array of middleware functions applied to all routes in this file.
+- `filters` (`any | any[]`): Route filters applied to all routes.
+- `onError` (`HookError`): A file-level error handler.
+- `onResponse` (`HookResponse`): A file-level response hook.
+- `[key: string]` (`RouteDefinition`): **Any other key** is treated as a route definition (e.g. `getUser: route.get(...)`). This is how you bind routes to the controller!
+
+---
+
+## `route`
+
+The `route` object provides factory functions for every HTTP method (e.g., `route.get`, `route.post`, `route.patch`, `route.delete`, `route.ws`, `route.sse`). 
+
+It takes a path and a `RouteConfig` object.
+
+### Usage
+
+```typescript
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  createUser: route.post('/users', {
+    body: tex.object({
+      email: tex.email(),
+      password: tex.string({ min: 8 })
+    }),
+    async handle(ctx) {
+      // ctx.body is strictly typed!
+      const { email, password } = ctx.body 
+      return { success: true, email }
+    }
+  })
+})
+```
+
+### Options (`RouteConfig`)
+
+- `body`: A validation schema for the request body (e.g., using `v` or Zod).
+- `query`: A validation schema for the query string.
+- `params`: A validation schema for the URL path parameters.
+- `response`: A validation schema to serialize/validate the outgoing response.
+- `middleware` (`Handler[]`): An array of middleware specific to this route.
+- `cors` (`boolean | CorsConfig`): Route-specific CORS overrides.
+- `filters` (`any | any[]`): Route-specific filters (like rate limiters or authorization checks).
+- `permissions` (`string[]`): An array of required permission flags to access this route.
+- `metadata` (`Record<string, any>`): Arbitrary metadata attached to the route for custom plugins/middleware.
+- `host` (`string | string[]`): Restrict this route to a specific subdomain/host (e.g. `api.example.com`).
+- `handle`: The async function that executes your business logic. It receives a `SuperContext`.
+
+---
+
+## `SuperContext`
+
+Every `handle` function receives a `SuperContext` object that provides fully-typed access to the request and application environment.
+
+```typescript
+import { controller, route } from '../router' // Import your custom router (see below)
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  getUserInfo: route.get('/info/:id', {
+    params: tex.object({ id: tex.string() }),
+    query: tex.object({ debug: tex.boolean({ optional: true }) }),
+    async handle({ body, query, params, headers, req, res, app, state, user, workspace }) {
+      // 1. `body`, `query`, and `params` are pre-validated and fully typed!
+      const id = params.id
+      
+      // 2. `req` and `res` are the raw ExisJS request/response objects
+      const ip = req.ip
+      
+      // 3. `app` is the global ExisJS application instance
+      const db = app.resolve('Database')
+      
+      // 4. `resolve` is the request-scoped dependency injection resolver!
+      const usersService = resolve(UsersService)
+
+      // 5. `state` is a mutable object shared across middlewares
+      const cacheHit = state.cacheHit 
+
+      // 6. `user` and `workspace` are strictly typed from your custom context!
+      return { id, email: user.email, workspace }
+    }
+  })
+})
+```
+
+---
+
+## `createRouter<T>()`
+
+If your application relies heavily on custom context (e.g., passing a `user` or `workspace` object injected via middleware to every route), you can create a strongly-typed custom router using `createRouter<T>()`.
+
+This removes the need to constantly cast or redefine types.
+
+### Usage
+
+```typescript filename="src/router.ts"
+import { createRouter } from "exisjs/router";
+
+interface User {
+  userId: string;
+  role: string;
+  email: string;
+}
+
+interface AppContext {
+  user: User;
+  workspace: string; // Just an example to prove we can pass any property
+}
+
+// Create a completely customized router scoped to this application
+export const { route, controller } = createRouter<AppContext>();
+```
+
+Now, when you use this custom `route` object, the `SuperContext` will automatically infer your custom context fields!
+
+```typescript filename="src/http/users/route.ts"
+import { route, controller } from '../../router'
+
+export default controller({
+  me: route.get('/me', {
+    async handle({ user, workspace }) {
+      // `user` and `workspace` are strictly typed!
+      return { id: user.userId, workspace }
+    }
+  })
+})
+```
+
+---
+
+## 2. Class-Based Routing (OOP)
+
+If you prefer an Object-Oriented paradigm, ExisJS provides a robust set of decorators via `exisjs/decorators`. These decorators are built on standard ECMAScript decorators and do not require `reflect-metadata`, making them incredibly fast and lightweight.
+
+### Usage
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Post, Body, Param } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+
+@Controller('/users')
+export default class UserController {
+  
+  @Get('/:id')
+  async getUser(@Param('id') id: string) {
+    return { id, name: 'Alice' }
+  }
+
+  @Post('/', {
+    body: tex.object({ email: tex.email(), password: tex.string() })
+  })
+  async createUser(@Body() body: any) {
+    // body is automatically validated!
+    return { success: true, email: body.email }
+  }
+}
+```
+
+### Route Decorators
+
+- `@Get(path, schema?)`
+- `@Post(path, schema?)`
+- `@Put(path, schema?)`
+- `@Patch(path, schema?)`
+- `@Delete(path, schema?)`
+- `@Ws(path, schema?)`: Defines a WebSocket route.
+- `@Sse(path, schema?)`: Defines a Server-Sent Events stream route.
+
+*Note: Just like functional routes, you can pass an optional `RouteSchema` to any of these decorators to automatically validate requests!*
+
+### Parameter Injectors
+
+Use parameter decorators to automatically extract data from the incoming request and inject them into your method arguments:
+
+- `@Body()`: Injects the parsed JSON request body.
+- `@Param('id')`: Injects a specific URL path parameter.
+- `@Query('search')`: Injects a specific query string parameter.
+- `@Headers('authorization')`: Injects a specific HTTP header.
+- `@Req()`: Injects the raw ExisJS Request object.
+- `@Res()`: Injects the raw ExisJS Response object.
+- `@Next()`: Injects the next function.
+- `@Socket()`: Injects the active WebSocket instance (for `@Ws` routes).
+- `@Stream()`: Injects the active SSE instance (for `@Sse` routes).
+
+### Advanced Decorators
+
+ExisJS provides a rich ecosystem of decorators to apply middleware, configure responses, and enforce security on both individual routes and entire controllers:
+
+#### Configuration & Middleware
+- `@Use(...middlewares)`: Applies Express-style middleware to a route or entire controller.
+- `@Hosts('api.example.com')`: Restricts the route or controller to specific domains.
+
+#### Security & Lifecycle
+- `@Permissions('admin')`: Requires specific permission flags.
+- `@UseGuards(...guards)`: Attaches Guards (like auth checks) to a route/controller.
+- `@UseInterceptors(...interceptors)`: Attaches Interceptors to mutate requests/responses.
+- `@UseFilters(...filters)`: Attaches Exception Filters to handle specific errors.
+
+#### Responses & Caching
+- `@HttpCode(201)`: Forces a specific HTTP status code for successful responses.
+- `@Header('X-Custom', 'Value')`: Automatically injects a specific response header.
+- `@Returns(schema)`: Explicitly defines the response schema for OpenAPI generation.
+- `@Cache({ ttlMs: 60000 })`: Automatically caches GET responses.
+- `@Idempotent()`: Enforces idempotency keys for mutations (e.g., checkout/payments).

package/dist/docs/reference/sanitize.mdx

@@ -0,0 +1,130 @@
+---
+title: "Sanitization"
+description: "API Reference for ExisJS built-in Sanitization Engine."
+---
+
+# Sanitization (`sanitize`)
+
+The `exisjs/sanitize` module provides a comprehensive suite of pure, dependency-free functions for transforming and cleaning data **before** it hits your business logic or database.
+
+Sanitizers are designed to be perfectly composable with the [ExisJS Validator](/docs/reference/validator) via the `.sanitize()` modifier, meaning you can strip HTML, trim whitespace, and enforce limits *while* validating request payloads.
+
+---
+
+## Core Sanitizers
+
+The `sanitize` object exposes pure functions grouped by their target data type.
+
+### String Sanitizers
+
+- `sanitize.trim`: Trims leading and trailing whitespace.
+- `sanitize.toLowerCase`: Converts the string to lower case.
+- `sanitize.toUpperCase`: Converts the string to upper case.
+- `sanitize.collapseWhitespace`: Replaces multiple consecutive spaces, tabs, or newlines with a single space.
+- `sanitize.stripHtml`: Removes all HTML tags from the string.
+- `sanitize.escapeHtml`: Escapes dangerous characters (`&`, `<`, `>`, `"`, `'`) into HTML entities.
+- `sanitize.normalizeUnicode`: Normalizes unicode characters to their canonical form (NFC).
+- `sanitize.slugify`: Converts a string into a URL-friendly slug (e.g., `Hello World!` -> `hello-world`).
+- `sanitize.truncate(length)`: Hard-truncates a string to a specific maximum length.
+- `sanitize.removeNonAlphanumeric`: Removes all characters except letters and numbers.
+- `sanitize.normalizeLineEndings`: Converts Windows line endings (`\r\n`) to Unix line endings (`\n`).
+
+### Number Sanitizers
+
+- `sanitize.round`: Rounds the number to the nearest integer.
+- `sanitize.clamp(min, max)`: Restricts a number to fall within a specific range.
+- `sanitize.defaultIfNaN(fallback)`: Returns the fallback value if the provided number is `NaN`.
+
+### Date Sanitizers
+
+- `sanitize.normalizeToIsoString`: Converts a Date object into a standard ISO 8601 string.
+- `sanitize.stripTime`: Resets the time portion of a Date object to `00:00:00:000` (midnight local time).
+
+### Array Sanitizers
+
+- `sanitize.dedupe`: Removes duplicate elements from the array.
+- `sanitize.compact`: Removes `null`, `undefined`, and empty strings (`''`) from the array.
+- `sanitize.trimElements`: Trims whitespace from all string elements inside the array.
+- `sanitize.limitLength(length)`: Slices the array down to a maximum length.
+
+### Object Sanitizers
+
+- `sanitize.stripUnknownKeys(['allowedA', 'allowedB'])`: Strips out any keys from the object that are not explicitly allowed.
+- `sanitize.deepTrimStringValues`: Recursively walks through an object (and nested arrays/objects) and trims all string values found.
+- `sanitize.omit(['secret'])`: Removes specific keys from the object.
+- `sanitize.pick(['publicField'])`: Returns a new object containing only the specified keys.
+
+---
+
+## Using with Validation
+
+The most powerful way to use ExisJS sanitizers is to chain them directly into your schemas using the `.sanitize()` modifier. 
+
+**Note that sanitization runs *before* final validation checks (like `.email()` or `.min()`).**
+
+```typescript filename="src/http/posts/route.ts"
+import { Controller, Post, Body } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+import { sanitize } from 'exisjs/sanitize'
+
+const CreatePostSchema = tex.object({
+  // Trim the title, then ensure it's still at least 5 characters
+  title: tex.string({ min: 5 })
+    .sanitize(sanitize.trim, sanitize.collapseWhitespace),
+
+  // Automatically generate a URL slug from the input string
+  slug: tex.string()
+    .sanitize(sanitize.slugify),
+
+  // Strip all HTML before saving to the database
+  content: tex.string()
+    .sanitize(sanitize.stripHtml),
+
+  // Deduplicate tags and remove empty strings
+  tags: tex.array(tex.string())
+    .sanitize(sanitize.dedupe, sanitize.compact)
+})
+
+// === Class-Based (OOP) Example ===
+@Controller('/api/posts')
+export default class PostController {
+  @Post('/', { body: CreatePostSchema })
+  createPost(@Body() data: any) {
+    // data.title will be trimmed
+    // data.content will have zero HTML tags
+    // data.tags will contain no duplicates
+    return data
+  }
+}
+
+// === Functional Example ===
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  createPostFn: route.post('/api/posts/functional', {
+    body: CreatePostSchema,
+    async handle(ctx) {
+      // ctx.body is fully sanitized and strongly typed!
+      return ctx.body
+    }
+  })
+})
+```
+
+---
+
+## Standalone Usage
+
+Because the `sanitize` methods are pure functions, you can easily use them independently anywhere in your application.
+
+```typescript
+import { sanitize } from 'exisjs/sanitize'
+
+const rawInput = "   <script>alert('hack')</script> Hello    World!   "
+
+let safeInput = sanitize.stripHtml(rawInput)
+safeInput = sanitize.collapseWhitespace(safeInput)
+safeInput = sanitize.trim(safeInput)
+
+console.log(safeInput) // "Hello World!"
+```

package/dist/docs/reference/storage.mdx

@@ -0,0 +1,116 @@
+---
+title: "Storage & Uploads"
+description: "API Reference for ExisJS Storage and File Uploads (`exisjs/storage`)."
+---
+
+# Storage & Uploads (`exisjs/storage`)
+
+ExisJS provides native, extremely memory-efficient support for handling `multipart/form-data` file uploads.
+
+Instead of buffering large files into RAM (which can easily crash Node.js servers under heavy load), ExisJS streams file chunks directly from the network socket into the disk using a highly optimized Busboy integration.
+
+---
+
+## How it Works
+
+When you invoke `streamUpload`, ExisJS takes over the raw socket stream. As bytes come in from the network, they are instantly piped to the disk. 
+
+Because ExisJS parses the multipart stream on the fly:
+1. Your Node.js RAM footprint stays incredibly flat, even when users upload massive 10GB video files.
+2. Form text fields are extracted in real-time. Once the upload finishes, ExisJS automatically merges all text fields directly into `req.body` so your subsequent logic (or validators) can treat them like a normal JSON payload!
+
+---
+
+## 1. Functional Example (`streamUpload`)
+
+If you are using the Functional architecture, import the `streamUpload` helper from `exisjs/storage` and pass it your request context.
+
+### Example Usage
+
+```typescript filename="src/http/upload/route.ts"
+import { controller, route } from 'exisjs/router'
+import { streamUpload } from 'exisjs/storage'
+import { HttpError } from 'exisjs/error'
+
+export default controller({
+  uploadAvatar: route.post('/avatar', {
+    async handle(ctx) {
+      try {
+        const { files, fields } = await streamUpload(ctx.req, {
+          dest: './storage/avatars'
+        })
+
+        if (files.length === 0) {
+          throw HttpError.badRequest('No file provided')
+        }
+
+        const uploadedFile = files[0]
+        
+        // Log the fields submitted with the form
+        console.log('User ID associated with upload:', fields.userId)
+
+        return {
+          success: true,
+          filename: uploadedFile.filename,
+          savedAt: uploadedFile.destPath,
+          size: uploadedFile.size,
+          mimetype: uploadedFile.mimetype
+        }
+      } catch (err) {
+        // streamUpload throws HttpErrors if the request isn't valid multipart/form-data
+        throw err
+      }
+    }
+  })
+})
+```
+
+### Return Value
+
+`streamUpload` resolves a Promise containing an object with two properties:
+
+#### 1. `fields` (`Record<string, string>`)
+An object containing all the non-file text fields submitted in the `multipart/form-data` payload. Note that `streamUpload` automatically populates `ctx.req.body` with these fields as well upon completion.
+
+#### 2. `files` (`Array<object>`)
+An array of successfully streamed files. Each object contains:
+- **`fieldname`**: The name of the HTML form field (e.g., `avatar`).
+- **`filename`**: The original name of the file uploaded by the user.
+- **`mimetype`**: The MIME type of the file (e.g., `image/png`).
+- **`destPath`**: The absolute path on your server's disk where the file was safely saved. *Note: ExisJS appends a randomized unique suffix to the filename to prevent overwrites.*
+- **`size`**: The total file size in bytes.
+
+---
+
+## 2. Class-Based Example (`req.streamUpload`)
+
+If you are using Object-Oriented `@Controller` classes, ExisJS natively extends the Request object. You do not even need to import `streamUpload`! 
+
+Simply inject the Request object via the `@Req()` decorator and call `req.streamUpload(dest)` directly.
+
+```typescript filename="src/http/upload/route.ts"
+import { Controller, Post, Req } from 'exisjs/decorators'
+import type { Request } from 'exisjs'
+import { HttpError } from 'exisjs/error'
+
+@Controller('/upload')
+export default class UploadController {
+  
+  @Post('/avatar')
+  async handleUpload(@Req() req: Request) {
+    // Exactly identical to streamUpload(req, { dest: ... })
+    // We pass the destination path directly into the Request method
+    const { files, fields } = await req.streamUpload('./storage/avatars')
+    
+    if (!files.length) throw HttpError.badRequest('Missing file')
+    
+    // Remember: fields are also populated into req.body!
+    console.log(req.body.userId === fields.userId) // true!
+    
+    return { 
+      message: 'Upload successful', 
+      files 
+    }
+  }
+}
+```

package/dist/docs/reference/swagger.mdx

@@ -0,0 +1,132 @@
+---
+title: "Swagger & OpenAPI"
+description: "API Reference for ExisJS auto-generated Swagger UI (`exisjs/swagger`)."
+---
+
+# Swagger / OpenAPI (`exisjs/swagger`)
+
+ExisJS ships with native, zero-configuration OpenAPI 3.0 generation.
+
+Because ExisJS routes strongly integrate with `exisjs/validator`, the framework automatically introspects your validators (`tex.object`, `tex.string`, etc.) across all controllers and automatically generates a fully interactive Swagger UI!
+
+---
+
+## 1. Global Setup (`exis.config.ts`)
+
+Because the Swagger engine needs to read all registered routes at boot time, you mount it globally using a Plugin.
+
+Create a new file in your `plugins` directory:
+
+```typescript filename="src/plugins/swagger.ts"
+import { definePlugin } from 'exisjs/plugin'
+import { serveSwagger } from 'exisjs/swagger'
+
+export const swaggerPlugin = definePlugin({
+  name: 'swagger-ui',
+  register(app) {
+    serveSwagger(app, {
+      path: '/docs',               // The URL where the UI will be served
+      title: 'My ExisJS API',
+      version: '1.0.0',
+      
+      // Optionally attach global OpenAPI components (like Bearer Auth definitions)
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: 'JWT',
+          }
+        }
+      }
+    })
+  }
+})
+```
+
+Then, natively register your plugin in `exis.config.ts`:
+
+```typescript filename="exis.config.ts"
+import { defineConfig } from 'exisjs/config'
+import { swaggerPlugin } from './src/plugins/swagger'
+
+export default defineConfig({
+  plugins: [
+    swaggerPlugin()
+  ]
+})
+```
+
+---
+
+## 2. Automatic Schema Inference
+
+You do not need to write YAML files or manually define your request bodies in Swagger. ExisJS reads the schemas directly from your code!
+
+### Functional Architecture
+
+When using the `route.*` functions, anything you pass to `schema.body`, `schema.query`, or `schema.response` is instantly injected into the Swagger documentation.
+
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { tex } from 'exisjs/validator'
+
+export default controller({
+  createUser: route.post('/', {
+    schema: {
+      // ExisJS automatically builds an OpenAPI schema from this validator!
+      body: tex.object({
+        email: tex.email(),
+        age: tex.number({ min: 18 })
+      }),
+      response: tex.object({
+        id: tex.string(),
+        success: tex.boolean()
+      })
+    },
+    async handle(ctx) {
+      return { id: '123', success: true }
+    }
+  })
+})
+```
+
+### Class-Based (OOP) Architecture
+
+If you are using OOP Decorators, ExisJS achieves the exact same result by reading your `@Body()`, `@Query()`, and `@Returns()` decorators.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Post, Body, Returns } from 'exisjs/decorators'
+import { tex } from 'exisjs/validator'
+
+const CreateUserSchema = tex.object({
+  email: tex.email(),
+  age: tex.number({ min: 18 })
+})
+
+const ResponseSchema = tex.object({
+  id: tex.string(),
+  success: tex.boolean()
+})
+
+@Controller('/users')
+export default class UserController {
+  
+  @Post('/')
+  @Returns(ResponseSchema)
+  async createUser(@Body(CreateUserSchema) body: any) {
+    return { id: '123', success: true }
+  }
+}
+```
+
+---
+
+## 3. Accessing the UI
+
+Once you boot your application, simply navigate to the `path` you defined in your plugin:
+
+- **Swagger UI**: `http://localhost:4000/docs`
+- **Raw OpenAPI JSON**: `http://localhost:4000/docs/json`
+
+The generated Swagger UI is fully interactive, meaning you can authenticate and test your API directly from the browser!