exisjs 0.6.1 → 0.7.1

package/dist/docs/reference/decorators.mdx

@@ -3,11 +3,11 @@ title: "Decorators"
 description: "API Reference for ExisJS Class-Based Routing and Decorators."
 ---
 
-# Decorators (OOP)
+# Decorators (`exisjs/decorators`)
 
-ExisJS provides a robust Object-Oriented Programming (OOP) paradigm via the `exisjs/decorators` module. 
+ExisJS provides a robust Object-Oriented Programming (OOP) paradigm via the `exisjs/decorators` module.
 
-Unlike many other frameworks (such as NestJS or TypeDI), ExisJS decorators are built completely on standard ECMAScript decorators and **do not require `reflect-metadata`**. This makes them incredibly lightweight, extremely fast, and completely free of legacy metadata bloat.
+Unlike frameworks that depend on heavy reflection libraries, ExisJS decorators are built completely on standard ECMAScript decorators and **do not require `reflect-metadata`**.
 
 ---
 
@@ -20,8 +20,7 @@ Marks a class as a Controller. All route handler methods within the class will b
 ```typescript filename="src/http/users/route.ts"
 import { Controller } from 'exisjs/decorators'
 
-// Routes will be mounted at /api/users
-@Controller('/api/users')
+@Controller('/users')
 export default class UserController {
   // ...
 }
@@ -40,7 +39,6 @@ Defines an HTTP route handler on a class method. You can optionally pass a schem
 - `@Connect(path?, schema?)`
 - `@Trace(path?, schema?)`
 - `@All(path?, schema?)`
-- `@Query(path?, schema?)`: Can be used as a method decorator to handle custom `QUERY` method requests (e.g., RPC or GraphQL-like endpoints).
 
 ```typescript filename="src/http/users/route.ts"
 import { Controller, Get, Post } from 'exisjs/decorators'
@@ -60,234 +58,54 @@ export default class UserController {
 }
 ```
 
-### Real-Time Methods
-- `@Ws(path?, schema?)`: Maps the handler to a WebSocket connection.
-- `@Sse(path?, schema?)`: Maps the handler to a Server-Sent Events stream.
-
 ---
 
 ## 2. Parameter Injection
 
-Parameter decorators automatically extract data from the incoming request and inject them directly into your method arguments, drastically reducing boilerplate.
+Parameter decorators automatically extract data from the incoming request and inject them directly into your method arguments:
 
-- `@Body()`: Parses and injects the JSON request body.
-- `@Param(name?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
-- `@Query(name?)`: Injects a query string parameter. (Note: `@Query` doubles as a route decorator if used on a method).
-- `@Headers(name?)`: Injects an HTTP header by name.
-- `@HostParam(name?)`: Injects a subdomain parameter (e.g., extracted from `@Hosts(':tenant.example.com')`).
+- `@Body(nameOrPipe?)`: Parses and injects the JSON request body (or passes it through a validator/pipe).
+- `@Param(nameOrPipe?)`: Injects a URL path parameter (e.g., `id` from `/:id`).
+- `@Headers(nameOrPipe?)`: Injects an HTTP header by name.
+- `@QueryParam(nameOrPipe?)` / `@Query(nameOrPipe?)`: Injects a URL query parameter (e.g., `?search=term`).
+- `@HostParam(nameOrPipe?)`: Injects a subdomain parameter.
 - `@Req()`: Injects the raw ExisJS Request object.
-- `@Res(options?)`: Injects the raw ExisJS Response object. Use `@Res({ passthrough: true })` if you want ExisJS to still handle the final response serialization.
+- `@Res(options?)`: Injects the raw ExisJS Response object (`{ passthrough: true }`).
 - `@Ip()`: Injects the client's IP address.
-- `@Session()`: Injects the active session object (requires session middleware).
 - `@Next()`: Injects the Next function.
-- `@Socket()`: Injects the active WebSocket instance (for `@Ws`).
-- `@Stream()`: Injects the active SSE instance (for `@Sse`).
-- `@UploadedFile() / @UploadedFiles()`: Injects multipart/form-data files.
-
-```typescript filename="src/http/users/route.ts"
-import { Controller, Get, Post, Param, Body, Ip } from 'exisjs/decorators'
-
-@Controller('/users')
-export default class UserController {
-  @Get('/:id')
-  getUser(@Param('id') id: string, @Ip() ip: string) {
-    return { id, requestedBy: ip }
-  }
-
-  @Post('/')
-  createUser(@Body() body: { email: string }) {
-    return { email: body.email }
-  }
-}
-```
+- `createParamDecorator(factory)`: Exports a factory to create custom parameter decorators (e.g. `@CurrentUser()`).
 
 ---
 
-## 3. Middleware & Configuration
-
-### `@Use(...middlewares)`
-Applies Express-style middleware functions to a specific route handler or an entire controller class.
-
-```typescript filename="src/http/secure/route.ts"
-import { Controller, Get, Use } from 'exisjs/decorators'
-import { authMiddleware } from '../middleware/auth'
-
-@Controller('/secure')
-@Use(authMiddleware)
-export default class SecureController {
-  @Get('/')
-  getSecureData() {
-    return { secure: true }
-  }
-}
-```
-
-### `@Cache(options)`
-Automatically caches `GET` responses in memory or Redis.
-
-### `@Idempotent(options)`
-Enforces idempotency based on the `Idempotency-Key` header, preventing duplicate mutations (e.g., duplicate payments).
-
-```typescript filename="src/http/payments/route.ts"
-import { Controller, Post, Idempotent } from 'exisjs/decorators'
-
-@Controller('/payments')
-export default class PaymentController {
-  @Post('/checkout')
-  @Idempotent()
-  checkout() {
-    return { status: 'processing' }
-  }
-}
-```
-
----
-
-## 4. Responses & Metadata
-
-### `@HttpCode(code)`
-Forces a specific HTTP status code for successful responses.
-
-### `@Header(name, value)`
-Automatically injects a specific response header before sending the response.
+## 3. Middleware & Pipeline Decorators
 
-### `@Redirect(url, statusCode?)`
-Redirects the request to the specified URL.
-
-### `@Returns(schema)`
-Explicitly defines the response schema for OpenAPI (Swagger) generation.
-
-```typescript filename="src/http/documents/route.ts"
-import { Controller, Post, HttpCode, Header } from 'exisjs/decorators'
-
-@Controller('/documents')
-export default class DocumentController {
-  @Post('/')
-  @HttpCode(201)
-  @Header('X-Custom-Status', 'Processed')
-  createDoc() {
-    return { created: true }
-  }
-}
-```
+- `@Use(...middlewaresOrGuardsOrInterceptorsOrFilters)`: Unified decorator that binds middlewares, guards (`canActivate`), interceptors (`intercept`), or exception filters (`catch`) to a controller class or method.
+- `@Idempotent(options?)`: Caches responses based on the `Idempotency-Key` header using native in-memory off-heap storage.
 
 ---
 
-## 5. Security & Lifecycle
+## 4. Response & Metadata Modifiers
 
-These decorators allow you to attach ExisJS lifecycle hooks to your OOP routes.
-
-- `@Permissions(...flags)`: Restricts the route to users with specific permission flags.
-- `@Hosts(...hosts)`: Restricts the route to a specific subdomain/host.
-- `@UseGuards(...guards)`: Attaches Guards (authentication/authorization checks).
-- `@UseInterceptors(...interceptors)`: Attaches Interceptors (request/response mutation).
-- `@UseFilters(...filters)`: Attaches Exception Filters (custom error handling).
+- `@HttpCode(code: number)`: Enforces a custom HTTP status code on success.
+- `@Header(name: string, value: string)`: Appends an HTTP header to the response.
+- `@Returns(schema)`: Attaches response schema for OpenAPI documentation.
+- `@Redirect(url: string, statusCode?: number)`: Redirects request to target URL.
+- `@Permissions(...permissions: string[])`: Sets required permissions on the route.
+- `@Hosts(...hosts: string[])`: Restricts routes to specific Host headers.
+- `@SetMetadata(key, value)`: Attaches arbitrary custom metadata to a class or handler method, retrievable via `Reflector`.
+- `Reflector`: Utility class to inspect metadata attached by `@SetMetadata`:
+  - `Reflector.get(key, target)`: Retrieves metadata for a specific target.
+  - `Reflector.getAllAndOverride(key, targets)`: Retrieves metadata, overriding higher-level targets with lower-level targets.
+  - `Reflector.getAllAndMerge(key, targets)`: Merges array/object metadata across multiple targets.
 
 ---
 
-## 6. Global Setup
-
-### `@Server(options?)`
-Marks a class as the root Server entry point. Used to register global configuration and dependencies.
-
-**Options Interface:**
-```typescript
-interface ServerConfig {
-  plugins?: any[]
-  providers?: any[]
-  cron?: any[]
-  queue?: any[]
-}
-```
-
-```typescript filename="src/http/server.ts"
-import { Server } from 'exisjs/decorators'
-import { corsPlugin } from 'exisjs/middleware'
-
-@Server({
-  plugins: [corsPlugin]
-})
-export default class RootServer {
-  async onStart(app) {
-    app.log.info("App booted!")
-  }
-}
-```
+## 5. Dependency Injection & Modules
 
-### `@Gateway(options?)`
-Marks a class as a Gateway module. Gateways are used to apply massive configuration blocks across an entire directory of routes (e.g., applying an auth guard to all routes inside `src/http/admin`).
+- `@Module({ imports?, controllers?, providers?, exports? })`: OOP class decorator equivalent to `defineModule()` for structuring application modules.
+- `@Injectable(options?)`: Marks a service class as an IoC provider managed by the container. Supports `{ scope: 'singleton' | 'request' | 'transient' }`.
+- `@Inject(token)`: Constructor parameter decorator for injecting dependencies by class, string, or symbol token.
+- `@Optional()`: Constructor parameter decorator resolving missing dependencies to `undefined` without throwing.
+- `@Boundary(config)`: Marks a class as a folder-scoped Boundary configuring CORS, headers, exclusions, and pipeline steps.
+- `@Server(config)`: Marks a class as a root server definition.
 
-**Options Interface:**
-```typescript
-interface GatewayConfig {
-  exclude?: any[]
-  middleware?: any[]
-  filters?: any[]
-  guards?: any[]
-  interceptors?: any[]
-  timeout?: number | ((req: any) => number)
-  metadata?: Record<string, any>
-  cors?: any
-  headers?: Record<string, string>
-  imports?: any[]
-  providers?: any[]
-}
-```
-
-```typescript filename="src/http/gateway.ts"
-import { Gateway } from 'exisjs/decorators'
-import { helmet, hpp } from 'exisjs/middleware'
-
-/**
- * Root Gateway (gatekeeper for the entire application)
- *
- * Gateways apply configuration to all routes within their directory and subdirectories.
- * This acts as the global security and infrastructure layer.
- */
-@Gateway({
-  // 1. Cross-Origin Resource Sharing (CORS)
-  cors: {
-    origin: ['https://myapp.com', /localhost:\d+/],
-    credentials: true,
-  },
-
-  // 2. Global Headers
-  headers: {
-    'X-Powered-By': 'ExisJS',
-    'X-Application-Version': '1.0.0',
-  },
-
-  // 3. Global Middleware
-  middleware: [
-    helmet(), // Sets secure HTTP headers
-    hpp(),    // Prevents HTTP Parameter Pollution
-  ],
-
-  // 4. Exclude Paths
-  exclude: [{ path: '/health', method: 'GET' }],
-
-  // 5. Dependency Injection Providers
-  providers: [
-    ['ConfigService', { useValue: { apiKey: process.env.API_KEY || 'default' } }],
-  ],
-
-  // 6. Global Metadata
-  metadata: {
-    tenant: 'root',
-  },
-
-  // 7. Request Timeout
-  timeout: 10000,
-})
-export default class RootGateway {}
-```
-
-### `@Injectable(options?)`
-Marks a class as a provider for Dependency Injection, meaning it can be automatically injected into controllers or other services by the IoC container.
-
-**Options Interface:**
-```typescript
-interface InjectableOptions {
-  scope?: 'singleton' | 'request'
-}
-```

package/dist/docs/reference/di.mdx

@@ -51,17 +51,26 @@ app.provide(AuthService, AuthService)
 
 ---
 
-## Scopes (`singleton` vs `request`)
+## Scopes (`singleton`, `request`, `transient`)
 
 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`.
+ExisJS supports three provider scopes in the `@Injectable()` decorator and `app.provide()`:
+
+- **`singleton` (Default)**: Instantiated once and cached for the lifetime of the application.
+- **`request`**: A new instance is created exclusively for each incoming HTTP request, and garbage collected afterward.
+- **`transient`**: A new instance is created every single time the dependency is injected or resolved.
 
 ```typescript
 app.provide('TraceLogger', { 
   useClass: RequestScopedLogger, 
   scope: 'request' 
 })
+
+app.provide('OperationContext', {
+  useClass: OperationContext,
+  scope: 'transient'
+})
 ```
 
 > [!WARNING]
@@ -78,7 +87,7 @@ 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 { route, controller } from 'exisjs/router'
 import { inject } from 'exisjs/di'
 import { Database } from '../db' // The class definition
 
@@ -100,24 +109,39 @@ export default controller({
 > [!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. 
+### 2. Constructor Injection in Classes (OOP)
 
-Instead, you use the exact same `inject()` function directly inside your Controller methods! This completely eliminates the need for `@Inject()` decorators or massive constructor boilerplate.
+ExisJS supports full OOP constructor parameter injection. You can inject services directly via type annotation or specify tokens with `@Inject()`, and designate optional dependencies with `@Optional()`:
 
 ```typescript filename="src/http/users/route.ts"
-import { Controller, Get } from 'exisjs/decorators'
-import { inject } from 'exisjs/di'
-import { Database } from '../db'
+import { Controller, Get, Param, Inject, Optional } from 'exisjs/decorators'
+import { UserService } from './service'
+
+@Controller('/users')
+export default class UserController {
+  constructor(
+    private userService: UserService,
+    @Inject('DATABASE_URL') private dbUrl: string,
+    @Optional() @Inject('ANALYTICS') private analytics?: any
+  ) {}
+
+  @Get('/:id')
+  async getUser(@Param('id') id: string) {
+    return this.userService.findById(id)
+  }
+}
+```
 
+You can also use property-level `inject()` inside your Controller methods:
+
+```typescript
 @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/logger.mdx

@@ -0,0 +1,100 @@
+---
+title: "Logger"
+description: "API Reference for the ExisJS structured logger (exisjs/logger)."
+---
+
+# Logger (`exisjs/logger`)
+
+ExisJS includes a built-in, high-performance structured logger powered by Pino. It provides colored, pretty-printed logs in development and fast, structured JSON in production.
+
+All logger APIs are imported directly from the dedicated subpath `exisjs/logger`.
+
+```typescript
+import { logger, configureLogger, setLogger } from 'exisjs/logger'
+```
+
+---
+
+## 1. Global Logger Singleton (`logger`)
+
+The `logger` singleton can be imported and called anywhere in your application:
+
+```typescript
+import { logger } from 'exisjs/logger'
+
+logger.info('Server boot sequence initiated')
+logger.warn({ origin: req.headers.origin }, 'Untrusted origin detected')
+logger.error({ err }, 'Failed to persist record to database')
+logger.debug({ payload }, 'Parsing incoming request payload')
+```
+
+### Methods
+- `logger.info([obj], msg, ...args)`
+- `logger.warn([obj], msg, ...args)`
+- `logger.error([obj], msg, ...args)`
+- `logger.debug([obj], msg, ...args)`
+- `logger.trace([obj], msg, ...args)`
+- `logger.fatal([obj], msg, ...args)`
+- `logger.child(bindings)`: Creates a child logger with bound metadata (e.g. `{ requestId: '123' }`).
+
+---
+
+## 2. Configuration (`configureLogger`)
+
+Use `configureLogger()` to adjust log levels, toggle pretty printing, and customize sensitive field redactions across the entire application:
+
+```typescript filename="src/http/server.ts"
+import { configureLogger } from 'exisjs/logger'
+
+configureLogger({
+  level: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
+  pretty: process.env.NODE_ENV !== 'production',
+  redact: ['*.password', '*.token', '*.secret', 'req.headers.cookie'],
+})
+```
+
+### Options
+- `level` (`'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent'`): Minimum level to output (default: `'info'`).
+- `pretty` (`boolean`): Whether to format log lines with bracketed timestamp and colorized labels (`[HH:MM:ss] LEVEL: message`). Default is `true` in development and `false` in production.
+- `redact` (`string[]`): Property paths to censor automatically from log payloads.
+- `replaceRedact` (`boolean`): When `true`, replaces default redact paths instead of merging with them.
+
+---
+
+## 3. Custom Logger Instance (`setLogger`)
+
+If you want to plug in your own custom Pino instance or transport (e.g., streaming logs directly to Loki, Datadog, or Elasticsearch), pass it to `setLogger()`:
+
+```typescript filename="src/http/server.ts"
+import { setLogger } from 'exisjs/logger'
+import pino from 'pino'
+
+const customPino = pino({
+  level: 'info',
+  transport: {
+    target: 'pino-loki',
+    options: { host: 'http://localhost:3100' }
+  }
+})
+
+setLogger(customPino)
+```
+
+---
+
+## 4. Request-Scoped Logger (`req.log`)
+
+Every incoming HTTP request in ExisJS automatically receives a child logger bound to `req.log`. It automatically includes request context such as `req.requestId`:
+
+```typescript filename="src/http/users/route.ts"
+import { route, controller } from 'exisjs/router'
+
+export default controller({
+  profile: route.get('/profile', {
+    async handle({ req }) {
+      req.log.info('Fetching user profile')
+      return { ok: true }
+    }
+  })
+})
+```