🚀 Redis Core Client

A strict, production‑ready Redis client SDK built on top of ioredis, designed with:

• ✅ Standalone Redis & Redis Cluster support
• 🔐 Strict TLS (fail‑fast, no silent downgrade)
• 🧠 Clear separation of infra vs helpers
• ✨ Optional DX helpers wrapper with full autocomplete

This package is for backend developers who want Redis to be explicit, safe, and predictable — not magical.

📦 Installation

npm install @kaushverse/redis-core

⚠️ ioredis is a peer dependency and must be installed by the consumer.

🔧 Creating a Redis Client

Option 1️⃣ Host + Port (Standalone)

import { createRedisClient } from "@kaushverse/redis-core";

// Use this for local / simple setups
// NOTE: Do NOT provide `url` when using host + port
const redis = createRedisClient({
  host: "127.0.0.1",
  port: 6379,
});

Option 2️⃣ URL Based Connection

// Use this when you already have a Redis URL
// NOTE:
// - Do NOT provide host / port when using url
// - redis://  → non‑TLS
// - rediss:// → TLS (must match `tls: true`)

const redis = createRedisClient({
  url: "redis://127.0.0.1:6379",
});

Option 3️⃣ Strict TLS (Standalone)

const redis = createRedisClient({
  host: "redis.example.com",
  port: 6379,
  password: "secret",
  tls: true,
});

🔐 TLS Rules:

• tls: true → TLS is mandatory
• Invalid / missing cert → app crashes
• ❌ No fallback to non‑TLS
• ❌ No silent downgrade

Option 4️⃣ Redis Cluster

const redis = createRedisClient({
  nodes: [
    { host: "10.0.0.1", port: 6379 },
    { host: "10.0.0.2", port: 6379 },
  ],
  password: "secret",
  tls: true,
});

Cluster mode is auto‑detected via the nodes property.

🔔 Connection Events

The client automatically logs lifecycle events:

• connect → Socket connected
• ready → Redis ready
• close → Connection closed
• error → Redis / TLS error

TLS‑related errors are fatal when tls: true is enabled.

✨ Developer‑Friendly Helpers (Recommended)

Instead of calling helpers like getValue(redis, key) everywhere, wrap the client once for clean DX + autocomplete.

Create Helper Wrapper

import { withRedisHelpers } from "@kaushverse/redis-core";

const redis = createRedisClient(config);
const cache = withRedisHelpers(redis);

STRING Operations (via wrapper)

await cache.setValue("user:1", "kaush", 60);
await cache.getValue("user:1");

await cache.incrValue("counter");
await cache.appendValue("log", "entry");
await cache.mgetValue(["a", "b"]);

All helpers are typed, auto‑suggested, and work with:

• Standalone Redis
• Redis Cluster
• TLS / non‑TLS

🧵 Raw Helper Imports (Optional)

If you prefer functional style:

import { setValue, getValue } from "@kaushverse/redis-core";

await setValue(redis, "name", "kaush");
const value = await getValue(redis, "name");

📁 Recommended Project Structure

myapp/
 ├─ config/
 │   └─ redis.ts      # redis-core usage
 ├─ services/
 │   └─ user.service.ts
 └─ index.ts

✅ When to Use This Package

• Backend APIs
• Microservices
• Distributed locks
• Feature flags
• Caching layers

🏁 Final Notes

This package treats Redis as infrastructure, not magic.

If Redis is misconfigured — your app should know immediately.

Happy hacking 🔥