@venizia/ignis-docs 0.0.8-3 → 0.1.0

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

@@ -0,0 +1,283 @@
+# Error
+
+Standardized error class and factory for throwing HTTP-aware errors with machine-readable codes across the application.
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Package** | `@venizia/ignis-helpers` |
+| **Class** | `ApplicationError` |
+| **Extends** | `Error` (native) |
+| **Runtimes** | Both |
+
+#### Import Paths
+
+```typescript
+import { ApplicationError, getError, isApplicationError } from '@venizia/ignis-helpers';
+import { ErrorSchema } from '@venizia/ignis-helpers';
+import type { TError } from '@venizia/ignis-helpers';
+```
+
+## Creating an Instance
+
+The canonical way to raise an error in IGNIS is the standalone `getError()` factory - use it everywhere (house rule: `getError`, never `new Error`). `ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification; `getError()` constructs one for you.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+throw getError({
+  message: 'User not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+  messageCode: 'core.user.not_found',
+});
+```
+
+#### Options (`TError`)
+
+The same options apply to `getError()`, the `ApplicationError` constructor, and the static factory:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `message` | `string` | -- (required) | Human-readable error message |
+| `statusCode` | `number` | `400` | HTTP status code |
+| `messageCode` | `string` | `MessageCode.DEFAULT` (`'core.system_error'`) | Machine-readable error code for client-side handling. Always resolved through `MessageCode.resolve()` -- never left `undefined`, and lower-cased regardless of what was passed in |
+| `name` | `string` | `undefined` | Accepted by the schema but discarded by the constructor (the native `Error` name is kept) |
+
+> [!TIP]
+> The `TError` type is derived from `ErrorSchema` (a Zod schema) and uses `.catchall(z.any())`, so you can pass additional arbitrary properties beyond the four listed above. Extra properties are collected into the `extra` field on the resulting `ApplicationError` instance.
+
+#### `ApplicationError` Constructor and Static Factory
+
+`getError()` is the canonical form. The class constructor and the static `ApplicationError.getError()` are legal equivalents - use them only when a direct class reference reads better:
+
+```typescript
+import { ApplicationError, HTTP } from '@venizia/ignis-helpers';
+
+// Class constructor (equivalent to getError)
+const error = new ApplicationError({
+  message: 'Configuration missing',
+  statusCode: HTTP.ResultCodes.RS_5.InternalServerError,
+});
+
+// Static factory (equivalent to getError)
+throw ApplicationError.getError({
+  message: 'Invalid credentials',
+  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+  messageCode: 'core.auth.invalid_credentials',
+});
+```
+
+### MessageCode
+
+`MessageCode` builds and normalizes the machine-readable codes carried on `ApplicationError.messageCode`. Every code an application throws should be constructed with `MessageCode.build()` rather than typed as a raw string literal -- a malformed code fails at module load (import time) instead of shipping dead into production.
+
+```typescript
+import { MessageCode } from '@venizia/ignis-helpers';
+
+export class UserErrorCodes {
+  static readonly NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
+  static readonly DUPLICATE_EMAIL = MessageCode.build({ parts: ['core', 'user', 'duplicate_email'] });
+}
+```
+
+| Member | Type | Value / Signature | Description |
+|--------|------|--------------------|-------------|
+| `DEFAULT` | `string` | `'core.system_error'` | The code `ApplicationError` falls back to when no `messageCode` is supplied |
+| `SEPARATOR` | `string` | `'.'` | Joins segments into a dotted code (e.g. `core.mail.send_failed`) |
+| `SEGMENT_PATTERN` | `RegExp` | `/^[a-z0-9]+(_[a-z0-9]+)*$/` | Each segment must be lower snake_case -- `a-z`, `0-9`, `_` |
+| `MIN_SEGMENTS` | `number` | `2` | A code needs at least a namespace and a reason (e.g. `core.not_found` is valid, `not_found` alone is not) |
+| `build(opts: { parts: Array<string> })` | `string` | -- | Joins `parts` with `SEPARATOR` and lower-cases the result. Throws (via `getError`) if `parts.length < MIN_SEGMENTS`, or if any segment fails `SEGMENT_PATTERN` |
+| `isValid(code: string)` | `boolean` | -- | Cheap structural check for a code arriving from outside the process |
+| `resolve(code?: string)` | `string` | -- | Normalizes an absent or empty code to `DEFAULT`; otherwise lower-cases `code` |
+
+> [!IMPORTANT]
+> `ApplicationError`'s constructor always calls `MessageCode.resolve(messageCode)` -- so `error.messageCode` is **never** `undefined`, and it is **always lower-cased** regardless of the casing passed to `getError()`. A comparison like `error.messageCode === 'DUPLICATE_EMAIL'` is always false; compare against `'duplicate_email'` (or the exact string returned by `MessageCode.build()`).
+
+## Checking for an Application Error
+
+Use `isApplicationError(error)` to recognize an application error by **shape** - an `Error` instance carrying a numeric `statusCode` - rather than by class identity:
+
+```typescript
+import { isApplicationError } from '@venizia/ignis-helpers';
+
+try {
+  await someOperation();
+} catch (error) {
+  if (isApplicationError(error)) {
+    // already shaped (has a statusCode) - surface as-is
+    throw error;
+  }
+  // an unknown failure - sanitize before rethrowing
+  throw getError({ message: 'Operation failed', statusCode: HTTP.ResultCodes.RS_5.InternalServerError });
+}
+```
+
+> [!WARNING]
+> Never compare `ApplicationError` with `instanceof` across a package boundary. `inversion` ships **dual CJS + ESM** builds (its DI powers frontend libraries), so its error class deliberately has more than one runtime identity, and `helpers` keeps its own `ApplicationError` for the backend stack. Two objects that are both "an application error" can be instances of different classes, so `instanceof` gives false negatives. `isApplicationError` checks the shape and works regardless of which package threw. The search connectors use it to decide what is already shaped versus what must be sanitized as a `503`.
+
+## Usage
+
+### Throwing Errors in Services
+
+The most common pattern is throwing `ApplicationError` from service methods to signal HTTP-level failures. The framework's error handling middleware catches these and formats the response automatically.
+
+```typescript
+import { getError, HTTP } from '@venizia/ignis-helpers';
+
+class AuthenticationService {
+  async signUp(opts: { username: string; credential: string }) {
+    const existingUser = await this.userRepository.findByUsername(opts.username);
+    if (existingUser) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        message: 'Username already exists',
+      });
+    }
+    // ...
+  }
+}
+```
+
+### Using `messageCode` for Client-Side Handling
+
+The `messageCode` field allows frontend applications to map errors to localized messages or specific UI behaviors without parsing the human-readable `message` string.
+
+```typescript
+throw getError({
+  message: 'Email verification required before login',
+  statusCode: HTTP.ResultCodes.RS_4.Forbidden,
+  messageCode: 'auth.email_not_verified',
+});
+```
+
+### Error Response Format
+
+The built-in `appErrorHandler` middleware (from `@venizia/ignis`) catches `ApplicationError` instances and formats them into consistent JSON responses. The response shape differs by environment.
+
+#### Sanitized (Production-Class) Response
+
+The handler is **fail-closed**: it exposes internals only when `NODE_ENV` names a development environment - one of `local`, `debug`, `development`, `dev`, `sit` (`Environment.DEVELOPMENT_ENVS`). Everything else is sanitized as production: `production`, and also `alpha`, `beta`, `uat`, `staging`, an unrecognized name, and an unset `NODE_ENV`.
+
+In a sanitized response, `stack` and `cause` are omitted from `details`. For unexpected errors without a `statusCode` (i.e., not thrown via `getError`), the raw message is replaced with a generic `"Internal Server Error"`, and a database error keeps only its base message - no SQL detail, no table or constraint name.
+
+```json
+{
+  "message": "User not found",
+  "messageCode": "core.user.not_found",
+  "statusCode": 404,
+  "requestId": "abc-123-def",
+  "details": {
+    "url": "http://localhost:3000/api/users/123",
+    "path": "/api/users/123"
+  }
+}
+```
+
+#### Development Response
+
+In a development environment (see the list above), `details` additionally includes debugging fields:
+
+```json
+{
+  "message": "User not found",
+  "messageCode": "core.user.not_found",
+  "statusCode": 404,
+  "requestId": "abc-123-def",
+  "details": {
+    "url": "http://localhost:3000/api/users/123",
+    "path": "/api/users/123",
+    "stack": "Error: User not found\n    at ...",
+    "cause": "..."
+  }
+}
+```
+
+### ErrorSchema (Zod)
+
+`ErrorSchema` is a Zod object schema used for OpenAPI response documentation. It is typically referenced in route definitions to describe error responses.
+
+```typescript
+import { ErrorSchema, HTTP } from '@venizia/ignis-helpers';
+
+// In route definition responses
+const responses = {
+  [HTTP.ResultCodes.RS_4.NotFound]: {
+    description: 'Resource not found',
+    content: {
+      'application/json': { schema: ErrorSchema },
+    },
+  },
+};
+```
+
+The schema shape:
+
+```typescript
+const ErrorSchema = z
+  .object({
+    name: z.string().optional(),
+    statusCode: z.number().optional(),
+    messageCode: z.string().optional(),
+    message: z.string(),
+  })
+  .catchall(z.any());
+```
+
+### Common Status Code Patterns
+
+| Scenario | Status Code | `HTTP.ResultCodes` Path |
+|----------|-------------|-------------------------|
+| Invalid input / bad request | 400 | `RS_4.BadRequest` |
+| Missing or invalid auth | 401 | `RS_4.Unauthorized` |
+| Insufficient permissions | 403 | `RS_4.Forbidden` |
+| Resource not found | 404 | `RS_4.NotFound` |
+| Duplicate resource | 409 | `RS_4.Conflict` |
+| Validation error | 422 | `RS_4.UnprocessableEntity` |
+| Server failure | 500 | `RS_5.InternalServerError` |
+
+## Troubleshooting
+
+### `statusCode` defaults to 400
+
+**Cause:** `getError()` was called without specifying a `statusCode`. The `ApplicationError` constructor defaults to `400` (Bad Request).
+
+**Fix:** Always provide an explicit status code using `HTTP.ResultCodes`:
+
+```typescript
+throw getError({
+  message: 'Resource not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+});
+```
+
+### Error response missing `stack` and `cause`
+
+**Cause:** `NODE_ENV` is not one of the development environments, so the handler sanitized the response (`url` and `path` are always included). Note this is what happens on `alpha`/`staging`, on a typo'd name, and when `NODE_ENV` is unset - not only on `production`.
+
+**Fix:** Set `NODE_ENV` to a development name - `development`, `dev`, `local`, `debug` or `sit`. Anything else stays sanitized by design.
+
+### Errors returning 500 instead of expected status code
+
+**Cause:** A plain `Error` (not `ApplicationError`) was thrown. The `appErrorHandler` middleware only reads `statusCode` from errors that have that property. Native `Error` instances default to `500`.
+
+**Fix:** Use `getError()` or `new ApplicationError()` instead of `new Error()`:
+
+```typescript
+// Incorrect -- will return 500
+throw new Error('Not found');
+
+// Correct -- will return 404
+throw getError({
+  message: 'Not found',
+  statusCode: HTTP.ResultCodes.RS_4.NotFound,
+});
+```
+
+## See Also
+
+- [Controllers](/references/base/controllers) -- Throwing errors in route handlers
+- [Services](/references/base/services) -- Error handling in business logic
+- [Middlewares](/references/base/middlewares) -- The `appErrorHandler` middleware
+- [Helpers Index](/extensions/helpers/) -- All available helpers
+- [Logger Helper](/extensions/helpers/logger/) -- Logging errors

package/{wiki → content}/extensions/helpers/index.md

@@ -11,7 +11,7 @@ Reusable classes and functions providing common functionality - designed for eas
 | [Crypto](./crypto/) | Cryptographic operations | AES/RSA/ECDH encryption, key exchange, hashing |
 | [Environment](./env/) | Environment variables | Centralized config access |
 | [Error](./error/) | Error handling | `ApplicationError`, consistent responses |
-| [Inversion](./inversion/) | Dependency injection | DI container implementation |
+| [Inversion](./inversion/) | Dependency injection | IoC container - separate package `@venizia/ignis-inversion` |
 | [Logger](./logger/) | Logging | Winston-based, multiple transports, scopes |
 | [Network](./network/) | Network requests | HTTP, TCP, UDP helpers |
 | [Kafka](./kafka/) | Event streaming | Apache Kafka producer/consumer/admin/schema registry |
@@ -19,8 +19,7 @@ Reusable classes and functions providing common functionality - designed for eas
 | [Redis](./redis/) | Redis operations | Single/cluster, key-value, hashes, JSON, pub/sub |
 | [Socket.IO](./socket-io/) | Real-time communication | Socket.IO client/server helpers |
 | [WebSocket](./websocket/) | Real-time communication | Bun native WebSocket server/emitter, Redis scaling |
-| [Storage](./storage/) | File storage | In-memory, Minio object storage |
-| [Testing](./testing/) | Test utilities | Test plan runner, base test classes |
+| [Storage](./storage/) | File storage | In-memory, disk, MinIO, Bun S3 object storage |
 | [UID](./uid/) | Unique ID generation | Snowflake IDs, Base62 encoding |
 | [Worker Thread](./worker-thread/) | Worker threads | Node.js worker management |
 

package/{wiki → content}/extensions/helpers/inversion/index.md

@@ -1,6 +1,6 @@
 # Inversion (DI)
 
-Standalone IoC container with decorator-based injection, fluent binding API, and singleton/transient scoping -- the foundation layer for all Ignis packages.
+Standalone IoC container with decorator-based injection, fluent binding API, and singleton/transient scoping -- the foundation layer for all IGNIS packages.
 
 ## Quick Reference
 
@@ -50,7 +50,7 @@ import type {
 ```
 
 > [!NOTE]
-> The framework package `@venizia/ignis` re-exports DI-specific symbols (`Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`, `IProvider`, `isClass`, `isClassProvider`, `isClassConstructor`, `TBindingScope`, `TBindingValueType`, `IBindingTag`) from `@venizia/ignis-inversion` and adds higher-level helpers (`app.controller()`, `app.service()`, etc.). All types from inversion are also available via type-only re-exports.
+> The framework package `@venizia/ignis` re-exports DI-specific symbols (`Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`, `IProvider`, `isClass`, `isClassProvider`, `TBindingScope`, `TBindingValueType`, `IBindingTag`) from `@venizia/ignis-inversion` and adds higher-level helpers (`app.controller()`, `app.service()`, etc.). All types from inversion are also available via type-only re-exports.
 
 ## Creating an Instance
 
@@ -160,7 +160,7 @@ import { inject, injectable, BindingScopes } from '@venizia/ignis-inversion';
 class UserService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
-    private userRepo: UserRepository,
+    private userRepository: UserRepository,
 
     @inject({ key: 'services.Logger', isOptional: true })
     private logger?: Logger,
@@ -168,7 +168,10 @@ class UserService {
 }
 ```
 
-The container reads `@inject` metadata during `instantiate()`, sorts by parameter index, resolves each dependency, and passes them as constructor arguments.
+The container reads `@inject` metadata during `instantiate()` by constructor index (the `Reflect`-stored array is already index-keyed - no sort is performed), resolves each dependency, and passes them as constructor arguments.
+
+> [!IMPORTANT]
+> Every constructor parameter of a container-instantiated class must carry `@inject`. Mixing decorated and undecorated parameters is refused: an undecorated parameter leaves a hole in the index-keyed metadata array, and there is no channel through which the container could supply it anyway. `instantiate()` throws `[ClassName] Constructor parameter N has no @inject | Every parameter of a container-instantiated class must be decorated - the container cannot supply an undecorated one`.
 
 ### Property Injection
 
@@ -178,7 +181,7 @@ import { inject, injectable } from '@venizia/ignis-inversion';
 @injectable({})
 class UserService {
   @inject({ key: 'repositories.UserRepository' })
-  private userRepo: UserRepository;
+  private userRepository: UserRepository;
 
   @inject({ key: 'services.Logger', isOptional: true })
   private logger?: Logger;
@@ -189,7 +192,7 @@ class UserService {
 > Property-injected classes must be instantiated through the container (`container.resolve()` or `container.instantiate()`). Using `new MyClass()` directly will leave `@inject` properties as `undefined`.
 
 The instantiation algorithm is two-phase:
-1. **Constructor injection** -- reads `@inject` metadata on the constructor, sorts by parameter index, resolves from container
+1. **Constructor injection** -- reads `@inject` metadata on the constructor by parameter index (no sort - the metadata is already index-keyed), resolves from container
 2. **Property injection** -- reads property metadata, resolves and assigns each dependency to the instance
 
 ### Scopes (Singleton / Transient)
@@ -511,7 +514,6 @@ interface IInjectableMetadata {
 // Type guards
 function isClass<T>(target: any): target is TClass<T>;
 function isClassProvider<T>(target: any): target is TClass<IProvider<T>>;
-function isClassConstructor(fn: Function): boolean;
 ```
 
 ## Troubleshooting
@@ -555,6 +557,12 @@ function isClassConstructor(fn: Function): boolean;
 
 **Fix:** Provide a non-empty `key` string: `BindingKeys.build({ namespace: 'services', key: 'UserService' })`.
 
+### "[ClassName] Constructor parameter N has no @inject"
+
+**Cause:** A container-instantiated class has a constructor with a mix of decorated and undecorated parameters. `@inject` stores its metadata at the parameter's index, so an undecorated parameter leaves a hole in that index-keyed array; there is no channel through which the container could supply it anyway. `instantiate()` refuses the shape by name and index rather than passing `undefined`.
+
+**Fix:** Decorate every constructor parameter of the class with `@inject`. There is no partial-injection escape hatch - if a value does not come from the container (e.g. a plain `scope: string`), pass it through a factory/provider instead of a bare constructor parameter, or have the subclass forward it via its own `@inject`-decorated parameter.
+
 ### "@inject decorator can only be used on class properties or constructor parameters"
 
 **Cause:** The `@inject` decorator was applied to something other than a class property or constructor parameter.

package/{wiki → content}/extensions/helpers/kafka/examples.md

@@ -251,7 +251,7 @@ const consumer = KafkaConsumerHelper.newInstance({
 await consumer.start({ topics: ['orders'] });
 ```
 
-## Using Helpers with Ignis IoC
+## Using Helpers with IGNIS IoC
 
 ```typescript
 import {

package/{wiki → content}/extensions/helpers/logger/index.md

@@ -189,6 +189,34 @@ class UserService {
 }
 ```
 
+### Logging Errors: `%s`, Never `%j`
+
+`message` and `stack` are non-enumerable properties on a native `Error`. `%j` formats via `JSON.stringify`, which only visits enumerable own properties, so `logger.error('Failed: %j', error)` silently drops both `message` and `stack` -- the two fields the log line exists to capture. Always pair an `Error` argument with `%s`; reserve `%j`/`%o` for plain data objects.
+
+```typescript
+// ✅ Good - %s prints message + stack
+logger.error('Failed to create user: %s', error);
+
+// ❌ Bad - %j drops message and stack (non-enumerable on Error)
+logger.error('Failed to create user: %j', error);
+```
+
+### Object Inspection Depth for `%s`
+
+Node hard-codes `depth: 0` for `%s` in `util.format` -- an object passed to `%s` collapses to `[Object]`, hiding the nested `extra` or `cause` a wrapped error carries. IGNIS's formatter (`formatLogMessage`/`deepSplat`) pre-inspects any object bound to a `%s` placeholder before handing the message to Winston, widening that depth so nested fields print instead of collapsing.
+
+```typescript
+logger.error('Failed: %s', error); // nested `error.cause` is now visible, not `[Object]`
+```
+
+The inspection depth defaults to `5` and is configurable via `APP_ENV_LOGGER_INSPECT_DEPTH`:
+
+```bash
+APP_ENV_LOGGER_INSPECT_DEPTH=8
+```
+
+The value must be a non-negative integer. An absent, empty, negative, or unparseable value falls back to the default of `5` -- there is no "unlimited" setting.
+
 ### Log Formats
 
 The logger supports two output formats, controlled by the `APP_ENV_LOGGER_FORMAT` environment variable (default: `text`).
@@ -396,7 +424,7 @@ Debug logs require **both** conditions to be met:
 1. `DEBUG=true` environment variable is set (parsed via `toBoolean`)
 2. `NODE_ENV` is either unset **or** is present in the `Environment.COMMON_ENVS` set
 
-The `COMMON_ENVS` set includes: `local`, `debug`, `development`, `alpha`, `beta`, `staging`, `production`. You can extend this set with `APP_ENV_EXTRA_LOG_ENVS`:
+The `COMMON_ENVS` set includes: `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production`. You can extend this set with `APP_ENV_EXTRA_LOG_ENVS`:
 
 ```bash
 DEBUG=true
@@ -473,6 +501,7 @@ The buffer wraps around at 65,536 entries using bitwise AND masking (`writeIndex
 | `APP_ENV_EXTRA_LOG_ENVS` | _(empty)_ | Comma-separated additional environments to allow debug |
 | `APP_ENV_LOGGER_FORMAT` | `text` | Output format (`json` or `text`) |
 | `APP_ENV_LOGGER_FOLDER_PATH` | `./` | Log files directory |
+| `APP_ENV_LOGGER_INSPECT_DEPTH` | `5` | Object inspection depth for `%s` placeholders. Non-negative integer only; invalid or absent falls back to `5` |
 
 #### File Rotation
 
@@ -502,6 +531,7 @@ APP_ENV_APPLICATION_NAME=my-service
 DEBUG=true
 APP_ENV_LOGGER_FORMAT=json
 APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
+APP_ENV_LOGGER_INSPECT_DEPTH=5
 
 # File rotation
 APP_ENV_LOGGER_FILE_FREQUENCY=24h
@@ -547,7 +577,7 @@ APP_ENV_LOGGER_DGRAM_LEVELS=error,warn,info
 
 **Fix:**
 1. Verify `DEBUG=true` is set in your environment.
-2. Verify `NODE_ENV` is set to one of: `local`, `debug`, `development`, `alpha`, `beta`, `staging`, `production` -- or is unset entirely.
+2. Verify `NODE_ENV` is set to one of: `local`, `debug`, `development`, `dev`, `sit`, `uat`, `alpha`, `beta`, `staging`, `production` -- or is unset entirely.
 3. If you use a custom environment name (e.g. `qa`), add it to `APP_ENV_EXTRA_LOG_ENVS=qa`.
 
 ```bash

package/{wiki → content}/extensions/helpers/network/index.md

@@ -332,6 +332,12 @@ class PaymentGateway extends AxiosNetworkRequest {
 }
 ```
 
+#### Request Logging & Redaction
+
+Both `NodeFetcher` and `AxiosFetcher` log every outbound request at `info` level (`URL: %s | Props: %s | ...`), including the request config -- headers, body, and any other options passed to `send()`. Before that log line is written, the request config is run through `redactSecrets()`, so values under secret-looking keys never reach the log.
+
+Redaction matches by key name, case-insensitively, at any depth -- both options-object spellings (`apiKey`, `token`, `password`, `authorization`, ...) and HTTP header spellings (`x-api-key`, `x-csrf-token`, `cookie`, `set-cookie`, `proxy-authorization`, `www-authenticate`, ...). A header like `'X-API-Key': process.env.PAYMENT_API_KEY` or `'Authorization': 'Bearer my-token'` (as in the examples above) is logged as `'[REDACTED]'`, not the real value. This redaction happens automatically -- there is nothing to configure.
+
 #### Convenience Methods
 
 ```typescript

package/{wiki → content}/extensions/helpers/queue/index.md

@@ -75,7 +75,7 @@ All queue helpers extend `BaseHelper` (Kafka helpers via `BaseKafkaHelper`), pro
 The `BullMQHelper` wraps the BullMQ library for Redis-backed job queuing. It operates in one of two roles: `'queue'` (producer) or `'worker'` (consumer). The role is set at construction time and determines which BullMQ primitives are initialized.
 
 ```typescript
-import { DefaultRedisHelper } from '@venizia/ignis-helpers';
+import { RedisSingleHelper } from '@venizia/ignis-helpers';
 import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
 
 const worker = new BullMQHelper({
@@ -107,7 +107,7 @@ const worker = new BullMQHelper({
 | `queueName` | `string` | -- | Name of the BullMQ queue. Must be non-empty. |
 | `identifier` | `string` | -- | Unique identifier used for scoped logging. |
 | `role` | `TBullQueueRole` | -- | `'queue'` (producer) or `'worker'` (consumer). |
-| `redisConnection` | `DefaultRedisHelper` | -- | Redis helper instance. The helper calls `getClient().duplicate()` internally. |
+| `redisConnection` | `IRedisHelper` | -- | Redis helper instance. The helper calls `duplicateClient()` internally. |
 | `numberOfWorker` | `number` | `1` | Worker concurrency (number of jobs processed in parallel). |
 | `lockDuration` | `number` | `5400000` | Job lock duration in milliseconds (default: 90 minutes). |
 | `onWorkerData` | `(job: Job<TQueueElement, TQueueResult>) => Promise<any>` | `undefined` | Job processing callback. If omitted, the worker logs job details. |
@@ -115,7 +115,7 @@ const worker = new BullMQHelper({
 | `onWorkerDataFail` | `(job: Job<TQueueElement, TQueueResult> \| undefined, error: Error) => Promise<void>` | `undefined` | Callback fired when a job fails. |
 
 > [!IMPORTANT]
-> Pass the `DefaultRedisHelper` instance to `redisConnection`, **not** the raw ioredis client. The helper internally calls `redisConnection.getClient().duplicate()` to create dedicated connections for the queue and worker.
+> Pass an `IRedisHelper` instance to `redisConnection`, **not** the raw ioredis client. The helper internally calls `redisConnection.duplicateClient()` to create dedicated connections for the queue and worker.
 
 ### MQTTClientHelper
 
@@ -162,6 +162,9 @@ const mqttClient = new MQTTClientHelper({
 | `onError` | `(error: Error) => void` | `undefined` | Callback fired on client errors. |
 | `onClose` | `(error?: Error) => void` | `undefined` | Callback fired when the connection is closed. |
 
+> [!NOTE]
+> At connect time, `MQTTClientHelper` logs the broker `url` through `redactUrlCredentials()` and the `options` object through `redactSecrets()`. If `url` embeds a password (e.g. `mqtts://user:hunter2@broker:8883`), the password never reaches the log -- only `mqtts://user:[REDACTED]@broker:8883` does.
+
 ### QueueHelper
 
 The `QueueHelper` is a generator-based, in-memory queue with a built-in state machine. It processes enqueued items one at a time, making it suitable for sequential task processing within a single process.
@@ -442,34 +445,28 @@ If `onWorkerData` is not provided, the worker logs the job's `id`, `name`, and `
 
 ### BullMQ -- Redis Cluster
 
-When using Redis Cluster with BullMQ, you must set `maxRetriesPerRequest: null` on the cluster config -- this is **required** by BullMQ.
+When using Redis Cluster with BullMQ, use `RedisClusterHelper`. Set `maxRetriesPerRequest: null` inside `clusterOptions.redisOptions` -- this is **required** by BullMQ.
 
 ```typescript
-import { Cluster } from 'ioredis';
-import { DefaultRedisHelper } from '@venizia/ignis-helpers';
+import { RedisClusterHelper } from '@venizia/ignis-helpers';
 import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
 
-const cluster = new Cluster(
-  [
+const redisHelper = new RedisClusterHelper({
+  name: 'cluster-redis',
+  nodes: [
     { host: 'node1.redis.example.com', port: 6379 },
     { host: 'node2.redis.example.com', port: 6379 },
     { host: 'node3.redis.example.com', port: 6379 },
   ],
-  {
-    maxRetriesPerRequest: null,  // Required by BullMQ
+  clusterOptions: {
     enableReadyCheck: true,
     scaleReads: 'slave',
     redisOptions: {
       password: 'your-password',
       tls: {},
+      maxRetriesPerRequest: null,  // Required by BullMQ
     },
-  }
-);
-
-const redisHelper = new DefaultRedisHelper({
-  scope: 'BullMQ',
-  identifier: 'cluster-redis',
-  client: cluster,
+  },
 });
 
 const worker = BullMQHelper.newInstance({