redis-plus

A lightweight, promise-based Redis adapter for Node.js applications.

redis-plus provides a simple cache abstraction, automatic JSON serialization, and a built-in health checker. It is designed to be lightweight, framework-independent, and easy to integrate into enterprise applications and microservices.

Features

• Modern Redis v4+ API
• Generic CachePort interface
• Automatic JSON serialization and deserialization
• Store strings or objects with the same API
• Redis health checker with configurable timeout
• Lightweight and dependency-free abstraction
• Easy to mock and unit test
• Suitable for microservices and enterprise applications

Installation

npm install redis-plus redis

Create a Redis Client

import { createClient } from "redis";

const client = createClient({
  url: "redis://localhost:6379"
});

await client.connect();

Using RedisAdapter

import { RedisAdapter } from "redis-plus";

interface User {
  id: string;
  name: string;
}

const cache = new RedisAdapter<User>(client);

await cache.put("user:1", {
  id: "1",
  name: "John"
}, 300);

const user = await cache.get("user:1");

console.log(user);

Objects are automatically serialized to JSON before storing and deserialized when retrieved.

Store Plain Strings

If you want to store plain strings without JSON serialization:

const cache = new RedisAdapter<string>(client, false);

await cache.put("message", "Hello Redis");

const message = await cache.get("message");

CachePort

Applications should depend on the cache abstraction instead of Redis directly.

export interface CachePort<K, V> {
  isEnabled(): boolean;

  put(key: K, value: V, expiresInSeconds?: number): Promise<boolean>;

  get(key: K): Promise<V>;

  getMany(keys: K[]): Promise<V[]>;

  containsKey(key: K): Promise<boolean>;

  expire(key: K, timeToLive: number): Promise<boolean>;

  remove(key: K): Promise<boolean>;

  clear(): Promise<boolean>;

  keys(): Promise<string[]>;

  count(): Promise<number>;

  size(): Promise<number>;
}

Business services only depend on CachePort.

class UserService {

  constructor(
    private readonly cache: CachePort<string, User>
  ) {}

}

This makes applications easier to test and allows Redis to be replaced with another cache implementation if needed.

Health Check

RedisChecker verifies that Redis is reachable and responds within the configured timeout.

import { RedisChecker } from "redis-plus";

const checker = new RedisChecker(client);

const result = await checker.check();

console.log(result);

Example output:

{
    status: "UP",
    connected: true,
    responseTime: 3
}

If Redis is unavailable:

{
    status: "DOWN",
    connected: false,
    responseTime: 4502,
    error: "Redis health check timeout after 4500 ms"
}

API

RedisAdapter

Method	Description
put()	Store a value
get()	Retrieve a value
getMany()	Retrieve multiple values
expire()	Update TTL
containsKey()	Check whether a key exists
remove()	Delete a key
clear()	Remove all keys
keys()	Get all keys
count()	Get the number of keys
size()	Alias of count()
isEnabled()	Check whether Redis is available

RedisChecker

Method	Description
check()	Execute a Redis health check
build()	Build the health response
name()	Return the service name

Architecture

  Application
       │
       ▼
 CachePort<K, V>
       │
       ▼
 RedisAdapter<V>
       │
       ▼
Redis Client (v4)
       │
       ▼
     Redis

Applications depend on the CachePort interface rather than Redis itself, making the infrastructure layer replaceable and easier to test.

Why redis-plus?

Most Redis libraries expose Redis commands directly.

redis-plus focuses on providing a clean cache abstraction while preserving the power and performance of the official Redis client.

It offers:

• A consistent cache interface
• Automatic object serialization
• Framework independence
• Minimal overhead
• Easy unit testing
• Health checking for production environments

Use Cases

• Application caching
• Session storage
• Authentication and authorization
• API response caching
• Rate limiting
• Distributed locking
• Microservices
• Cloud-native applications

Related Projects

The redis-plus library is part of the core-ts ecosystem.

• sql-core — Database abstraction for SQL databases
• mongodb-kit — MongoDB toolkit
• query-mappers — Mapping database results to TypeScript models
• nats-plus — NATS messaging adapter
• activemq — ActiveMQ adapter
• config-plus — Configuration management
• reflect-core — Reflection utilities

Roadmap

• Support key prefixes
• Batch write operations
• Pipeline helpers
• Transaction helpers
• Distributed lock utilities
• Configurable serializers
• Metrics integration

Contributing

Contributions, issues, and feature requests are welcome.

GitHub Repository:

https://github.com/core-ts/redis

License

MIT