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

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

@@ -6,7 +6,7 @@ difficulty: intermediate
 
 # Redis
 
-The Redis helper gives you one data API that works identically whether you are talking to a single node, a sharded cluster, or a Sentinel-managed high-availability pair.
+The Redis helper gives you one data API for Redis. Talk to a single node, a sharded cluster, or a Sentinel-managed high-availability pair - the calls you write stay the same.
 
 ## In one example
 
@@ -34,7 +34,8 @@ console.log(session); // { userId: 42, active: true }
 
 ## How it works
 
-- **Three topologies, one interface.** `RedisSingleHelper`, `RedisClusterHelper`, and `RedisSentinelHelper` all extend `AbstractRedisHelper` and implement `IRedisHelper`. Only the constructor options differ - the data API (`get`, `hSet`, `publish`, ...) is identical, so code written against `IRedisHelper` works with any topology unchanged.
+- **Three topologies, one interface.** `RedisSingleHelper`, `RedisClusterHelper`, and `RedisSentinelHelper` all extend `AbstractRedisHelper` and implement `IRedisHelper`. Only the constructor options differ.
+- **The data API never changes.** `get`, `hSet`, `publish`, and every other method are identical across all three. Code written against `IRedisHelper` works unchanged, whichever topology backs it.
 
 | Topology | Class | Fits |
 |----------|-------|------|
@@ -42,18 +43,35 @@ console.log(session); // { userId: 42, active: true }
 | Cluster | `RedisClusterHelper` | Data sharded across nodes |
 | Sentinel | `RedisSentinelHelper` | Automatic failover for one logical master |
 
-- **Pick a topology via the factory.** `createRedisHelper({ mode })` picks a topology from configuration - it is overloaded to return the concrete class when `mode` is a literal (`RedisModes.SINGLE | CLUSTER | SENTINEL`).
-- **Connection lifecycle is automatic.** With `autoConnect: true` (default) the ioredis client starts connecting in the constructor; with `autoConnect: false` you call `connect()` yourself.
-- **Reconnects back off automatically.** The backoff grows with each attempt, capped between 1 and 5 seconds, up to `maxRetry` attempts (`0` = unlimited, the default; `-1` = no retry).
-- **BullMQ compatibility differs by topology.** `maxRetriesPerRequest: null` is always set for single and Sentinel helpers, which is what makes them BullMQ-compatible out of the box. Cluster does not get this automatically - see the [Full reference](/extensions/helpers/redis/reference).
-- **Values are JSON-serialized automatically.** `set`, `mSet`, `jSet`, and `jPush` call `JSON.stringify` before writing; `getObject`, `getObjects`, and `jGet` parse on read. Plain `get`/`mGet` return the raw stored string unless you pass a `transform` function - reach for `getObject`/`getObjects` when you wrote the value with `set`.
+- **Pick a topology via the factory.** `createRedisHelper({ mode })` picks a topology from configuration. Pass a literal `mode` (`RedisModes.SINGLE | CLUSTER | SENTINEL`) and it returns the concrete class, not the generic `IRedisHelper`.
+- **Connection lifecycle is automatic.** With `autoConnect: true` (the default), the ioredis client starts connecting inside the constructor. Set `autoConnect: false` and call `connect()` yourself instead.
+- **Reconnect backoff grows with each attempt:** 2 s, then 4 s, then 5 s for every attempt after that. A successful reconnect resets it.
+- **The default does not reconnect at all.** `maxRetry` defaults to `0`, which gives up after the first failed attempt. Pass `-1` to reconnect forever.
+
+| `maxRetry` | Behavior |
+|---|---|
+| `0` (default) | No reconnect - the client gives up after the first failed attempt |
+| `-1` | Reconnect forever |
+| A positive number | Stop reconnecting after that many attempts |
+
+- **BullMQ compatibility differs by topology.** Single and Sentinel helpers always set `maxRetriesPerRequest: null`, which is what BullMQ requires. Cluster does not get this automatically - see the [Full reference](/extensions/helpers/redis/reference).
+- **Values are JSON-serialized automatically.**
+
+| Method group | Behavior |
+|---|---|
+| `set`, `mSet`, `jSet`, `jPush` | `JSON.stringify` before writing |
+| `getObject`, `getObjects`, `jGet` | `JSON.parse` on read |
+| `get`, `mGet` | Return the raw stored string, unless you pass `transform` |
+
+Wrote a value with `set`? Read it back with `getObject`/`getObjects`.
+
 - **Every method is camelCase.** `hSet`, `lPush`, `sAdd` - even where the underlying ioredis/Redis command is lowercase (`hset`, `lpush`, `sadd`). There is no lowercase alias.
 
 ## Common tasks
 
 ### Pick a topology
 
-Switch topology by changing `mode` and its matching options; the rest of your code does not change.
+Switch topology by changing `mode` and its matching options. The rest of your code does not change.
 
 ```typescript
 import { createRedisHelper, RedisModes, type IRedisHelper } from '@venizia/ignis-helpers';
@@ -71,7 +89,7 @@ See [Full reference](/extensions/helpers/redis/reference) for the cluster (`node
 
 ### Cache a value with a TTL
 
-`options.expiresIn` on `set` is in **milliseconds**, but `ttl()` reports remaining time in **seconds** - mixing the two up is the most common bug with this helper.
+`options.expiresIn` on `set` is in **milliseconds**. `ttl()` reports remaining time in **seconds**. Mixing the two up is the most common bug with this helper.
 
 ```typescript
 await redis.set({
@@ -85,7 +103,7 @@ const remaining = await redis.ttl({ key: 'session:42' }); // seconds; -1 = no ex
 
 ### Publish and subscribe
 
-A subscribed ioredis connection cannot run regular commands, so use a second helper instance for subscribing and keep the first for data operations.
+A subscribed ioredis connection cannot run regular commands. Use a second helper instance for subscribing, and keep the first for data operations.
 
 ```typescript
 const subscriber = new RedisSingleHelper({ name: 'sub', host: 'localhost', port: 6379, password: 'secret' });
@@ -112,7 +130,7 @@ await redis.lPush({ key: 'queue:emails', values: ['welcome@example.com'] });
 
 ### Drop to a raw command
 
-`execute` calls any ioredis command directly - useful for commands the typed API does not cover, like `SCAN` (prefer it over `keys()` in production, which blocks the server on large keyspaces).
+`execute` calls any ioredis command directly. Reach for it when the typed API doesn't cover a command, like `SCAN`. Prefer `SCAN` over `keys()` in production - `keys()` blocks the server on large keyspaces.
 
 ```typescript
 const [cursor, matched] = await redis.execute<[string, string[]]>('SCAN', [

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

@@ -21,6 +21,21 @@ Backed by **ioredis** under the hood.
 - [`packages/helpers/src/modules/redis/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/common/types.ts) - option and callback types
 - [`packages/helpers/src/modules/redis/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/common/constants.ts) - `RedisModes`, `RedisSentinelRoles`
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See the class hierarchy and the nine capability interfaces | [Class and Interface Model](#class-and-interface-model) |
+| Construct a single-node client | [Construction - Single](#construction---single) |
+| Construct a cluster client | [Construction - Cluster](#construction---cluster) |
+| Construct a Sentinel client, or understand Sentinel HA | [Construction - Sentinel](#construction---sentinel) |
+| Pick a topology from configuration instead of hardcoding a class | [Selecting a Topology - the Factory](#selecting-a-topology---the-factory) |
+| Understand `autoConnect`, the four lifecycle callbacks, or `duplicateClient()` | [Lifecycle and Events](#lifecycle-and-events) |
+| Look up a method's signature and behavior | [Full Method Reference](#full-method-reference) |
+| Wire the helper into BullMQ, Socket.IO, WebSocket, or Casbin | [Using the Helper Across IGNIS](#using-the-helper-across-ignis) |
+| Avoid a production footgun | [Production Notes](#production-notes) |
+| Copy the full import list | [Import Reference](#import-reference) |
+
 ## Class and Interface Model
 
 ### Class hierarchy
@@ -33,7 +48,7 @@ Backed by **ioredis** under the hood.
 | `RedisSentinelHelper` | `AbstractRedisHelper` | ioredis `Redis` client (Sentinel mode); returns `Redis` from `getClient()` |
 
 > [!TIP] Typing rule
-> Declare parameters and bindings as `IRedisHelper`. Use `instanceof AbstractRedisHelper` for runtime topology checks. Never type-check against the concrete subclasses unless you need topology-specific behavior.
+> Declare parameters and bindings as `IRedisHelper`. Use `isRedisHelper(value)` for runtime checks - it reads a `Symbol.for` brand, so it still answers `true` for a helper built by a second installed copy of the package, where `instanceof AbstractRedisHelper` answers `false`. Never type-check against the concrete subclasses unless you need topology-specific behavior.
 
 ### TRedisClient
 
@@ -101,10 +116,11 @@ Combines `IRedisSingleHelperProps` and `IRedisHelperCallbacks`.
 | `name` | `string` | Yes | - | Helper identifier used in logs and as `IRedisHelper.name` |
 | `host` | `string` | Yes | - | Redis server hostname |
 | `port` | `string \| number` | Yes | - | Redis server port |
+| `user` | `string` | No | - | Accepted by the type but not read by the constructor - has no effect. Set auth via `password` only. |
 | `password` | `string` | Yes | - | Redis `requirepass` value |
 | `database` | `number` | No | `0` | Redis database index (0-15) |
 | `autoConnect` | `boolean` | No | `true` | Connect immediately; `false` uses ioredis `lazyConnect` |
-| `maxRetry` | `number` | No | `0` | Max reconnect attempts; `0` = unlimited; `-1` = no retry |
+| `maxRetry` | `number` | No | `0` | Reconnect attempts before giving up. `0` (default) = no reconnect; `-1` = reconnect forever |
 | `onInitialized` | `(opts: { name: string; helper: IRedisHelper }) => void` | No | - | Fired synchronously after construction |
 | `onConnected` | `(opts: { name: string; helper: IRedisHelper }) => void` | No | - | Fired on TCP connection established |
 | `onReady` | `(opts: { name: string; helper: IRedisHelper }) => void` | No | - | Fired when client is ready for commands |
@@ -112,10 +128,31 @@ Combines `IRedisSingleHelperProps` and `IRedisHelperCallbacks`.
 
 ### Retry strategy
 
-- **Backoff formula.** `Math.max(Math.min(attempt * 2000, 5000), 1000)` - starting at 1 s, capped at 5 s.
-- **Stop condition.** Reconnect stops when `attempt > maxRetry` (if `maxRetry > -1`).
+ioredis calls the strategy with `attempt` starting at `1`, so the first reconnect waits 2 s.
+
+| `attempt` | Delay |
+|---|---|
+| 1 | 2 s |
+| 2 | 4 s |
+| 3 and later | 5 s |
+
+- **Backoff formula.** `Math.max(Math.min(attempt * 2000, 5000), 1000)`. The `1000` floor is unreachable, because the smallest `attempt` is `1`.
+- **Backoff resets on success.** ioredis sets `retryAttempts` back to `0` once the client reaches `ready`.
+- **Stop condition.** Reconnect stops when `attempt > maxRetry`, unless `maxRetry` is `-1`. Under the default `maxRetry: 0` that fires on the very first attempt, so the client never reconnects.
+- **This strategy does not retry commands.** It only schedules reconnection.
 - **BullMQ requirement.** The framework always sets `maxRetriesPerRequest: null` internally, which BullMQ requires.
 
+### What happens to commands while the connection is down
+
+`maxRetriesPerRequest: null` turns off the per-request retry limit, so ioredis parks commands in its offline queue instead of failing them after N attempts. How that ends depends on `maxRetry`.
+
+| `maxRetry` | Outcome for queued commands |
+|---|---|
+| `-1` or a positive number | Flushed to the server once the client reconnects |
+| `0` (default) | Rejected with `Connection is closed.` as soon as the client gives up |
+
+To survive a restart or a failover without losing commands, set `maxRetry: -1`.
+
 ## Construction - Cluster
 
 `Source ->` [`packages/helpers/src/modules/redis/cluster/cluster.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/cluster/cluster.helper.ts)
@@ -151,7 +188,7 @@ const cluster = new RedisClusterHelper({
 > [!WARNING] No framework defaults injected
 > Cluster does not apply the backoff retry strategy or `maxRetriesPerRequest: null` automatically. Pass those inside `clusterOptions.redisOptions` if your consumers (e.g. BullMQ) require them.
 
-`duplicateClient()` on a cluster creates a **new** `Cluster` instance from the same startup nodes and options (because ioredis `Cluster` does not implement `.duplicate()`).
+`duplicateClient()` on a cluster creates a **new** `Cluster` instance from the same startup nodes and options. ioredis `Cluster` doesn't implement `.duplicate()`, so the helper builds a fresh instance instead.
 
 ## Construction - Sentinel
 
@@ -180,9 +217,9 @@ Redis Sentinel is a high-availability (HA) architecture made of three process ty
 ### Why your app connects to sentinels, not the master
 
 - **The master's address can change after a failover.** Hard-coding a master host would break on every failover.
-- **You give ioredis the sentinel addresses instead**, plus the monitored master group name (`masterName`). ioredis asks a sentinel for the current master and connects to it.
+- **You give ioredis the sentinel addresses instead**, plus the monitored master group name (`masterName`). ioredis asks a sentinel for the current master, then connects to it.
 - **ioredis re-queries sentinels automatically after a failover** - no manual reconnection logic needed.
-- **Your application code does not change during a failover.** The only observable effect is a few seconds of transient command failures, which the retry strategy handles.
+- **Your application code does not change during a failover.** The only observable effect is a few seconds of transient command failures. Set `maxRetry: -1` so the client reconnects and drains its queued commands - the default `maxRetry: 0` rejects them instead.
 
 ### Constructor
 
@@ -219,7 +256,7 @@ const redis = new RedisSentinelHelper({
 | `sentinelUsername` | `string` | No | - | Sentinel ACL username |
 | `database` | `number` | No | `0` | Redis database index |
 | `autoConnect` | `boolean` | No | `true` | Connect immediately |
-| `maxRetry` | `number` | No | `0` | Max reconnect attempts |
+| `maxRetry` | `number` | No | `0` | Reconnect attempts before giving up. `0` (default) = no reconnect; `-1` = reconnect forever. See [Retry strategy](#retry-strategy) |
 | `redisOptions` | `Partial<RedisOptions>` | No | - | Extra ioredis options; first-class fields above always override matching keys here |
 | `onInitialized` / `onConnected` / `onReady` / `onError` | callbacks | No | - | Same shape as single |
 
@@ -236,7 +273,7 @@ They are independent. You can name the helper `'ha-cache'` while `masterName` is
 
 ### The authentication model - 4 relationships
 
-Sentinel deployments have four separate authentication relationships. The app only configures two of them; the other two are server-side.
+Sentinel deployments have four separate authentication relationships. The app configures two of them. The other two are server-side.
 
 | # | From | To | App field | Server config |
 |---|------|----|-----------|---------------|
@@ -245,7 +282,7 @@ Sentinel deployments have four separate authentication relationships. The app on
 | 3 | **Sentinel** | **Data nodes** | (not set by app) | `sentinel auth-pass <group> <pass>` in sentinel.conf |
 | 4 | **Replica** | **Master** (replication) | (not set by app) | `masterauth` in redis.conf |
 
-**Relationship 3 is the silent failure.** If the data nodes require a password but sentinel.conf does not have `sentinel auth-pass`, the sentinel processes cannot check master health and will trigger false failovers. Configure it on the server side even when your app only sets `password`.
+**Relationship 3 is the silent failure.** If the data nodes require a password but `sentinel.conf` has no `sentinel auth-pass`, the sentinel processes can't check master health. They trigger false failovers instead. Configure `sentinel auth-pass` on the server side, even when your app sets only `password`.
 
 **Common cases:**
 - Private network, sentinels unauthenticated: set only `password`.
@@ -258,7 +295,7 @@ When the master fails:
 1. Sentinels reach quorum and promote a replica.
 2. ioredis detects the master change via sentinel notification.
 3. ioredis reconnects to the new master transparently.
-4. Any in-flight commands during the few-second window may fail transiently - the retry strategy retries them.
+4. Commands issued during the few-second window queue up, then flush once the client reconnects. This needs `maxRetry: -1` or a positive `maxRetry`; the default `0` rejects them.
 5. **Your application code does not change.** The same `RedisSentinelHelper` instance continues to work after failover.
 
 ### Local testing with Docker Compose
@@ -426,10 +463,10 @@ const dedicated = redis.duplicateClient();
 ```
 
 - **Creates an independent ioredis connection** from the same configuration.
-- **Implementation.** `AbstractRedisHelper.duplicateClient()` calls ioredis `client.duplicate()`, which copies the parent's `options` - including `lazyConnect`.
-- **Lazy or immediate.** `lazyConnect` is set to `!autoConnect`. With the default `autoConnect: true` (`lazyConnect: false`) the duplicate connects immediately; it is lazy (connects on first use) only when the parent was created with `autoConnect: false`.
+- **Implementation.** `AbstractRedisHelper.duplicateClient()` calls ioredis `client.duplicate()`. That copies the parent's `options`, including `lazyConnect`.
+- **Lazy or immediate.** `lazyConnect` is set to `!autoConnect`. With the default `autoConnect: true`, the duplicate connects immediately (`lazyConnect: false`). With `autoConnect: false`, the duplicate is lazy - it connects on first use.
 - **When to use it.** Whenever a consumer needs its own dedicated connection - Pub/Sub, BullMQ, Socket.IO adapters.
-- **Cluster is different.** For `RedisClusterHelper`, `duplicateClient()` instead constructs a new `Cluster` from the same startup nodes and options (ioredis `Cluster` has no `.duplicate()`).
+- **Cluster is different.** For `RedisClusterHelper`, `duplicateClient()` builds a new `Cluster` from the same startup nodes and options instead. ioredis `Cluster` has no `.duplicate()`.
 
 ## Full Method Reference
 
@@ -437,11 +474,31 @@ const dedicated = redis.duplicateClient();
 
 ### General notes (apply to all families)
 
-- **Empty-input no-ops:** Methods that accept an array (`keys`, `members`, `values`, `fields`, `payload`) short-circuit immediately when the array is empty, without calling ioredis - returning `0`, `[]`, or (for `mSet`) resolving `void`, per each method's return type. This prevents the "wrong number of arguments" error ioredis throws on empty varargs.
-- **Boolean mapping:** `expire`, `expireAt`, `persist`, `hExists`, `sIsMember` map ioredis numeric replies to `true` (`=== 1`) / `false`.
-- **JSON auto-serialization:** `set`, `mSet`, `jSet`, `jPush` call `JSON.stringify` before writing. `getObject`, `getObjects`, `jGet` parse on read. `get` and `mGet` return raw strings unless you pass `transform`.
-- **TTL units:** `set.options.expiresIn` is **milliseconds** (ioredis `PX`). `expire.seconds` is **seconds** (ioredis `EXPIRE`). `expireAt.atEpochSeconds` is a Unix epoch **in seconds** (ioredis `EXPIREAT`).
-- **Pub/Sub errors:** On subscription callback error, the helper **logs** the error and returns without throwing, because throwing inside an ioredis async callback would be an unhandled rejection.
+- **Empty-input no-ops.** `keys`, `members`, `values`, `fields`, and `payload` are all array inputs. An empty array skips the ioredis call and returns immediately - this avoids the "wrong number of arguments" error ioredis throws on empty varargs.
+
+  | Return value | Applies to |
+  |---|---|
+  | `0` | Count methods - `del`, `hDel`, `sRem`, `sAdd`, `lPush`, `rPush` |
+  | `[]` | Array reads - `mGet`, `sMembers` |
+  | `void` (no-op) | `mSet` |
+- **Boolean mapping.** `expire`, `expireAt`, `persist`, `hExists`, and `sIsMember` map ioredis numeric replies to `true` (`=== 1`) or `false`.
+- **JSON auto-serialization.**
+
+  | Method group | Behavior |
+  |---|---|
+  | `set`, `mSet`, `jSet`, `jPush` | `JSON.stringify` before writing |
+  | `getObject`, `getObjects`, `jGet` | `JSON.parse` on read |
+  | `get`, `mGet` | Return the raw string, unless you pass `transform` |
+
+- **TTL units differ by field.**
+
+  | Field | Unit | ioredis command |
+  |---|---|---|
+  | `set.options.expiresIn` | milliseconds | `PX` |
+  | `expire.seconds` | seconds | `EXPIRE` |
+  | `expireAt.atEpochSeconds` | Unix epoch seconds | `EXPIREAT` |
+
+- **Pub/Sub errors.** On a subscription callback error, the helper logs the error and returns. It never throws - throwing inside an ioredis async callback would be an unhandled rejection.
 
 ### IRedisConnection - connection lifecycle
 
@@ -521,7 +578,7 @@ const dedicated = redis.duplicateClient();
 
 | Method | Signature | Behavior |
 |--------|-----------|----------|
-| `publish<T>` | `(opts: { topics: string[]; payload: T; useCompress?: boolean }): Promise<void>` | JSON-serializes `payload` into a `Buffer`; optionally zlib-deflates it; publishes to each topic; skips empty/blank topics (logs error, does not throw) |
+| `publish<T>` | `(opts: { topics: string[]; payload: T; useCompress?: boolean }): Promise<void>` | JSON-serializes `payload` into a `Buffer`, optionally zlib-deflates it, and publishes to each topic. Filters out empty/blank topics first; if none remain, logs an error and returns without publishing |
 | `subscribe` | `(opts: { topic: string }): void` | Subscribes the client to `topic`; on subscription error the helper **logs** it and does not throw |
 | `unsubscribe` | `(opts: { topic: string }): void` | Unsubscribes from `topic`; on error the helper **logs** it and does not throw |
 
@@ -575,15 +632,15 @@ const info = await redis.execute<string>('INFO');
 
 ## Using the Helper Across IGNIS
 
-All three topologies implement `IRedisHelper` and are interchangeable in every integration below. Switch topology by changing the helper you construct; the consumer code does not change.
+All three topologies implement `IRedisHelper` and are interchangeable in every integration below. Switch topology by changing the helper you construct. The consumer code does not change.
 
 ### BullMQ (BullMQHelper)
 
 `BullMQHelper` accepts a `redisConnection: IRedisHelper`. Internally it:
-- Calls `redisConnection.duplicateClient()` to create dedicated `Queue` and `Worker` connections (BullMQ requires separate connections per role).
+- Calls `redisConnection.duplicateClient()` to create dedicated `Queue` and `Worker` connections. BullMQ requires a separate connection per role.
 - Calls `redisConnection.getClient() instanceof Cluster` to detect cluster topology and adjust BullMQ configuration.
 
-`RedisSingleHelper` (and `RedisSentinelHelper`) are BullMQ-compatible out of the box because the framework sets `maxRetriesPerRequest: null` in `buildDefaultOpts`.
+`RedisSingleHelper` and `RedisSentinelHelper` are BullMQ-compatible out of the box. The framework sets `maxRetriesPerRequest: null` in `buildDefaultOpts`.
 
 ```typescript
 import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
@@ -617,7 +674,7 @@ See the Socket.IO component documentation for the full component registration an
 ### WebSocket component (WebSocket server and emitter)
 
 - **Resolved from a binding key.** The WebSocket component resolves an `AbstractRedisHelper` from `@app/websocket/redis-connection`.
-- **Two dedicated connections.** `WebSocketServerHelper` calls `duplicateClient()` for its pub and sub connections; the WebSocket emitter calls `duplicateClient()` for its own pub connection.
+- **Two dedicated connections.** `WebSocketServerHelper` calls `duplicateClient()` for its pub and sub connections. The WebSocket emitter calls `duplicateClient()` again for its own pub connection.
 - **Any topology works.** Bind single, cluster, or Sentinel:
 
 ```typescript
@@ -632,7 +689,7 @@ See the WebSocket component documentation for the full component registration.
 ### Casbin authorization enforcer
 
 - **Configured via options.** The cached Casbin enforcer (`ICasbinEnforcerCachedRedis`) accepts `connection: IRedisHelper` inside its `options`.
-- **Uses only the typed API.** It calls the helper's `get`, `set` (with `options.expiresIn`), and `del` to read, write, and invalidate cached policy keys - it never reaches the raw client.
+- **Uses only the typed API.** It calls the helper's `get`, `set` (with `options.expiresIn`), and `del` to read, write, and invalidate cached policy keys. It never reaches the raw client.
 - **Any topology works** as the `connection`:
 
 ```typescript
@@ -674,10 +731,10 @@ class MyApp extends BaseApplication {
 ## Production Notes
 
 - **Use a singleton per logical connection.** Construct the helper once at startup and share it. Do not construct a new helper per request - each construction opens a new connection pool.
-- **`duplicateClient()` for Pub/Sub.** A subscribed ioredis connection cannot run normal commands. Always call `duplicateClient()` to get a dedicated subscriber connection and keep the main client for data operations.
+- **`duplicateClient()` for Pub/Sub.** A subscribed ioredis connection cannot run normal commands. Always call `duplicateClient()` to get a dedicated subscriber connection. Keep the main client for data operations.
 - **Sentinel for HA; Cluster for sharding.** These are different problems. Sentinel gives you automatic failover for a single logical master. Cluster shards data across nodes. They are not interchangeable.
-- **TTL unit reminder:** `set.options.expiresIn` is **milliseconds**; `expire.seconds` is **seconds**; `expireAt.atEpochSeconds` is a Unix epoch in **seconds**. Mixing these up causes unexpected key expirations.
-- **Sentinel `sentinel auth-pass` is a server-side requirement.** If your data nodes require a password, configure `sentinel auth-pass <group> <password>` in sentinel.conf in addition to the app-side `password` field. Missing it causes false failovers even when `password` is correct.
+- **TTL units differ by field** - see the [units table above](#general-notes-apply-to-all-families). Mixing them up causes unexpected key expirations.
+- **Sentinel `sentinel auth-pass` is a server-side requirement.** If your data nodes require a password, configure `sentinel auth-pass <group> <password>` in `sentinel.conf`, in addition to the app-side `password` field. Missing it causes false failovers, even when `password` is correct.
 - **Avoid `keys()` in production.** The Redis `KEYS` command scans the entire keyspace and blocks the server. Use `execute('SCAN', [...])` for production pattern matching.
 
 ## Import Reference

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

@@ -6,10 +6,10 @@ difficulty: intermediate
 
 # Secrets & Vault
 
-The Secrets helper family reads configuration and credentials from a backend - HashiCorp Vault, an encrypted `.env.vault`, or plain `process.env` - behind one `ISecretsHelper` interface. Only HashiCorp mints dynamic, rotating credentials; the other two are static.
+The Secrets helper family reads configuration and credentials from a backend, behind one `ISecretsHelper` interface. Swap the provider, and the calling code stays the same.
 
 > [!TIP] In an application, you rarely build a provider by hand
-> An IGNIS app enables secrets by overriding `registerSecrets()` on its application class; the framework builds the provider, hydrates static secrets into `Envs`, and wires rotation for you. See the [Secrets & Vault deep dive](/references/base/secrets) and the [guide](/guides/core-concepts/secrets-vault). This page documents the provider family itself.
+> An IGNIS app enables secrets by overriding `registerSecrets()` on its application class. The framework then builds the provider, hydrates static secrets into `Envs`, and wires rotation for you. See the [Secrets & Vault deep dive](/references/base/secrets) and the [guide](/guides/core-concepts/secrets-vault). This page documents the provider family itself.
 
 ## In one example
 
@@ -24,13 +24,9 @@ await secrets.configure();
 const value = await secrets.get({ path: 'ignored', key: 'APP_ENV_DB_PASSWORD' });
 ```
 
-Swap `provider` for `SecretProviders.HASHICORP_VAULT` (with a `config: { endpoint, auth }`) or `SecretProviders.DOTENV_VAULT` to change the backend - the calling code stays the same.
+Swap `provider` for `SecretProviders.HASHICORP_VAULT` (with a `config: { endpoint, auth }`) or `SecretProviders.DOTENV_VAULT` to change the backend.
 
-## How it works
-
-- **One base, three providers.** `AbstractSecretsHelper` owns the provider-agnostic machinery (TTL cache, lease registry, renewal scheduler, rotation dispatch). Concrete providers implement only the raw fetch/renew/revoke calls.
-- **Two secret classes.** Static secrets (`get`/`getBundle`) are TTL-cached. Dynamic, lease-bearing secrets (`lease`) are renewed automatically and drive rotation - only HashiCorp supports them.
-- **Factory selection.** `createSecretsHelper({ provider })` picks the tier; the peer-backed providers are reached only through a bundler-invisible dynamic import (`importOptionalModule`), so importing the package never requires `node-vault` or `@dotenvx/dotenvx` - not even when the application is compiled into a binary with `Bun.build`, which resolves literal dynamic imports at bundle time. No `external` entry is needed in the compile step.
+## The three providers
 
 | Provider | `SecretProviders` value | Kind | Optional peer |
 |----------|-------------------------|------|---------------|
@@ -38,6 +34,19 @@ Swap `provider` for `SecretProviders.HASHICORP_VAULT` (with a `config: { endpoin
 | `HashiCorpVaultHelper` | `hashicorp-vault` | KV + dynamic + rotation | `node-vault` (`@venizia/ignis-helpers/hashicorp-vault`) |
 | `DotenvVaultHelper` | `dotenv-vault` | Static (encrypted `.env.vault`) | `@dotenvx/dotenvx` (`@venizia/ignis-helpers/dotenv-vault`) |
 
+Only HashiCorp mints dynamic, lease-bearing credentials. The other two are read-only snapshots.
+
+## How it works
+
+- **One base class, three providers.** `AbstractSecretsHelper` owns the provider-agnostic machinery: a TTL cache, a lease registry, a renewal scheduler, and rotation dispatch. Each concrete provider implements only the raw fetch/renew/revoke calls.
+- **Static reads are TTL-cached.** `get()` and `getBundle()` cache by path, for `cacheTtlSeconds` (default `300`).
+- **The cache evicts lazily, not on a timer.** An expired entry is only cleared the next time you call `get()` or `getBundle()` for that path - there's no background sweep.
+- **Dynamic secrets renew themselves.** `lease()` opens a lease-bearing secret, and schedules its own renewal at `ttlSeconds * renewBeforeRatio` (default ratio `0.66`). Only HashiCorp supports `lease()` - the static providers throw.
+- **A failed renewal retries with backoff, then rotates.** If Vault is unreachable, the scheduler retries with capped exponential backoff. Once a renewal genuinely can't extend the lease, the helper fetches a fresh one and dispatches rotation.
+- **`createSecretsHelper({ provider })` picks the concrete class for you.**
+- **The peer packages stay invisible to bundlers.** `node-vault` and `@dotenvx/dotenvx` load only through a dynamic import (`ModuleUtility.load`). Importing `@venizia/ignis-helpers` never requires either package.
+- **This holds under `Bun.build` too.** A literal dynamic import resolves at bundle time, so a compiled binary needs no `external` entry for either peer.
+
 ## The `ISecretsHelper` interface
 
 | Method | Purpose |
@@ -52,10 +61,71 @@ Swap `provider` for `SecretProviders.HASHICORP_VAULT` (with a `config: { endpoin
 
 ## Common tasks
 
-- **Pick a provider.** `createSecretsHelper({ provider: SecretProviders.HASHICORP_VAULT, config: { endpoint, auth: { method: 'app-role', roleId, secretId } } })`. Install the peer first (`bun add node-vault`).
-- **Read a static value or a bundle.** `await secrets.get({ path, key })` / `await secrets.getBundle({ path })`.
-- **Open a dynamic, rotating credential.** `await secrets.lease({ path: 'database/creds/app-role', key: 'datasources.PostgresDataSource' })` - the provider renews it and emits `onRotate` when the backend issues fresh credentials.
-- **Static providers reject `lease()`.** `SystemEnvsHelper` and `DotenvVaultHelper` throw NotSupported - only HashiCorp has dynamic secrets.
+### Read a static value or a bundle
+
+```typescript
+const password = await secrets.get({ path: 'secret/data/app', key: 'DB_PASSWORD' });
+const bundle = await secrets.getBundle({ path: 'secret/data/app' });
+```
+
+### Connect to HashiCorp Vault
+
+Install the peer first: `bun add node-vault`. Vault supports three auth methods.
+
+| `auth.method` | Fields |
+|---|---|
+| `token` | `token` |
+| `app-role` | `roleId`, `secretId`, `mountPath?` |
+| `kubernetes` | `role`, `jwtPath?`, `mountPath?` |
+
+```typescript
+const secrets = await createSecretsHelper({
+  provider: SecretProviders.HASHICORP_VAULT,
+  config: {
+    endpoint: 'https://vault.internal:8200',
+    auth: { method: 'app-role', roleId, secretId },
+  },
+});
+await secrets.configure();
+```
+
+### Open a dynamic, rotating credential
+
+```typescript
+const lease = await secrets.lease({
+  path: 'database/creds/app-role',
+  key: 'datasources.PostgresDataSource',
+});
+
+secrets.onRotate(({ key, lease }) => {
+  logger.for('secrets').info('Rotated | key: %s | ttl: %d', key, lease.ttlSeconds);
+});
+```
+
+### Rebuild a live consumer when its secret rotates
+
+`registerRotatable` connects a pool - or any `ISecretRotatable` - directly to a lease key. It rebuilds on rotation without going through `onRotate`.
+
+```typescript
+secrets.registerRotatable({ key: 'datasources.PostgresDataSource', target: pool });
+```
+
+### Read a static `.env.vault`
+
+```typescript
+const secrets = await createSecretsHelper({
+  provider: SecretProviders.DOTENV_VAULT,
+  config: { path: '.env.vault', dotenvKey: process.env.DOTENV_KEY },
+});
+```
+
+### Shut down cleanly
+
+`shutdown()` clears every renewal timer and revokes every outstanding lease. Call it on application stop.
+
+```typescript
+await secrets.shutdown();
+```
 
 ## See also
 

package/content/extensions/helpers/socket-io/api.md

@@ -16,6 +16,19 @@ Exhaustive reference for `SocketIOServerHelper` and `SocketIOClientHelper`. For
 - [`packages/helpers/src/modules/socket/socket-io/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/common/constants.ts) - `SocketIOConstants`, `SocketIOClientStates`
 - [`packages/helpers/src/modules/socket/socket-io/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/socket/socket-io/index.ts) - barrel export (`@venizia/ignis-helpers/socket-io`)
 
+## Find what you need
+
+| You want to | Go to |
+|---|---|
+| See the full server and client call sequence | [Architecture](#architecture) |
+| Look up a server method (`send()`, `on()`, `getClients()`, ...) | [Server API](#server-api) |
+| Look up a client method (`emit()`, `subscribe()`, `joinRooms()`, ...) | [Client API](#client-api) |
+| Follow the auth handshake step by step | [Authentication Protocol](#authentication-protocol) |
+| Understand the three Redis connections | [Redis Adapter](#redis-adapter) |
+| Look up a type, option, or callback signature | [Types Reference](#types-reference) |
+| Look up an event name, room default, or client state | [Constants](#constants) |
+| Match an error message to its cause | [Common Errors](#common-errors) |
+
 ## Architecture
 
 ```
@@ -96,19 +109,21 @@ Extends `BaseHelper`. Manages a `socket.io` server with a Redis adapter, authent
 
 #### `constructor(opts: TSocketIOServerOptions)`
 
-Validates the runtime-specific `server` (Node) or `engine` (Bun) field and duplicates the provided `redisConnection` into three independent clients (`redisPub`, `redisSub`, `redisEmitter`). Does **not** start the IO server - call `configure()` to complete initialization.
+Validates the runtime-specific `server` (Node) or `engine` (Bun) field. Duplicates the provided `redisConnection` into three independent clients (`redisPub`, `redisSub`, `redisEmitter`). Does **not** start the IO server - call `configure()` to complete initialization.
 
 **Throws:**
 
-- `'[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!'` - `runtime: 'node'` and `server` is falsy
-- `'[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!'` - `runtime: 'bun'` and `engine` is falsy
-- `'[SocketIOServerHelper] Unsupported runtime!'` - `runtime` is neither `'node'` nor `'bun'`
-- `'Invalid redis connection to config socket.io adapter!'` - `redisConnection` is falsy
+| Message | Condition |
+|---------|-----------|
+| `[SocketIOServerHelper] Invalid HTTP server for Node.js runtime!` | `runtime: 'node'` and `server` is falsy |
+| `[SocketIOServerHelper] Invalid @socket.io/bun-engine instance for Bun runtime!` | `runtime: 'bun'` and `engine` is falsy |
+| `[SocketIOServerHelper] Unsupported runtime!` | `runtime` is neither `'node'` nor `'bun'` |
+| `Invalid redis connection to config socket.io adapter!` | `redisConnection` is falsy |
 
 #### `configure(): Promise<void>`
 
 1. Registers `error` listeners on all three duplicated Redis clients (logged, not thrown)
-2. Kicks off `connect()` on any client still in `'wait'` status (duplicated clients inherit `lazyConnect` from the parent and do not dial on their own)
+2. Kicks off `connect()` on any client still in `'wait'` status
 3. `await Promise.all([waitForRedisReady(redisPub), waitForRedisReady(redisSub), waitForRedisReady(redisEmitter)])`
 4. Creates the `IOServer` - `new IOServer(server, serverOptions)` for Node.js, or `new IOServer()` followed by `io.bind(engine)` for Bun
 5. Attaches the Redis adapter via `@socket.io/redis-adapter`
@@ -118,7 +133,7 @@ Validates the runtime-specific `server` (Node) or `engine` (Bun) field and dupli
 Must be called before `on()`, `send()`, or any server operation.
 
 > [!NOTE]
-> `waitForRedisReady` rejects after **30 seconds** if a client never reaches `ready` (or immediately on that client's `error` event), so a broken Redis connection fails `configure()` instead of hanging boot indefinitely.
+> `waitForRedisReady` rejects after **30 seconds** if a client never reaches `ready` (or immediately on that client's `error` event). A broken Redis connection fails `configure()` instead of hanging boot indefinitely.
 
 #### `getIOServer(): IOServer`
 
@@ -159,13 +174,15 @@ socketServer.on({
 
 **Throws:**
 
-- `'[on] Invalid topic to start binding handler'` - `topic` is empty/falsy
-- `'[on] Invalid event handler | topic: {topic}'` - `handler` is missing
-- `'[on] IOServer is not initialized yet!'` - called before `configure()` completes
+| Message | Condition |
+|---------|-----------|
+| `[on] Invalid topic to start binding handler` | `topic` is empty/falsy |
+| `[on] Invalid event handler \| topic: {topic}` | `handler` is missing |
+| `[on] IOServer is not initialized yet!` | called before `configure()` completes |
 
 #### `onClientConnect(opts: { socket: IOSocket }): void`
 
-Handles a new socket connection. Invoked automatically by the `'connection'` event; can also be called manually.
+Handles a new socket connection. Invoked automatically by the `'connection'` event, but can also be called manually.
 
 1. Creates an `ISocketIOClient` entry with state `UNAUTHORIZED`
 2. Starts the `authenticateTimeout` timer
@@ -241,11 +258,11 @@ Extends `BaseHelper`. Manages a `socket.io-client` connection with authenticatio
 
 #### `constructor(opts: ISocketIOClientOptions)`
 
-Stores the callbacks and calls `configure()` internally - the client starts connecting immediately.
+Stores the callbacks and calls `configure()` internally. The client starts connecting immediately.
 
 #### `configure(): void`
 
-Creates the `socket.io-client` connection (`io(host, options)`) and registers the internal lifecycle handlers below. Called automatically by the constructor; a second call is a no-op if a client instance already exists.
+Creates the `socket.io-client` connection (`io(host, options)`) and registers the internal lifecycle handlers below. Called automatically by the constructor. A second call is a no-op if a client instance already exists.
 
 | Event | Behavior |
 |-------|----------|
@@ -294,7 +311,7 @@ const client = new SocketIOClientHelper({
 
 #### `subscribe<T>(opts: { event: string; handler: TSocketIOEventHandler<T>; ignoreDuplicate?: boolean }): void`
 
-Registers a handler on the client socket. The handler is wrapped with error handling that catches both sync throws and async rejections, and the wrapper is tracked in an internal `wrappedHandlers` map so `unsubscribe()` can find and remove it.
+Registers a handler on the client socket. The handler is wrapped with error handling that catches both sync throws and async rejections. That wrapper is tracked in an internal `wrappedHandlers` map, so `unsubscribe()` can find and remove it.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -317,7 +334,7 @@ client.subscribeMany({
 
 #### `unsubscribe(opts: { event: string; handler?: TSocketIOEventHandler }): void`
 
-- With `handler`, removes only that specific handler (looked up in `wrappedHandlers`; no-op if it was not registered through this helper)
+- With `handler`, removes only that specific handler (looked up in `wrappedHandlers`). No-op if that handler was not registered through this helper
 - Without `handler`, removes **all** handlers for the event
 - No-op if the event has no listeners
 
@@ -347,21 +364,23 @@ Emits an event to the server.
 | `doLog` | `boolean` | `false` | Logs the emission details |
 | `callback` | `() => void` | `undefined` | Invoked via `setImmediate` after the emit call |
 
-**Throws:**
+**Throws** (both status `400`):
 
-- `'Invalid socket client state to emit'` (status 400) - the client is not connected
-- `'Topic is required to emit'` (status 400) - `topic` is empty/falsy
+| Message | Condition |
+|---------|-----------|
+| `Invalid socket client state to emit` | the client is not connected |
+| `Topic is required to emit` | `topic` is empty/falsy |
 
 #### `joinRooms(opts: { rooms: string[] }): void`
 
-Emits `'join'` with `{ rooms }`; the server validates the request through its `validateRoomFn`. Logs a warning and no-ops if the client is not connected.
+Emits `'join'` with `{ rooms }`. The server validates the request through its `validateRoomFn`. Logs a warning and no-ops if the client is not connected.
 
 #### `leaveRooms(opts: { rooms: string[] }): void`
 
 Emits `'leave'` with `{ rooms }`. Logs a warning and no-ops if the client is not connected.
 
 > [!NOTE]
-> Unlike `joinRooms()`, leave requests are **not** validated server-side - the client can request to leave any room name, including ones it never joined (`socket.leave()` on a room the socket isn't in is a no-op).
+> Unlike `joinRooms()`, leave requests are **not** validated server-side. The client can request to leave any room name, including ones it never joined. `socket.leave()` on a room the socket isn't in is a no-op.
 
 #### `shutdown(): void`
 
@@ -419,7 +438,7 @@ The server uses `@socket.io/redis-adapter` and `@socket.io/redis-emitter` for ho
 | `redisEmitter` | Powers `send()` for cross-instance message delivery |
 
 - **Initialized during `configure()`.** All three clients are created and awaited before the IO server starts.
-- **Lazy connect handled explicitly.** If the parent `redisConnection` uses `lazyConnect` (`autoConnect: false`), the duplicated clients are kicked into `connect()` explicitly, since duplicated clients inherit `lazyConnect` but never dial on their own.
+- **Lazy connect handled explicitly.** Duplicated clients inherit `lazyConnect` but never dial on their own. If the parent `redisConnection` uses `lazyConnect` (`autoConnect: false`), `configure()` kicks each duplicated client into `connect()` explicitly.
 
 ## Types Reference