gamestdio / leaderboard

🏆 Minimalist Leaderboard Module for Node.js using MongoDB

@gamestdio/leaderboard

Minimalist Leaderboard Module for Node.js using MongoDB.

This module uses MongoDB's TTL feature in order to avoid maintenance of leaderboard records.

Note: It would be nice to have support for multiple databases, such as MySQL, Postgres, etc. Pull-requests are welcome!

Usage

Installation

npm install mongodb
npm install @gamestdio/leaderboard

Import and set up

import { MongoClient } from "mongodb";
import { Leaderboard } from "@gamestdio/leaderboard";

// Setup your MongoDB connection.
const client = new MongoClient("mongodb://...");
const db = client.db("your_database");

// Initialize the leaderboard.
const leaderboard = new Leaderboard(db);

Creating a leaderboard

You may have as many leaderboards as you'd like to.

// creating a daily leaderboard (records are removed after 24h)
leaderboard.create("day", { ttl: 1 * 60 * 60 * 24 });

// creating a daily leaderboard (records are removed after 7 days)
leaderboard.create("week", { ttl: 1 * 60 * 60 * 24 * 7 });

// creating a montly leaderboard (records are removed after 30 days)
leaderboard.create("month", { ttl: 1 * 60 * 60 * 24 * 30 });

Inserting scores into the leaderboard

leaderboard.record("day", { id: "unique user id here", score: 50 });

Querying for scores

leaderboard.list("day").then((rows) => {
    console.log(rows);
});

Getting exact position of player

leaderboard.position("day", "unique user id here").then((position) => {
    console.log(position) // => 1 ~ 9999...
});

Get scores surrounding player

leaderboard.surrounding("day", "unique user id here", { limit: 3 }).then((scores) => {
    console.log(scores) ; /* => [
        { id: 'player7', score: 60, createdAt: 2018-05-04T02:54:55.836Z },
        { id: 'player3', score: 50, createdAt: 2018-05-04T02:54:55.825Z },
        { id: 'player2', score: 30, createdAt: 2018-05-04T02:54:55.824Z },
        { id: 'unique user id here', score: 25, createdAt: 2018-05-04T02:54:55.826Z },
        { id: 'player1', score: 10, createdAt: 2018-05-04T02:54:55.823Z },
        { id: 'player6', score: 3, createdAt: 2018-05-04T02:54:55.828Z },
        { id: 'player5', score: 1, createdAt: 2018-05-04T02:54:55.827Z }
    ]*/
}),

License

MIT

leaderboard's Issues

Should we support querying by properties

Hi!
I am thinking how we can have the leaderboard for the country. For example, we will filter score by USA, Germany .. I can create a separate leaderboard for each country but I think we can use added properties when we submitted score like country, age, ... so we can filter by that properties later...
Thank so much!

API for updating scores by id

this would be helpful for when you have permanent leaderboards!

Save command mistake

Hey mates! Yo posted at readme that to save an entrie you should use .store. If you take a look to yours leaderboard.js you will not find any .store function. It is called .record.
Thanks!!

Please support API for get around player position

Hi!
Your Leaderboard is awesome and very clean! I love it!
Please support API for query information for example 2 user above and 2 users bellow current user position.
That way we can tell user hey let try more 10 scores and then you can have higher pos!
Thank so much!