@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/extensions/helpers/socket-io/index.md

@@ -6,7 +6,9 @@ difficulty: intermediate
 
 # Socket.IO
 
-`SocketIOServerHelper` and `SocketIOClientHelper` wrap `socket.io` with a mandatory post-connection authentication handshake, room management, and a Redis adapter so events reach clients no matter which server instance they are connected to.
+`SocketIOServerHelper` and `SocketIOClientHelper` wrap `socket.io` with a mandatory post-connection authentication handshake and room management. A Redis adapter makes sure events reach a client no matter which server instance it's connected to.
+
+These are the raw classes: construct and `configure()` them yourself. Need the server helper inside an IGNIS app instead? [`SocketIOComponent`](/extensions/components/socket-io/) wires it into DI for you, on both Node.js and Bun.
 
 ## In one example
 
@@ -58,14 +60,28 @@ const client = new SocketIOClientHelper({
 
 ## How it works
 
-- **Two independent helpers.** `SocketIOServerHelper` wraps a `socket.io` `Server`; `SocketIOClientHelper` wraps a `socket.io-client` `Socket`. Both extend `BaseHelper`, and the client can talk to any `socket.io` server, not only this one.
+- **Two independent helpers, both extending `BaseHelper`:**
+
+| Helper | Wraps |
+|--------|-------|
+| `SocketIOServerHelper` | a `socket.io` `Server` |
+| `SocketIOClientHelper` | a `socket.io-client` `Socket` |
+
+- **The client isn't locked to this server.** It can talk to any `socket.io` server, not only this one.
 - **Runtime-agnostic server.** Pass a Node.js `http.Server` for `runtime: 'node'`, or an `@socket.io/bun-engine` instance for `runtime: 'bun'`.
-- **Redis is mandatory server-side.** `configure()` duplicates the parent `redisConnection` into three dedicated clients: `redisPub`/`redisSub` power `@socket.io/redis-adapter` for cross-instance room broadcast, and `redisEmitter` powers `@socket.io/redis-emitter` for `send()`.
-- **Boot fails fast on a broken Redis connection.** `configure()` waits for all three clients to reach `ready` and rejects after 30 seconds if any never do, so a broken Redis connection fails boot instead of hanging it.
-- **Authentication is a step separate from connecting.** A client connects at the transport level in state `UNAUTHORIZED`, then must emit `'authenticate'`. The server calls `authenticateFn(handshake)`; only `true` moves the client to `AUTHENTICATED` and joins it to `defaultRooms`.
-- **Unauthenticated clients time out.** A client that never authenticates within `authenticateTimeout` is disconnected - including one whose `authenticateFn` is still pending when the timeout fires.
-- **Heartbeat has no pong check.** Once authenticated, the server pings on `pingInterval` as a keep-alive; a silently dead connection is only caught when the underlying transport itself notices.
-- **Custom rooms need `validateRoomFn`.** Room joins beyond `defaultRooms` are rejected unless you supply it - without it, every custom join request is dropped.
+- **Redis is mandatory server-side.** `configure()` duplicates the parent `redisConnection` into three dedicated clients:
+
+| Client | Powers |
+|--------|--------|
+| `redisPub` + `redisSub` | `@socket.io/redis-adapter` - cross-instance room broadcast |
+| `redisEmitter` | `@socket.io/redis-emitter` - used by `send()` |
+
+- **Boot fails fast on a broken Redis connection.** `configure()` waits for all three clients to reach `ready`. It rejects after 30 seconds if any never do, so a broken Redis connection fails boot instead of hanging it.
+- **Authentication is a step separate from connecting.** A client connects at the transport level in state `UNAUTHORIZED`, then must emit `'authenticate'`. The server then calls `authenticateFn(handshake)`.
+- **Only `true` authenticates.** It moves the client to `AUTHENTICATED` and joins it to `defaultRooms`.
+- **Unauthenticated clients time out.** A client that never authenticates within `authenticateTimeout` is disconnected. That includes a client whose `authenticateFn` is still pending when the timeout fires.
+- **Heartbeat has no pong check.** Once authenticated, the server pings on `pingInterval` as a keep-alive. A silently dead connection is only caught when the underlying transport itself notices.
+- **Custom rooms need `validateRoomFn`.** Room joins beyond `defaultRooms` are rejected unless you supply `validateRoomFn`.
 
 **Defaults**
 
@@ -90,7 +106,7 @@ socketServer.send({
 
 ### Listen for a custom event
 
-Register on the server with `on()`; subscribe on the client with `subscribe()`.
+Register on the server with `on()`. Subscribe on the client with `subscribe()`.
 
 ```typescript
 socketServer.on({
@@ -106,7 +122,7 @@ client.subscribe({
 
 ### Manage rooms
 
-Clients request rooms with `joinRooms()` / `leaveRooms()`; the server filters join requests through `validateRoomFn`.
+Clients request rooms with `joinRooms()` / `leaveRooms()`. The server filters join requests through `validateRoomFn`.
 
 ```typescript
 const socketServer = new SocketIOServerHelper({

package/content/extensions/helpers/storage/api.md

@@ -19,6 +19,22 @@ Exhaustive reference for `BaseStorageHelper`, the three `IStorageHelper` backend
 - [`packages/helpers/src/modules/storage/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/types.ts) - `IStorageHelper` and every option/result type
 - [`packages/helpers/src/common/constants/mime.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/constants/mime.ts) - `MimeTypes` const-class
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See which class implements which backend | [Class and Interface Model](#class-and-interface-model) |
+| Construct a backend and see its options | [MinioHelper](#miniohelper) / [BunS3Helper](#buns3helper) / [DiskHelper](#diskhelper) |
+| Understand what `upload()` validates and how it writes files | [upload (template method)](#upload-template-method-shared-by-every-backend) |
+| Validate a name or path before writing | [isValidName](#isvalidname) / [isValidPath](#isvalidpath) |
+| Look up every error message `upload()` can throw | [validateUploadFiles](#upload-template-method-shared-by-every-backend) |
+| Read a file back as a stream | [MinioHelper#getFile](#getfile) / [BunS3Helper#getFile](#getfile-1) / [DiskHelper#getFile](#getfile-2) |
+| List or delete objects in a bucket | per-backend Methods tables ([MinioHelper](#methods), [BunS3Helper](#methods-1), [DiskHelper](#methods-2)) |
+| Cache values in-process (not bucket storage) | [MemoryStorageHelper](#memorystoragehelper) |
+| Look up a type or option shape | [Types Reference](#types-reference) |
+| Compare backend differences at a glance | [Backend Behavior Matrix](#backend-behavior-matrix) |
+| Fix a thrown error message | [Troubleshooting](#troubleshooting) |
+
 ## Class and Interface Model
 
 ```
@@ -30,8 +46,9 @@ BaseHelper
 └── MemoryStorageHelper   -- In-memory key-value store (standalone, not IStorageHelper)
 ```
 
-- **`upload()` is a template method.** It validates the bucket and every file, then calls two protected hooks each backend supplies: `defaultLinkPrefix` (a getter) and `writeObject()` (the actual write).
-- **Every other method is backend-specific.** `isBucketExists`, `getBuckets`, `getBucket`, `createBucket`, `removeBucket`, `getFile`, `getStat`, `removeObject`, `removeObjects`, and `listObjects` are declared `abstract` on `BaseStorageHelper` and fully reimplemented per backend - there is no shared logic between a filesystem read and a MinIO `statObject()` call.
+- **`upload()` is a template method.** It validates the bucket and every file. Then it calls two protected hooks each backend supplies: `defaultLinkPrefix` (a getter) and `writeObject()` (the write itself).
+- **Every other method is backend-specific.** `isBucketExists`, `getBuckets`, `getBucket`, `createBucket`, `removeBucket`, `getFile`, `getStat`, `removeObject`, `removeObjects`, and `listObjects` are declared `abstract` on `BaseStorageHelper`.
+  - Each one is fully reimplemented per backend - no logic is shared between a filesystem read and a MinIO `statObject()` call.
 
 > [!TIP] Typing rule
 > Declare parameters and bindings as `IStorageHelper` for `MinioHelper` / `BunS3Helper` / `DiskHelper`. `MemoryStorageHelper` does not implement it and has its own standalone API - see [MemoryStorageHelper](#memorystoragehelper).
@@ -81,7 +98,7 @@ constructor(opts: { scope: string; identifier: string })
 | `scope` | `string` | Logger scope name. |
 | `identifier` | `string` | Helper identifier. |
 
-Every concrete backend's own constructor supplies defaults (`options.scope ?? <ClassName>`, `options.identifier ?? <ClassName>`) before calling `super()` - `scope`/`identifier` are required here but optional on every subclass's public options type.
+Every concrete backend's constructor calls `super()` with its own defaults: `scope: options.scope ?? <ClassName>`, `identifier: options.identifier ?? <ClassName>`. That's why `scope` and `identifier` are required here, but optional on every subclass's public options type.
 
 ### Static properties
 
@@ -139,7 +156,7 @@ storage.getMimeType('unknown.xyz');  // 'application/octet-stream'
 isValidName(name: string): boolean
 ```
 
-Validates a **single path segment** (bucket name or bare file name - must not contain `/`). Used internally by `isValidPath` to validate each segment. Logs a specific error for whichever rule fails.
+Validates a **single path segment**: a bucket name or a bare file name, which must not contain `/`. Used internally by `isValidPath` to validate each segment. Logs a specific error for whichever rule fails.
 
 | Rule (checked in order) | Example rejected | Reason |
 |---|---|---|
@@ -166,7 +183,7 @@ storage.isValidName('.hidden');        // false -- starts with dot
 isValidPath(pathStr: string, opts?: { maxDepth?: number }): boolean
 ```
 
-Validates a **full object path** that may include folder segments (e.g. `2025/uploads/report.pdf`). Trims leading/trailing slashes, splits on `/`, validates each segment with `isValidName`, and enforces a maximum folder depth.
+Validates a **full object path** that may include folder segments, for example `2025/uploads/report.pdf`. It trims leading and trailing slashes, splits on `/`, validates each segment with `isValidName`, and enforces a maximum folder depth. See the exact rules below.
 
 | Rule (checked in order) | Description |
 |---|---|
@@ -191,7 +208,7 @@ storage.isValidPath('a/b/c/d/file.pdf');     // false -- exceeds default max dep
 getFileType(opts: { mimeType: string }): string
 ```
 
-Categorizes a MIME type using the `MimeTypes` const-class (`UNKNOWN`, `IMAGE`, `VIDEO`, `TEXT`) by checking whether `mimeType` (lowercased) starts with `image`, `video`, or `text`.
+Categorizes a MIME type using the `MimeTypes` const-class: `UNKNOWN`, `IMAGE`, `VIDEO`, `TEXT`. It lowercases `mimeType` first, then checks whether it starts with `image`, `video`, or `text`.
 
 ```typescript
 storage.getFileType({ mimeType: 'image/png' });        // 'image'
@@ -220,9 +237,9 @@ Implemented once on `BaseStorageHelper`; `MinioHelper`, `BunS3Helper`, and `Disk
 2. Calls `isBucketExists({ name: bucket })`; throws if the bucket does not exist.
 3. Validates every file (`validateUploadFiles`, below).
 4. For each file, in parallel via `Promise.all()`:
-   - Computes `normalizeName` via `normalizeNameFn` if provided, else the default normalizer (lowercase, spaces to `_`, `{folderPath}/` prefix if set).
-   - Re-validates `normalizeName` with `isValidPath({ maxDepth: maxFolderDepth })` - this catches a traversal payload returned by a **custom** `normalizeNameFn`, even though `originalName` already passed validation.
-   - Computes `normalizeLink` via `normalizeLinkFn` if provided, else the default (`{defaultLinkPrefix}{bucket}/{normalizeName}`, each `/`-segment `encodeURIComponent`-ed).
+   - Computes `normalizeName` via `normalizeNameFn` if provided. Otherwise the default normalizer lowercases the name, replaces spaces with `_`, and prefixes `{folderPath}/` if set.
+   - Re-validates `normalizeName` with `isValidPath({ maxDepth: maxFolderDepth })`. This catches a traversal payload returned by a **custom** `normalizeNameFn`, even though `originalName` already passed validation.
+   - Computes `normalizeLink` via `normalizeLinkFn` if provided. Otherwise it builds the default: `{defaultLinkPrefix}{bucket}/{normalizeName}`, with each `/`-segment run through `encodeURIComponent`.
    - Calls the backend's `writeObject({ bucket, normalizeName, file })`.
    - Logs an info line with `normalizeName`, `normalizeLink`, `mimeType`, `encoding`, `size`, and elapsed time.
 5. Returns `{ bucketName, objectName, link }` per file.
@@ -234,7 +251,7 @@ Implemented once on `BaseStorageHelper`; `MinioHelper`, `BunS3Helper`, and `Disk
 | `isValidName(originalName)` | `'[upload] Invalid original file name'` |
 | If `folderPath` set: segment count vs. `maxFolderDepth ?? DEFAULT_MAX_FOLDER_DEPTH` | `` `[upload] Invalid folder path | depth: {depth} | max: {max}` `` |
 | If `folderPath` set: `isValidPath(folderPath, { maxDepth })` | `'[upload] Invalid folder path'` |
-| `size` must be a number `>= 0` (`undefined`/`null`/negative rejected; `0` is a legal empty file) | `` `[upload] Invalid file size | size: {size}` `` |
+| `size` must be a number `>= 0`. `undefined`, `null`, and negative values are rejected; `0` is a legal empty file. | `` `[upload] Invalid file size | size: {size}` `` |
 
 **Also throws:**
 
@@ -311,12 +328,12 @@ Creates a `minio.Client` internally and stores it as a private `client` field -
 | `options.scope` | `string` | `'MinioHelper'` | Logger scope name. |
 | `options.identifier` | `string` | `'MinioHelper'` | Helper identifier. |
 
-All other `minio.ClientOptions` fields (`region`, `transport`, `sessionToken`, `partSize`, `pathStyle`, ...) are also accepted and passed to the client - see the [minio JavaScript SDK docs](https://min.io/docs/minio/linux/developers/javascript/API.html).
+All other `minio.ClientOptions` fields are also accepted and passed to the client: `region`, `transport`, `sessionToken`, `partSize`, `pathStyle`, and more. See the [minio JavaScript SDK docs](https://min.io/docs/minio/linux/developers/javascript/API.html) for the complete list.
 
 ### defaultLinkPrefix and writeObject
 
 - `defaultLinkPrefix`: `'/static-assets/'`
-- `writeObject`: calls `client.putObject(bucket, normalizeName, buffer, size, metadata)` where `metadata` is `{ originalName, normalizeName, size, encoding, mimeType }` - the full upload metadata is persisted server-side and returned later by `getStat()`.
+- `writeObject`: calls `client.putObject(bucket, normalizeName, buffer, size, metadata)`, where `metadata` is `{ originalName, normalizeName, size, encoding, mimeType }`. The full upload metadata is persisted server-side and returned later by `getStat()`.
 
 ### Methods
 
@@ -366,7 +383,7 @@ const fileStream = await minioStorage.getFile({
 async getStat(opts: { bucket: string; name: string }): Promise<IFileStat>
 ```
 
-`client.statObject()`. Returns `size`, `metadata` (MinIO's `metaData` - the full dict written by `writeObject`), `lastModified`, `etag`, and `versionId` (if versioning is enabled).
+`client.statObject()`. Returns `size`, `metadata`, `lastModified`, `etag`, and `versionId`. `metadata` is MinIO's `metaData` field: the full dict written by `writeObject`. `versionId` is set only if versioning is enabled.
 
 #### listObjects
 
@@ -428,13 +445,13 @@ Creates a Bun `S3Client` for object operations and stores `{ accessKey, secretKe
 ### defaultLinkPrefix and writeObject
 
 - `defaultLinkPrefix`: `'/static-assets/'`
-- `writeObject`: `client.write(normalizeName, buffer, { bucket, type: mimeType })` - only the content type is persisted; unlike `MinioHelper`, no `originalName`/`encoding`/`size` metadata dictionary is stored.
+- `writeObject`: `client.write(normalizeName, buffer, { bucket, type: mimeType })`. Only the content type is persisted. Unlike `MinioHelper`, no `originalName`/`encoding`/`size` metadata dictionary is stored.
 
 ### Methods
 
 | Method | Behavior |
 |---|---|
-| `isBucketExists` | Returns `false` if the name fails `isValidName()`. Otherwise attempts `client.list({ maxKeys: 1 }, { bucket: name })`; returns `false` on any error (network, missing bucket, etc.). |
+| `isBucketExists` | Returns `false` if the name fails `isValidName()`. Otherwise attempts `client.list({ maxKeys: 1 }, { bucket: name })`, and returns `false` on any error - for example a network failure or a missing bucket. |
 | `getBuckets` | Signed `GET /`; parses `<Bucket><Name>...<CreationDate>...` from the XML response. |
 | `getBucket` | Finds the entry in `getBuckets()`; `null` if not found. |
 | `createBucket` | Signed `PUT /{name}`. Throws `'[createBucket] Invalid name to create bucket!'` on invalid name, or `` `[createBucket] S3 error: {xml}` `` on a non-OK response. |
@@ -504,7 +521,7 @@ async function buildSignedRequest(opts: {
 ```
 
 - **Internal only.** Not exported from the package barrel.
-- **Builds the `Authorization` header from scratch.** Uses `crypto.subtle` (HMAC-SHA256 and SHA-256 digest), following the standard SigV4 derivation: `kDate -> kRegion -> kService -> kSigning`.
+- **Builds the `Authorization` header from scratch.** Uses `crypto.subtle` for HMAC-SHA256 and SHA-256 digests, following the standard SigV4 derivation: `kDate -> kRegion -> kService -> kSigning`.
 - **Signs four headers.** `host`, `x-amz-content-sha256`, `x-amz-date`, and (if present) `x-amz-security-token`.
 - **Used exclusively for bucket management.** `getBuckets`, `createBucket`, and `removeBucket` on `BunS3Helper`.
 
@@ -524,7 +541,7 @@ interface IDiskHelperOptions extends IStorageHelperOptions {
 }
 ```
 
-Resolves `basePath` to an absolute path with `path.resolve()` and creates it (`fs.mkdirSync(..., { recursive: true })`) if it does not exist.
+Resolves `basePath` to an absolute path with `path.resolve()`. Creates it via `fs.mkdirSync(..., { recursive: true })` if it does not exist.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -546,8 +563,9 @@ app_data/storage/           <-- basePath
 
 ### defaultLinkPrefix and writeObject
 
-- `defaultLinkPrefix`: `'/static-resources/'` (the one backend that differs from `/static-assets/`).
-- `writeObject`: creates the object's parent directory if missing (`fsp.mkdir(dir, { recursive: true })`), then `fsp.writeFile(objectPath, file.buffer)`. No metadata dictionary is persisted alongside the file - `getStat()` derives `mimetype` from the filename at read time.
+- `defaultLinkPrefix`: `'/static-resources/'` - the one backend that differs from `/static-assets/`.
+- `writeObject`: creates the object's parent directory if missing, via `fsp.mkdir(dir, { recursive: true })`. Then it calls `fsp.writeFile(objectPath, file.buffer)`.
+- No metadata dictionary is persisted alongside the file. `getStat()` derives `mimetype` from the filename at read time instead.
 
 ### Methods
 
@@ -559,7 +577,7 @@ app_data/storage/           <-- basePath
 | `createBucket` | `fsp.mkdir(bucketPath, { recursive: true })`, then returns `getBucket()`. |
 | `removeBucket` | `fsp.rmdir(bucketPath)`. |
 | `removeObject` | Checks the object exists first (`fsp.access`); throws if missing. Otherwise `fsp.unlink(objectPath)`. |
-| `removeObjects` | Deletes **sequentially** by calling `removeObject()` per name in a `for` loop - if any file is missing, the error propagates immediately and remaining names are not attempted. |
+| `removeObjects` | Deletes **sequentially** by calling `removeObject()` per name in a `for` loop. If any file is missing, the error propagates immediately and remaining names are not attempted. |
 
 **`createBucket` throws:**
 
@@ -846,7 +864,7 @@ interface IBunS3HelperOptions extends IStorageHelperOptions {
 
 ### "[createBucket] Invalid name to create bucket!"
 
-**Cause:** The bucket name failed `isValidName()` - it may contain path traversal characters, start with a dot, contain shell-special characters, or exceed 255 characters.
+**Cause:** The bucket name failed `isValidName()`. See the [validation rules](#isvalidname) for exactly what's rejected.
 
 **Fix:**
 
@@ -865,7 +883,7 @@ await storage.createBucket({ name: 'my-bucket' });
 
 ### "[createBucket] Bucket already exists | name: {name}"
 
-**Cause:** `DiskHelper` throws this exact message when `createBucket()` targets a directory that already exists. `MinioHelper` and `BunS3Helper` do not perform this check themselves - an existing bucket instead surfaces whatever the `minio` SDK or the raw S3 `PUT` request returns for that case, which depends on the server.
+**Cause:** `DiskHelper` throws this exact message when `createBucket()` targets a directory that already exists. `MinioHelper` and `BunS3Helper` skip this check. An existing bucket instead surfaces whatever the `minio` SDK or the raw S3 `PUT` request returns, which depends on the server.
 
 **Fix:** Check existence first.
 
@@ -929,7 +947,7 @@ await storage.upload({
 
 ### "[upload] Invalid folder path" / "[upload] Invalid folder path | depth: {depth} | max: {max}"
 
-**Cause:** A file's `folderPath` either exceeds `maxFolderDepth` (the depth-specific message) or fails `isValidPath()` for another reason (traversal, invalid segment, the generic message).
+**Cause:** A file's `folderPath` triggers one of two messages. The depth-specific message means it exceeds `maxFolderDepth`. The generic message means it fails `isValidPath()` for another reason, such as a traversal segment.
 
 **Fix:** Keep `folderPath` within `maxFolderDepth` (default `2`) segments, and free of `..`/invalid characters.
 
@@ -950,7 +968,7 @@ const file: IUploadFile = {
 
 ### "[upload] Invalid normalized object name | name: {name}"
 
-**Cause:** A custom `normalizeNameFn` returned a value that fails `isValidPath()` - typically a traversal payload (`../../../etc/cron.d/pwn`) or a name exceeding `maxFolderDepth`. This check exists specifically because `originalName` passing validation does not guarantee the function's *output* is safe.
+**Cause:** A custom `normalizeNameFn` returned a value that fails `isValidPath()`. That's typically a traversal payload like `../../../etc/cron.d/pwn`, or a name exceeding `maxFolderDepth`. This check exists because `originalName` passing validation does not guarantee the function's *output* is safe.
 
 **Fix:** Ensure `normalizeNameFn` returns a plain relative name/path - no `..` segments, no leading `/`, no more folder segments than `maxFolderDepth` allows.
 

package/content/extensions/helpers/storage/index.md

@@ -10,7 +10,7 @@ Storage gives you one file-storage interface with interchangeable backends for S
 
 ## In one example
 
-`DiskHelper` needs no external server, so it is the fastest way to see the shape of the API - create a bucket, upload a file, get a link back.
+`DiskHelper` needs no external server, so it's the fastest way to see the shape of the API. Create a bucket, upload a file, get a link back.
 
 ```typescript
 import { DiskHelper } from '@venizia/ignis-helpers';
@@ -39,12 +39,14 @@ console.log(result);
 
 ## How it works
 
-- **`BaseStorageHelper` owns the shared logic.** It's an abstract class implementing `IStorageHelper` - name/path validation, MIME type detection, and the `upload()` orchestration itself (check the bucket exists, validate every file, write in parallel). Each backend only supplies two protected hooks: `defaultLinkPrefix` and `writeObject()`.
-- **Everything else is per-backend.** `isBucketExists`, `getBuckets`, `createBucket`, `getFile`, `getStat`, `removeObject`, `listObjects`, and the rest of `IStorageHelper` are implemented independently per backend - a filesystem `stat()` and a MinIO `statObject()` share nothing beyond the return shape.
+- **`BaseStorageHelper` owns the shared logic.** It's an abstract class implementing `IStorageHelper`: name/path validation, MIME type detection, and the `upload()` orchestration itself. Each backend only supplies two protected hooks: `defaultLinkPrefix` and `writeObject()`.
+- **Everything else is per-backend.** `isBucketExists`, `getBuckets`, `createBucket`, `getFile`, `getStat`, `removeObject`, `listObjects`, and the rest of `IStorageHelper` are implemented independently per backend. A filesystem `stat()` and a MinIO `statObject()` share nothing beyond the return shape.
 - **The three backends are interchangeable.** Write services against `IStorageHelper`, not a concrete class, and swap backends by construction only.
-- **`MemoryStorageHelper` is unrelated.** A standalone generic key-value store for in-process caching, extending `BaseHelper` directly - no bucket or file concept.
-- **Every write path is validated first.** `originalName` and `folderPath` run through `isValidName()`/`isValidPath()` before touching the filesystem or object store, rejecting path traversal (`../`), shell-injection characters, hidden files, and folder nesting beyond `maxFolderDepth` (default `2`). The same check re-runs on whatever a custom `normalizeNameFn` returns, so a traversal payload smuggled back from application code is rejected too.
-- **Two backends stay optional.** `MinioHelper` and `BunS3Helper` live behind separate sub-path exports, so apps that only need `DiskHelper` or `MemoryStorageHelper` don't pull in the `minio` package or require the Bun runtime.
+- **`MemoryStorageHelper` is unrelated.** It's a standalone generic key-value store for in-process caching, extending `BaseHelper` directly - no bucket or file concept.
+- **Every write path is validated first.** `originalName` and `folderPath` run through `isValidName()`/`isValidPath()` before touching the filesystem or object store.
+- **Validation blocks four kinds of bad input:** path traversal (`../`), shell-injection characters, hidden files, and folder nesting beyond `maxFolderDepth` (default `2`).
+- **A custom `normalizeNameFn` doesn't get a free pass.** Its output runs through the same check, so a traversal payload smuggled back from application code is rejected too.
+- **Two backends stay optional.** `MinioHelper` and `BunS3Helper` live behind separate sub-path exports. Apps that only need `DiskHelper` or `MemoryStorageHelper` don't pull in the `minio` package or require the Bun runtime.
 
 **Backends**
 
@@ -124,7 +126,8 @@ import type { IStorageHelper, IUploadFile } from '@venizia/ignis-helpers';
 class FileService {
   constructor(private storage: IStorageHelper) {}
 
-  uploadFile(bucket: string, file: IUploadFile) {
+  uploadFile(opts: { bucket: string; file: IUploadFile }) {
+    const { bucket, file } = opts;
     return this.storage.upload({ bucket, files: [file] });
   }
 }

package/content/extensions/helpers/types/index.md

@@ -6,7 +6,7 @@ difficulty: beginner
 
 # Types
 
-`@venizia/ignis-helpers` exports the utility types, lazy-value resolvers, and constant classes (`HTTP`, `GRPC`, `RuntimeModules`, ...) that the rest of the Ignis stack builds on.
+`@venizia/ignis-helpers` exports the utility types, lazy-value resolvers, and constant classes (`HTTP`, `GRPC`, `RuntimeModules`, ...) that the rest of the IGNIS stack builds on.
 
 ## In one example
 
@@ -26,10 +26,23 @@ configure({ timeout: () => 5000 });
 
 ## How it works
 
-- **Escape hatches, not the norm.** `AnyType` (`any`) and `AnyObject` (`Record<string | symbol | number, any>`) exist for the rare case a shape truly cannot be known at compile time - the framework itself prefers types derived from definitions (`typeof X.schema`) everywhere else.
-- **Nullable and async are explicit.** `TNullable<T>` (`T | undefined | null`) and `ValueOrPromise<T>` (`T | Promise<T>`) appear on most framework method signatures, since sync and async implementations share one type.
-- **Resolvers defer construction.** `TResolver`/`TAsyncResolver` and their `TValueOrResolver`/`TValueOrAsyncResolver` unions let a config option be given eagerly or lazily. `resolveValue`/`resolveValueAsync` collapse either shape to a value - class constructors are always passed through untouched, detected via `isClass()` (re-exported from `@venizia/ignis-inversion`), never invoked as a resolver.
-- **Const classes replace string unions.** A class of `static readonly` fields (`HTTP`, `GRPC`, `RuntimeModules`, `MimeTypes`, `DataTypes`) is both a value namespace and, via `TConstValue<typeof X>`, the source of its own union type - one declaration, no duplicated string literals.
+- **Escape hatches, not the norm.** `AnyType` and `AnyObject` exist for the rare case a shape truly cannot be known at compile time. The framework prefers types derived from definitions, like `typeof X.schema`, everywhere else.
+
+| Type | Is |
+|---|---|
+| `AnyType` | `any` |
+| `AnyObject` | `Record<string \| symbol \| number, any>` |
+
+- **Nullable and async are explicit.** `TNullable<T>` and `ValueOrPromise<T>` appear on most framework method signatures. One declared type covers both the sync and the async implementation.
+
+| Type | Shape |
+|---|---|
+| `TNullable<T>` | `T \| undefined \| null` |
+| `ValueOrPromise<T>` | `T \| Promise<T>` |
+
+- **Resolvers defer construction.** `TResolver`/`TAsyncResolver` and their `TValueOrResolver`/`TValueOrAsyncResolver` unions let a config option be given eagerly or lazily. `resolveValue`/`resolveValueAsync` collapse either shape to a value.
+- **Class constructors pass through untouched.** `isClass()` detects them, so the resolver never invokes a class as if it were a function. It's re-exported from `@venizia/ignis-inversion` into `helpers`.
+- **Const classes replace string unions.** A class of `static readonly` fields, for example `HTTP` or `RuntimeModules`, is a value namespace. `TConstValue<typeof X>` derives its own union type from those fields - one declaration, no duplicated string literals.
 
 ## Common tasks
 
@@ -105,7 +118,7 @@ function WithTimestamps<T extends TMixinTarget<BaseEntity>>(Base: T) {
 
 ### Flatten an intersection type for readable hover tooltips
 
-`TPrettify<T>` collapses `A & B` into a single flat object type, which IDE tooltips render far more readably than a chain of intersections.
+`TPrettify<T>` collapses `A & B` into a single flat object type. IDE tooltips render that far more readably than a chain of intersections.
 
 ```typescript
 import { TPrettify } from '@venizia/ignis-helpers';
@@ -114,7 +127,7 @@ type Merged = TPrettify<{ id: string } & { name: string }>;
 // Hovers as { id: string; name: string } instead of { id: string } & { name: string }
 ```
 
-Every type, resolver function, and constant (including the full `HTTP.Headers`, `HTTP.ResultCodes`, and `GRPC` tables) is in the [Full reference](/extensions/helpers/types/reference).
+See the [Full reference](/extensions/helpers/types/reference) for every type, resolver function, and constant - including the full `HTTP.Headers`, `HTTP.ResultCodes`, and `GRPC` tables.
 
 ## See also
 

package/content/extensions/helpers/types/reference.md

@@ -17,6 +17,27 @@ Exhaustive reference for every utility type, resolver function, and constant cla
 - [`packages/helpers/src/common/constants/mime.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/constants/mime.ts) - `MimeTypes`
 - [`packages/helpers/src/common/constants/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/common/constants/index.ts) - constants barrel
 
+## Find what you need
+
+| Looking for | Go to |
+|---|---|
+| An escape hatch (`any`, a loose object) | [General Purpose Types](#general-purpose-types) |
+| A value that may be absent, or a callback that may be async | [Nullable and Promise Types](#nullable-and-promise-types) |
+| A constructor or class type parameter | [Class and Constructor Types](#class-and-constructor-types) |
+| Telling a class from a plain function at runtime | [isClass](#isclass) |
+| Making object keys optional or required, or flattening `A & B` | [Object Utility Types](#object-utility-types) |
+| A union type derived from a const class | [Const Value Extraction Types](#const-value-extraction-types) |
+| An option that accepts an eager value or a resolver function | [Value Resolution Types and Functions](#value-resolution-types-and-functions) |
+| A config-driven field-to-type mapping | [Field Mapping Types](#field-mapping-types) |
+| DI container getter types, the `configure()` interface | [DI and Lifecycle Types](#di-and-lifecycle-types) |
+| JSX component prop types | [JSX Types](#jsx-types) |
+| Query pagination defaults, the application name | [Defaults](#defaults) |
+| Detecting Bun vs Node at runtime | [RuntimeModules](#runtimemodules) |
+| Schema data type constants | [DataTypes](#datatypes) |
+| HTTP headers, methods, status codes | [HTTP](#http) |
+| gRPC methods, headers, status codes | [GRPC](#grpc) |
+| Content-type classification (image, video, text) | [MimeTypes](#mimetypes) |
+
 ## Import paths
 
 ```typescript
@@ -76,7 +97,7 @@ import type {
 import type { Child, FC, PropsWithChildren } from '@venizia/ignis-helpers';
 ```
 
-All of the above resolve through the root `@venizia/ignis-helpers` barrel, which re-exports `./common` (and therefore `./common/types` and `./common/constants`) in full.
+All of the above resolve through the root `@venizia/ignis-helpers` barrel. It re-exports `./common` in full, which includes `./common/types` and `./common/constants`.
 
 ## General Purpose Types
 
@@ -142,7 +163,7 @@ function MyMixin<T extends TMixinTarget<BaseClass>>(Base: T) {
 const isClass: <T>(target: any) => target is TClass<T>;
 ```
 
-Declared in `@venizia/ignis-inversion` and re-exported by `helpers`. The single predicate that tells a constructor from a resolver function - the boot booters, controller factories, and `resolveValue`/`resolveValueAsync`/`resolveClass` all branch on it.
+Declared in `@venizia/ignis-inversion` and re-exported by `helpers`. It's the single predicate that tells a constructor from a resolver function. The boot booters, controller factories, and `resolveValue`/`resolveValueAsync`/`resolveClass` all branch on it.
 
 - **Filters to functions with a `prototype`** - true of every non-arrow function, so this alone is not sufficient.
 - **Decompiles the function via `Function.prototype.toString`** and regex-tests that the source text literally starts with the `class` keyword.
@@ -209,11 +230,13 @@ type TValueOrAsyncResolver<T> = T | TAsyncResolver<T>;
 const resolveValue: <T>(valueOrResolver: TValueOrResolver<T>) => T;
 ```
 
-Synchronously resolves a lazy value:
+Synchronously resolves a lazy value.
 
-- **Non-function values** - returned as-is.
-- **Class constructors** - returned as-is (detected via `isClass()`, never invoked).
-- **Resolver functions** - invoked and the result returned.
+| Input | Result |
+|---|---|
+| Non-function value | Returned as-is |
+| Class constructor | Returned as-is - detected via `isClass()`, never invoked |
+| Resolver function | Invoked; the return value is returned |
 
 ### resolveValueAsync
 
@@ -231,11 +254,13 @@ const resolveClass: <T>(
 ) => TClass<T> | string;
 ```
 
-Resolves lazy class references. Handles three cases:
+Resolves lazy class references.
 
-- **String binding keys** - returned as-is (for DI key lookups).
-- **Class constructors** - returned as-is.
-- **Resolver functions** - invoked via `resolveValue` and the result returned.
+| Input | Result |
+|---|---|
+| String binding key | Returned as-is, for DI key lookups |
+| Class constructor | Returned as-is |
+| Resolver function | Invoked via `resolveValue`; the result is returned |
 
 ### Resolution example
 
@@ -361,7 +386,13 @@ class RuntimeModules {
 type TRuntimeModule = TConstValue<typeof RuntimeModules>; // 'node' | 'bun'
 ```
 
-Runtime detection utility. `detect()` returns `'bun'` if `typeof Bun !== 'undefined'`, `'node'` otherwise. `isBun()` and `isNode()` are convenience methods that call `detect()` internally on every invocation - there is no caching.
+Runtime detection utility.
+
+| Method | Behavior |
+|---|---|
+| `detect()` | Returns `'bun'` if `typeof Bun !== 'undefined'`, else `'node'` |
+| `isBun()` | Calls `detect()` and compares to `'bun'` - no caching, runs the check every time |
+| `isNode()` | Calls `detect()` and compares to `'node'` - no caching, runs the check every time |
 
 ### DataTypes
 
@@ -439,7 +470,7 @@ Grouped by category, matching the source file's comments:
 | **Rate limiting** (de facto standard) | `X_RATELIMIT_LIMIT` | `'x-ratelimit-limit'` |
 | | `X_RATELIMIT_REMAINING` | `'x-ratelimit-remaining'` |
 | | `X_RATELIMIT_RESET` | `'x-ratelimit-reset'` |
-| **Ignis custom** | `REQUEST_TRACING_ID` | `'x-request-id'` |
+| **IGNIS custom** | `REQUEST_TRACING_ID` | `'x-request-id'` |
 | | `REQUEST_DEVICE_INFO` | `'x-device-info'` |
 | | `REQUEST_CHANNEL` | `'x-request-channel'` |
 | | `REQUEST_COUNT_DATA` | `'x-request-count'` |
@@ -489,7 +520,15 @@ Grouped by category, matching the source file's comments:
 | `HTTP.Methods.QUERY` | `'query'` (RFC 10008 `QUERY` method) |
 
 > [!IMPORTANT]
-> All `HTTP.Methods.*` tokens are lowercase - `@hono/zod-openapi` route definitions accept no other case. Each network fetcher uppercases at the wire boundary (`method.toUpperCase()`): undici only normalizes `DELETE`/`GET`/`HEAD`/`OPTIONS`/`POST`/`PUT`, so a lowercase `patch` or `query` sent as-is travels verbatim over Node and the server rejects it. Bun's `fetch` uppercases everything, which hides the bug until the app runs on Node.
+> All `HTTP.Methods.*` tokens are lowercase. `@hono/zod-openapi` route definitions accept no other case.
+
+Every IGNIS network fetcher uppercases the method at the wire boundary, via `method.toUpperCase()`. But undici, Node's `fetch` implementation, only normalizes six of the eight methods on its own:
+
+| Undici normalizes it on its own | Undici does not |
+|---|---|
+| `delete`, `get`, `head`, `options`, `post`, `put` | `patch`, `query` |
+
+A lowercase `patch` or `query` sent as-is travels verbatim over Node, and the server rejects it. Bun's `fetch` uppercases every method, which hides the bug until the app runs on Node.
 
 #### HTTP.Protocols
 
@@ -500,7 +539,7 @@ Grouped by category, matching the source file's comments:
 
 #### HTTP.ResultCodes
 
-Status codes are grouped by class under `HTTP.ResultCodes.RS_1` through `HTTP.ResultCodes.RS_5` (e.g. `HTTP.ResultCodes.RS_4.NotFound`).
+Status codes are grouped by class under `HTTP.ResultCodes.RS_1` through `HTTP.ResultCodes.RS_5` - for example, `HTTP.ResultCodes.RS_4.NotFound`.
 
 | Group | Constant | Value |
 |-------|----------|-------|