poker-extval 3.2.1 → 3.3.0

package/README.md

@@ -7,6 +7,7 @@ A comprehensive poker hand evaluation library for Node.js that evaluates poker h
 - **Comprehensive Hand Evaluation**: Evaluates all standard poker hand types (Royal Flush, Straight Flush, Four of a Kind, Full House, Flush, Straight, Three of a Kind, Two Pair, Pair, High Card)
 - **Strict Mode (Default)**: Only marks the strongest made hand and stronger draws, preventing weaker hands from being marked when stronger ones exist
 - **Detailed Categorization**: Categorizes pairs (Top, Middle, Bottom), two pairs, and three of a kind by position
+- **Overcard Categorization**: With hole cards supplied, classifies them against the board (two overcards, overcard and middle card, overcard and undercard, two middle cards, middle and undercard, two undercards)
 - **Draw Detection**: Identifies flush draws, backdoor flush draws, open-ended straight draws, and inside straight draws
 - **Key Cards and Kicker Cards**: Provides detailed card arrays showing which cards form each hand type and which are kickers
 - **Wheel Straight Support**: Handles Ace-low straights (A-2-3-4-5) correctly
@@ -56,6 +57,49 @@ const evaluation = evaluator.evaluation;
 const nonStrictEvaluator = new HandEvaluator(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
 ```
 
+### Overcards
+
+The overcard categorizations describe your **hole cards** relative to the **board**, so the evaluator needs to know which two of the cards are yours. Pass them as the third argument:
+
+```javascript
+const { evaluateHand } = require('poker-extval');
+
+const board = ['Ks', 'Qh', '8d', '3c'];
+const holeCards = ['Ad', 'Jh'];
+
+const result = evaluateHand([...board, ...holeCards], true, holeCards);
+const evaluation = result[Object.keys(result)[0]];
+
+evaluation.isOvercard;                // true  (the ace beats every board card)
+evaluation.isOvercardAndMiddleCard;   // true  (ace is an overcard, jack sits between 3 and K)
+evaluation.isTwoOvercards;            // false
+evaluation.keyCards.isOvercard;       // ['Ad']
+```
+
+Each hole card is classified against the board:
+
+| Classification | Meaning |
+| --- | --- |
+| Overcard | Rank is higher than every board card |
+| Middle card | Rank sits strictly between the highest and lowest board ranks |
+| Undercard | Rank is lower than every board card |
+| Paired | Rank matches a board card, so it belongs to none of the above |
+
+The two classifications combine into one (and only one) of the six categories below. If either hole card pairs the board, none of the six is true — though `isOvercard` can still be true on its own.
+
+```javascript
+// Board: K Q 8 3
+evaluateHand([...board, 'Ad', 'Kc'], true, ['Ad', 'Kc']);  // isOvercard only (the king pairs the board)
+evaluateHand([...board, 'Jd', 'Th'], true, ['Jd', 'Th']);  // isTwoMiddleCards
+evaluateHand([...board, '4d', '2h'], true, ['4d', '2h']);  // isMiddleAndUndercard (the 4 beats the 3)
+evaluateHand([...board, '2d', '2h'], true, ['2d', '2h']);  // isTwoUndercards
+```
+
+**Notes:**
+- Hole cards are optional. Without them every overcard property is `false`.
+- Both hole cards must appear in the `cards` array, but they do **not** have to appear in the 5-card combination being evaluated — the classification is a property of the whole hand and is identical across every combination.
+- These categorizations describe the hole cards, not the made hand, so **strict mode does not filter them**. A hand that flops a straight with A-J on a K-Q-T-3 board reports both `isStraight` and `isOvercardAndMiddleCard`.
+
 ### Strict Mode
 
 By default, the evaluator uses **strict mode** which only marks the strongest made hand and stronger draws as true. This prevents weaker hands from being marked when a stronger hand exists.
@@ -146,6 +190,19 @@ The `evaluateHand()` function returns an object where:
 - `isMiddleThreeOfAKind` - Three of a kind is neither highest nor lowest
 - `isBottomThreeOfAKind` - Three of a kind is the lowest rank
 
+#### Overcard Categorization (requires `holeCards`; not filtered by strict mode)
+- `isOvercard` - At least one hole card ranks above every board card
+- `isTwoOvercards` - Both hole cards rank above every board card
+- `isOvercardAndMiddleCard` - One overcard, one middle card
+- `isOvercardAndUndercard` - One overcard, one undercard
+- `isTwoMiddleCards` - Both hole cards sit strictly between the highest and lowest board ranks
+- `isMiddleAndUndercard` - One middle card, one undercard
+- `isTwoUndercards` - Both hole cards rank below every board card
+
+#### Other Categorization
+- `isUnderPair` - Pocket pair ranked below every other card in the hand (requires 6+ cards)
+- `isComboDraw` - Both a flush draw (not backdoor) and a straight draw
+
 #### Draws
 - `isFlushDraw` - Four cards of the same suit (one away from flush)
 - `isBackdoorFlushDraw` - Three cards of the same suit (two away from flush)
@@ -162,6 +219,8 @@ The `evaluateHand()` function returns an object where:
 - `keyCards` - Object with keys for each hand type/draw, values are arrays of cards (sorted) that constitute that specific hand type or draw. False hand types have empty arrays `[]`.
 - `kickerCards` - Object with keys for each hand type/draw, values are arrays of cards (sorted) that don't constitute that specific hand type or draw. False hand types have empty arrays `[]`, except `isHighCard` which contains all 5 cards when true.
 
+**Note**: For the overcard categorizations, `keyCards` holds the qualifying hole cards and `kickerCards` holds the remaining cards of the **full hand** (the board, plus any hole card that is not a key card) rather than the remaining cards of the 5-card combination.
+
 **Note**: Each hand type has its own `keyCards` and `kickerCards` entries. For example, a hand with both a pair and a flush draw will have separate entries in `keyCards.isPair`, `keyCards.isFlushDraw`, `kickerCards.isPair`, and `kickerCards.isFlushDraw`.
 
 ### Example Response
@@ -352,6 +411,7 @@ The evaluator validates input and throws descriptive errors for:
 - Invalid rank (not A, K, Q, J, T, 9-2)
 - Invalid suit (not s, h, d, c)
 - Duplicate cards
+- Hole cards that are not an array of exactly 2 distinct cards drawn from `cards`
 
 Example:
 ```javascript
@@ -370,23 +430,25 @@ Run the test suite:
 npm test
 ```
 
-The test suite includes 572+ tests covering:
+The test suite includes 700+ tests covering:
 - All hand types
 - Edge cases
 - Invalid input handling
 - Wheel straights
 - Draw detection
 - Categorization logic
+- Overcard categorization and hole card validation
 
 ## API Reference
 
-### `evaluateHand(cards, strict)`
+### `evaluateHand(cards, strict, holeCards)`
 
 Main function to evaluate poker hands.
 
 **Parameters:**
 - `cards` (string[]): Array of 5 or more card strings
 - `strict` (boolean, optional): If `true`, only the strongest made hand and stronger draws are marked. If `false`, all applicable hand types are marked (default: `true`).
+- `holeCards` (string[] | null, optional): Exactly 2 cards identifying the player's hole cards, both of which must appear in `cards`. Required for the overcard categorizations; without it those properties are always `false` (default: `null`).
 
 **Returns:**
 - Object mapping sorted hand strings to evaluation objects
@@ -399,7 +461,7 @@ Main function to evaluate poker hands.
 #### Constructor
 
 ```javascript
-new HandEvaluator(cards, strict)
+new HandEvaluator(cards, strict, holeCards)
 ```
 
 Creates a new HandEvaluator instance.
@@ -407,11 +469,13 @@ Creates a new HandEvaluator instance.
 **Parameters:**
 - `cards` (string[]): Array of 5 or more card strings
 - `strict` (boolean, optional): If `true`, only the strongest made hand and stronger draws are marked. If `false`, all applicable hand types are marked (default: `true`).
+- `holeCards` (string[] | null, optional): Exactly 2 cards identifying the player's hole cards, both of which must appear in `cards`. Required for the overcard categorizations (default: `null`).
 
 **Properties:**
 - `evaluation` - Object mapping sorted hand strings to evaluation objects (same format as `evaluateHand()` return value)
 - `cards` - Array of input cards
 - `strict` - Boolean indicating whether strict mode is enabled
+- `holeCards` - Array of the 2 hole cards, or `null` if none were supplied
 
 **Note**: All internal methods are private. Use the `evaluation` property to access evaluation results.
 

package/evaluator.js

@@ -19,6 +19,23 @@
  * const result = evaluator.evaluation;
  * // result contains 6 key-value pairs, one for each 5-card combination
  */
+/**
+ * Evaluation properties that categorize the player's hole cards relative to the board.
+ * These describe the two hole cards rather than a 5-card hand, so their kicker cards are
+ * drawn from the full hand (the board) rather than from the 5-card combination.
+ *
+ * @constant {Set<string>}
+ */
+const HOLE_CARD_CATEGORIES = new Set([
+  'isOvercard',
+  'isTwoOvercards',
+  'isOvercardAndMiddleCard',
+  'isOvercardAndUndercard',
+  'isTwoMiddleCards',
+  'isMiddleAndUndercard',
+  'isTwoUndercards'
+]);
+
 class HandEvaluator {
   /**
    * Creates an instance of HandEvaluator.
@@ -28,8 +45,12 @@ class HandEvaluator {
    *   - s is suit: s (spades), h (hearts), d (diamonds), c (clubs)
    * @param {boolean} [strict=true] - If true, only the strongest made hand and stronger draws are marked as true.
    *   If false, all applicable hand types are marked (current behavior).
+   * @param {string[]|null} [holeCards=null] - Optional array of exactly 2 cards identifying the player's
+   *   hole cards. Required for the overcard categorizations (isOvercard, isTwoOvercards, etc.); without it
+   *   those properties are always false. Both cards must be present in `cards`.
    * @throws {Error} If cards is not an array, has fewer than 5 cards, contains invalid format,
    *   invalid rank, invalid suit, or duplicate cards
+   * @throws {Error} If holeCards is provided but is not an array of exactly 2 distinct cards drawn from `cards`
    * @example
    * const evaluator = new HandEvaluator(['As', 'Ks', 'Qs', 'Js', 'Ts']);
    * @example
@@ -38,15 +59,65 @@ class HandEvaluator {
    * @example
    * // Non-strict mode - all applicable hands marked
    * const nonStrictEvaluator = new HandEvaluator(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
+   * @example
+   * // With hole cards - enables overcard categorization
+   * const withHoleCards = new HandEvaluator(['Ks', 'Qh', '8d', '3c', 'Ad', 'Jh'], true, ['Ad', 'Jh']);
    */
-  constructor(cards, strict = true, originalCards = null) {
+  constructor(cards, strict = true, holeCards = null, originalCards = null) {
     this.#validateCards(cards);
     this.cards = cards;
     this.strict = strict;
     this.originalCards = originalCards || (cards.length > 5 ? cards : null);
+    if (holeCards === null || holeCards === undefined) {
+      this.holeCards = null;
+    } else {
+      this.#validateHoleCards(holeCards, this.originalCards || cards);
+      this.holeCards = holeCards;
+    }
     this.evaluation = this.#evaluateAllCombinations();
   }
 
+  /**
+   * Validates the optional hole cards array.
+   * Hole cards must be exactly 2 distinct cards that appear in the full hand.
+   *
+   * @private
+   * @param {string[]} holeCards - Array of hole card strings to validate
+   * @param {string[]} fullHand - The complete set of cards the hole cards must be drawn from
+   * @throws {Error} If holeCards is not an array
+   * @throws {Error} If holeCards does not contain exactly 2 cards
+   * @throws {Error} If any hole card is not a string
+   * @throws {Error} If duplicate hole cards are found
+   * @throws {Error} If a hole card is not present in the full hand
+   */
+  #validateHoleCards(holeCards, fullHand) {
+    if (!Array.isArray(holeCards)) {
+      throw new Error('Hole cards must be an array');
+    }
+    if (holeCards.length !== 2) {
+      throw new Error(`Expected exactly 2 hole cards, received ${holeCards.length}`);
+    }
+
+    const handSet = new Set(fullHand);
+    const seenHoleCards = new Set();
+
+    for (let i = 0; i < holeCards.length; i++) {
+      const card = holeCards[i];
+
+      if (typeof card !== 'string') {
+        throw new Error(`Hole card at index ${i} must be a string`);
+      }
+      if (seenHoleCards.has(card)) {
+        throw new Error(`Duplicate hole card found: "${card}"`);
+      }
+      seenHoleCards.add(card);
+
+      if (!handSet.has(card)) {
+        throw new Error(`Hole card not found in cards: "${card}"`);
+      }
+    }
+  }
+
   /**
    * Validates the input cards array for correct format, length, and uniqueness.
    * 
@@ -201,6 +272,7 @@ class HandEvaluator {
     this.#isStraightDraw();
     this.#isComboDraw();
     this.#isUnderPair();
+    this.#isOvercards();
     this.#isHighCard();
     
     // Add keyCards and kickerCards before restoring original evaluation
@@ -418,7 +490,7 @@ class HandEvaluator {
     const result = {};
     for (const combination of combinations) {
       const key = this.#formatHandKey(combination);
-      const tempEvaluator = new HandEvaluator(combination, this.strict, this.originalCards);
+      const tempEvaluator = new HandEvaluator(combination, this.strict, this.holeCards, this.originalCards);
       const evaluationKey = Object.keys(tempEvaluator.evaluation)[0];
       result[key] = tempEvaluator.evaluation[evaluationKey];
     }
@@ -1460,6 +1532,32 @@ class HandEvaluator {
     return this.#getKeyCardsForPair();
   }
 
+  /**
+   * Gets key cards for the general overcard property (the hole cards that beat the whole board).
+   *
+   * @private
+   * @returns {string[]} Array of 1 or 2 overcards if isOvercard, empty array otherwise
+   */
+  #getKeyCardsForOvercard() {
+    if (!this.evaluation.isOvercard) return [];
+    const classifications = this.#classifyHoleCards();
+    return this.holeCards
+      .filter((card, i) => classifications[i] === 'over')
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for a two-card hole card categorization (both hole cards, sorted high to low).
+   *
+   * @private
+   * @param {string} category - The evaluation property name (e.g. 'isTwoOvercards')
+   * @returns {string[]} Array of both hole cards if the category is true, empty array otherwise
+   */
+  #getKeyCardsForHoleCardCategory(category) {
+    if (!this.evaluation[category]) return [];
+    return [...this.holeCards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
   /**
    * Gets key cards for wheel straight (5 cards forming wheel).
    * 
@@ -1539,6 +1637,13 @@ class HandEvaluator {
       isInsideStraightDrawWheel: this.#getKeyCardsForInsideStraightDrawWheel(),
       isComboDraw: this.#getKeyCardsForComboDraw(),
       isUnderPair: this.#getKeyCardsForUnderPair(),
+      isOvercard: this.#getKeyCardsForOvercard(),
+      isTwoOvercards: this.#getKeyCardsForHoleCardCategory('isTwoOvercards'),
+      isOvercardAndMiddleCard: this.#getKeyCardsForHoleCardCategory('isOvercardAndMiddleCard'),
+      isOvercardAndUndercard: this.#getKeyCardsForHoleCardCategory('isOvercardAndUndercard'),
+      isTwoMiddleCards: this.#getKeyCardsForHoleCardCategory('isTwoMiddleCards'),
+      isMiddleAndUndercard: this.#getKeyCardsForHoleCardCategory('isMiddleAndUndercard'),
+      isTwoUndercards: this.#getKeyCardsForHoleCardCategory('isTwoUndercards'),
       isHighCard: this.#getKeyCardsForHighCard()
     };
   }
@@ -1559,6 +1664,14 @@ class HandEvaluator {
         result[handType] = sortedCards;
       } else if (keyCards.length === 0) {
         result[handType] = [];
+      } else if (HOLE_CARD_CATEGORIES.has(handType)) {
+        // Hole card categorizations are evaluated against the board, which may include cards
+        // outside the current 5-card combination, so kickers come from the full hand.
+        const keyCardsSet = new Set(keyCards);
+        const fullHand = this.originalCards || this.cards;
+        result[handType] = fullHand
+          .filter(c => !keyCardsSet.has(c))
+          .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
       } else {
         const keyCardsSet = new Set(keyCards);
         result[handType] = this.cards
@@ -1667,6 +1780,95 @@ class HandEvaluator {
     return null;
   }
   
+  // ==================== OVERCARDS ====================
+
+  /**
+   * Classifies each hole card relative to the board (every card in the full hand that is not a
+   * hole card). A card is an "overcard" when its rank beats every board card, an "undercard" when
+   * every board card beats it, and a "middle card" when it falls strictly between the highest and
+   * lowest board ranks. A hole card whose rank matches any board rank pairs the board and is
+   * classified as "paired", which belongs to none of the three categories.
+   *
+   * @private
+   * @returns {string[]|null} Array of 2 classifications ('over', 'middle', 'under' or 'paired')
+   *   parallel to this.holeCards, or null if hole cards were not supplied
+   * @example
+   * // Board: K Q 8 3, hole cards: A J
+   * this.#classifyHoleCards(); // Returns ['over', 'middle']
+   */
+  #classifyHoleCards() {
+    if (!this.holeCards || this.holeCards.length !== 2) return null;
+
+    const fullHand = this.originalCards || this.cards;
+    const holeCardSet = new Set(this.holeCards);
+    const board = fullHand.filter(c => !holeCardSet.has(c));
+    if (board.length < 3) return null;
+
+    const boardRanks = new Set(board.map(c => c.slice(0, -1)));
+    const boardValues = board.map(c => this.#getRankValue(c));
+    const highestBoard = Math.max(...boardValues);
+    const lowestBoard = Math.min(...boardValues);
+
+    return this.holeCards.map(card => {
+      if (boardRanks.has(card.slice(0, -1))) return 'paired';
+      const value = this.#getRankValue(card);
+      if (value > highestBoard) return 'over';
+      if (value < lowestBoard) return 'under';
+      return 'middle';
+    });
+  }
+
+  /**
+   * Counts how many hole cards fall into each classification.
+   *
+   * @private
+   * @returns {Object} Object with 'over', 'middle', 'under' and 'paired' counts
+   */
+  #getHoleCardCounts() {
+    const counts = { over: 0, middle: 0, under: 0, paired: 0 };
+    const classifications = this.#classifyHoleCards();
+    if (classifications) {
+      for (const classification of classifications) counts[classification]++;
+    }
+    return counts;
+  }
+
+  /**
+   * Determines how the player's hole cards rank against the board and sets every overcard
+   * categorization property. Requires hole cards to have been supplied; without them all
+   * overcard properties are false.
+   *
+   * These categorizations describe the hole cards themselves, not the made hand, so they are
+   * identical across every 5-card combination of a hand and are not filtered by strict mode.
+   *
+   * Sets: isOvercard, isTwoOvercards, isOvercardAndMiddleCard, isOvercardAndUndercard,
+   * isTwoMiddleCards, isMiddleAndUndercard, isTwoUndercards.
+   *
+   * @returns {boolean} True if at least one hole card is an overcard, false otherwise
+   * @example
+   * // Board: K Q 8 3, Hand: AJ
+   * const evaluator = new HandEvaluator(['Ks', 'Qh', '8d', '3c', 'Ad', 'Jh'], true, ['Ad', 'Jh']);
+   * // isOvercard: true, isOvercardAndMiddleCard: true
+   * @example
+   * // Board: 9 7 4 2, Hand: AK (both hole cards beat every board card)
+   * const twoOvercards = new HandEvaluator(['9s', '7h', '4d', '2c', 'Ad', 'Kh'], true, ['Ad', 'Kh']);
+   * // isTwoOvercards: true
+   */
+  #isOvercards() {
+    if (this.evaluation.isOvercard !== undefined) return this.evaluation.isOvercard;
+
+    const counts = this.#getHoleCardCounts();
+
+    this.evaluation.isTwoOvercards = counts.over === 2;
+    this.evaluation.isOvercardAndMiddleCard = counts.over === 1 && counts.middle === 1;
+    this.evaluation.isOvercardAndUndercard = counts.over === 1 && counts.under === 1;
+    this.evaluation.isTwoMiddleCards = counts.middle === 2;
+    this.evaluation.isMiddleAndUndercard = counts.middle === 1 && counts.under === 1;
+    this.evaluation.isTwoUndercards = counts.under === 2;
+
+    return this.evaluation.isOvercard = counts.over > 0;
+  }
+
   /**
    * Determines if the hand is high card only (no pairs, two pair, three of a kind, full house,
    * four of a kind, flush, or straight).
@@ -1696,10 +1898,14 @@ class HandEvaluator {
  * @param {string[]} cards - Array of 5 or more card strings in format "Rs" where R is rank (A, K, Q, J, T, 9, 8, 7, 6, 5, 4, 3, 2) and s is suit (s, h, d, c)
  * @param {boolean} [strict=true] - If true, only the strongest made hand and stronger draws are marked as true.
  *   If false, all applicable hand types are marked.
+ * @param {string[]|null} [holeCards=null] - Optional array of exactly 2 cards identifying the player's hole cards.
+ *   Required for the overcard categorizations (isOvercard, isTwoOvercards, isOvercardAndMiddleCard,
+ *   isOvercardAndUndercard, isTwoMiddleCards, isMiddleAndUndercard, isTwoUndercards); without it those
+ *   properties are always false. Both cards must be present in `cards`.
  * @returns {Object} Object mapping sorted hand strings (e.g., "As, Ks, Qs, Js, Ts") to evaluation objects with boolean fields for all hand types and draws
  */
-function evaluateHand(cards, strict = true) {
-  const evaluator = new HandEvaluator(cards, strict);
+function evaluateHand(cards, strict = true, holeCards = null) {
+  const evaluator = new HandEvaluator(cards, strict, holeCards);
   return evaluator.evaluation;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poker-extval",
-  "version": "3.2.1",
+  "version": "3.3.0",
   "description": "Poker hand evaluator with comprehensive test suite",
   "main": "evaluator.js",
   "files": [