goleaderboard

README

goleaderboard

Package to make your own leaderboard in simple way

What is it?

A leaderboard written in Go using Redis database

Features

• Ranking members by score
• Members with same score will have the same rank
• Get around members of a member with specific order
• Can create multiple leaderboards by name

Installation

Install by using go get

go get github.com/duysmile/goleaderboard

How to use

Create a new leaderboard

rdb := redis.NewClient(&redis.Options{
		Addr:     "localhost:6379",
		Password: "", // no password set
		DB:       0,  // use default DB
	})
leaderboard := goleaderboard.NewLeaderBoard(rdb, "test", nil)

Add a member with id and score

leaderboard.AddMember(ctx, "P4", 2)

Get rank of a member by id

rank, _ := leaderboard.GetRank(ctx, "P4")
fmt.Println("rank of member:", fmt.Sprintf("#%v", rank))

List members by rank

list, _ := leaderboard.List(ctx, 0, 10, goleaderboard.OrderDesc)

// you can choose the order you want
// for example: 
// list, _ := leaderboard.List(ctx, 0, 10, goleaderboard.OrderAsc)

Get around of a member

list, _ = leaderboard.GetAround(ctx, "P4", 4, goleaderboard.OrderDesc)

Contribution

All your contributions to project and make it better, they are welcome. Feel free to start an issue.

License

@2022, DuyN. Released under the MIT License

Documentation

Index

• type Leaderboard
  • func NewLeaderBoard(redisClient *redis.Client, name string, opts *Options) Leaderboard
• type Member
• type Options
• type Order
• type RedisLeaderboard
  • func (l *RedisLeaderboard) AddMember(ctx context.Context, id interface{}, score int) error
  • func (l *RedisLeaderboard) Clean(ctx context.Context) error
  • func (l *RedisLeaderboard) GetAround(ctx context.Context, id interface{}, limit int, order Order) ([]*Member, error)
  • func (l *RedisLeaderboard) GetRank(ctx context.Context, id interface{}) (int, error)
  • func (l *RedisLeaderboard) List(ctx context.Context, offset, limit int, order Order) ([]*Member, error)

Types

type Leaderboard

type Leaderboard interface {
	AddMember(ctx context.Context, id interface{}, score int) error
	List(ctx context.Context, offset, limit int, order Order) ([]*Member, error)
	GetAround(ctx context.Context, id interface{}, limit int, order Order) ([]*Member, error)
	GetRank(ctx context.Context, id interface{}) (int, error)
	Clean(ctx context.Context) error
}

Leaderboard is the representation of a leaderboard usage.

func NewLeaderBoard

func NewLeaderBoard(redisClient *redis.Client, name string, opts *Options) Leaderboard

NewLeaderBoard create a new leaderboard stored in Redis with specific name and configs. You can see all supported config in type `Options`

type Member

type Member struct {
	ID    interface{}
	Score int
	Rank  int
}

Member is a member of leaderboard. It is the main object of leaderboard.

type Options

type Options struct {
	AllowSameRank bool
	LifeTime      time.Duration
}

Options contains all configs for leaderboard

type Order

type Order string

Order is the way to sort leaderboard.

var (
	OrderDesc Order = "desc"
	OrderAsc  Order = "asc"
)

type RedisLeaderboard

type RedisLeaderboard struct {
	// contains filtered or unexported fields
}

RedisLeaderboard defines a leaderboard stored in Redis, follows Leaderboard interface

func (*RedisLeaderboard) AddMember

func (l *RedisLeaderboard) AddMember(ctx context.Context, id interface{}, score int) error

AddMember add a member with score to leaderboard. It will automatically add member to the right position, if member was already in leaderboard, it will update the rank of this one.

func (*RedisLeaderboard) Clean

func (l *RedisLeaderboard) Clean(ctx context.Context) error

Clean clear all data of leaderboard in redis

func (*RedisLeaderboard) GetAround

func (l *RedisLeaderboard) GetAround(ctx context.Context, id interface{}, limit int, order Order) ([]*Member, error)

GetAround get list member around another member with limit and order

func (*RedisLeaderboard) GetRank

func (l *RedisLeaderboard) GetRank(ctx context.Context, id interface{}) (int, error)

GetRank get rank of a member

func (*RedisLeaderboard) List

func (l *RedisLeaderboard) List(ctx context.Context, offset, limit int, order Order) ([]*Member, error)

List get list member with offset, limit and order in leaderboard