@echecs/trf - v4.0.0
    Preparing search index...

    @echecs/trf - v4.0.0

    TRF

    npm Coverage License: MIT Spec

    TRF is a TypeScript parser and serializer for the FIDE Tournament Report File format — the standard interchange format used by all FIDE-endorsed pairing software (JaVaFo, bbpPairings, Swiss Manager, Vega).

    Parses TRF strings into a fully-typed Tournament object and serializes them back. Zero runtime dependencies.

    npm install @echecs/trf

    import { parse, stringify } from '@echecs/trf';

    const tournament = parse(trfString);

    console.log(tournament.name); // "My Tournament"
    console.log(tournament.rounds); // 9
    console.log(tournament.players[0].name); // "Player0001"
    console.log(tournament.players[0].rating); // 2720
    console.log(tournament.players[0].results); // [{ round: 1, color: 'w', opponentId: 4, result: '1' }, ...]

    const trf = stringify(tournament); // back to TRF string

    parse()

    import { parse } from '@echecs/trf';

    function parse(input: string, options?: ParseOptions): Tournament | null;

    Takes a TRF string and returns a Tournament object, or null if the input cannot be parsed.

    • Strips BOM and surrounding whitespace automatically.
    • Never throws — parse failures call options.onError and return null.
    • Recoverable issues (unknown tags, malformed fields) call options.onWarning and continue parsing.
    import { parse } from '@echecs/trf';

    const tournament = parse(trfString, {
      onError: (err) => console.error(`Parse failed: ${err.message}`),
      onWarning: (warn) => console.warn(`Warning: ${warn.message}`),
    });

    Round results on each player use the following codes:

    Code Meaning
    1 Win
    0 Loss
    = Draw
    + Forfeit win
    - Forfeit loss
    D Draw (unrated game, less than one move)
    F Full-point bye
    H Half-point bye
    L Loss (unrated game, less than one move)
    U Unplayed
    W Win (unrated game, less than one move)
    Z Zero-point bye

    stringify()

    import { stringify } from '@echecs/trf';

    function stringify(tournament: Tournament, options?: StringifyOptions): string;

    Takes a Tournament object and returns a TRF string.

    • Never throws.
    • Omits optional header fields when absent.
    • parse(stringify(t)) roundtrips cleanly for any valid Tournament.
    • Warns (via options.onWarning) when a player string field exceeds its column width and will be truncated.
    import { parse, stringify } from '@echecs/trf';

    const t1 = parse(trfString)!;
    // ...modify t1...
    const updated = stringify(t1, {
      onWarning: (w) => console.warn(w.message),
    });

    @echecs/trf has no dependency on @echecs/swiss by design. To use a parsed tournament as input to the Swiss pairing functions, adapt the types in your own code:

    import { parse } from '@echecs/trf';
    import { pair } from '@echecs/swiss';

    import type { Tournament } from '@echecs/trf';
    import type { Game, Player } from '@echecs/swiss';

    function toPlayers(tournament: Tournament): Player[] {
      return tournament.players.map((p) => ({
        id: String(p.pairingNumber),
        rating: p.rating,
      }));
    }

    function toGames(tournament: Tournament): Game[][] {
      const gamesByRound = new Map<number, Game[]>();
      for (const player of tournament.players) {
        for (const result of player.results) {
          if (result.color !== 'w' || result.opponentId === null) continue;
          let score: 0 | 0.5 | 1;
          if (result.result === '1' || result.result === '+') score = 1;
          else if (result.result === '0' || result.result === '-') score = 0;
          else if (result.result === '=') score = 0.5;
          else continue;
          const games = gamesByRound.get(result.round) ?? [];
          games.push({
            black: String(result.opponentId),
            result: score,
            white: String(player.pairingNumber),
          });
          gamesByRound.set(result.round, games);
        }
      }
      const roundCount = Math.max(0, ...gamesByRound.keys());
      return Array.from(
        { length: roundCount },
        (_, i) => gamesByRound.get(i + 1) ?? [],
      );
    }

    const tournament = parse(trfString)!;
    const pairings = pair(toPlayers(tournament), toGames(tournament));

    Tournament

    interface Tournament {
      abnormalPoints?: AbnormalPoints[]; // Tag 299 — abnormal result overrides per round
      absentPlayers?: number[]; // XXZ — pairing numbers absent for current round
      acceleratedRounds?: AcceleratedRound[]; // Tag 250 — per-player fictitious points per round range
      byes?: Bye[]; // Tag 240 — bye assignments per round
      chiefArbiter?: string; // Tag 102
      city?: string;
      colourSequence?: string; // Tag 352 — e.g. 'WBWBWB'
      comments?: string[]; // TRF26 '###' comment lines
      deputyArbiters?: string[]; // Tag 112 — one entry per deputy arbiter line
      encodedTimeControl?: string; // Tag 222 — e.g. '5400+30'
      encodedTournamentType?: string; // Tag 192 — e.g. 'FIDE_DUTCH_2025'
      endDate?: string;
      federation?: string;
      forfeitedMatches?: ForfeitedMatch[]; // Tag 330 — forfeited team matches per round
      initialColour?: 'B' | 'W'; // Tag 152 / XXC white1/black1
      name?: string;
      numberOfPlayers?: number; // Tag 062
      numberOfRatedPlayers?: number; // Tag 072
      numberOfTeams?: number; // Tag 082
      outOfOrderLineups?: OutOfOrderLineup[]; // Tag 300 — out-of-order team lineups per round
      pairingController?: string; // Tag 092
      playerAccelerations?: PlayerAcceleration[]; // XXA — per-player acceleration points
      players: Player[];
      prohibitedPairings?: ProhibitedPairing[]; // Tag 260 / XXP — forbidden pairings
      roundDates?: string[]; // Tag 132 — one ISO date per round
      rounds: number; // XXR — total planned round count
      scoringSystem?: ScoringSystem; // Tag 162 / XXS
      standingsTiebreaks?: string[]; // Tag 212 — codes for defining standings
      startDate?: string;
      startingRankMethod?: string; // Tag 172 — e.g. 'FRA FIDON'
      teamPairingAllocatedByes?: TeamPairingAllocatedBye; // Tag 320
      teamRoundResults?: TeamRoundResult[]; // Tags 801/802 — team round-by-round results
      teams?: Team[]; // Tag 310
      teamScoringSystem?: string; // Tag 362 — e.g. 'TW 2.0    TD 1.0    TL 0.0'
      tiebreaks?: string[]; // Tag 202 — codes for breaking ties
      timeControl?: string; // Tag 122
      tournamentType?: string; // Tag 092 (TRF26) — free-form tournament type
      useRankingId?: boolean; // XXC rank
      version: Version; // 'TRF16' | 'TRF26'
    }

    Player

    interface Player {
      birthDate?: string;
      federation?: string;
      fideId?: string;
      name: string;
      nationalRatings?: NationalRating[]; // NRS records for this player
      pairingNumber: number;
      points: number;
      rank: number;
      rating?: number;
      results: RoundResult[];
      sex?: Sex; // 'm' | 'w'
      title?: Title; // 'GM' | 'IM' | 'FM' | ...
    }

    RoundResult

    interface RoundResult {
      color: 'b' | 'w' | '-'; // '-' = no color assigned (bye/unplayed)
      opponentId: number | null; // null for byes
      result: ResultCode;
      round: number;
    }

    PlayerAcceleration

    Per-player acceleration record (XXA). Stores fictitious extra points per round.

    interface PlayerAcceleration {
      pairingNumber: number;
      points: number[]; // one value per round, indexed from 0
    }

    ScoringSystem

    Custom scoring weights for result types (Tag 162 / XXS).

    interface ScoringSystem {
      absence?: number;
      blackDraw?: number;
      blackLoss?: number;
      blackWin?: number;
      draw?: number;
      forfeitLoss?: number;
      forfeitWin?: number;
      fullPointBye?: number;
      halfPointBye?: number;
      loss?: number;
      pairingAllocatedBye?: number;
      unknown?: number;
      whiteDraw?: number;
      whiteLoss?: number;
      whiteWin?: number;
      win?: number;
      zeroPointBye?: number;
    }

    TeamRoundResult

    Team round-by-round result record (tags 801 and 802). One entry per line in the TRF file. Tag 802 uses structured per-round fields; tag 801 stores raw per-round strings.

    interface TeamRoundResult {
      gamePoints: number;
      matchPoints: number;
      nickname?: string;
      results: TeamRoundResult801[] | TeamRoundResult802[];
      tag: '801' | '802';
      teamId: number;
    }

    interface TeamRoundResult801 {
      opponentId: number | null;
      raw: string; // e.g. 'b =0=1 1234'
      round: number;
      type?: 'FPB' | 'HPB' | 'PAB' | 'ZPB';
    }

    interface TeamRoundResult802 {
      color?: 'b' | 'w';
      forfeit?: boolean;
      gamePoints: number;
      opponentId: number | null;
      round: number;
      type?: 'FPB' | 'HPB' | 'PAB' | 'ZPB';
    }

    ParseOptions

    interface ParseOptions {
      onError?: (error: ParseError) => void;
      onWarning?: (warning: ParseWarning) => void;
    }

    ParseError

    Reported via ParseOptions.onError when parsing fails unrecoverably. When an error is reported, parse() returns null.

    interface ParseError {
      column: number; // 1-based column in the source
      line: number; // 1-based line in the source
      message: string;
      offset: number; // byte offset in the source
    }

    ParseWarning

    Reported via ParseOptions.onWarning (or StringifyOptions.onWarning) for recoverable issues. Parsing continues after a warning.

    interface ParseWarning {
      column: number; // 1-based column in the source
      line: number; // 1-based line in the source (player index for stringify)
      message: string;
      offset: number; // byte offset in the source (0 for stringify)
    }

    StringifyOptions

    interface StringifyOptions {
      onWarning?: (warning: ParseWarning) => void;
    }

    ResultCode

    type ResultCode =
      | '+' // forfeit win
      | '-' // forfeit loss
      | '0' // loss
      | '1' // win
      | '=' // draw
      | 'D' // draw (unrated game, less than one move)
      | 'F' // full-point bye
      | 'H' // half-point bye
      | 'L' // loss (unrated game, less than one move)
      | 'U' // unplayed
      | 'W' // win (unrated game, less than one move)
      | 'Z'; // zero-point bye

    Sex

    type Sex = 'm' | 'w';

    Title

    FIDE title codes.

    type Title = 'CM' | 'FM' | 'GM' | 'IM' | 'WCM' | 'WFM' | 'WGM' | 'WIM';

    Version

    type Version = 'TRF16' | 'TRF26';
    Format Status Description
    TRF16 Full FIDE TRF standard (2016)
    TRF26 Full FIDE TRF standard (2026), all tags including 162, 192, 172, 222, 352, 362
    TRFx Full JaVaFo extensions (XXC, XXZ, XXP, XXA, XXS)

    The Tournament Report File (TRF) format is defined in the FIDE Handbook. TRF16 is the 2016 standard; TRF26 was approved by FIDE Council on 12/05/2025 and applied from 01/09/2025. TRFx is the de facto extension format used by JaVaFo, the FIDE reference pairing engine.

    MIT

    Settings

    Member Visibility

    On This Page

    TRF