README.md

📊 redis-rank

Manage real-time leaderboards using Redis

Features

• Lightweight: minimal dependencies, only ioredis is required
• Performance: guaranteed at most one trip to Redis on each function call*, taking advantage of ioredis's pipelining and Lua scripts
• Drop-in replacement: use any existing sorted set as a leaderboard
• Clear interface: Promise-based & provides TypeScript definitions
• Periodic leaderboards: create recurring leaderboards: daily, weekly, monthly, etc or use a custom cycle
• Combine leaderboards: create a matrix of leaderboards: update, filter and retrieve multiple entries in a single call
• Export: export your leaderboards for long-term storage
• Tested: 100% code coverage

Quick Start

⚙️ Install

⚠️ For ioredis <= 4.x use redis-rank@2.1.2, for ioredis >= 5.x use the latest version.

$ npm install redis-rank ioredis

Redis 2.6.12 or newer is required. The package ioredis is a peer dependency and must be installed separately.

🔗 Import and connect

ES5

const Redis = require('ioredis');
const { Leaderboard, PeriodicLeaderboard, LeaderboardMatrix } = require('redis-rank');

ES6

import { Redis } from 'ioredis';
import { Leaderboard, PeriodicLeaderboard, LeaderboardMatrix } from 'redis-rank';

You will have to provide a ioredis connection. See here for more information.

const client = new Redis({
    host: "127.0.0.1",
    port: 6379
});

You are ready, now read one of the examples linked below!

Examples

• Basic leaderboard usage
• Exporting a leaderboard
• Recurring leaderboards
• Custom cycles
• Clean stale leaderboards
• Matrix of leaderboards
• Showcasing leaderboards

API

• Types
• Leaderboard
  • Types
  • Constructor
  • Insert/update entries
  • Remove entries
  • Find entries
  • List entries
  • Export
  • Information
• PeriodicLeaderboard
  • Types
  • Constructor
  • Keys
  • Leaderboards
• LeaderboardMatrix
  • Types
  • Constructor
  • Leaderboards
  • Insert/update entries
  • Remove entries
  • Find entries
  • List entries
  • Information
• Redis keys

Running tests

A Redis server in localhost without password is expected. You can create one easily with Docker like so:

docker run -p 6379:6379 -t -i --rm redis:latest

⚠️ Note: The database #15 will be flushed ⚠️

Run tests:

npm test

I tried with ioredis-mock but I experienced some issues with Lua scripts so we have to rely on a real Redis server (which I think is better anyway).

License

MIT. See LICENSE.