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.

Swiss Pairings

• Players are preferred to play against other players with equal point totals
• If there are an odd number of players, players with the lowest point total who have not previously received a bye are preferred to receive the bye
• If the tournament is rated, players are preferred to play other players with similar ratings
• If the seating in a tournament is relevant, such as white and black in chess, players are preferred to play the opposite seat than last played and strongly preferred to not play the same seat more than two times consecutively

Requirements

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

Discussion

You can discuss this repository more in my Discord.

Documentation

Installation

npm i tournament-pairings

Importing

Named imports:

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

Namespace import:

import * as Pairings from 'tournament-pairings'

Interfaces for TypeScript:

import {
    Match,
    Player
} from 'tournament-pairings/interfaces'

Functions

Single elimination:

SingleElimination(
    players: Number | Array<String>,
    startingRound: Number = 1,
    consolation: Boolean = false,
    ordered: Boolean = false
): Array<Match>

Double elimination:

DoubleElimination(
    players: Number | Array<String>,
    startingRound: Number = 1,
    ordered: Boolean = false
): Array<Match>

Round-robin:

RoundRobin(
    players: Number | Array<String>,
    startingRound: Number = 1,
    ordered: Boolean = false
): Array<Match>

Stepladder:

Stepladder(
    players: Number | Array<String>,
    startingRound: Number = 1,
    ordered: Boolean = true
): Array<Match>

Swiss:

Swiss(
    players: Array<Player>,
    round: Number,
    rated: Boolean = false,
    seating: Boolean = false
): Array<Match>

Player {
    id: String | Number,
    score: Number,
    pairedUpDown?: Boolean,
    receivedBye? : Boolean,
    avoid?: Array<String | Number>,
    seating?: Array<-1 | 1>,
    rating?: Number | null
}

Notes on Parameters

players: if provided a number n (except for Swiss), then players are array of numbers from 1 to n.

consolation: if there is an additional match in the final round to determine third place.

ordered: if the array provided for players is ordered.

rated: if the players have a rating to be considered for pairing.

seating: if the seating of the players needs to be considered.

Notes on Player Interface

pairedUpDown: if the player has been paired with someone outside their point group in a prior round.

receivedBye: if the player was unpaired in a prior round.

avoid: an array of IDs representing prior opponents of the player.

seating: an array of either 1 or -1 to represent seating. The most obvious example is playing white or black in chess.

Return Value

Each function returns an Array<Match>.

Match {
    round: Number,
    match: Number,
    player1: String | Number | null,
    player2: String | Number | null,
    win?: {
        round: Number,
        match: Number
    },
    loss?: {
        round: Number,
        match: Number
    }
}

The Swiss function returns matches for the given round, while all other functions return matches for the entire tournament.