exisjs 0.5.10 → 0.5.11

package/dist/docs/reference/di.mdx

@@ -0,0 +1,123 @@
+---
+title: "Dependency Injection"
+description: "API Reference for ExisJS Dependency Injection (`exisjs/di`)."
+---
+
+# Dependency Injection (`exisjs/di`)
+
+ExisJS ships with a powerful, built-in Inversion of Control (IoC) Container. 
+
+It fully supports standard Class-Based constructor injection (similar to NestJS or Angular) but also introduces a highly optimized `inject()` function that allows perfectly typed, deeply nested dependency injection inside purely functional architectures.
+
+---
+
+## Providing Dependencies
+
+Before a dependency can be injected, it must be provided to the application container. This is typically done in your plugins or the global `server.ts` file using `app.provide()`.
+
+### Provider Types
+
+ExisJS supports four types of providers:
+
+**1. Value Providers**
+Provide static, pre-instantiated values or configuration objects.
+```typescript
+app.provide('API_KEY', { useValue: 'sk_live_123' })
+```
+
+**2. Class Providers**
+Provide a class constructor. ExisJS will automatically instantiate it the first time it is resolved.
+```typescript
+app.provide('UserService', { useClass: UserService })
+```
+
+**3. Factory Providers**
+Provide a synchronous or asynchronous function to generate the value dynamically.
+```typescript
+app.provide('Database', { 
+  useFactory: async () => {
+    const db = new DatabaseConnection()
+    await db.connect()
+    return db
+  }
+})
+```
+
+**4. Direct Injection**
+If you pass an undecorated Class or object directly, ExisJS will attempt to resolve it automatically.
+```typescript
+app.provide(AuthService, AuthService)
+```
+
+---
+
+## Scopes (`singleton` vs `request`)
+
+By default, all providers in ExisJS are **Singletons**. They are instantiated once and cached for the lifetime of the application.
+
+If you need a new instance of a dependency for *every single incoming HTTP request*, you can change the scope to `request`.
+
+```typescript
+app.provide('TraceLogger', { 
+  useClass: RequestScopedLogger, 
+  scope: 'request' 
+})
+```
+
+> [!WARNING]
+> Request-scoped providers can severely impact application performance because they force the engine to allocate new memory and construct new classes on every single HTTP request. Only use `request` scope when strictly necessary.
+
+---
+
+## Injecting Dependencies
+
+### 1. Functional Injection (`inject()`)
+
+The true superpower of ExisJS is the `inject()` hook. 
+
+Powered by Node.js `AsyncLocalStorage`, `inject()` can be called from **anywhere** within a request lifecycle (Controllers, Middlewares, nested utility functions) without needing to explicitly pass the `app` or `req` objects down the call chain!
+
+```typescript filename="src/http/users/route.ts"
+import { route } from 'exisjs/router'
+import { inject } from 'exisjs/di'
+import { Database } from '../db' // The class definition
+
+export default controller({
+  getUsers: route.get('/', {
+    async handle() {
+      // Magically resolves the correct instance from the global container!
+      // Type is automatically inferred as `Database`.
+      const db = inject(Database) 
+      
+      const apiKey = inject<string>('API_KEY')
+      
+      return db.query('SELECT * FROM users')
+    }
+  })
+})
+```
+
+> [!NOTE]
+> `inject()` relies on the active execution context. If you call `inject()` outside of an active HTTP request or application lifecycle hook (e.g., in a background `setInterval` without context), it will throw an error.
+
+### 2. Using `inject()` in Classes (OOP)
+
+Unlike other frameworks like NestJS, ExisJS does **not** rely on slow, metadata-heavy Constructor Injection. 
+
+Instead, you use the exact same blazingly fast `inject()` function directly inside your Controller methods! This completely eliminates the need for `@Inject()` decorators or massive constructor boilerplate.
+
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get } from 'exisjs/decorators'
+import { inject } from 'exisjs/di'
+import { Database } from '../db'
+
+@Controller('/users')
+export default class UserController {
+  @Get('/')
+  async getUsers() {
+    // Inject dependencies perfectly cleanly right where you need them!
+    const db = inject(Database)
+    return db.query('SELECT * FROM users')
+  }
+}
+```

package/dist/docs/reference/error.mdx

@@ -0,0 +1,170 @@
+---
+title: "Error Handling"
+description: "API Reference for ExisJS built-in Error Handling (`exisjs/error`)."
+---
+
+# Error Handling (`exisjs/error`)
+
+ExisJS provides a rich set of predefined, highly optimized HTTP Error classes and a global error handler that automatically intercepts errors, formats them into a standard JSON shape, and prevents sensitive stack traces from leaking into production.
+
+---
+
+## Standard Exceptions
+
+You can throw these predefined exceptions from anywhere in your application (Controllers, Gateways, Services, or Middlewares). ExisJS will automatically catch them and map them to the correct HTTP status code.
+
+### Using Factory Methods (Recommended)
+
+The base `HttpError` class provides static factory methods for every standard HTTP error, making it extremely clean to throw errors inline:
+
+**Class-Based (OOP)**
+```typescript filename="src/http/users/route.ts"
+import { Controller, Get, Param } from 'exisjs/decorators'
+import { HttpError } from 'exisjs/error'
+
+@Controller('/users')
+export default class UserController {
+  @Get('/:id')
+  async getUser(@Param('id') id: string) {
+    const user = await db.users.find(id)
+    
+    if (!user) throw HttpError.notFound('User could not be found')
+    if (user.isBanned) throw HttpError.forbidden('User account is suspended')
+
+    return user
+  }
+}
+```
+
+**Functional**
+```typescript filename="src/http/users/route.ts"
+import { controller, route } from 'exisjs/router'
+import { HttpError } from 'exisjs/error'
+
+export default controller({
+  getUser: route.get('/:id', {
+    async handle(ctx) {
+      const user = await db.users.find(ctx.params.id)
+      
+      if (!user) throw HttpError.notFound('User could not be found')
+      if (user.isBanned) throw HttpError.forbidden('User account is suspended')
+
+      return user
+    }
+  })
+})
+```
+
+### Supported Factory Methods
+- `HttpError.badRequest(msg, details?)` (400)
+- `HttpError.unauthorized(msg?)` (401)
+- `HttpError.forbidden(msg?)` (403)
+- `HttpError.notFound(resource?)` (404)
+- `HttpError.conflict(msg)` (409)
+- `HttpError.unprocessable(msg, details?)` (422)
+- `HttpError.tooManyRequests(msg?)` (429)
+- `HttpError.internal(msg?)` (500)
+- `HttpError.serviceUnavailable(msg?)` (503)
+
+### `HttpError` Properties
+
+If you catch an `HttpError` or intercept it, you have access to the following properties:
+- **`statusCode`** `(number)`: The HTTP status code.
+- **`code`** `(string)`: The unique uppercase error code (e.g., `'NOT_FOUND'`).
+- **`message`** `(string)`: The human-readable message.
+- **`details`** `(unknown)`: Optional metadata attached to the error.
+- **`isOperational`** `(boolean)`: Always `true` for `HttpError`s. Used by the global error handler to determine if an error was intentionally thrown vs an unexpected crash.
+- **`toJSON()`**: Serializes the error into the strictly typed ExisJS `{ success: false, error: ... }` response shape.
+
+---
+
+## Direct Class Instantiation
+
+If you prefer class instantiation (common in NestJS workflows), you can directly instantiate the error classes or their `Exception` aliases.
+
+```typescript filename="src/services/auth.ts"
+import { UnauthorizedError, ConflictException } from 'exisjs/error'
+
+export function verifyToken(token: string) {
+  if (!isValid(token)) {
+    throw new UnauthorizedError('Invalid or expired token')
+  }
+}
+
+export function createUser(email: string) {
+  if (db.exists(email)) {
+    throw new ConflictException('Email already exists')
+  }
+}
+```
+
+### Supported Classes
+- `BadRequestError` / `BadRequestException`
+- `UnauthorizedError` / `UnauthorizedException`
+- `ForbiddenError` / `ForbiddenException`
+- `NotFoundError` / `NotFoundException`
+- `ConflictError` / `ConflictException`
+- `UnprocessableError` / `UnprocessableException`
+- `RateLimitError` / `RateLimitException`
+- `InternalError` / `InternalException`
+
+---
+
+## Custom Errors
+
+You can easily create your own custom domain errors by extending the base `HttpError` class.
+
+```typescript filename="src/errors/payment.ts"
+import { HttpError } from 'exisjs/error'
+
+export class InsufficientFundsError extends HttpError {
+  constructor(currentBalance: number) {
+    super(
+      'Insufficient funds to complete this transaction',
+      402, // Payment Required
+      'INSUFFICIENT_FUNDS', // Custom Error Code
+      { currentBalance } // Extra details attached to the response
+    )
+  }
+}
+```
+
+---
+
+## Global Error Handler
+
+ExisJS uses a highly sophisticated global error handler out of the box, generated via `createErrorHandler(isDev)`. 
+
+### Automatic Features:
+1. **JSON Standardization**: Automatically formats all errors into a strict `{ success: false, error: { code, message, details? } }` shape.
+2. **Third-Party Integrations**: Natively catches and normalizes schema validation errors from **Zod**, **Yup**, and the **ExisJS built-in validator**.
+3. **Syntax Guard**: Catches malformed JSON payloads (SyntaxErrors) in the request body gracefully.
+4. **Dev vs Prod Modes**: If `isDev` is true, unexpected internal errors (500) will attach stack traces to the response. In production, stack traces are completely stripped to prevent security leaks.
+5. **HTML Error Pages**: In Dev mode, if a request accepts `text/html`, the error handler renders a beautiful, stylized HTML error page displaying the stack trace directly in the browser.
+
+### Overriding the Global Handler
+
+If you need to intercept errors before they reach the client (e.g., to send them to Sentry or Datadog), you can provide a custom global error handler:
+
+```typescript filename="src/server.ts"
+import { exis } from 'exisjs'
+import { HttpError } from 'exisjs/error'
+
+const app = exis()
+
+app.use((err, req, res, next) => {
+  // Log unexpected errors to Sentry
+  if (!(err instanceof HttpError) || err.statusCode >= 500) {
+    Sentry.captureException(err)
+  }
+
+  // Pass it down to the default ExisJS error handler
+  next(err)
+})
+```
+
+### Express Compatibility (`asyncHandler`)
+
+ExisJS natively intercepts and handles Promise rejections at the core routing level. 
+
+Unlike Express, you do **not** need to wrap your routes in an `asyncHandler`. However, for strict compatibility with older Express middleware ecosystems, `exisjs/error` does export an `asyncHandler` wrapper. Note that using it in ExisJS is entirely redundant and merely adds unnecessary Promise allocations.

package/dist/docs/reference/exis.mdx

@@ -0,0 +1,124 @@
+---
+title: "exis()"
+description: "API Reference for the exis() application builder."
+---
+
+# Application Instance (exis)
+
+The `exis()` function is the primary entry point for configuring and booting your ExisJS application. It defines your core configuration, middleware, plugins, and lifecycle hooks.
+
+It returns a configured `App` instance that the CLI or deployment platform will automatically discover and run. The framework's auto-discovery mechanism effortlessly handles both **Functional** and **Class-Based (OOP)** routes inside your `src/http` directory.
+
+## Usage
+
+ExisJS supports both Functional and Class-Based (OOP) paradigms for configuring your application entry point.
+
+### 1. Functional Setup
+
+```typescript filename="src/http/server.ts"
+import { exis } from 'exisjs'
+import { cors } from 'exisjs/middleware'
+
+export default exis({
+  port: 3000,
+  helmet: true,
+  cors: {
+    origin: '*',
+  },
+  middlewares: [
+    cors()
+  ],
+  async onStart(app) {
+    app.log.info("Server is starting up!")
+  }
+})
+```
+
+---
+
+### 2. Class-Based Setup (OOP)
+
+If you prefer an Object-Oriented approach, you can define your application entry point using the `@Server()` decorator.
+
+```typescript filename="src/http/server.ts"
+import { Server } from 'exisjs/decorators'
+import type { App } from 'exisjs'
+
+@Server({
+  plugins: [
+    // You can register plugins or configuration directly in the decorator options
+  ]
+})
+export default class RootServer {
+  async onStart(app: App) {
+    app.log.info("Server is starting up!")
+  }
+  
+  async onClose(app: App) {
+    app.log.info("Server is shutting down!")
+  }
+}
+```
+
+---
+
+## Configuration Options
+
+The `exis()` function takes an `ExisConfig` object.
+
+### `port`
+- **Type**: `number`
+- **Default**: `3000` (or `process.env.PORT`)
+- The port the server will listen on during development or manual instantiation.
+
+### `host`
+- **Type**: `string`
+- **Default**: `'0.0.0.0'` (or `process.env.HOST`)
+- The host the server will bind to.
+
+### `env`
+- **Type**: `'development' | 'production' | 'test'`
+- **Default**: Auto-detected via `NODE_ENV`.
+- The current environment of the application.
+
+### `logger`
+- **Type**: `boolean | LoggerConfig`
+- **Default**: `true`
+- Toggles the built-in Pino logger. You can pass a custom configuration object to set the log level, redact sensitive fields, or output JSON.
+
+### `helmet`
+- **Type**: `boolean`
+- **Default**: `true`
+- Automatically applies security headers to every response. Set to `false` to disable.
+
+### `cors`
+- **Type**: `boolean | CorsConfig`
+- **Default**: `false`
+- Automatically injects CORS headers into the request pipeline. You can pass a configuration object to specify allowed origins, methods, and credentials.
+
+### `compression`
+- **Type**: `boolean`
+- **Default**: `true` (if applicable)
+- Automatically compresses HTTP responses (gzip/brotli).
+
+### `middlewares`
+- **Type**: `Handler[]`
+- **Default**: `[]`
+- An array of global middleware functions that will run on every single request.
+
+### `plugins`
+- **Type**: `ExisPlugin[]`
+- **Default**: `[]`
+- An array of ExisJS plugins to register.
+
+---
+
+## Lifecycle Hooks
+
+You can define async hooks that execute at specific stages of the application's lifecycle.
+
+### `onStart(app: App)`
+Fired after configuration is loaded but before the server starts accepting connections. This is the ideal place to connect to databases, initialize singletons, or run startup migrations.
+
+### `onClose(app: App)`
+Fired when the server receives a shutdown signal (e.g., `SIGINT`, `SIGTERM`). Use this to gracefully close database connections, flush analytics events, or tear down background workers.