🎯 Type-Safe Bingo Board Generator & Judge

A simple and type-safe Bingo board library written in TypeScript.
Supports board generation and win-condition checking (bingo, waiting, none), including free-space handling.

Features

• ✅ Type-safe number ranges per column (B/I/N/G/O)
• 🎲 Deterministic and random board generation
• 🧠 Bingo judgment logic (row, column, diagonal)
• 🟩 free space handled correctly (center cell)
• 🧪 Fully tested with Vitest

Installation

npm install bingo-ts
# or
yarn add bingo-ts

Usage

Generate a Board

import { generateBoard } from 'bingo-ts';

const board = generateBoard();
/*
[
  [ 5,   7,  13,  2,  15 ],
  [ 19, 24, 27, 22, 30 ],
  [ 33, 41, 'free', 39, 44 ],
  [ 48, 53, 56, 52, 60 ],
  [ 62, 66, 70, 68, 75 ]
]
*/

Create a Board

import { createBoard } from 'bingo-typescript';

const cells = [
  // B column (1-15)
  1, 2, 3, 4, 5,
  // I column (16-30)
  16, 17, 18, 19, 20,
  // N column (31-45)
  31, 32, 'free', 33, 34,
  // G column (46-60)
  46, 47, 48, 49, 50,
  // O column (61-75)
  61, 62, 63, 64, 65
];
const board = createBoard(cells);

Judge a Board

import { judgeBoard } from 'bingo-ts';

const openedNumbers = [5, 7, 13, 2, 15]; // First row
const result = judgeBoard(board, openedNumbers);

/*
Possible result:
{
  status: 'bingo',
  bingos: [{ line: [...] }],
  waitings: []
}
*/

Types

type Num = 1 | 2 | ... | 75;          // Number from 1 to 75
type Cell = Num | 'free';            // A cell in the board
type Board = Cell[5][5];             // 5x5 board with 'free' in the center
type Result = Bingo | Waiting | None;

type Bingo = {
  status: 'bingo';
  bingos: { line: Line }[];
  waitings: { line: Line; remaining: Num }[];
};

type Waiting = {
  status: 'waiting';
  waitings: { line: Line; remaining: Num }[];
};

type None = {
  status: 'none';
};

Testing

npm run test

Tests are written with Vitest and cover board generation, uniqueness, valid ranges, and bingo logic.

License

MIT