@openpairings/gridswiss

Typed Node.js bindings for the GridSwiss Swiss pairing engine.

import { pairDutch, pairNextRound, pairUsChess } from "@openpairings/gridswiss";

const result = pairDutch({
  expectedRounds: 9,
  players: [
    { id: "alice", pairingNumber: 1, rating: 2200 },
    { id: "bob", pairingNumber: 2, rating: 2100 },
  ],
});

const usChess = pairUsChess({
  expectedRounds: 5,
  players: [
    { id: "alice", pairingNumber: 1, rating: 2200 },
    {
      id: "bob",
      pairingNumber: 2,
      rating: 2100,
      requestedByes: [{ round: 1, kind: "half-point" }],
      pairingAllocatedByeIneligible: true,
    },
  ],
});

US Chess options are typed. Unsupported exposed policies throw explicit errors instead of silently falling back. Useful current options:

• teamConflicts: "avoid-when-practical": default 28N plus-two method.
• teamConflicts: "avoid-when-possible": stricter teammate avoidance.
• teamConflicts: "hard": reject unavoidable same-team pairings.
• colorAllocation: "team-priority": apply 29E8 team priority during color repair.
• Other colorAllocation variations are typed but fail closed, including "top-down", "equalization-priority", "plus-even-minus-priority", "alternating-priority", "lot-last-round", and "rank-priority".
• acceleratedPairings: "standard-first-two-rounds": 28R1 acceleration for rounds one and two.
• acceleratedPairings: "adjusted-rating-round-two": 28R2 first-round quarter pairings and adjusted round-two A2/B2/C2/D2 grouping.
• acceleratedPairings: "sixths": 28R3 sixth-based acceleration for the first two rounds.
• requestedNonPairings: hard-only via forbiddenPairs today.

The public API accepts typed JavaScript objects. The native binding is loaded from native/gridswiss.node, then from the matching optional platform package; set GRIDSWISS_NATIVE_PATH to override that path in development.

rank defaults to pairingNumber and must be unique when supplied. For US Chess late entrants, provide a rating-order rank if the entrant's appended pairing number should not determine their score-group order.

US Chess policy options are exposed through the typed object API, not TRF/XXG records. TRF imports may carry XXG system US_CHESS and supported player state metadata, but unsupported policy records fail closed.

The generic dispatcher is a discriminated union. Dutch and Burstein use the simple tournament shape; US Chess alone accepts the richer US Chess metadata:

pairNextRound({ system: "dutch", tournament });
pairNextRound({ system: "uschess", tournament: usChessTournament, options });