mlomb/redis-rank

Manage real-time leaderboards using Redis

📊 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 [email protected], 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.

redis-rank's Issues

Reverse Lookup: Find nearby users with a particular score

I am looking for a way to find users within a score range. Is there a way to do it with this library?
One of the use cases is matchmaking. Given a skill rating, I would like to find players with a similar skill rating.
If there is no way to do it currently, do you have a plan to implement this feature?

I find that Redis support ZRANGE BYSCORE, which means this should be relatively easy to implement. I could try to implement it and submit a PR.

How do you "add or increment" ?

Hello,

Your lib is interesting and I am evaluating if I could use it for our project.
One thing I am not sure how to do from the docs is to add a new entry if it does not exist or increment the score of that entry if it does? Would I need to peek() then decide add / increment or is there a better solution?

Feature request: allow to store and retrieve arbitrary data for each member

Sometimes we need additional data about users in the leaderboard.

Following the redis docs about leaderboards.

The first problem that comes to mind is that the username may not be a good ID for the leaderboard if users can change it. Especially if we go for longer periods like weekly leaderboards.

So we need a constant ID and a "screenname".
In the Redis docs, they create an additional hash for each user with the needed properties. What they don't explain is how to best "join" the data.

I am interested in replicating this in redis-rank. Is this something you'd agree to have? I'd like to help as much as I can (I don't know much Redis)

[bug] scores are turned into integers

A bit everywhere in the code, parseInt is used on scores. It leads to wrong results with decimal values.

2 examples:

• Leaderboard.ts list
• Leaderboard.ts incr
  This one tricked me becauseparseInt is applied on the returned value. So the value in Redis is correctly increased but the returned value is wrong if it has decimals.

I suppose replacing parseInt by parseFloat everywhere would do the trick but maybe you had a reason.

BUG: leaderboard creation not working

I have recently changed my leaderboard update policy in my backend to 'aggregate' from 'replace'.
'replace' was working fine but was confusing to use as it required me fetching and updating myself instead of just sending a new value to be added.
however, since i have switched to 'aggregate' i have noticed that the leaderboards are not being created. at first i didn't notice this due to the cycle not ending but now i have just tested on a minute cycle and seen it.
I've just switched back to 'replace' and found that this isn't working either.

const periodicOptions: PeriodicLeaderboardOptions = {
        leaderboardOptions: {
            sortPolicy: 'high-to-low',
            updatePolicy: 'aggregate',
        },
        cycle: 'minute', // Update monthly
    };

    // Create a periodic leaderboard
    plb = new PeriodicLeaderboard(redisClient, 'gutz_monthly_leaderboard_m_test', periodicOptions);

    await redisClient.connect();    

[FEATURE]: Ability to set up a function to run at the end of each periodic leaderboard for example, for rewards to be distributed