tournament-pairings

Node.js package containing functions to generate tournament pairings.

If you want a full-fledged package for organizing tournaments, consider tournament-organizer.

Algorithms

Double elimination: avoids rematches in the loser's bracket by alternating how matches are routed.

Round-robin: players are paired via Berger tables.

Swiss: generated using a weighted blossom algorithm with maximum cardinality.

Requirements

This is an ESM module. You will need to use import instead of require and add type: "module" to your package.json. See this for more information.

Installation

npm i tournament-pairings

Documentation

Imports

There are 5 named exports you can import into your project.

import {
    SingleElimination,
    DoubleElimination,
    RoundRobin,
    Stepladder,
    Swiss
} from 'tournament-pairings';

You can also import them all.

import * as Pairings from 'tournament-pairings';

Parameters

SingleElimination() has four parameters:

• players: either a number of players or an array of unique strings or numbers representing players
• startingRound (optional): an integer indicating the starting round (default: 1)
• consolation (optional): a boolean to determine if a third place match should be created (default: false)
• ordered (optional): a boolean to indicate if the array provided for players is ordered (default: false)

DoubleElimination() and RoundRobin() have three parameters:

• players: either a number of players or an array of unique strings or numbers representing players
• startingRound (optional): an integer indicating the starting round (default: 1)
• ordered (optional): a boolean to indicate if the array provided for players is ordered (default: false)

Stepladder() has three parameters:

• players: either a number of players or an array of unique strings or numbers representing players
• startingRound (optional): an integer indicating the starting round (default: 1)
• ordered (optional): a boolean to indicate if the array provided for players is ordered (default: true)

Swiss() has four parameters:

• players: an array of objects with the following structure

{
    id: String | Number, // unique identifier
    score: Number, // current score
    pairedUpDown?: Boolean, // if the player has been paired up/down prior (optional)
    receivedBye? : Boolean, // if the player has received a bye prior (optional)
    avoid?: Array<String | Number>, // array of IDs the player can not be paired with (optional)
    colors?: Array<'w' | 'b'>, // array of colors player has been assigned, where 'w' is white and 'b' is black (used for chess) (optional)
    rating?: Number | null // rating of the player (optional)
}

• round: the round number
• rated (optional): a boolean to indicate if the players have a rating that should be considered when pairing (default: false)
• colors (optional): a boolean to indicate if the players have had colors assigned to them, such as in chess (default: false)

Returns

Each function returns an array of matches. Matches are objects with the following structure:

{
    round: Number,
    match: Number,
    player1: String | Number | null,
    player2: String | Number | null,
    // the following objects are only present in elimination pairings
    win?: {
        round: Number,
        match: Number
    },
    loss?: {
        round: Number,
        match: Number
    }
}

For Swiss pairings, if colors = true, then player1 would be white and player2 would be black.

The Swiss function returns matches for one round, while single/double elimination and round-robin functions return all matches for the tournament.

Examples

Creating a generic single elimination bracket for 8 players with a third place match:

import { SingleElimination } from 'tournament-pairings';

const elimBracket = SingleElimination(8, 1, true);

console.log(elimBracket);
/*
Expected output:
[
  {
    round: 1,
    match: 1,
    player1: 1,
    player2: 8,
    win: { round: 2, match: 1 }
  },
  {
    round: 1,
    match: 2,
    player1: 4,
    player2: 5,
    win: { round: 2, match: 1 }
  },
  {
    round: 1,
    match: 3,
    player1: 2,
    player2: 7,
    win: { round: 2, match: 2 }
  },
  {
    round: 1,
    match: 4,
    player1: 3,
    player2: 6,
    win: { round: 2, match: 2 }
  },
  {
    round: 2,
    match: 1,
    player1: null,
    player2: null,
    win: { round: 3, match: 1 },
    loss: { round: 3, match: 2 }
  },
  {
    round: 2,
    match: 2,
    player1: null,
    player2: null,
    win: { round: 3, match: 1 },
    loss: { round: 3, match: 2 }
  },
  { round: 3, match: 1, player1: null, player2: null },
  { round: 3, match: 2, player1: null, player2: null }
]
*/

Creating round-robin pairings for the Teenage Mutant Ninja Turtles:

import { RoundRobin } from 'tournament-pairings';

const pairings = RoundRobin([
    'Leonardo',
    'Raphael',
    'Donatello',
    'Michelangelo'
]);
console.log(pairings);
/*
Expected output:
[
  { round: 1, match: 1, player1: 'Donatello', player2: 'Michelangelo' },
  { round: 1, match: 2, player1: 'Leonardo', player2: 'Raphael' },
  { round: 2, match: 1, player1: 'Michelangelo', player2: 'Raphael' },
  { round: 2, match: 2, player1: 'Donatello', player2: 'Leonardo' },
  { round: 3, match: 1, player1: 'Leonardo', player2: 'Michelangelo' },
  { round: 3, match: 2, player1: 'Raphael', player2: 'Donatello' }
]
*/

Discussion

You can discuss this repository more in my Discord.