exisjs 0.7.12 → 0.7.14

package/dist/docs/reference/sanitize.mdx

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