holdem_card_deck v1.0.4

Card Deck

Implementation of a deck of cards for Texas Hold'em.

Usage

This library is designed for playing hands of Texas Hold'em. The flow should look like:

// 1. Create a new card deck and shuffle it
const cardDeck = CardDeck.createDefaultDeck();
cardDeck.shuffle();

// 2. "Deal" out the hole cards
const p1HoleCards = [cardDeck.popBack(), cardDeck.popBack()];
const p2HoleCards = [cardDeck.popBack(), cardDeck.popBack()];

// 3. "Deal" the community cards
const communityCards = [cardDeck.popBack(), cardDeck.popBack(), cardDeck.popBack(), cardDeck.popBack(), cardDeck.popBack()];

// 4. Evaluate the hands
const results = HoldemHandEvaluator.evaluateHands(communityCards, [p1HoleCards, p2HoleCards]);

// 5. Run business logic on the results
results.map((result: [number, Hand<ValidHand>], index: number) => {
  const [rank, hand] = result;
  if (rank === 0) {
    console.log(`Player at ${index} won with ${hand.toString()});
  }
});

Documentation

Cards

• Card - represents a single playing card

  • toString(): string - debug string
  • value: Value - the rank or value of the card (Value.ACE, Value,KING, Value.QUEEN, etc.)
  • suit: Suit - the suit of the card (Suit.CLUBS, Suit.DIAMONDS, Suit.HEARTS, Suit.SPADES)

• Suit - enum for the suits

• Value - enum for every value from Ace to King

• CardDeck - abstraction around a deck of Cards

  • static createDefaultDeck(): CardDeck - create a standard 52 card deck
  • constructor(deck: Card[]) - constructor for initializing a CardDeck instance
  • shuffle(): void - does a Fisher-Yates shuffle on the current cards of the deck
  • length(): number - returns the number of cards currently in the deck
  • popBack(): Card - removes the last Card and returns it
  • toString(): string - debug string
  • cards: Card[] - array of the current list of cards

Evaluators

• HandEvaluator - evaluator for a set of five cards

  • static evaluateHand(cards: [Card, Card, Card, Card, Card]): Hand<ValidHand> - evalutes a set of five cards to the best possible hand it contains using the histogram method

• HoldemHandEvaluator - evaluator designed for holdem's use case of community and hole cards

  • static evaluateHand(cards: [Card, Card, Card, Card, Card, Card, Card]): Hand<ValidHand> - returns the best possible hand made with five cards of the seven
  • static evaluateHands(communityCards: [Card, Card, Card, Card, Card], holeCards: [Card, Card][]): [number, Hand<ValidHand>][] - given the five community cards and an array representing the players' hole cards, determine the hand each player has and their rank. The returned array is always equal to the size of the holeCards array. It contains tuples of the hand rank (0 first) with the corresponding Hand. Note that ties will be represented by having the same rank.

Hands

• ValidHand - typescript typing of all valid holdem hands
• HandRank - enum of all valid holdem hands with an associated number describing their rank

• Hand - abstract class that all hands inherit from

  • comparedTo(other: Hand<ValidHand>): number - compare this hand instance to another instance. Returns +1 of the current instance is greater, 0 if they're equal, and -1 if the current instance is smaller. It does this by first comparing HandRank and then calling compareOther
  • abstract compareOther(other: T): number - compare two hands of the same hand rank. This must be implemented by child classes. As an example, this would let us compare two OnePairs by looking at who has the higher pair and then the better kickers.
  • abstract toString - debug string
  • abstract validate - throws an InvalidHandType if the hand is invalid. Note that validity is based on that the cards contain a hand that's at least of this hand rank. For instance, OnePair will check that it contains a pair, even though it could contain a full house. Generally, the library relies on using HandEvaluator.evaluateHand to return the best possible hand.

• The following classes all extend Hand:

  • HighCard
  • OnePair
  • TwoPair
  • ThreeOfAKind
  • Straight
  • Flush
  • FullHouse
  • FourOfAKind
  • StraightFlush
  • RoyalFlush

Validation

• Hand validation checks that they are at least the hand they see they are. A fullhouse could get validated as a one pair. But a one pair would fail validation as a two pair.

Development

• Building: yarn build
• Testing: yarn test
• Test coverage: yarn coverage
• Test that the combinations are correct: yarn test-combinations
• Lint: yarn lint

Order of Reading

• cards/Card.ts
• cards/CardDeck.ts
• hands/Hand.ts
• evaluate/HandEvaluator.ts
• evaluate/HoldemHandEvaluator.ts
• tests/all_combinations.test.ts