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

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

@@ -20,13 +20,33 @@ throw getError({
 });
 ```
 
-The framework's `AppErrorMiddleware` catches `ApplicationError` instances and formats them into a consistent JSON response - see [Common tasks](#common-tasks) below.
+The framework's `AppErrorMiddleware` catches `ApplicationError` instances and formats them into a consistent JSON response.
+
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| Throw a one-off error with a status code | [Throw a free-form error](#throw-a-free-form-error) |
+| Re-throw an error you already caught and shaped | [Recognize an already-shaped error in a catch block](#recognize-an-already-shaped-error-in-a-catch-block) |
+| Declare a reusable, i18n-ready error once | [Catalog a reusable error](#catalog-a-reusable-error) |
+| Get autocomplete on `messageCode` | [Register catalog keys for messageCode autocomplete](#register-catalog-keys-for-messagecode-autocomplete) |
+| Build a message code outside a catalog | [Build a code outside a catalog](#build-a-code-outside-a-catalog) |
+| See the exact JSON shape a client receives | [Read the error response shape](#read-the-error-response-shape) |
+| Read or rehydrate a server error in a browser app | [Consume the error response from a browser client](#consume-the-error-response-from-a-browser-client) |
+| Look up what a specific input produces | [Every shape and its output](#every-shape-and-its-output) |
+| Confirm you're checking errors the safe way | [How it works](#how-it-works) - `isApplicationError()`, never `instanceof` |
 
 ## How it works
 
-- **Three equivalent entry points.** `getError(opts)`, `new ApplicationError(opts)`, and the static `ApplicationError.getError(opts)` all take the same input and build the same object - use the class form only when a direct reference reads better.
-- **Two input shapes.** Free-form (`{ message, statusCode?, messageCode? }`) covers one-off failures - most throw sites. Catalogued (`{ error: TErrorDefinition }`) raises a failure declared once at module scope, so its code, status, and default text cannot drift across the call sites that raise it.
-- **One message shape everywhere.** `message` is either the historical string (with sibling `messageCode?`/`messageArgs?`) or an object mirroring `normalized`: `{ text, code?, args? }`. Both resolve to the same `normalized`:
+- **Three equivalent entry points.** `getError(opts)`, `new ApplicationError(opts)`, and the static `ApplicationError.getError(opts)` all build the same object from the same input. Use the class form only when a direct reference reads better.
+- **Two input shapes.** Free-form covers one-off failures - most throw sites. Catalogued raises a failure declared once at module scope, so its code, status, and default text can't drift across the call sites that raise it.
+
+  | Shape | Input |
+  |---|---|
+  | Free-form | `{ message, statusCode?, messageCode? }` |
+  | Catalogued | `{ error: TErrorDefinition }` |
+
+- **One message shape everywhere.** `message` is either the historical string (with sibling `messageCode?`/`messageArgs?`), or an object mirroring `normalized`: `{ text, code?, args? }`. Both resolve to the same `normalized`:
 
   ```typescript
   getError({ message: 'Only %{n} left', messageCode: 'stock.low', messageArgs: { n: 2 } }); // flat
@@ -34,13 +54,20 @@ The framework's `AppErrorMiddleware` catches `ApplicationError` instances and fo
   getError({ error: StockErrors.LOW, messageArgs: { n: 2 } });                              // catalogued
   ```
 
-  On the catalogued form, `message` is a **partial** override - `{ message: { args } }` amends just the args and keeps the definition's `text`/`code`.
-- **Precedence, most specific first.** `code`: `message.code` -> the definition's `message.code` -> `messageCode`. `args`: `message.args` -> `messageArgs` -> the definition's `message.args`.
-- **`messageCode` always resolves to something.** `MessageCode.resolve()` lower-cases it and falls back to `MessageCode.DEFAULT` (`'core.system_error'`) when none is given or it is empty - `error.normalized.code` is never `undefined`.
-- **`normalized` is the single source, and there is no flat duplicate.** `{ text, code, args }` - `text` defaults to `message`, `code`/`args` resolve per the precedence above. `args` is always populated (`{}` when empty), so no consumer needs a null check. A client renders any error with one lookup: `translate(error.normalized.code, error.normalized.args)`. `messageCode` and `messageArgs` are INPUTS only: there is no `error.messageCode` field, and `extra` never mirrors `messageArgs`. Pass `transform` to build `normalized` yourself in place of the default.
-- **Any key the input does not declare rides into `extra`.** Attach whatever context your clients need - `getError({ message, transaction: {...} })` lands at `error.extra.transaction`. Passing `extra` explicitly works too, and the two merge with the explicit one winning. `extra` carries caller context ONLY; it is `undefined` when there is nothing to carry.
-- **`cause` reaches the native `Error.cause`,** not `extra` - wrap a lower-level failure with `getError({ message, cause: originalError })` and every tool that reads `.cause` sees it. `error` is **refused** on the free-form branch (`error?: never`) precisely so this mistake fails at compile time: `getError({ message, error: caughtError })` does not compile - use `cause`.
-- **`isApplicationError()` checks shape, not class identity.** There is one `ApplicationError` - it lives in `@venizia/ignis-inversion` so a browser application can raise and read the same errors the server does, and `helpers` re-exports it. `instanceof` still fails across a package boundary: inversion ships dual CJS+ESM builds, so one source class has two runtime constructors. Test the shape.
+  On the catalogued form, `message` is a **partial** override. `{ message: { args } }` amends just the args and keeps the definition's `text`/`code`.
+
+- **Precedence resolves most-specific-first.** See the [full precedence table](#every-shape-and-its-output) below - a definition's own `message.code` beats a flat `messageCode`.
+- **`messageCode` always resolves to something.** `MessageCode.resolve()` lower-cases it and falls back to `MessageCode.DEFAULT` (`'core.system_error'`) when none is given or empty. `error.normalized.code` is never `undefined`.
+- **`normalized` is the single source - there's no flat duplicate.** It's `{ text, code, args }`. `text` defaults to `message`; `code` and `args` resolve per the precedence table.
+- **`args` is always populated, so no consumer needs a null check.** One lookup renders any error: `translate(error.normalized.code, error.normalized.args)`.
+- **`messageCode` and `messageArgs` are INPUTS only.** There's no `error.messageCode` field, and `extra` never mirrors `messageArgs`. Pass `transform` to build `normalized` yourself in place of the default.
+- **Any key the input doesn't declare rides into `extra`.** Attach whatever context your clients need: `getError({ message, transaction: {...} })` lands at `error.extra.transaction`. Passing `extra` explicitly works too - the two merge, and the explicit one wins on a clash.
+- **`extra` carries caller context only.** It's `undefined` when there is nothing to carry.
+- **`cause` reaches the native `Error.cause`, not `extra`.** Wrap a lower-level failure with `getError({ message, cause: originalError })`, and every tool that reads `.cause` sees it.
+- **`error` is refused on the free-form branch (`error?: never`).** This makes `getError({ message, error: caughtError })` fail to compile, so the mistake is caught before runtime - use `cause` instead.
+
+> [!IMPORTANT]
+> **Use `isApplicationError()`, never `instanceof ApplicationError`.** There is one `ApplicationError` class, defined in `@venizia/ignis-inversion`. `helpers` re-exports it, so a browser app can raise and read the same errors the server does. But `instanceof` still fails across a package boundary: inversion ships dual CJS+ESM builds, so one source class has two runtime constructors. `isApplicationError()` tests shape, not identity, so it works everywhere.
 
 **Options shared by both forms**
 
@@ -53,10 +80,11 @@ The framework's `AppErrorMiddleware` catches `ApplicationError` instances and fo
 | `cause`         | `unknown`                              | The wrapped failure - reaches `Error.cause`. Use this to wrap a caught error; `error` is refused on the free-form branch for exactly this case |
 | `extra`         | `Record<string, unknown>`              | Explicit context, merged with any swept keys - and it wins on a clash                                           |
 | `transform`     | `TErrorNormalizeTransformFn`           | Builds `normalized` in place of the default. Receives `{ message: TErrorNormalized, statusCode, extra? }` - `message` is the default normalized being replaced, so `s => ({ ...s.message, text: 'x' })` amends one field |
+| `logLevel`      | `error \| emerg \| warn \| info \| debug` | The level the error handler logs this at. Defaults to `error`; lower it for an expected failure (`getError({ message, statusCode: 404, logLevel: 'warn' })`), or raise it to `emerg`. Steers the server log only - never the response |
 | _anything else_ | `unknown`                              | Rides into `extra` under its own name. `getError({ message, transaction })` lands at `error.extra.transaction`  |
 
 > [!TIP]
-> Spreading a definition now resolves identically to passing it as `error`: `getError({ ...CategoryErrors.CREATE_DUPLICATE_NAME })` and `getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME })` build the same `ApplicationError`. A definition's `message` is `{ text, code, args? }` - the same shape the free-form input accepts - so the spread degrades to nothing. Prefer `{ error: DEF }` anyway; it reads as "raise this catalogued error" instead of "raise these loose fields."
+> Spreading a definition now resolves identically to passing it as `error`: `getError({ ...CategoryErrors.CREATE_DUPLICATE_NAME })` and `getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME })` build the same `ApplicationError`. A definition's `message` is `{ text, code, args? }` - the same shape the free-form input accepts - so the spread degrades to nothing. Prefer `{ error: DEF }` anyway. It reads as "raise this catalogued error", not "raise these loose fields."
 
 ## Every shape and its output
 
@@ -190,14 +218,14 @@ throw getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME, messageArgs: { nam
 throw getError({ error: CategoryErrors.CREATE_DUPLICATE_NAME, message: { args: { name: 'Vé' } } });
 ```
 
-`ErrorScopes` groups a failure by intent - `AUTH`, `VALIDATION`, `BUSINESS`, `SYSTEM`, `INTEGRATION` - because `statusCode` cannot: a `409` is a business conflict in one place and a validation clash in another.
+`ErrorScopes` groups a failure by intent - `AUTH`, `VALIDATION`, `BUSINESS`, `SYSTEM`, `INTEGRATION`. `statusCode` can't do this job: a `409` is a business conflict in one place and a validation clash in another.
 
 > [!WARNING]
-> `category` is catalog **metadata only** - it does not reach the error response. `getError` reads `message.text`, `message.code` and `statusCode` off a definition and ignores the rest. Use it to group and filter catalogs (ops dashboards, translator exports); do not expect a client to receive it.
+> `category` is catalog **metadata only** - it does not reach the error response. `getError` reads `message.text`, `message.code` and `statusCode` off a definition and ignores the rest. Use it to group and filter catalogs (ops dashboards, translator exports). Don't expect a client to receive it.
 
 ### Register catalog keys for `messageCode` autocomplete
 
-Augment the module the file already imports from. `IErrorKeyRegistry` is declared in `@venizia/ignis-inversion` and re-exported by `helpers`; merging follows the re-export, so either name populates the same registry.
+Augment the module the file already imports from. `IErrorKeyRegistry` is declared in `@venizia/ignis-inversion` and re-exported by `helpers`. Merging follows the re-export, so either name populates the same registry.
 
 ```typescript
 import type { TRegisterErrors } from '@venizia/ignis-helpers';
@@ -225,7 +253,7 @@ const NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
 
 ### Read the error response shape
 
-`AppErrorMiddleware` (from `@venizia/ignis`) routes every thrown value into one of five shapes. All five carry `message`, `statusCode`, `normalized` and `details`; only an intentional error can carry `extra`. The code lives at `normalized.code` - there is no flat `messageCode` on the response.
+`AppErrorMiddleware` (from `@venizia/ignis`) routes every thrown value into one of five shapes. All five carry `message`, `statusCode`, `normalized` and `details`. Only an intentional error can carry `extra`. The code lives at `normalized.code` - there is no flat `messageCode` on the response.
 
 | What was thrown                           | Status  | `normalized.code`                                        | `message`                                                             | `extra`                                               |
 | ----------------------------------------- | ------- | ------------------------------------------------------ | --------------------------------------------------------------------- | ----------------------------------------------------- |
@@ -235,11 +263,11 @@ const NOT_FOUND = MessageCode.build({ parts: ['core', 'user', 'not_found'] });
 | `getError(...)` - intentional             | its own | its own                                                | its own                                                               | when the throw site attached `extra` or unknown keys  |
 | Anything else                             | 500     | `core.system_error`                                    | `Internal Server Error` in production; the raw message in development | never                                                 |
 
-Only the intentional branch reports what the throw site wrote. The other four **replace** the message, because a driver error carries SQL, schema and constraint names - and `normalized` is built from the replacement, so it can never leak what `message` just scrubbed.
+Only the intentional branch reports what the throw site wrote. The other four **replace** the message - a driver error can carry SQL, schema, and constraint names. `normalized` is built from that replacement, so it can never leak what `message` just scrubbed.
 
 `rootKey` (e.g. `new AppErrorMiddleware({ logger, rootKey: 'error' }).value()`) nests any of these under that key.
 
-The handler is fail-closed on environment: it exposes `stack` and `cause` in `details` only when `NODE_ENV` is one of `local`, `debug`, `development`, `dev`, `sit` (`Environment.DEVELOPMENT_ENVS`). Everything else - including `alpha`, `staging`, a typo, or an unset `NODE_ENV` - gets the sanitized shape:
+The handler is fail-closed on environment. It exposes `stack` and `cause` in `details` only for `Environment.DEVELOPMENT_ENVS`: `local`, `debug`, `development`, `dev`, `sit`. Everything else - including `alpha`, `staging`, a typo, or an unset `NODE_ENV` - gets the sanitized shape:
 
 ```json
 {
@@ -263,10 +291,58 @@ The handler is fail-closed on environment: it exposes `stack` and `cause` in `de
 > [!IMPORTANT]
 > **`messageCode` and `extra.messageArgs` are GONE from the response.** They duplicated `normalized.code` and `normalized.args`. Read `normalized` - it is the only source. A client still reading either must migrate: `translate(error.messageCode, error.extra?.messageArgs)` becomes `translate(error.normalized.code, error.normalized.args)`.
 >
-> Note the two `details`: the inner one is context the throw site attached (it went through `extra`), the outer one is the middleware's own request info. They are unrelated despite the name.
+> Note the two `details`. The inner one is context the throw site attached - it went through `extra`. The outer one is the middleware's own request info. They're unrelated despite sharing a name.
 
 > [!NOTE]
-> `message` and `normalized.text` are the same string unless a `transform` deliberately makes them differ - `message` stays the raw text the throw site wrote, `normalized.text` is what a client shows. Most errors never set `transform`, so most of the time they match.
+> `message` and `normalized.text` are the same string, unless a `transform` deliberately makes them differ. `message` stays the raw text the throw site wrote. `normalized.text` is what a client shows. Most errors never set `transform`, so most of the time the two match.
+
+### Consume the error response from a browser client
+
+The error layer lives in `@venizia/ignis-inversion`, not in helpers, precisely so a browser app can
+share it. It depends only on `lodash`, ships dual CJS+ESM, and pulls in no server module. A frontend
+throws its own failures with the same `getError` the server uses, and reads the server's with the
+same field names.
+
+**Reading is all most clients need.** `normalized` is on every error response:
+
+- `getError` always builds one.
+- A foreign error gets one synthesized.
+- A `ZodError` builds its own.
+
+So there's no null-check and no parsing step: one lookup handles every case.
+
+```ts
+const { error } = await response.json(); // `error` is the rootKey, if one is configured
+
+translate(error.normalized.code, error.normalized.args);
+```
+
+**Rehydrating** is for the client that wants one `catch` block for both a server failure and a
+locally thrown one. `fromError` inverts the response the middleware emitted:
+
+```ts
+import { fromError, isApplicationError } from '@venizia/ignis-inversion';
+
+const { error } = await response.json();
+throw fromError({ error }); // now an ApplicationError - isApplicationError() is true
+```
+
+| Wire field   | Where it lands                                                                    |
+| ------------ | --------------------------------------------------------------------------------- |
+| `normalized` | `normalized`, verbatim - `text`, `code` and `args` round-trip unchanged           |
+| `message`    | `normalized.text`, but only when `normalized` is missing entirely                 |
+| `statusCode` | `statusCode`; `400` when the payload carries none                                 |
+| `extra`      | `extra`, verbatim                                                                 |
+| `requestId`  | `extra.requestId` - it is the identifier a support ticket quotes, so it survives   |
+| `details`    | dropped - `url` and `path` the client already knows, and `stack` is the server's   |
+
+Every field of `TResponsedError` is optional by design: a client parses what a gateway, a proxy or an
+older server actually sent. A body that is not an IGNIS error at all still yields an
+`ApplicationError`, degraded to `MessageCode.DEFAULT` and status `400`. No call site branches on
+a parse failure.
+
+> [!TIP]
+> Same rule here: prefer `isApplicationError()` over `instanceof ApplicationError`. See the [callout above](#how-it-works) for why - a browser app bundles its own copy of the class, so `instanceof` fails across the boundary.
 
 **Common status codes**
 
@@ -290,8 +366,8 @@ The handler is fail-closed on environment: it exposes `stack` and `cause` in `de
 **Files:**
 
 - [`packages/helpers/src/modules/error/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/error/index.ts) - module barrel
-- [`packages/helpers/src/modules/error/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/error/types.ts) - `ErrorSchema`, `TErrorResponse` (the RESPONSE schema, for OpenAPI)
-- [`packages/inversion/src/modules/error/app-error.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/app-error.ts) - `ApplicationError`, `getError`, `isApplicationError`
-- [`packages/inversion/src/modules/error/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/types.ts) - `TError`, `TErrorDefinition`, `TErrorNormalized`, `IErrorKeyRegistry`, `TRegisterErrors`
+- [`packages/helpers/src/modules/error/schemas.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/error/schemas.ts) - `ErrorSchema`, `TErrorResponse` (the RESPONSE schema, for OpenAPI)
+- [`packages/inversion/src/modules/error/app-error.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/app-error.ts) - `ApplicationError`, `getError`, `fromError`, `isApplicationError`
+- [`packages/inversion/src/modules/error/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/types.ts) - `TError`, `TErrorDefinition`, `TErrorNormalized`, `TResponsedError`, `IErrorKeyRegistry`, `TRegisterErrors`
 - [`packages/inversion/src/modules/error/definition.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/definition.ts) - `ErrorScopes`, `TErrorScope`
 - [`packages/inversion/src/modules/error/message-code.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/inversion/src/modules/error/message-code.ts) - `MessageCode`

package/content/extensions/helpers/index.md

@@ -1,49 +1,63 @@
 # Helpers
 
-Reusable classes and functions providing common functionality - designed for easy injection and configuration.
-
-## Available Helpers
-
-| Helper | Purpose | Key Features |
-|--------|---------|--------------|
-| [Common Types](./types/) | Utility types | Nullable, resolvers, class types |
-| [Cron](./cron/) | Job scheduling | Cron expressions, task management |
-| [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 | 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 |
-| [Queue](./queue/) | Message queues | BullMQ, MQTT support |
-| [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, 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 |
-
-### Subpath Imports
-
-Some helpers with optional peer dependencies are only available via subpath imports to ensure proper tree-shaking:
-
-| Subpath | Peer Dependency | Description |
-|---------|-----------------|-------------|
-| `@venizia/ignis-helpers/kafka` | `@platformatic/kafka` | Kafka producer/consumer/admin/schema registry |
-| `@venizia/ignis-helpers/bullmq` | `bullmq` | BullMQ job queue |
-| `@venizia/ignis-helpers/mqtt` | `mqtt` | MQTT pub/sub client |
-| `@venizia/ignis-helpers/socket-io` | `socket.io`, `socket.io-client` | Socket.IO server/client |
-| `@venizia/ignis-helpers/minio` | `minio` | MinIO S3-compatible storage |
-| `@venizia/ignis-helpers/bun-s3` | -- | Bun native S3 storage |
-| `@venizia/ignis-helpers/cron` | `cron` | Cron job scheduling |
-| `@venizia/ignis-helpers/axios` | `axios` | Axios HTTP client |
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - Using helpers in service layer
-  - [Controllers](/guides/core-concepts/rest-controllers) - Using helpers in controllers
-
-- **References:**
-  - [Utilities](/references/utilities/) - Pure utility functions
-  - [Components](/extensions/components/) - Framework components
+Standalone utility classes for infrastructure concerns - extend `BaseHelper` for scoped logging, and inject them wherever you need them.
+
+Every peer dependency below is optional. You install one only when you use the helper that needs it.
+
+| Helper | What it does | When you reach for it | Peer dependency |
+|---|---|---|---|
+| [Types](./types/) | Shared utility types | You need IGNIS's shared TypeScript utility types | None |
+| [Cron](./cron/) | Scheduled tasks | You run code on a cron schedule | `cron` |
+| [Crypto](./crypto/) | Encryption and signing | You hash, encrypt, or sign data | None |
+| [Environment](./env/) | Env var management | You need typed, validated env var access | None |
+| [Error](./error/) | Error utilities | You throw or handle an error | None |
+| [Secrets & Vault](./secrets/) | Secrets and credentials | You read config or credentials from Vault or a vaulted `.env` | `node-vault` or `@dotenvx/dotenvx` |
+| [Inversion](./inversion/) | DI container | You build custom bindings or providers | None |
+| [Logger](./logger/) | Logging | You need scoped, leveled logging | `winston` or `pino` |
+| [Network](./network/) | HTTP/TCP/UDP clients | You call another service over HTTP, TCP, or UDP | `axios`, for the Axios client only |
+| [Kafka](./kafka/) | Kafka messaging | You publish or consume Kafka topics | `@platformatic/kafka` |
+| [Queue](./queue/) | Job queues | You need background or delayed work | `bullmq` or `mqtt` |
+| [Redis](./redis/) | Redis client | You need a Redis connection - cache, pub/sub, locks | None - `ioredis` ships with the package |
+| [Socket.IO](./socket-io/) | Socket.IO server | You build a custom real-time feature | `socket.io` |
+| [WebSocket](./websocket/) | WebSocket server | You build a custom real-time feature | None |
+| [Storage](./storage/) | File storage | You read/write files to MinIO or disk directly | `minio`, for the MinIO backend only |
+| [UID](./uid/) | Snowflake IDs | You need unique, sortable IDs | None |
+| [Worker Thread](./worker-thread/) | Worker pools | You move CPU-heavy work off the main thread | None |
+
+## Subpath imports
+
+A helper with an optional peer dependency ships from its own subpath, so a bundler never pulls in a peer you don't use.
+
+| Import from | Requires |
+|---|---|
+| `@venizia/ignis-helpers/cron` | `cron` |
+| `@venizia/ignis-helpers/axios` | `axios` |
+| `@venizia/ignis-helpers/kafka` | `@platformatic/kafka` |
+| `@venizia/ignis-helpers/bullmq` | `bullmq` |
+| `@venizia/ignis-helpers/mqtt` | `mqtt` |
+| `@venizia/ignis-helpers/socket-io` | `socket.io`, `socket.io-client` |
+| `@venizia/ignis-helpers/minio` | `minio` |
+| `@venizia/ignis-helpers/bun-s3` | none - Bun native |
+| `@venizia/ignis-helpers/hashicorp-vault` | `node-vault` |
+| `@venizia/ignis-helpers/dotenv-vault` | `@dotenvx/dotenvx` |
+| `@venizia/ignis-helpers/winston` | `winston` |
+| `@venizia/ignis-helpers/pino` | `pino` |
+
+`@venizia/ignis-helpers/common` is a subpath of a different kind. It isolates nothing - it exposes the
+part of this package that is already browser-safe: `HTTP`, `TConstValue`, and the constant and
+redaction tables. Import it when your code has to bundle for a browser.
+
+The root barrel cannot: it re-exports every module, so reaching one constant through it pulls in 14
+node builtins and 27 packages, `winston` and `ioredis` among them. A guard test bundles both entry
+points for a browser target and fails if that ever changes.
+
+```typescript
+import { HTTP } from '@venizia/ignis-helpers/common';
+```
+
+## See also
+
+- [Services](/guides/core-concepts/services) - using helpers in the service layer
+- [Controllers](/guides/core-concepts/rest-controllers) - using helpers in controllers
+- [Utilities](/references/utilities/) - pure utility functions
+- [Components](/extensions/components/) - framework components

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

@@ -29,14 +29,29 @@ container.bind<UserService>({ key: 'services.UserService' })
 const userService = container.get<UserService>({ key: 'services.UserService' });
 ```
 
-A class needs no decorator to be bindable - the binding is always created explicitly with `container.bind()`, and scope is set on the binding via `setScope()`. The framework layer (`@venizia/ignis`) creates these bindings for you for controllers, services, and repositories via `app.controller()` / `app.service()` / `@repository`.
+A class needs no decorator to be bindable. The binding is always created explicitly with `container.bind()`, and its scope is set via `setScope()`.
+
+The framework layer (`@venizia/ignis`) creates these bindings for you - for controllers, services, and repositories - via `app.controller()` / `app.service()` / `@repository`.
 
 ## How it works
 
-- **Three ways to resolve a binding.** `toClass` (container instantiates with DI), `toValue` (returned as-is), `toProvider` (factory function or `IProvider` class). All `Binding` setters return `this`, so calls chain.
-- **Instantiation is two-phase.** Constructor injection runs first, reading `@inject` metadata by parameter index and passing resolved values as constructor args; property injection runs second, assigning each `@inject`-decorated property on the built instance. `container.resolve(cls)` and `container.instantiate(cls)` are the same method - `resolve` is an alias.
+- **A binding resolves one of three ways.** All `Binding` setters return `this`, so calls chain.
+
+  | Resolver | Behavior |
+  |---|---|
+  | `toClass` | Container instantiates the class with full DI |
+  | `toValue` | Returns the value as-is |
+  | `toProvider` | Calls a factory function, or an `IProvider` class |
+
+- **Instantiation is two-phase.** `container.resolve(cls)` and `container.instantiate(cls)` are the same method - `resolve` is an alias.
+
+  | Phase | What happens |
+  |---|---|
+  | 1. Constructor injection | Reads `@inject` metadata by parameter index, passes resolved values as constructor args |
+  | 2. Property injection | Assigns each `@inject`-decorated property on the built instance |
+
 - **Every constructor parameter must carry `@inject`.** The metadata array is index-keyed - an undecorated parameter leaves a hole the container has no way to fill. `instantiate()` refuses the class by name and parameter index rather than passing `undefined`.
-- **Namespaces auto-tag bindings.** A key like `services.UserService` tags the binding `services` automatically; `setTags()` adds more. `findByTag()` queries by tag, with an `exclude` list.
+- **Namespaces auto-tag bindings.** A key like `services.UserService` tags the binding `services` automatically. `setTags()` adds more. `findByTag()` queries by tag, with an `exclude` list.
 - **Keys** can be a `string`, a `symbol`, or `{ namespace, key }` (built into a dotted string via `BindingKeys.build`).
 
 **Scopes**
@@ -47,9 +62,11 @@ A class needs no decorator to be bindable - the binding is always created explic
 | Singleton | `BindingScopes.SINGLETON` | Cached on the `Binding` after first resolution |
 
 > [!IMPORTANT]
-> Singleton caching lives on the `Binding` object, not the container. Rebinding a key creates a fresh `Binding` with its own cache; a `Binding` reference you hold onto keeps its own cache independent of `container.clear()`/`reset()` on a different `Binding` for the same key.
+> Singleton caching lives on the `Binding` object, not the container. Rebinding a key creates a fresh `Binding` with its own cache. If you hold onto an old `Binding` reference, its cache stays independent of `container.clear()`/`reset()` calls made against the new `Binding` registered under the same key.
+
+Property-injected classes only get their `@inject` properties populated when built through the container - `container.resolve()` or `instantiate()`. A plain `new MyClass()` leaves them `undefined`.
 
-Property-injected classes only get their `@inject` properties populated when built through the container (`container.resolve()`/`instantiate()`) - `new MyClass()` leaves them `undefined`. The [Full reference](/extensions/helpers/inversion/reference) covers `MetadataRegistry`, `gets()`, key formats, `IProvider`, and every error message in detail.
+The [Full reference](/extensions/helpers/inversion/reference) covers `MetadataRegistry`, `gets()`, key formats, `IProvider`, and every error message in detail.
 
 ## Common tasks
 

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

@@ -80,7 +80,7 @@ import type {
 ```
 
 > [!NOTE]
-> 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 are also available via type-only re-exports.
+> The framework package `@venizia/ignis` re-exports these DI symbols from `@venizia/ignis-inversion`, types included: `Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`, `IProvider`, `isClass`, `isClassProvider`, `TBindingScope`, `TBindingValueType`, `IBindingTag`. It also adds higher-level helpers of its own (`app.controller()`, `app.service()`, etc.).
 
 ## Class Hierarchy
 
@@ -92,7 +92,7 @@ AbstractContainer extends BaseHelper implements IContainer   # contract only - e
         └── Container                                        # instantiate() = two-phase decorator injection
 ```
 
-`AbstractContainer` exists so a container implementation that shares nothing with the shipped storage can start there; one that only wants to vary resolution extends `BaseContainer` instead. `binding/` and `container/` only talk to each other through `IContainer`/`IBinding` - there is no import cycle between the two folders.
+`AbstractContainer` exists so a container implementation that shares nothing with the shipped storage can start there. One that only wants to vary resolution extends `BaseContainer` instead. `binding/` and `container/` only talk to each other through `IContainer`/`IBinding` - there is no import cycle between the two folders.
 
 ## Creating a Container
 
@@ -124,7 +124,7 @@ const container = new Container({ scope: 'MyApp' });
 | `reset` | `reset(): void` | Remove all bindings entirely |
 | `getMetadataRegistry` | `getMetadataRegistry(): MetadataRegistry` | Return the shared `metadataRegistry` singleton |
 
-All keys passed to `bind`, `isBound`, and `unbind` are normalized with `String(key)` before being used as the `Map` key - a `Symbol` key resolves to its `.toString()` form (`'Symbol(...)'`), so a `symbol` and the equivalent string are distinct entries.
+All keys passed to `bind`, `isBound`, and `unbind` are normalized with `String(key)` before being used as the `Map` key. A `Symbol` key resolves to its `.toString()` form (`'Symbol(...)'`), so a `symbol` and the equivalent string are distinct entries.
 
 ### `instantiate()` - two-phase algorithm
 
@@ -139,10 +139,11 @@ override instantiate<T>(cls: TClass<T>): T
 
 The array is already index-keyed (`setInjectMetadata` writes to `injects[index]`) - there is no sort step. Once all arguments are resolved, `new cls(...args)` builds the instance.
 
-**Phase 2 - property injection.** Reads `registry.getPropertiesMetadata({ target: instance })`. If there is none, returns the instance as-is. Otherwise, for each `[propertyKey, metadata]` entry, resolves `this.get({ key: metadata.bindingKey, isOptional: metadata.optional ?? false })` and assigns it to `instance[propertyKey]`.
+**Phase 2 - property injection.** Reads `registry.getPropertiesMetadata({ target: instance })`. If there is none, returns the instance as-is.
 
-> [!WARNING]
-> Property injection's optional check reads `metadata.optional`, but `@inject` writes `IPropertyMetadata.isOptional` (see [`IPropertyMetadata`](#metadataregistry-types) below) - `metadata.optional` is always `undefined` at runtime, so `metadata.optional ?? false` always evaluates to `false`. In practice, `@inject({ key, isOptional: true })` on a **property** has no effect: an unbound property dependency still throws. This is a verified source-level discrepancy in `container.ts`, not a documented API - `isOptional` on a **constructor parameter** (`meta.isOptional`, phase 1) works correctly. If you need an optional dependency, use `@inject` on a constructor parameter, or resolve it manually with `container.get({ key, isOptional: true })` inside the constructor.
+Otherwise, for each `[propertyKey, metadata]` entry, resolves `this.get({ key: metadata.bindingKey, isOptional: metadata.isOptional ?? false })` and assigns it to `instance[propertyKey]`.
+
+`@inject({ key, isOptional: true })` on a **property** behaves exactly like on a constructor parameter: an unbound key resolves to `undefined` instead of throwing. A required property (`isOptional` omitted or `false`) still throws when its key is unbound.
 
 ### Key formats
 
@@ -167,7 +168,7 @@ const [svcA, svcB] = container.gets<[ServiceA, ServiceB]>({
 });
 ```
 
-Internally maps each entry through `this.get({ ...opt, isOptional: true })` - regardless of what `isOptional` was set to on the entry, `gets()` always resolves with `isOptional: true` and returns `undefined` for anything unbound rather than throwing.
+Internally maps each entry through `this.get({ ...opt, isOptional: true })`. Regardless of what `isOptional` was set on the entry, `gets()` always resolves with `isOptional: true` - anything unbound returns `undefined` instead of throwing.
 
 ## Binding
 
@@ -194,17 +195,20 @@ Internally maps each entry through `this.get({ ...opt, isOptional: true })` - re
 constructor(opts: { key: string })
 ```
 
-Splits `key` on `.`; if there is more than one segment, the first segment is auto-added as a tag via `setTags()`. `'services.UserService'` auto-tags `'services'`; a key with no `.` gets no automatic tag.
+Splits `key` on `.`. If there is more than one segment, the first segment is auto-added as a tag via `setTags()`. `'services.UserService'` auto-tags `'services'`. A key with no `.` gets no automatic tag.
 
 ### `getValue()` resolution by type
 
 | Resolver type | Behavior | Throws when |
 |----------------|----------|--------------|
 | `VALUE` | Returns the stored value directly | Never |
-| `PROVIDER` | If the stored value is a plain function, calls `provider(container)`. If it is a class matching `isClassProvider` (prototype has a `value()` method), the container `instantiate()`s the class first, then calls `.value(container)` on the instance | No `container` argument was passed - `[getValue] Invalid context/container to get provider value` |
+| `PROVIDER` (plain function) | Calls `provider(container)` | No `container` argument was passed - `[getValue] Invalid context/container to get provider value` |
+| `PROVIDER` (class, matched via `isClassProvider`) | `container.instantiate()`s the class, then calls `.value(container)` on the instance | Same as above |
 | `CLASS` | `container.instantiate(this.resolver.value)` | No `container` argument was passed - `[getValue] Invalid context/container to instantiate class` |
 
-If `bindScope` is `SINGLETON`, the resolved instance is cached on `this.cached` and returned directly on every subsequent call without re-invoking the resolver - caching is per-`Binding` instance, not per-container.
+`isClassProvider` matches a class whose prototype has a `value()` method - see [Class-based provider](#class-based-provider) below.
+
+If `bindScope` is `SINGLETON`, the resolved instance is cached on `this.cached`. Every subsequent call returns it directly without re-invoking the resolver - caching is per-`Binding` instance, not per-container.
 
 ### Class-based provider
 
@@ -279,7 +283,6 @@ interface IInjectMetadata {
 interface IPropertyMetadata {
   bindingKey: TBindingKey;
   isOptional?: boolean;
-  [key: string]: any;
 }
 ```
 
@@ -330,7 +333,7 @@ BindingKeys.build({ namespace: 'services', key: '' });
 // throws: [BindingKeys][build] Invalid key to build | key:
 ```
 
-`key` is required and must be non-empty; `namespace` is optional and silently omitted from the joined string when empty.
+`key` is required and must be non-empty. `namespace` is optional - it's silently omitted from the joined string when empty.
 
 ```typescript
 container.bind({ key: 'workers.EmailWorker' }).toClass(EmailWorker).setTags('background', 'email');
@@ -356,11 +359,13 @@ class ApplicationError extends Error {
 getError(opts: TError): ApplicationError; // factory function
 ```
 
-`opts.message` accepts two shapes: the historical string (paired with sibling `messageCode?`/`messageArgs?`), or an object mirroring `normalized` - `{ text, code?, args? }`. Both resolve to the same `normalized`; `messageCode`/`messageArgs` are lowest precedence, so `message.code`/`message.args` (or a catalogued definition's own `message.code`/`message.args`) win when both are present. There is no flat `error.messageCode`, and `extra` never mirrors `messageArgs`. `normalized.args` is always populated (`{}` when empty).
+`opts.message` accepts two shapes: the historical string (paired with sibling `messageCode?`/`messageArgs?`), or an object mirroring `normalized` - `{ text, code?, args? }`. Both resolve to the same `normalized`.
 
-The catalogued form (`{ error: TErrorDefinition }`) takes `message` as a **partial** override - `{ message: { args } }` amends just the args and keeps the definition's `text`/`code`. `error` is refused on the free-form branch (`error?: never`) - wrap a caught failure with `cause` instead.
+`messageCode`/`messageArgs` are lowest precedence - `message.code`/`message.args`, or a catalogued definition's own, win when both are present. There is no flat `error.messageCode`. `extra` never mirrors `messageArgs`. `normalized.args` is always populated (`{}` when empty).
 
-`ApplicationError`'s constructor defaults `statusCode` to `400` when omitted, and moves any property it does not model into `this.extra`. The error RESPONSE schema (`ErrorSchema`, for OpenAPI) lives in `@venizia/ignis-helpers`, not here - it needs `@hono/zod-openapi`, which inversion must not depend on because it ships to browsers.
+The catalogued form (`{ error: TErrorDefinition }`) takes `message` as a **partial** override. `{ message: { args } }` amends just the args and keeps the definition's `text`/`code`. `error` is refused on the free-form branch (`error?: never`) - wrap a caught failure with `cause` instead.
+
+`ApplicationError`'s constructor defaults `statusCode` to `400` when omitted, and moves any property it does not model into `this.extra`. The error RESPONSE schema (`ErrorSchema`, for OpenAPI) lives in `@venizia/ignis-helpers`, not here. It needs `@hono/zod-openapi`, which inversion must not depend on - inversion ships to browsers.
 
 ```typescript
 throw getError({ message: 'Something failed', statusCode: 500, messageCode: 'ERR_INTERNAL' });
@@ -407,7 +412,7 @@ interface IBindingTag {
 function isClass<T>(target: any): target is TClass<T>;
 ```
 
-`isClass` tests `typeof target === 'function' && target.prototype !== undefined` plus a regex match on the function's stringified source (`/^class[\s{]/`) - it relies on the class being emitted as an ES2024 `class`, not transpiled down to an ES5 constructor function.
+`isClass` tests `typeof target === 'function' && target.prototype !== undefined` plus a regex match on the function's stringified source (`/^class[\s{]/`). It relies on the class being emitted as an ES2024 `class`, not transpiled down to an ES5 constructor function.
 
 ```typescript
 interface IProvider<T> {
@@ -438,7 +443,7 @@ function isClassProvider<T>(target: any): target is TClass<IProvider<T>>;
 **Fix:**
 1. Verify the binding exists: `container.isBound({ key: 'services.UserService' })`.
 2. Check for typos between `@inject({ key: '...' })` and the key used in `container.bind({ key: '...' })`.
-3. If the dependency is genuinely optional, use `@inject({ key: '...', isOptional: true })` on a **constructor parameter** (not a property - see the warning above), or `container.get({ key: '...', isOptional: true })`.
+3. If the dependency is genuinely optional, add `isOptional: true` to the `@inject` call - constructor parameter or property, both work - or use `container.get({ key: '...', isOptional: true })`.
 
 ### "[getValue] Invalid context/container to instantiate class"
 
@@ -472,9 +477,12 @@ function isClassProvider<T>(target: any): target is TClass<IProvider<T>>;
 
 ### "[ClassName] Constructor parameter N has no @inject"
 
-**Cause:** A container-instantiated class has a constructor mixing decorated and undecorated parameters. `@inject` stores metadata at the parameter's index, so an undecorated parameter leaves a hole in that array; there is no channel through which the container could supply it anyway.
+**Cause:** A container-instantiated class has a constructor mixing decorated and undecorated parameters. `@inject` stores metadata at the parameter's index, so an undecorated parameter leaves a hole in that array. There is no channel through which the container could supply it anyway.
+
+**Fix:** Decorate every constructor parameter with `@inject`. There is no partial-injection escape hatch. If a value doesn't come from the container (e.g. a plain `scope: string`), choose one:
 
-**Fix:** Decorate every constructor parameter 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.
+- Pass it through a factory/provider instead of a bare constructor parameter.
+- Have the subclass forward it via its own `@inject`-decorated parameter.
 
 ### "@inject decorator can only be used on class properties or constructor parameters"
 
@@ -482,11 +490,11 @@ function isClassProvider<T>(target: any): target is TClass<IProvider<T>>;
 
 **Fix:** Only use `@inject` on constructor parameters or class properties.
 
-### Property injection returns `undefined` even without `isOptional`
+### Property injection never runs
 
-**Cause:** Either (a) the class was instantiated with `new MyClass()` directly instead of through the container - only the container reads `@inject` metadata and populates properties - or (b) the binding key really is unbound, and the `isOptional: true` you set on the property has no effect (see the phase-2 warning above, `metadata.optional` vs `metadata.isOptional`).
+**Cause:** The class was instantiated with `new MyClass()` directly instead of through the container. Only `container.resolve()`/`instantiate()` reads `@inject` metadata and populates properties. A plain `new` leaves them at whatever their field initializer set - `undefined` if none.
 
-**Fix:** Always use `container.resolve(MyClass)` or `container.instantiate(MyClass)` to create instances. If the dependency may legitimately be absent, inject it on the constructor instead of a property, or resolve it manually inside the constructor with `container.get({ key, isOptional: true })`.
+**Fix:** Always use `container.resolve(MyClass)` or `container.instantiate(MyClass)` to create instances that use property injection.
 
 ### "getInjectMetadata returns undefined"
 

package/content/extensions/helpers/kafka/admin.md

@@ -13,7 +13,7 @@ class KafkaAdminHelper extends BaseKafkaHelper<Admin>
 ```
 
 > [!NOTE]
-> `KafkaAdminHelper` has **no generic type parameters** -- the Admin client does not deal with serialized messages.
+> `KafkaAdminHelper` has **no generic type parameters** - the Admin client does not deal with serialized messages.
 
 ## Helper API
 
@@ -24,6 +24,7 @@ class KafkaAdminHelper extends BaseKafkaHelper<Admin>
 | `isHealthy()` | `(): boolean` | `true` when broker connected |
 | `isReady()` | `(): boolean` | Same as `isHealthy()` |
 | `getHealthStatus()` | `(): TKafkaHealthStatus` | `'connected'` \| `'disconnected'` \| `'unknown'` |
+| `getConnectedBrokerCount()` | `(): number` | Number of currently connected brokers |
 | `close(opts?)` | `(opts?: { isForce?: boolean }): Promise<void>` | Close the admin connection (default: graceful) |
 
 ## IKafkaAdminOptions
@@ -71,7 +72,7 @@ await helper.close({ isForce: true });
 
 ## Graceful Shutdown
 
-`close()` uses the base `closeClient()` (which calls `this.client.close()`) with a graceful timeout. If the graceful close exceeds `shutdownTimeout` (default 30s), it automatically force-closes. After `close()`, `healthStatus` is set to `'disconnected'`.
+`close()` uses the base `closeClient()`, wrapped in a graceful timeout. `closeClient()` calls `this.client.close()` directly. If the graceful close exceeds `shutdownTimeout` (default 30s), it automatically force-closes. After `close()`, `healthStatus` becomes `'disconnected'`.
 
 ```typescript
 // Graceful (recommended)