npm package: 27-lowball-evaluator
Description: 2-7 (Deuce-to-Seven) Lowball poker hand evaluator. Correctly handles aces high, straights/flushes count against you.
Author: cyberfyed
Latest version: 1.0.1

# 2-7 Lowball Hand Evaluator

A JavaScript poker hand evaluator for **2-7 (Deuce-to-Seven) Lowball** variants including Triple Draw and Single Draw.

## Features

- Correctly handles **aces as high** (not low like A-5 lowball)
- **Straights and flushes count against you** (as per 2-7 rules)
- Identifies special hands: Number One (7-5-4-3-2), Number Two, etc.
- Compare hands and find winners
- Zero dependencies

## Installation

```bash
npm install 27-lowball-evaluator
```

## Usage

### Evaluate a Single Hand

```javascript
const { LowballHand } = require('27-lowball-evaluator');

const hand = LowballHand.solve(['7h', '5c', '4d', '3s', '2h']);

console.log(hand.descr);      // "7-5-4-3-2 (Number One)"
console.log(hand.name);       // "Seven Low"
console.log(hand.handTypeName); // "High Card"
console.log(hand.rank);       // Lower is better
```

### Compare Two Hands

```javascript
const { LowballHand } = require('27-lowball-evaluator');

// Returns: -1 if first wins, 1 if second wins, 0 if tie
const result = LowballHand.compare(
  ['7h', '5c', '4d', '3s', '2h'],  // Number One
  ['8h', '6c', '4d', '3s', '2h']   // 8-low
);
console.log(result); // -1 (first hand wins)
```

### Find Winner(s) from Multiple Hands

```javascript
const { LowballHand } = require('27-lowball-evaluator');

const hands = [
  LowballHand.solve(['7h', '5c', '4d', '3s', '2h']),
  LowballHand.solve(['8h', '6c', '4d', '3s', '2h']),
  LowballHand.solve(['9h', '7c', '5d', '3s', '2h']),
];

const winners = LowballHand.winners(hands);
console.log(winners[0].descr); // "7-5-4-3-2 (Number One)"
```

### Instance Methods

```javascript
const hand1 = LowballHand.solve(['7h', '5c', '4d', '3s', '2h']);
const hand2 = LowballHand.solve(['8h', '6c', '4d', '3s', '2h']);

hand1.beats(hand2);    // true
hand1.ties(hand2);     // false
hand1.compareTo(hand2); // negative (hand1 is better)
```

## Card Format

Cards are represented as strings: `rank + suit`

- **Ranks**: `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `T` (or `10`), `J`, `Q`, `K`, `A`
- **Suits**: `h` (hearts), `d` (diamonds), `c` (clubs), `s` (spades)

Examples: `'7h'`, `'As'`, `'Td'`, `'2c'`

## 2-7 Lowball Rules

In 2-7 (Deuce-to-Seven) Lowball:

1. **Aces are always HIGH** - A-2-3-4-5 is NOT a straight, it's A-high
2. **Straights count against you** - 6-5-4-3-2 is a straight (bad)
3. **Flushes count against you** - All same suit is bad
4. **Best possible hand**: 7-5-4-3-2 unsuited (called "Number One" or "the wheel")

### Hand Rankings (Best to Worst)

1. High Card (no pair, no straight, no flush) - **BEST**
2. One Pair
3. Two Pair
4. Three of a Kind
5. Straight
6. Flush
7. Full House
8. Four of a Kind
9. Straight Flush - **WORST**

### Top 10 Hands

1. 7-5-4-3-2 (Number One)
2. 7-6-4-3-2 (Number Two)
3. 7-6-5-3-2 (Number Three)
4. 7-6-5-4-2 (Number Four)
5. 8-5-4-3-2
6. 8-6-4-3-2
7. 8-6-5-3-2
8. 8-6-5-4-2
9. 8-6-5-4-3
10. 8-7-4-3-2

## API Reference

### `LowballHand.solve(cards)`
Create and evaluate a hand from an array of 5 card strings.

### `LowballHand.compare(cards1, cards2)`
Compare two hands. Returns `-1` if first wins, `1` if second wins, `0` for tie.

### `LowballHand.winners(hands)`
Find winner(s) from an array of LowballHand instances. Returns array (can have multiple for ties).

### Instance Properties
- `hand.rank` - Numeric rank (lower is better)
- `hand.handType` - Hand type constant (HIGH_CARD, ONE_PAIR, etc.)
- `hand.handTypeName` - Human-readable type ("High Card", "One Pair", etc.)
- `hand.name` - Short name ("Seven Low", "One Pair")
- `hand.descr` - Detailed description ("7-5-4-3-2 (Number One)")
- `hand.cards` - Original card array
- `hand.sortedRanks` - Ranks sorted high to low

## License

MIT