@jgamaraalv/ts-dev-kit 1.0.0

package/skills/ioredis/references/advanced-patterns.md

@@ -0,0 +1,312 @@
+# ioredis Advanced Patterns Reference
+
+## Table of Contents
+
+- [Streams (XADD/XREAD)](#streams)
+- [Auto-pipelining](#auto-pipelining)
+- [Lua scripting details](#lua-scripting-details)
+- [Argument and reply transformers](#argument-and-reply-transformers)
+- [Binary data](#binary-data)
+- [Key prefixing](#key-prefixing)
+- [Monitor mode](#monitor-mode)
+- [Error handling](#error-handling)
+- [Debugging](#debugging)
+
+## Streams
+
+Redis Streams (v5+) for event streaming and log-like data:
+
+```ts
+// Producer:
+await redis.xadd("mystream", "*", "field1", "value1", "field2", "value2");
+
+// Consumer (blocking read):
+async function listenForMessage(lastId = "$") {
+  const results = await redis.xread("BLOCK", 0, "STREAMS", "mystream", lastId);
+  const [key, messages] = results[0];
+  // messages: Array<[id, [field1, value1, field2, value2]]>
+
+  for (const [id, fields] of messages) {
+    console.log("Id:", id, "Data:", fields);
+  }
+
+  // Continue from the last received ID:
+  const lastMsg = messages[messages.length - 1];
+  await listenForMessage(lastMsg[0]);
+}
+
+listenForMessage();
+```
+
+Consumer groups:
+
+```ts
+// Create group:
+await redis.xgroup("CREATE", "mystream", "mygroup", "0", "MKSTREAM");
+
+// Read as consumer:
+const results = await redis.xreadgroup(
+  "GROUP",
+  "mygroup",
+  "consumer1",
+  "COUNT",
+  10,
+  "BLOCK",
+  5000,
+  "STREAMS",
+  "mystream",
+  ">",
+);
+
+// Acknowledge:
+await redis.xack("mystream", "mygroup", messageId);
+```
+
+## Auto-pipelining
+
+Automatically batches all commands issued in the same event loop tick into a single pipeline:
+
+```ts
+const redis = new Redis({ enableAutoPipelining: true });
+
+// These three commands from the same tick are sent as one pipeline:
+const [a, b, c] = await Promise.all([redis.get("key1"), redis.get("key2"), redis.get("key3")]);
+```
+
+Performance: 35-50% throughput improvement in benchmarks.
+
+In Cluster mode, one pipeline per node is created. Commands are routed by slot.
+
+Exclude specific commands from auto-pipelining:
+
+```ts
+const redis = new Redis({
+  enableAutoPipelining: true,
+  autoPipeliningIgnoredCommands: ["subscribe", "unsubscribe"],
+});
+```
+
+## Lua scripting details
+
+### defineCommand
+
+```ts
+redis.defineCommand("mycommand", {
+  numberOfKeys: 2,
+  lua: `
+    local key1 = KEYS[1]
+    local key2 = KEYS[2]
+    local arg1 = ARGV[1]
+    return redis.call('SET', key1, arg1)
+  `,
+});
+
+// Use:
+await redis.mycommand("k1", "k2", "value");
+
+// Buffer variant is auto-created:
+await redis.mycommandBuffer("k1", "k2", "value");
+
+// Works with pipeline:
+await redis.pipeline().mycommand("k1", "k2", "value").exec();
+```
+
+### Dynamic key count
+
+Omit `numberOfKeys` and pass it as the first argument each time:
+
+```ts
+redis.defineCommand("dynamicScript", {
+  lua: "return {KEYS[1], ARGV[1]}",
+});
+
+await redis.dynamicScript(1, "mykey", "myarg"); // 1 = numberOfKeys
+```
+
+### Constructor option
+
+```ts
+const redis = new Redis({
+  scripts: {
+    mycommand: {
+      numberOfKeys: 2,
+      lua: "return {KEYS[1],KEYS[2],ARGV[1]}",
+      readOnly: true, // Hint for Cluster read-write splitting
+    },
+  },
+});
+```
+
+ioredis uses EVALSHA internally and falls back to EVAL only when the script is not cached.
+
+### TypeScript typing
+
+For TypeScript projects, declare custom commands on the Redis interface:
+
+```ts
+declare module "ioredis" {
+  interface RedisCommander<Context> {
+    mycommand(key1: string, key2: string, arg1: string): Result<string, Context>;
+  }
+}
+```
+
+## Argument and reply transformers
+
+Transform command arguments or replies globally:
+
+```ts
+import { Redis } from "ioredis";
+
+// Built-in: hmset accepts objects:
+await redis.hmset("hash", { field1: "val1", field2: "val2" });
+// Equivalent to: HMSET hash field1 val1 field2 val2
+
+// Built-in: hgetall returns object:
+const hash = await redis.hgetall("hash");
+// { field1: "val1", field2: "val2" }
+
+// Built-in: mset accepts objects:
+await redis.mset({ k1: "v1", k2: "v2" });
+
+// Custom argument transformer:
+Redis.Command.setArgumentTransformer("hmset", (args) => {
+  if (args.length === 2 && typeof args[1] === "object") {
+    const flat = [];
+    for (const [k, v] of Object.entries(args[1])) {
+      flat.push(k, v);
+    }
+    return [args[0], ...flat];
+  }
+  return args;
+});
+
+// Custom reply transformer:
+Redis.Command.setReplyTransformer("hgetall", (result) => {
+  if (Array.isArray(result)) {
+    const obj: Record<string, string> = {};
+    for (let i = 0; i < result.length; i += 2) {
+      obj[result[i]] = result[i + 1];
+    }
+    return obj;
+  }
+  return result;
+});
+```
+
+## Binary data
+
+Send binary data with Buffers:
+
+```ts
+await redis.set("binary", Buffer.from([0x62, 0x75, 0x66]));
+
+// Use Buffer variant to receive binary:
+const buf = await redis.getBuffer("binary");
+// buf: <Buffer 62 75 66>
+
+// Every bulk-string command has a Buffer variant:
+// getBuffer, hgetallBuffer, lrangeBuffer, etc.
+
+// You don't need setBuffer — regular set() accepts Buffers:
+await redis.set("key", Buffer.from("hello"));
+```
+
+## Key prefixing
+
+Auto-prefix all keys transparently:
+
+```ts
+const redis = new Redis({ keyPrefix: "app:" });
+
+await redis.set("user:1", "Alice");
+// Actually sends: SET app:user:1 Alice
+
+await redis.get("user:1");
+// Actually sends: GET app:user:1
+
+// Works with pipeline and custom commands:
+redis
+  .pipeline()
+  .set("k1", "v1") // SET app:k1 v1
+  .get("k1") // GET app:k1
+  .exec();
+```
+
+**Limitation**: Does not apply to pattern-based commands like `KEYS`, `SCAN`, or to reply values that happen to be key names.
+
+## Monitor mode
+
+See all commands received by the server across all clients:
+
+```ts
+const monitor = await redis.monitor();
+
+monitor.on("monitor", (time, args, source, database) => {
+  // time: Unix timestamp from Redis
+  // args: command arguments array
+  // source: client address
+  // database: database number
+  console.log(time, args.join(" "), "from", source);
+});
+
+// When done:
+monitor.disconnect();
+```
+
+A monitor connection cannot run other commands.
+
+## Error handling
+
+All Redis server errors are `ReplyError` instances:
+
+```ts
+import { Redis } from "ioredis";
+
+try {
+  await redis.set("foo"); // wrong number of args
+} catch (err) {
+  if (err instanceof Redis.ReplyError) {
+    console.log(err.message); // "ERR wrong number of arguments for 'set' command"
+  }
+}
+```
+
+### Friendly error stacks (dev only)
+
+```ts
+// Default stack: internal ioredis frames (useless for debugging)
+// Friendly stack: points to your code
+
+const redis = new Redis({ showFriendlyErrorStack: true });
+// NEVER use in production — significant performance overhead
+```
+
+### Pipeline error handling
+
+`pipeline.exec()` never rejects. Each command's result is `[error, value]`:
+
+```ts
+const results = await redis.pipeline().set("foo", "bar").get("nonexistent").exec();
+
+// results[0] = [null, "OK"]     — success
+// results[1] = [null, null]     — key doesn't exist (not an error)
+
+// If a command fails:
+// results[N] = [ReplyError, undefined]
+```
+
+## Debugging
+
+Enable debug logging via the DEBUG environment variable:
+
+```bash
+DEBUG=ioredis:* node app.js
+```
+
+Prefix patterns:
+
+- `ioredis:*` — all logs
+- `ioredis:redis` — connection/command logs
+- `ioredis:cluster` — cluster-specific logs
+- `ioredis:sentinel` — sentinel-specific logs

package/skills/ioredis/references/cluster-sentinel.md

@@ -0,0 +1,280 @@
+# ioredis Cluster & Sentinel Reference
+
+## Table of Contents
+
+- [Redis Cluster](#redis-cluster)
+- [ClusterOptions](#clusteroptions)
+- [Read-write splitting](#read-write-splitting)
+- [NAT mapping](#nat-mapping)
+- [Pipeline & transaction in Cluster](#pipeline--transaction-in-cluster)
+- [Pub/Sub in Cluster](#pubsub-in-cluster)
+- [Cluster events](#cluster-events)
+- [Cluster password](#cluster-password)
+- [AWS ElastiCache with TLS](#aws-elasticache-with-tls)
+- [Sentinel](#sentinel)
+- [SentinelConnectionOptions](#sentinelconnectionoptions)
+- [Sentinel failover](#sentinel-failover)
+
+> **Terminology note:** ioredis uses `slave` in its API (e.g., `scaleReads: "slave"`, `role: "slave"`, `preferredSlaves`); Redis 5.0+ documentation uses `replica` instead.
+
+## Redis Cluster
+
+```ts
+import { Cluster } from "ioredis";
+
+const cluster = new Cluster([
+  { host: "127.0.0.1", port: 6380 },
+  { host: "127.0.0.1", port: 6381 },
+]);
+
+await cluster.set("foo", "bar");
+const val = await cluster.get("foo"); // "bar"
+```
+
+First argument: startup nodes (not all nodes needed — ioredis auto-discovers the rest).
+
+## ClusterOptions
+
+Second argument to `new Cluster(nodes, options)`:
+
+| Option                    | Type                                       | Default                        | Description                                                                    |
+| ------------------------- | ------------------------------------------ | ------------------------------ | ------------------------------------------------------------------------------ |
+| `clusterRetryStrategy`    | `(times) => number \| void`                | backoff 100+times\*2, max 2000 | Delay before reconnecting when no startup nodes reachable. Return void to stop |
+| `scaleReads`              | `"master" \| "slave" \| "all" \| Function` | `"master"`                     | Where to route read queries                                                    |
+| `enableOfflineQueue`      | `boolean`                                  | `true`                         | Queue commands before ready                                                    |
+| `enableReadyCheck`        | `boolean`                                  | `true`                         | Wait for CLUSTER INFO ready                                                    |
+| `maxRedirections`         | `number`                                   | `16`                           | Max MOVED/ASK redirections per command                                         |
+| `retryDelayOnFailover`    | `number`                                   | `100`                          | Ms delay when target node disconnected                                         |
+| `retryDelayOnClusterDown` | `number`                                   | `100`                          | Ms delay on CLUSTERDOWN error                                                  |
+| `retryDelayOnTryAgain`    | `number`                                   | `100`                          | Ms delay on TRYAGAIN error                                                     |
+| `retryDelayOnMoved`       | `number`                                   | `0`                            | Ms delay on MOVED error                                                        |
+| `slotsRefreshTimeout`     | `number`                                   | `1000`                         | Ms timeout for slot refresh                                                    |
+| `slotsRefreshInterval`    | `number`                                   | disabled                       | Ms between automatic slot refreshes                                            |
+| `redisOptions`            | `RedisOptions`                             | `{}`                           | Default options for each node connection                                       |
+| `dnsLookup`               | `Function`                                 | `dns.lookup`                   | Custom DNS resolution                                                          |
+| `natMap`                  | `object \| Function`                       | `undefined`                    | NAT address translation                                                        |
+| `shardedSubscribers`      | `boolean`                                  | `false`                        | Enable sharded Pub/Sub connections                                             |
+
+### clusterRetryStrategy
+
+```ts
+// Default:
+clusterRetryStrategy(times) {
+  return Math.min(100 + times * 2, 2000);
+}
+
+// Switch startup nodes on failure:
+clusterRetryStrategy(times) {
+  this.startupNodes = [{ port: 6790, host: "127.0.0.1" }];
+  return Math.min(100 + times * 2, 2000);
+}
+```
+
+## Read-write splitting
+
+```ts
+const cluster = new Cluster(nodes, { scaleReads: "slave" });
+cluster.set("foo", "bar"); // -> master
+cluster.get("foo"); // -> random slave (may lag behind master)
+```
+
+`scaleReads` values:
+
+- `"master"` (default) — all queries to master
+- `"slave"` — writes to master, reads to slaves
+- `"all"` — writes to master, reads to master or slaves randomly
+- `function(nodes, command)` — custom routing. First node is always master. Return single node or array (random pick)
+
+## NAT mapping
+
+For clusters behind NAT (Docker, AWS VPC):
+
+```ts
+// Object mapping:
+const cluster = new Cluster([{ host: "203.0.113.73", port: 30001 }], {
+  natMap: {
+    "10.0.1.230:30001": { host: "203.0.113.73", port: 30001 },
+    "10.0.1.231:30001": { host: "203.0.113.73", port: 30002 },
+  },
+});
+
+// Function mapping:
+const cluster = new Cluster([{ host: "203.0.113.73", port: 30001 }], {
+  natMap: (key) => {
+    if (key.includes("30001")) return { host: "203.0.113.73", port: 30001 };
+    return null;
+  },
+});
+```
+
+## Pipeline & transaction in Cluster
+
+**Constraint**: All keys in a pipeline must hash to slots on the same node.
+
+```ts
+// Works — same slot via hash tags:
+cluster.pipeline().set("{user:1}:name", "Alice").set("{user:1}:email", "alice@example.com").exec();
+
+// multi() without pipeline is NOT supported in Cluster:
+// cluster.multi({ pipeline: false }) — throws error
+```
+
+Auto-resend: If all commands get the same MOVED/ASK error and all successful commands were read-only, ioredis automatically resends the entire pipeline to the correct node.
+
+## Pub/Sub in Cluster
+
+Works the same as standalone. One node is subscribed; messages are broadcast cluster-wide.
+
+```ts
+const pub = new Cluster(nodes);
+const sub = new Cluster(nodes);
+
+sub.on("message", (channel, message) => console.log(channel, message));
+await sub.subscribe("news");
+pub.publish("news", "hello");
+```
+
+### Sharded Pub/Sub (Redis >= 7)
+
+Enable `shardedSubscribers: true`. All channels in one `ssubscribe` call must hash to the same slot.
+
+```ts
+const cluster = new Cluster(nodes, { shardedSubscribers: true });
+
+cluster.on("smessage", (channel, message) => console.log(message));
+await cluster.ssubscribe("channel{my}:1", "channel{my}:2");
+cluster.spublish("channel{my}:1", "test message");
+```
+
+## Cluster events
+
+| Event          | Description                                              |
+| -------------- | -------------------------------------------------------- |
+| `connect`      | Connection established                                   |
+| `ready`        | Cluster ready (after CLUSTER INFO if `enableReadyCheck`) |
+| `error`        | Error with `lastNodeError` property                      |
+| `close`        | Connection closed                                        |
+| `reconnecting` | Reconnecting, arg = delay ms                             |
+| `end`          | No more reconnections                                    |
+| `+node`        | New node connected                                       |
+| `-node`        | Node disconnected                                        |
+| `node error`   | Error connecting to node (2nd arg = address)             |
+
+## Cluster password
+
+```ts
+// Same password for all nodes:
+const cluster = new Cluster(nodes, {
+  redisOptions: { password: "cluster-password" },
+});
+
+// Per-node passwords:
+const cluster = new Cluster(
+  [
+    { port: 30001, password: "pass-for-30001" },
+    { port: 30002, password: null }, // no password
+  ],
+  {
+    redisOptions: { password: "fallback-password" },
+  },
+);
+```
+
+## AWS ElastiCache with TLS
+
+```ts
+const cluster = new Cluster(
+  [{ host: "clustercfg.myCluster.abcdefg.xyz.cache.amazonaws.com", port: 6379 }],
+  {
+    dnsLookup: (address, callback) => callback(null, address),
+    redisOptions: { tls: {} },
+  },
+);
+```
+
+The `dnsLookup` override prevents certificate validation errors with ElastiCache TLS.
+
+## Sentinel
+
+```ts
+import { Redis } from "ioredis";
+
+const redis = new Redis({
+  sentinels: [
+    { host: "localhost", port: 26379 },
+    { host: "localhost", port: 26380 },
+  ],
+  name: "mymaster", // Master group name
+  // Optional:
+  sentinelPassword: "sentinel-pass",
+  sentinelUsername: "sentinel-user", // Redis >= 6
+  role: "master", // "master" (default) or "slave"
+  password: "redis-pass", // Password for the actual Redis instance
+});
+```
+
+ioredis guarantees:
+
+- Always connects to the current master (even after failover)
+- Commands during failover are queued and run on the new master
+- If `role: "slave"`, always connects to a slave; reconnects to another slave if promoted
+
+### preferredSlaves
+
+```ts
+// Array format (lower prio = higher priority):
+const redis = new Redis({
+  sentinels: [...],
+  name: "mymaster",
+  role: "slave",
+  preferredSlaves: [
+    { ip: "127.0.0.1", port: "31231", prio: 1 },
+    { ip: "127.0.0.1", port: "31232", prio: 2 },
+  ],
+});
+
+// Function format:
+const redis = new Redis({
+  sentinels: [...],
+  name: "mymaster",
+  role: "slave",
+  preferredSlaves(availableSlaves) {
+    return availableSlaves.find(s => s.port === "31234") || false;
+  },
+});
+```
+
+## SentinelConnectionOptions
+
+| Option                      | Type                        | Default               | Description                                 |
+| --------------------------- | --------------------------- | --------------------- | ------------------------------------------- |
+| `sentinels`                 | `Array<{ host?, port? }>`   | required              | List of sentinel nodes                      |
+| `name`                      | `string`                    | required              | Master group name                           |
+| `role`                      | `"master" \| "slave"`       | `"master"`            | Connect to master or slave                  |
+| `sentinelPassword`          | `string`                    | `undefined`           | Password for sentinel instances             |
+| `sentinelUsername`          | `string`                    | `undefined`           | Username for sentinel (Redis >= 6)          |
+| `sentinelRetryStrategy`     | `(times) => number \| void` | `min(times*10, 1000)` | Retry when all sentinels unreachable        |
+| `sentinelReconnectStrategy` | `(times) => number \| void` | —                     | Reconnect strategy for sentinel connections |
+| `preferredSlaves`           | `Array \| Function`         | `undefined`           | Slave selection preference                  |
+| `enableTLSForSentinelMode`  | `boolean`                   | `false`               | TLS for sentinel connections                |
+| `sentinelTLS`               | `tls.ConnectionOptions`     | `undefined`           | TLS options for sentinel                    |
+| `tls`                       | `tls.ConnectionOptions`     | `undefined`           | TLS for Redis connection                    |
+| `updateSentinels`           | `boolean`                   | `true`                | Auto-update sentinel list                   |
+| `failoverDetector`          | `boolean`                   | `false`               | Detect failover proactively                 |
+| `natMap`                    | `object \| Function`        | `undefined`           | NAT mapping                                 |
+| `sentinelMaxConnections`    | `number`                    | `10`                  | Max sentinel connections                    |
+| `sentinelCommandTimeout`    | `number`                    | `undefined`           | Timeout for sentinel commands               |
+| `connectTimeout`            | `number`                    | `undefined`           | Connect timeout for sentinel                |
+| `disconnectTimeout`         | `number`                    | `undefined`           | Disconnect timeout                          |
+
+## Sentinel failover
+
+Default `sentinelRetryStrategy`:
+
+```ts
+sentinelRetryStrategy(times) {
+  return Math.min(times * 10, 1000);
+}
+```
+
+When all sentinels are unreachable, this controls the delay before retrying from scratch. Return `undefined` to stop.