https://github.com/rocambille/elo
Enrich your objects with Elo rating.
https://github.com/rocambille/elo
chess elo elo-rating game go hacktoberfest ranking rating
Last synced: 6 months ago
JSON representation
Enrich your objects with Elo rating.
- Host: GitHub
- URL: https://github.com/rocambille/elo
- Owner: rocambille
- License: mit
- Created: 2021-08-21T13:40:21.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-10-05T08:01:49.000Z (12 months ago)
- Last Synced: 2025-03-28T23:51:17.951Z (6 months ago)
- Topics: chess, elo, elo-rating, game, go, hacktoberfest, ranking, rating
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@rocambille/elo
- Size: 319 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Elo
Enrich your objects with [Elo rating](https://en.wikipedia.org/wiki/Elo_rating_system).
## Installation
```bash
npm i @rocambille/elo
```
## Basic usage
```js
import elo from "@rocambille/elo";
// or const elo = require("@rocambille/elo");
const player = elo();
let foo = { a: 42 };
let bar = { z: 43 };
const odds = player(foo).oddsAgainst(bar);
console.log(`foo has a ${odds * 100}% chance of winning against bar`);
[foo, bar] = player(foo).wins(bar);
// or [foo, bar] = player(foo).loses(bar);
// or [foo, bar] = player(foo).ties(bar);
console.log(foo, bar);
```
Should print something like this:
```bash
foo has a 50% chance of winning against bar
{
a: 42,
elo: {
rating: 1516,
matchCount: 1,
lastDelta: 16,
lastPlayedAt: 1629554837908
}
} {
z: 43,
elo: {
rating: 1484,
matchCount: 1,
lastDelta: -16,
lastPlayedAt: 1629554837908
}
}
```
Note that the elo module keeps `foo.a` and `bar.z` untouched.
It enriches the objects with Elo stuff (rating, match count, last delta and last play timestamp).
This is useful if you want to add elo rating on top of existing data, e.g. coming from an API.
## The Pool object
You can manage a whole collection using the `Pool` object as follows:
```js
import { Pool } from "@rocambille/elo";
// or const { Pool } = require("@rocambille/elo");
let pool = Pool.from([{ a: 42 }, { z: 43 }, { x: 44 }]);
const odds = pool.player(0).oddsAgainst(1);
console.log(`player 0 has a ${odds * 100}% chance of winning against player 1`);
pool = pool.player(0).wins(1);
// or pool = pool.player(0).loses(1);
// or pool = pool.player(0).ties(1);
console.log(pool);
```
Should print something like this:
```bash
player 0 has a 50% chance of winning against player 1
[
{
a: 42,
elo: {
rating: 1516,
matchCount: 1,
lastDelta: 16,
lastPlayedAt: 1629554837908
}
},
{
z: 43,
elo: {
rating: 1484,
matchCount: 1,
lastDelta: -16,
lastPlayedAt: 1629554837908
}
},
{
x: 44,
elo: {
rating: 1500,
matchCount: 0,
lastDelta: NaN,
lastPlayedAt: NaN
}
}
]
```
The `Pool` provides a useful method to `pick` player indices using multiple options:
```js
import { Pool } from "@rocambille/elo";
// or const { Pool } = require("@rocambille/elo");
let pool = Pool.from([{ a: 42 }, { z: 43 }, { x: 44 }]);
// use one of the following lines to pick players
const [i, j] = pool.pick("random"); // randomly pick
const [i, j] = pool.pick("matchCount"); // pick players with a low match count
const [i, j] = pool.pick("lastPlayedAt"); // pick players who have last played in the longest time
const [i, j] = pool.pick(); // pick players by randomly choosing one the above method (recommended)
// then you can use i and j to trigger a match
pool = pool.player(i).wins(j);
```
## Configuration
You can pass a configuration object as parameter to the `elo` function.
Here is an example with the default values:
```js
import elo from "elo";
// or const elo = require("@rocambille/elo");
const player = elo({
initialRating: 1500,
DMax: 400,
kGenerator: (eloData) => {
if (eloData.matchCount < 30) {
return 32;
}
return 24;
},
propsKey: "elo",
});
```
Same works with the `Pool` object, using the `Pool.config` method:
```js
import { Pool } from "elo";
// or const { Pool } = require("@rocambille/elo");
const pool = Pool.config({
initialRating: 1500,
DMax: 400,
kGenerator: (eloData) => {
if (eloData.matchCount < 30) {
return 32;
}
return 24;
},
propsKey: "elo",
}).from(...);
```
The module will use `initialRating` for players with an _undefined_ rating.
See details of [Elo rating system](https://en.wikipedia.org/wiki/Elo_rating_system) for the `DMax` and `k` factors.
## License
elo is open source software [licensed as MIT](https://github.com/rocambille/elo/blob/main/LICENSE).