Poker Nuts Practice CLI

A minimal TypeScript CLI for practicing poker nuts identification on flop scenarios in Texas Hold'em.

♠ ♥ Try the Live Demo! ♦ ♣

Features

• Random flop generation with seedable RNG for reproducible games
• Interactive nuts guessing with multiple input formats (AA, KQs, A5o, AhQh)
• Comprehensive hand evaluation covering all poker hand types
• Smart pattern canonicalization for suited/offsuit requirements
• Test-driven development with 100% test coverage

Installation

Global Installation (Recommended)

npm install -g poker-nuts-practice

# Then run anywhere:
pokernuts

Local Development

# Clone and install
git clone https://github.com/yisselda/pokernuts.git
cd pokernuts
npm install

# Run tests
npm test

# Start playing
npm run cli

# Play with specific seed for reproducible flops
npm run cli -- -seed=12345

Architecture

• src/engine.ts - Core poker logic, hand evaluation, nuts calculation
• src/cli.ts - Interactive command-line interface
• tests/engine.test.ts - Comprehensive test suite

Technical Details

• Language: TypeScript with Node.js
• Testing: Vitest framework
• RNG: Custom seedable Linear Congruential Generator
• Performance: Single nuts calculation <100ms
• Hand Types: Royal flush, quads, full house, flush, straight, trips, two pair, pair, high card

Programmatic API

Use the poker engine in your own applications:

React/React Native

import { createRNG, dealFlop, evaluateNuts, validateGuess } from 'poker-nuts-practice/engine'

function PokerGame() {
  const [rng] = useState(() => createRNG())
  const [flop, setFlop] = useState([])

  const dealNewFlop = () => setFlop(dealFlop(rng))

  const handleGuess = (guess) => {
    const result = validateGuess(flop, guess)
    // result.correct, result.reason, result.canonicalNuts
    return result
  }

  return <YourPokerUI />
}

Node.js/Custom CLI

import { createRNG, dealFlop, evaluateNuts, formatCard } from 'poker-nuts-practice/engine'

const rng = createRNG(42) // Optional seed for deterministic results
const flop = dealFlop(rng)
const nuts = evaluateNuts(flop)

console.log(`Flop: ${flop.map(formatCard).join(' ')}`)
console.log(`Nuts: ${nuts.patterns.join(', ')} (${nuts.explanation})`)

Available Functions

• createRNG(seed?) - Create seedable random number generator
• dealFlop(rng) - Deal 3-card flop
• evaluateNuts(flop) - Find nuts for given flop
• validateGuess(flop, guess) - Validate user guess
• formatCard(card) - Format card as "Ah", "Ks", etc.
• parseCard(string) - Parse card string to Card object

🎯 Complete Examples

See the examples/ directory for full working implementations:

• React Web App - Interactive UI with real-time validation
• React Native - Mobile poker practice app
• Node.js Bot - Automated flop analysis
• Custom CLI - Build your own poker tools

Each example is ready to run with npm install && npm start!

Development

# Run tests in watch mode
npm run dev:test

# Build TypeScript
npm run build

# Run built JavaScript
npm start