@venizia/ignis-docs 0.0.8 → 0.2.0

package/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/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/content/extensions/helpers/kafka/compile-binary.md

@@ -0,0 +1,92 @@
+# Compiling to a Single Binary
+
+`bun build --compile` produces a standalone executable that crashes on startup when the application
+imports any Kafka helper, unless the build registers `platformaticWasmPlugin`.
+
+```
+ENOENT: no such file or directory, open '/$bunfs/dist/native.wasm'
+```
+
+The failure happens while the module graph is still loading -- before the IGNIS application boots, so
+no log line, no lifecycle hook, and no error handler of yours ever runs.
+
+## Why it happens
+
+`@platformatic/kafka` computes Kafka's CRC32C checksums and lz4/snappy compression in WebAssembly,
+through `@platformatic/wasm-utils`. The default entrypoint of that package reads the wasm payload
+from disk at module load time:
+
+```javascript
+// @platformatic/wasm-utils/dist/index.js
+const wasm = readFileSync(new URL('../dist/native.wasm', import.meta.url));
+```
+
+`bun build --compile` embeds JavaScript modules only -- assets such as `native.wasm` are not carried
+into the executable. Inside the binary, `import.meta.url` resolves against the virtual `/$bunfs`
+filesystem, the file is not there, and the read throws.
+
+Running from source (`bun run`, `bun .`) is unaffected: `node_modules` is on disk, so the read
+succeeds. The bug only exists in compiled binaries.
+
+## The fix
+
+`@platformatic/wasm-utils` ships a second entrypoint, `@platformatic/wasm-utils/bundled`, exposing
+the same API with the wasm payload inlined as base64 -- no filesystem read. `platformaticWasmPlugin`
+swaps one entrypoint for the other at bundle time.
+
+Compile through a Bun build script instead of the `bun build --compile` CLI, which cannot register
+plugins:
+
+```typescript
+// scripts/compile.ts
+import { platformaticWasmPlugin } from '@venizia/ignis-helpers/kafka';
+
+const built = await Bun.build({
+  entrypoints: ['./dist/index.js'],
+  target: 'bun',
+  minify: { whitespace: true, syntax: true },
+  sourcemap: 'linked',
+  compile: {
+    target: process.env.BUN_TARGET ?? 'bun-linux-x64',
+    outfile: './dist/bin',
+  },
+  plugins: [platformaticWasmPlugin()],
+});
+
+if (!built.success) {
+  console.error(built.logs);
+  process.exit(1);
+}
+```
+
+```json
+{
+  "scripts": {
+    "compile": "bun run ./scripts/compile.ts"
+  }
+}
+```
+
+The plugin resolves `@platformatic/wasm-utils/bundled` from the importing module's own directory, so
+it works with hoisted and isolated `node_modules` layouts alike, and pins no package version.
+
+## Verifying
+
+A correctly built binary contains no reference to the wasm file on disk:
+
+```bash
+grep -c 'native.wasm' ./dist/bin   # 0 -- the payload is inlined
+./dist/bin                         # boots instead of throwing ENOENT
+```
+
+The binary grows by roughly 76 KB, the base64 form of the 57 KB wasm module.
+
+## Notes
+
+- Upgrading `@platformatic/kafka` does not remove the need for the plugin: every release to date,
+  including 2.6.1, imports the default `@platformatic/wasm-utils` entrypoint.
+- Applications that never import a Kafka helper need no plugin -- nothing pulls in
+  `@platformatic/wasm-utils`, and the plugin's resolver never fires.
+- Patching `node_modules` during the build achieves the same result, but mutates a dependency in
+  place, pins the store path to one version, and leaves the tree dirty when a build fails. The
+  plugin needs neither.

package/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/content/extensions/helpers/kafka/index.md

@@ -88,6 +88,9 @@ import type {
 > [!NOTE]
 > Kafka helpers are **not** re-exported from the main `@venizia/ignis-helpers` entry point. You must use the `@venizia/ignis-helpers/kafka` subpath import. This keeps the optional `@platformatic/kafka` peer dependency isolated for tree-shaking.
 
+> [!WARNING]
+> Compiling an application that uses these helpers with `bun build --compile` produces a binary that dies on startup with `ENOENT: /$bunfs/dist/native.wasm`. The build must register `platformaticWasmPlugin` from `@venizia/ignis-helpers/kafka` -- see [Compiling to a Single Binary](./compile-binary.md).
+
 ### Installation
 
 ```bash

package/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/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/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({