# 🎯 Tambola - Professional Tambola/Housie Ticket Generator

[![npm version](https://img.shields.io/npm/v/tambola.svg)](https://www.npmjs.com/package/tambola)
[![Build Status](https://img.shields.io/github/actions/workflow/status/geek4teck/tambola/build.yml?branch=main)](https://github.com/geek4teck/tambola/actions/workflows/build.yml)
[![Test Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen)](https://github.com/geek4teck/tambola)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)

> **The Ultimate Tambola/Housie Ticket Generator for Node.js** 🚀

Generate professional Tambola tickets and draw sequences with **zero dependencies**, **lightning-fast performance**, and **100% official game rule compliance**. Perfect for game organizers, developers, and anyone who needs reliable Tambola ticket generation.

## ✨ Why Choose Tambola?

### 🎯 **Official Game Compliance**
- ✅ Follows all official Tambola/Housie game rules
- ✅ Validates ticket structure and number distribution
- ✅ Ensures proper column ranges and ascending order
- ✅ Generates exactly 15 numbers per ticket (5 per row)

### ⚡ **Lightning Fast Performance**
- 🚀 **1000+ tickets per second** on modern hardware
- 🚀 **10,000+ sequences per second** for draw simulation
- 🚀 **Zero dependencies** - lightweight and fast
- 🚀 **Memory efficient** - no memory leaks

### 🛠️ **Developer Friendly**
- 📦 **Simple API** - just two functions to get started
- 🖥️ **CLI Support** - command-line interface included
- 📊 **Multiple Formats** - JSON, CSV, and table output
- 🧪 **Comprehensive Testing** - 84+ tests with 80%+ coverage

### 🌍 **Production Ready**
- 🔒 **Cross-platform** - works on all Node.js platforms
- 🔒 **Node.js 16+** compatibility
- 🔒 **CI/CD Pipeline** - automated testing and deployment
- 🔒 **Active Maintenance** - regular updates and improvements

## 🚀 Quick Start

### Installation
```bash
npm install tambola
```

### Basic Usage
```javascript
const tambola = require('tambola');

// Generate a professional Tambola ticket
const ticket = tambola.generateTicket();
console.log(ticket);
// Output: [[2, 0, 22, 0, 0, 56, 0, 71, 81], [0, 13, 0, 34, 45, 0, 65, 0, 88], [7, 19, 0, 39, 0, 59, 67, 0, 0]]

// Generate a random draw sequence (1-90)
const sequence = tambola.getDrawSequence();
console.log(sequence);
// Output: [37, 2, 89, 15, 73, 41, 8, 56, 23, ...]
```

### Command Line Interface
```bash
# Generate a ticket
npx tambola ticket

# Generate 5 tickets in JSON format
npx tambola ticket -c 5 -f json

# Generate draw sequence
npx tambola sequence

# Save to file
npx tambola ticket -o my_tickets.json
```

## 🎮 Perfect For

### 🏢 **Event Organizers**
- Generate hundreds of tickets for corporate events
- Create backup draw sequences
- Export to various formats for printing
- Ensure fair and random ticket distribution

### 👨‍💻 **Developers**
- Integrate into web applications
- Build Tambola game apps
- Create automated ticket systems
- Add to existing game platforms

### 🎯 **Game Enthusiasts**
- Organize family Tambola nights
- Create custom game variations
- Generate practice tickets
- Learn official game rules

### 🏫 **Educational Institutions**
- Teach probability and statistics
- Organize student events
- Create educational games
- Demonstrate random number generation

## 📊 Performance Benchmarks

| Operation | Speed | Memory Usage |
|-----------|-------|--------------|
| Ticket Generation | 1,000+ tickets/sec | ~216 bytes/ticket |
| Draw Sequence | 10,000+ sequences/sec | ~720 bytes/sequence |
| CLI Operations | Instant response | Minimal overhead |
| Batch Processing | 100,000+ items/min | Efficient memory usage |

## 🎯 Real-World Examples

### Event Management System
```javascript
const tambola = require('tambola');

// Generate tickets for a 500-person event
const eventTickets = [];
for (let i = 0; i < 500; i++) {
  eventTickets.push(tambola.generateTicket());
}

// Generate backup draw sequences
const drawSequences = [];
for (let i = 0; i < 3; i++) {
  drawSequences.push(tambola.getDrawSequence());
}

console.log(`Generated ${eventTickets.length} tickets and ${drawSequences.length} draw sequences`);
```

### Web Application Integration
```javascript
const express = require('express');
const tambola = require('tambola');

const app = express();

app.get('/api/ticket', (req, res) => {
  const ticket = tambola.generateTicket();
  res.json({ ticket, timestamp: new Date().toISOString() });
});

app.get('/api/sequence', (req, res) => {
  const sequence = tambola.getDrawSequence();
  res.json({ sequence, timestamp: new Date().toISOString() });
});
```

## 📚 Documentation

### 📖 **Complete Documentation**
- **[📋 API Reference](docs/API_REFERENCE.md)** - Complete API documentation with examples
- **[🖥️ CLI Guide](docs/CLI_GUIDE.md)** - Command-line interface usage
- **[🎮 Game Rules](docs/GAME_RULES.md)** - Official Tambola/Housie rules
- **[🧪 Testing Guide](docs/TESTING_GUIDE.md)** - Testing documentation
- **[🤝 Contributing](docs/CONTRIBUTING.md)** - How to contribute

### 🚀 **Quick Links**
- **[📦 NPM Package](https://www.npmjs.com/package/tambola)** - Install from npm
- **[🐙 GitHub Repository](https://github.com/geek4teck/tambola)** - Source code
- **[📊 GitHub Actions](https://github.com/geek4teck/tambola/actions)** - CI/CD status
- **[📝 Issues](https://github.com/geek4teck/tambola/issues)** - Report bugs & request features

## 🏆 Features at a Glance

| Feature | Description | Benefit |
|---------|-------------|---------|
| **Official Compliance** | Follows all Tambola rules | Legitimate game tickets |
| **High Performance** | 1000+ tickets/second | Fast batch processing |
| **Zero Dependencies** | No external packages | Lightweight & secure |
| **CLI Support** | Command-line interface | Easy automation |
| **Multiple Formats** | JSON, CSV, Table | Flexible output |
| **Comprehensive Tests** | 84+ tests, 80%+ coverage | Reliable & stable |
| **Cross-Platform** | Works everywhere | Universal compatibility |
| **Active Maintenance** | Regular updates | Long-term support |

## 🎯 Use Cases

### 🏢 **Corporate Events**
- Team building activities
- Holiday parties
- Fundraising events
- Client entertainment

### 🏠 **Family Gatherings**
- Birthday parties
- Holiday celebrations
- Weekend entertainment
- Educational activities

### 🎮 **Game Development**
- Mobile apps
- Web games
- Educational software
- Gaming platforms

### 📊 **Data Analysis**
- Probability studies
- Random number research
- Statistical analysis
- Algorithm testing

## 🔧 Technical Specifications

- **Node.js**: >= 16.0.0
- **Package Size**: < 50KB
- **Memory Usage**: Minimal
- **Dependencies**: Zero
- **License**: ISC
- **Platform**: Cross-platform

## 🚀 Getting Started

### 1. Install the Package
```bash
npm install tambola
```

### 2. Generate Your First Ticket
```javascript
const tambola = require('tambola');
const ticket = tambola.generateTicket();
console.log('Your Tambola ticket:', ticket);
```

### 3. Try the CLI
```bash
npx tambola ticket
npx tambola sequence
```

### 4. Explore Documentation
Visit the [📚 Complete Documentation](docs/README.md) for detailed guides and examples.

## 🤝 Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

- 📖 **[Contributing Guide](docs/CONTRIBUTING.md)** - How to contribute
- 🐛 **[Report Issues](https://github.com/geek4teck/tambola/issues)** - Bug reports & feature requests
- 💬 **[Discussions](https://github.com/geek4teck/tambola/discussions)** - Questions & community help

## 📄 License

This project is licensed under the [ISC License](LICENSE) - see the license file for details.

## 👨‍💻 Author

**Vishal Goyal** - [GitHub](https://github.com/geek4teck)

---

## 🎯 Ready to Get Started?

```bash
npm install tambola
```

**Join thousands of developers and game organizers who trust Tambola for their ticket generation needs!** 🚀

---

<div align="center">

**⭐ Star this repository if you find it useful!**

[![GitHub stars](https://img.shields.io/github/stars/geek4teck/tambola?style=social)](https://github.com/geek4teck/tambola/stargazers)
[![NPM downloads](https://img.shields.io/npm/dm/tambola.svg)](https://www.npmjs.com/package/tambola)

</div>