power-redis/README.md

Production-grade Redis abstraction for Node.js with strict key formatting, safe JSON serialization, advanced list/queue operations, SCAN-based pattern tools, TTL helpers, batch UNLINK deletion, and Redis Streams support. Perfect for high-load microservice

# power-redis

## A safe, high-performance, multifunctional, and extensible Redis abstraction for Node.js.

It provides a set of advanced Redis operations that are not available in standard clients, including consistent key-formatting utilities, safe serialization, bulk operations, and more.

This library is built with a focus on stability, clarity, and real-world application needs, making Redis usage more maintainable and convenient in large distributed systems.

<p align="center">
  <img src="https://img.shields.io/badge/nodejs-queue-green?logo=node.js" />
  <img src="https://img.shields.io/badge/typescript-ready-blue?logo=typescript" />
  <img src="https://img.shields.io/badge/license-MIT-lightgrey" />
  <img src="https://img.shields.io/badge/status-production-success" />
</p>

## 📚 Documentation

Full documentation is available here:  
👉 **https://power-redis.docs.ihor.bielchenko.com**

## 📦 Installation

```bash
npm install power-redis
```

or

```bash
yarn add power-redis
```

## 🧪 Basic usage

```ts
import { PowerRedis } from 'power-redis';
import Redis from 'ioredis';

class MyRedis extends PowerRedis {
	public redis = new Redis({ host: '127.0.0.1', port: 6379 });
}

const redis = new MyRedis();

(async () => {
	await redis.setMany([
		{ 
			key: 'key1', 
			value: 'value 1' 
		},
		{ 
			key: 'key2', 
			value: 'value 2' 
		}
	], 3600);

	const keys = await redis.keys('key_prefix:1:*');    // [ "key_prefix:1:key1", "key_prefix:1:key2" ]
	const data = await redis.getMany('key_prefix:1:*'); // [{ key1: "value 1" }, { key2: "value 2" }]
})();
```

## 🚀 Key Features & Advantages

### ✔ Strict and Predictable Key Formatting
**power-redis** enforces a consistent, error‑free key style:
- Disallows invalid characters, spaces, forbidden segments, and empty sections
- Prevents accidental wildcard collisions
- Ensures uniform key naming across services

This dramatically reduces debugging time in multi‑team and multi‑service environments.

### ✔ Safe and Reliable Payload Serialization
Built‑in helpers (`toPayload`, `fromPayload`) handle:
- JSON objects
- Arrays
- Numeric and boolean primitives
- String boolean formats (`"yes"`, `"no"`, `"true"`, `"false"`)
- Empty strings
- Graceful fallbacks

This prevents the classic `[object Object]` and malformed JSON issues.

### ✔ High‑Level List Operations (Queues, Buffers, Streams)
Includes utilities not found in basic Redis clients:

- **lpopCountCompat** - a safe polyfill for `LPOP key count`
- **getListIterator** - async chunk‑based iteration over large lists
- **pushOne / pushMany** - with optional TTL support
- **getList(remove=true/false)** - consumption or read‑only mode

These features are ideal for queueing, batch processing, schedulers, and background jobs.

### ✔ SCAN‑Based Pattern Tools (Safe Alternative to KEYS)
**power-redis** offers efficient mass‑operations without blocking Redis:

- `keys(pattern, limit, scanSize)` - safe pattern scanning
- `getMany(pattern)` - batch MGET with chunking
- `dropMany(pattern)` - deletion via `SCAN + UNLINK`

Usage of `UNLINK` improves performance for large keysets.

### ✔ Connection Safety Built In
`checkConnection()` ensures Redis is ready before any command is executed.

Environment variable `REDIS_STRICT_CHECK_CONNECTION` enables strict or soft connection modes.

### ✔ TTL Helpers & Semi‑Atomic Behaviors
- `setOne` / `setMany` - automatic TTL support
- `pushOne` / `pushMany` - TTL for lists
- `incr(key, ttl)` - counter with TTL reset

These are extremely useful for rate‑limiters, counters, and expiring caches.

### ✔ Redis Streams Support
Convenience wrappers for:
- `XGROUP`
- `XREADGROUP`
- `SCRIPT LOAD`

Works well alongside queue systems or event pipelines.

## 🧱 Why Not Use Raw ioredis/node‑redis?

Typical Redis clients only expose low‑level commands.
Real‑world applications quickly accumulate duplicated logic, such as:

- inconsistent key naming
- unsafe SCAN/KEYS usage
- repeated JSON encode/decode
- list pagination boilerplate
- TTL handling logic
- mismatched connection state checks

**power-redis** solves these problems with a clean, unified API layer that keeps your microservices consistent and safe.

## 🏗️ Ideal Use Cases

- Node.js / TypeScript microservice ecosystems
- Distributed architectures
- High‑volume Redis workloads
- Queueing and background processing
- Monitoring, tracking, real‑time data pipelines
- Systems requiring predictable Redis key structure

## 📜 License  
MIT - free for commercial and private use.