Fischer960

A Fischer Random Chess / Chess960 JavaScript library based on algorithms.

let sp = fischer.random()

sp.id // -> 518
sp.arrangement // -> ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']

Install

npm: npm i fischer960
yarn: yarn add fischer960
pnpm: pnpm add fischer960

Use

One can import only the functions to be used:

import { random, toString, toUnicode } from 'fischer960'

But importing the whole library will let you write fischer.random() 😎

import * as fischer from 'fischer960'
let sp = fischer.random()

A few things to be aware of:

• IDs are zero-indexed (0-959, the standard starting position being 518)
• random() and decode() return the arrangement as an array (to convert the array to a string, see toString())
• All arrangement arguments can take either an array (['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']) or a string ('BBQNNRKR')

Main functions

random()

Generates a random starting position, returning its ID and arrangement of pieces.

random() // -> eg. { id: 518, arrangement: ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R'] }

randomID()

Picks a random starting position's ID.

randomID() // -> eg. 518

decode(id)

Given an ID, returns the starting position's arrangement of pieces, or false if the ID is invalid.

decode(518) // -> eg. ['R', 'N', 'B', 'Q', 'K', 'B', 'N', 'R']

encode(arrangement)

Given an arrangement of pieces, returns the starting position's ID, or -1 if the arrangement is invalid.

encode('RKRNNQBB') // -> 959

Helper functions

A set of helper functions for manipulating arrangements are also provided.

Except for toString() and toArray(), these functions return the same type as was provided (if you pass a string you get a string, if you pass an array you get an array). Except for toLowerCase() and toUpperCase(), these also return the same case as was provided.

toString(arrangement)

Converts an arrangement of pieces from Array to String.

toString(['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']) // -> 'BBQNNRKR'

toArray(arrangement)

Converts an arrangement of pieces from String to Array.

toArray('BBQNNRKR') // -> ['B', 'B', 'Q', 'N', 'N', 'R', 'K', 'R']

toLowerCase(arrangement)

Converts an arrangement of pieces to lowercase notation.

toLowerCase('BBQNNRKR') // -> 'bbqnnrkr'

toUpperCase(arrangement)

Converts an arrangement of pieces to uppercase notation.

toUpperCase('bbqnnrkr') // -> 'BBQNNRKR'

toMirror(arrangement)

Mirrors an arrangement of pieces (returns its “twin”).

toMirror('BBQNNRKR') // -> 'RKRNNQBB'

toUnicode(arrangement, color)

Converts an arrangement of pieces to Unicode symbols.

The color argument is optional and defaults to white (falsy = white, truthy = black).

Note: There's no way to convert back to letters from Unicode symbols.

toUnicode('BBQNNRKR') // -> '♗♗♕♘♘♖♔♖'
toUnicode('BBQNNRKR', true) // -> '♝♝♛♞♞♜♚♜'

isValidArrangement(arrangement)

Validates a starting position's arrangement of pieces.

isValidArrangement('BBQNNRKR') // -> true
isValidArrangement('KQRBRBNN') // -> false (not a valid starting position)

isValidID(id)

Validates a starting position's ID.

Note: 960 is not a valid ID, as this library uses zero-based IDs.

isValidID(0) // -> true
isValidID(960) // -> false

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

1.0.0 - 2022-10-25

Added

• This CHANGELOG file (retroactive)
• .editorconfig file

Changed

• Test runner from AVA to Jest
• Renamed .js files .mjs so tests would run
• Updated dependencies
• Cleaned up README

Removed

• Benchmarks, as they're no longer useful
• Strong random number generator, as it's overkill adding complexity
• Cleaned up dependencies

0.3.2 - 2019-11-06

Added

• fischer.random() and fischer.randomID() (85b6dcf)
• API compatible random… functions to lookup.js (829d46d)
• Benchmark (3ba5747)

Changed

• Documentation and examples (7c49a8b)

Fixed

• Tests (87b444b)
• Examples for validation functions (9df819d)

Deprecated

• generate() is now deprecated (3788933)

0.3.1 - 2019-11-06

Changed

• Renamed validation functions to isValid…

This should cause a major version bump, but nobody's using this library yet anyway. And what's the point of rules if you can't break them? Guidelines > Rules.

0.3.0 - 2019-11-06

Added

• Validation of input (30bf090)
• AVA test runner and tests (553a70d)
• Debug config for VSCode (e8a9665)
• MIT license (d67f374)

Changed

• Improved documentation (2a9b407)