Giter VIP home page Giter VIP logo

tt-match-ranking's Introduction

Table Tennis Match Ranking

A library that calculates the ranking of match (often a tournament) in table tennis.

It follows the official NTTB rules for tournaments.

  • Supports using your own datatypes to define your players
  • Supports various ways of scoring for both game, set and match
  • Supports walkovers (winning because the opponent refuses to player)
  • Supports incomplete games and sets

Installing

npm i @nttb/tt-match-ranking

Documentation

You can find the documentation here: https://nttb.github.io/tt-match-ranking/

FAQ

  • Q: The top-most data type is TTMatch shouldn't that be called a competiton or tournament?
    A: No, but we agree it's confusing. The naming convention is based on the "game, set and match". However many table tennis players talk about "winning a set" as if it were "winning a game".
  • Q: Why can I only add players/sets but not update them?
    A: Although the library looks like it is intended to be used manage a match, the only goal is to calculate the ranking. We recommend creating your own data types for storing and managing and then use this library to calculate the ranking. (We tried to create an all-in-one solution but failed as calculating ranking is quite complex)
  • Q: How well tested is this library?
    A: The library was created through test driven development and has a 100% test coverage, meaning that all functionality was written because an earlier test case demanded it. We are certain that all official scenarios are tested and we even added a few tests for unofficial edge cases such as when games or sets aren't completed. However like every piece of code the "absence of proof" is not "proof of absence".
  • Q: Can I use the library in javascript instead of typescript?
    A: Yes, the library is compiled to javascript from typescript without any dependencies. The example only uses typescript as it better displays the functionality.

Example

import { 
  TTMatch,              // The type that contains all the match data
  parseSetScore,        // An easy to use function for adding sets
  generateMatchRank     // The function that generates the ranking
} from "@nttb/tt-match-ranking";

////////////////////////////////////////////////////////////////
// 0. You can create your own player-information (or just use a string).
interface MyPlayerType {
  name: string;
  club: string;
}

////////////////////////////////////////////////////////////////
// 1. Define the match and set rules
const matchRules = {
  victoryPoints: 2, // Players get 2 points when they are the winner
  defeatPoints: 1   // Players get 1 points when they play and lose...
                    // ... so that players that refuse to play are at a bigger disadvantage. 
};

const setRules = {
  bestOf: 5,           // A set is won when a player has 3 out of 5 games. 

  gameRules: {         // A game is won when a player...
    scoreMinimum: 11,  // - ... has at least 11 points
    scoreDistance: 2,  // - ... has at least 2 points advantage 
  }
};

////////////////////////////////////////////////////////////////
// 2. Create the match/tournament.
const match = new TTMatch<MyPlayerType>();

////////////////////////////////////////////////////////////////
// 3. Add the players that are participating.
const playerA = match.addPlayer({ name: "Player A", club: "my-club" });
const playerB = match.addPlayer({ name: "Player B", club: "my-club" });
const playerC = match.addPlayer({ name: "Player C", club: "my-club" });
const playerD = match.addPlayer({ name: "Player D", club: "my-club" });
const playerE = match.addPlayer({ name: "Player E", club: "my-club" });
const playerF = match.addPlayer({ name: "Player F", club: "my-club" });

////////////////////////////////////////////////////////////////
// 4. Add the played sets
// A vs B -- Player A loses in 3 games
match.addSet(playerA, playerB, parseSetScore("0-11,0-11,0-11"));
// A vs C -- Player A wins in 4 games
match.addSet(playerA, playerC, parseSetScore("0-11,11-0,11-0,11-0"));
// A vs D -- Player A loses in 5 games.
match.addSet(playerA, playerD, parseSetScore("0-11,11-0,0-11,11-0,0-11"));
// A vs E -- Player A wins because player E refuses to play
match.addSet(playerA, playerE, parseSetScore("wo:home"));
// A vs F -- Unknown result, as the set has no clear winner.
match.addSet(playerA, playerF, parseSetScore("0-11"));

////////////////////////////////////////////////////////////////
// 5. Calculate the ranking
const ranking = generateMatchRank(match, matchRules, setRules);

////////////////////////////////////////////////////////////////
// X. Display the ranking
ranking.ranked.forEach((rank, i) => {
  const pos = i + 1;
  console.log(`${pos}. ${rank.player.name}`)
})

Versions

1.0.0 - Initial release

  • This is the initial release

1.0.1 - Correct the ranked/unranked players

  • fixed: Before a player would be unranked when a player only has walkovers. Now that player will be ranked first.
  • new: Ranked sets are also included in the result. This is often needed when determing the total win/lose ratio in the ranking.

tt-match-ranking's People

Contributors

devwouter avatar

Stargazers

 avatar

Watchers

 avatar  avatar  avatar

tt-match-ranking's Issues

Support both best-of-x-games and minimal-x-games

Currently the library supports only best-of 3 or a variation of it.
However in some cases the rules is that a minimum of 3 games is played.
So 11-0,11-0,11-0 can occur but also 11-0,0-11,11-0.

As a user, I want to see the steps used to determine the ranking

It would be useful for both users and developers of the library that when the ranking is generated it also reports the steps and calculations that it has taken.

The current library does display a few (deprecated) fields but without inner understanding of the system it will be hard to use and validate (which is why they have been marked as deprecated).

As a developer, I want to consume the library as a single file

When build it exists out of multiple javascript files. Although this is fine for developers that are familiar with javascript bundeling, it will make it harder for developers who are unfamiliar with it.

I see no reason that the typescript compilation can output a single file. In fact from a performance point of view I think it's prefered.

As a developer, I want automatic build and publishing

Currently builds are done by hand, locally on a developer machine. As a general rule local builds are untrusted and it would be prefered if builds were created by Github.

Things to that we need to think about:

  • How do we secure the access to NPMJS?
  • How do we update the documentation? (This is now in the "prepack" script and then commited)
  • What about versioning and changelogs?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.