@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/references/utilities/request.md

@@ -1,245 +1,84 @@
-# Request Utility
-
-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`
-
-The `parseMultipartBody` function is an asynchronous utility for parsing `multipart/form-data` request bodies, which is essential for handling file uploads. It can store the uploaded files in memory or on disk.
-
-### `parseMultipartBody(opts)`
-
--   `opts` (object):
-    -   `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. String form fields are skipped (only `File` entries are processed).
-
-### `IParsedFile` Interface
+---
+title: Request Utility
+description: Multipart form parsing and secure Content-Disposition header helpers for file uploads and downloads
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
--   `fieldname`: The name of the form field.
--   `originalname`: The original name of the uploaded file.
--   `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 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'`).
+# Request Utility
 
-### Example
+Functions for handling HTTP request data: parsing `multipart/form-data` bodies for file uploads, and building safe, RFC-compliant `Content-Disposition` headers for downloads.
 
-Here is an example of how to use `parseMultipartBody` in a controller to handle a file upload.
+## In one example
 
 ```typescript
 import { BaseRestController, controller } from '@venizia/ignis';
-import { parseMultipartBody, HTTP } from '@venizia/ignis-helpers';
+import { parseMultipartBody, createContentDispositionHeader, HTTP } from '@venizia/ignis-helpers';
 
 @controller({ path: '/files' })
 export class FileController extends BaseRestController {
-  // ...
   override binding() {
-    this.defineRoute({
-      configs: {
-        path: '/upload',
-        method: 'post',
-        // Note: You would typically define a request body schema
-        // for multipart/form-data in your OpenAPI spec.
+    this.bindRoute({ configs: { path: '/upload', method: 'post' } }).to({
+      handler: async (ctx) => {
+        const files = await parseMultipartBody({ context: ctx, storage: 'disk', uploadDir: './uploads' });
+        return ctx.json(
+          { message: 'Uploaded', files: files.map(f => ({ name: f.originalname, size: f.size })) },
+          HTTP.ResultCodes.RS_2.Ok,
+        );
       },
-      handler: async (c) => {
-        try {
-          const files = await parseMultipartBody({
-            context: c,
-            storage: 'disk', // or 'memory'
-            uploadDir: './my-uploads',
-          });
-
-          console.log('Uploaded files:', files);
-
-          return c.json(
-            { message: `${files.length} file(s) uploaded successfully.` },
-            HTTP.ResultCodes.RS_2.Ok,
-          );
-        } catch (error) {
-          return c.json(
-            { message: 'Failed to upload files', error: error.message },
-            HTTP.ResultCodes.RS_5.InternalServerError,
-          );
-        }
+    });
+
+    this.bindRoute({ configs: { path: '/:filename', method: 'get' } }).to({
+      handler: (ctx) => {
+        const { filename } = ctx.req.valid('param');
+        ctx.header(
+          'content-disposition',
+          createContentDispositionHeader({ filename, type: 'attachment' }),
+        );
+        // ... stream the file
       },
     });
   }
 }
 ```
 
----
-
-## Content-Disposition Utilities
-
-These utilities help create secure, RFC-compliant `Content-Disposition` headers for file downloads.
-
-### `createContentDispositionHeader`
-
-Creates a safe Content-Disposition header with proper filename encoding for file downloads.
-
-#### `createContentDispositionHeader(opts)`
-
--   `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 via `sanitizeFilename()`
-- UTF-8 encoding support via `encodeRFC5987()`
-- RFC 5987 compliant
-- Dual `filename` / `filename*` for browser compatibility
-
-**Example:**
-
-```typescript
-import { createContentDispositionHeader } from '@venizia/ignis-helpers';
-
-// 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
-```
-
----
-
-### `sanitizeFilename`
-
-Sanitizes a filename for safe use, removing path components and dangerous characters. Useful for HTTP headers (e.g., Content-Disposition) and general file handling.
-
-#### `sanitizeFilename(filename: string): string`
-
--   `filename` (string): The filename to sanitize.
-
-Returns a safe filename suitable for use in headers or filesystem operations.
-
-**Features:**
-- 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)
-- Returns `'download'` for empty, suspicious, or invalid filenames
-
-**Example:**
-
-```typescript
-import { sanitizeFilename } from '@venizia/ignis-helpers';
-
-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('');                        // Returns: 'download'
-sanitizeFilename('..');                      // Returns: 'download'
-```
-
-
-### `encodeRFC5987`
-
-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`
-
--   `filename` (string): The filename to encode.
-
-Returns an RFC 5987 encoded string suitable for the `filename*` parameter in Content-Disposition headers.
-
-**Example:**
-
-```typescript
-import { encodeRFC5987 } from '@venizia/ignis-helpers';
-
-encodeRFC5987('my document.pdf');     // Returns: 'my%20document.pdf'
-```
-
+## Functions
 
-## `IRequestedRemark` Interface
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `parseMultipartBody` | `parseMultipartBody(opts: { context: { req: any }; storage?: 'memory' \| 'disk'; uploadDir?: string }): Promise<IParsedFile[]>` | Parses a `multipart/form-data` body via `context.req.formData()`. String fields are skipped - only `File` entries are returned. |
+| `sanitizeFilename` | `sanitizeFilename(filename: string): string` | Strips path components and dangerous characters from `filename`. Returns `'download'` for empty or suspicious input. |
+| `encodeRFC5987` | `encodeRFC5987(filename: string): string` | RFC 5987 encodes `filename` for the `filename*` header parameter (`encodeURIComponent` plus escaped `'`, `(`, `)`, `*`). |
+| `createContentDispositionHeader` | `createContentDispositionHeader(opts: { filename: string; type: 'attachment' \| 'inline' }): string` | Builds a full `Content-Disposition` value: sanitizes the filename, then emits both the ASCII `filename=` and UTF-8 `filename*=` forms. |
 
-The Request utility also exports the `IRequestedRemark` interface, which describes a request remark object:
+## Parsed file shape
 
--   `id` (string): The request identifier.
--   `url` (string): The request URL.
--   `method` (string): The HTTP method.
--   `[extra: string | symbol]`: Additional arbitrary properties.
+`parseMultipartBody` resolves to an array of objects (the `IParsedFile` shape, internal to the module - not separately exported):
 
+| Field | Type | Present when |
+|-------|------|---------------|
+| `fieldname` | `string` | always |
+| `originalname` | `string` | always |
+| `encoding` | `string` | always - hardcoded `'utf8'` |
+| `mimetype` | `string` | always |
+| `size` | `number` | always |
+| `buffer` | `Buffer` | `storage: 'memory'` (default) |
+| `filename` | `string` | `storage: 'disk'` - format `{timestamp}-{randomString}-{sanitizedOriginalName}` |
+| `path` | `string` | `storage: 'disk'` |
 
-## Complete File Download Example
+## Notes
 
-Here's a complete example combining multipart upload parsing with secure file downloads:
+- **`storage` defaults to `'memory'`**; `uploadDir` defaults to `'./uploads'` and is created recursively if it does not exist.
+- **`sanitizeFilename` is applied automatically** inside `createContentDispositionHeader` - callers do not need to sanitize twice. It also removes leading dots, collapses repeated dots, and strips `..` sequences to block directory traversal and hidden-file tricks.
+- **`createContentDispositionHeader` always emits both forms** (`filename="..."; filename*=UTF-8''...`) for maximum browser compatibility - older browsers read the ASCII fallback, modern ones read the UTF-8 form.
+- **`IRequestedRemark`** is a separately exported interface for describing a request: `{ id: string; url: string; method: string; [extra: string | symbol]: any }`. It is not consumed internally by `parseMultipartBody` or any other function on this page - it is a general-purpose shape for application code that needs to tag a request with an id, URL, method, and arbitrary extra fields.
 
-```typescript
-import { BaseRestController, controller } from '@venizia/ignis';
-import { parseMultipartBody, createContentDispositionHeader, HTTP } from '@venizia/ignis-helpers';
-import fs from 'node:fs';
-import path from 'node:path';
+## See also
 
-@controller({ path: '/files' })
-export class FileController extends BaseRestController {
-  override binding() {
-    // Upload endpoint
-    this.bindRoute({
-      configs: { path: '/upload', method: 'post' },
-    }).to({
-      handler: async (ctx) => {
-        const files = await parseMultipartBody({
-          context: ctx,
-          storage: 'disk',
-          uploadDir: './uploads',
-        });
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [Static Asset Component](/extensions/components/static-asset/) - built-in upload/download CRUD built on this utility
+- [Request Tracker Component](/extensions/components/request-tracker) - `x-request-id` header and request body parsing
 
-        return ctx.json(
-          {
-            message: 'Files uploaded successfully',
-            files: files.map(f => ({ name: f.originalname, size: f.size })),
-          },
-          HTTP.ResultCodes.RS_2.Ok,
-        );
-      },
-    });
+**Files:**
 
-    // Download endpoint
-    this.bindRoute({
-      configs: { path: '/:filename', method: 'get' },
-    }).to({
-      handler: async (ctx) => {
-        const { filename } = ctx.req.valid('param');
-        const filePath = path.join('./uploads', filename);
-
-        // Read file
-        const fileStat = fs.statSync(filePath);
-        const fileStream = fs.createReadStream(filePath);
-
-        // Set secure headers
-        ctx.header('content-type', 'application/octet-stream');
-        ctx.header('content-length', fileStat.size.toString());
-        ctx.header('content-disposition', createContentDispositionHeader({
-          filename,
-          type: 'attachment',
-        }));
-        ctx.header('x-content-type-options', 'nosniff');
-
-        return new Response(fileStream, {
-          headers: ctx.res.headers,
-          status: HTTP.ResultCodes.RS_2.Ok,
-        });
-      },
-    });
-  }
-}
-```
+- [`packages/helpers/src/utilities/request.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/utilities/request.utility.ts)

package/content/references/utilities/schema.md

@@ -1,162 +1,68 @@
-# Schema Utility
-
-The Schema utility provides a set of helper functions and predefined schemas for working with `zod` and `@hono/zod-openapi`. These utilities simplify the process of defining API request/response schemas and improve consistency in your API documentation.
-
-## `jsonContent`
-
-The `jsonContent` function creates a standard OpenAPI content object for `application/json` payloads.
+---
+title: Schema Utility
+description: Zod and OpenAPI helpers for JSON response schemas, path params, string constraints, and case conversion
+difficulty: beginner
+lastUpdated: 2026-07-16
+---
 
-### `jsonContent(opts)`
-
--   `opts` (object):
-    -   `schema` (ZodType): The Zod schema describing the JSON payload.
-    -   `description` (string): A description of the content.
-    -   `required` (boolean, optional): Whether the content is required.
-
-```typescript
-import { jsonContent } from '@venizia/ignis';
-import { z } from '@hono/zod-openapi';
-
-const UserSchema = z.object({
-  id: z.number(),
-  name: z.string(),
-});
-
-const userResponse = {
-  description: 'A single user object',
-  ...jsonContent({ schema: UserSchema, description: 'User data' }),
-};
-```
-
-## `jsonResponse`
-
-The `jsonResponse` function generates a standard OpenAPI response object that includes a success (200 OK) response and a default error response for `4xx | 5xx` status codes. The error response uses the `ErrorSchema`.
+# Schema Utility
 
-### `jsonResponse(opts)`
+Helper functions and predefined schemas for working with `zod` and `@hono/zod-openapi` - building JSON request/response schemas, path-param schemas, and case-converting schemas for API routes.
 
--   `opts` (object):
-    -   `schema` (ZodType): The Zod schema for the success response body.
-    -   `description` (string, optional): A description for the success response. Defaults to `'Success Response'`.
-    -   `required` (boolean, optional): Whether the content is required.
-    -   `headers` (Record<string, THeaderObject>, optional): Custom response headers to include in the success response.
+## In one example
 
 ```typescript
-import { jsonResponse } from '@venizia/ignis';
+import { jsonResponse, requiredString, idParamsSchema } from '@venizia/ignis';
 import { z } from '@hono/zod-openapi';
 
-const UserSchema = z.object({
-  id: z.number(),
-  name: z.string(),
-});
+const UserSchema = z.object({ id: z.number(), name: requiredString({ min: 1, max: 50 }) });
 
 this.defineRoute({
   configs: {
-    path: '/',
+    path: '/{id}',
     method: 'get',
-    responses: jsonResponse({
-      description: 'A single user object',
-      schema: UserSchema,
-    }),
+    request: { params: idParamsSchema({ idType: 'number' }) },
+    responses: jsonResponse({ schema: UserSchema, description: 'A single user object' }),
   },
-  // ...
-});
-
-// With custom headers
-this.defineRoute({
-  configs: {
-    path: '/list',
-    method: 'get',
-    responses: jsonResponse({
-      schema: z.array(UserSchema),
-      description: 'User list',
-      headers: {
-        'x-total-count': {
-          description: 'Total number of records',
-          schema: { type: 'string', examples: ['100'] },
-        },
-      },
-    }),
+  handler: (c) => {
+    const { id } = c.req.valid('param');
+    // ...
   },
-  // ...
 });
 ```
 
-## `requiredString`
+## Functions
 
-This function creates a `zod` string schema that is non-empty (`nonempty()`) and can be further constrained by length.
+| Function | Signature | What it does |
+|----------|-----------|---------------|
+| `jsonContent` | `jsonContent(opts: { schema: ZodType; description: string; required?: boolean }): { description; content; required }` | Builds a standard OpenAPI content object for an `application/json` payload. |
+| `jsonResponse` | `jsonResponse(opts: { schema: ZodType; description?: string; required?: boolean; headers?: Record<string, THeaderObject> }): Record<number \| string, ...>` | Builds a full response map: `200` success (via `jsonContent`, description defaults to `'Success Response'`) plus a `'4xx \| 5xx'` error entry using `ErrorSchema`. |
+| `requiredString` | `requiredString(opts?: { min?: number; max?: number; fixed?: number }): ZodString` | A non-empty (`.nonempty()`) Zod string, optionally constrained by `min`, `max`, or an exact `fixed` length. |
+| `idParamsSchema` | `idParamsSchema(opts?: { idType?: 'number' \| 'string' }): ZodObject` | Builds a path-param schema for `{ id }`, typed and OpenAPI-documented as `number` (default) or `string`. Throws on any other `idType`. |
+| `snakeToCamel` | `snakeToCamel<T extends ZodRawShape>(shape: T): ZodEffects` | Wraps a Zod object `shape` so it accepts `snake_case` input keys and produces a `camelCase`-keyed output, via `.transform()` piped into a camelCase-shaped schema. |
 
-### `requiredString(opts?)`
+## Predefined schemas and types
 
--   `opts` (object, optional):
-    -   `min` (number, optional): Minimum string length.
-    -   `max` (number, optional): Maximum string length.
-    -   `fixed` (number, optional): Exact string length (uses `.length()`).
+| Export | What it is |
+|--------|------------|
+| `AnyObjectSchema` | `z.object().catchall(z.any())`, OpenAPI-described as `'Unknown schema'` - a permissive object schema. |
+| `TAnyObjectSchema` | Type alias for `z.ZodObject<z.ZodRawShape>`. |
+| `TInferSchema<T>` | Type alias for `z.infer<T>` - the TypeScript type inferred from a Zod schema `T`. |
 
-```typescript
-import { requiredString } from '@venizia/ignis';
+## Notes
 
-const schema = z.object({
-  username: requiredString({ min: 3, max: 20 }),
-  password: requiredString({ min: 8 }),
-  countryCode: requiredString({ fixed: 2 }),
-});
-```
-
-## Predefined Schemas
+- **Two source files, one page.** `requiredString`, `AnyObjectSchema`, `TAnyObjectSchema`, and `TInferSchema` live in `schema.utility.ts`; `jsonContent`, `jsonResponse`, `idParamsSchema`, and `snakeToCamel` live in `base/models/common/types.ts`. Both are re-exported from the `@venizia/ignis` root barrel, so the import path is the same either way.
+- **`jsonResponse`'s error branch is fixed** - it always uses `ErrorSchema` under the `'4xx | 5xx'` key; only the success schema, description, and headers are customizable per call.
+- **HTML responses are a separate utility.** For `text/html` routes, use `htmlContent`/`htmlResponse` from the [JSX Utility](/references/utilities/jsx) instead of `jsonContent`/`jsonResponse`.
 
--   **`AnyObjectSchema`**: A flexible schema for any object (`z.object().catchall(z.any())`), with an OpenAPI description of `'Unknown schema'`.
+## See also
 
-### Type Utilities
+- [Utilities Overview](/references/utilities/) - all utility functions
+- [JSX Utility](/references/utilities/jsx) - `htmlContent()` / `htmlResponse()` for HTML routes
+- [Parse Utility](/references/utilities/parse) - `toCamel()` / `keysToCamel()`, the transforms `snakeToCamel` builds on
+- [REST Controllers Guide](/guides/core-concepts/rest-controllers) - defining routes with `request`/`responses`
 
-```typescript
-import { TAnyObjectSchema, TInferSchema } from '@venizia/ignis';
+**Files:**
 
-// TAnyObjectSchema = z.ZodObject<z.ZodRawShape>
-// TInferSchema<T> = z.infer<T> - infer TypeScript type from a Zod schema
-
-type UserType = TInferSchema<typeof UserSchema>;
-```
-
-## `snakeToCamel`
-
-Transforms a Zod object shape from snake_case keys to camelCase. Uses `.transform()` and `.pipe()` to create a schema that accepts snake_case input but produces camelCase output.
-
-```typescript
-import { snakeToCamel } from '@venizia/ignis';
-
-const schema = snakeToCamel({
-  first_name: z.string(),
-  last_name: z.string(),
-});
-
-// Input: { first_name: 'John', last_name: 'Doe' }
-// Output: { firstName: 'John', lastName: 'Doe' }
-```
-
-## Custom ID Params
-
-Use the `idParamsSchema()` helper to generate path parameter schemas for resource IDs:
-
-### `idParamsSchema(opts?)`
-
--   `opts` (object, optional):
-    -   `idType` (string): `'number'` (default) or `'string'`.
-
-```typescript
-import { idParamsSchema } from '@venizia/ignis';
-
-this.defineRoute({
-  configs: {
-    path: '/{id}',
-    method: 'get',
-    request: {
-      params: idParamsSchema({ idType: 'number' }),
-    },
-    // ...
-  },
-  handler: (c) => {
-    const { id } = c.req.valid('param');
-    // ...
-  },
-});
-```
+- [`packages/core/src/utilities/schema.utility.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/utilities/schema.utility.ts)
+- [`packages/core/src/base/models/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/models/common/types.ts)