redis-csc

library1.0.7jsnpmunverified

Redis client-side caching wrapper for ioredis using Redis 6+ CLIENT TRACKING BCAST mode. Current stable version is 1.0.7 (last updated October 2023). It automatically invalidates local in-memory cache when subscribed key prefixes change in Redis, reducing latency and server load. Unlike generic caching libraries, this uses native Redis tracking for real-time invalidation without polling. Requires Redis >=6.0 and ioredis >=5.0 as a peer dependency. Ships TypeScript types and supports NOLOOP to avoid self-invalidation.

database storage

npm install redis-csc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-CSC

redis-csc

databasejavascriptv1.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RedisClientSideCache

✓ import { RedisClientSideCache } from 'redis-csc'

✗ const RedisClientSideCache = require('redis-csc')

ESM default is named export; commonjs usage may need destructuring. The package ships TypeScript types.

create (static method)

✓ const cache = await RedisClientSideCache.create(redis, prefixes, defaultExpiry, callback, readyTimeoutMs, localCacheTTL)

✗ const cache = new RedisClientSideCache(redis, prefixes, ...)

The class constructor is private; you must use the static create() method which returns a promise.

getCached / setCached

✓ await cache.getCached('key') await cache.setCached('key', value, ttl?)

✗ await cache.get('key')

Cache operations are methods on the instance returned by create(), not on the class itself. The library does not extend ioredis.

Shows instantiation via async create() method, then getCached and setCached operations.

import Redis from 'ioredis'; import { RedisClientSideCache } from 'redis-csc'; const redis = new Redis({ host: process.env.REDIS_HOST ?? 'localhost', port: Number(process.env.REDIS_PORT ?? 6379) }); const prefixes = ['user:', 'product:']; const defaultExpiry = 3600; const invalidationCallback = (keys) => console.log('Invalidated:', keys); const readyTimeoutMs = 5000; const localCacheTTL = 300; const cache = await RedisClientSideCache.create(redis, prefixes, defaultExpiry, invalidationCallback, readyTimeoutMs, localCacheTTL); const { data, cacheHits } = await cache.getCached('user:123'); console.log('User:', data, 'Cache hits:', cacheHits); await cache.setCached('user:123', JSON.stringify({ name: 'John' }), 3600);

Debug

Known issues

breakingConstructor is private; must use static create() method.

fix

Replace `new RedisClientSideCache(...)` with `await RedisClientSideCache.create(...)`.

affects: >=1.0.0

deprecatedThe mGetCached and mSetCached methods are present but not documented; may be unstable.

fix

Use individual getCached/setCached in loops until methods are stable.

affects: 1.0.7

gotchaRequires Redis server version >=6.0; CLIENT TRACKING command unavailable on older versions.

fix

Ensure Redis 6+ is running. The lib will fail silently or throw an error if tracking is unsupported.

affects: >=1.0.0

gotchaLocal cache TTL (localCacheTTL) applies only to the in-memory cache, not the Redis key TTL.

fix

Set both defaultExpiry (Redis key TTL) and localCacheTTL independently to avoid stale data in local cache.

affects: >=1.0.0

gotchaOnly BCAST mode with prefix tracking is supported; REDIRECT mode (per-key tracking) is not implemented.

fix

Use prefix-based tracking; for per-key tracking consider alternatives like redis-lru-cache.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: RedisClientSideCache.create is not a function

Using CommonJS require incorrectly without destructuring the named export.

fix

Use `const { RedisClientSideCache } = require('redis-csc');` instead of `const RedisClientSideCache = require('redis-csc');`.

RedisError: ERR NOLOOP can't be used with BCAST

The library uses NOLOOP but your Redis server version may not support it (requires Redis 6.0+).

fix

Upgrade Redis server to 6.0 or later.

Error: Connection timeout

The readyTimeoutMs passed to create() was too short or Redis server is unreachable.

fix

Increase readyTimeoutMs or check Redis connection settings.

Upgrade

Version history

1.0.7latest on npm

Audit

Dependencies

ioredisrequiredpeer dependency >=5.0.0; used as the Redis client

Agent activity

29 hits · last 30 days

node