polyglot-book-js

A production-ready JavaScript/TypeScript library for reading Polyglot opening book files (.bin). Uses FEN strings as input and returns matching opening moves with weights.

Features

✅ Spec-compliant - Implements the official Polyglot Zobrist hashing algorithm
✅ Zero dependencies - No external chess libraries required
✅ TypeScript - Full type definitions included
✅ Cross-platform - Works in Node.js and browsers
✅ Efficient - Binary search for fast lookups
✅ Well-tested - Verified against official Polyglot test data

Installation

npm install polyglot-book-js

Quick Start

Node.js

import fs from 'fs';
import { getBookMoves } from 'polyglot-book-js';

// Read a Polyglot book file
const bookData = fs.readFileSync('book.bin');

// Get moves for the starting position
const startFEN = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
const moves = getBookMoves(startFEN, bookData);

console.log(moves);
// [
//   { uci: 'e2e4', weight: 5000, learn: 0, from: 12, to: 28 },
//   { uci: 'd2d4', weight: 3000, learn: 0, from: 11, to: 27 },
//   ...
// ]

Browser

import { getBookMoves } from 'polyglot-book-js';

// Fetch a book file
const response = await fetch('book.bin');
const bookData = await response.arrayBuffer();

// Get moves
const fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
const moves = getBookMoves(fen, bookData);

console.log(moves); // Sorted by weight (descending)

API Reference

getBookMoves(fen, bookData)

Get all book moves for a given position.

Parameters:

• fen (string) - FEN string representing the position
• bookData (ArrayBuffer | Uint8Array) - Polyglot book file data

Returns: BookMove[] - Array of moves sorted by weight (descending)

BookMove interface:

interface BookMove {
  uci: string;           // UCI notation (e.g., "e2e4", "e7e8q")
  weight: number;        // Move weight from the book
  learn: number;         // Learn value from the book
  from: number;          // From square (0-63)
  to: number;            // To square (0-63)
  promotion?: string;    // Promotion piece if applicable ('n', 'b', 'r', 'q')
}

computePolyglotHash(fen)

Compute the Polyglot Zobrist hash for a position.

Parameters:

• fen (string) - FEN string

Returns: bigint - 64-bit Zobrist hash

Example:

import { computePolyglotHash } from 'polyglot-book-js';

const hash = computePolyglotHash('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');
console.log(hash.toString(16)); // "463b96181691fc9c"

parseFEN(fen)

Parse a FEN string into structured data.

Parameters:

• fen (string) - FEN string

Returns: FENData - Parsed FEN components

Example:

import { parseFEN } from 'polyglot-book-js';

const data = parseFEN('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');
console.log(data.sideToMove); // 'w'
console.log(data.castling.whiteKingside); // true

Polyglot Book Format

This library implements the official Polyglot opening book specification:

• File format: Binary .bin files
• Entry size: 16 bytes per entry
  • 8 bytes: Zobrist hash key (big-endian)
  • 2 bytes: Encoded move (big-endian)
  • 2 bytes: Weight (big-endian)
  • 4 bytes: Learn value (big-endian)
• Sorting: Entries are sorted by hash key
• Lookup: Binary search for efficient retrieval

Zobrist Hashing

The library uses the official Polyglot Zobrist hashing algorithm:

• Random table: 781 pre-generated 64-bit values
• Piece hashing: XOR values based on piece type and square
• Castling: Individual flags for K, Q, k, q
• En passant: Hashed only if a legal capture exists
• Side to move: Hashed when it's White's turn

TypeScript Support

Full TypeScript definitions are included:

import { getBookMoves, BookMove, FENData } from 'polyglot-book-js';

const moves: BookMove[] = getBookMoves(fen, bookData);
const topMove: BookMove = moves[0];
console.log(topMove.uci); // Type-safe!

Error Handling

The library throws descriptive errors for invalid input:

try {
  const moves = getBookMoves('invalid fen', bookData);
} catch (error) {
  console.error(error.message); // "FEN must have at least 4 parts..."
}

Performance

• Binary search: O(log n) lookup time
• Memory efficient: Doesn't load entire book into memory
• BigInt operations: Proper 64-bit hash handling

Where to Get Polyglot Books

Popular Polyglot opening books:

• Performance.bin - Balanced opening repertoire
• Human.bin - Human-like opening choices
• Computer.bin - Engine-optimized openings

You can create custom books using tools like:

• polyglot make-book command
• Chess engine analysis tools

License

MIT © 2026

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Related Projects

• python-chess - Python chess library with Polyglot support
• Polyglot specification - Official format documentation

Acknowledgments

• Zobrist random table from the official Polyglot specification
• Test data verified against python-chess implementation