https://github.com/ya-s-u/bingo-ts
🎱 A simple and type-safe Bingo board library written in TypeScript.
https://github.com/ya-s-u/bingo-ts
bingo typescript
Last synced: 4 months ago
JSON representation
🎱 A simple and type-safe Bingo board library written in TypeScript.
- Host: GitHub
- URL: https://github.com/ya-s-u/bingo-ts
- Owner: ya-s-u
- License: mit
- Created: 2025-05-15T14:08:09.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-05-26T03:50:19.000Z (5 months ago)
- Last Synced: 2025-06-06T06:30:43.610Z (4 months ago)
- Topics: bingo, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/bingo-ts
- Size: 27.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🎯 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
```bash
npm install bingo-ts
# or
yarn add bingo-ts
````
## Usage
### Generate a Board
```ts
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
```ts
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
```ts
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
```ts
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
```bash
npm run test
```
Tests are written with [Vitest](https://vitest.dev/) and cover board generation, uniqueness, valid ranges, and bingo logic.
## License
MIT