@venizia/ignis-docs 0.0.7 → 0.0.8-1

package/wiki/{references → extensions}/components/websocket/index.md

@@ -11,20 +11,24 @@
 |------|-------|
 | **Package** | `@venizia/ignis` (core component) + `@venizia/ignis-helpers` (helper classes) |
 | **Component** | `WebSocketComponent` |
-| **Server Helper** | [`WebSocketServerHelper`](/references/helpers/websocket/) |
+| **Server Helper** | [`WebSocketServerHelper`](/extensions/helpers/websocket/) |
 | **Emitter Helper** | `WebSocketEmitter` (standalone Redis publisher) |
 | **Runtimes** | Bun only (throws on Node.js) |
 | **Scaling** | Redis Pub/Sub (ioredis -- single or Cluster) |
 
 #### Import Paths
+
+> [!IMPORTANT]
+> `WebSocketComponent` and `WebSocketBindingKeys` are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/websocket` subpath.
+
 ```typescript
-// From core -- component + binding keys only
+// From core -- subpath import (NOT from '@venizia/ignis')
 import {
   WebSocketComponent,
   WebSocketBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/websocket';
 
-// From helpers -- types, helpers, constants
+// From helpers -- types, helpers, constants (exported from main entry)
 import {
   WebSocketServerHelper,
   WebSocketEmitter,
@@ -53,7 +57,7 @@ import type {
 ```
 
 > [!NOTE]
-> `IServerOptions` (the core component's subset type) is **not** exported from `@venizia/ignis`. Only `WebSocketBindingKeys` and `WebSocketComponent` are exported from the core package. All helper types, constants, and classes are imported from `@venizia/ignis-helpers`.
+> `IServerOptions` (the core component's subset type) is **not** exported from `@venizia/ignis` or `@venizia/ignis/websocket`. Only `WebSocketBindingKeys` and `WebSocketComponent` are exported from the core subpath. All helper types, constants, and classes are imported from `@venizia/ignis-helpers`.
 
 ### Use Cases
 
@@ -82,11 +86,11 @@ In your application's `preConfigure()` method, bind the required services and re
 
 #### Full Setup Example
 ```typescript
+import { BaseApplication } from '@venizia/ignis';
 import {
-  BaseApplication,
   WebSocketComponent,
   WebSocketBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/websocket';
 import {
   RedisHelper,
 } from '@venizia/ignis-helpers';
@@ -98,7 +102,6 @@ import type {
   TWebSocketMessageHandler,
   TWebSocketOutboundTransformer,
   TWebSocketHandshakeFn,
-  IWebSocketServerOptions,
   IBunWebSocketConfig,
   ValueOrPromise,
 } from '@venizia/ignis-helpers';
@@ -204,7 +207,7 @@ export class Application extends BaseApplication {
     }).toValue(handshakeFn);
 
     // 9. Server options (optional -- customize defaults)
-    this.bind<Partial<IWebSocketServerOptions>>({
+    this.bind({
       key: WebSocketBindingKeys.SERVER_OPTIONS,
     }).toValue({
       identifier: 'my-app-websocket',
@@ -240,11 +243,14 @@ The core component's `IServerOptions` interface controls the WebSocket server se
 }
 ```
 
+> [!NOTE]
+> The `DEFAULT_SERVER_OPTIONS` in the core component only sets `identifier` and `path`. The remaining defaults (`defaultRooms`, `heartbeatInterval`, `heartbeatTimeout`, `serverOptions`) come from `WebSocketDefaults` applied by the helper constructor.
+
 To customize options, bind a partial options object before registering the component:
 
 #### Custom Server Options Example
 ```typescript
-import { WebSocketBindingKeys } from '@venizia/ignis';
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
 
 this.bind({
   key: WebSocketBindingKeys.SERVER_OPTIONS,
@@ -448,6 +454,6 @@ Called during authentication when `requireEncryption` is `true`. Receives the sa
 - [Usage & Examples](./usage) - Server-side usage, emitter, wire protocol, client tracking, and delivery strategy
 - [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
 - [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference

package/wiki/{references → extensions}/components/websocket/usage.md

@@ -10,10 +10,10 @@ Inject `WebSocketServerHelper` to interact with WebSocket:
 import {
   BaseService,
   inject,
-  WebSocketBindingKeys,
   CoreBindings,
   BaseApplication,
 } from '@venizia/ignis';
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
 import { WebSocketServerHelper } from '@venizia/ignis-helpers';
 
 export class NotificationService extends BaseService {
@@ -470,6 +470,6 @@ The helper uses a dual delivery strategy depending on whether encryption is acti
 - [Setup & Configuration](./) - Quick reference, imports, setup steps, configuration, and binding keys
 - [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
 - [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference

package/wiki/{references → extensions}/helpers/crypto/index.md

@@ -531,7 +531,7 @@ const hashed = hash('text', {
 
 - **References:**
   - [Crypto Utility](/references/utilities/crypto) -- Pure crypto utilities
-  - [Authentication Component](/references/components/authentication/) -- JWT and password verification
+  - [Authentication Component](/extensions/components/authentication/) -- JWT and password verification
 
 - **Best Practices:**
   - [Security Guidelines](/best-practices/security-guidelines) -- Cryptographic best practices

package/wiki/{references → extensions}/helpers/env/index.md

@@ -9,14 +9,14 @@ Structured access to application environment variables with prefix filtering, ty
 | **Package** | `@venizia/ignis-helpers` |
 | **Classes** | `ApplicationEnvironment`, `Environment` |
 | **Extends** | `IApplicationEnvironment` (interface) |
-| **Singleton** | `applicationEnvironment` -- auto-initialized at module load |
+| **Singleton** | `applicationEnvironment` (alias `Envs`) -- auto-initialized at module load |
 | **Runtimes** | Both |
 
 #### Import Paths
 
 ```typescript
 // Singleton instance (recommended)
-import { applicationEnvironment } from '@venizia/ignis-helpers';
+import { applicationEnvironment, Envs } from '@venizia/ignis-helpers';
 
 // Classes
 import { ApplicationEnvironment, Environment } from '@venizia/ignis-helpers';
@@ -29,12 +29,15 @@ import type { IApplicationEnvironment } from '@venizia/ignis-helpers';
 
 ### Singleton (Recommended)
 
-A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`).
+A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`). An alias `Envs` is also exported for convenience.
 
 ```typescript
 import { applicationEnvironment } from '@venizia/ignis-helpers';
+// or
+import { Envs } from '@venizia/ignis-helpers';
 
 const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
+const jwtSecret2 = Envs.get<string>('APP_ENV_JWT_SECRET');
 ```
 
 > [!TIP]
@@ -68,13 +71,14 @@ The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` as
 
 ### Reading Variables
 
-Use `get<ReturnType>(key)` to retrieve a typed environment variable. Only keys matching the configured prefix are available.
+Use `get<ReturnType>(key, defaultValue?)` to retrieve a typed environment variable. Only keys matching the configured prefix are available. An optional `defaultValue` is returned when the key is not found.
 
 ```typescript
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 
 const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
 const serverPort = applicationEnvironment.get<string>('APP_ENV_SERVER_PORT');
+const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', 5000);
 ```
 
 > [!WARNING]
@@ -211,4 +215,4 @@ ALLOW_EMPTY_ENV_VALUE=true
 
 - **Other Helpers:**
   - [Helpers Index](../index) -- All available helpers
-  - [Logger](/references/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering
+  - [Logger](/extensions/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering

package/wiki/{references → extensions}/helpers/error/index.md

@@ -19,9 +19,6 @@ import { ErrorSchema } from '@venizia/ignis-helpers';
 import type { TError } from '@venizia/ignis-helpers';
 ```
 
-> [!NOTE]
-> `ApplicationError`, `getError`, `ErrorSchema`, and `TError` are also available from `@venizia/ignis-inversion`. Their types are re-exported through `@venizia/ignis` (via `export type *`), but for runtime usage, import directly from `@venizia/ignis-helpers` or `@venizia/ignis-inversion`.
-
 ## Creating an Instance
 
 `ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification.
@@ -226,7 +223,5 @@ throw getError({
 - [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](/references/helpers/) -- All available helpers
-- [Logger Helper](/references/helpers/logger/) -- Logging errors
-- [Error Handling Best Practices](/best-practices/error-handling) -- Patterns and anti-patterns
-- [Common Pitfalls](/best-practices/common-pitfalls) -- Frequent error handling mistakes
+- [Helpers Index](/extensions/helpers/) -- All available helpers
+- [Logger Helper](/extensions/helpers/logger/) -- Logging errors

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

@@ -14,7 +14,7 @@ Reusable classes and functions providing common functionality - designed for eas
 | [Inversion](./inversion/) | Dependency injection | DI container implementation |
 | [Logger](./logger/) | Logging | Winston-based, multiple transports, scopes |
 | [Network](./network/) | Network requests | HTTP, TCP, UDP helpers |
-| Kafka <Badge type="warning" text="Experimental" /> | Event streaming | Apache Kafka producer/consumer |
+| [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 |
@@ -24,15 +24,27 @@ Reusable classes and functions providing common functionality - designed for eas
 | [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/controllers) - Using helpers in controllers
+  - [Controllers](/guides/core-concepts/rest-controllers) - Using helpers in controllers
 
 - **References:**
   - [Utilities](/references/utilities/) - Pure utility functions
-  - [Components](/references/components/) - Framework components
-
-- **Best Practices:**
-  - [Code Style Standards](/best-practices/code-style-standards/) - Helper usage patterns
+  - [Components](/extensions/components/) - Framework components

package/wiki/{references → extensions}/helpers/kafka/admin.md

@@ -7,7 +7,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
 
@@ -63,6 +63,18 @@ await helper.close();
 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'`.
+
+```typescript
+// Graceful (recommended)
+await helper.close();
+
+// Force
+await helper.close({ isForce: true });
+```
+
 ## API Reference (`@platformatic/kafka`)
 
 After calling `helper.getAdmin()`, you have full access to the `Admin` class.

package/wiki/{references → extensions}/helpers/kafka/consumer.md

@@ -21,9 +21,10 @@ class KafkaConsumerHelper<
 | `start(opts)` | `(opts: IKafkaConsumeStartOptions): Promise<void>` | Start consuming (creates stream, wires callbacks) |
 | `startLagMonitoring(opts)` | `(opts: { topics: string[]; interval?: number }): void` | Start periodic lag monitoring |
 | `stopLagMonitoring()` | `(): void` | Stop lag monitoring |
-| `isHealthy()` | `(): boolean` | `true` when broker connected |
+| `isHealthy()` | `(): boolean` | `true` when at least one broker connected |
 | `isReady()` | `(): boolean` | `isHealthy()` **and** `consumer.isActive()` |
 | `getHealthStatus()` | `(): TKafkaHealthStatus` | `'connected'` \| `'disconnected'` \| `'unknown'` |
+| `getConnectedBrokerCount()` | `(): number` | Number of currently connected brokers |
 | `close(opts?)` | `(opts?: { isForce?: boolean }): Promise<void>` | Stop lag, close stream, close consumer |
 
 ## IKafkaConsumerOptions
@@ -37,22 +38,22 @@ interface IKafkaConsumerOptions<KeyType, ValueType, HeaderKeyType, HeaderValueTy
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `groupId` | `string` | — | Consumer group ID. **Required** |
+| `groupId` | `string` | -- | Consumer group ID. **Required** |
 | `identifier` | `string` | `'kafka-consumer'` | Scoped logging identifier |
-| `deserializers` | `Partial<Deserializers<K,V,HK,HV>>` | — | Key/value/header deserializers |
+| `deserializers` | `Partial<Deserializers<K,V,HK,HV>>` | -- | Key/value/header deserializers |
 | `autocommit` | `boolean \| number` | `false` | Auto-commit offsets. `true` = default interval, `number` = custom ms |
-| `sessionTimeout` | `number` | `30000` | Session timeout — consumer removed from group if no heartbeat |
-| `heartbeatInterval` | `number` | `3000` | Heartbeat interval — must be less than `sessionTimeout` |
-| `rebalanceTimeout` | `number` | `sessionTimeout` | Max time for rebalance |
+| `sessionTimeout` | `number` | `60000` | Session timeout -- consumer removed from group if no heartbeat |
+| `heartbeatInterval` | `number` | `10000` | Heartbeat interval -- must be less than `sessionTimeout` |
+| `rebalanceTimeout` | `number` | `sessionTimeout` | Max time for rebalance. Defaults to the value of `sessionTimeout` |
 | `highWaterMark` | `number` | `1024` | Stream buffer size (messages) |
 | `minBytes` | `number` | `1` | Min bytes per fetch response |
-| `maxBytes` | `number` | — | Max bytes per fetch response per partition |
-| `maxWaitTime` | `number` | — | Max time (ms) broker waits for `minBytes` |
+| `maxBytes` | `number` | -- | Max bytes per fetch response per partition |
+| `maxWaitTime` | `number` | -- | Max time (ms) broker waits for `minBytes` |
 | `metadataMaxAge` | `number` | `300000` | Metadata cache TTL (ms) |
 | `groupProtocol` | `'classic' \| 'consumer'` | `'classic'` | Consumer group protocol. `'consumer'` = KIP-848 (Kafka 3.7+) |
-| `groupInstanceId` | `string` | — | Static group membership ID — prevents rebalance on restart |
+| `groupInstanceId` | `string` | -- | Static group membership ID -- prevents rebalance on restart |
 | `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in ms |
-| `registry` | `SchemaRegistry` | — | Schema registry for auto deser |
+| `registry` | `SchemaRegistry` | -- | Schema registry for auto deser |
 
 ### Lifecycle Callbacks
 
@@ -101,7 +102,7 @@ const helper = KafkaConsumerHelper.newInstance({
 
   // Message lifecycle
   onMessage: async ({ message }) => {
-    console.log(`${message.topic}[${message.partition}] @${message.offset}: ${message.key} → ${message.value}`);
+    console.log(`${message.topic}[${message.partition}] @${message.offset}: ${message.key} -> ${message.value}`);
     await message.commit();
   },
   onMessageDone: ({ message }) => {
@@ -141,8 +142,8 @@ await helper.start({ topics: ['orders'] });
 helper.startLagMonitoring({ topics: ['orders'], interval: 10_000 });
 
 // Health check
-helper.isHealthy(); // true when broker connected
-helper.isReady();   // true when broker connected AND consumer is active
+helper.isHealthy(); // true when at least one broker connected
+helper.isReady();   // true when at least one broker connected AND consumer is active
 
 // Shutdown
 await helper.close();
@@ -154,18 +155,18 @@ When `start()` is called, the helper creates a `MessagesStream` and wires the ca
 
 ```
 Stream 'data' event
-  → onMessage({ message })
-    ├── success → onMessageDone({ message })
-    └── error   → onMessageError({ error, message })
+  -> onMessage({ message })
+    +-- success -> onMessageDone({ message })
+    +-- error   -> onMessageError({ error, message })
 
 Stream 'error' event
-  → onMessageError({ error })  (no message available)
+  -> onMessageError({ error })  (no message available)
 ```
 
-- `onMessage` is the main processing callback — do your business logic here
-- `onMessageDone` fires only after `onMessage` resolves successfully — use for logging, metrics, etc.
-- `onMessageError` fires if `onMessage` OR `onMessageDone` throws — use for error tracking
-- The stream `'error'` event also calls `onMessageError` (without `message` since it's a stream-level error)
+- `onMessage` is the main processing callback -- do your business logic here
+- `onMessageDone` fires only after `onMessage` resolves successfully -- use for logging, metrics, etc.
+- `onMessageError` fires if `onMessage` throws -- use for error tracking. Note that errors from `onMessageDone` also trigger `onMessageError`
+- The stream `'error'` event also calls `onMessageError` (without `message` since it's a stream-level error), but only if `onMessageError` was provided
 
 ## start()
 
@@ -188,8 +189,8 @@ interface IKafkaConsumeStartOptions {
 
 | Fallback | Description |
 |----------|-------------|
-| `'latest'` | Start from latest (default) — ignore historical messages |
-| `'earliest'` | Start from beginning — process all historical messages |
+| `'latest'` | Start from latest (default) -- ignore historical messages |
+| `'earliest'` | Start from beginning -- process all historical messages |
 | `'fail'` | Throw an error |
 
 ```typescript
@@ -207,7 +208,7 @@ await helper.start({
 });
 ```
 
-Guards against duplicate starts — calling `start()` twice logs a warning and returns immediately.
+Guards against duplicate starts -- calling `start()` twice logs a warning and returns immediately.
 
 ## Lag Monitoring
 
@@ -221,7 +222,7 @@ helper.stopLagMonitoring();
 
 Lag data is delivered via the `onLag` callback. Errors via `onLagError`.
 
-Guards against duplicate starts — calling `startLagMonitoring()` twice logs a warning.
+Guards against duplicate starts -- calling `startLagMonitoring()` twice logs a warning.
 
 For one-time lag checks, use the underlying consumer directly:
 
@@ -234,8 +235,8 @@ const lag = await helper.getConsumer().getLag({ topics: ['orders'] });
 `close()` implements an ordered shutdown:
 
 1. Stop lag monitoring
-2. Close the stream (leave consumer group)
-3. Close the consumer client (graceful with timeout, or force)
+2. Close the stream (calls `stream.close()` callback-style)
+3. Close the consumer client (calls `client.close(true)` with graceful timeout, or force)
 4. Set health status to `'disconnected'`
 
 ```typescript
@@ -356,7 +357,7 @@ consumer.generationId;   // number
 consumer.assignments;    // GroupAssignment[] | null
 consumer.isActive();     // boolean
 
-// Static membership — prevents rebalance on restart
+// Static membership -- prevents rebalance on restart
 const helper = KafkaConsumerHelper.newInstance({
   ...
   groupInstanceId: 'worker-1',
@@ -370,9 +371,9 @@ When multiple consumers share the same `groupId`, Kafka distributes topic partit
 
 ```
 Topic "orders" (3 partitions)
-├── Partition 0 → Consumer A
-├── Partition 1 → Consumer B
-└── Partition 2 → Consumer C
++-- Partition 0 -> Consumer A
++-- Partition 1 -> Consumer B
++-- Partition 2 -> Consumer C
 ```
 
 - Each partition is assigned to **exactly one** consumer in the group

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

@@ -58,7 +58,7 @@ const helper = KafkaConsumerHelper.newInstance({
 
   onMessage: async ({ message }) => {
     const data = JSON.parse(message.value!);
-    console.log(`Processing: ${message.key} → ${JSON.stringify(data)}`);
+    console.log(`Processing: ${message.key} -> ${JSON.stringify(data)}`);
     await message.commit();
   },
   onMessageDone: ({ message }) => {
@@ -119,7 +119,7 @@ const stream = await consumer.consume({
 });
 
 for await (const message of stream) {
-  console.log(`${message.topic}[${message.partition}] @${message.offset}: ${message.key} → ${message.value}`);
+  console.log(`${message.topic}[${message.partition}] @${message.offset}: ${message.key} -> ${message.value}`);
   await message.commit();
 }
 
@@ -268,7 +268,7 @@ app.bind('kafka.producer').to(
     bootstrapBrokers: ['localhost:9092'],
     clientId: 'order-service-producer',
     serializers: stringSerializers,
-    onBrokerConnect: ({ broker }) => console.log(`Producer → ${broker.host}`),
+    onBrokerConnect: ({ broker }) => console.log(`Producer -> ${broker.host}`),
   }),
 );
 
@@ -281,7 +281,7 @@ app.bind('kafka.consumer').to(
     onMessage: async ({ message }) => {
       // Handled by the service below
     },
-    onBrokerConnect: ({ broker }) => console.log(`Consumer → ${broker.host}`),
+    onBrokerConnect: ({ broker }) => console.log(`Consumer -> ${broker.host}`),
   }),
 );
 
@@ -313,13 +313,13 @@ export class OrderEventService {
 |-------|-------|-----|
 | `ECONNREFUSED localhost:9092` | Broker `advertised.listeners` set to `localhost` but connecting remotely | Set `KAFKA_ADVERTISED_LISTENERS` with the correct external host IP |
 | `Request timed out` | SASL handshake or broker unreachable | Add `connectTimeout: 30_000, requestTimeout: 30_000` |
-| `Connection closed` | Connecting without SASL to a SASL-required listener | Check `KAFKA_LISTENER_SECURITY_PROTOCOL_MAP` — use `SASL_PLAINTEXT` |
+| `Connection closed` | Connecting without SASL to a SASL-required listener | Check `KAFKA_LISTENER_SECURITY_PROTOCOL_MAP` -- use `SASL_PLAINTEXT` |
 | `Cannot find a suitable SASL mechanism` | Wrong mechanism (e.g., `PLAIN` when broker only supports `SCRAM-SHA-512`) | Check error message for supported mechanisms, match `mechanism` |
 | `Failed to deserialize a message` | Mismatch between serializer and deserializer | Ensure matching serde. For old data, use a new consumer group or recreate topic |
 | `JSON.stringify cannot serialize BigInt` | `message.offset` and `message.timestamp` are `bigint` | Use custom replacer: `(_k, v) => typeof v === 'bigint' ? v.toString() : v` |
 | Consumer idle (no messages) | More consumers than partitions | Ensure `numPartitions >= numConsumers` |
-| `isHealthy()` returns `false` | No broker connected yet, or connection lost | Check broker addresses, SASL config, network connectivity |
-| `isReady()` returns `false` (consumer) | Consumer not active — `start()` not called or stream closed | Call `await helper.start({ topics })` before checking readiness |
+| `isHealthy()` returns `false` | All brokers disconnected (a single idle disconnect won't trigger this) | Check broker addresses, SASL config, network connectivity. Use `getConnectedBrokerCount()` for details |
+| `isReady()` returns `false` (consumer) | Consumer not active -- `start()` not called or stream closed | Call `await helper.start({ topics })` before checking readiness |
 | Graceful shutdown timeout | In-flight requests taking too long | Increase `shutdownTimeout` or use `close({ isForce: true })` |
 
 ### Docker Kafka Configuration
@@ -338,24 +338,24 @@ environment:
     CONTROLLER:PLAINTEXT
 ```
 
-- `INTERNAL` — used for inter-broker communication
-- `EXTERNAL` — used for client connections from outside Docker
-- `CONTROLLER` — used for KRaft controller communication
+- `INTERNAL` -- used for inter-broker communication
+- `EXTERNAL` -- used for client connections from outside Docker
+- `CONTROLLER` -- used for KRaft controller communication
 
 ## See Also
 
 - **Kafka Pages:**
-  - [Overview & Fundamentals](./) — Connection, serialization, constants, compression
-  - [Producer](./producer) — Producer helper, transactions, API reference
-  - [Consumer](./consumer) — Consumer helper, callbacks, lag monitoring, API reference
-  - [Admin](./admin) — Admin helper & API reference
-  - [Schema Registry](./schema-registry) — Schema registry helper
+  - [Overview & Fundamentals](./) -- Connection, serialization, constants, compression
+  - [Producer](./producer) -- Producer helper, transactions, API reference
+  - [Consumer](./consumer) -- Consumer helper, callbacks, lag monitoring, API reference
+  - [Admin](./admin) -- Admin helper & API reference
+  - [Schema Registry](./schema-registry) -- Schema registry helper
 
 - **Other Helpers:**
-  - [Queue Helper](../queue/) — BullMQ, MQTT, and in-memory queues
-  - [Redis Helper](../redis/) — Redis connection management
+  - [Queue Helper](../queue/) -- BullMQ, MQTT, and in-memory queues
+  - [Redis Helper](../redis/) -- Redis connection management
 
 - **External Resources:**
-  - [@platformatic/kafka](https://github.com/platformatic/kafka) — Underlying Kafka client library
-  - [Apache Kafka Documentation](https://kafka.apache.org/documentation/) — Official Kafka docs
-  - [KIP-848](https://cwiki.apache.org/confluence/display/KAFKA/KIP-848) — New consumer group protocol
+  - [@platformatic/kafka](https://github.com/platformatic/kafka) -- Underlying Kafka client library
+  - [Apache Kafka Documentation](https://kafka.apache.org/documentation/) -- Official Kafka docs
+  - [KIP-848](https://cwiki.apache.org/confluence/display/KAFKA/KIP-848) -- New consumer group protocol