@venizia/ignis-docs 0.0.7 → 0.0.8-1

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

@@ -1,6 +1,6 @@
 # Kafka
 
-Apache Kafka event streaming with producer, consumer, admin, and schema registry helpers. Built on [`@platformatic/kafka`](https://github.com/platformatic/kafka) v1.30.0 — a pure TypeScript Kafka client with zero native dependencies.
+Apache Kafka event streaming with producer, consumer, admin, and schema registry helpers. Built on [`@platformatic/kafka`](https://github.com/platformatic/kafka) v1.30.0 -- a pure TypeScript Kafka client with zero native dependencies.
 
 ## Overview
 
@@ -16,9 +16,10 @@ The Kafka module provides four helper classes built on a shared `BaseKafkaHelper
 All helpers (except schema registry) extend `BaseKafkaHelper` which provides:
 
 - **Scoped logging** via `BaseHelper` (Winston with daily rotation)
-- **Health tracking** — `isHealthy()`, `isReady()`, `getHealthStatus()`
-- **Broker event callbacks** — `onBrokerConnect`, `onBrokerDisconnect`
-- **Graceful shutdown** — timeout-based with force fallback
+- **Health tracking** -- per-broker connection tracking via `isHealthy()`, `isReady()`, `getHealthStatus()`, `getConnectedBrokerCount()`
+- **Broker event callbacks** -- `onBrokerConnect`, `onBrokerDisconnect`
+- **Broker failure tracking** -- automatic `configureBrokerFailed()` sets status to `'disconnected'` only when all brokers are gone
+- **Graceful shutdown** -- timeout-based with force fallback
 - **Sensible defaults** via `KafkaDefaults` constants
 - **Factory pattern** via `newInstance()` static method
 
@@ -27,7 +28,7 @@ Use `getProducer()`, `getConsumer()`, or `getAdmin()` to access the full underly
 ### Import Path
 
 ```typescript
-// Helpers & constants
+// Helpers & constants (via subpath export)
 import {
   KafkaProducerHelper,
   KafkaConsumerHelper,
@@ -84,6 +85,9 @@ import type {
 } from '@platformatic/kafka';
 ```
 
+> [!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.
+
 ### Installation
 
 ```bash
@@ -96,13 +100,12 @@ bun add @platformatic/kafka
 
 ```
 BaseHelper (scoped logging, identifier)
-  └── BaseKafkaHelper<TClient> (health tracking, broker events, graceful shutdown)
-        ├── KafkaProducerHelper<K,V,HK,HV>
-        ├── KafkaConsumerHelper<K,V,HK,HV>
-        └── KafkaAdminHelper
-
-BaseHelper
-  └── KafkaSchemaRegistryHelper<K,V,HK,HV>  (no broker connection)
+  +-- BaseKafkaHelper<TClient> (health tracking, broker events, graceful shutdown)
+  |     +-- KafkaProducerHelper<K,V,HK,HV>
+  |     +-- KafkaConsumerHelper<K,V,HK,HV>
+  |     +-- KafkaAdminHelper
+  |
+  +-- KafkaSchemaRegistryHelper<K,V,HK,HV>  (no broker connection)
 ```
 
 ### BaseKafkaHelper
@@ -112,21 +115,25 @@ All Kafka helpers (except schema registry) extend `BaseKafkaHelper<TClient>`, wh
 ```typescript
 abstract class BaseKafkaHelper<TClient extends Base<BaseOptions>> extends BaseHelper {
   // Health
-  isHealthy(): boolean;          // healthStatus === 'connected'
-  isReady(): boolean;            // healthStatus === 'connected' (consumer overrides: + isActive())
-  getHealthStatus(): TKafkaHealthStatus; // 'connected' | 'disconnected' | 'unknown'
+  isHealthy(): boolean;              // true when at least one broker is connected
+  isReady(): boolean;                // healthStatus === 'connected' (consumer overrides: + isActive())
+  getHealthStatus(): TKafkaHealthStatus;  // 'connected' | 'disconnected' | 'unknown'
+  getConnectedBrokerCount(): number; // number of currently connected brokers
 
   // Shutdown (used by subclasses)
   protected closeClient(): Promise<void>;
   protected gracefulCloseClient(): Promise<void>; // races closeClient vs shutdownTimeout
+  protected resetHealthState(): void;             // clears broker tracking + sets 'disconnected'
 }
 ```
 
+Health tracking uses a **per-broker connection set** (`host:port` keys). A single idle broker disconnect does not make the client unhealthy -- only when **all** brokers are disconnected does `isHealthy()` return `false`.
+
 Health status transitions automatically via broker events:
-- `client:broker:connect` → `'connected'`
-- `client:broker:disconnect` → `'disconnected'`
-- `client:broker:failed` → `'disconnected'`
-- `close()` → `'disconnected'`
+- `client:broker:connect` -> adds broker, sets `healthStatus` to `'connected'`
+- `client:broker:disconnect` -> removes broker, sets `healthStatus` to `'disconnected'` only when all brokers are gone
+- `client:broker:failed` -> removes broker, sets `healthStatus` to `'disconnected'` only when all brokers are gone
+- `close()` -> clears all brokers, sets `healthStatus` to `'disconnected'`
 
 ## Connection Options
 
@@ -145,15 +152,15 @@ interface IKafkaConnectionOptions extends ConnectionOptions {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `bootstrapBrokers` | `string[]` | — | Kafka broker addresses (`host:port`). **Required** |
-| `clientId` | `string` | — | Unique client identifier. **Required** |
+| `bootstrapBrokers` | `string[]` | -- | Kafka broker addresses (`host:port`). **Required** |
+| `clientId` | `string` | -- | Unique client identifier. **Required** |
 | `retries` | `number` | `3` | Number of connection retries before failing |
 | `retryDelay` | `number` | `1000` | Delay between retries in milliseconds |
-| `sasl` | `SASLOptions` | — | SASL authentication configuration |
-| `tls` | `TLSConnectionOptions` | — | TLS/SSL connection options |
-| `ssl` | `TLSConnectionOptions` | — | Alias for `tls` |
-| `connectTimeout` | `number` | — | TCP connection timeout in milliseconds |
-| `requestTimeout` | `number` | — | Kafka request timeout in milliseconds |
+| `sasl` | `SASLOptions` | -- | SASL authentication configuration |
+| `tls` | `TLSConnectionOptions` | -- | TLS/SSL connection options |
+| `ssl` | `TLSConnectionOptions` | -- | Alias for `tls` |
+| `connectTimeout` | `number` | -- | TCP connection timeout in milliseconds |
+| `requestTimeout` | `number` | -- | Kafka request timeout in milliseconds |
 
 ### Shared Helper Options
 
@@ -163,8 +170,8 @@ These options are available on all three helpers (`IKafkaProducerOptions`, `IKaf
 |--------|------|---------|-------------|
 | `identifier` | `string` | `'kafka-{type}'` | Scoped logging identifier |
 | `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in ms |
-| `onBrokerConnect` | `TKafkaBrokerEventCallback` | — | Called when broker connects |
-| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | — | Called when broker disconnects |
+| `onBrokerConnect` | `TKafkaBrokerEventCallback` | -- | Called when broker connects |
+| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | -- | Called when broker disconnects |
 
 ### SASL Authentication
 
@@ -247,10 +254,10 @@ const helper = KafkaProducerHelper.newInstance({
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `stringSerializer` | `Serializer<string>` | `string → Buffer` (UTF-8) |
-| `stringDeserializer` | `Deserializer<string>` | `Buffer → string` (UTF-8) |
-| `jsonSerializer` | `Serializer<T>` | `object → Buffer` (JSON.stringify + UTF-8) |
-| `jsonDeserializer` | `Deserializer<T>` | `Buffer → object` (UTF-8 + JSON.parse) |
+| `stringSerializer` | `Serializer<string>` | `string -> Buffer` (UTF-8) |
+| `stringDeserializer` | `Deserializer<string>` | `Buffer -> string` (UTF-8) |
+| `jsonSerializer` | `Serializer<T>` | `object -> Buffer` (JSON.stringify + UTF-8) |
+| `jsonDeserializer` | `Deserializer<T>` | `Buffer -> object` (UTF-8 + JSON.parse) |
 | `stringSerializers` | `Serializers<string, string, string, string>` | All four positions as string |
 | `stringDeserializers` | `Deserializers<string, string, string, string>` | All four positions as string |
 
@@ -397,8 +404,8 @@ import { KafkaDefaults } from '@venizia/ignis-helpers/kafka';
 | `STRICT` | `true` | Producer | Fail on unknown topics |
 | `AUTOCREATE_TOPICS` | `false` | Producer | Auto-create topics on produce |
 | `AUTOCOMMIT` | `false` | Consumer | Auto-commit offsets |
-| `SESSION_TIMEOUT` | `30000` | Consumer | Session timeout in ms |
-| `HEARTBEAT_INTERVAL` | `3000` | Consumer | Heartbeat interval in ms |
+| `SESSION_TIMEOUT` | `60000` | Consumer | Session timeout in ms |
+| `HEARTBEAT_INTERVAL` | `10000` | Consumer | Heartbeat interval in ms |
 | `HIGH_WATER_MARK` | `1024` | Consumer | Stream buffer size (messages) |
 | `MIN_BYTES` | `1` | Consumer | Min bytes per fetch |
 | `METADATA_MAX_AGE` | `300000` | Consumer | Metadata cache TTL in ms |
@@ -453,7 +460,7 @@ import { KafkaAcks } from '@venizia/ignis-helpers/kafka';
 
 | Constant | Value | Description | Trade-off |
 |----------|-------|-------------|-----------|
-| `NONE` | `0` | No acknowledgment — fire-and-forget | Fastest, no durability guarantee |
+| `NONE` | `0` | No acknowledgment -- fire-and-forget | Fastest, no durability guarantee |
 | `LEADER` | `1` | Leader broker acknowledges | Fast, leader-durable |
 | `ALL` | `-1` | All in-sync replicas acknowledge | Slowest, fully durable |
 
@@ -468,7 +475,7 @@ import { KafkaGroupProtocol } from '@venizia/ignis-helpers/kafka';
 | Constant | Value | Description |
 |----------|-------|-------------|
 | `CLASSIC` | `'classic'` | Classic consumer group protocol (default, all Kafka versions) |
-| `CONSUMER` | `'consumer'` | New consumer group protocol — KIP-848 (Kafka 3.7+) |
+| `CONSUMER` | `'consumer'` | New consumer group protocol -- KIP-848 (Kafka 3.7+) |
 
 ### Derived Types
 
@@ -558,16 +565,16 @@ const consumer = KafkaConsumerHelper.newInstance({
 | Admin | Producer | Consumer |
 |-------|----------|----------|
 | `admin.getAdmin()` | `producer.getProducer()` | `consumer.getConsumer()` |
-| — | `producer.getProducer().send(...)` | `await consumer.start({ topics: ['t1'] })` |
-| — | `await producer.runInTransaction(async ({ send, addConsumer, addOffset }) => { ... })` | `consumer.startLagMonitoring({ topics: ['t1'], interval: 10_000 })` |
-| — | — | `consumer.stopLagMonitoring()` |
-| — | — | `consumer.getStream()` |
+| -- | `producer.getProducer().send(...)` | `await consumer.start({ topics: ['t1'] })` |
+| -- | `await producer.runInTransaction(async ({ send, addConsumer, addOffset }) => { ... })` | `consumer.startLagMonitoring({ topics: ['t1'], interval: 10_000 })` |
+| -- | -- | `consumer.stopLagMonitoring()` |
+| -- | -- | `consumer.getStream()` |
 
 ### Health Checks
 
 ```typescript
-// All three — identical API
-helper.isHealthy();      // true when broker connected
+// All three -- identical API
+helper.isHealthy();      // true when at least one broker connected
 helper.isReady();        // Admin/Producer: same as isHealthy()
                          // Consumer: isHealthy() + consumer.isActive()
 helper.getHealthStatus(); // 'connected' | 'disconnected' | 'unknown'
@@ -576,8 +583,8 @@ helper.getHealthStatus(); // 'connected' | 'disconnected' | 'unknown'
 ### Shutdown
 
 ```typescript
-// All three — identical API
-await helper.close();                    // graceful (timeout → force fallback)
+// All three -- identical API
+await helper.close();                    // graceful (timeout -> force fallback)
 await helper.close({ isForce: true });   // immediate force close
 ```
 
@@ -618,19 +625,19 @@ const result = await producer.runInTransaction(async ({ send, addConsumer, addOf
 
 ## Pages
 
-- **[Producer](./producer)** — Producer helper, transactions, and full `@platformatic/kafka` Producer API reference
-- **[Consumer](./consumer)** — Consumer helper, message callbacks, lag monitoring, and full Consumer API reference
-- **[Admin](./admin)** — Admin helper and full Admin API reference
-- **[Schema Registry](./schema-registry)** — Schema registry helper for Avro/Protobuf/JSON Schema validation
-- **[Examples & Troubleshooting](./examples)** — Complete examples, IoC integration, and troubleshooting guide
+- **[Producer](./producer)** -- Producer helper, transactions, and full `@platformatic/kafka` Producer API reference
+- **[Consumer](./consumer)** -- Consumer helper, message callbacks, lag monitoring, and full Consumer API reference
+- **[Admin](./admin)** -- Admin helper and full Admin API reference
+- **[Schema Registry](./schema-registry)** -- Schema registry helper for Avro/Protobuf/JSON Schema validation
+- **[Examples & Troubleshooting](./examples)** -- Complete examples, IoC integration, and troubleshooting guide
 
 ## See Also
 
 - **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

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

@@ -18,9 +18,10 @@ class KafkaProducerHelper<
 | `newInstance(opts)` | `static newInstance<K,V,HK,HV>(opts): KafkaProducerHelper<K,V,HK,HV>` | Factory method |
 | `getProducer()` | `(): Producer<K,V,HK,HV>` | Access the underlying `Producer` |
 | `runInTransaction(cb)` | `<R>(cb: TKafkaTransactionCallback<R,K,V,HK,HV>): Promise<R>` | Execute callback within a Kafka transaction |
-| `isHealthy()` | `(): boolean` | `true` when broker connected |
+| `isHealthy()` | `(): boolean` | `true` when at least one 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 producer (default: graceful) |
 
 ## IKafkaProducerOptions
@@ -33,17 +34,17 @@ interface IKafkaProducerOptions<KeyType, ValueType, HeaderKeyType, HeaderValueTy
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `identifier` | `string` | `'kafka-producer'` | Scoped logging identifier |
-| `serializers` | `Partial<Serializers<K,V,HK,HV>>` | — | Key/value/header serializers |
-| `compression` | `CompressionAlgorithmValue` | — | `'none'`, `'gzip'`, `'snappy'`, `'lz4'`, `'zstd'` |
-| `acks` | `TKafkaAcks` | — | Acknowledgment level: `0`, `1`, or `-1` |
-| `idempotent` | `boolean` | — | Enable idempotent producer (exactly-once within partition) |
-| `transactionalId` | `string` | — | Transactional ID for exactly-once across partitions |
-| `strict` | `boolean` | `true` | Strict mode — fail on unknown topics |
+| `serializers` | `Partial<Serializers<K,V,HK,HV>>` | -- | Key/value/header serializers |
+| `compression` | `CompressionAlgorithmValue` | -- | `'none'`, `'gzip'`, `'snappy'`, `'lz4'`, `'zstd'` |
+| `acks` | `TKafkaAcks` | -- | Acknowledgment level: `0`, `1`, or `-1` |
+| `idempotent` | `boolean` | -- | Enable idempotent producer (exactly-once within partition) |
+| `transactionalId` | `string` | -- | Transactional ID for exactly-once across partitions |
+| `strict` | `boolean` | `true` | Strict mode -- fail on unknown topics |
 | `autocreateTopics` | `boolean` | `false` | Auto-create topics on first produce |
 | `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in ms |
-| `registry` | `SchemaRegistry` | — | Schema registry for auto ser/deser |
-| `onBrokerConnect` | `TKafkaBrokerEventCallback` | — | Called when broker connects |
-| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | — | Called when broker disconnects |
+| `registry` | `SchemaRegistry` | -- | Schema registry for auto ser/deser |
+| `onBrokerConnect` | `TKafkaBrokerEventCallback` | -- | Called when broker connects |
+| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | -- | Called when broker disconnects |
 
 Plus all [Connection Options](./#connection-options).
 
@@ -64,7 +65,7 @@ const helper = KafkaProducerHelper.newInstance({
 });
 
 // Health check
-helper.isHealthy();      // true when connected
+helper.isHealthy();      // true when at least one broker connected
 helper.getHealthStatus(); // 'connected' | 'disconnected' | 'unknown'
 
 // Send messages via the underlying producer
@@ -84,7 +85,7 @@ await producer.send({
   ],
 });
 
-// Graceful close (waits for in-flight, times out after shutdownTimeout → force)
+// Graceful close (waits for in-flight, times out after shutdownTimeout -> force)
 await helper.close();
 
 // Or force close immediately
@@ -93,7 +94,7 @@ await helper.close({ isForce: true });
 
 ## Transactions
 
-`runInTransaction()` wraps `beginTransaction()` → callback → `commit()` / `abort()` with automatic logging.
+`runInTransaction()` wraps `beginTransaction()` -> callback -> `commit()` / `abort()` with automatic logging.
 
 > [!NOTE]
 > Requires `transactionalId` and `idempotent: true` in producer options.
@@ -149,9 +150,11 @@ If the callback throws, the transaction is automatically aborted and the error r
 
 `close()` implements a two-phase shutdown:
 
-1. **Graceful** (default): Waits for in-flight requests to complete, with a timeout (`shutdownTimeout`, default 30s)
+1. **Graceful** (default): Calls `close(true)` on the underlying producer (force-flush), with a timeout (`shutdownTimeout`, default 30s)
 2. **Force fallback**: If graceful times out, automatically force-closes
-3. **Force** (`{ isForce: true }`): Immediately aborts all in-flight requests
+3. **Force** (`{ isForce: true }`): Immediately calls `close(true)` without timeout protection
+
+After `close()`, all broker tracking is cleared and `healthStatus` is set to `'disconnected'`.
 
 ```typescript
 // Graceful (recommended)
@@ -161,8 +164,6 @@ await helper.close();
 await helper.close({ isForce: true });
 ```
 
-After `close()`, `healthStatus` is set to `'disconnected'`.
-
 ## API Reference (`@platformatic/kafka`)
 
 After calling `helper.getProducer()`, you have full access to the `Producer` class:
@@ -258,9 +259,9 @@ Close the producer connection.
 
 By default, `@platformatic/kafka` uses **murmur2 hashing** on the message key to determine the target partition:
 
-- Same key → always same partition → guaranteed ordering per key
-- `undefined` key → round-robin across partitions
-- Explicit `partition` field → overrides the partitioner
+- Same key -> always same partition -> guaranteed ordering per key
+- `undefined` key -> round-robin across partitions
+- Explicit `partition` field -> overrides the partitioner
 
 ```typescript
 // Custom partitioner

package/wiki/{references → extensions}/helpers/kafka/schema-registry.md

@@ -12,7 +12,7 @@ class KafkaSchemaRegistryHelper<
 ```
 
 > [!NOTE]
-> `KafkaSchemaRegistryHelper` extends `BaseHelper` directly (not `BaseKafkaHelper`) — it has no broker connection or health tracking. It's a configuration wrapper, not a client.
+> `KafkaSchemaRegistryHelper` extends `BaseHelper` directly (not `BaseKafkaHelper`) -- it has no broker connection or health tracking. It's a configuration wrapper, not a client.
 
 ## Helper API
 
@@ -33,10 +33,10 @@ interface IKafkaSchemaRegistryOptions extends ConfluentSchemaRegistryOptions {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `url` | `string` | — | Schema registry URL. **Required** |
-| `auth` | `{ username: string; password: string }` | — | Basic auth credentials |
-| `protobufTypeMapper` | `ProtobufTypeMapper` | — | Custom Protobuf type mapper |
-| `jsonValidateSend` | `boolean` | — | Validate JSON schema on produce |
+| `url` | `string` | -- | Schema registry URL. **Required** |
+| `auth` | `{ username: string; password: string }` | -- | Basic auth credentials |
+| `protobufTypeMapper` | `ProtobufTypeMapper` | -- | Custom Protobuf type mapper |
+| `jsonValidateSend` | `boolean` | -- | Validate JSON schema on produce |
 | `identifier` | `string` | `'kafka-schema-registry'` | Scoped logging identifier |
 
 ## What Schema Registry Solves
@@ -46,14 +46,14 @@ Without a schema registry, producers and consumers must agree on message format
 **Schema Registry** is a centralized server (Confluent Schema Registry) that stores and validates schemas (Avro, Protobuf, JSON Schema). It enforces a contract:
 
 ```
-Producer → "I want to send this shape" → Schema Registry validates → Kafka
-Kafka → Consumer → "What shape is this?" → Schema Registry tells → Deserialize
+Producer -> "I want to send this shape" -> Schema Registry validates -> Kafka
+Kafka -> Consumer -> "What shape is this?" -> Schema Registry tells -> Deserialize
 ```
 
 ### Without Schema Registry (raw strings)
 
 ```typescript
-// Producer — manually serialize
+// Producer -- manually serialize
 const producer = KafkaProducerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-producer',
@@ -63,17 +63,17 @@ await producer.getProducer().send({
   messages: [{
     topic: 'orders',
     key: 'order-1',
-    value: JSON.stringify({ id: 1, total: 99.99 }),  // ← just a string, no validation
+    value: JSON.stringify({ id: 1, total: 99.99 }),  // <- just a string, no validation
   }],
 });
 
-// Consumer — manually deserialize, hope the shape is correct
+// Consumer -- manually deserialize, hope the shape is correct
 const consumer = KafkaConsumerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-consumer',
   groupId: 'order-group',
   onMessage: async ({ message }) => {
-    const order = JSON.parse(message.value as string);  // ← pray it matches
+    const order = JSON.parse(message.value as string);  // <- pray it matches
     console.log(order.id, order.total);
   },
 });
@@ -84,34 +84,34 @@ Problem: if producer adds `{ id: 1, total: 99.99, currency: 'USD' }` or removes
 ### With Schema Registry (auto serialize/deserialize)
 
 ```typescript
-// 1. Create registry — points to Confluent Schema Registry server
+// 1. Create registry -- points to Confluent Schema Registry server
 const registry = KafkaSchemaRegistryHelper.newInstance({
   url: 'http://localhost:8081',
   // auth: { username: 'user', password: 'pass' },  // optional
 });
 
-// 2. Producer — pass registry, it auto-serializes values using registered schema
+// 2. Producer -- pass registry, it auto-serializes values using registered schema
 const producer = KafkaProducerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-producer',
-  registry: registry.getRegistry(),  // ← registry handles serialization
+  registry: registry.getRegistry(),  // <- registry handles serialization
 });
 
 await producer.getProducer().send({
   messages: [{
     topic: 'orders',
     key: 'order-1',
-    value: { id: 1, total: 99.99 },  // ← object, not string! Registry serializes it
+    value: { id: 1, total: 99.99 },  // <- object, not string! Registry serializes it
   }],
 });
-// If the value doesn't match the registered schema → error BEFORE sending to Kafka
+// If the value doesn't match the registered schema -> error BEFORE sending to Kafka
 
-// 3. Consumer — pass same registry, it auto-deserializes
+// 3. Consumer -- pass same registry, it auto-deserializes
 const consumer = KafkaConsumerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-consumer',
   groupId: 'order-group',
-  registry: registry.getRegistry(),  // ← registry handles deserialization
+  registry: registry.getRegistry(),  // <- registry handles deserialization
   onMessage: async ({ message }) => {
     // message.value is already a typed object, not a raw string
     console.log(message.value.id, message.value.total);
@@ -124,7 +124,7 @@ const consumer = KafkaConsumerHelper.newInstance({
 | | Without Registry | With Registry |
 |---|---|---|
 | **Message format** | Raw string, manual `JSON.stringify/parse` | Typed object, auto ser/deser |
-| **Validation** | None — runtime crashes | Schema validated before send |
+| **Validation** | None -- runtime crashes | Schema validated before send |
 | **Schema evolution** | Break consumers silently | Backward/forward compatibility enforced |
 | **Where schemas live** | Nowhere (tribal knowledge) | Centralized server `http://registry:8081` |
 
@@ -135,12 +135,12 @@ You only need it when you want **schema enforcement** across producers/consumers
 ```typescript
 import { KafkaSchemaRegistryHelper, KafkaProducerHelper, KafkaConsumerHelper } from '@venizia/ignis-helpers/kafka';
 
-// 1. Create registry — points to Confluent Schema Registry server
+// 1. Create registry -- points to Confluent Schema Registry server
 const registry = KafkaSchemaRegistryHelper.newInstance({
   url: 'http://localhost:8081',
 });
 
-// 2. Producer — registry auto-serializes values using registered schema
+// 2. Producer -- registry auto-serializes values using registered schema
 const producer = KafkaProducerHelper.newInstance({
   bootstrapBrokers: ['localhost:9092'],
   clientId: 'order-producer',
@@ -151,12 +151,12 @@ await producer.getProducer().send({
   messages: [{
     topic: 'orders',
     key: 'order-1',
-    value: { id: 1, total: 99.99 },  // object, not string — registry serializes
+    value: { id: 1, total: 99.99 },  // object, not string -- registry serializes
   }],
 });
-// If value doesn't match the registered schema → error BEFORE sending to Kafka
+// If value doesn't match the registered schema -> error BEFORE sending to Kafka
 
-// 3. Consumer — registry auto-deserializes
+// 3. Consumer -- registry auto-deserializes
 const consumer = KafkaConsumerHelper.newInstance({
   bootstrapBrokers: ['localhost:9092'],
   clientId: 'order-consumer',
@@ -210,5 +210,5 @@ const consumer = KafkaConsumerHelper.newInstance({
 
 ## When to Use
 
-- **Use schema registry** when you need schema enforcement, validation, and compatibility checks across producers/consumers — especially in multi-team environments
+- **Use schema registry** when you need schema enforcement, validation, and compatibility checks across producers/consumers -- especially in multi-team environments
 - **Skip schema registry** for simple string/JSON messages where both sides are controlled by the same team and format changes are coordinated

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

@@ -587,13 +587,13 @@ APP_ENV_APPLICATION_NAME=my-service
 
 - **Related Concepts:**
   - [Services](/guides/core-concepts/services) -- Logging in services
-  - [Controllers](/guides/core-concepts/controllers) -- Logging in controllers
+  - [Controllers](/guides/core-concepts/rest-controllers) -- Logging in controllers
 
 - **Other Helpers:**
   - [Helpers Index](../index) -- All available helpers
 
 - **References:**
-  - [Request Tracker Component](/references/components/request-tracker) -- Request logging
+  - [Request Tracker Component](/extensions/components/request-tracker) -- Request logging
 
 - **External Resources:**
   - [Winston Documentation](https://github.com/winstonjs/winston) -- Winston logging library