npm package: @kaushverse/redis-core
Description: A secure, fail-fast Redis core SDK for Node.js with strict TLS enforcement and first-class TypeScript support.
Author: Kaushik
Latest version: 1.0.11

# 🚀 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

```bash
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)

```ts
import { createRedisClient } from "@kaushverse/redis-core";

// Use this for local / simple setups
// NOTE: Do NOT provide `url` when using host + port
const config = createRedisClient({
  host: "127.0.0.1",
  port: 6379,
});
```

---

### Option 2️⃣ URL Based Connection

```ts
// 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 config = createRedisClient({
  url: "redis://127.0.0.1:6379",
});
```

---

### Option 3️⃣ Strict TLS (Standalone)

```ts
const config = 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

```ts
const config = 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

```ts
import { withRedisHelpers, createRedisClient } from "@kaushverse/redis-core";

const redis = createRedisClient(config);
const cache = withRedisHelpers(redis);
```

---

### STRING Operations (via wrapper)

```ts
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:

```ts
import { setValue, getValue } from "@kaushverse/redis-core";

await setValue(redis, "name", "kaush");
const value = await getValue(redis, "name");
```

---

## 📁 Recommended Project Structure

```txt
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 🔥