@venizia/ignis-docs 0.0.7 → 0.0.8-0

package/wiki/references/utilities/jsx.md

@@ -89,7 +89,7 @@ const pageContent = htmlContent({
 
 ## htmlResponse()
 
-Creates a standard OpenAPI response object for HTML endpoints, including success (200 OK) HTML response and JSON error responses for 4xx/5xx status codes.
+Creates a standard OpenAPI response object for HTML endpoints, including a success (200 OK) HTML response and a JSON error response for `4xx | 5xx` status codes using the `ErrorSchema`.
 
 ### Signature
 
@@ -120,7 +120,7 @@ function htmlResponse(opts: {
 ### Returns
 
 Returns an OpenAPI responses object with:
-- `200`: Success response with HTML content
+- `200`: Success response with HTML content (via `htmlContent()`)
 - `4xx | 5xx`: Error responses with JSON error schema
 
 ### Example
@@ -157,14 +157,16 @@ this.defineRoute({
 ### Basic HTML Route
 
 ```typescript
-import { BaseController, get, htmlResponse } from '@venizia/ignis';
+import { BaseRestController, get, htmlResponse } from '@venizia/ignis';
 
-export class PageController extends BaseController {
+export class PageController extends BaseRestController {
   @get({
-    path: '/home',
-    responses: htmlResponse({
-      description: 'Home page HTML',
-    }),
+    configs: {
+      path: '/home',
+      responses: htmlResponse({
+        description: 'Home page HTML',
+      }),
+    },
   })
   async getHomePage() {
     return this.context.html(
@@ -184,7 +186,7 @@ export class PageController extends BaseController {
 ### HTML Email Preview
 
 ```typescript
-import { BaseController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
+import { BaseRestController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const EmailRoutes = {
@@ -200,7 +202,7 @@ const EmailRoutes = {
   },
 } as const;
 
-export class EmailController extends BaseController {
+export class EmailController extends BaseRestController {
   @get({ configs: EmailRoutes.PREVIEW })
   async previewTemplate(c: TRouteContext) {
     const { templateId } = c.req.valid<{ templateId: string }>('param');
@@ -223,7 +225,7 @@ export class EmailController extends BaseController {
 ### Documentation Page
 
 ```typescript
-import { BaseController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
+import { BaseRestController, get, htmlResponse, TRouteContext, z } from '@venizia/ignis';
 import { HTTP } from '@venizia/ignis-helpers';
 
 const DocsRoutes = {
@@ -239,7 +241,7 @@ const DocsRoutes = {
   },
 } as const;
 
-export class DocsController extends BaseController {
+export class DocsController extends BaseRestController {
   @get({ configs: DocsRoutes.GET_SECTION })
   async getDocumentation(c: TRouteContext) {
     const { section } = c.req.valid<{ section: string }>('param');
@@ -270,16 +272,17 @@ export class DocsController extends BaseController {
 ### Admin Dashboard
 
 ```typescript
-import { BaseController, get, htmlResponse } from '@venizia/ignis';
-import { authenticate } from '../middleware/auth';
+import { BaseRestController, get, htmlResponse } from '@venizia/ignis';
 
-export class AdminController extends BaseController {
+export class AdminController extends BaseRestController {
   @get({
-    path: '/admin',
-    middleware: [authenticate({ role: 'admin' })],
-    responses: htmlResponse({
-      description: 'Admin dashboard',
-    }),
+    configs: {
+      path: '/admin',
+      middleware: [authenticate({ role: 'admin' })],
+      responses: htmlResponse({
+        description: 'Admin dashboard',
+      }),
+    },
   })
   async getDashboard() {
     const stats = await this.statsService.getAdminStats();
@@ -337,7 +340,7 @@ export class AdminController extends BaseController {
 ### 1. Use for Server-Side Rendering
 
 ```typescript
-// ✅ Good: Use htmlResponse for SSR routes
+// Good: Use htmlResponse for SSR routes
 const ProfileConfig = {
   method: HTTP.Methods.GET,
   path: '/profile/:userId',
@@ -352,29 +355,16 @@ async getUserProfile(c: TRouteContext) {
   return c.html(<UserProfile user={user} />);
 }
 
-// ❌ Bad: Don't use htmlResponse for API endpoints
-const BadConfig = {
-  method: HTTP.Methods.GET,
-  path: '/api/users/:userId',
-  request: { params: z.object({ userId: z.string() }) },
-  responses: htmlResponse({ description: 'User data' }), // Wrong!
-} as const;
-
-@get({ configs: BadConfig })
-async getUser(c: TRouteContext) {
-  const { userId } = c.req.valid<{ userId: string }>('param');
-  return { id: userId, name: 'John' }; // Should use jsonResponse
-}
+// Bad: Don't use htmlResponse for API endpoints — use jsonResponse instead
 ```
 
 ### 2. Combine with Authentication
 
 ```typescript
-// ✅ Good: Protect HTML routes with auth
 const SettingsConfig = {
   method: HTTP.Methods.GET,
   path: '/admin/settings',
-  authStrategies: [Authentication.STRATEGY_JWT],
+  authenticate: { strategies: ['jwt'] },
   responses: htmlResponse({ description: 'Settings page' }),
 } as const;
 
@@ -490,8 +480,10 @@ export const Layout = (props: { title: string; children: any }) => {
 import { Layout } from './components/Layout';
 
 @get({
-  path: '/',
-  responses: htmlResponse({ description: 'Home page' }),
+  configs: {
+    path: '/',
+    responses: htmlResponse({ description: 'Home page' }),
+  },
 })
 async getHome() {
   return this.context.html(
@@ -509,19 +501,23 @@ async getHome() {
 ### Pitfall 1: Missing HTML Wrapper
 
 ```typescript
-// ❌ Bad: Incomplete HTML
+// Bad: Incomplete HTML
 @get({
-  path: '/page',
-  responses: htmlResponse({ description: 'Page' }),
+  configs: {
+    path: '/page',
+    responses: htmlResponse({ description: 'Page' }),
+  },
 })
 async getPage() {
   return this.context.html(<div>Hello</div>); // Missing <html>, <head>, <body>
 }
 
-// ✅ Good: Complete HTML document
+// Good: Complete HTML document
 @get({
-  path: '/page',
-  responses: htmlResponse({ description: 'Page' }),
+  configs: {
+    path: '/page',
+    responses: htmlResponse({ description: 'Page' }),
+  },
 })
 async getPage() {
   return this.context.html(
@@ -536,22 +532,26 @@ async getPage() {
 ### Pitfall 2: Using htmlResponse for APIs
 
 ```typescript
-// ❌ Bad: HTML response for API
+// Bad: HTML response for API
 @get({
-  path: '/api/users',
-  responses: htmlResponse({ description: 'Users' }),
+  configs: {
+    path: '/api/users',
+    responses: htmlResponse({ description: 'Users' }),
+  },
 })
 async getUsers() {
   return { users: [...] }; // Should return HTML or use jsonResponse
 }
 
-// ✅ Good: Use jsonResponse for APIs
+// Good: Use jsonResponse for APIs
 @get({
-  path: '/api/users',
-  responses: jsonResponse({
-    description: 'Users list',
-    schema: z.object({ users: z.array(UserSchema) }),
-  }),
+  configs: {
+    path: '/api/users',
+    responses: jsonResponse({
+      description: 'Users list',
+      schema: z.object({ users: z.array(UserSchema) }),
+    }),
+  },
 })
 async getUsers() {
   return { users: await this.userService.findAll() };
@@ -564,7 +564,7 @@ async getUsers() {
 - **Related References:**
   - [Schema Utility](./schema.md) - JSON content and response helpers
   - [Controllers](../base/controllers.md) - Defining routes and handlers
-  - [OpenAPI Component](../components/swagger) - API documentation
+  - [OpenAPI Component](/extensions/components/swagger) - API documentation
 
 - **External Resources:**
   - [Hono JSX Documentation](https://hono.dev/guides/jsx)

package/wiki/references/utilities/module.md

@@ -1,16 +1,18 @@
 # Module Utility
 
-The Module utility provides a simple function to validate the existence of a Node.js module at runtime.
+The Module utility provides a function to validate the existence of Node.js modules at runtime. It uses `createRequire` from `node:module` rooted at the application's `process.cwd()/node_modules`, so peer dependencies in the consuming application are properly resolved even though this utility lives inside `packages/helpers`.
 
 ## `validateModule`
 
-The `validateModule` function checks if a list of modules can be resolved. If a module is not found, it throws a descriptive error, prompting the developer to install it. This is particularly useful for features that have optional peer dependencies.
+The `validateModule` function checks if a list of modules can be resolved. If a module is not found, it logs the error and throws a descriptive error, prompting the developer to install it. This is particularly useful for features that have optional peer dependencies.
 
 ### `validateModule(opts)`
 
 -   `opts` (object):
-    -   `scope` (string, optional): A string to identify the feature or component that requires the module, making the error message more informative.
-    -   `modules` (Array<string>): An array of module names to validate.
+    -   `scope` (string, optional): A string to identify the feature or component that requires the module, making the error message more informative. Defaults to empty string.
+    -   `modules` (Array<string>): An array of module names to validate. Defaults to empty array.
+
+This is an `async` function, though it performs synchronous resolution internally.
 
 ### Example
 
@@ -24,7 +26,7 @@ export class SwaggerComponent extends BaseComponent {
 
   override async binding() {
     // This will throw an error if '@hono/swagger-ui' is not installed
-    validateModule({ scope: SwaggerComponent.name, modules: ['@hono/swagger-ui'] });
+    await validateModule({ scope: SwaggerComponent.name, modules: ['@hono/swagger-ui'] });
 
     const { swaggerUI } = await import('@hono/swagger-ui');
 
@@ -33,7 +35,7 @@ export class SwaggerComponent extends BaseComponent {
 }
 ```
 
-If the module is missing, the application will fail to start with an error message like:
+If the module is missing, the application will fail with an error message like:
 
 ```
 [validateModule] @hono/swagger-ui is required for SwaggerComponent. Please install '@hono/swagger-ui'

package/wiki/references/utilities/parse.md

@@ -9,17 +9,19 @@ The Parse utility provides a collection of functions for data type checking, con
 
 ## Type Conversion
 
--   **`int(input)`**: Parses a value to an integer. Handles string with commas and defaults to `0` if the input is invalid.
--   **`float(input, digit = 2)`**: Parses a value to a float, rounding to a specified number of digits. Handles string with commas and defaults to `0` if the input is invalid.
--   **`toBoolean(input)`**: Converts various string/number representations (e.g., `'true'`, `'1'`, `1`) to a boolean.
--   **`toStringDecimal(input, digit = 2)`**: Formats a number to a string with a specified number of decimal places, using locale-specific formatting.
+-   **`int(input)`**: Parses a value to an integer. Handles strings with commas and defaults to `0` if the input is invalid.
+-   **`float(input, digit = 2)`**: Parses a value to a float, rounding to a specified number of digits. Handles strings with commas and defaults to `0` if the input is invalid.
+-   **`toBoolean(input)`**: Converts a value to a boolean. Returns `false` for empty string, `'false'`, `'0'`, `false`, `0`, `null`, and `undefined`. Returns `true` for everything else.
+-   **`toStringDecimal(input, digit = 2, options?)`**: Formats a number to a string with a specified number of decimal places. By default uses locale-specific formatting (`useLocaleFormat: true`). When `useLocaleFormat` is `false`, uses `toFixed()` instead.
 
 ```typescript
-import { int, float, toBoolean } from '@venizia/ignis-helpers';
+import { int, float, toBoolean, toStringDecimal } from '@venizia/ignis-helpers';
 
 const myInt = int('1,000'); // => 1000
 const myFloat = float('1,234.567', 2); // => 1234.57
 const myBool = toBoolean('true'); // => true
+const formatted = toStringDecimal(1234.5, 2); // => '1,234.50'
+const fixed = toStringDecimal(1234.5, 2, { useLocaleFormat: false }); // => '1234.50'
 ```
 
 ## String and Object Transformation
@@ -59,17 +61,22 @@ getNumberValue('1.234,56', { method: 'float', locale: 'eu' }); // => 1234.56
 
 ## Array Transformation
 
--   **`parseArrayToRecordWithKey(opts)`**: Transforms an array of objects into a record (plain object), using a specified property of the objects as keys.
--   **`parseArrayToMapWithKey(arr, keyMap)`**: Transforms an array of objects into a `Map`, using a specified property of the objects as keys. This is useful for efficient lookups.
+-   **`parseArrayToRecordWithKey(opts)`**: Transforms an array of objects into a record (plain object), using a specified property of the objects as keys. Takes an options object with `arr` and `keyMap` properties. Throws an error if `keyMap` is not found in an element. Last element wins on duplicate keys.
+-   **`parseArrayToMapWithKey(arr, keyMap)`**: Transforms an array of objects into a `Map`, using a specified property of the objects as keys. Takes positional arguments (not an options object). Throws an error if `keyMap` is not found in an element. Last element wins on duplicate keys.
 
 ```typescript
-import { parseArrayToMapWithKey } from '@venizia/ignis-helpers';
+import { parseArrayToRecordWithKey, parseArrayToMapWithKey } from '@venizia/ignis-helpers';
 
 const users = [
   { id: 1, name: 'Alice' },
   { id: 2, name: 'Bob' },
 ];
 
+// Record (options object pattern)
+const usersRecord = parseArrayToRecordWithKey({ arr: users, keyMap: 'id' });
+// => { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } }
+
+// Map (positional arguments)
 const usersMap = parseArrayToMapWithKey(users, 'id');
 // => Map { 1 => { id: 1, name: 'Alice' }, 2 => { id: 2, name: 'Bob' } }
 
@@ -79,7 +86,7 @@ const user = usersMap.get(1);
 
 ## Unique ID
 
--   **`getUID()`**: Generates a simple, short unique ID string.
+-   **`getUID()`**: Generates a simple, short unique ID string based on `Math.random()`, returned in uppercase.
 
 ```typescript
 import { getUID } from '@venizia/ignis-helpers';

package/wiki/references/utilities/performance.md

@@ -1,18 +1,20 @@
 # Performance Utility
 
-The Performance utility provides functions for measuring and logging the execution time of code blocks, which is useful for identifying bottlenecks and optimizing your application.
+The Performance utility provides functions for measuring and logging the execution time of code blocks, which is useful for identifying bottlenecks and optimizing your application. All timing uses `performance.now()` (milliseconds).
 
 ## `executeWithPerformanceMeasure`
 
-This is a higher-order function that wraps a task (a function returning a Promise), automatically logging its start time, end time, and total execution duration.
+This is a higher-order function that wraps a task (a function), automatically logging its start time, end time, and total execution duration. Returns a Promise that resolves to the task's return value.
 
 ### `executeWithPerformanceMeasure(opts)`
 
 -   `opts` (object):
-    -   `logger` (ApplicationLogger, optional): A logger instance to use for logging. Defaults to `console`.
-    -   `description` (string, optional): A description of the task being measured.
+    -   `logger` (Logger, optional): A logger instance to use for logging. Defaults to `console`.
+    -   `level` (string, optional): The log level to use (e.g., `'debug'`, `'info'`). Defaults to `'debug'`.
+    -   `description` (string, optional): A description of the task being measured. Defaults to `'Executing'`.
     -   `scope` (string): A scope to identify the context of the measurement.
-    -   `task` (Function): The asynchronous function (or a function that returns a Promise) to be executed and measured.
+    -   `task` (Function): The function to be executed and measured. Can be sync or async (wrapped with `Promise.resolve()`).
+    -   `args` (any, optional): Arguments to include in the log output for debugging purposes. When provided, they are logged as JSON (`%j` format).
 
 ### Example
 
@@ -43,12 +45,21 @@ When `registerComponents` is called, it will produce log output similar to this:
 [RegisterComponents] DONE | Register application components | Took: 12.3456 (ms)
 ```
 
+With `args` provided:
+
+```
+[RegisterComponents] START | Register application components... | Args: {"name":"auth"}
+[RegisterComponents] DONE | Register application components | Args: {"name":"auth"} | Took: 12.3456 (ms)
+```
+
 ## Low-Level Utilities
 
 For more granular measurements, you can use the lower-level functions:
 
--   **`getPerformanceCheckpoint()`**: Returns a high-resolution timestamp, which you can use as a starting point.
--   **`getExecutedPerformance(opts)`**: Calculates the elapsed time in milliseconds since a given checkpoint.
+-   **`getPerformanceCheckpoint()`**: Returns a high-resolution timestamp from `performance.now()`, which you can use as a starting point.
+-   **`getExecutedPerformance(opts)`**: Calculates the elapsed time in milliseconds since a given checkpoint. Rounds to 6 decimal places by default.
+    -   `opts.from` (number): The starting checkpoint from `getPerformanceCheckpoint()`.
+    -   `opts.digit` (number, optional): Number of decimal places for rounding. Defaults to `6`.
 
 ### Example
 
@@ -61,4 +72,8 @@ const start = getPerformanceCheckpoint();
 
 const duration = getExecutedPerformance({ from: start });
 console.log(`The work took ${duration} ms.`);
+
+// With custom precision
+const preciseDuration = getExecutedPerformance({ from: start, digit: 2 });
+console.log(`The work took ${preciseDuration} ms.`);
 ```

package/wiki/references/utilities/promise.md

@@ -11,7 +11,7 @@ This function executes an array of asynchronous tasks concurrently, but with a s
 -   `opts` (object):
     -   `tasks` (Array<() => Promise<T>>): An array of functions that each return a Promise.
     -   `limit` (number): The maximum number of promises to execute in parallel.
-    -   `onTaskDone` (<R>(opts: { result: R }) => ValueOrPromise<void>, optional): A callback function that is executed whenever a task is completed.
+    -   `onTaskDone` (<R>(opts: { result: R }) => ValueOrPromise<void>, optional): A callback function that is executed whenever a task is completed (specifically, when the concurrency limit is reached and a task finishes to make room).
 
 ### Example
 
@@ -38,9 +38,22 @@ const results = await executePromiseWithLimit({
 console.log('All tasks finished:', results);
 ```
 
+## `transformValueOrPromise`
+
+This async function applies a transformation function to a value that might be a direct value or a Promise. It always returns a Promise.
+
+```typescript
+import { transformValueOrPromise } from '@venizia/ignis-helpers';
+
+const double = (n: number) => n * 2;
+
+const result1 = await transformValueOrPromise(5, double); // => 10
+const result2 = await transformValueOrPromise(Promise.resolve(5), double); // => 10
+```
+
 ## `isPromiseLike`
 
-A type guard function to check if a given value is a Promise-like object (i.e., it has a `then` method).
+A type guard function to check if a given value is a Promise-like object (i.e., it has a `then` method). Checks that the value is non-null, is an object or function, and has a `then` property that is a function.
 
 ```typescript
 import { isPromiseLike } from '@venizia/ignis-helpers';
@@ -57,22 +70,9 @@ if (isPromiseLike(b)) {
 }
 ```
 
-## `transformValueOrPromise`
-
-This function applies a transformation function to a value that might be a direct value or a Promise.
-
-```typescript
-import { transformValueOrPromise, isPromiseLike } from '@venizia/ignis-helpers';
-
-const double = (n: number) => n * 2;
-
-const result1 = await transformValueOrPromise(5, double); // => 10
-const result2 = await transformValueOrPromise(Promise.resolve(5), double); // => 10
-```
-
 ## `getDeepProperty`
 
-Safely retrieves a deeply nested property from an object using a dot-separated path string. It throws an error if any part of the path is null or undefined.
+Traverses a dot-separated property path on an object and returns the value. It throws an error if any intermediate part of the path is null or undefined.
 
 ```typescript
 import { getDeepProperty } from '@venizia/ignis-helpers';
@@ -80,4 +80,7 @@ import { getDeepProperty } from '@venizia/ignis-helpers';
 const obj = { a: { b: { c: 'hello' } } };
 
 const value = getDeepProperty(obj, 'a.b.c'); // => 'hello'
+
+// Throws: Cannot read property 'x' of undefined
+getDeepProperty(obj, 'a.x.y');
 ```

package/wiki/references/utilities/request.md

@@ -1,6 +1,6 @@
 # Request Utility
 
-The Request utility provides functions for handling HTTP request data, such as parsing multipart form data.
+The Request utility provides functions for handling HTTP request data, such as parsing multipart form data, and utilities for creating secure Content-Disposition headers.
 
 ## `parseMultipartBody`
 
@@ -9,21 +9,21 @@ The `parseMultipartBody` function is an asynchronous utility for parsing `multip
 ### `parseMultipartBody(opts)`
 
 -   `opts` (object):
-    -   `context` (Hono.Context): The Hono context object for the current request.
-    -   `storage` ('memory' | 'disk', optional): The storage strategy for uploaded files. Defaults to `'memory'`.
-    -   `uploadDir` (string, optional): The directory to save files to when using the `'disk'` storage strategy. Defaults to `'./uploads'`.
+    -   `context` (object with `req` property): The Hono context object for the current request. Uses `context.req.formData()` internally.
+    -   `storage` (`'memory'` | `'disk'`, optional): The storage strategy for uploaded files. Defaults to `'memory'`.
+    -   `uploadDir` (string, optional): The directory to save files to when using the `'disk'` storage strategy. Defaults to `'./uploads'`. The directory is created recursively if it does not exist.
 
-The function returns a `Promise` that resolves to an array of `IParsedFile` objects.
+The function returns a `Promise` that resolves to an array of `IParsedFile` objects. String form fields are skipped (only `File` entries are processed).
 
 ### `IParsedFile` Interface
 
 -   `fieldname`: The name of the form field.
 -   `originalname`: The original name of the uploaded file.
--   `encoding`: The file's encoding.
+-   `encoding`: The file's encoding (always `'utf8'`).
 -   `mimetype`: The MIME type of the file.
 -   `size`: The size of the file in bytes.
 -   `buffer` (Buffer, optional): The file's content as a Buffer (if `storage` is `'memory'`).
--   `filename` (string, optional): The name of the file on disk (if `storage` is `'disk'`).
+-   `filename` (string, optional): The generated name of the file on disk (if `storage` is `'disk'`). Format: `{timestamp}-{randomString}-{sanitizedOriginalName}`.
 -   `path` (string, optional): The full path to the file on disk (if `storage` is `'disk'`).
 
 ### Example
@@ -31,11 +31,11 @@ The function returns a `Promise` that resolves to an array of `IParsedFile` obje
 Here is an example of how to use `parseMultipartBody` in a controller to handle a file upload.
 
 ```typescript
-import { BaseController, controller } from '@venizia/ignis';
+import { BaseRestController, controller } from '@venizia/ignis';
 import { parseMultipartBody, HTTP } from '@venizia/ignis-helpers';
 
 @controller({ path: '/files' })
-export class FileController extends BaseController {
+export class FileController extends BaseRestController {
   // ...
   override binding() {
     this.defineRoute({
@@ -81,27 +81,38 @@ These utilities help create secure, RFC-compliant `Content-Disposition` headers
 
 Creates a safe Content-Disposition header with proper filename encoding for file downloads.
 
-#### `createContentDispositionHeader(filename: string): string`
+#### `createContentDispositionHeader(opts)`
 
--   `filename` (string): The filename to use in the Content-Disposition header.
+-   `opts` (object):
+    -   `filename` (string): The filename to use in the Content-Disposition header.
+    -   `type` (`'attachment'` | `'inline'`): The disposition type.
 
 The function returns a properly formatted `Content-Disposition` header string with both ASCII and UTF-8 encoded filenames for maximum browser compatibility.
 
 **Features:**
-- Automatic filename sanitization (removes path components and dangerous characters)
-- UTF-8 encoding support for international characters
+- Automatic filename sanitization via `sanitizeFilename()`
+- UTF-8 encoding support via `encodeRFC5987()`
 - RFC 5987 compliant
-- Fallback for older browsers
+- Dual `filename` / `filename*` for browser compatibility
 
 **Example:**
 
 ```typescript
 import { createContentDispositionHeader } from '@venizia/ignis-helpers';
 
-// In a download endpoint
-ctx.header('content-disposition', createContentDispositionHeader('my-document.pdf'));
-
+// Attachment (file download)
+ctx.header('content-disposition', createContentDispositionHeader({
+  filename: 'my-document.pdf',
+  type: 'attachment',
+}));
 // Output: attachment; filename="my-document.pdf"; filename*=UTF-8''my-document.pdf
+
+// Inline (display in browser)
+ctx.header('content-disposition', createContentDispositionHeader({
+  filename: 'report.pdf',
+  type: 'inline',
+}));
+// Output: inline; filename="report.pdf"; filename*=UTF-8''report.pdf
 ```
 
 ---
@@ -117,13 +128,13 @@ Sanitizes a filename for safe use, removing path components and dangerous charac
 Returns a safe filename suitable for use in headers or filesystem operations.
 
 **Features:**
-- Removes path components (prevents directory traversal attacks)
-- Allows only alphanumeric characters, spaces, hyphens, underscores, and dots
+- Removes path components via `path.basename()` (prevents directory traversal attacks)
+- Allows only word characters (`\w`), spaces, hyphens, underscores, and dots
 - Replaces dangerous characters with underscores
 - Removes leading dots (prevents hidden files)
 - Replaces consecutive dots with a single dot
 - Removes ".." patterns (additional path traversal protection)
-- Prevents empty filenames and suspicious patterns
+- Returns `'download'` for empty, suspicious, or invalid filenames
 
 **Example:**
 
@@ -134,7 +145,6 @@ sanitizeFilename('../../etc/passwd');        // Returns: 'passwd'
 sanitizeFilename('my<file>name.txt');        // Returns: 'my_file_name.txt'
 sanitizeFilename('.hidden');                 // Returns: 'hidden'
 sanitizeFilename('file...txt');              // Returns: 'file.txt'
-sanitizeFilename('документ.pdf');            // Returns: '_________.pdf'
 sanitizeFilename('');                        // Returns: 'download'
 sanitizeFilename('..');                      // Returns: 'download'
 ```
@@ -142,7 +152,7 @@ sanitizeFilename('..');                      // Returns: 'download'
 
 ### `encodeRFC5987`
 
-Encodes a filename according to RFC 5987 for use in HTTP headers.
+Encodes a filename according to RFC 5987 for use in HTTP headers. Encodes using `encodeURIComponent` and additionally escapes single quotes, parentheses, and asterisks.
 
 #### `encodeRFC5987(filename: string): string`
 
@@ -156,22 +166,31 @@ Returns an RFC 5987 encoded string suitable for the `filename*` parameter in Con
 import { encodeRFC5987 } from '@venizia/ignis-helpers';
 
 encodeRFC5987('my document.pdf');     // Returns: 'my%20document.pdf'
-encodeRFC5987('файл.txt');            // Returns: '%D1%84%D0%B0%D0%B9%D0%BB.txt'
 ```
 
 
+## `IRequestedRemark` Interface
+
+The Request utility also exports the `IRequestedRemark` interface, which describes a request remark object:
+
+-   `id` (string): The request identifier.
+-   `url` (string): The request URL.
+-   `method` (string): The HTTP method.
+-   `[extra: string | symbol]`: Additional arbitrary properties.
+
+
 ## Complete File Download Example
 
 Here's a complete example combining multipart upload parsing with secure file downloads:
 
 ```typescript
-import { BaseController, controller } from '@venizia/ignis';
+import { BaseRestController, controller } from '@venizia/ignis';
 import { parseMultipartBody, createContentDispositionHeader, HTTP } from '@venizia/ignis-helpers';
 import fs from 'node:fs';
 import path from 'node:path';
 
 @controller({ path: '/files' })
-export class FileController extends BaseController {
+export class FileController extends BaseRestController {
   override binding() {
     // Upload endpoint
     this.bindRoute({
@@ -209,7 +228,10 @@ export class FileController extends BaseController {
         // Set secure headers
         ctx.header('content-type', 'application/octet-stream');
         ctx.header('content-length', fileStat.size.toString());
-        ctx.header('content-disposition', createContentDispositionHeader(filename));
+        ctx.header('content-disposition', createContentDispositionHeader({
+          filename,
+          type: 'attachment',
+        }));
         ctx.header('x-content-type-options', 'nosniff');
 
         return new Response(fileStream, {