@venizia/ignis-docs 0.2.0 → 0.2.1-0

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

@@ -1,59 +1,16 @@
-# Redis
-
-The Redis helper module provides a unified data API across three deployment topologies - single node, cluster, and Sentinel - via the `AbstractRedisHelper` base class. All three implement the same `IRedisHelper` interface, so a consumer written against `IRedisHelper` works with any topology and can be switched without changing application code.
-
-Backed by **ioredis** under the hood.
-
-## 1. Overview
-
-### When to use which topology
-
-| Topology | Class | Use when |
-|----------|-------|----------|
-| **Single** | `RedisSingleHelper` | One Redis node - development, simple production setups |
-| **Cluster** | `RedisClusterHelper` | Sharded data across multiple nodes - horizontal scale or large datasets |
-| **Sentinel** | `RedisSentinelHelper` | One logical master + replicas with automatic failover - high availability |
-
-All three share the full data API defined in `IRedisHelper` (`get`, `set`, `hSet`, `publish`, etc.). Only the constructor options differ.
-
-## 2. Class and Interface Model
-
-### Class hierarchy
-
-| Class | Extends | Notes |
-|-------|---------|-------|
-| `AbstractRedisHelper` | `BaseHelper` | Base class; implements `IRedisHelper`; never constructed directly |
-| `RedisSingleHelper` | `AbstractRedisHelper` | ioredis `Redis` client; returns `Redis` from `getClient()` |
-| `RedisClusterHelper` | `AbstractRedisHelper` | ioredis `Cluster` client; returns `Cluster` from `getClient()` |
-| `RedisSentinelHelper` | `AbstractRedisHelper` | ioredis `Redis` client (Sentinel mode); returns `Redis` from `getClient()` |
-
-> **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.
-
-### TRedisClient
-
-```typescript
-type TRedisClient = Redis | Cluster; // ioredis
-```
-
-`RedisSingleHelper` and `RedisSentinelHelper` return a `Redis` instance. `RedisClusterHelper` returns a `Cluster` instance. Both satisfy `TRedisClient`.
+---
+title: Redis
+description: A single data API - get/set, hashes, sets, lists, pub/sub, RedisJSON - across single-node, cluster, and Sentinel topologies
+difficulty: intermediate
+---
 
-### IRedisHelper and its nine capability interfaces
+# Redis
 
-`IRedisHelper` extends all nine of the following:
+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.
 
-| Interface | Responsibility |
-|-----------|----------------|
-| `IRedisConnection` | Connection lifecycle - `connect`, `disconnect`, `ping`, `getClient`, `duplicateClient` |
-| `IRedisKey` | Key TTL and counters - `exists`, `expire`, `expireAt`, `ttl`, `persist`, `incr`/`decr` variants |
-| `IRedisKeyValue` | String key-value - `get`, `set`, `del`, `keys`, `getString(s)`, `getObject(s)`, `mSet`, `mGet` |
-| `IRedisHash` | Hash maps - `hSet`, `hGetAll`, `hGet`, `hDel`, `hExists`, `hKeys`, `hVals`, `hIncrBy`, `hLen` |
-| `IRedisSet` | Sets - `sAdd`, `sRem`, `sMembers`, `sIsMember`, `sCard` |
-| `IRedisList` | Lists - `lPush`, `rPush`, `lPop`, `rPop`, `lRange`, `lLen` |
-| `IRedisPubSub` | Pub/Sub with optional zlib compression - `publish`, `subscribe`, `unsubscribe` |
-| `IRedisJson` | RedisJSON module operations - `jSet`, `jGet`, `jDelete`, `jNumberIncreaseBy`, `jStringAppend`, `jPush`, `jPop` |
-| `IRedisCommand` | Raw escape hatch - `execute(command, params?)` |
+## In one example
 
-## 3. Construction - Single
+Construct a single-node helper and round-trip a value through it.
 
 ```typescript
 import { RedisSingleHelper } from '@venizia/ignis-helpers';
@@ -63,284 +20,46 @@ const redis = new RedisSingleHelper({
   host: 'localhost',
   port: 6379,
   password: 'secret',
-  database: 0,
-  autoConnect: true,
-  maxRetry: 5,
-
-  onInitialized: ({ name, helper }) => {
-    console.log(`[${name}] initialized`);
-  },
-  onConnected: ({ name }) => {
-    console.log(`[${name}] connected`);
-  },
-  onReady: ({ name }) => {
-    console.log(`[${name}] ready`);
-  },
-  onError: ({ name, error }) => {
-    console.error(`[${name}] error`, error);
-  },
 });
-```
 
-### IRedisSingleHelperOptions
+await redis.set({ key: 'session:42', value: { userId: 42, active: true } });
 
-Combines `IRedisSingleHelperProps` and `IRedisHelperCallbacks`.
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `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 |
-| `password` | `string` | Yes | - | Redis `requirepass` value |
-| `user` | `string` | No | - | Redis username (ACL authentication) |
-| `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 |
-| `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 |
-| `onError` | `(opts: { name: string; helper: IRedisHelper; error: unknown }) => void` | No | - | Fired on connection or command errors |
-
-### Retry strategy
-
-Backoff formula: `Math.max(Math.min(attempt * 2000, 5000), 1000)` - starting at 1 s, capped at 5 s. Reconnect stops when `attempt > maxRetry` (if `maxRetry > -1`). The framework always sets `maxRetriesPerRequest: null` internally, which is required for BullMQ compatibility.
-
-## 4. Construction - Cluster
-
-```typescript
-import { RedisClusterHelper } from '@venizia/ignis-helpers';
-
-const cluster = new RedisClusterHelper({
-  name: 'cache-cluster',
-  nodes: [
-    { host: 'redis-node-1', port: 7000 },
-    { host: 'redis-node-2', port: 7001 },
-    { host: 'redis-node-3', port: 7002 },
-  ],
-  clusterOptions: {
-    redisOptions: { password: 'cluster-password' },
-  },
-  onReady: ({ name }) => {
-    console.log(`[${name}] cluster ready`);
-  },
+const session = await redis.getObject<{ userId: number; active: boolean }>({
+  key: 'session:42',
 });
+console.log(session); // { userId: 42, active: true }
 ```
 
-### IRedisClusterHelperOptions
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `name` | `string` | Yes | - | Helper identifier |
-| `nodes` | `Array<{ host: string; port: string \| number; password?: string }>` | Yes | - | Startup nodes - ioredis discovers the rest |
-| `clusterOptions` | `ClusterOptions` | No | - | Passed verbatim to `new Cluster(nodes, clusterOptions)` |
-| `onInitialized` / `onConnected` / `onReady` / `onError` | callbacks | No | - | Same shape as single |
-
-> **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.
+`autoConnect` defaults to `true`, so the client starts connecting inside the constructor - no explicit `connect()` call needed for this example.
 
-`duplicateClient()` on a cluster creates a **new** `Cluster` instance from the same startup nodes and options (because ioredis `Cluster` does not implement `.duplicate()`).
+## How it works
 
-## 5. Construction - Sentinel
+- **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.
 
-### What Redis Sentinel is
+| Topology | Class | Fits |
+|----------|-------|------|
+| Single node | `RedisSingleHelper` | One Redis instance |
+| Cluster | `RedisClusterHelper` | Data sharded across nodes |
+| Sentinel | `RedisSentinelHelper` | Automatic failover for one logical master |
 
-Redis Sentinel is a high-availability (HA) architecture made of three process types:
+- **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`.
+- **Every method is camelCase.** `hSet`, `lPush`, `sAdd` - even where the underlying ioredis/Redis command is lowercase (`hset`, `lpush`, `sadd`). There is no lowercase alias.
 
-```
-  +------------------+      monitors      +--------------------+
-  |  Sentinel (1)    |<------------------>|  Master (primary)  |
-  +------------------+                    +--------------------+
-  +------------------+         replication        |
-  |  Sentinel (2)    |              +--------------+
-  +------------------+              v
-  +------------------+      +--------------------+
-  |  Sentinel (3)    |      |  Replica (standby) |
-  +------------------+      +--------------------+
-```
+## Common tasks
 
-- **Sentinels** form a quorum (typically 3 processes). They monitor the master, agree by majority vote when it is down, and promote a replica to master (failover).
-- **Master** accepts all writes.
-- **Replicas** replicate from master and serve reads when `role: 'slave'` is set.
-
-### Why your app connects to sentinels, not the master
-
-The master's address can change after a failover. Instead of hard-coding a master host, you give ioredis the sentinel addresses and the monitored master group name (`masterName`). ioredis asks a sentinel for the current master, connects to it, and re-queries sentinels automatically after a failover. **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.
-
-### Constructor
-
-```typescript
-import { RedisSentinelHelper } from '@venizia/ignis-helpers';
-
-const redis = new RedisSentinelHelper({
-  name: 'ha-cache',          // helper identifier (logging/scope)
-  masterName: 'mymaster',    // group name in sentinel.conf "sentinel monitor mymaster ..."
-  sentinels: [
-    { host: '10.0.0.1', port: 26379 },
-    { host: '10.0.0.2', port: 26379 },
-    { host: '10.0.0.3' },   // port defaults to 26379
-  ],
-  role: 'master',            // 'master' (default) or 'slave'
-  password: 'data-secret',   // master/replica requirepass
-  sentinelPassword: 'sentinel-secret', // sentinel.conf requirepass
-  database: 0,
-  autoConnect: true,
-  maxRetry: 5,
-});
-```
-
-### IRedisSentinelHelperOptions
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `name` | `string` | Yes | - | Helper identifier (logs, `IRedisHelper.name`) |
-| `masterName` | `string` | Yes | - | Sentinel-monitored master group name - maps to ioredis `name` |
-| `sentinels` | `Array<{ host: string; port?: string \| number }>` | Yes | - | Sentinel process addresses |
-| `role` | `TRedisSentinelRole` (`RedisSentinelRoles.MASTER \| SLAVE`) | No | `RedisSentinelRoles.MASTER` | Connect to master (writes) or a replica (reads) |
-| `password` | `string` | No | - | Data-node `requirepass` (master and replicas) |
-| `sentinelPassword` | `string` | No | - | Sentinel-process `requirepass` |
-| `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 |
-| `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 |
-
-### Field clarity - name vs masterName
-
-This is the most common source of confusion:
-
-| Field | What it is | Where it goes |
-|-------|-----------|---------------|
-| `name` | The helper's own identifier used for logging and `IRedisHelper.name` | `AbstractRedisHelper` identifier |
-| `masterName` | The master group being monitored by Sentinel processes, matching `sentinel monitor <name> ...` in sentinel.conf | Maps to ioredis `name` option |
-
-They are independent. You can name the helper `'ha-cache'` while `masterName` is `'mymaster'`.
-
-### 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.
-
-| # | From | To | App field | Server config |
-|---|------|----|-----------|---------------|
-| 1 | **App** | **Sentinel processes** | `sentinelPassword` | `requirepass` in sentinel.conf |
-| 2 | **App** | **Data nodes** (master/replica) | `password` | `requirepass` in redis.conf |
-| 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`.
-
-**Common cases:**
-- Private network, sentinels unauthenticated: set only `password`.
-- Fully secured cluster: set both `password` and `sentinelPassword`; configure relationships 3 and 4 on the servers.
-
-### Failover behavior
-
-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.
-5. **Your application code does not change.** The same `RedisSentinelHelper` instance continues to work after failover.
-
-### Local testing with Docker Compose
-
-The following Compose file starts a master, one replica, and one sentinel with full authentication. It demonstrates all four relationships.
-
-```yaml
-version: '3.8'
-
-services:
-  redis-master:
-    image: redis:7-alpine
-    command: redis-server --requirepass data-secret --masterauth data-secret
-    ports:
-      - '6379:6379'
-
-  redis-replica:
-    image: redis:7-alpine
-    command: >
-      redis-server
-      --requirepass data-secret
-      --masterauth data-secret
-      --replicaof redis-master 6379
-    depends_on:
-      - redis-master
-
-  redis-sentinel:
-    image: redis:7-alpine
-    command: >
-      sh -c "
-        echo 'sentinel monitor mymaster redis-master 6379 1' > /sentinel.conf &&
-        echo 'sentinel auth-pass mymaster data-secret' >> /sentinel.conf &&
-        echo 'sentinel down-after-milliseconds mymaster 3000' >> /sentinel.conf &&
-        echo 'sentinel failover-timeout mymaster 10000' >> /sentinel.conf &&
-        echo 'requirepass sentinel-secret' >> /sentinel.conf &&
-        redis-sentinel /sentinel.conf
-      "
-    ports:
-      - '26379:26379'
-    depends_on:
-      - redis-master
-      - redis-replica
-```
+### Pick a topology
 
-Connect and verify failover:
-
-```typescript
-import { RedisSentinelHelper } from '@venizia/ignis-helpers';
-
-const redis = new RedisSentinelHelper({
-  name: 'test',
-  masterName: 'mymaster',
-  sentinels: [{ host: 'localhost', port: 26379 }],
-  password: 'data-secret',
-  sentinelPassword: 'sentinel-secret',
-  onReady: ({ name }) => console.log(`[${name}] ready`),
-});
-
-await redis.set({ key: 'hello', value: 'world' });
-const val = await redis.get({ key: 'hello' });
-console.log(val); // "world"
-
-// Stop the master container - wait ~5 s - the replica is promoted.
-// The same redis instance will reconnect automatically and continue working.
-```
-
-## 6. Selecting a Topology - the Factory
-
-`createRedisHelper` is an overloaded factory that returns the concrete type when `mode` is a literal.
-
-```typescript
-import { createRedisHelper, RedisModes } from '@venizia/ignis-helpers';
-
-// Type inferred as RedisSingleHelper
-const single = createRedisHelper({
-  mode: RedisModes.SINGLE,
-  name: 'cache',
-  host: process.env.REDIS_HOST!,
-  port: Number(process.env.REDIS_PORT),
-  password: process.env.REDIS_PASSWORD!,
-});
-
-// Type inferred as RedisSentinelHelper
-const sentinel = createRedisHelper({
-  mode: RedisModes.SENTINEL,
-  name: 'cache-ha',
-  masterName: 'mymaster',
-  sentinels: [{ host: process.env.SENTINEL_HOST! }],
-  password: process.env.REDIS_PASSWORD!,
-});
-```
-
-Switch by environment:
+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';
 
-const mode = (process.env.REDIS_MODE ?? RedisModes.SINGLE) as typeof RedisModes.SINGLE;
-
 const redis: IRedisHelper = createRedisHelper({
-  mode,
+  mode: RedisModes.SINGLE, // or RedisModes.CLUSTER / RedisModes.SENTINEL
   name: 'app-cache',
   host: process.env.REDIS_HOST!,
   port: Number(process.env.REDIS_PORT),
@@ -348,366 +67,75 @@ const redis: IRedisHelper = createRedisHelper({
 });
 ```
 
-| `mode` value | Returns |
-|---|---|
-| `RedisModes.SINGLE` (`'single'`) | `RedisSingleHelper` |
-| `RedisModes.CLUSTER` (`'cluster'`) | `RedisClusterHelper` |
-| `RedisModes.SENTINEL` (`'sentinel'`) | `RedisSentinelHelper` |
-
-Unknown mode throws an `ApplicationError`.
-
-## 7. Lifecycle and Events
+See [Full reference](/extensions/helpers/redis/reference) for the cluster (`nodes`) and Sentinel (`sentinels`, `masterName`) constructor shapes.
 
-### autoConnect and manual connect
+### Cache a value with a TTL
 
-When `autoConnect: true` (default), the ioredis client starts connecting immediately in the constructor. When `autoConnect: false`, ioredis uses `lazyConnect` mode and you must call `connect()` explicitly before issuing commands.
+`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.
 
 ```typescript
-// Lazy connect
-const redis = new RedisSingleHelper({
-  name: 'cache',
-  host: 'localhost',
-  port: 6379,
-  password: 'secret',
-  autoConnect: false,
+await redis.set({
+  key: 'session:42',
+  value: { userId: 42 },
+  options: { expiresIn: 60_000 }, // 60 seconds
 });
 
-await redis.connect(); // resolves true when status === 'ready'
+const remaining = await redis.ttl({ key: 'session:42' }); // seconds; -1 = no expiry, -2 = missing
 ```
 
-### Connection methods
+### Publish and subscribe
 
-| Method | Behavior |
-|--------|----------|
-| `connect()` | Resolves `false` (no-op) if status is `ready`, `reconnecting`, or `connecting`; otherwise calls ioredis `connect()` and resolves `true` when status reaches `ready` |
-| `disconnect()` | Resolves `false` (no-op) if status is `end` or `close`; otherwise sends `QUIT` and resolves `true` on `'OK'` |
-| `ping()` | Sends `PING`; returns `'PONG'` |
-
-### The four lifecycle callbacks
-
-All helpers accept `IRedisHelperCallbacks`:
-
-| Callback | Fired when | ioredis event |
-|----------|-----------|---------------|
-| `onInitialized` | Synchronously at the end of the constructor | - |
-| `onConnected` | TCP connection is established | `connect` |
-| `onReady` | Client is ready to accept commands | `ready` |
-| `onError` | A connection or command error occurs | `error` |
-
-The client also logs a `WARN` internally on `reconnecting` events (not surfaced as a callback).
-
-### duplicateClient
+A subscribed ioredis connection cannot run regular commands, so use a second helper instance for subscribing and keep the first for data operations.
 
 ```typescript
-const dedicated = redis.duplicateClient();
-```
-
-Creates an **independent** ioredis connection from the same configuration. The duplicate starts disconnected - ioredis auto-connects it on first use. Use this whenever a consumer needs its own dedicated connection (Pub/Sub, BullMQ, Socket.IO adapters). For `RedisClusterHelper`, `duplicateClient()` constructs a new `Cluster` from the same startup nodes and options.
-
-## 8. Full Method Reference
-
-### General notes (apply to all families)
+const subscriber = new RedisSingleHelper({ name: 'sub', host: 'localhost', port: 6379, password: 'secret' });
 
-- **Empty-input no-ops:** Methods that accept an array (`keys`, `members`, `values`, `fields`, `payload`) return `0` or `[]` immediately when the array is empty, without calling ioredis. 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.
-
----
-
-### IRedisConnection - connection lifecycle
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `getClient` | `(): TRedisClient` | Returns the raw ioredis `Redis` or `Cluster` instance |
-| `duplicateClient` | `(): TRedisClient` | Creates an independent ioredis connection (same config, separate socket) |
-| `ping` | `(): Promise<string>` | Sends `PING`; returns `'PONG'` on success |
-| `connect` | `(): Promise<boolean>` | Connects the client; resolves `false` if already connected/connecting/ready |
-| `disconnect` | `(): Promise<boolean>` | Graceful `QUIT`; resolves `false` if already ended/closed |
-
----
-
-### IRedisKey - key lifecycle and counters
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `exists` | `(opts: { keys: string[] }): Promise<number>` | Returns the count of keys that exist; empty `keys` returns `0` without calling Redis |
-| `expire` | `(opts: { key: string; seconds: number }): Promise<boolean>` | Sets expiry in seconds; `true` if applied |
-| `expireAt` | `(opts: { key: string; atEpochSeconds: number }): Promise<boolean>` | Sets expiry at an epoch second timestamp; `true` if applied |
-| `ttl` | `(opts: { key: string }): Promise<number>` | Returns remaining TTL in seconds; `-1` = no expiry; `-2` = key missing |
-| `persist` | `(opts: { key: string }): Promise<boolean>` | Removes expiry; `true` if the timeout was removed |
-| `incr` | `(opts: { key: string }): Promise<number>` | Atomically increments integer at key by 1; returns new value |
-| `decr` | `(opts: { key: string }): Promise<number>` | Atomically decrements integer at key by 1; returns new value |
-| `incrBy` | `(opts: { key: string; value: number }): Promise<number>` | Atomically increments by `value`; returns new value |
-| `decrBy` | `(opts: { key: string; value: number }): Promise<number>` | Atomically decrements by `value`; returns new value |
-
----
-
-### IRedisKeyValue - string key-value
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `set<T>` | `(opts: { key: string; value: T; options?: { log?: boolean; expiresIn?: number } }): Promise<void>` | JSON-serializes `value` and writes it; `expiresIn` is in **milliseconds** (uses `PX`); `log: true` emits an info log |
-| `get<T>` | `(opts: { key: string; transform?: (input: string) => T }): Promise<T \| null>` | Returns raw string or applies `transform`; `null` if key missing |
-| `del` | `(opts: { keys: string[] }): Promise<number>` | Deletes one or more keys; empty `keys` returns `0` |
-| `keys` | `(opts: { key: string }): Promise<string[]>` | Runs Redis `KEYS` with a glob pattern; avoid on large keyspaces - prefer `SCAN` via `execute` |
-| `getString` | `(opts: { key: string }): Promise<string \| null>` | Alias for `get` without transform |
-| `getStrings` | `(opts: { keys: string[] }): Promise<(string \| null)[]>` | Alias for `mGet` without transform |
-| `getObject<T>` | `(opts: { key: string }): Promise<T \| null>` | `get` with `JSON.parse` transform |
-| `getObjects` | `(opts: { keys: string[] }): Promise<(unknown \| null)[]>` | `mGet` with `JSON.parse` transform |
-| `mSet<T>` | `(opts: { payload: Array<{ key: string; value: T }>; options?: { log?: boolean } }): Promise<void>` | Bulk write; each value is JSON-serialized; empty `payload` is a no-op |
-| `mGet<T>` | `(opts: { keys: string[]; transform?: (input: string) => T }): Promise<(T \| null)[]>` | Bulk read with optional transform; empty `keys` returns `[]` |
-
----
-
-### IRedisHash - hash maps
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `hSet<T>` | `(opts: { key: string; value: T; options?: { log?: boolean } }): Promise<number>` | Sets all fields in a hash object; returns number of **new** fields added |
-| `hGetAll` | `(opts: { key: string; transform?: <T, R>(input: T) => R }): Promise<unknown>` | Returns all fields and values of a hash; applies optional transform |
-| `hGet` | `(opts: { key: string; field: string }): Promise<string \| null>` | Returns the value of a single hash field |
-| `hDel` | `(opts: { key: string; fields: string[] }): Promise<number>` | Deletes one or more hash fields; empty `fields` returns `0` |
-| `hExists` | `(opts: { key: string; field: string }): Promise<boolean>` | `true` if the field exists in the hash |
-| `hKeys` | `(opts: { key: string }): Promise<string[]>` | Returns all field names in the hash |
-| `hVals` | `(opts: { key: string }): Promise<string[]>` | Returns all field values in the hash |
-| `hIncrBy` | `(opts: { key: string; field: string; value: number }): Promise<number>` | Atomically increments a numeric hash field; returns new value |
-| `hLen` | `(opts: { key: string }): Promise<number>` | Returns the number of fields in the hash |
-
----
-
-### IRedisSet - sets
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `sAdd` | `(opts: { key: string; members: Array<string \| number> }): Promise<number>` | Adds members to a set; returns count of new members; empty `members` returns `0` |
-| `sRem` | `(opts: { key: string; members: Array<string \| number> }): Promise<number>` | Removes members from a set; returns count removed; empty `members` returns `0` |
-| `sMembers` | `(opts: { key: string }): Promise<string[]>` | Returns all members of the set |
-| `sIsMember` | `(opts: { key: string; member: string \| number }): Promise<boolean>` | `true` if `member` belongs to the set |
-| `sCard` | `(opts: { key: string }): Promise<number>` | Returns the number of members in the set |
-
----
-
-### IRedisList - lists
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `lPush` | `(opts: { key: string; values: Array<string \| number> }): Promise<number>` | Prepends values to the list head; returns list length after push; empty `values` returns `0` |
-| `rPush` | `(opts: { key: string; values: Array<string \| number> }): Promise<number>` | Appends values to the list tail; returns list length after push; empty `values` returns `0` |
-| `lPop` | `(opts: { key: string }): Promise<string \| null>` | Removes and returns the head element; `null` if list is empty |
-| `rPop` | `(opts: { key: string }): Promise<string \| null>` | Removes and returns the tail element; `null` if list is empty |
-| `lRange` | `(opts: { key: string; start: number; stop: number }): Promise<string[]>` | Returns elements from `start` to `stop` (inclusive, 0-indexed, `-1` = last) |
-| `lLen` | `(opts: { key: string }): Promise<number>` | Returns the number of elements in the list |
-
----
-
-### IRedisPubSub - publish/subscribe
-
-| 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) |
-| `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 |
-
-> **Important:** A subscribed ioredis connection enters subscriber mode and cannot run regular commands. Use `duplicateClient()` to obtain a separate connection for pub/sub.
-
-```typescript
-// Correct pattern - separate connections for data and pub/sub
-const dataClient = new RedisSingleHelper({ name: 'data', host, port, password });
-const subClient = new RedisSingleHelper({ name: 'sub',  host, port, password });
-
-subClient.subscribe({ topic: 'events' });
-subClient.getClient().on('message', (channel, message) => {
-  const parsed = JSON.parse(message.toString());
-  console.log(channel, parsed);
-});
-
-await dataClient.set({ key: 'foo', value: 'bar' });
-```
-
----
-
-### IRedisJson - RedisJSON module
-
-Requires the [RedisJSON module](https://redis.io/docs/stack/json/) on the server.
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `jSet<T>` | `(opts: { key: string; path: string; value: T }): Promise<string \| null>` | Sets a JSON document at `path` (`JSON.SET`); value is `JSON.stringify`-ed |
-| `jGet<T>` | `(opts: { key: string; path?: string }): Promise<T \| null>` | Retrieves the document or sub-path (`JSON.GET`); `path` defaults to `'$'` |
-| `jDelete` | `(opts: { key: string; path?: string }): Promise<number>` | Deletes the document or sub-path (`JSON.DEL`); `path` defaults to `'$'`; returns count deleted |
-| `jNumberIncreaseBy` | `(opts: { key: string; path: string; value: number }): Promise<string \| null>` | Increments a numeric field by `value` (`JSON.NUMINCRBY`) |
-| `jStringAppend` | `(opts: { key: string; path: string; value: string }): Promise<number[] \| null>` | Appends `value` to a string field (`JSON.STRAPPEND`); returns new string lengths |
-| `jPush<T>` | `(opts: { key: string; path: string; value: T }): Promise<number[] \| null>` | Appends `value` to an array field (`JSON.ARRAPPEND`); value is `JSON.stringify`-ed; returns new array lengths |
-| `jPop<T>` | `(opts: { key: string; path: string }): Promise<T \| null>` | Pops the last element from an array field (`JSON.ARRPOP`) |
-
----
-
-### IRedisCommand - raw escape hatch
-
-| Method | Signature | Behavior |
-|--------|-----------|----------|
-| `execute<R>` | `(command: string, parameters?: Array<string \| number \| Buffer>): Promise<R>` | Calls any ioredis command directly via `client.call(command, parameters)` |
-
-```typescript
-// Use SCAN instead of KEYS on large keyspaces
-const [cursor, keys] = await redis.execute<[string, string[]]>(
-  'SCAN',
-  [0, 'MATCH', 'user:*', 'COUNT', 100],
-);
-
-// Fetch server info
-const info = await redis.execute<string>('INFO');
-```
-
-## 9. 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.
-
-### 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.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`.
-
-```typescript
-import { BullMQHelper } from '@venizia/ignis-helpers';
-import { RedisSingleHelper } from '@venizia/ignis-helpers';
-
-const redis = new RedisSingleHelper({ name: 'queue-redis', host, port, password });
-
-const queue = BullMQHelper.newInstance({
-  queueName: 'email',
-  role: 'queue',
-  redisConnection: redis,
+subscriber.subscribe({ topic: 'events' });
+subscriber.getClient().on('message', (channel, message) => {
+  console.log(channel, JSON.parse(message.toString()));
 });
-```
-
-### Socket.IO component (SocketIOServerHelper)
 
-The Socket.IO component resolves an `AbstractRedisHelper` from its Redis-connection binding key (value `@app/socket-io/redis-connection`). Internally `SocketIOServerHelper` calls `duplicateClient()` three times - once each for the pub channel, sub channel, and emitter adapter. Bind any topology (single/cluster/sentinel); the consumer code is identical:
-
-```typescript
-import { AbstractRedisHelper, RedisSentinelHelper } from '@venizia/ignis-helpers';
-
-// In your Application preConfigure:
-const redis = new RedisSentinelHelper({ name: 'socket-redis', masterName: 'mymaster', sentinels, password });
-this.bind<AbstractRedisHelper>({ key: '@app/socket-io/redis-connection' }).to(redis);
+await redis.publish({ topics: ['events'], payload: { type: 'user.created' } });
 ```
 
-See the Socket.IO component documentation for the full component registration and adapter setup.
+### Hashes, sets, and lists
 
-### WebSocket component (WebSocket server and emitter)
-
-The WebSocket component resolves an `AbstractRedisHelper` from its Redis-connection binding key (value `@app/websocket/redis-connection`). The `WebSocketServerHelper` calls `duplicateClient()` for its pub and sub connections; the WebSocket emitter calls `duplicateClient()` for its pub connection. Bind any topology:
+Same key convention, one method family per data structure.
 
 ```typescript
-import { AbstractRedisHelper, RedisClusterHelper } from '@venizia/ignis-helpers';
+await redis.hSet({ key: 'user:42', value: { name: 'Ada', role: 'admin' } });
+const role = await redis.hGet({ key: 'user:42', field: 'role' });
 
-const redis = new RedisClusterHelper({ name: 'ws-redis', nodes });
-this.bind<AbstractRedisHelper>({ key: '@app/websocket/redis-connection' }).to(redis);
+await redis.sAdd({ key: 'tags:42', members: ['vip', 'beta'] });
+await redis.lPush({ key: 'queue:emails', values: ['welcome@example.com'] });
 ```
 
-See the WebSocket component documentation for the full component registration.
-
-### Casbin authorization enforcer
+### Drop to a raw command
 
-The cached Casbin enforcer (`ICasbinEnforcerCachedRedis`) accepts `connection: IRedisHelper` inside its `options`. It calls the helper's direct methods - `get`, `set` (with `options.expiresIn`), and `del` - to read, write, and invalidate cached policy keys; it does not reach the raw client. Any topology works as the `connection`:
+`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).
 
 ```typescript
-import type { IRedisHelper } from '@venizia/ignis-helpers';
-
-// Shape of the cached-enforcer config (see the Authorization component docs for full setup):
-const cached = {
-  use: true,
-  driver: CasbinEnforcerCachedDrivers.REDIS,
-  options: {
-    connection: redis as IRedisHelper, // any RedisSingleHelper / RedisClusterHelper / RedisSentinelHelper
-    expiresIn: 300_000, // cached-policy TTL in milliseconds
-    keyFn: ({ user }) => `authz:policy:${user.id}`,
-  },
-};
-```
-
-### Binding into an application
-
-```typescript
-import { RedisSingleHelper } from '@venizia/ignis-helpers';
-import { BaseApplication } from '@venizia/ignis';
-
-class MyApp extends BaseApplication {
-  async preConfigure() {
-    const redis = new RedisSingleHelper({
-      name: 'cache',
-      host: process.env.REDIS_HOST!,
-      port: Number(process.env.REDIS_PORT),
-      password: process.env.REDIS_PASSWORD!,
-    });
-
-    // Bind so components and services can resolve it
-    this.bind<RedisSingleHelper>({ key: 'helpers.RedisCache' }).to(redis);
-  }
-}
+const [cursor, matched] = await redis.execute<[string, string[]]>('SCAN', [
+  0,
+  'MATCH',
+  'user:*',
+  'COUNT',
+  100,
+]);
 ```
 
-## 10. Production Notes
+## See also
 
-- **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.
-
-- **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.
-
-- **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
-
-```typescript
-import {
-  // Classes
-  AbstractRedisHelper,
-  RedisSingleHelper,
-  RedisClusterHelper,
-  RedisSentinelHelper,
-  // Factory
-  createRedisHelper,
-  RedisModes,
-  // Sentinel role const-class
-  RedisSentinelRoles,
-} from '@venizia/ignis-helpers';
-
-import type {
-  // Interface
-  IRedisHelper,
-  // Option types
-  IRedisSingleHelperOptions,
-  IRedisSingleHelperProps,
-  IRedisClusterHelperOptions,
-  IRedisClusterHelperProps,
-  IRedisSentinelHelperOptions,
-  IRedisSentinelHelperProps,
-  IRedisHelperCallbacks,
-  // Client + enum types
-  TRedisClient,
-  TRedisMode,
-  TRedisSentinelRole,
-} from '@venizia/ignis-helpers';
-```
+- [Full reference](/extensions/helpers/redis/reference) - every method group, topology option, and lifecycle event
+- [Queue Helper](/extensions/helpers/queue/) - `BullMQHelper` uses a Redis helper as its connection backend
+- [Socket.IO Component](/extensions/components/socket-io/) - resolves an `AbstractRedisHelper` and calls `duplicateClient()` for its pub/sub adapter
+- [Authorization Component](/extensions/components/authorization/) - the cached Casbin enforcer uses the helper's `get`/`set`/`del`
+- [Migrating to the new Redis Helper API](/guides/migrations/redis-helpers-migration) - renames and breaking changes from the pre-refactor API
 
-## See Also
+**Files:**
 
-- [Helpers Index](../index) - All available helpers
-- [Queue Helper](../queue/) - BullMQ uses the Redis helper as its connection backend
-- [Socket.IO Component](/extensions/components/socket-io/) - Uses `duplicateClient` for pub/sub adapter
-- [WebSocket Component](/extensions/components/websocket/) - Uses `duplicateClient` for pub/sub channels
-- [Authorization Component](/extensions/components/authorization/) - Casbin enforcer uses the helper's `del`/`get`/`set` for cache operations
-- [ioredis documentation](https://github.com/redis/ioredis) - Underlying Redis client
-- [Redis Sentinel documentation](https://redis.io/docs/management/sentinel/) - Sentinel architecture reference
-- [RedisJSON documentation](https://redis.io/docs/stack/json/) - Required for `j*` methods
+- [`packages/helpers/src/modules/redis/base/abstract.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/base/abstract.helper.ts) - `AbstractRedisHelper`, the shared data API
+- [`packages/helpers/src/modules/redis/single/single.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/single/single.helper.ts) - `RedisSingleHelper`
+- [`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) - `RedisClusterHelper`
+- [`packages/helpers/src/modules/redis/sentinel/sentinel.helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/sentinel/sentinel.helper.ts) - `RedisSentinelHelper`
+- [`packages/helpers/src/modules/redis/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/redis/factory.ts) - `createRedisHelper` factory