Koya

Koya computes the Koya tiebreak — a FIDE-defined method for breaking tied scores in round-robin (all-play-all) chess tournaments (section 9.2). TypeScript, zero runtime dependencies.

Installation

npm install @echecs/koya
Copy

Quick Start

import { koya, tiebreak } from '@echecs/koya';
import type { Bye, CompletedRound, Game, Pairing, Player } from '@echecs/koya';

// games[n] = round n+1; Game has no `round` field
const games: Game[][] = [
  [{ black: 'B', result: 1, white: 'A' }], // round 1
  [{ black: 'C', result: 0.5, white: 'A' }], // round 2
  [{ black: 'A', result: 0, white: 'D' }], // round 3
  // Unplayed rounds use kind to classify the bye type
  [{ black: '', kind: 'half-bye', result: 0.5, white: 'A' }], // round 4
];

const score = koya('A', games);
// Returns points scored against opponents who achieved >= 50% of the maximum score
Copy

API

koya(player, games)

FIDE section 9.2. Returns the total points player scored against opponents who reached at least 50% of the tournament's maximum possible score. Round-robin format only.

Byes (unplayed rounds) count toward neither the 50% threshold nor the score sum. Array position sets the round: games[0] = round 1, games[1] = round 2, etc. Unplayed rounds are classified by the kind field of the Bye type ('full' | 'half' | 'pairing' | 'zero').

koya(player: string, games: Game[][]): number
Copy

tiebreak is an alias for koya for use in tiebreak pipelines.

/limit-m1

FIDE C.07 sections 9.2 + 14.5. Koya with the threshold lowered to 50% − ½: opponents qualify when they scored at least half the rounds minus one half point.

import { koyaLimitM1, tiebreak } from '@echecs/koya/limit-m1';
Copy

/limit-m2

FIDE C.07 sections 9.2 + 14.5. Koya with the threshold lowered to 50% − 1: opponents qualify when they scored at least half the rounds minus one point.

import { koyaLimitM2, tiebreak } from '@echecs/koya/limit-m2';
Copy

/limit-p1

FIDE C.07 sections 9.2 + 14.5. Koya with the threshold raised to 50% + ½: opponents qualify when they scored at least half the rounds plus one half point.

import { koyaLimitP1, tiebreak } from '@echecs/koya/limit-p1';
Copy

/limit-p2

FIDE C.07 sections 9.2 + 14.5. Koya with the threshold raised to 50% + 1: opponents qualify when they scored at least half the rounds plus one point.

import { koyaLimitP2, tiebreak } from '@echecs/koya/limit-p2';
Copy

Exports

// Functions
export { koya, tiebreak } from '@echecs/koya';

// Types
export type { Bye, CompletedRound, Game, Pairing, Player } from '@echecs/koya';
Copy

Each limit variant subpath exports its named function (e.g. koyaLimitP1), a tiebreak alias, and the same Bye, CompletedRound, Game, Pairing, and Player types.

Contributing

Contributions are welcome. Please open an issue at github.com/echecsjs/koya/issues.