exisjs 0.7.5 → 0.7.7

package/dist/docs/reference/logger.mdx

@@ -1,47 +1,97 @@
 ---
 title: "Logger"
-description: "API Reference for the ExisJS structured logger (exisjs/logger)."
+description: "API Reference and Architecture Guide 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`.
+ExisJS includes a high-performance, zero-overhead structured logging engine powered by Pino. It provides an **industry-standard single-line terminal format** in development and **ultra-fast structured NDJSON** in production for cloud observability platforms (Datadog, Loki, CloudWatch, OpenTelemetry).
 
 ```typescript
-import { logger, configureLogger, setLogger } from 'exisjs/logger'
+import {
+  logger,
+  configureLogger,
+  setLogger,
+  createLogger,
+  createSilentLogger,
+  isLogger,
+  formatBytes,
+  formatLatency,
+  formatMethod,
+  formatStatus,
+  formatUrl,
+  formatIp,
+} from 'exisjs/logger'
 ```
 
 ---
 
-## 1. Global Logger Singleton (`logger`)
+## 1. Terminal Request Logging (Development DX)
+
+When running your application in development mode (`exis dev` or `pretty: true`), ExisJS automatically formats every incoming HTTP request into a clean, concise, single-line terminal log:
+
+```text
+[22:50:17] [exis] GET     /                            304 Not Modified 18ms
+[22:50:55] [exis] GET     /api/v1/profile              200 OK          1.2ms   240 B
+[22:51:02] [exis] POST    /api/v1/users                201 Created     14.5ms  1.4 KB
+[22:51:10] [exis] PATCH   /api/v1/users/42             400 Bad Request 3.1ms   120 B
+   └─ ⚠ Validation [body]: Field "email" must be a valid email format
+[22:51:15] [exis] GET     /api/v1/unknown              404 Not Found   0.8ms    45 B
+[22:51:22] [exis] POST    /api/v1/checkout             500 Internal Error 320ms 82 B
+   └─ ✖ Error: Database connection timeout
+```
 
-The `logger` singleton can be imported and called anywhere in your application:
+### Visual Features & Formatting Elements
+
+| Element | Description | Behavior / Color Coding |
+| :--- | :--- | :--- |
+| **Timestamp** | `[HH:MM:SS]` | Dimmed gray for non-intrusive readability |
+| **Brand Badge** | `[exis]` | Framework brand color (`\x1b[38;2;160;70;255m`), `[warn]` (yellow), `[error]` (red) |
+| **HTTP Method** | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `QUERY`, `SEARCH`, `OPTIONS`, `HEAD`, `WS`, `SSE`, `CONNECT`, `TRACE`, `PURGE` | Fixed-width padded badge with distinct colors (`GET`/`SEARCH` cyan, `POST` green, `PUT`/`PATCH` yellow, `DELETE`/`PURGE` red, `QUERY` blue, `OPTIONS`/`HEAD`/`WS` magenta) |
+| **Path & Query** | `/api/v1/items?page=1` | Path in bright white, query parameters in dimmed gray |
+| **Status Code** | `101 Switching Protocols`, `200 OK`, `201 Created`, `400 Bad Request`, `404 Not Found`, `500 Internal Error` | Color-coded by range: `101` magenta, `2xx` green, `3xx` cyan, `4xx` yellow, `5xx` red |
+| **Response Latency** | `1.2ms`, `18ms`, `1.45s` | Dynamic threshold color coding: `< 50ms` (green), `50ms - 250ms` (yellow), `> 250ms` (red) |
+| **Content Size** | `120 B`, `1.4 KB`, `2.8 MB` | Formatted human-readable byte sizes from `Content-Length` |
+| **Client IP** | `192.168.1.5` | Localhost (`127.0.0.1` / `::1`) is suppressed by default for minimal noise; remote client IPs are cleanly displayed |
+| **Diagnostic Sublines** | `└─ ⚠ Validation: ...` / `└─ ✖ Error: ...` | Indented warning and error summaries printed directly below failed requests |
+
+---
+
+## 2. Structured Logging in Production (NDJSON)
+
+In production (`NODE_ENV === 'production'` or `pretty: false`), the logger outputs single-line structured JSON (NDJSON) directly to `stdout` with zero serialization overhead:
+
+```json
+{"level":30,"time":1774286390000,"pid":1234,"hostname":"prod-app-01","requestId":"req-42","method":"GET","url":"/api/v1/profile","statusCode":200,"responseTime":1.2,"contentLength":240,"ip":"10.0.0.4","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","msg":"GET /api/v1/profile"}
+```
+
+---
+
+## 3. Global Logger Singleton (`logger`)
+
+The `logger` singleton is a high-performance proxy that can be imported and used anywhere in your services, repositories, workers, and controllers:
 
 ```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')
+// Standard level methods
+logger.info('Payment service initialized')
+logger.warn({ ip: req.ip, attempts: 3 }, 'Multiple failed login attempts')
+logger.error({ err, orderId: 'ord_123' }, 'Stripe webhook processing failed')
+logger.debug({ payload }, 'Parsed RPC frame')
+logger.trace('Entering database connection pool checkout')
+logger.fatal({ err }, 'Unrecoverable process state')
+
+// Child loggers with bound context
+const workerLogger = logger.child({ workerId: 'worker-1', queue: 'emails' })
+workerLogger.info('Processing email batch')
 ```
 
-### 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`)
+## 4. Configuration (`configureLogger`)
 
-Use `configureLogger()` to adjust log levels, toggle pretty printing, and customize sensitive field redactions across the entire application:
+Use `configureLogger()` to adjust log levels, toggle pretty printing, and customize sensitive field redactions across your entire application:
 
 ```typescript filename="src/http/server.ts"
 import { configureLogger } from 'exisjs/logger'
@@ -49,21 +99,87 @@ 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'],
+  redact: ['*.password', '*.token', '*.secret', 'req.headers.cookie', '*.creditCard'],
+})
+```
+
+### Options Reference
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `level` | `'fatal' \| 'error' \| 'warn' \| 'info' \| 'debug' \| 'trace' \| 'silent'` | `'info'` | Minimum log level to emit |
+| `pretty` | `boolean` | `NODE_ENV !== 'production'` | Whether to use colored single-line terminal formatting |
+| `redact` | `string[]` | *See Redaction section* | Array of object paths to automatically censor from logs |
+| `replaceRedact` | `boolean` | `false` | When `true`, overrides default redact paths instead of merging |
+
+---
+
+## 5. Security & Sensitive Data Redaction
+
+By default, ExisJS automatically censors sensitive fields in all log payloads before they are serialized to disk or terminal:
+
+```typescript
+// Built-in default redacted paths:
+[
+  'req.headers.authorization',
+  'req.headers.cookie',
+  'req.body.password',
+  'req.body.token',
+  'req.body.secret',
+  '*.password',
+  '*.token',
+  '*.secret',
+  'password',
+  'token',
+  'secret'
+]
+```
+
+When logging objects containing these keys (e.g. `{ username: 'alex', password: 'supersecretpassword' }`), the value is replaced with `"[Redacted]"`.
+
+---
+
+## 6. Request-Scoped Logger (`req.log` / `ctx.log`)
+
+Every incoming HTTP request in ExisJS provides a zero-allocation lazy child logger bound to `req.log`. It automatically inherits and binds:
+- `requestId` (`req.requestId`)
+- `method` (`req.method`)
+- `url` (`req.path`)
+
+```typescript filename="src/http/orders/route.ts"
+import { route, controller } from 'exisjs/router'
+
+export default controller({
+  create: route.post('/', {
+    async handle({ req, body }) {
+      // req.log automatically includes { requestId, method, url }
+      req.log.info({ orderId: body.id }, 'Creating order record')
+      return { success: true }
+    }
+  })
 })
 ```
 
-### 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.
+---
+
+## 7. OpenTelemetry & Distributed Tracing
+
+ExisJS automatically integrates with `@opentelemetry/api` when present in your environment. Every log entry emitted via `logger` or `req.log` automatically receives the active `trace_id` and `span_id`:
+
+```json
+{
+  "level": 30,
+  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+  "span_id": "00f067aa0ba902b7",
+  "msg": "Order created successfully"
+}
+```
 
 ---
 
-## 3. Custom Logger Instance (`setLogger`)
+## 8. Custom Logger Integration (`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()`:
+To route ExisJS logs directly into custom transports (such as `pino-loki`, `@google-cloud/logging`, or Elasticsearch), supply your custom instance to `setLogger()`:
 
 ```typescript filename="src/http/server.ts"
 import { setLogger } from 'exisjs/logger'
@@ -82,19 +198,35 @@ 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`:
+## 9. Formatting Helper Utilities
 
-```typescript filename="src/http/users/route.ts"
-import { route, controller } from 'exisjs/router'
+ExisJS exports all terminal formatting helpers from `exisjs/logger` so you can use them in custom CLI tools, workers, and plugins:
 
-export default controller({
-  profile: route.get('/profile', {
-    async handle({ req }) {
-      req.log.info('Fetching user profile')
-      return { ok: true }
-    }
-  })
-})
+```typescript
+import {
+  formatBytes,
+  formatLatency,
+  formatMethod,
+  formatStatus,
+  formatUrl,
+  formatIp,
+  extractValidationSummary,
+  extractErrorMessage,
+} from 'exisjs/logger'
+
+// Byte formatting
+formatBytes(1420) // "1.4 KB"
+
+// Latency with color threshold
+formatLatency(14.5) // "\x1b[32m14.5ms\x1b[0m"
+
+// Padded color-coded method
+formatMethod('GET') // "\x1b[1;36mGET    \x1b[0m"
+
+// Status code with standard phrase
+formatStatus(200) // "\x1b[1;32m200 OK\x1b[0m"
+
+// Localhost suppression
+formatIp('127.0.0.1') // "" (suppressed)
+formatIp('192.168.1.10') // "\x1b[90m192.168.1.10\x1b[0m"
 ```

package/dist/docs/reference/middleware.mdx

@@ -48,6 +48,37 @@ export default controller({
 
 ---
 
+## Middleware Context Inference
+
+### `defineMiddleware<TContext>(fn)`
+
+Creates a strongly-typed middleware function that attaches custom typed properties (like `user`, `session`, or `tenantId`) to `req`. Downstream route handlers (`route.get`, `route.post`, etc.) automatically inherit and infer this context with full IDE autocomplete and zero manual type casts.
+
+```typescript
+import { controller, route, defineMiddleware } from 'exisjs/router'
+
+interface AuthContext {
+  user: { id: string; role: 'admin' | 'user'; email: string }
+}
+
+const auth = defineMiddleware<AuthContext>((req, res, next) => {
+  req.user = { id: 'u1', role: 'admin', email: 'alex@example.com' }
+  next()
+})
+
+export default controller({
+  profile: route.get('/profile', {
+    middlewares: [auth],
+    handle({ req, res }) {
+      // req.user has full autocomplete and strict typing:
+      return res.json({ id: req.user.id, role: req.user.role })
+    }
+  })
+})
+```
+
+---
+
 ## Security Middleware
 
 ### `helmet(options?)`

package/dist/docs/reference/router.mdx

@@ -248,3 +248,25 @@ ExisJS provides a rich ecosystem of decorators to apply middleware, configure re
 - `@Returns(schema)`: Explicitly defines the response schema for OpenAPI generation.
 - `@Idempotent()`: Enforces idempotency keys for mutations (e.g., checkout/payments).
 
+---
+
+## 3. Streaming & Backpressure Pipeline
+
+The response object supports universal streaming with backpressure management across all route types:
+
+- `res.sendStream(source)`: Streams a Node.js `stream.Readable`, Web `ReadableStream`, or `AsyncIterable` directly to the client socket. Pauses consumption when socket buffers fill up and terminates source readers upon client disconnection.
+- `res.stream(source)`: Alias for `sendStream()`.
+- **Automatic Handler Auto-Piping**: Returning a Node.js stream, Web standard `ReadableStream`, or `AsyncIterable` generator directly from `handle()` automatically delegates to `res.sendStream()`.
+
+---
+
+## 4. `AppRouter` Client Manifest Contract
+
+ExisJS generates a compile-time route manifest in `.exis/types.d.ts` and `.exis/types/index.d.ts`:
+
+- `AppRouterPaths`: Flat dictionary mapping URL route patterns (e.g. `'/users/:id'`) to their strongly-typed handler contracts (`(payload?: B, options?: { query?: Q; params?: P }) => Promise<R>`).
+- `AppRouterTree`: Hierarchical dot-notation tree mapping nested folder paths (`users: { ':id': ... }`) for `@exisjs/fetch`'s `createClient<AppRouter>()`.
+- `AppRouter`: Combined intersection type `AppRouterPaths & AppRouterTree`.
+- `RouteDefinition.__type`: Phantom type property on every route definition preserving exact inferred return types, DTO schemas, and Drizzle/Prisma models.
+
+

package/dist/docs/reference/swagger.mdx

@@ -0,0 +1,143 @@
+---
+title: "Swagger (exisjs/swagger)"
+description: "API Reference for ExisJS Swagger & OpenAPI 3.1 Documentation Subsystem"
+---
+
+# Swagger Reference (`exisjs/swagger`)
+
+The `exisjs/swagger` module provides tools and decorators for auto-generating OpenAPI 3.1 specifications and serving interactive documentation UIs.
+
+```typescript
+import {
+  swagger,
+  defineSwagger,
+  generateOpenApiSpec,
+  renderDocumentationHtml,
+  mountDocumentation,
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+  ApiSecurity,
+  ApiExclude,
+  ApiProperty,
+} from 'exisjs/swagger'
+```
+
+---
+
+## Configuration (`SwaggerConfig`)
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | Whether to enable documentation routes |
+| `path` | `string` | `'/docs'` | URL path for the interactive HTML UI |
+| `specPath` | `string` | `'/docs/json'` | URL path for OpenAPI 3.1 JSON specification |
+| `title` | `string` | `'ExisJS API Documentation'` | API Title displayed in documentation |
+| `version` | `string` | `'1.0.0'` | API Version string |
+| `description` | `string` | `undefined` | Overview markdown or description |
+| `ui` | `'swagger-ui' \| 'scalar'` | `'swagger-ui'` | Documentation UI renderer |
+| `servers` | `OpenApiServer[]` | `[{ url: '/' }]` | Target server list |
+| `tags` | `OpenApiTag[]` | `[]` | Group tags with descriptions |
+| `security` | `Record<string, string[]>[]` | `[]` | Global security requirements |
+| `securitySchemes` | `Record<string, SecurityScheme>` | `{}` | Reusable security scheme definitions |
+| `customCss` | `string` | `undefined` | Custom CSS injected into the UI |
+| `customFavicon` | `string` | `undefined` | Custom favicon image URL |
+| `transformSpec` | `(spec: OpenApiSpec) => OpenApiSpec` | `undefined` | Hook to mutate OpenAPI spec before serving |
+
+---
+
+## Decorators
+
+### `@ApiTags(...tags: string[])`
+Assigns one or more tags to a controller class or method handler.
+*(Alias: `@Tags()`)*
+
+```typescript
+@ApiTags('Users', 'Authentication')
+@Controller('/users')
+export class UserController {}
+```
+
+### `@ApiOperation(options)`
+Attaches summary, description, operationId, and deprecated status to a route method.
+*(Alias: `@Operation()`)*
+
+```typescript
+@Get('/:id')
+@ApiOperation({
+  summary: 'Get user by UUID',
+  description: 'Fetches user details from database',
+  deprecated: false,
+})
+getUser() {}
+```
+
+### `@ApiResponse(options)`
+Defines an expected HTTP response status code and optional schema.
+
+```typescript
+@ApiResponse({
+  status: 200,
+  description: 'User details found',
+  schema: UserResponseSchema,
+})
+@ApiResponse({ status: 404, description: 'User not found' })
+getUser() {}
+```
+
+### `@ApiBearerAuth(name?: string)`
+Requires Bearer JWT authentication for this endpoint or controller.
+*(Alias: `@BearerAuth()`)*
+
+```typescript
+@ApiBearerAuth()
+@Get('/me')
+getMe() {}
+```
+
+### `@ApiSecurity(name: string, scopes?: string[])`
+Requires custom security scheme authentication for this endpoint or controller.
+
+```typescript
+@ApiSecurity('apiKeyAuth')
+@Get('/metrics')
+getMetrics() {}
+```
+
+### `@ApiExclude()`
+Excludes an endpoint or controller class from OpenAPI and Swagger generation.
+
+```typescript
+@Get('/internal')
+@ApiExclude()
+getInternal() {}
+```
+
+### `@ApiProperty(options?: { description?: string; example?: any; required?: boolean })`
+Annotates a class property with metadata for OpenAPI schema models.
+
+---
+
+## Functions
+
+### `swagger(config?: SwaggerConfig)`
+Convenience helper to mount Swagger/OpenAPI documentation on an ExisJS App instance.
+
+```typescript
+import { App } from 'exisjs'
+import { swagger } from 'exisjs/swagger'
+
+const app = new App()
+swagger({ title: 'My API', path: '/docs' })(app)
+```
+
+### `generateOpenApiSpec(routesOrApp, config)`
+Pure generator function that introspects routes, parameters, Tex/Zod schemas, and returns an `OpenApiSpec` object.
+
+```typescript
+const spec = generateOpenApiSpec(app, { title: 'My API', version: '1.0.0' })
+```
+
+### `renderDocumentationHtml(config)`
+Renders standalone HTML markup for Swagger UI or Scalar API reference.

package/dist/docs/reference/validator.mdx

@@ -11,13 +11,23 @@ ExisJS ships with a efficient, integrated validation library out of the box, exp
 
 ## Core Types
 
-The `tex` object provides factory functions for every common primitive and data structure.
-
-- `tex.string()`: Validates a string.
-- `tex.number()`: Validates a number.
-- `tex.boolean()`: Validates a boolean.
-- `tex.email()`: Validates standard email formatting.
-- `tex.enum(['A', 'B'])`: Validates against a specific set of allowed strings.
+The `tex` object provides factory functions for every common primitive and data structure:
+
+- `tex.string(options?)`: Validates a string (supports min, max, trim, sanitizers, masking, SQL injection prevention, defaults).
+- `tex.number(options?)`: Validates a numeric value (supports min, max, coercion, defaults).
+- `tex.boolean(options?)`: Validates a boolean value (supports coercion, defaults).
+- `tex.email(options?)`: Validates standard email formatting.
+- `tex.uuid(options?)`: Validates UUID v1 or v4 strings (`{ version: 1 | 4 }`).
+- `tex.cuid(options?)`: Validates CUID identifiers.
+- `tex.password(options?)`: Enforces password complexity rules (`requireNumbers`, `requireSymbols`, `requireUppercase`, `requireLowercase`).
+- `tex.creditCard(options?)`: Validates credit card number format with optional masking (`{ mask: true }`).
+- `tex.date(options?)`: Validates Date instances, or coerces ISO 8601 strings and UNIX timestamps with `minDate` / `maxDate` bounds.
+- `tex.enum(values, options?)`: Validates against a specific set of allowed strings.
+- `tex.literal(value)`: Validates against an exact literal value (`string | number | boolean`).
+- `tex.record(schema)`: Validates a dictionary / map of key-value pairs matching the given value schema.
+- `tex.union(schemas)`: Validates that the input matches at least one of the provided schemas.
+- `tex.any()`: Allows any arbitrary payload value without constraints.
+- `tex.file(options?)`: Validates multipart file uploads (`maxSize`, `mimeTypes`).
 
 ### Objects & Arrays
 
@@ -114,8 +124,24 @@ All validators accept an options object that allows you to configure validation
 - `optional` / `.optional()`: Marks the field as optional (allows `undefined`).
 - `nullable` / `.nullable()`: Marks the field as nullable (allows `null`).
 - `nullish` / `.nullish()`: Marks the field as nullish (allows both `null` and `undefined`).
+- `default`: Accepts a static literal value (`string | number | boolean | ...`) or a lazy factory function (`() => value`). Automatically marks the field as optional in schemas while inferring a non-optional concrete TypeScript return type.
 - `coerce`: Instructs the Rust engine to automatically convert types when possible before validating. For example, converting `"123"` into a number, or `3000` into a string.
 
+> [!TIP]
+> **Static vs. Dynamic Defaults**:
+> ```typescript
+> const ConfigSchema = tex.object({
+>   // Static defaults
+>   PORT: tex.number({ coerce: true, default: 3000 }),
+>   THEME: tex.enum(['light', 'dark'] as const, { default: 'light' }),
+>   TAGS: tex.array(tex.string(), { default: ['exis', 'framework'] }),
+> 
+>   // Dynamic defaults (evaluated per parse call)
+>   createdAt: tex.date({ default: () => new Date() }),
+>   requestId: tex.string({ default: () => crypto.randomUUID() }),
+> })
+> ```
+
 > [!NOTE]
 > **Empty String Interop**: If an incoming string is empty (`""`), and the field is configured as `optional`, `nullable`, or `nullish`, ExisJS automatically converts it to `undefined` or `null` before running type checks. This cleanly handles form submissions and query strings without requiring ad-hoc pre-processors.
 
@@ -133,20 +159,28 @@ const EnvSchema = tex.object({
 })
 ```
 
-### String Options
-- `min`: Enforces a minimum string length.
-- `max`: Enforces a maximum string length.
-
-### Number Options
-- `min`: Enforces a minimum numeric value.
-- `max`: Enforces a maximum numeric value.
+### Primitive Options Summary
+
+| Primitive | Available Options |
+| :--- | :--- |
+| `tex.string(opts?)` | `min`, `max`, `trim`, `collapseWhitespace`, `toLowerCase`, `toUpperCase`, `escapeHtml`, `stripHtml`, `slugify`, `mask`, `preventSql`, `preventTraversal`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.number(opts?)` | `min`, `max`, `coerce`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.boolean(opts?)` | `coerce`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.date(opts?)` | `coerce`, `minDate`, `maxDate`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.array(schema, opts?)` | `min`, `max`, `dedupe`, `coerce`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.enum(values, opts?)` | `default`, `optional`, `nullable`, `nullish` |
+| `tex.uuid(opts?)` | `version: 1 \| 4`, `default`, `optional`, `nullable`, `nullish` |
+| `tex.password(opts?)` | `min`, `max`, `requireNumbers`, `requireSymbols`, `requireUppercase`, `requireLowercase`, `optional`, `nullable`, `nullish` |
+| `tex.creditCard(opts?)` | `mask: boolean`, `optional`, `nullable`, `nullish` |
+| `tex.file(opts?)` | `maxSize`, `mimeTypes: string[]`, `optional`, `nullable`, `nullish` |
 
 ```typescript
 const User = tex.object({ 
   id: tex.string(), 
   email: tex.email(), 
   password: tex.string({ min: 8, max: 100 }),
-  age: tex.number({ min: 13, optional: true })
+  age: tex.number({ min: 13, optional: true }),
+  role: tex.enum(['admin', 'member'], { default: 'member' })
 })
 ```
 
@@ -204,18 +238,44 @@ The `TexEngine` automatically converts validation schemas into strictly complian
 
 ---
 
-## Environment Validation
+## Environment Validation (`tex.env`)
 
-You can safely parse and validate your environment variables at startup using the standard `.parse()` method.
+Because `process.env` always supplies raw string values (e.g. `"4000"`, `"true"`, `"1"`), ExisJS provides a dedicated `tex.env()` schema parser that automatically applies type coercion (`number`, `boolean`, `date`, `array`) and parses string representations without requiring verbose `{ coerce: true }` flags on every field.
 
-```typescript filename="env.ts"
+```typescript filename="src/config/env.ts"
 import { tex } from 'exisjs/validator'
 
-// Validates process.env synchronously. Crashes the app on boot with a 
-// beautiful error message if validation fails.
-export const env = tex.object({
-  PORT: tex.number({ coerce: true, optional: true }),
+// Validates process.env synchronously with automatic type coercion on boot.
+export const env = tex.env({
+  PORT: tex.number({ default: 3000 }), // Automatically coerced from "3000" -> 3000
+  DEBUG: tex.boolean({ default: false }), // Parsed from "true" | "1" | "false" | "0"
   DATABASE_URL: tex.string(),
-  JWT_SECRET: tex.string({ min: 32 })
+  JWT_SECRET: tex.string({ min: 32 }),
+  ALLOWED_ORIGINS: tex.array(tex.string()), // Parsed from "http://localhost:3000,https://app.com"
+  NODE_ENV: tex.enum(['development', 'production', 'test'] as const, {
+    default: 'development',
+  }),
 }).parse(process.env)
 ```
+
+> [!TIP]
+> `tex.env` automatically applies defaults and lazy factories (`default: () => ...`) when environment variables are omitted, while throwing structured `ValidatorError` diagnostics on boot if required keys are missing.
+
+---
+
+## Validation Error Descriptors (`ValidationErrorDescriptor`)
+
+When validation fails, ExisJS emits structured error descriptors passed across the FFI boundary:
+
+```typescript
+export interface ValidationErrorDescriptor {
+  path: string      // e.g. "email" or "items[0].sku"
+  message: string   // Human-readable failure description
+  expected: string  // Expected constraint or type rule
+  received: string  // Received value representation
+  code: string      // Machine-readable code (e.g. MISSING_REQUIRED_FIELD, INVALID_TYPE, VALUE_TOO_SMALL)
+}
+```
+
+In HTTP 400 responses, the envelope contains both a legacy `errors: Record<string, string>` dictionary for backward compatibility and a structured `details: ValidationErrorDescriptor[]` array for modern form libraries.
+

package/dist/error/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/error/errors.ts"],"names":[],"mappings":"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"}