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

package/content/extensions/helpers/kafka/compile-binary.md

@@ -1,45 +1,16 @@
 ---
 title: Kafka - Compiling to a Single Binary
-description: The platformaticWasmPlugin() Bun bundler plugin required when compiling an app that imports a Kafka helper
+description: The platformaticKafkaPlugins() Bun bundler plugins required when compiling an app that imports a Kafka helper
 difficulty: advanced
 ---
 
 # Compiling to a Single Binary
 
-This page covers `platformaticWasmPlugin()`, the Bun bundler plugin required when compiling an application that imports any Kafka helper into a standalone `bun build --compile` executable.
-
-## The problem
-
-- **A compiled binary crashes on startup** if the application imports any Kafka helper and the build did not register the plugin:
-
-  ```
-  ENOENT: no such file or directory, open '/$bunfs/dist/native.wasm'
-  ```
-
-- **The crash happens before your code runs.** It fires while the module graph is still loading - before the IGNIS application boots, so no log line, no lifecycle hook, and no error handler of yours ever executes.
-
-## Why it happens
-
-- **The codecs are WebAssembly, not native bindings.** `@platformatic/kafka` computes Kafka's CRC32C checksums and lz4/snappy compression in WebAssembly, through `@platformatic/wasm-utils`.
-- **The default entrypoint reads the wasm payload from disk** at module load time:
-
-  ```javascript
-  // @platformatic/wasm-utils/dist/index.js
-  const wasm = readFileSync(new URL('../dist/native.wasm', import.meta.url));
-  ```
-
-- **`bun build --compile` embeds JavaScript modules only.** Assets such as `native.wasm` are never carried into the executable. Inside the binary, `import.meta.url` resolves against the virtual `/$bunfs` filesystem, the file isn't there, and the read throws.
-- **Running from source is unaffected.** `bun run` / `bun .` keep `node_modules` on disk, so the read succeeds - the bug only exists in compiled binaries.
-
-## The fix
-
-- **A second entrypoint ships the payload inline.** `@platformatic/wasm-utils/bundled` exposes the same API with the wasm payload inlined as base64 - no filesystem read.
-- **`platformaticWasmPlugin()` swaps one entrypoint for the other** at bundle time, so the rest of your code and `@platformatic/kafka` itself need no changes.
-- **Compile through a Bun build script, not the CLI.** `bun build --compile` on the command line cannot register plugins:
+`platformaticKafkaPlugins()` returns every Bun bundler plugin `@platformatic/kafka` needs to survive `bun build --compile`. Register them whenever you compile an application that imports a Kafka helper. Skip them, and the binary crashes on its first run.
 
 ```typescript
 // scripts/compile.ts
-import { platformaticWasmPlugin } from '@venizia/ignis-helpers/kafka';
+import { platformaticKafkaPlugins } from '@venizia/ignis-helpers/kafka';
 
 const built = await Bun.build({
   entrypoints: ['./dist/index.js'],
@@ -50,7 +21,7 @@ const built = await Bun.build({
     target: process.env.BUN_TARGET ?? 'bun-linux-x64',
     outfile: './dist/bin',
   },
-  plugins: [platformaticWasmPlugin()],
+  plugins: platformaticKafkaPlugins(),
 });
 
 if (!built.success) {
@@ -59,6 +30,8 @@ if (!built.success) {
 }
 ```
 
+`bun build --compile` on the command line cannot register plugins. Compile through a build script instead:
+
 ```json
 {
   "scripts": {
@@ -67,32 +40,84 @@ if (!built.success) {
 }
 ```
 
-- **The plugin resolves relative to the importing module's own directory** (`Bun.resolveSync` from `dirname(args.importer)`), so it works with hoisted and isolated `node_modules` layouts alike, and pins no package version.
+## The two crashes
 
-## Verifying
+| Crash | Plugin that prevents it |
+|---|---|
+| `ENOENT: no such file or directory, open '/$bunfs/dist/native.wasm'` | `platformaticWasmPlugin()` |
+| `Cannot find package 'ajv-draft-04' from '/$bunfs/root/index.js'` | `platformaticRequirePlugin()` |
+
+Both fire while the module graph is still loading, before the IGNIS application boots. No log line, no lifecycle hook, and no error handler of yours ever runs.
+
+Running from source is unaffected. `bun run` and `bun .` keep `node_modules` on disk, so both reads succeed. The crashes exist only in compiled binaries.
+
+## Why the wasm read fails
 
-A correctly built binary contains no reference to the wasm file on disk:
+`@platformatic/kafka` computes Kafka's CRC32C checksums and lz4/snappy compression in WebAssembly, through `@platformatic/wasm-utils`. That package reads its payload from disk at module load:
+
+```javascript
+// @platformatic/wasm-utils/dist/index.js
+const wasm = readFileSync(new URL('../dist/native.wasm', import.meta.url));
+```
+
+`bun build --compile` embeds JavaScript modules only. Assets such as `native.wasm` never reach the executable, so `import.meta.url` resolves against the virtual `/$bunfs` filesystem and the read throws.
+
+`platformaticWasmPlugin()` redirects the import to `@platformatic/wasm-utils/bundled`, the same API with the payload inlined as base64.
+
+## Why the package lookup fails
+
+Since 2.8.0, `@platformatic/kafka` resolves two dependencies at module scope through `createRequire`:
+
+```javascript
+// @platformatic/kafka/dist/registries/confluent-schema-registry.js
+const require = createRequire(import.meta.url);
+const AjvDraft04 = require('ajv-draft-04');
+const draft06MetaSchema = require('ajv/dist/refs/json-schema-draft-06.json');
+```
+
+Three facts make that fatal in a binary:
+
+- **The bundler cannot see through `createRequire`.** Neither module is embedded, and the bare specifier survives verbatim into the binary.
+- **The module always loads.** `dist/index.js` re-exports the schema registry, so importing anything from the package runs those two lines. A schema registry you never use still crashes the binary.
+- **A compiled binary has no `node_modules`.** `import.meta.url` resolves against `/$bunfs` and the lookup fails.
+
+`platformaticRequirePlugin()` rewrites each module-scope `require()` into a static import at bundle time, so the bundler pulls the module into the binary.
+
+> [!WARNING]
+> Installing `ajv-draft-04` as a direct dependency does not fix this. The defect is the resolution mechanism, not a missing package, so the second line fails identically.
+
+## Verifying
 
 ```bash
-grep -c 'native.wasm' ./dist/bin   # 0 -- the payload is inlined
-./dist/bin                         # boots instead of throwing ENOENT
+./dist/bin                           # boots instead of crashing
+grep -ac 'native.wasm'  ./dist/bin   # 0 - the wasm payload is inlined
+grep -ac 'ajv-draft-04' ./dist/bin   # 0 - the package is bundled in
 ```
 
-The binary grows by roughly 76 KB, the base64 form of the 57 KB wasm module.
+The last count is meaningful only for a minified build. An unminified bundle keeps package paths in module comments.
+
+The binary grows by roughly 76 KB for the base64 wasm module, plus the size of the two hoisted packages.
 
 ## Notes
 
-- **Upgrading `@platformatic/kafka` does not remove the need for the plugin.** Every release to date imports the default `@platformatic/wasm-utils` entrypoint.
-- **Apps that never import a Kafka helper need no plugin.** Nothing pulls in `@platformatic/wasm-utils`, and the plugin's resolver never fires.
-- **Patching `node_modules` during the build achieves the same result**, but mutates a dependency in place, pins the store path to one version, and leaves the tree dirty when a build fails. The plugin needs neither.
+- **Register the pair, not the individual plugins.** `platformaticKafkaPlugins()` picks up any future addition without another edit to your compile script. `platformaticWasmPlugin()` and `platformaticRequirePlugin()` stay exported for a build that needs one alone.
+- **Upgrading `@platformatic/kafka` does not remove the need for the plugins.** Every release to date imports the default `@platformatic/wasm-utils` entrypoint, and 2.8.0 introduced the `createRequire` calls in a minor release.
+- **An unresolvable specifier now fails the build**, with Bun's own resolution error and `built.success === false`. That is the point of hoisting to a static import: you learn at build time instead of on the first run in production.
+- **Both plugins resolve relative to the importing module's own directory.** That works with hoisted and isolated `node_modules` layouts alike, and pins no package version.
+- **Apps that never import a Kafka helper need no plugins.** Nothing pulls in `@platformatic/wasm-utils` or the schema registry, and neither plugin ever fires.
+- **`platformaticRequirePlugin()` skips `protobufjs` and `@node-rs/crc32`.** Both are optional peers of `@platformatic/kafka`, and a static import would break builds that do not install them.
+- **Patching `node_modules` during the build achieves the same result, but at a cost.** It mutates a dependency in place, pins the store path to one version, and leaves the tree dirty when a build fails. The plugins need none of that.
 
 ## See also
 
-- [Kafka Overview](./) - the four helpers this plugin protects
+- [Kafka Overview](./) - the four helpers these plugins protect
 - [Producer](./producer) / [Consumer](./consumer) / [Admin](./admin) - any of these importing into a compiled binary triggers this caveat
+- [Schema Registry](./schema-registry) - the helper that wraps the module the second crash comes from
 - [Examples & Troubleshooting](./examples) - other Kafka connection and configuration errors
 
 **Files:**
 
+- [`packages/helpers/src/modules/queue/kafka/bundler/plugins.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/kafka/bundler/plugins.ts) - `platformaticKafkaPlugins`
 - [`packages/helpers/src/modules/queue/kafka/bundler/platformatic-wasm.plugin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/kafka/bundler/platformatic-wasm.plugin.ts) - `platformaticWasmPlugin`
-- [`packages/helpers/src/modules/queue/kafka/bundler/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/kafka/bundler/common/constants.ts) - `KafkaBundlerPluginNames`, `PlatformaticWasmSpecifiers`
+- [`packages/helpers/src/modules/queue/kafka/bundler/platformatic-require.plugin.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/kafka/bundler/platformatic-require.plugin.ts) - `platformaticRequirePlugin`
+- [`packages/helpers/src/modules/queue/kafka/bundler/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/queue/kafka/bundler/common/constants.ts) - `KafkaBundlerPluginNames`, `PlatformaticWasmSpecifiers`, `PlatformaticRequireSpecifiers`

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

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Consumer
 
-The `KafkaConsumerHelper` wraps `@platformatic/kafka`'s `Consumer` with health tracking, graceful shutdown, message callbacks, consumer group event callbacks, automatic reconnect, and lag monitoring.
+The `KafkaConsumerHelper` wraps `@platformatic/kafka`'s `Consumer` with health tracking, graceful shutdown, message callbacks, group callbacks, automatic reconnect, and lag monitoring.
 
 ```typescript
 class KafkaConsumerHelper<
@@ -46,12 +46,12 @@ Plus the shared [Connection & Authentication](./producer#connection--authenticat
 
 | 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` | `60000` | Session timeout -- consumer removed from group if no heartbeat |
-| `heartbeatInterval` | `number` | `10000` | Heartbeat interval -- must be less than `sessionTimeout` |
+| `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 |
@@ -59,9 +59,9 @@ Plus the shared [Connection & Authentication](./producer#connection--authenticat
 | `maxWaitTime` | `number` | `5000` | 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
 
@@ -169,14 +169,15 @@ Stream 'error' event
   -> onMessageError({ error })  (no message available)
 ```
 
-- **`onMessage` is the main processing callback** -- do your business logic here.
-- **`onMessageDone` fires only after `onMessage` resolves successfully** -- use it for logging, metrics, and similar side effects. Note that errors thrown from `onMessageDone` also trigger `onMessageError`.
-- **`onMessageError` fires if `onMessage` throws**, and also for the stream's own `'error'` event (without a `message`, since it's a stream-level error).
-- **The stream `'error'` listener is always attached**, whether or not you pass `onMessageError`. An `EventEmitter` `'error'` event with zero listeners is rethrown as an uncaught exception -- without this listener, a pull-style consumer (`start()` + `getStream()`, no `onMessage`) would take the whole process down on the first broker drop.
+- **`onMessage` is the main processing callback.** Put your business logic here.
+- **`onMessageDone` fires only after `onMessage` resolves successfully.** Use it for logging, metrics, and similar side effects. An error thrown from `onMessageDone` also triggers `onMessageError`.
+- **`onMessageError` fires if `onMessage` throws.** It also fires for the stream's own `'error'` event. That case carries no `message` - it's a stream-level error, not a per-message one.
+- **The stream `'error'` listener is always attached**, whether or not you pass `onMessageError`. An `EventEmitter` `'error'` event with zero listeners becomes an uncaught exception.
+- **Pull-style consumers benefit too.** Without this listener, a consumer using `start()` + `getStream()` with no `onMessage` would take down the whole process on the first broker drop.
 
 ## start()
 
-`start()` creates the consume stream and wires all message callbacks. It must be called explicitly after construction, and it guards against duplicate starts -- calling it twice logs a warning and returns immediately.
+`start()` creates the consume stream and wires all message callbacks. Call it explicitly after construction - the constructor never calls it for you. It also guards against duplicate starts: calling it twice logs a warning and returns immediately.
 
 ```typescript
 interface IKafkaConsumeStartOptions {
@@ -197,8 +198,8 @@ interface IKafkaConsumeStartOptions {
 
 | Fallback | Description |
 |----------|-------------|
-| `'latest'` (default) | Start from latest -- ignore historical messages |
-| `'earliest'` | Start from beginning -- process all historical messages |
+| `'latest'` (default) | Start from latest - ignore historical messages |
+| `'earliest'` | Start from beginning - process all historical messages |
 | `'fail'` | Throw an error |
 
 | Reconnect option | Default | Description |
@@ -227,11 +228,13 @@ await helper.start({
 
 When `onMessage` is provided, `start()` drives a background consume loop on top of the stream. That loop reconnects on its own:
 
-- **Only the callback-driven loop reconnects.** A pull-style consumer using `getStream()` or `consumer.consume()` directly owns its own retry logic -- the helper's automatic reconnect only runs inside `startConsumeLoop`, which is wired exclusively when `onMessage` is set.
-- **A full broker outage marks the session stale.** When every broker disconnects (`getConnectedBrokerCount()` drops to `0`, via `client:broker:disconnect` or `client:broker:failed`), the helper destroys the current stream immediately instead of waiting for it to error out on its own.
-- **Reconnect rebuilds the client after a stale session.** The next attempt, after `reconnectDelayMs`, constructs a brand-new `@platformatic/kafka` `Consumer` with the original constructor options and swaps it in -- a fresh client forces a clean group rejoin rather than reusing session state Kafka has likely already expired. Active lag monitoring is re-armed on the new client automatically.
+- **Only the callback-driven loop reconnects.** A pull-style consumer using `getStream()` or `consumer.consume()` directly owns its own retry logic. The helper's automatic reconnect runs only inside `startConsumeLoop`, which is wired exclusively when `onMessage` is set.
+- **A full broker outage marks the session stale.** This happens when every broker disconnects - `getConnectedBrokerCount()` drops to `0` via `client:broker:disconnect` or `client:broker:failed` events.
+- **The helper reacts immediately.** It destroys the current stream right away, instead of waiting for the stream to error out on its own.
+- **Reconnect rebuilds the client after a stale session.** The next attempt, after `reconnectDelayMs`, constructs a brand-new `@platformatic/kafka` `Consumer` with the original options and swaps it in.
+- **A fresh client forces a clean group rejoin**, instead of reusing session state Kafka has likely already expired. Lag monitoring re-arms automatically on the new client.
 - **Attempts are capped.** After `maxReconnectAttempts` consecutive failures, the consume loop exits and logs an error. Message processing stops until you call `start()` again with a new set of options.
-- **Every retry is logged**, including the attempt number, delay, and current connected-broker count, so a stuck reconnect loop is visible in application logs without extra instrumentation.
+- **Every retry is logged**: the attempt number, the delay, and the current connected-broker count. A stuck reconnect loop stays visible in application logs without extra instrumentation.
 
 ## Lag Monitoring
 
@@ -243,7 +246,7 @@ helper.startLagMonitoring({ topics: ['orders'], interval: 10_000 });
 helper.stopLagMonitoring();
 ```
 
-Lag data is delivered via the `onLag` callback. Errors via `onLagError`. `interval` defaults to `30000` ms. Guards against duplicate starts -- calling `startLagMonitoring()` twice logs a warning.
+Lag data arrives through the `onLag` callback; errors through `onLagError`. `interval` defaults to `30000` ms. Calling `startLagMonitoring()` twice logs a warning instead of starting a second poll loop.
 
 For one-time lag checks, use the underlying consumer directly:
 
@@ -378,7 +381,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',
@@ -410,7 +413,7 @@ Topic "orders" (3 partitions)
 - [Kafka Overview](./) - the four helpers, shared health/close API, and the compile-binary caveat
 - [Producer](./producer) - the sending side, plus the shared Connection & Authentication options
 - [Admin](./admin) - create topics and inspect consumer groups from outside the running consumer
-- [Examples & Troubleshooting](./examples) - lag monitoring, exactly-once, and common connection errors
+- [Examples & Troubleshooting](./examples) - IoC wiring and the common connection-error lookup table
 
 **Files:**
 

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

@@ -1,140 +1,17 @@
 ---
 title: Kafka Examples & Troubleshooting
-description: End-to-end producer, consumer, admin, and IoC examples, plus a common-error lookup table
+description: A multi-topic admin setup script, wiring Kafka helpers into IGNIS IoC, and a common-error lookup table
 difficulty: intermediate
 ---
 
 # Examples & Troubleshooting
 
-Complete examples and common issue resolution for the Kafka helpers.
-
-## Producer: Send Messages with Health Monitoring
-
-```typescript
-import { KafkaProducerHelper, KafkaAcks } from '@venizia/ignis-helpers/kafka';
-import { stringSerializers } from '@platformatic/kafka';
-
-const helper = KafkaProducerHelper.newInstance({
-  bootstrapBrokers: ['broker1:9092', 'broker2:9092'],
-  clientId: 'interval-producer',
-  serializers: stringSerializers,
-  acks: KafkaAcks.ALL,
-  onBrokerConnect: ({ broker }) => console.log(`Connected to ${broker.host}:${broker.port}`),
-  onBrokerDisconnect: ({ broker }) => console.warn(`Disconnected from ${broker.host}`),
-});
-
-const producer = helper.getProducer();
-let count = 0;
-
-const interval = setInterval(async () => {
-  if (!helper.isHealthy()) {
-    console.warn('Producer not healthy, skipping...');
-    return;
-  }
-
-  await producer.send({
-    messages: [{
-      topic: 'events',
-      key: `key-${count % 3}`,
-      value: JSON.stringify({ index: count, timestamp: new Date().toISOString() }),
-    }],
-  });
-  count++;
-}, 100);
-
-process.on('SIGINT', async () => {
-  clearInterval(interval);
-  console.log(`Shutting down... (sent ${count} messages)`);
-  await helper.close();
-  process.exit(0);
-});
-```
-
-## Consumer: Callback-Based with Lag Monitoring
-
-```typescript
-import { KafkaConsumerHelper } from '@venizia/ignis-helpers/kafka';
-import { stringDeserializers } from '@platformatic/kafka';
-
-const helper = KafkaConsumerHelper.newInstance({
-  bootstrapBrokers: ['broker1:9092', 'broker2:9092'],
-  clientId: 'event-consumer',
-  groupId: 'processing-group',
-  deserializers: stringDeserializers,
-
-  onMessage: async ({ message }) => {
-    const data = JSON.parse(message.value!);
-    console.log(`Processing: ${message.key} -> ${JSON.stringify(data)}`);
-    await message.commit();
-  },
-  onMessageDone: ({ message }) => {
-    console.log(`Done: ${message.key}`);
-  },
-  onMessageError: ({ error, message }) => {
-    console.error(`Error processing ${message?.key}:`, error.message);
-  },
-
-  onGroupJoin: ({ groupId, memberId }) => {
-    console.log(`Joined group ${groupId} as ${memberId}`);
-  },
-  onGroupRebalance: ({ groupId }) => {
-    console.log(`Rebalance in ${groupId}`);
-  },
-
-  onLag: ({ lag }) => {
-    for (const [topic, partitionLags] of lag) {
-      partitionLags.forEach((lagValue, partition) => {
-        if (lagValue > 1000n) {
-          console.warn(`High lag on ${topic}[${partition}]: ${lagValue}`);
-        }
-      });
-    }
-  },
-  onLagError: ({ error }) => console.error('Lag error:', error),
-});
-
-await helper.start({ topics: ['events'] });
-helper.startLagMonitoring({ topics: ['events'], interval: 10_000 });
-
-process.on('SIGINT', async () => {
-  await helper.close();
-  process.exit(0);
-});
-```
-
-## Consumer: Direct Stream Access (for-await)
-
-```typescript
-import { KafkaConsumerHelper } from '@venizia/ignis-helpers/kafka';
-import { stringDeserializers } from '@platformatic/kafka';
-
-const helper = KafkaConsumerHelper.newInstance({
-  bootstrapBrokers: ['localhost:9092'],
-  clientId: 'stream-consumer',
-  groupId: 'stream-group',
-  deserializers: stringDeserializers,
-  onBrokerConnect: ({ broker }) => console.log(`Connected to ${broker.host}`),
-});
-
-// Use the consumer directly for async iterator pattern
-const consumer = helper.getConsumer();
-const stream = await consumer.consume({
-  topics: ['orders'],
-  mode: 'committed',
-  fallbackMode: 'latest',
-});
-
-for await (const message of stream) {
-  console.log(`${message.topic}[${message.partition}] @${message.offset}: ${message.key} -> ${message.value}`);
-  await message.commit();
-}
-
-await stream.close();
-await helper.close();
-```
+Two examples not covered on the reference pages, plus a lookup table for the errors you'll actually hit.
 
 ## Admin: Topic Setup Script
 
+A deploy-time script that creates several topics with production configuration in one call. Run it once, from a `migrate` step or a CI job.
+
 ```typescript
 import { KafkaAdminHelper } from '@venizia/ignis-helpers/kafka';
 
@@ -147,7 +24,6 @@ async function setupTopics() {
 
   const admin = helper.getAdmin();
 
-  // Create topics
   await admin.createTopics({
     topics: ['orders', 'inventory', 'notifications'],
     partitions: 6,
@@ -158,11 +34,8 @@ async function setupTopics() {
     ],
   });
 
-  // Verify
   const topics = await admin.listTopics({ includeInternals: false });
   console.log('Topics:', topics);
-
-  // Health check
   console.log('Healthy:', helper.isHealthy());
 
   await helper.close();
@@ -171,99 +44,14 @@ async function setupTopics() {
 setupTopics();
 ```
 
-## Exactly-Once: Consume-Transform-Produce
-
-```typescript
-import { KafkaProducerHelper, KafkaConsumerHelper } from '@venizia/ignis-helpers/kafka';
-import { stringSerializers, stringDeserializers } from '@platformatic/kafka';
-
-const producer = KafkaProducerHelper.newInstance({
-  bootstrapBrokers: ['localhost:9092'],
-  clientId: 'eos-producer',
-  serializers: stringSerializers,
-  transactionalId: 'eos-tx',
-  idempotent: true,
-});
-
-const consumer = KafkaConsumerHelper.newInstance({
-  bootstrapBrokers: ['localhost:9092'],
-  clientId: 'eos-consumer',
-  groupId: 'eos-group',
-  deserializers: stringDeserializers,
-  autocommit: false,
-
-  onMessage: async ({ message }) => {
-    // Consume-transform-produce within a single transaction
-    const transformed = JSON.stringify({
-      ...JSON.parse(message.value!),
-      processedAt: new Date().toISOString(),
-    });
-
-    await producer.runInTransaction(async ({ send, addConsumer, addOffset }) => {
-      await addConsumer(consumer.getConsumer());
-      await addOffset(message);
-      await send({
-        messages: [{ topic: 'processed-events', key: message.key, value: transformed }],
-      });
-    });
-  },
-  onMessageError: ({ error }) => console.error('Processing error:', error),
-});
-
-await consumer.start({ topics: ['raw-events'] });
-```
-
-## Schema Registry: Validated Messages
-
-```typescript
-import {
-  KafkaSchemaRegistryHelper,
-  KafkaProducerHelper,
-  KafkaConsumerHelper,
-} from '@venizia/ignis-helpers/kafka';
-
-const registry = KafkaSchemaRegistryHelper.newInstance({
-  url: 'http://localhost:8081',
-});
-
-const producer = KafkaProducerHelper.newInstance({
-  bootstrapBrokers: ['localhost:9092'],
-  clientId: 'schema-producer',
-  registry: registry.getRegistry(),
-  onBrokerConnect: ({ broker }) => console.log(`Producer connected to ${broker.host}`),
-});
-
-// Sends schema-validated objects
-await producer.getProducer().send({
-  messages: [{
-    topic: 'orders',
-    key: 'order-1',
-    value: { id: 1, status: 'created', total: 99.99 },
-  }],
-});
-
-const consumer = KafkaConsumerHelper.newInstance({
-  bootstrapBrokers: ['localhost:9092'],
-  clientId: 'schema-consumer',
-  groupId: 'schema-group',
-  registry: registry.getRegistry(),
-  onMessage: async ({ message }) => {
-    // message.value is auto-deserialized to the schema type
-    console.log(message.value.id, message.value.status);
-    await message.commit();
-  },
-});
-
-await consumer.start({ topics: ['orders'] });
-```
-
 ## Using Helpers with IGNIS IoC
 
+Bind each helper once at boot. Inject it wherever you need to publish or consume - the same pattern IGNIS uses for every other connected resource.
+
 ```typescript
 import {
   KafkaProducerHelper,
   KafkaConsumerHelper,
-  KafkaAdminHelper,
 } from '@venizia/ignis-helpers/kafka';
 import { stringSerializers, stringDeserializers } from '@platformatic/kafka';
 import { inject } from '@venizia/ignis-inversion';
@@ -312,24 +100,22 @@ export class OrderEventService {
 
 ## Troubleshooting
 
-### Common Issues
-
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `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` |
-| `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` | 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 })` |
+| `ECONNREFUSED localhost:9092` | Broker `advertised.listeners` set to `localhost` but you're connecting remotely | Set `KAFKA_ADVERTISED_LISTENERS` to the correct external host IP |
+| `Request timed out` | SASL handshake stalled, or the broker is 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` |
+| `Cannot find a suitable SASL mechanism` | Wrong mechanism, e.g. `PLAIN` when the broker only supports `SCRAM-SHA-512` | Read the error for the supported mechanisms, match `mechanism` to one |
+| `Failed to deserialize a message` | Serializer and deserializer don't match | Match the serde on both sides. For old data, use a new consumer group or recreate the topic |
+| `JSON.stringify cannot serialize BigInt` | `message.offset` and `message.timestamp` are `bigint` | Use a custom replacer: `(_k, v) => typeof v === 'bigint' ? v.toString() : v` |
+| Consumer sits idle, no messages | More consumers than partitions | Make sure `numPartitions >= numConsumers` |
+| `isHealthy()` returns `false` | Every broker disconnected - one idle disconnect alone won't trigger this | Check broker addresses, SASL config, network. `getConnectedBrokerCount()` gives the exact count |
+| `isReady()` returns `false` (consumer) | Consumer isn't active - `start()` was never called, or the stream closed | Call `await helper.start({ topics })` before checking readiness |
+| Graceful shutdown times out | In-flight requests are taking too long | Raise `shutdownTimeout`, or call `close({ isForce: true })` |
 
 ### Docker Kafka Configuration
 
-When running Kafka in Docker and connecting from outside the container:
+Connecting from outside a Dockerized Kafka needs two listeners: one for containers talking to each other, one for the host.
 
 ```yaml
 environment:
@@ -343,9 +129,11 @@ environment:
     CONTROLLER:PLAINTEXT
 ```
 
-- `INTERNAL` -- used for inter-broker communication
-- `EXTERNAL` -- used for client connections from outside Docker
-- `CONTROLLER` -- used for KRaft controller communication
+| Listener | Used for |
+|---|---|
+| `INTERNAL` | Inter-broker communication |
+| `EXTERNAL` | Client connections from outside Docker |
+| `CONTROLLER` | KRaft controller communication |
 
 ## See also