Norway Porridge Makers

    tournament-pairings
    TypeScript icon, indicating that this package has built-in type declarations

    1.5.2 • Public • Published

    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' }
    ]
    */

    Install

    npm i tournament-pairings

    DownloadsWeekly Downloads

    236

    Version

    1.5.2

    License

    GPL-3.0-or-later

    Unpacked Size

    146 kB

    Total Files

    28

    Last publish

    Collaborators

    • slashinfty