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

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

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Kafka
 
-The Kafka helpers wrap `@platformatic/kafka` with four scoped classes - producer, consumer, admin, and schema registry - that add health tracking, graceful shutdown, and IGNIS-style scoped logging on top of the underlying client.
+IGNIS wraps `@platformatic/kafka` in four scoped helpers: producer, consumer, admin, and schema registry. Each adds health tracking, graceful shutdown, and IGNIS-style scoped logging over the raw client.
 
 ## In one example
 
@@ -29,75 +29,43 @@ await producer.getProducer().send({
 await producer.close();
 ```
 
-`getProducer()` returns the full `@platformatic/kafka` `Producer`. Every helper follows this same pattern: construct through `newInstance()`, reach the native client through `getProducer()` / `getConsumer()` / `getAdmin()`, close through the helper.
+`getProducer()` returns the full `@platformatic/kafka` `Producer`. Every helper follows the same three-step pattern:
 
-## How it works
-
-- **Four helpers, one job each.**
-
-  | Class | Wraps | Use case |
-  |---|---|---|
-  | `KafkaProducerHelper` | `Producer` | Publish messages, run transactions |
-  | `KafkaConsumerHelper` | `Consumer` | Consume via consumer groups, monitor lag |
-  | `KafkaAdminHelper` | `Admin` | Manage topics, partitions, groups, ACLs, configs |
-  | `KafkaSchemaRegistryHelper` | `ConfluentSchemaRegistry` | Schema-validated serialization (Avro/Protobuf/JSON Schema) |
-
-- **The three connected helpers share an identical health & close API**, regardless of which client they wrap:
-
-  ```typescript
-  const producer = KafkaProducerHelper.newInstance({ bootstrapBrokers, clientId });
-  const consumer = KafkaConsumerHelper.newInstance({ bootstrapBrokers, clientId, groupId });
-  const admin = KafkaAdminHelper.newInstance({ bootstrapBrokers, clientId });
-
-  producer.isHealthy();     // true once at least one broker is connected
-  consumer.isReady();       // true once connected AND consumer.isActive()
-  admin.getHealthStatus();  // 'connected' | 'disconnected' | 'unknown'
-
-  await Promise.all([producer.close(), consumer.close(), admin.close()]); // graceful, force fallback
-  ```
-
-  ```
-  BaseHelper (scoped logging, identifier)
-    +-- 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` is the shared base** for the three connected helpers (everything but the schema registry). It tracks per-broker connection state (`host:port` keys), so one idle disconnect never flips `isHealthy()` to `false` - only when every broker is gone. `isReady()`, `getHealthStatus()`, and `getConnectedBrokerCount()` read the same state, and `close({ isForce })` gives every connected helper the same two-phase graceful-then-force shutdown.
-- **Health status follows broker events automatically.** `client:broker:connect` marks a broker connected; `client:broker:disconnect` and `client:broker:failed` remove it and only flip the status to `'disconnected'` once every broker is gone; `close()` clears everything. You never set `healthStatus` yourself.
-- **`KafkaSchemaRegistryHelper` extends `BaseHelper` directly.** It opens no broker connection, so it has no health tracking - it's a configuration wrapper you hand to a producer or consumer via `registry`.
-- **Everything lives at the `/kafka` sub-path, never the root barrel.** `@platformatic/kafka` is an optional peer dependency (`^2.1.0` - `bun add @platformatic/kafka`); keeping it off the root barrel lets apps that never touch Kafka tree-shake it away entirely.
-- **Generics default to `string`.** All four classes accept `<KeyType, ValueType, HeaderKeyType, HeaderValueType>` generics. Without serializers/deserializers, messages travel as raw `Buffer`.
-- **`newInstance()` is the documented entry point.** Every class also exposes a public constructor, but `newInstance()` is what every example on these pages uses, and it carries the same generic inference: `KafkaProducerHelper.newInstance<string, MyEvent>({ ... })`.
-- **Compiling to a single binary needs one extra step.** `bun build --compile` crashes at startup with `ENOENT: native.wasm` unless the build registers `platformaticWasmPlugin()` - see [Compiling to a Single Binary](./compile-binary).
+| Step | Call |
+|---|---|
+| Construct | `newInstance()` |
+| Reach the native client | `getProducer()` / `getConsumer()` / `getAdmin()` |
+| Close | through the helper, not the native client |
 
-**Exported constants** (`@venizia/ignis-helpers/kafka`):
+## Which helper do I need
 
-| Constant | Exports | Purpose |
+| Class | Wraps | Use it to |
 |---|---|---|
-| `KafkaDefaults` | Timeouts, retry counts, buffer sizes | Every default value the helpers fall back to |
-| `KafkaAcks` | `NONE` (`0`) / `LEADER` (`1`) / `ALL` (`-1`) | Producer acknowledgment levels |
-| `KafkaGroupProtocol` | `CLASSIC` / `CONSUMER` | Consumer group protocol version |
-| `KafkaHealthStatuses` | `CONNECTED` / `DISCONNECTED` / `UNKNOWN` | `getHealthStatus()` return values |
-| `KafkaClientEvents` | Raw platformatic event names | Direct listening on `getProducer()` / `getConsumer()` / `getAdmin()` |
+| `KafkaProducerHelper` | `Producer` | Publish messages, run transactions |
+| `KafkaConsumerHelper` | `Consumer` | Consume via consumer groups, monitor lag |
+| `KafkaAdminHelper` | `Admin` | Manage topics, partitions, groups, ACLs, configs |
+| `KafkaSchemaRegistryHelper` | `ConfluentSchemaRegistry` | Schema-validated serialization (Avro/Protobuf/JSON Schema) |
+
+A few facts hold across all four:
 
-## Pages
+- **Producer, consumer, and admin share one health and close API.** `isHealthy()`, `isReady()`, `getHealthStatus()`, and `close({ isForce })` mean the same thing on every class. Each page documents the exact return values.
+- **Schema registry opens no broker connection.** It extends `BaseHelper` directly, not the shared connected-helper base. It has no health tracking - it's a configuration wrapper you hand to a producer or consumer via `registry`.
+- **Everything lives under `/kafka`, never the root barrel.** Install the optional peer yourself: `bun add @platformatic/kafka` (`^2.6.1`). An app that never touches Kafka tree-shakes it away entirely.
+- **Compiling to a single binary needs one extra build step.** Skip it, and the compiled app crashes at startup with `ENOENT: native.wasm` or `Cannot find package 'ajv-draft-04'` - see [Compiling to a Single Binary](./compile-binary).
+- **Defaults and enum-like values ship as exported constants**, not magic numbers - `KafkaDefaults`, `KafkaAcks`, `KafkaGroupProtocol`, `KafkaHealthStatuses`. Each page's options table names the constant it uses.
 
-Each class, and the one build-time gotcha, gets its own page:
+## Find what you need
 
-| Page | Covers |
+| You want to | Go to |
 |---|---|
-| [Producer](./producer) | `KafkaProducerHelper` - connection & SASL setup, serialization, compression, transactions, full `Producer` API |
-| [Consumer](./consumer) | `KafkaConsumerHelper` - message callbacks, automatic reconnect, lag monitoring, full `Consumer` API |
-| [Admin](./admin) | `KafkaAdminHelper` - topic, group, offset, ACL, and quota management |
-| [Schema Registry](./schema-registry) | `KafkaSchemaRegistryHelper` for Avro/Protobuf/JSON Schema validated messages |
-| [Compiling to a Single Binary](./compile-binary) | The `platformaticWasmPlugin()` fix for `bun build --compile` |
-| [Examples & Troubleshooting](./examples) | End-to-end examples, IoC wiring, common errors |
-
-Start with [Producer](./producer) or [Consumer](./consumer) if you're wiring up your first topic; start with [Compiling to a Single Binary](./compile-binary) if an existing app just started throwing `ENOENT: native.wasm` after a `bun build --compile`.
+| Publish messages, set up SASL/TLS, run transactions | [Producer](./producer) |
+| Consume messages, monitor lag, handle reconnects | [Consumer](./consumer) |
+| Create or delete topics, inspect consumer groups, manage ACLs | [Admin](./admin) |
+| Validate message shape with Avro, Protobuf, or JSON Schema | [Schema Registry](./schema-registry) |
+| See end-to-end examples or fix a connection error | [Examples & Troubleshooting](./examples) |
+| Ship an app that imports a Kafka helper as a single binary | [Compiling to a Single Binary](./compile-binary) |
+
+Start with [Producer](./producer) or [Consumer](./consumer) if you're wiring up your first topic. Start with [Compiling to a Single Binary](./compile-binary) if an existing app started crashing at startup after a `bun build --compile`.
 
 ## See also
 

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

@@ -40,17 +40,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` (none), `1` (leader), `-1` (all) |
-| `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` (none), `1` (leader), `-1` (all) |
+| `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 the shared [Connection & Authentication](#connection--authentication) options below, all inherited from `IKafkaConnectionOptions`.
 
@@ -60,14 +60,14 @@ Plus the shared [Connection & Authentication](#connection--authentication) optio
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `bootstrapBrokers` | `string[]` | -- | Broker addresses (`host:port`). **Required** |
-| `clientId` | `string` | -- | Unique client identifier. **Required** |
+| `bootstrapBrokers` | `string[]` | - | Broker addresses (`host:port`). **Required** |
+| `clientId` | `string` | - | Unique client identifier. **Required** |
 | `retries` | `number` | `3` | Connection retries before failing |
 | `retryDelay` | `number` | `1000` | Delay between retries (ms) |
-| `sasl` | `SASLOptions` | -- | SASL authentication |
-| `tls` / `ssl` | `TLSConnectionOptions` | -- | TLS options (`ssl` is an alias for `tls`) |
-| `connectTimeout` | `number` | -- | TCP connection timeout (ms) |
-| `requestTimeout` | `number` | -- | Kafka request timeout (ms) |
+| `sasl` | `SASLOptions` | - | SASL authentication |
+| `tls` / `ssl` | `TLSConnectionOptions` | - | TLS options (`ssl` is an alias for `tls`) |
+| `connectTimeout` | `number` | - | TCP connection timeout (ms) |
+| `requestTimeout` | `number` | - | Kafka request timeout (ms) |
 
 **SASL mechanisms** (`@platformatic/kafka` supports five):
 
@@ -75,7 +75,7 @@ Plus the shared [Connection & Authentication](#connection--authentication) optio
 |-----------|----------|
 | `PLAIN` | Username/password (pair with `tls` in production) |
 | `SCRAM-SHA-256` / `SCRAM-SHA-512` | Challenge-response - password never sent in plaintext |
-| `OAUTHBEARER` | Token-based (Azure Event Hubs, Confluent Cloud). `token` accepts a string or an async function returning one |
+| `OAUTHBEARER` | Token-based - Azure Event Hubs, Confluent Cloud. `token` accepts a string or an async function that returns one |
 | `GSSAPI` | Kerberos authentication |
 
 ```typescript
@@ -142,7 +142,7 @@ await helper.close({ isForce: true });
 
 ## Serialization
 
-`@platformatic/kafka`'s default wire format is `Buffer`. The helpers default the generic types to `string`, but you must pass serializers explicitly or messages travel as raw `Buffer`.
+`@platformatic/kafka`'s default wire format is `Buffer`. The helpers default the generic types to `string`, but that's a type default only. Pass serializers explicitly, or messages travel as raw `Buffer`.
 
 | Export | Type | Description |
 |--------|------|-------------|
@@ -264,13 +264,15 @@ The callback receives an `IKafkaTransactionContext`:
 
 ## Graceful Shutdown
 
-`close()` implements a two-phase shutdown:
+`close()` runs a two-phase shutdown:
 
-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 calls `close(true)` without timeout protection
+| Phase | When it runs | What happens |
+|---|---|---|
+| Graceful | Default | Calls `close(true)` on the underlying producer, capped at `shutdownTimeout` (default 30s) |
+| Force fallback | Graceful times out | Force-closes automatically, no further waiting |
+| Force | `close({ isForce: true })` | Calls `close(true)` immediately, no timeout |
 
-After `close()`, all broker tracking is cleared and `healthStatus` is set to `'disconnected'`.
+After `close()`, all broker tracking is cleared and `healthStatus` becomes `'disconnected'`.
 
 ```typescript
 // Graceful (recommended)
@@ -373,11 +375,13 @@ Close the producer connection.
 
 ## Key Partitioning
 
-By default, `@platformatic/kafka` uses **murmur2 hashing** on the message key to determine the target partition:
+By default, `@platformatic/kafka` uses **murmur2 hashing** on the message key to pick the target partition:
 
-- Same key -> always same partition -> guaranteed ordering per key
-- `undefined` key -> round-robin across partitions
-- Explicit `partition` field -> overrides the partitioner
+| Key | Target partition |
+|---|---|
+| Same key, every time | Same partition - ordering is guaranteed per key |
+| `undefined` | Round-robin across partitions |
+| Explicit `partition` field | That partition, overriding the partitioner |
 
 ```typescript
 // Custom partitioner
@@ -395,6 +399,7 @@ await producer.send({
 - [Consumer](./consumer) - the receiving side, including message callbacks and lag monitoring
 - [Schema Registry](./schema-registry) - schema-validated serialization instead of manual `serializers`
 - [Compiling to a Single Binary](./compile-binary) - required when this helper ships inside a `bun build --compile` binary
+- [Examples & Troubleshooting](./examples) - IoC wiring and the common connection-error lookup table
 
 **Files:**
 

package/content/extensions/helpers/kafka/schema-registry.md

@@ -18,7 +18,10 @@ 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.
+
+> [!WARNING]
+> Compiling to a standalone binary needs `platformaticRequirePlugin()`. `ConfluentSchemaRegistry` resolves `ajv-draft-04` through `createRequire` at module load, which `bun build --compile` cannot see through. See [Compiling to a Single Binary](./compile-binary).
 
 ## Helper API
 
@@ -39,10 +42,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 it solves
@@ -50,23 +53,24 @@ interface IKafkaSchemaRegistryOptions extends ConfluentSchemaRegistryOptions {
 Without a schema registry, producers and consumers must agree on message shape out-of-band. If the producer changes the shape of `value` (adds/removes fields), consumers break silently at runtime.
 
 - **Schema Registry is a centralized server** (Confluent Schema Registry) that stores and validates schemas.
-- **It enforces a contract:** the producer says "I want to send this shape", the registry validates it against the registered schema before the message reaches Kafka; the consumer asks "what shape is this?" and the registry tells it how to deserialize.
+- **It enforces a contract on the way out.** The producer says "I want to send this shape." The registry validates that shape against the registered schema before the message reaches Kafka.
+- **It enforces a contract on the way in.** The consumer asks "what shape is this?" The registry answers with how to deserialize it.
 
 | | Without registry | With registry |
 |---|---|---|
 | **Message format** | Raw string, manual `JSON.stringify`/`JSON.parse` | Typed object, auto ser/deser |
-| **Validation** | None -- runtime crashes on shape drift | Schema validated before send |
+| **Validation** | None - runtime crashes on shape drift | Schema validated before send |
 | **Schema evolution** | Breaks consumers silently | Backward/forward compatibility enforced |
 | **Where schemas live** | Nowhere (tribal knowledge) | Centralized server, e.g. `http://registry:8081` |
 
-Use it when you need schema enforcement and compatibility checks across producers/consumers - especially in multi-team environments. Skip it for simple string/JSON messages where both sides are controlled by the same team and format changes are coordinated by hand.
+Use it when you need schema enforcement and compatibility checks across producers and consumers, especially in multi-team environments. Skip it for simple string or JSON messages where one team controls both sides - coordinate format changes by hand instead.
 
 ## Without vs. with the registry
 
 Without a registry, serialization is entirely manual and unchecked:
 
 ```typescript
-// Producer -- manually serialize
+// Producer - manually serialize
 const producer = KafkaProducerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-producer',
@@ -76,11 +80,11 @@ 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 }),  // <- plain 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',
@@ -103,13 +107,13 @@ import {
   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',
   // auth: { username: 'user', password: 'pass' },  // optional
 });
 
-// 2. Producer -- pass registry, it auto-serializes values using the registered schema
+// 2. Producer - pass registry, it auto-serializes values using the registered schema
 const producer = KafkaProducerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-producer',
@@ -125,7 +129,7 @@ await producer.getProducer().send({
 });
 // If the value doesn't match the registered schema -> error BEFORE sending to Kafka
 
-// 3. Consumer -- pass the same registry, it auto-deserializes
+// 3. Consumer - pass the same registry, it auto-deserializes
 const consumer = KafkaConsumerHelper.newInstance({
   bootstrapBrokers: ['127.0.0.1:29092'],
   clientId: 'order-consumer',
@@ -182,6 +186,7 @@ const consumer = KafkaConsumerHelper.newInstance({
 - [Kafka Overview](./) - the four helpers, shared health/close API, and the compile-binary caveat
 - [Producer](./producer) - `registry` as a producer option, plus the manual `serializers` alternative
 - [Consumer](./consumer) - `registry` as a consumer option, plus the manual `deserializers` alternative
+- [Examples & Troubleshooting](./examples) - IoC wiring and the common connection-error lookup table
 
 **Files:**
 

package/content/extensions/helpers/logger/hf-logger.md

@@ -6,16 +6,22 @@ difficulty: advanced
 
 # HfLogger - High-Frequency Logging Guide
 
-`HfLogger` is a fixed-layout ring-buffer logger for hot paths where even the standard `Logger` is too expensive. A log call writes a 256-byte binary entry into a lazily-allocated buffer - no string formatting, no transport I/O, no per-call allocation on the fast path - and a separate `HfLogFlusher` drains entries later, off the hot path.
+`HfLogger` is a fixed-layout ring-buffer logger for hot paths where even the standard `Logger` is too expensive. A log call writes a 256-byte binary entry into a lazily-allocated buffer. Nothing runs on the fast path: no string formatting, no transport I/O, no per-call allocation. A separate `HfLogFlusher` drains entries later, off the hot path.
 
-It implements `ILogger` (`AbstractLogger`), so it is a drop-in replacement anywhere an `ILogger` is expected - a direct method for every level (`debug`, `info`, `warn`, `error`, `emerg`), plus `log` and `for`, all work. It is still entirely separate from the Winston-backed `Logger` pipeline: no formatters, no transports, no `APP_ENV_LOGGER_*` variables apply to it. It trades that pipeline away for enqueue speed - measured at 59.4ns/op on the bytes path and 66.0ns/op on the string no-args path on a modern machine (Bun 1.3.14, 1M-iteration median), against 831ns/op for pino writing to `/dev/null` on the same machine - roughly 14x faster.
+It implements `ILogger` (`AbstractLogger`), so it's a drop-in replacement anywhere an `ILogger` is expected. Every level method works - `debug`, `info`, `warn`, `error`, `emerg`, plus `log` and `for`. But it stays entirely separate from the Winston-backed `Logger` pipeline: no formatters, no transports, no `APP_ENV_LOGGER_*` variables apply to it.
+
+That separation buys enqueue speed - roughly 14x faster than pino on the same machine. See [Performance characteristics](#performance-characteristics) below for the measured numbers.
 
 > [!IMPORTANT]
 > Reach for `HfLogger` only when a profiler shows logging itself in your hot path - order engines, market-data ticks, per-packet paths at 100k+ events/sec. For everything else, the standard scoped `Logger` is the right tool: it formats, redacts, rotates files, and ships UDP. Most services never need this module.
 
 ## Mental model
 
-One ring buffer per process holds 65,536 entries of 256 bytes each (16MB), allocated lazily on the first `HfLogger.get()` call - not at module import. Writers stamp entries in; the ring never blocks and never grows. When the ring is full, the NEXT write overwrites the OLDEST entry - the buffer trades completeness for a bounded, allocation-free hot path, and the flusher now counts and reports every entry it overwrites before it could be read (see "Lap accounting" below).
+One ring buffer per process holds 65,536 entries of 256 bytes each - 16MB total. It allocates lazily, on the first `HfLogger.get()` call, never at module import.
+
+Writers stamp entries in. The ring never blocks and never grows.
+
+When the ring is full, the next write overwrites the oldest entry. The buffer trades completeness for a bounded, allocation-free hot path. But every overwrite is counted and reported, never silent - see [Lap accounting](#lap-accounting) below.
 
 **Entry layout (256 bytes):**
 
@@ -28,7 +34,9 @@ One ring buffer per process holds 65,536 entries of 256 bytes each (16MB), alloc
 | 42 | 1 byte | Message length (0-213) |
 | 43-255 | 213 bytes | Message bytes |
 
-The two length bytes are what make reads exact: the flusher decodes only the bytes a field actually holds, never the fixed-width remainder, so there is no NUL padding and no stale tail leaking from whatever a reused slot last held. Because entries are fixed-width binary, everything you log must fit the layout: scopes at most 32 bytes, messages at most 213 bytes. Anything longer is truncated, not rejected.
+The two length bytes are what make reads exact. The flusher decodes only the bytes a field actually holds, never the fixed-width remainder. So there's no NUL padding, no stale tail leaking from whatever a reused slot last held.
+
+Because entries are fixed-width binary, everything you log must fit the layout above. Anything longer than the scope or message cap is truncated, not rejected.
 
 ## Setup - everything happens at initialization time
 
@@ -60,7 +68,7 @@ orderLogger.log('error', MSG_ORDER_REJECTED);
 ```
 
 ```typescript
-// -- Or drain manually (e.g. at a batch boundary or before shutdown) --
+// -- Or drain manually (for example, at a batch boundary or before shutdown) --
 await flusher.flush();
 
 // -- And stop the interval when the logger is no longer needed --
@@ -69,7 +77,7 @@ flusher.stop();
 
 ## The ILogger surface - and its cost model
 
-`HfLogger` implements the same `ILogger` methods as the standard `Logger`, so it can be typed and passed around as `ILogger`. But each method sits on a different point of the cost curve, and picking the right one is the whole point of this module:
+`HfLogger` implements the same `ILogger` methods as the standard `Logger`, so it can be typed and passed around as `ILogger`. But each method sits on a different point of the cost curve. Picking the right one is the whole point of this module:
 
 ```typescript
 import { HfLogger } from '@venizia/ignis-helpers';
@@ -98,19 +106,35 @@ const MSG_ORDER_SENT = HfLogger.encodeMessage('Order sent');
 logger.log('info', MSG_ORDER_SENT);
 ```
 
-Rule of thumb: pre-encode and call the bytes overload for anything on a per-event, per-tick, per-packet path. Reach for the no-args string call when the message is a small fixed set of facts you did not think to pre-encode. Reach for the args form only off the true hot path - it is correct (nothing is ever silently dropped), just not free.
+Rule of thumb:
+
+| When | Use | Cost |
+|---|---|---|
+| A per-event, per-tick, per-packet path | Pre-encode, then call the bytes overload | ~59ns/op |
+| A small fixed set of facts you didn't pre-encode | The no-args string call | ~66ns/op |
+| Off the true hot path only | The args form (dynamic `%s` data) | Correct - nothing is ever silently dropped - but not free |
 
 ## The rules that keep it fast and correct
 
-**1. Never encode in the hot path.** `HfLogger.encodeMessage` (and the no-args string call, which shares the same cache) remembers every distinct string it sees. The cache is FIFO-bounded at 4096 entries - calling it with dynamic strings (`encodeMessage('order ' + id)`) still puts UTF-8 encoding on your hot path and now evicts the oldest cached message once you cross the cap, corrupting the fixed vocabulary you rely on elsewhere. If a value varies per event, it does not belong in an `HfLogger` message; log the static fact here and the variable detail through the standard `Logger` at a lower frequency, or use the args form off the hot path.
+**1. Never encode in the hot path.** `HfLogger.encodeMessage` remembers every distinct string it sees. So does the no-args string call, since it shares the same cache. That cache is FIFO-bounded at 4096 entries.
+
+Calling it with dynamic strings (`encodeMessage('order ' + id)`) still puts UTF-8 encoding on your hot path. Worse, it evicts the oldest cached message once you cross the cap - corrupting the fixed vocabulary you rely on elsewhere.
+
+If a value varies per event, it doesn't belong in an `HfLogger` message. Log the static fact here, and the variable detail through the standard `Logger` at a lower frequency. Or use the args form, off the hot path.
+
+**2. A fixed vocabulary of messages.** The bytes path targets a finite set of pre-encoded facts: "Order sent", "Tick received", "Risk check failed".
+
+If you find yourself needing free-form text on the hot path, you're in the wrong module. Use the args form instead, off the hot path.
+
+**3. Size the flush interval against your write rate.** The ring holds 65,536 entries. Write more than that between two flushes, and the oldest unflushed entries get overwritten. The flusher reports exactly how many via `dropped` on the sink batch - never silently (see below).
 
-**2. A fixed vocabulary of messages.** The design point of the bytes path is a finite set of pre-encoded facts ("Order sent", "Tick received", "Risk check failed"). If you find yourself needing free-form text on the hot path, you are in the wrong module - or you want the args form, off the hot path.
+Pick the interval so `writeRate x interval < 65,536`, with comfortable margin. At 100k logs/sec, a 100ms interval accumulates ~10k entries per drain - safe. At 1M logs/sec, you need ~30ms or faster.
 
-**3. Size the flush interval against your write rate.** The ring holds 65,536 entries. If more entries than that are written between two flushes, the oldest unflushed entries are overwritten - and the flusher now reports exactly how many via `dropped` on the sink batch (see below) instead of silently emitting stale data. Pick the interval so that `writeRate x interval < 65,536` with comfortable margin: at 100k logs/sec, a 100ms interval accumulates ~10k entries per drain - safe; at 1M logs/sec you need ~30ms or faster.
+**4. One process, one thread.** `HfLogger` is safe only on a single thread within a single process. The write index is a plain counter - not shared, not atomic.
 
-**4. One process, one thread.** `HfLogger` is safe only on a single thread within a single process - the write index is a plain counter, not shared or atomic. Do not log to it from worker threads; each worker importing the module gets its own independent ring, and nothing coordinates them. This is a documented design point, not an accident.
+Don't log to it from worker threads. Each worker that imports the module gets its own independent ring, and nothing coordinates them. This is a documented design point, not an accident.
 
-**5. Flush before shutdown.** Entries live only in memory. An exiting process loses everything not yet flushed - call `await flusher.flush()` in your shutdown path, and `flusher.stop()` to clear the interval.
+**5. Flush before shutdown.** Entries live only in memory. An exiting process loses everything not yet flushed. Call `await flusher.flush()` in your shutdown path, and `flusher.stop()` to clear the interval.
 
 ## The flusher
 
@@ -136,7 +160,7 @@ const customFlusher = new HfLogFlusher({
 });
 
 flusher.start(100); // interval-based draining, unref'd so it never blocks process exit
-await flusher.flush(); // one-shot drain, e.g. before shutdown
+await flusher.flush(); // one-shot drain, for example before shutdown
 flusher.stop(); // clears the interval; start() again to resume
 ```
 
@@ -150,24 +174,27 @@ A rendered line looks like this:
 
 ### Lap accounting
 
-Every batch the flusher hands to its sink carries `dropped: number` - the count of entries overwritten by the ring before the flusher could read them since the previous batch. The default sink emits a `warn` marker line ahead of the batch when `dropped > 0`:
+Every batch the flusher hands to its sink carries `dropped: number`. That's the count of entries the ring overwrote before the flusher could read them, since the previous batch. The default sink emits a `warn` marker line ahead of the batch when `dropped > 0`:
 
 ```
 2026-07-18T09:41:03.200Z [warn] HfLogFlusher ring lapped - 342 entries overwritten before they could be read
 ```
 
-A custom `sink` gets the same `dropped` count on `batch.dropped` and decides how to surface it. This replaces the old silent behavior where a lapped ring simply emitted whatever currently sat in each slot.
+A custom `sink` gets the same `dropped` count on `batch.dropped` and decides how to surface it. This replaces the old silent behavior, where a lapped ring emitted whatever currently sat in each slot with no warning.
 
 ## Current limitations
 
 These are real behaviors of the current implementation - design around them:
 
-- **Single-thread only.** The write index is not shared or atomic across threads; each worker thread importing the module gets an independent ring. Do not log to `HfLogger` from worker threads expecting a shared buffer.
-- **The ring overwrites the oldest entry when lapped.** If the producer writes faster than the flusher drains (rule 3 above), unflushed entries are silently overwritten in memory - but the flusher now counts and reports every one of them via `dropped`, so the loss is visible rather than invisible.
-- **213-byte message cap, 32-byte scope cap.** Both are truncation-only - a longer value is cut, not rejected. The truncation is a byte-boundary cut, not a character-boundary one, so it can split a multibyte UTF-8 character - the truncated tail then renders as the U+FFFD replacement character.
-- **Run one flusher per process.** Each `HfLogFlusher` tracks its own read position from the start of the ring, not a shared cursor - a second flusher re-emits entries the first one already drained.
-- **A fixed, pre-encoded vocabulary is still the right pattern for the bytes path.** `HfLogger.encodeMessage` / the no-args string call exist to make the ENCODE cost a one-time expense; the args form is correct but is the slow path by design.
-- **The encode cache is FIFO-bounded at 4096 entries.** Well within a real fixed vocabulary, but a hot path that generates many distinct dynamic strings through the no-args string call will start evicting and re-encoding.
+- **Single-thread only.** The write index is not shared or atomic across threads. Each worker thread that imports the module gets an independent ring. Don't log to `HfLogger` from worker threads expecting a shared buffer.
+- **The ring overwrites the oldest entry when lapped.** If the producer writes faster than the flusher drains (see rule 3 above), unflushed entries get silently overwritten in memory.
+- **The loss is visible, not invisible.** The flusher counts and reports every overwritten entry via `dropped`.
+- **213-byte message cap, 32-byte scope cap.** Both are truncation-only - a longer value is cut, not rejected.
+- **Truncation happens at a byte boundary, not a character boundary.** It can split a multibyte UTF-8 character - the truncated tail then renders as the U+FFFD replacement character.
+- **Run one flusher per process.** Each `HfLogFlusher` tracks its own read position from the start of the ring - not a shared cursor. A second flusher re-emits entries the first one already drained.
+- **A fixed, pre-encoded vocabulary is still the right pattern for the bytes path.** `HfLogger.encodeMessage` and the no-args string call exist to make the ENCODE cost a one-time expense.
+- **The args form is correct, but it's the slow path by design.** Reserve it for control-flow events, off the hot path.
+- **The encode cache is FIFO-bounded at 4096 entries.** That's well within a real fixed vocabulary. But a hot path that generates many distinct dynamic strings, through the no-args string call, will start evicting and re-encoding.
 
 ## Performance characteristics
 
@@ -179,7 +206,7 @@ Measured on Bun 1.3.14, 1M-iteration median:
 | String, no args (`info('Order sent')`) | 66.0ns/op | Cache-hit encode lookup + bytes-path write |
 | pino, sync, `/dev/null` | 831ns/op | ~14x slower than the `HfLogger` bytes path on the same machine |
 
-Heap growth measured at 0.0MB over 1M bytes-path logs - the hot path does not allocate. That buys an ENQUEUE, not a durable log line; the flusher still pays rendering cost later, off the hot path.
+Heap growth measured at 0.0MB over 1M bytes-path logs - the hot path does not allocate. That buys an ENQUEUE, not a durable log line. The flusher still pays rendering cost later, off the hot path.
 
 ## See also
 

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

@@ -1,12 +1,12 @@
 ---
 title: Logger
-description: Scoped, cached Winston logging with console, daily-rotating file, and UDP transports
+description: Scoped, cached logging via LoggerFactory - Winston by default, with console, daily-rotating file, and UDP transports built in
 difficulty: beginner
 ---
 
 # Logger
 
-The logger helper wraps Winston in a scoped, cached `Logger` class with console, daily-rotating file, and UDP transports built in.
+IGNIS gives every helper a scoped `ILogger`. `LoggerFactory` builds it from one registered provider - Winston by default, with console, daily-rotating file, and UDP transports built in.
 
 ## In one example
 
@@ -24,16 +24,17 @@ logger.info('User created');
 
 ## How it works
 
-- **Typed against `ILogger`.** Every consumer, including `BaseHelper.logger`, receives the `ILogger` interface, not a concrete class - Winston is the built-in provider behind it today, selected in `factory.ts`.
-- **Provider-based.** `LoggerFactory.use({ provider })` selects the app's logger engine once at the entrypoint - Winston by default, [pino](/extensions/helpers/logger/pino) for throughput. Every factory-issued logger (including ones captured at import time) follows the registration.
-- **Scoped and cached.** `LoggerFactory.getLogger(scopes)` joins the scopes with `-` and caches per scope - the same scope returns the same instance. `BaseHelper` calls this in its constructor, so every helper gets `this.logger` scoped automatically. (Custom-backed winston loggers - `Logger.get(scope, customWinstonLogger)` from the `/winston` sub-path - are NOT cached: each call is a fresh wrapper over the given instance.)
+- **Typed against `ILogger`.** Every consumer - including `BaseHelper.logger` - gets the `ILogger` interface, never a concrete class. Winston is the default provider behind it, selected in `factory.ts`.
+- **Provider-based.** `LoggerFactory.use({ provider })` selects the app's logger engine once, at the entrypoint. Winston is the default; [pino](/extensions/helpers/logger/pino) is the throughput option. Every factory-issued logger follows the registration, even one captured at import time.
+- **Scoped and cached.** `LoggerFactory.getLogger(scopes)` joins the scopes with `-` and caches the result per scope. The same scope always returns the same instance. `BaseHelper` calls this in its constructor, so every helper's `this.logger` comes pre-scoped.
+- **Custom-backed loggers are the exception.** `Logger.get(scope, customWinstonLogger)` (from the `/winston` sub-path) is NOT cached. Each call returns a fresh wrapper over the instance you passed in.
 - **Method scoping.** `.for(methodName)` returns a child logger scoped to `<scope>-<methodName>` (also cached), so each line shows where it came from.
-- **Level floor.** `APP_ENV_LOGGER_LEVEL` (default `debug`) sets the logger-level floor; transports without their own level inherit it.
-- **`debug()` is gated.** It emits only when `DEBUG=true` and `NODE_ENV` is unset or in `Environment.COMMON_ENVS` (extend via `APP_ENV_EXTRA_LOG_ENVS`). The check runs once at module load - runtime env changes need a restart.
+- **Level floor.** `APP_ENV_LOGGER_LEVEL` (default `debug`) sets the logger-level floor. Transports without their own level inherit it.
+- **`debug()` is gated.** It emits only when `DEBUG=true` and `NODE_ENV` is unset or listed in `Environment.COMMON_ENVS`. Extend that set via `APP_ENV_EXTRA_LOG_ENVS`. The check runs once at module load - runtime env changes need a restart.
 
 **Log levels**
 
-Five levels, each with a direct method: `debug`, `info`, `warn`, `error`, `emerg`. The generic `.log(level, ...)` remains for picking the level dynamically. What each level MEANS and when to use it is in the [level guide](/extensions/helpers/logger/reference#what-each-level-means).
+Five levels, each with a direct method: `debug`, `info`, `warn`, `error`, `emerg`. The generic `.log(level, ...)` remains for picking the level dynamically. What each level means, and when to use it, is in the [level guide](/extensions/helpers/logger/reference#what-each-level-means).
 
 **Transports**
 
@@ -43,7 +44,9 @@ Five levels, each with a direct method: `debug`, `info`, `warn`, `error`, `emerg
 | Daily-rotating file | `APP_ENV_LOGGER_FOLDER_PATH` is set |
 | UDP (`DgramTransport`) | All four UDP `APP_ENV_LOGGER_DGRAM_*` variables are set |
 
-Output shape (plain text or JSON) follows `APP_ENV_LOGGER_FORMAT`. Color codes appear only on the console - file and UDP output never carries ANSI escapes. For extreme hot paths, `HfLogger` is a separate ring-buffer logger outside this pipeline - it has its own [usage guide](/extensions/helpers/logger/hf-logger). The [Full reference](/extensions/helpers/logger/reference) covers everything else, including the `ApplicationLogger` facade.
+Output shape (plain text or JSON) follows `APP_ENV_LOGGER_FORMAT`. Color codes appear only on the console, and only in a development `NODE_ENV` - file and UDP output never carries ANSI escapes. See [Color](./reference#color) to override.
+
+For extreme hot paths, `HfLogger` is a separate ring-buffer logger outside this pipeline, with its own [usage guide](/extensions/helpers/logger/hf-logger). The [Full reference](/extensions/helpers/logger/reference) covers everything else, including the `ApplicationLogger` facade.
 
 ## Common tasks
 
@@ -75,12 +78,28 @@ class UserService {
 
 ### Log an Error with `%s`, never `%j`
 
-`message` and `stack` are non-enumerable on a native `Error`. `%j` formats via `JSON.stringify`, which only visits enumerable own properties, so it silently drops both. Always pair an `Error` argument with `%s`.
+`%s` routes the error through `ErrorPrettier`, which projects it down to identity, cause and frames. `%j` keeps every enumerable own property instead, so a driver error takes its whole query along and a `jose` error its whole payload. Always pair an `Error` argument with `%s`.
 
 ```typescript
 logger.error('Failed to create user: %s', error); // prints message + stack
 ```
 
+A mistaken `%j` is no longer a silent loss: the formatter projects `message` and `stack` in before `JSON.stringify` runs, which on its own would drop both (they are non-enumerable). It is still the wrong placeholder for an error.
+
+### Keep a driver error readable with `ErrorPrettier`
+
+`%s` prints the whole object. A `pg` or `drizzle` failure carries the statement in `message`, again in `stack`, and again in `query` - one failure floods the log with the same SQL several times. Wrap it:
+
+```typescript
+import { ErrorPrettier } from '@venizia/ignis-helpers';
+
+logger.error('Failed to create user | %s', ErrorPrettier.format({ error }));
+```
+
+You get the identity, the root `cause` with its code, the driver's `hint`, the full message and the top stack frames - each on its own line, with the message's real newlines intact. The duplicated statement and the noisy driver internals are gone.
+
+Pass `includeStack: false` when the error is one you raised yourself and the frames add nothing. For a JSON sink, `ErrorPrettier.summarize({ error })` returns the same projection as a typed object instead of a string.
+
 ### Switch the output format
 
 `APP_ENV_LOGGER_FORMAT` controls plain text (default) vs. JSON output.
@@ -94,14 +113,20 @@ The `[APP]` label comes from `APP_ENV_APPLICATION_NAME` (defaults to `'APP'`).
 
 ### Enable daily file rotation
 
-Point `APP_ENV_LOGGER_FOLDER_PATH` at a directory; rotation frequency, size cap, and retention are also env-driven. Without this variable no log files are written - console (and UDP, if configured) remain the only outputs.
+Point `APP_ENV_LOGGER_FOLDER_PATH` at a directory. Rotation frequency, size cap, and retention are also env-driven. Without this variable, no log files are written - console (and UDP, if configured) remain the only outputs.
 
 ```bash
 APP_ENV_LOGGER_FOLDER_PATH=./app_data/logs
 APP_ENV_LOGGER_FILE_MAX_FILES=30d
 ```
 
-Defaults: `1h` rotation frequency, `100m` max size per file, `5d` retention. Programmatic configuration (per-transport prefixes, custom retention) is in the [Full reference](/extensions/helpers/logger/reference).
+| Setting | Default |
+|---|---|
+| Rotation frequency | `1h` |
+| Max file size | `100m` |
+| Retention | `5d` |
+
+Full programmatic configuration - custom prefixes, custom retention - is in the [Full reference](/extensions/helpers/logger/reference).
 
 ### Forward logs over UDP