redis-rank

library2.2.3jsnpmunverified

A lightweight, high-performance Redis-backed leaderboard library for Node.js. Version 2.2.3 is the latest stable release, with active development. It provides a clean Promise-based API with full TypeScript support, leveraging ioredis pipelining and Lua scripts to guarantee at most one Redis trip per function call. Key differentiators: support for periodic/daily/weekly/monthly leaderboards, combining multiple leaderboards into a matrix, and the ability to use any existing Redis sorted set as a drop-in leaderboard. Unopinionated and well-tested with 100% code coverage.

gaming analytics

npm install redis-rank

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REDIS-RANK

redis-rank

gamingjavascriptv2.2.3

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.

Leaderboard

✓ import { Leaderboard } from 'redis-rank'

✗ const Leaderboard = require('redis-rank').Leaderboard

Both ESM and CJS work. The library includes TypeScript definitions.

PeriodicLeaderboard

✓ import { PeriodicLeaderboard } from 'redis-rank'

✗ import PeriodicLeaderboard from 'redis-rank'

Named export, not default.

LeaderboardMatrix

✓ import { LeaderboardMatrix } from 'redis-rank'

✗ const { LeaderboardMatrix } = require('redis-rank')

CJS destructuring works, but is less common for named exports in docs.

Creates a Redis client, initializes a leaderboard, adds three players with scores, retrieves the top two, and fetches a player's rank.

import { Redis } from 'ioredis'; import { Leaderboard } from 'redis-rank'; const client = new Redis({ host: '127.0.0.1', port: 6379 }); const leaderboard = new Leaderboard(client, 'game:scores'); await leaderboard.set('player1', 100); await leaderboard.set('player2', 200); await leaderboard.set('player3', 150); // Get top 2 players const top = await leaderboard.list({ start: 0, stop: 1 }); console.log(top.length); // 2 // Get player1's rank const rank = await leaderboard.rank('player1'); console.log(rank); // 3 (0-indexed, so 3rd) await client.quit();

Debug

Known issues

breakingioredis v5 peer dependency: redis-rank >= 2.2.0 requires ioredis v5.x or newer. Using ioredis v4 will cause compatibility issues.

fix

Upgrade ioredis to >= 5.0.0, or use redis-rank < 2.2.0 (e.g., 2.1.2) with ioredis v4.

affects: >=2.2.0

deprecatedThe 'periodic' option in Leaderboard constructor is deprecated in favor of PeriodicLeaderboard class.

fix

Use the PeriodicLeaderboard class for periodic leaderboards instead of passing a 'periodic' option.

affects: >=2.0.0

gotchaRedis 2.6.12 or newer required. Older Redis versions do not support some Lua scripts used internally.

fix

Check Redis server version: redis-server --version, upgrade if below 2.6.12.

affects: >=1.0.0

gotchaThe 'rank' method returns 0-indexed rank (0 = highest rank). This differs from some other leaderboard libraries that use 1-indexed ranks.

fix

Add 1 to the result if you need 1-indexed rank. E.g., const rank = (await leaderboard.rank('player')) + 1;

affects: >=1.0.0

gotchaThe Leaderboard constructor uses the same Redis key as your existing sorted set. If the key does not exist, it will be created when adding entries.

fix

Ensure your Redis sorted set key is correctly specified; the library will not create a key until a write operation occurs.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: leaderboard.set is not a function

Attempting to call set() on an instance created with wrong import (e.g., using default import instead of named).

fix

Use correct named import: import { Leaderboard } from 'redis-rank'. Then instantiate: const lb = new Leaderboard(client, 'key');

Error: Redis connection to 127.0.0.1:6379 failed - connect ECONNREFUSED

Redis server is not running or not reachable at the specified host/port.

fix

Start Redis server with: redis-server. Or modify connection options to point to a running instance.

TypeError: Leaderboard is not a constructor

Using CJS require on a default export; redis-rank does not have a default export.

fix

Use destructured require: const { Leaderboard } = require('redis-rank');

Cannot find module 'redis-rank'

The package is not installed.

fix

Run: npm install redis-rank ioredis

Upgrade

Version history

2.2.3latest on npm

Audit

Dependencies

ioredisrequiredPeer dependency: required for Redis connection. Version 5.x required for redis-rank >= 2.2.0, v4.x for older versions.

Agent activity

38 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/mlomb/redis-rank ↗

packageredis-rank ↗

homepagehttps://github.com/mlomb/redis-rank ↗