@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/extensions/components/authorization/usage.md

@@ -338,7 +338,7 @@ It supports multiple formats:
 // String array
 roles: ['admin', 'user']
 
-// Object array with identifier (preferred — matches AuthorizationRole.identifier)
+// Object array with identifier (preferred - matches AuthorizationRole.identifier)
 roles: [{ id: 1, identifier: '900_admin', priority: 900 }]
 
 // Object array with name fallback
@@ -586,24 +586,24 @@ AuthorizationEnforcerRegistry.getInstance().register({
 
 ## Custom Filtered Adapter
 
-For most apps, use the ready-made [`ScopedCasbinAdapter`](./api#scopedcasbinadapter) — it reads a single
+For most apps, use the ready-made [`ScopedCasbinAdapter`](./api#scopedcasbinadapter) - it reads a single
 edge table and needs no subclassing. Write a custom adapter only when your storage model differs.
 
 `BaseFilteredAdapter` is now thin: it provides the datasource/connector plumbing, the `isFiltered()`
 flag, no-op write methods, and a `loadLines` helper. A subclass implements **only** `loadFilteredPolicy`
-— query your store for ONE principal's policies and turn them into casbin lines.
+- query your store for ONE principal's policies and turn them into casbin lines.
 
 ```typescript
 import {
   BaseFilteredAdapter,
   ICasbinPolicyFilter,
-  type IDataSource,
+  type ICasbinPolicySource,
 } from '@venizia/ignis';
 import type { Model } from 'casbin';
 
 // Narrow the filter if you like, or use the default ICasbinPolicyFilter ({ principal: { type, id } }).
 class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
-  constructor(opts: { dataSource: IDataSource }) {
+  constructor(opts: { dataSource: ICasbinPolicySource }) {
     super({ scope: MyCustomAdapter.name, dataSource: opts.dataSource });
   }
 
@@ -628,7 +628,7 @@ class MyCustomAdapter extends BaseFilteredAdapter<ICasbinPolicyFilter> {
 ```
 
 The base no longer ships template-method hooks (`buildDirectPolicies`/`buildGroupPolicies`/…) or line
-formatters — you own line construction. See `ScopedCasbinAdapter` for a full reference implementation
+formatters - you own line construction. See `ScopedCasbinAdapter` for a full reference implementation
 (role closure, structural trees, soft-delete, schema-qualified SQL).
 
 ## AuthorizationRole Comparison
@@ -704,7 +704,7 @@ import { MetadataRegistry } from '@venizia/ignis';
 
 const registry = MetadataRegistry.getInstance();
 
-// Flat array of principal names — ideal for Casbin policy setup
+// Flat array of principal names - ideal for Casbin policy setup
 const principals = registry.getAuthorizeModelPrincipals({ format: 'array' });
 // ['article', 'user', 'configuration']
 
@@ -729,11 +729,11 @@ For multi-tenant apps where a user holds roles **scoped to specific tenants** (a
 
 There are two ways to do domain scoping:
 
-- **Scoped model (recommended)** — set `isScoped: true` + use `ScopedCasbinAdapter` + the built-in
+- **Scoped model (recommended)** - set `isScoped: true` + use `ScopedCasbinAdapter` + the built-in
   `CASBIN_RBAC_DOMAIN_SCOPED_MODEL`, and supply the request domain **per route** via `spec.domain` (or a
   global `domainResolver`). The enforcer registers the matchers for you; you do not write `domainMatching`
   or `normalizePayloadFn`.
-- **Manual flat model (lower-level)** — keep a flat `g + p` model and register `domainMatching` +
+- **Manual flat model (lower-level)** - keep a flat `g + p` model and register `domainMatching` +
   `normalizePayloadFn` yourself. Documented below under [The model](#the-model).
 
 ### Scoped model + per-route domain (recommended)
@@ -745,7 +745,7 @@ then tell each route where to read its domain from. `IAuthorizationSpec.domain`
 ```typescript
 import type { IAuthorizationDomainSource, TAuthorizationDomainResolver } from '@venizia/ignis';
 
-// (a) Declarative — read the domain id from a request param/header/query/context var:
+// (a) Declarative - read the domain id from a request param/header/query/context var:
 authorize({
   spec: {
     action: 'read',
@@ -754,7 +754,7 @@ authorize({
   },
 });
 
-// (b) Resolver — compute { type, id } yourself (return null → SYSTEM_WIDE):
+// (b) Resolver - compute { type, id } yourself (return null → SYSTEM_WIDE):
 authorize({
   spec: {
     action: 'read',
@@ -803,9 +803,9 @@ e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
 m = g(r.sub, p.sub, r.dom) && keyMatch(r.dom, p.dom) && r.obj == p.obj && r.act == p.act
 ```
 
-- `g = _, _, _` — the membership relation is **domain-aware** (subject, role, domain).
-- `g(r.sub, p.sub, r.dom)` — the registered domain matching function decides whether the request domain matches the stored membership domain (this is what makes `*` a wildcard).
-- `keyMatch(r.dom, p.dom)` — `keyMatch` is a **built-in matcher function** (no registration needed); it lets a permission with `p.dom = "*"` match any request domain.
+- `g = _, _, _` - the membership relation is **domain-aware** (subject, role, domain).
+- `g(r.sub, p.sub, r.dom)` - the registered domain matching function decides whether the request domain matches the stored membership domain (this is what makes `*` a wildcard).
+- `keyMatch(r.dom, p.dom)` - `keyMatch` is a **built-in matcher function** (no registration needed); it lets a permission with `p.dom = "*"` match any request domain.
 
 ### Registering the domain matching function
 
@@ -829,7 +829,7 @@ AuthorizationEnforcerRegistry.getInstance().register({
       name: 'casbin',
       type: AuthorizationEnforcerTypes.CASBIN,
       options: {
-        model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_MODEL },
+        model: { driver: CasbinEnforcerModelDrivers.TEXT, definition: CASBIN_RBAC_DOMAIN_SCOPED_MODEL },
         adapter,
         cached,
         // For a domain model, normalizePayloadFn MUST always return a `domain`.
@@ -848,7 +848,7 @@ AuthorizationEnforcerRegistry.getInstance().register({
 ```
 
 > [!NOTE]
-> `domainMatching` is opt-in. When omitted, domains are compared as exact strings and behavior is unchanged. The enforcer calls Casbin's `addNamedDomainMatchingFunc(roleDefinition, Util.keyMatchFunc)` internally — you never call it directly.
+> `domainMatching` is opt-in. When omitted, domains are compared as exact strings and behavior is unchanged. The enforcer calls Casbin's `addNamedDomainMatchingFunc(roleDefinition, Util.keyMatchFunc)` internally - you never call it directly.
 
 ### Choosing the matching function
 
@@ -861,26 +861,26 @@ domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.KEY_MAT
 domainMatching: { roleDefinition: 'g', fn: CasbinDomainMatchingFunctions.REGEX_MATCH };  // ^Merchant_.*$
 ```
 
-### All cases — policy lines and outcomes
+### All cases - policy lines and outcomes
 
 Given the model above with `keyMatch` registered on `g`, the request is `enforceSync(subject, domain, resource, action)`:
 
 | Case | Policy lines | Request | Outcome |
 |------|--------------|---------|---------|
 | **Scoped role** (owner/employee in a tenant) | `g, User_u, Role_owner, Merchant_A`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_A, Material.find, read)` | ✅ allow |
-| **Scoped role — isolation** | (same as above) | `(User_u, Merchant_B, Material.find, read)` | ❌ deny (`g` domain doesn't match) |
+| **Scoped role - isolation** | (same as above) | `(User_u, Merchant_B, Material.find, read)` | ❌ deny (`g` domain doesn't match) |
 | **Multi-tenant role** | `g, User_u, Role_owner, Merchant_A`<br/>`g, User_u, Role_owner, Merchant_B`<br/>`p, Role_owner, *, Material.find, read, allow` | `(User_u, Merchant_B, Material.find, read)` | ✅ allow (one `g` line per owned tenant; **single** `p` line) |
 | **Global role** (e.g. guest/onboarding) | `g, User_u, Role_guest, *`<br/>`p, Role_guest, *, Organizer.onBoarding, create, allow` | `(User_u, Merchant_anything, Organizer.onBoarding, create)` | ✅ allow (wildcard `g` domain) |
 | **Direct user permission (scoped)** | `p, User_u, Merchant_A, Report.read, read, allow` | `(User_u, Merchant_A, Report.read, read)` | ✅ allow (reflexive `g(u,u,dom)` + `keyMatch`) |
-| **Direct user permission — isolation** | (same as above) | `(User_u, Merchant_B, Report.read, read)` | ❌ deny |
+| **Direct user permission - isolation** | (same as above) | `(User_u, Merchant_B, Report.read, read)` | ❌ deny |
 | **Deny override** | `p, Role_x, *, Secret.read, read, deny`<br/>`p, Role_y, *, Secret.read, read, allow` | any domain where the user has both roles | ❌ deny (`!some(p.eft == deny)`) |
 
 > [!IMPORTANT]
-> The function is applied as `fn(requestDomain, policyDomain)` — the wildcard belongs on the **stored** side. Store only `*` or exact domain values (never `Merchant_*`) to keep isolation guaranteed.
+> The function is applied as `fn(requestDomain, policyDomain)` - the wildcard belongs on the **stored** side. Store only `*` or exact domain values (never `Merchant_*`) to keep isolation guaranteed.
 
 ### Misconfiguration is caught early
 
-If `roleDefinition` is not declared under `[role_definition]` in the model, `configure()` throws — Casbin would otherwise register the function as a silent no-op, leaving wildcard domains permanently unmatched (global roles silently denied):
+If `roleDefinition` is not declared under `[role_definition]` in the model, `configure()` throws - Casbin would otherwise register the function as a silent no-op, leaving wildcard domains permanently unmatched (global roles silently denied):
 
 ```typescript
 // model declares `g` only

package/content/extensions/components/health-check.md

@@ -200,7 +200,7 @@ Response `200`:
 
 ### Route Definition Patterns
 
-The `HealthCheckController` demonstrates all three route definition patterns supported by Ignis:
+The `HealthCheckController` demonstrates all three route definition patterns supported by IGNIS:
 
 | Pattern | Method | Used For |
 |---------|--------|----------|

package/content/extensions/components/index.md

@@ -1,6 +1,6 @@
 # Components
 
-Reusable, pluggable modules that group together related features. A component can encapsulate various resources such as providers, services, controllers, repositories, or even an entire mini-application, providing a clean way to modularize and share complex logic across Ignis applications.
+Reusable, pluggable modules that group together related features. A component can encapsulate various resources such as providers, services, controllers, repositories, or even an entire mini-application, providing a clean way to modularize and share complex logic across IGNIS applications.
 
 ## Built-in Components
 
@@ -13,8 +13,8 @@ Reusable, pluggable modules that group together related features. A component ca
 | [Request Tracker](./request-tracker) | Request logging | Request ID generation, timing, structured logging |
 | [Socket.IO](./socket-io/) | Real-time communication | WebSocket support, Redis adapter, event-based |
 | [WebSocket](./websocket/) | Real-time communication | Bun native WebSocket, Redis Pub/Sub, heartbeat |
-| [Static Asset](./static-asset/) | File management | Upload/download files, MinIO & local filesystem support |
-| [Swagger](./swagger) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
+| [Static Asset](./static-asset/) | File management | Upload/download files, MinIO, Bun S3 & local filesystem support |
+| [Swagger](./api-reference) | API documentation | OpenAPI generation, Swagger UI, Scalar UI |
 | [gRPC](/references/base/grpc-controllers) | gRPC transport | ConnectRPC integration, unary RPC, decorator-based |
 
 ## Creating a Component
@@ -80,8 +80,8 @@ Using components is a great way to organize your application's features into mod
   - [Request Tracker](./request-tracker) - Request tracking
   - [Socket.IO](./socket-io/) - Socket.IO WebSocket support
   - [WebSocket](./websocket/) - Bun native WebSocket
-  - [Static Asset](./static-asset/) - Static file serving
-  - [Swagger](./swagger) - API documentation
+  - [Static Asset](./static-asset/) - File upload/download management
+  - [Swagger](./api-reference) - API documentation
   - [gRPC](/references/base/grpc-controllers) - gRPC transport (ConnectRPC)
 
 - **References:**

package/content/extensions/components/mail/errors.md

@@ -10,13 +10,13 @@ All errors are created via `getError()` and include `statusCode`, `messageCode`,
 
 | Condition | Status | Error Code | Message |
 |-----------|--------|-----------|---------|
-| `to` is missing or empty array | 400 | `MAIL_INVALID_RECIPIENT` | `Recipient email address is required` |
-| `subject` is falsy | 400 | `MAIL_INVALID_CONFIGURATION` | `Email subject is required` |
-| Both `text` and `html` are falsy | 400 | `MAIL_INVALID_CONFIGURATION` | `Email must have either text or html content` |
-| Transport throws during `send()` | 500 | `MAIL_SEND_FAILED` | `Failed to send email: <error>` |
-| Batch operation fails | 500 | `MAIL_BATCH_SEND_FAILED` | `Failed to send batch emails: <error>` |
-| Template engine not configured for `sendTemplate()` | 500 | `MAIL_INVALID_CONFIGURATION` | `Template engine not configured` |
-| Transport throws during `verify()` | 500 | `MAIL_VERIFICATION_FAILED` | `Mail transport verification failed: <error>` |
+| `to` is missing or empty array | 400 | `core.mail.invalid_recipient` | `Recipient email address is required` |
+| `subject` is falsy | 400 | `core.mail.invalid_configuration` | `Email subject is required` |
+| Both `text` and `html` are falsy | 400 | `core.mail.invalid_configuration` | `Email must have either text or html content` |
+| Transport throws during `send()` | 500 | `core.mail.send_failed` | `Failed to send email: <error>` |
+| Batch operation fails | 500 | `core.mail.batch_send_failed` | `Failed to send batch emails: <error>` |
+| Template engine not configured for `sendTemplate()` | 500 | `core.mail.invalid_configuration` | `Template engine not configured` |
+| Transport throws during `verify()` | 500 | `core.mail.verification_failed` | `Mail transport verification failed: <error>` |
 
 ### MailComponent Errors
 
@@ -28,11 +28,11 @@ All errors are created via `getError()` and include `statusCode`, `messageCode`,
 
 | Condition | Status | Error Code | Message |
 |-----------|--------|-----------|---------|
-| Unsupported provider string | 500 | `MAIL_INVALID_CONFIGURATION` | `Unsupported mail provider: <provider>` |
-| Nodemailer options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid Nodemailer configuration` |
-| Mailgun options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid Mailgun configuration` |
-| Custom options fail type guard | 500 | `MAIL_INVALID_CONFIGURATION` | `Invalid custom mail provider configuration` |
-| Custom config missing `send`/`verify` | 500 | `MAIL_INVALID_CONFIGURATION` | `Custom mail provider must implement IMailTransport interface. Missing methods: <methods>` |
+| Unsupported provider string | 500 | `core.mail.invalid_configuration` | `Unsupported mail provider: <provider>` |
+| Nodemailer options fail type guard | 500 | `core.mail.invalid_configuration` | `Invalid Nodemailer configuration` |
+| Mailgun options fail type guard | 500 | `core.mail.invalid_configuration` | `Invalid Mailgun configuration` |
+| Custom options fail type guard | 500 | `core.mail.invalid_configuration` | `Invalid custom mail provider configuration` |
+| Custom config missing `send`/`verify` | 500 | `core.mail.invalid_configuration` | `Custom mail provider must implement IMailTransport interface. Missing methods: <methods>` |
 
 ### MailQueueExecutorProvider Errors
 
@@ -47,8 +47,8 @@ All errors are created via `getError()` and include `statusCode`, `messageCode`,
 | Condition | Status | Error Code | Message |
 |-----------|--------|-----------|---------|
 | Neither `templateName` nor `templateData` provided | -- | -- | `Either templateName or templateData must be provided` |
-| Template name not found in registry | 404 | `TEMPLATE_NOT_FOUND` | `Template not found: <name>` |
-| Missing template data keys (with `requireValidate: true`) | 400 | `MAIL_INVALID_CONFIGURATION` | `Missing template data for keys: <keys>` |
+| Template name not found in registry | 404 | `core.mail.template_not_found` | `Template not found: <name>` |
+| Missing template data keys (with `requireValidate: true`) | 400 | `core.mail.invalid_configuration` | `Missing template data for keys: <keys>` |
 
 ### Queue Executor Errors
 
@@ -78,7 +78,7 @@ this.application.bind({ key: MailKeys.MAIL_OPTIONS }).toValue({
 this.application.component(MailComponent);
 ```
 
-### "TEMPLATE_NOT_FOUND" when calling `sendTemplate()`
+### "core.mail.template_not_found" when calling `sendTemplate()`
 
 **Cause:** The template name passed to `sendTemplate()` was never registered via `templateEngine.registerTemplate()`.
 

package/content/extensions/components/mail/index.md

@@ -107,9 +107,8 @@ import {
   Binding,
   CoreBindings,
   inject,
-  applicationEnvironment,
-  toBoolean,
 } from '@venizia/ignis';
+import { applicationEnvironment, toBoolean } from '@venizia/ignis-helpers';
 import { MailComponent, MailKeys, MailProviders } from '@venizia/ignis/mail';
 
 export class NodemailerComponent extends BaseComponent {

package/content/extensions/components/mail/usage.md

@@ -81,7 +81,7 @@ await mailService.send({
   subject: '', // Empty subject triggers validation error
   html: '<p>Hello</p>',
 });
-// Error: { statusCode: 400, messageCode: 'MAIL_INVALID_CONFIGURATION', message: 'Email subject is required' }
+// Error: { statusCode: 400, messageCode: 'core.mail.invalid_configuration', message: 'Email subject is required' }
 ```
 
 ## Template Engine

package/content/extensions/components/request-tracker.md

@@ -67,7 +67,7 @@ The log format follows this structure:
 The HTTP method is padded to 8 characters for consistent alignment in log output.
 
 > [!TIP]
-> The request ID is also available in error middleware contexts (`NotFoundMiddleware`, `AppErrorMiddleware`), making it easy to correlate error logs with the original request.
+> The request ID is also available in the framework's error handlers (`notFoundHandler`, `appErrorHandler`), making it easy to correlate error logs with the original request.
 
 ## Configuration
 

package/content/extensions/components/socket-io/api.md

@@ -4,7 +4,7 @@
 
 ## Architecture
 
-The component integrates Socket.IO into the Ignis application lifecycle with runtime-specific initialization (Node.js vs Bun).
+The component integrates Socket.IO into the IGNIS application lifecycle with runtime-specific initialization (Node.js vs Bun).
 
 #### Architecture Diagram
 ```
@@ -170,7 +170,7 @@ The helper uses a **discriminated union** for its constructor options, keyed on
 interface ISocketIOServerBaseOptions {
   identifier: string;
   serverOptions: Partial<ServerOptions>;
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
   defaultRooms?: string[];               // Default: ['io-default', 'io-notification']
   authenticateTimeout?: number;           // Default: 10_000 (10 seconds)
   pingInterval?: number;                  // Default: 30_000 (30 seconds)
@@ -201,7 +201,7 @@ During construction:
 4. Calls `initRedisClients()` -- creates 3 duplicated Redis clients from the connection
 
 > [!IMPORTANT]
-> Redis clients are **duplicated** from the parent connection (`client.duplicate()`). This means the helper uses 3 independent connections (pub, sub, emitter) that inherit config from the parent but maintain separate state. The parent `RedisHelper` connection is not consumed.
+> Redis clients are **duplicated** from the parent connection (`client.duplicate()`). This means the helper uses 3 independent connections (pub, sub, emitter) that inherit config from the parent but maintain separate state. The parent `RedisSingleHelper` connection is not consumed.
 
 ### `configure()` -- Server Initialization
 
@@ -629,7 +629,7 @@ Reads all binding keys from the DI container and validates required ones:
 | Binding | Validation | Error on Failure |
 |---------|-----------|------------------|
 | `SERVER_OPTIONS` | Optional, merged with defaults via `Object.assign()` | -- |
-| `REDIS_CONNECTION` | Must be `instanceof DefaultRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
+| `REDIS_CONNECTION` | Must be `instanceof AbstractRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisSingleHelper (single), RedisClusterHelper (cluster), or RedisSentinelHelper (sentinel)"` |
 | `AUTHENTICATE_HANDLER` | Must be a function (non-null) | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
 | `VALIDATE_ROOM_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
 | `CLIENT_CONNECTED_HANDLER` | Optional, resolved from container, `null` coerced to `undefined` | -- |
@@ -681,10 +681,10 @@ Node mode is simpler because Socket.IO natively attaches to `node:http.Server`.
 
 ### Redis 3-Client Architecture
 
-The server helper creates 3 independent Redis connections from a single `DefaultRedisHelper`:
+The server helper creates 3 independent Redis connections from a single `AbstractRedisHelper` instance:
 
 ```
-RedisHelper (parent -- NOT consumed)
+RedisSingleHelper (parent -- NOT consumed)
   |
   +-- client.duplicate() --> redisPub    (for Redis adapter -- publishes)
   |
@@ -696,7 +696,7 @@ RedisHelper (parent -- NOT consumed)
 **Why 3 clients?**
 - `@socket.io/redis-adapter` requires separate pub and sub clients because a Redis connection in subscribe mode cannot execute other commands
 - `@socket.io/redis-emitter` uses its own client to emit messages independently of the adapter, enabling cross-instance broadcasting even from contexts without a direct Socket.IO reference
-- The parent `RedisHelper` connection remains independent and is not consumed -- it can be used for other purposes (e.g., caching, sessions)
+- The parent `RedisSingleHelper` connection remains independent and is not consumed -- it can be used for other purposes (e.g., caching, sessions)
 
 **`TRedisClient` type:**
 ```typescript
@@ -826,7 +826,7 @@ type TSocketIOServerOptions = ISocketIOServerNodeOptions | ISocketIOServerBunOpt
 interface ISocketIOServerBaseOptions {
   identifier: string;
   serverOptions: Partial<ServerOptions>;
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
   defaultRooms?: string[];
   authenticateTimeout?: number;
   pingInterval?: number;
@@ -915,7 +915,7 @@ interface IServerOptions extends ServerOptions {
 
 // Resolved binding values from DI container
 interface IResolvedBindings {
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
   authenticateFn: TSocketIOAuthenticateFn;
   validateRoomFn?: TSocketIOValidateRoomFn;
   clientConnectedFn?: TSocketIOClientConnectedFn;

package/content/extensions/components/socket-io/errors.md

@@ -10,7 +10,7 @@
 |--------|-----------|---------------|
 | `binding()` | `application` is falsy | `"[binding] Invalid application to bind SocketIOComponent"` |
 | `binding()` | Unsupported runtime | `"[SocketIOComponent] Unsupported runtime: <runtime>"` |
-| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `DefaultRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisHelper for single redis connection or RedisClusterHelper for redis cluster mode!"` |
+| `resolveBindings()` | `REDIS_CONNECTION` not instanceof `AbstractRedisHelper` | `"Invalid instance of redisConnection | Please init connection with RedisSingleHelper for single redis connection, RedisClusterHelper for cluster mode, or RedisSentinelHelper for sentinel mode!"` |
 | `resolveBindings()` | `AUTHENTICATE_HANDLER` is falsy | `"[DANGER][SocketIOComponent] Invalid authenticateFn to setup io socket server!"` |
 | `registerNodeHook()` | HTTP server not available | `"[SocketIOComponent] HTTP server not available for Node.js runtime!"` |
 
@@ -54,16 +54,16 @@
 
 ### "Invalid instance of redisConnection"
 
-**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `DefaultRedisHelper` (or its subclasses `RedisHelper` / `RedisClusterHelper`).
+**Cause**: The value bound to `REDIS_CONNECTION` is not an instance of `AbstractRedisHelper` (i.e. not a `RedisSingleHelper`, `RedisClusterHelper`, or `RedisSentinelHelper`).
 
-**Fix**: Use `RedisHelper` (single instance) or `RedisClusterHelper` (cluster mode):
+**Fix**: Use one of the concrete topology helpers:
 
 ```typescript
 import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
 
 // Correct -- single instance
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
-  .toValue(new RedisHelper({ name: 'socket-io', host, port, password }));
+  .toValue(new RedisSingleHelper({ name: 'socket-io', host, port, password }));
 
 // Correct -- cluster mode
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
@@ -71,7 +71,7 @@ this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
 
 // Wrong -- raw ioredis client
 this.bind({ key: SocketIOBindingKeys.REDIS_CONNECTION })
-  .toValue(new Redis(6379));  // This is NOT a DefaultRedisHelper!
+  .toValue(new Redis(6379));  // This is NOT an AbstractRedisHelper!
 ```
 
 ### "Cannot find module '@socket.io/bun-engine'"

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

@@ -76,7 +76,7 @@ import {
   SocketIOComponent,
   SocketIOBindingKeys,
 } from '@venizia/ignis/socket-io';
-import { RedisHelper, ValueOrPromise } from '@venizia/ignis-helpers';
+import { RedisSingleHelper, ValueOrPromise } from '@venizia/ignis-helpers';
 import type {
   TSocketIOAuthenticateFn,
   TSocketIOValidateRoomFn,
@@ -84,7 +84,7 @@ import type {
 } from '@venizia/ignis-helpers/socket-io';
 
 export class Application extends BaseApplication {
-  private redisHelper: RedisHelper;
+  private redisHelper: RedisSingleHelper;
 
   preConfigure(): ValueOrPromise<void> {
     this.setupSocketIO();
@@ -93,7 +93,7 @@ export class Application extends BaseApplication {
 
   setupSocketIO() {
     // 1. Redis connection (required for adapter + emitter)
-    this.redisHelper = new RedisHelper({
+    this.redisHelper = new RedisSingleHelper({
       name: 'socket-io-redis',
       host: process.env.REDIS_HOST ?? 'localhost',
       port: +(process.env.REDIS_PORT ?? 6379),
@@ -101,7 +101,7 @@ export class Application extends BaseApplication {
       autoConnect: false,
     });
 
-    this.bind<RedisHelper>({
+    this.bind<RedisSingleHelper>({
       key: SocketIOBindingKeys.REDIS_CONNECTION,
     }).toValue(this.redisHelper);
 
@@ -145,11 +145,11 @@ export class Application extends BaseApplication {
 
 #### `autoConnect: false` Rationale
 
-The `RedisHelper` is created with `autoConnect: false` because the server helper internally calls `client.duplicate()` to create 3 independent Redis connections (pub, sub, emitter). The duplicated clients inherit the `lazyConnect` setting from the parent. During `configure()`, the helper detects clients in `wait` status and explicitly calls `client.connect()` on each, then awaits all 3 to reach `ready` status before proceeding. This avoids race conditions where the parent connects before the duplicates are created.
+The `RedisSingleHelper` is created with `autoConnect: false` because the server helper internally calls `client.duplicate()` to create 3 independent Redis connections (pub, sub, emitter). The duplicated clients inherit the `lazyConnect` setting from the parent. During `configure()`, the helper detects clients in `wait` status and explicitly calls `client.connect()` on each, then awaits all 3 to reach `ready` status before proceeding. This avoids race conditions where the parent connects before the duplicates are created.
 
 #### Redis Connection Alternatives
 
-You can use either `RedisHelper` (single Redis instance) or `RedisClusterHelper` (Redis Cluster mode). Both extend `DefaultRedisHelper`, which is the type the component validates against:
+You can use `RedisSingleHelper` (single Redis instance), `RedisClusterHelper` (Redis Cluster mode), or `RedisSentinelHelper` (Sentinel HA). All extend `AbstractRedisHelper` and satisfy the `IRedisHelper` interface that the component validates against:
 
 ```typescript
 import { RedisClusterHelper } from '@venizia/ignis-helpers';
@@ -258,7 +258,7 @@ All binding keys are available in `SocketIOBindingKeys`:
 | Binding Key | Constant | Type | Required | Default |
 |------------|----------|------|----------|---------|
 | `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<ServerOptions>` | No | See defaults above |
-| `@app/socket-io/redis-connection` | `REDIS_CONNECTION` | `RedisHelper` / `RedisClusterHelper` / `DefaultRedisHelper` | **Yes** | `null` |
+| `@app/socket-io/redis-connection` | `REDIS_CONNECTION` | `IRedisHelper` (`RedisSingleHelper` / `RedisClusterHelper` / `RedisSentinelHelper`) | **Yes** | `null` |
 | `@app/socket-io/authenticate-handler` | `AUTHENTICATE_HANDLER` | `TSocketIOAuthenticateFn` | **Yes** | `null` |
 | `@app/socket-io/validate-room-handler` | `VALIDATE_ROOM_HANDLER` | `TSocketIOValidateRoomFn` | No | `null` |
 | `@app/socket-io/client-connected-handler` | `CLIENT_CONNECTED_HANDLER` | `TSocketIOClientConnectedFn` | No | `null` |
@@ -360,7 +360,7 @@ The component resolves all binding keys into a single `IResolvedBindings` object
 #### `IResolvedBindings` Interface
 ```typescript
 interface IResolvedBindings {
-  redisConnection: DefaultRedisHelper;
+  redisConnection: IRedisHelper;
   authenticateFn: TSocketIOAuthenticateFn;
   validateRoomFn?: TSocketIOValidateRoomFn;
   clientConnectedFn?: TSocketIOClientConnectedFn;

package/content/extensions/components/socket-io/usage.md

@@ -128,7 +128,7 @@ The constructor immediately calls `configure()`, which creates the `socket.io-cl
 
 #### `connect` vs `connection` Event
 
-The client-side `socket.io-client` library fires the `connect` event (no "ion" suffix) when the connection is established. The server-side `socket.io` library fires `connection` (with the suffix). This is a Socket.IO convention, not an Ignis-specific behavior. The client helper registers on `'connect'` while the server helper registers on `SocketIOConstants.EVENT_CONNECT` which equals `'connection'`.
+The client-side `socket.io-client` library fires the `connect` event (no "ion" suffix) when the connection is established. The server-side `socket.io` library fires `connection` (with the suffix). This is a Socket.IO convention, not an IGNIS-specific behavior. The client helper registers on `'connect'` while the server helper registers on `SocketIOConstants.EVENT_CONNECT` which equals `'connection'`.
 
 ### Authentication Flow
 

package/content/extensions/components/static-asset/api.md

@@ -40,7 +40,7 @@ interface IAssetControllerOptions {
 
 ## StaticAssetStorageTypes
 
-A constants class following the Ignis pattern with `static readonly` fields, a `SCHEME_SET`, and an `isValid()` method:
+A constants class following the IGNIS pattern with `static readonly` fields, a `SCHEME_SET`, and an `isValid()` method:
 
 ```typescript
 class StaticAssetStorageTypes {
@@ -112,6 +112,17 @@ Content-Disposition: attachment; filename="..."  (download endpoint only)
 
 Whitelisted metadata headers forwarded from storage: `content-type`, `content-encoding`, `cache-control`, `etag`, `last-modified`. All other metadata headers are dropped. Header values are sanitized (see [Header Sanitization](#header-sanitization)).
 
+## Object Name Decoding
+
+Hono already percent-decodes the `:objectName` path param before the handler reads it, so the controller does not decode it again - the value read from `ctx.req.valid<TObjectParams>('param')` is used as-is.
+
+A prior second `decodeURIComponent()` was actively wrong:
+
+- `report_100%.pdf` is a legal object name. Its link is `.../objects/report_100%25.pdf`; Hono hands the handler back `report_100%.pdf`, and a second decode would hit the invalid escape `%.p` and throw - the object would become unfetchable and undeletable.
+- An object named `a%2Fb.png` would decode twice into `a/b.png` - a different object than the one requested.
+
+`isValidName()`/`isValidPath()` still run on the (singly-decoded) value, so a traversal payload is rejected exactly as before - what changes is that legal names with `%` in them stop being mangled.
+
 ## IStorageHelper Interface
 
 All storage helpers implement this unified interface:
@@ -119,6 +130,7 @@ All storage helpers implement this unified interface:
 ```typescript
 interface IStorageHelper {
   isValidName(name: string): boolean;
+  isValidPath(pathStr: string, opts?: { maxDepth?: number }): boolean;
 
   // Bucket operations
   isBucketExists(opts: { name: string }): Promise<boolean>;
@@ -131,7 +143,7 @@ interface IStorageHelper {
   upload(opts: {
     bucket: string;
     files: IUploadFile[];
-    normalizeNameFn?: (opts: { originalName: string }) => string;
+    normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
     normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
   }): Promise<IUploadResult[]>;
 
@@ -155,6 +167,7 @@ interface IUploadFile {
   buffer: Buffer;
   size: number;
   encoding?: string;
+  folderPath?: string;
   [key: string | symbol]: any;
 }
 
@@ -214,8 +227,8 @@ BaseStorageHelper (abstract class)
 | Field | Type | Nullable | Default | Description |
 |-------|------|----------|---------|-------------|
 | `id` | TEXT | No | -- | Primary key (UUID) |
-| `created_at` | TIMESTAMP | No | `NOW()` | When record was created |
-| `modified_at` | TIMESTAMP | No | `NOW()` | When record was last updated |
+| `created_at` | TIMESTAMPTZ | No | `NOW()` | When record was created |
+| `modified_at` | TIMESTAMPTZ | No | `NOW()` | When record was last updated |
 | `bucket_name` | TEXT | No | -- | Storage bucket name |
 | `object_name` | TEXT | No | -- | File object name |
 | `link` | TEXT | No | -- | Access URL to the file |

package/content/extensions/components/static-asset/errors.md

@@ -4,7 +4,7 @@
 
 ## Name Validation
 
-All bucket and object names go through `helper.isValidName()` before any storage operation. The validation blocks:
+Bucket names are validated with `helper.isValidName()` (single segment - no path separators allowed). Object names, which may include folder segments (e.g., `2025/uploads/report.pdf`), are validated with `helper.isValidPath()`. The validation blocks:
 
 | Pattern | Example | Reason |
 |---------|---------|--------|
@@ -15,18 +15,18 @@ All bucket and object names go through `helper.isValidName()` before any storage
 | Long names | 256+ chars | Exceeds 255 character limit |
 | Empty names | `""`, `"  "` | Empty or whitespace-only |
 
-Every endpoint that accepts `bucketName` validates it and returns HTTP 400 `"Invalid bucket name"` on failure. Every endpoint that accepts `objectName` validates it separately and returns HTTP 400 `"Invalid object name"` on failure.
+Every endpoint that accepts `bucketName` validates it and returns HTTP 400 `"Invalid bucket name"` on failure. Every endpoint that accepts `objectName` validates it separately and returns HTTP 400 `"Invalid object name or path"` on failure.
 
 ## Troubleshooting
 
 ### "Invalid bucket/object name"
 
-**Cause:** The name fails `isValidName()` validation. Names cannot contain `..`, `/`, `\`, shell special characters, or start with `.`. Names must be <= 255 characters and non-empty.
+**Cause:** Bucket name validation: fails `isValidName()` - bucket names are single segments and cannot contain `..`, `/`, or `\`, shell special characters, or start with `.`, and must be <= 255 characters. Object name validation: fails `isValidPath()` - object names may contain `/` for folder structure but each segment must pass the same single-segment rules, and the folder depth must not exceed the configured limit.
 
 **Fix:** Ensure names follow these rules:
 - No path separators (`..`, `/`, `\`)
 - No leading dot (`.hidden`)
-- No shell special characters (`;`, `|`, `&`, `$`, `` ` ``, `<`, `>`, `(`, `)`, `{`, `}`, `[`, `]`, `!`, `#`)
+- No shell special characters (`;`, `|`, `&`, `$`, `` ` ``, `<`, `>`, `{`, `}`, `[`, `]`, `!`, `#`)
 - No control characters (`\n`, `\r`, `\0`)
 - 255 characters or fewer
 - Not empty or whitespace-only