exisjs 0.9.0 → 0.9.2

package/dist/docs/content/responses.mdx

@@ -451,6 +451,60 @@ export default controller({
 })
 ```
 
+## Caching & Conditional Requests (ETag, 304, 412)
+
+ExisJS follows the conditional request rules of RFC 9110 §13 everywhere: for automatic ETags, in `res.checkPreconditions()`, for `serveStatic` and for `res.download(path)`.
+
+| Request header | Checked against | Result when it does not hold |
+| :--- | :--- | :--- |
+| `If-Match` | `ETag`, strong comparison | `412 Precondition Failed` |
+| `If-Unmodified-Since` (only without `If-Match`) | `Last-Modified` | `412 Precondition Failed` |
+| `If-None-Match` | `ETag`, weak comparison; lists and `*` supported | Matches: `304` for GET/HEAD, `412` for writes |
+| `If-Modified-Since` (only without `If-None-Match`, GET/HEAD) | `Last-Modified` | Unchanged: `304 Not Modified` |
+
+A `304` carries the `ETag`, `Last-Modified`, `Cache-Control` and `Vary` of the `200` it replaces, and no body or `Content-Type`. Errors use the standard envelope (`PRECONDITION_FAILED`, `PRECONDITION_REQUIRED`).
+
+### Automatic ETags
+
+With `etag: true` in `exis.config.ts` (or `conditionalGet()` on some routes), every successful `GET`/`HEAD` response sent with `res.json()`, `res.send()` or a returned value gets a weak ETag hashed from its body, and a matching `If-None-Match` is answered with `304`. The handler still runs, so this saves bandwidth, not work. Writes and error responses get no ETag.
+
+### Validators from your data: `res.checkPreconditions()`
+
+When the resource has a version or update time, check it **before** doing the work. On reads this skips the query for the body and serialization; on writes it prevents lost updates: a client that edited an old copy gets `412` instead of overwriting someone else's change.
+
+```typescript filename="src/http/documents/[id]/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  read: route.get('/', {
+    async handle({ params, res }) {
+      const meta = await documents.meta(params.id) // cheap: version + updatedAt
+      // Sets ETag / Last-Modified; answers 304 and returns true when current
+      if (res.checkPreconditions({ etag: `v${meta.version}`, lastModified: meta.updatedAt })) return
+      return documents.find(params.id)
+    },
+  }),
+
+  update: route.put('/', {
+    async handle({ params, body, res }) {
+      const current = await documents.meta(params.id)
+      // 412 if the client's If-Match is stale; 428 if it sent no precondition
+      res.checkPreconditions({ etag: `v${current.version}` }, { required: true })
+      const updated = await documents.update(params.id, body)
+      res.setHeader('ETag', `"v${updated.version}"`) // the new state
+      return updated
+    },
+  }),
+})
+```
+
+- `etag` may be bare (`v3` is sent as `"v3"`) or a full tag (`W/"v3"`). Use a value that changes whenever the representation changes: a version column, a hash, `updatedAt`.
+- `lastModified` takes a `Date`, a timestamp or an HTTP date. It is rounded to whole seconds, and a time in the future is capped at the current time.
+- For "create only if absent" (`PUT` with `If-None-Match: *`), pass `exists: false` when the resource does not exist yet; an existing one answers `412`.
+- On writes, the old validators are not sent back. Set the new `ETag` after the change, as above.
+
+`req.fresh` (and `req.stale`) apply the same rules to the response headers set so far.
+
 ---
 
 ## Next Steps

package/dist/docs/content/validation.mdx

@@ -45,15 +45,16 @@ ExisJS provides type-safe primitives that accept modifier options and configurat
 
 | Primitive | Signature | Description |
 | :--- | :--- | :--- |
-| `tex.string()` | `tex.string(options?)` | Validates strings. Supports `{ min, max, trim, toLowerCase, toUpperCase, collapseWhitespace, escapeHtml, stripHtml, slugify, mask, preventSql, preventTraversal, coerce, default }`. |
-| `tex.number()` | `tex.number(options?)` | Validates numbers. Supports `{ min, max, coerce, default }`. |
-| `tex.boolean()` | `tex.boolean(options?)` | Validates booleans. Supports `{ coerce, default }`. Coerces `"true"`, `"false"`, `"1"`, `"0"`. |
+| `tex.string()` | `tex.string(options?)` | Validates strings. Supports `{ min, max, length, pattern, trim, toLowerCase, toUpperCase, collapseWhitespace, escapeHtml, stripHtml, slugify, mask, preventSql, preventTraversal, coerce, default }`. `pattern` is a `RegExp` checked after trimming and case changes. |
+| `tex.number()` | `tex.number(options?)` | Validates finite numbers. Supports `{ int, min, max, coerce, default }`; `int: true` accepts whole numbers only. |
+| `tex.boolean()` | `tex.boolean(options?)` | Validates booleans. Supports `{ coerce, default }`. Coerces `"true"`, `"false"`, `"1"`, `"0"` (any case, surrounding spaces ignored) and `1` / `0`. |
 | `tex.email()` | `tex.email(options?)` | Validates RFC-compliant email formatting. Supports `{ trim, toLowerCase, mask, default }`. |
+| `tex.url()` | `tex.url(options?)` | Validates absolute URLs. Only `http` and `https` unless `{ protocols: ['https'] }` says otherwise, so `javascript:` links are rejected. Supports `{ trim, min, max, pattern, default }`. |
 | `tex.uuid()` | `tex.uuid(options?)` | Validates UUID strings. Supports `{ version: 1 \| 4, default }`. |
 | `tex.cuid()` | `tex.cuid(options?)` | Validates CUID identifiers. Supports `{ default }`. |
 | `tex.password()` | `tex.password(options?)` | Validates password complexity. Supports `{ min, max, requireNumbers, requireSymbols, requireUppercase, requireLowercase }`. |
 | `tex.creditCard()` | `tex.creditCard(options?)` | Validates credit card numbers using the Luhn algorithm. Supports `{ mask: true }`. |
-| `tex.date()` | `tex.date(options?)` | Validates JavaScript `Date` instances or ISO strings with `{ coerce: true, minDate, maxDate, default }`. |
+| `tex.date()` | `tex.date(options?)` | Validates a `Date`, a date string or a timestamp, with `{ coerce, minDate, maxDate, default }`. An unparsable value is rejected, and the parsed value is always a `Date` (`coerce` is accepted but no longer needed). |
 | `tex.array()` | `tex.array(schema, options?)` | Validates arrays of items. Accepts primitive schemas, `tex.object(...)`, or shorthand `{ ... }`. Supports `{ min, max, dedupe, coerce, default }`. |
 | `tex.enum()` | `tex.enum(values, options?)` | Validates against an allowed list of string literals. Supports `{ default }`. |
 | `tex.literal()` | `tex.literal(value, options?)` | Validates against an exact primitive value (`string \| number \| boolean`). |
@@ -78,7 +79,7 @@ All primitive builders accept modifier options directly in their configuration a
 | **Optional** | `{ optional: true }` | `.optional()` | Allows `undefined`. |
 | **Nullable** | `{ nullable: true }` | `.nullable()` | Allows `null`. |
 | **Nullish** | `{ nullish: true }` | `.nullish()` | Allows both `null` and `undefined`. |
-| **Default** | `{ default: value \| () => value }` | N/A | Used when the field is missing. A client may omit the field, and after parsing it always has a value. |
+| **Default** | `{ default: value \| () => value }` | `.default(value)` | Used when the field is missing (or blank, for a form field). A client may omit the field, and after parsing it always has a value. Object and array defaults are copied, so parses never share them. |
 
 ```typescript filename="example.ts"
 import { tex } from 'exisjs/validator'
@@ -92,6 +93,21 @@ const Schema = tex.object({
 })
 ```
 
+Every method returns a new schema, so a field schema can be shared between objects: `Name.optional()` in one object does not make `Name` optional anywhere else. `parse()` never modifies the object it is given; it returns a new one.
+
+Nested object schemas take the same modifiers as methods: `.optional()`, `.nullable()` and `.nullish()`. A plain object literal is also a nested object:
+
+```typescript filename="src/http/leads/schema.ts"
+const Address = tex.object({ city: tex.string(), pin: tex.string({ optional: true }) })
+
+export const UpdateLead = tex.object({
+  status: tex.enum(['new', 'won', 'lost']),
+  address: Address.optional(), // may be left out
+  billing: Address.nullish(), // may be left out or sent as null to clear it
+  meta: { source: tex.string() }, // same as tex.object({ source: tex.string() })
+})
+```
+
 ### Input and Output Types
 
 A field with a `default` may be left out of a request but is always present after parsing, so the two sides have different types:
@@ -301,20 +317,27 @@ export function sanitizeTitle(input: string): string {
 | Category | Function | Description |
 | :--- | :--- | :--- |
 | **Security** | `sanitize.escapeHtml(val)` | Escapes HTML entities (`&`, `<`, `>`, `"`, `'`). |
-| **Security** | `sanitize.stripHtml(val)` | Removes HTML tags and element markup. |
-| **Security** | `sanitize.preventSql(val)` | Neutralizes common SQL injection sequences. |
-| **Security** | `sanitize.preventTraversal(val)` | Strips directory traversal sequences (`../`, `..\\`). |
-| **Masking** | `sanitize.maskEmail(val)` | Masks email local-parts (e.g. `u***r@example.com`). |
+| **Security** | `sanitize.stripHtml(val)` | Removes tags, comments, and `<script>` / `<style>` elements with their content. |
+| **Security** | `sanitize.stripControlChars(val)` | Removes invisible control characters and bidirectional overrides. |
+| **Security** | `sanitize.preventSql(val)` | Rejects common SQL injection probes (the field fails validation). |
+| **Security** | `sanitize.preventTraversal(val)` | Rejects `..` path segments, also percent-encoded, and NUL bytes. |
+| **Masking** | `sanitize.maskEmail(val)` | Masks email local-parts (e.g. `us***@example.com`). |
 | **Masking** | `sanitize.maskString(val)` | Masks characters leaving only boundary characters visible. |
 | **Formatting** | `sanitize.trim(val)` | Trims leading and trailing whitespace. |
 | **Formatting** | `sanitize.toLowerCase(val)` | Converts string to lowercase. |
 | **Formatting** | `sanitize.toUpperCase(val)` | Converts string to uppercase. |
 | **Formatting** | `sanitize.collapseWhitespace(val)` | Replaces consecutive whitespace with a single space. |
 | **Formatting** | `sanitize.slugify(val)` | Converts string into URL-friendly slug format. |
-| **Formatting** | `sanitize.truncate(length)(val)` | Truncates string to specified maximum length. |
+| **Formatting** | `sanitize.normalizeEmail(val)` | Trims and lowercases an email address. |
+| **Formatting** | `sanitize.truncate(length)(val)` | Truncates to `length` characters without splitting an emoji. |
+| **Numbers** | `sanitize.round(decimals)(val)`, `sanitize.clamp(min, max)(val)` | Rounds; limits to a range. |
 | **Arrays & Objects** | `sanitize.dedupe(array)` | Removes duplicate elements using a `Set`. |
 | **Arrays & Objects** | `sanitize.compact(array)` | Removes `null`, `undefined`, and empty string values. |
-| **Arrays & Objects** | `sanitize.omit(keys)(obj)` | Omits specified keys from an object. |
+| **Arrays & Objects** | `sanitize.trimElements(array)`, `sanitize.limitLength(n)(array)` | Trims string items; keeps the first `n` items. |
+| **Arrays & Objects** | `sanitize.pick(keys)(obj)`, `sanitize.omit(keys)(obj)` | Keeps or removes keys (`pick` ignores inherited keys). |
+| **Arrays & Objects** | `sanitize.deepTrim(value)` | Trims every string in a nested object or array. |
+
+Sanitizers run before the field's type check. One that throws, such as `preventSql`, fails that field with a `400` (code `SANITIZATION_FAILED`) instead of crashing the request.
 
 ---
 
@@ -340,6 +363,16 @@ export const RegisterSchema = tex.object({
 })
 ```
 
+A field's `.refine()` and `.sanitize()` run wherever the field is: in nested objects, array items and record values too. An object's `.refine(fn, { message, path })` runs once all its fields are valid and reports the error on `path`. `parseAsync()` (used for route validation) also runs `.refineAsync()` rules at every depth.
+
+To handle failures without `try` / `catch`, use `safeParse()`:
+
+```typescript
+const result = RegisterSchema.safeParse(input)
+if (!result.success) return { errors: result.errors } // [{ path, message, code, ... }]
+const user = result.data
+```
+
 ---
 
 ## Discriminated Unions (`tex.discriminatedUnion`)
@@ -633,6 +666,8 @@ When incoming requests fail validation, ExisJS returns an HTTP `400 Bad Request`
 }
 ```
 
+Every failing value is listed: each bad item of an array, each bad field of a nested object, up to 100 entries. Common `code` values: `MISSING_REQUIRED_FIELD`, `INVALID_TYPE`, `VALUE_TOO_SMALL`, `VALUE_TOO_LARGE`, `INVALID_LENGTH`, `INVALID_FORMAT` (pattern), `INVALID_EMAIL`, `INVALID_URL`, `INVALID_ENUM_VALUE`, `INVALID_DATE`, `DATE_TOO_EARLY`, `DATE_TOO_LATE`, `ARRAY_TOO_SHORT`, `ARRAY_TOO_LONG`, `UNRECOGNIZED_KEYS` (strict mode), `CUSTOM_VALIDATION` (`refine`), `SANITIZATION_FAILED`.
+
 In development mode (`NODE_ENV=development`), ExisJS also outputs a tabular summary of the failed validation constraints to the terminal.
 
 ---

package/dist/docs/reference/README.md

@@ -8,22 +8,22 @@ This directory contains complete, information-dense API references, TypeScript i
 
 | Module / Entrypoint | Document                                                                               | Description                                                                                            |
 | :------------------ | :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- |
-| `exisjs`            | [`exis.mdx`](file:///z:/projects/framework/exisjs/docs/reference/exis.mdx)             | Root application builder (`exis` / `defineApp`), `App` instance methods, and process resolvers.        |
-| `exisjs/config`     | [`config.mdx`](file:///z:/projects/framework/exisjs/docs/reference/config.mdx)         | Configuration schema (`ExisConfig`, `WatchConfig`, `DevConfig`), environment parsing, and phases.      |
-| `exisjs/router`     | [`router.mdx`](file:///z:/projects/framework/exisjs/docs/reference/router.mdx)         | Functional route builder (`route.*`, `controller`), `Router` engine, and request/response types.       |
-| `exisjs/decorators` | [`decorators.mdx`](file:///z:/projects/framework/exisjs/docs/reference/decorators.mdx) | Class, method, and parameter decorators for OOP architecture (`@Controller`, `@Get`, `@Body`).         |
-| `exisjs/validator`  | [`validator.mdx`](file:///z:/projects/framework/exisjs/docs/reference/validator.mdx)   | `TexEngine` validator suite (`tex.*`), schema modifiers (`.optional()`, `.default()`), and pipes.      |
-| `exisjs/database`   | [`database.mdx`](file:///z:/projects/framework/exisjs/docs/reference/database.mdx)     | Database lifecycle coordinator (`registerDatabase`, `DatabaseManager`), and transactions.              |
-| `exisjs/logger`     | [`logger.mdx`](file:///z:/projects/framework/exisjs/docs/reference/logger.mdx)         | Structured Pino logger interface, log levels, sensitive credential redaction, and formatters.          |
-| `exisjs/di`         | [`di.mdx`](file:///z:/projects/framework/exisjs/docs/reference/di.mdx)                 | Inversion of Control `Container`, dependency injection tokens, `inject()`, and `forwardRef()`.         |
-| `exisjs/error`      | [`error.mdx`](file:///z:/projects/framework/exisjs/docs/reference/error.mdx)           | HTTP exception hierarchy (`HttpError`, `BadRequestException`), error codes, and JSON envelopes.        |
-| `exisjs/middleware` | [`middleware.mdx`](file:///z:/projects/framework/exisjs/docs/reference/middleware.mdx) | Built-in middleware suite: Helmet, CORS, CSRF, rate limiting, IP filtering, and multipart uploads.     |
-| `exisjs/context`    | [`context.mdx`](file:///z:/projects/framework/exisjs/docs/reference/context.mdx)       | `AsyncLocalStorage` request context API (`getRequest`, `getResponse`, `getContext`, `after`).          |
-| `exisjs/cron`       | [`cron.mdx`](file:///z:/projects/framework/exisjs/docs/reference/cron.mdx)             | Task scheduler (`cron()`, `@Cron()`), interval timers, presets, and `CronManager` runtime controls.    |
-| `exisjs/sanitize`   | [`sanitize.mdx`](file:///z:/projects/framework/exisjs/docs/reference/sanitize.mdx)     | Security cleaners (`escapeHtml`, `preventSql`) and data transform utilities.          |
-| `exisjs/swagger`    | [`swagger.mdx`](file:///z:/projects/framework/exisjs/docs/reference/swagger.mdx)       | OpenAPI 3.1 specification generation, Swagger UI / Scalar interactive rendering, and decorators.       |
-| `exisjs/testing`    | [`testing.mdx`](file:///z:/projects/framework/exisjs/docs/reference/testing.mdx)       | Test runner (`node:test`), synthetic HTTP client (`createTestApp`), `expect` matchers, and `ex` mocks. |
-| `exisjs/plugin`     | [`plugin.mdx`](file:///z:/projects/framework/exisjs/docs/reference/plugin.mdx)         | Modular plugin development (`definePlugin`), lifecycle hooks, and dependency encapsulation.            |
+| `exisjs`            | [`exis.mdx`](./exis.mdx)             | Root application builder (`exis` / `defineApp`), `App` instance methods, and process resolvers.        |
+| `exisjs/config`     | [`config.mdx`](./config.mdx)         | Configuration schema (`ExisConfig`, `WatchConfig`, `DevConfig`), environment parsing, and phases.      |
+| `exisjs/router`     | [`router.mdx`](./router.mdx)         | Functional route builder (`route.*`, `controller`), `Router` engine, and request/response types.       |
+| `exisjs/decorators` | [`decorators.mdx`](./decorators.mdx) | Class, method, and parameter decorators for OOP architecture (`@Controller`, `@Get`, `@Body`).         |
+| `exisjs/validator`  | [`validator.mdx`](./validator.mdx)   | `TexEngine` validator suite (`tex.*`), schema modifiers (`.optional()`, `.default()`), and pipes.      |
+| `exisjs/database`   | [`database.mdx`](./database.mdx)     | Database lifecycle coordinator (`registerDatabase`, `DatabaseManager`), and transactions.              |
+| `exisjs/logger`     | [`logger.mdx`](./logger.mdx)         | Structured Pino logger interface, log levels, sensitive credential redaction, and formatters.          |
+| `exisjs/di`         | [`di.mdx`](./di.mdx)                 | Inversion of Control `Container`, dependency injection tokens, `inject()`, and `forwardRef()`.         |
+| `exisjs/error`      | [`error.mdx`](./error.mdx)           | HTTP exception hierarchy (`HttpError`, `BadRequestException`), error codes, and JSON envelopes.        |
+| `exisjs/middleware` | [`middleware.mdx`](./middleware.mdx) | Built-in middleware suite: Helmet, CORS, CSRF, rate limiting, IP filtering, and multipart uploads.     |
+| `exisjs/context`    | [`context.mdx`](./context.mdx)       | `AsyncLocalStorage` request context API (`getRequest`, `getResponse`, `getContext`, `after`).          |
+| `exisjs/cron`       | [`cron.mdx`](./cron.mdx)             | Task scheduler (`cron()`, `@Cron()`), interval timers, presets, and `CronManager` runtime controls.    |
+| `exisjs/sanitize`   | [`sanitize.mdx`](./sanitize.mdx)     | Security cleaners (`escapeHtml`, `preventSql`) and data transform utilities.          |
+| `exisjs/swagger`    | [`swagger.mdx`](./swagger.mdx)       | OpenAPI 3.1 specification generation, Swagger UI / Scalar interactive rendering, and decorators.       |
+| `exisjs/testing`    | [`testing.mdx`](./testing.mdx)       | Test runner (`node:test`), synthetic HTTP client (`createTestApp`), `expect` matchers, and `ex` mocks. |
+| `exisjs/plugin`     | [`plugin.mdx`](./plugin.mdx)         | Modular plugin development (`definePlugin`), lifecycle hooks, and dependency encapsulation.            |
 
 ---
 

package/dist/docs/reference/config.mdx

@@ -175,7 +175,7 @@ The root configuration schema accepted by `exis.config.ts`:
 | `trustProxy` | `boolean \| number` | `false` | `true`: trust all proxy headers (`X-Forwarded-For`, `CF-Connecting-IP`, `True-Client-IP`, `X-Real-IP`). `N`: trust only the N closest hops in `X-Forwarded-For`, counting the socket peer; CDN headers are ignored. |
 | `bodyLimit` | `number` | `10485760` (10MB) | Maximum payload size in bytes for JSON and URL-encoded request bodies. |
 | `compression` | `boolean` | `false` | Enables gzip and Brotli response compression. |
-| `etag` | `boolean` | `false` | Enables ETag computation for dynamic responses. |
+| `etag` | `boolean` | `false` | Weak ETags on successful GET/HEAD responses, and `304` for a matching `If-None-Match`. |
 | `debugRouting` | `boolean` | `false` | Logs the matched file-system route file and applied boundaries for every request. |
 | `asyncContext` | `boolean` | `false` | Enables `AsyncLocalStorage` context tracking (`getContext()`). |
 | `transformResponse` | `boolean \| ((data: any, req: any, res: any) => any)` | `false` | Global transformation function to wrap route responses in a standardized envelope. |
@@ -299,6 +299,7 @@ export interface DevConfig {
   binaryInterval?: number
   extensions?: string[]
   debounceMs?: number
+  lazyRoutes?: boolean // default true: load each route file on its first request
 }
 ```
 

package/dist/docs/reference/database.mdx

@@ -59,6 +59,7 @@ function registerDatabase(
 | `connect` | `() => Promise<void> \| void` | Asynchronous callback establishing client connection pools. |
 | `disconnect` | `() => Promise<void> \| void` | Asynchronous callback to safely terminate open sockets and pools. |
 | `healthCheck` / `isHealthy` | `() => Promise<boolean \| DatabaseHealthInfo> \| boolean \| DatabaseHealthInfo` | Optional callback returning health status boolean or detailed metrics. |
+| `healthTimeoutMs` | `number` | How long the health check may take before it is reported as `status: 'error'`, so an unresponsive database fails `/_ready` instead of hanging it. Default `5000`. |
 
 #### Example: Prisma Lifecycle Registration
 
@@ -97,9 +98,9 @@ Static singleton registry coordinating all registered database adapters.
 | Method | Signature | Description |
 | :--- | :--- | :--- |
 | `register(db)` | `(db: DatabaseRegistration) => void` | Adds a database adapter to the manager. |
-| `connectAll()` | `() => Promise<void>` | Connects all registered database instances concurrently. |
+| `connectAll()` | `() => Promise<void>` | Connects all registered databases in parallel, so boot waits for the slowest one rather than the sum. If any fail, the error names each failed database (`error.failures` lists them); the others stay connected and a later call retries only the failed ones. |
 | `disconnectAll()` | `() => Promise<void>` | Closes all database connections gracefully using `Promise.allSettled`. |
-| `checkHealth()` | `() => Promise<{ healthy: boolean; databases: Record<string, DatabaseHealthInfo> }>` | Executes health checks across all registered databases and aggregates results. |
+| `checkHealth()` | `() => Promise<{ healthy: boolean; databases: Record<string, DatabaseHealthInfo> }>` | Runs every database's health check in parallel, each limited by its `healthTimeoutMs`. Calls made while a check is running share its result, so frequent probes from several load balancers cost one round of pings. |
 | `clear()` | `() => void` | Clears all registered database adapters (useful for test tear-downs). |
 
 #### Health Output Structures

package/dist/docs/reference/middleware.mdx

@@ -317,6 +317,6 @@ app.use(fromExpress(morgan('combined')))
 | `requestId()` | `() => Handler` | Injects a unique `X-Request-Id` into request and response headers. |
 | `requestLogger(options?)` | `(options?: LoggerConfig) => Handler` | Formats and logs request completion timings and status codes. |
 | `serveStatic(root, options?)` | `(root: string, options?: StaticOptions) => Handler` | Serves static assets from disk with caching headers and streaming backpressure. |
-| `conditionalGet()` | `() => Handler` | Enables ETag validation and `304 Not Modified` responses. |
+| `conditionalGet()` | `() => Handler` | Turns on automatic ETags and `304 Not Modified` for the routes it is applied to (as `etag: true` does app-wide). |
 | `validate(schema)` | `(schema: ValidateSchema) => Handler` | Validates request parameters against a `TexEngine` schema. |
 

package/dist/docs/reference/sanitize.mdx

@@ -1,134 +1,129 @@
----
-title: "exisjs/sanitize"
-description: "API Reference for ExisJS data sanitization engine: string cleaners, safeSanitize, and object transformers."
-nextUrl: "/docs/reference/swagger"
-nextTitle: "Swagger Reference"
----
-
-# `exisjs/sanitize`
-
-The `exisjs/sanitize` module provides pure data sanitization functions for cleaning and normalizing input strings, numbers, dates, arrays, and complex objects before business logic execution. It includes security transforms for XSS escaping, HTML stripping, and basic SQL injection and path traversal probe detection.
-
----
-
-## Module Exports
-
-```typescript
-import { sanitize } from 'exisjs/sanitize'
-```
-
----
-
-## 1. Security Sanitizers
-
-The SQL and path traversal checks reject common probe strings; they complement, and never replace, parameterized queries and resolved-path checks.
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.escapeHtml` | `(val: string) => string` | Escapes `&`, `<`, `>`, `"`, and `'` into HTML entity equivalents. |
-| `sanitize.stripHtml` | `(val: string) => string` | Strips all HTML tags and markup characters from the string. |
-| `sanitize.preventSql` | `(val: string) => string` | Neutralizes common SQL injection sequences and comment tokens. |
-| `sanitize.preventTraversal` | `(val: string) => string` | Strips directory traversal sequences (`../`, `..\\`, null bytes). |
-| `sanitize.maskEmail` | `(val: string) => string` | Obfuscates email addresses (e.g., `al***@example.com`). |
-| `sanitize.maskString` | `(val: string) => string` | Masks sensitive string segments for logging or auditing. |
-
----
-
-## 2. Text & String Sanitizers
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.trim` | `(val: string) => string` | Strips leading and trailing whitespace. |
-| `sanitize.toLowerCase` | `(val: string) => string` | Converts all characters to lowercase. |
-| `sanitize.toUpperCase` | `(val: string) => string` | Converts all characters to uppercase. |
-| `sanitize.collapseWhitespace`| `(val: string) => string` | Collapses consecutive whitespace, tabs, and newlines into a single space. |
-| `sanitize.normalizeUnicode` | `(val: string) => string` | Normalizes Unicode characters to Canonical Decomposition followed by Canonical Composition (NFC). |
-| `sanitize.slugify` | `(val: string) => string` | Converts strings into clean URL-friendly slugs (`"Hello World!"` $\to$ `"hello-world"`). |
-| `sanitize.truncate(length)` | `(length: number) => (val: string) => string` | Truncates strings exceeding the specified maximum length. |
-| `sanitize.removeNonAlphanumeric` | `(val: string) => string` | Strips all characters except standard ASCII letters and numbers. |
-| `sanitize.normalizeLineEndings` | `(val: string) => string` | Converts Windows CRLF (`\r\n`) to POSIX LF (`\n`). |
-
----
-
-## 3. Numbers & Dates
-
-### Number Transforms
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.round` | `(val: number) => number` | Rounds a float to the nearest integer. |
-| `sanitize.clamp(min, max)` | `(min: number, max: number) => (val: number) => number` | Constrains numeric input to fall within `[min, max]`. |
-| `sanitize.defaultIfNaN(fallback)` | `(fallback: number) => (val: number) => number` | Returns the fallback number if input evaluates to `NaN`. |
-
-### Date Transforms
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.normalizeToIsoString` | `(val: Date) => string` | Formats a Date object into an ISO 8601 string representation. |
-| `sanitize.stripTime` | `(val: Date) => Date` | Resets hours, minutes, seconds, and milliseconds to `00:00:00.000`. |
-
----
-
-## 4. Arrays & Complex Objects
-
-### Array Transforms
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.dedupe` | `<T>(val: T[]) => T[]` | Removes duplicate values preserving first-seen ordering. |
-| `sanitize.compact` | `<T>(val: T[]) => T[]` | Removes `null`, `undefined`, and empty strings (`""`). |
-| `sanitize.trimElements` | `(val: string[]) => string[]` | Trims whitespace from all string elements in an array. |
-| `sanitize.limitLength(n)` | `<T>(length: number) => (val: T[]) => T[]` | Slices an array to at most `length` elements. |
-
-### Object Transforms
-
-| Function | Signature | Description |
-| :--- | :--- | :--- |
-| `sanitize.stripUnknownKeys(keys)` | `<T>(allowedKeys: (keyof T)[]) => (val: T) => T` | Strips unlisted properties from an object. |
-| `sanitize.deepTrimStringValues` | `<T>(val: T) => T` | Recursively walks an object graph and trims all nested string properties. |
-| `sanitize.omit(keys)` | `<T, K extends keyof T>(keys: K[]) => (val: T) => Omit<T, K>` | Removes specified keys from an object. |
-| `sanitize.pick(keys)` | `<T, K extends keyof T>(keys: K[]) => (val: T) => Pick<T, K>` | Returns an object containing only the specified keys. |
-
----
-
-## 5. Integration with TexEngine Validation
-
-Sanitizers integrate with `tex` validator chains using the `.sanitize()` modifier. Sanitization occurs **before** rule validation checks:
-
-```typescript filename="src/http/articles/schema.ts"
-import { tex } from 'exisjs/validator'
-import { sanitize } from 'exisjs/sanitize'
-
-export const CreateArticleSchema = tex.object({
-  title: tex
-    .string({ min: 5, max: 120 })
-    .sanitize(sanitize.trim, sanitize.collapseWhitespace),
-
-  slug: tex
-    .string()
-    .sanitize(sanitize.slugify),
-
-  content: tex
-    .string()
-    .sanitize(sanitize.stripHtml),
-
-  tags: tex
-    .array(tex.string())
-    .sanitize(sanitize.dedupe, sanitize.compact),
-})
-```
-
----
-
-## 6. Standalone Usage Example
-
-```typescript filename="src/services/import.service.ts"
-import { sanitize } from 'exisjs/sanitize'
-
-export function processUserInput(rawContent: string): string {
-  const step1 = sanitize.stripHtml(rawContent)
-  const step2 = sanitize.collapseWhitespace(step1)
-  const clean = sanitize.trim(step2)
-  return clean
-}
-```
+---
+title: "exisjs/sanitize"
+description: "API Reference for ExisJS data sanitization engine: string cleaners, safeSanitize, and object transformers."
+nextUrl: "/docs/reference/swagger"
+nextTitle: "Swagger Reference"
+---
+
+# `exisjs/sanitize`
+
+The `exisjs/sanitize` module provides pure data sanitization functions for cleaning and normalizing input strings, numbers, dates, arrays, and complex objects before business logic execution. It includes security transforms for XSS escaping, HTML stripping, and basic SQL injection and path traversal probe detection.
+
+---
+
+## Module Exports
+
+```typescript
+import { sanitize } from 'exisjs/sanitize'
+```
+
+---
+
+## 1. Security Sanitizers
+
+The SQL and path traversal checks reject common probe strings; they complement, and never replace, parameterized queries and resolved-path checks. A sanitizer that throws inside `.sanitize()` becomes a `400` validation error for that field (code `SANITIZATION_FAILED`).
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `sanitize.escapeHtml` | `(val: string) => string` | Escapes `&`, `<`, `>`, `"`, and `'` into HTML entities. Use it for text shown in HTML. |
+| `sanitize.stripHtml` | `(val: string) => string` | Removes tags, comments, and `<script>` / `<style>` elements with their content. A `<` that does not start a tag (`a < b`) is kept. |
+| `sanitize.stripControlChars` | `(val: string) => string` | Removes invisible control characters (keeps tab and line breaks) and the bidirectional overrides used to disguise text. |
+| `sanitize.preventSql` | `(val: string) => string` | Throws on common SQL injection probes (`' or 1=1`, `union select`, ...). |
+| `sanitize.preventTraversal` | `(val: string) => string` | Throws on a `..` path segment (also `\` separators and percent-encoded forms such as `%2e%2e%2f`) and on NUL bytes. `report..final.pdf` is allowed. |
+| `sanitize.maskEmail` | `(val: string) => string` | Obfuscates email addresses (e.g., `al***@example.com`). |
+| `sanitize.maskString` | `(val: string) => string` | Keeps the first and last two characters (`ab****yz`). |
+
+---
+
+## 2. Text & String Sanitizers
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `sanitize.trim` | `(val: string) => string` | Strips leading and trailing whitespace. |
+| `sanitize.toLowerCase` | `(val: string) => string` | Converts all characters to lowercase. |
+| `sanitize.toUpperCase` | `(val: string) => string` | Converts all characters to uppercase. |
+| `sanitize.collapseWhitespace`| `(val: string) => string` | Collapses consecutive whitespace, tabs, and newlines into a single space. |
+| `sanitize.normalizeUnicode` | `(val: string) => string` | Normalizes to Unicode NFC, so visually equal strings compare equal. |
+| `sanitize.normalizeEmail` | `(val: string) => string` | Trims and lowercases an email address. |
+| `sanitize.slugify` | `(val: string) => string` | URL-friendly slug; accented letters keep their base letter (`"Café Crème"` $	o$ `"cafe-creme"`). |
+| `sanitize.truncate(length)` | `(length: number) => (val: string) => string` | Shortens to `length` characters without splitting an emoji in two. |
+| `sanitize.removeNonAlphanumeric` | `(val: string) => string` | Strips all characters except ASCII letters and digits. |
+| `sanitize.normalizeLineEndings` | `(val: string) => string` | Converts `
+` and lone `
+`. |
+
+---
+
+## 3. Numbers
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `sanitize.round(decimals?)` | `(decimals = 0) => (val: number) => number` | Rounds to `decimals` places. |
+| `sanitize.clamp(min, max)` | `(min: number, max: number) => (val: number) => number` | Constrains a number to `[min, max]`. |
+
+---
+
+## 4. Arrays & Objects
+
+### Array Transforms
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `sanitize.dedupe` | `<T>(val: T[]) => T[]` | Removes duplicate values preserving first-seen ordering. |
+| `sanitize.compact` | `<T>(val: T[]) => T[]` | Removes `null`, `undefined`, and empty strings (`""`). |
+| `sanitize.trimElements` | `(val: string[]) => string[]` | Trims every string item. |
+| `sanitize.limitLength(n)` | `(length: number) => <T>(val: T[]) => T[]` | Keeps the first `length` items. |
+
+### Object Transforms
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `sanitize.pick(keys)` | `<T, K extends keyof T>(keys: K[]) => (val: T) => Pick<T, K>` | Keeps only the listed keys the object itself has (never inherited ones such as `constructor`). |
+| `sanitize.omit(keys)` | `<T, K extends keyof T>(keys: K[]) => (val: T) => Omit<T, K>` | Removes the listed keys. |
+| `sanitize.deepTrim` | `<T>(val: T) => T` | Trims every string in a nested object or array. |
+
+Every sanitizer passes values of another type through unchanged (a string sanitizer returns a number as is, an array sanitizer returns a non-array as is), so they are safe on optional and nullable fields.
+
+---
+
+## 5. Integration with TexEngine Validation
+
+Sanitizers integrate with `tex` validator chains using the `.sanitize()` modifier. Sanitization occurs **before** rule validation checks:
+
+```typescript filename="src/http/articles/schema.ts"
+import { tex } from 'exisjs/validator'
+import { sanitize } from 'exisjs/sanitize'
+
+export const CreateArticleSchema = tex.object({
+  title: tex
+    .string({ min: 5, max: 120 })
+    .sanitize(sanitize.trim, sanitize.collapseWhitespace),
+
+  slug: tex
+    .string()
+    .sanitize(sanitize.slugify),
+
+  content: tex
+    .string()
+    .sanitize(sanitize.stripHtml),
+
+  tags: tex
+    .array(tex.string())
+    .sanitize(sanitize.dedupe, sanitize.compact),
+})
+```
+
+---
+
+## 6. Standalone Usage Example
+
+```typescript filename="src/services/import.service.ts"
+import { sanitize } from 'exisjs/sanitize'
+
+export function processUserInput(rawContent: string): string {
+  const step1 = sanitize.stripHtml(rawContent)
+  const step2 = sanitize.collapseWhitespace(step1)
+  const clean = sanitize.trim(step2)
+  return clean
+}
+```

package/dist/docs/reference/validator.mdx

@@ -55,8 +55,9 @@ The `tex` instance exposes factory functions for all standard primitives, comple
 
 | Method | Return Type | Options Interface | Description |
 | :--- | :--- | :--- | :--- |
-| `tex.string(options?)` | `TexType<string>` | `TexStringOptions` | String validation with trimming, HTML escaping, min/max bounds, masking, coercion, and injection checks. |
-| `tex.number(options?)` | `TexType<number>` | `TexNumberOptions` | Number validation with optional string coercion (`coerce: true`) and min/max limits. |
+| `tex.string(options?)` | `TexType<string>` | `TexStringOptions` | String validation with trimming, HTML escaping, min/max/exact `length`, `pattern` (RegExp), masking, coercion, and injection checks. |
+| `tex.number(options?)` | `TexType<number>` | `TexNumberOptions` | Number validation with optional string coercion (`coerce: true`), whole numbers (`int: true`) and min/max limits. |
+| `tex.url(options?)` | `TexType<string>` | `TexUrlOptions` | Absolute URL; `http` / `https` only unless `protocols` lists others. |
 | `tex.boolean(options?)` | `TexType<boolean>` | `TexBooleanOptions` | Boolean validation with string/numeric coercion (`"true"`, `"1"` -> `true`). |
 | `tex.email(options?)` | `TexType<string>` | `TexStringOptions` | Standard RFC 5322 email format validation. |
 | `tex.uuid(options?)` | `TexType<string>` | `{ version?: 1 \| 4 }` | Validates UUID strings (v1 or v4). |
@@ -160,6 +161,8 @@ All `TexType` instances provide fluent modifier and documentation methods:
 | `.transform(fn)` | `<Out>(fn: (val: T) => Out) => TexTransformed<Out>` | Applies a synchronous transformation to validated field data. |
 | `.toOpenApi()` | `() => Record<string, any>` | Converts the type definition into an OpenAPI 3.1 schema object. |
 
+Every method returns a new schema and leaves the original unchanged, so one field schema can be reused in several objects.
+
 ---
 
 ## `TexEngine` Schema Object Methods
@@ -168,15 +171,20 @@ All `TexType` instances provide fluent modifier and documentation methods:
 
 | Method | Signature | Description |
 | :--- | :--- | :--- |
+| `optional()` | `() => TexEngine<T \| undefined>` | Used as a field of another object: the field may be left out. |
+| `nullable()` | `() => TexEngine<T \| null>` | Used as a field of another object: the field may be `null`. |
+| `nullish()` | `() => TexEngine<T \| null \| undefined>` | Used as a field of another object: the field may be left out or `null`. |
 | `partial()` | `() => TexEngine<Partial<T>>` | Returns a copy of the schema with all fields marked optional. |
 | `pick(keys)` | `<K extends keyof T>(keys: K[]) => TexEngine<Pick<T, K>>` | Creates a new schema containing only the specified keys. |
 | `omit(keys)` | `<K extends keyof T>(keys: K[]) => TexEngine<Omit<T, K>>` | Creates a new schema omitting the specified keys. |
 | `extend(shape)` | `<E>(extension: E) => TexEngine<T & ResolveSchema<E>>` | Merges additional or overridden fields into the existing schema. |
 | `merge(other)` | `<U>(other: TexEngine<U>) => TexEngine<T & U>` | Deeply merges two `TexEngine` schemas into a combined validator. |
+| `refine(fn, opts?)` | `(fn: (data: T) => boolean, opts?: string \| { message?, path? }) => TexEngine<T>` | A check across fields, run once every field is valid; the error is reported on `path`. |
 | `transform(fn)` | `<Out>(fn: (data: T) => Out) => TexTransformedEngine<T, Out>` | Applies post-validation data reshaping to the entire schema output. |
 | `parse(data)` | `(data: unknown) => T` | Synchronously parses and validates data, throwing `ValidatorError` on failure. |
 | `parseAsync(data)` | `(data: unknown) => Promise<T>` | Asynchronously parses and validates data, evaluating async refinements. |
-| `safeParse(data)` | `(data: unknown) => { success: true, data: T } \| { success: false, error: ValidatorError }` | Validates data without throwing exceptions. |
+| `safeParse(data)` | `(data: unknown) => { success: true, data: T } \| { success: false, errors, error: ValidatorError }` | Validates data without throwing; `errors` is the list of `{ path, message, code, ... }`. |
+| `safeParseAsync(data)` | `(data: unknown) => Promise<SafeParseResult<T>>` | `safeParse` that also runs async refinements. |
 | `toOpenApi()` | `() => Record<string, any>` | Translates the schema into an OpenAPI 3.1 JSON schema representation. |
 
 ---

package/dist/middleware/compression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,UAAU,CAAA;AAyB1D,wBAAgB,WAAW,IAAI,OAAO,CAoGrC"}
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/middleware/compression.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,UAAU,CAAA;AA0B1D,wBAAgB,WAAW,IAAI,OAAO,CAoGrC"}