poker-extval 3.2.1 → 3.3.1

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,50 @@ 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`.
+- Supplying hole cards also restricts draws to those that use at least one hole card (see [Draws](#draws)).
+- 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 +191,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)
@@ -153,6 +211,8 @@ The `evaluateHand()` function returns an object where:
 - `isInsideStraightDraw` - One card away from straight (needed card in middle)
 - `isStraightDraw` - Any type of straight draw (open-ended or inside, standard or wheel)
 
+**Note**: When `holeCards` are supplied, every draw (including `isComboDraw` and the wheel draws) must use at least one hole card. A draw made entirely of board cards is shared by every player, so it is not reported: 2-2 on a 9-8-7-6 board is not an open-ended straight draw, and A♦-Q♦ on a K♠-7♠-2♠ flop is not a backdoor flush draw. Without `holeCards` the evaluator cannot tell the board from the hand, so draws are detected from all cards.
+
 #### Wheel Straight Support
 - `isStraightWheel` - Wheel straight (A-2-3-4-5)
 - `isOpenEndedStraightDrawWheel` - Open-ended draw using wheel ranking
@@ -162,6 +222,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 +414,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 +433,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 +464,7 @@ Main function to evaluate poker hands.
 #### Constructor
 
 ```javascript
-new HandEvaluator(cards, strict)
+new HandEvaluator(cards, strict, holeCards)
 ```
 
 Creates a new HandEvaluator instance.
@@ -407,14 +472,20 @@ 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.
 
+## Releasing
+
+Pushing to `main` publishes to npm via GitHub Actions (`.github/workflows/publish.yml`), using npm trusted publishing so no token is stored. Every push to `main` is released: the workflow runs the tests, bumps the patch version, commits the bump back to `main`, tags it `v<version>` and publishes. There is no need to bump the version by hand for patch releases. For a minor or major release, bump it in your change (`npm version minor|major --no-git-tag-version`); a version that is not on npm yet is published as is, without an extra bump.
+
 ## License
 
 MIT License

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];
     }
@@ -882,7 +954,8 @@ class HandEvaluator {
 
   /**
    * Determines if the hand has four cards of the same suit (one card away from a flush).
-   * Returns false if the hand is already a flush.
+   * Returns false if the hand is already a flush. When hole cards are supplied, at least one
+   * of the four suited cards must be a hole card.
    * 
    * @returns {boolean} True if the hand is a flush draw, false otherwise
    * @example
@@ -894,12 +967,13 @@ class HandEvaluator {
     if (this.evaluation.isFlush === undefined) this.#isFlush();
     if (this.evaluation.isFlush) return this.evaluation.isFlushDraw = false;
     const suits = this.#countSuits();
-    return this.evaluation.isFlushDraw = Object.values(suits).some(count => count === 4);
+    return this.evaluation.isFlushDraw = Object.keys(suits).some(s => suits[s] === 4 && this.#usesHoleCard(this.#getCardsOfSuit(s)));
   }
 
   /**
    * Determines if the hand has three cards of the same suit (two cards away from a flush).
-   * Returns false if the hand is already a flush or flush draw.
+   * Returns false if the hand is already a flush or flush draw. When hole cards are supplied,
+   * at least one of the three suited cards must be a hole card.
    * 
    * @returns {boolean} True if the hand is a backdoor flush draw, false otherwise
    * @example
@@ -912,7 +986,7 @@ class HandEvaluator {
     if (this.evaluation.isFlushDraw === undefined) this.#isFlushDraw();
     if (this.evaluation.isFlush || this.evaluation.isFlushDraw) return this.evaluation.isBackdoorFlushDraw = false;
     const suits = this.#countSuits();
-    return this.evaluation.isBackdoorFlushDraw = Object.values(suits).some(count => count === 3);
+    return this.evaluation.isBackdoorFlushDraw = Object.keys(suits).some(s => suits[s] === 3 && this.#usesHoleCard(this.#getCardsOfSuit(s)));
   }
 
   // ==================== STRAIGHT EVALUATION ====================
@@ -1008,6 +1082,7 @@ class HandEvaluator {
   /**
    * Determines if the hand is an open-ended straight draw (one card away from a straight on either end).
    * Checks both standard and wheel-equivalent open-ended draws.
+   * When hole cards are supplied, the four drawing cards must include at least one hole card.
    * Returns false if the hand already contains pairs, two pair, three of a kind, full house, four of a kind, or a straight.
    * 
    * @returns {boolean} True if the hand is an open-ended straight draw, false otherwise
@@ -1028,8 +1103,7 @@ class HandEvaluator {
       if (this.#isOpenEndedStraightDrawWheel()) return this.evaluation.isOpenEndedStraightDraw = true;
       return this.evaluation.isOpenEndedStraightDraw = false;
     }
-    this.#sort();
-    const result = this.#getDistance(this.cards.slice(0,4)) === 3 || this.#getDistance(this.cards.slice(1,5)) === 3;
+    const result = this.#findStraightDrawWindow([3], false) !== null;
     if (result) return this.evaluation.isOpenEndedStraightDraw = true;
     // Check wheel equivalent
     if (this.#isOpenEndedStraightDrawWheel()) return this.evaluation.isOpenEndedStraightDraw = true;
@@ -1052,13 +1126,13 @@ class HandEvaluator {
     if (this.evaluation.isFourOfAKind === undefined) this.#isFourOfAKind();
     if (this.evaluation.isStraightWheel === undefined) this.#isStraightWheel();
     if (this.evaluation.isPair || this.evaluation.isTwoPair || this.evaluation.isThreeOfAKind || this.evaluation.isFullHouse || this.evaluation.isFourOfAKind || this.evaluation.isStraightWheel) return this.evaluation.isOpenEndedStraightDrawWheel = false;
-    this.#sortWheel();
-    return this.evaluation.isOpenEndedStraightDrawWheel = this.#getDistanceWheel(this.cards.slice(0,4)) === 3 || this.#getDistanceWheel(this.cards.slice(1,5)) === 3;
+    return this.evaluation.isOpenEndedStraightDrawWheel = this.#findStraightDrawWindow([3], true) !== null;
   }
 
   /**
    * Determines if the hand is an inside straight draw (one card away from a straight, but the needed card is in the middle).
    * Checks both standard and wheel-equivalent inside draws.
+   * When hole cards are supplied, the four drawing cards must include at least one hole card.
    * Returns false if the hand already contains pairs, two pair, three of a kind, full house, four of a kind, or a straight.
    * 
    * @returns {boolean} True if the hand is an inside straight draw, false otherwise
@@ -1080,8 +1154,7 @@ class HandEvaluator {
       return this.evaluation.isInsideStraightDraw = false;
     }
 
-    this.#sort();
-    const result = this.#getDistance(this.cards.slice(0,4)) === 4 || this.#getDistance(this.cards.slice(1,5)) === 4;
+    const result = this.#findStraightDrawWindow([4], false) !== null;
     if (result) return this.evaluation.isInsideStraightDraw = true;
     // Check wheel equivalent
     if (this.#isInsideStraightDrawWheel()) return this.evaluation.isInsideStraightDraw = true;
@@ -1105,8 +1178,7 @@ class HandEvaluator {
     if (this.evaluation.isStraightWheel === undefined) this.#isStraightWheel();
     if (this.evaluation.isPair || this.evaluation.isTwoPair || this.evaluation.isThreeOfAKind || this.evaluation.isFullHouse || this.evaluation.isFourOfAKind || this.evaluation.isStraightWheel) return this.evaluation.isInsideStraightDrawWheel = false;
 
-    this.#sortWheel();
-    return this.evaluation.isInsideStraightDrawWheel = this.#getDistanceWheel(this.cards.slice(0,4)) === 4 || this.#getDistanceWheel(this.cards.slice(1,5)) === 4;
+    return this.evaluation.isInsideStraightDrawWheel = this.#findStraightDrawWindow([4], true) !== null;
   }
 
   /**
@@ -1382,8 +1454,7 @@ class HandEvaluator {
     if (!this.evaluation.isFlushDraw) return [];
     const suits = this.#countSuits();
     const flushSuit = Object.keys(suits).find(s => suits[s] === 4);
-    return this.cards.filter(c => c.slice(-1) === flushSuit)
-      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+    return this.#getCardsOfSuit(flushSuit);
   }
 
   /**
@@ -1396,8 +1467,7 @@ class HandEvaluator {
     if (!this.evaluation.isBackdoorFlushDraw) return [];
     const suits = this.#countSuits();
     const flushSuit = Object.keys(suits).find(s => suits[s] === 3);
-    return this.cards.filter(c => c.slice(-1) === flushSuit)
-      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+    return this.#getCardsOfSuit(flushSuit);
   }
 
   /**
@@ -1408,7 +1478,7 @@ class HandEvaluator {
    */
   #getKeyCardsForOpenEndedStraightDraw() {
     if (!this.evaluation.isOpenEndedStraightDraw) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([3]);
   }
 
   /**
@@ -1419,7 +1489,7 @@ class HandEvaluator {
    */
   #getKeyCardsForInsideStraightDraw() {
     if (!this.evaluation.isInsideStraightDraw) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([4]);
   }
 
   /**
@@ -1460,6 +1530,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).
    * 
@@ -1479,7 +1575,7 @@ class HandEvaluator {
    */
   #getKeyCardsForOpenEndedStraightDrawWheel() {
     if (!this.evaluation.isOpenEndedStraightDrawWheel) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([3]);
   }
 
   /**
@@ -1490,7 +1586,7 @@ class HandEvaluator {
    */
   #getKeyCardsForInsideStraightDrawWheel() {
     if (!this.evaluation.isInsideStraightDrawWheel) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([4]);
   }
 
   /**
@@ -1539,6 +1635,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 +1662,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
@@ -1572,41 +1683,64 @@ class HandEvaluator {
 
   /**
    * Helper method to extract the 4 cards that form a straight draw.
-   * Handles both standard and wheel straight draws.
+   * Handles both standard and wheel straight draws, preferring a standard draw.
+   * When hole cards are supplied, only draws that use at least one hole card are returned.
    * 
    * @private
+   * @param {number[]} [distances=[3, 4]] - Accepted rank spans for the 4 drawing cards
+   *   (3 = open-ended, 4 = inside)
    * @returns {string[]} Array of 4 cards forming the draw, sorted from highest to lowest
    */
-  #getStraightDrawCards() {
-    // Try standard straight draw
-    this.#sort();
-    const firstFour = this.cards.slice(0, 4);
-    const lastFour = this.cards.slice(1, 5);
-    
-    const firstFourDist = this.#getDistance(firstFour);
-    if (firstFourDist === 3 || firstFourDist === 4) {
-      return [...firstFour].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    const lastFourDist = this.#getDistance(lastFour);
-    if (lastFourDist === 3 || lastFourDist === 4) {
-      return [...lastFour].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    // Try wheel straight draw
-    this.#sortWheel();
-    const firstFourWheel = this.cards.slice(0, 4);
-    const lastFourWheel = this.cards.slice(1, 5);
-    
-    const firstFourDistWheel = this.#getDistanceWheel(firstFourWheel);
-    if (firstFourDistWheel === 3 || firstFourDistWheel === 4) {
-      return [...firstFourWheel].sort((a, b) => this.#getRankValueWheel(b) - this.#getRankValueWheel(a));
-    }
-    const lastFourDistWheel = this.#getDistanceWheel(lastFourWheel);
-    if (lastFourDistWheel === 3 || lastFourDistWheel === 4) {
-      return [...lastFourWheel].sort((a, b) => this.#getRankValueWheel(b) - this.#getRankValueWheel(a));
+  #getStraightDrawCards(distances = [3, 4]) {
+    return this.#findStraightDrawWindow(distances, false) || this.#findStraightDrawWindow(distances, true) || [];
+  }
+
+  /**
+   * Finds 4 rank-adjacent cards (the highest four or the lowest four) whose rank span is one of
+   * the given distances. When hole cards are supplied, a window made only of board cards is
+   * skipped, since a draw the board gives every player is not the player's draw.
+   * 
+   * @private
+   * @param {number[]} distances - Accepted rank spans for the 4 cards (3 = open-ended, 4 = inside)
+   * @param {boolean} wheel - If true, ranks the Ace low (for wheel draws)
+   * @returns {string[]|null} Array of 4 cards sorted from highest to lowest, or null if none match
+   */
+  #findStraightDrawWindow(distances, wheel) {
+    const rankValue = wheel ? c => this.#getRankValueWheel(c) : c => this.#getRankValue(c);
+    if (wheel) this.#sortWheel(); else this.#sort();
+    for (const window of [this.cards.slice(0, 4), this.cards.slice(1, 5)]) {
+      const distance = wheel ? this.#getDistanceWheel(window) : this.#getDistance(window);
+      if (distances.includes(distance) && this.#usesHoleCard(window)) {
+        return [...window].sort((a, b) => rankValue(b) - rankValue(a));
+      }
     }
-    
-    return [];
+    return null;
+  }
+
+  /**
+   * Gets the cards of a given suit in the hand, sorted from highest to lowest rank.
+   * 
+   * @private
+   * @param {string} suit - Suit character (s, h, d, c)
+   * @returns {string[]} Cards of that suit
+   */
+  #getCardsOfSuit(suit) {
+    return this.cards.filter(c => c.slice(-1) === suit)
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Determines whether a draw's cards include at least one of the player's hole cards.
+   * A draw made entirely of board cards is shared by every player, so when hole cards are
+   * supplied it does not count as the player's draw. Without hole cards every draw qualifies.
+   * 
+   * @private
+   * @param {string[]} cards - The cards forming the draw
+   * @returns {boolean} True if no hole cards were supplied or a hole card is among the cards
+   */
+  #usesHoleCard(cards) {
+    if (!this.holeCards) return true;
+    return cards.some(c => this.holeCards.includes(c));
   }
 
   // ==================== HIGH CARD ====================
@@ -1667,6 +1801,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 +1919,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.1",
   "description": "Poker hand evaluator with comprehensive test suite",
   "main": "evaluator.js",
   "files": [