poker-extval 3.3.1 → 3.3.3

package/README.md

@@ -201,18 +201,20 @@ The `evaluateHand()` function returns an object where:
 - `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)
+- `isUnderPair` - Pocket pair ranked below every board card. With `holeCards` this works on any street, including the flop; without them the board is unknown, so it requires 6+ cards and means a pair ranked below every other card
 - `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)
-- `isOpenEndedStraightDraw` - One card away from straight on either end
-- `isInsideStraightDraw` - One card away from straight (needed card in middle)
+- `isOpenEndedStraightDraw` - Four in a row that a card at either end completes (e.g. 9-8-7-6). A-K-Q-J and A-2-3-4 complete at one end only, so they count as inside draws
+- `isInsideStraightDraw` - One card away from a straight that only one rank completes (a gap in the middle, or A-K-Q-J / A-2-3-4)
 - `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.
 
+**Note**: Straight draws count paired cards once, so a paired hand can still hold one: 5-4 on an 8-8-6 flop is a pair and an inside straight draw. With `holeCards`, a hole card that only pairs a board rank does not create a straight draw (9-2 on a 9-8-7-6 board has no straight draw of its own).
+
 #### Wheel Straight Support
 - `isStraightWheel` - Wheel straight (A-2-3-4-5)
 - `isOpenEndedStraightDrawWheel` - Open-ended draw using wheel ranking

package/evaluator.js

@@ -65,7 +65,8 @@ class HandEvaluator {
    */
   constructor(cards, strict = true, holeCards = null, originalCards = null) {
     this.#validateCards(cards);
-    this.cards = cards;
+    // Copy so that in-place sorting during evaluation never reorders the caller's array
+    this.cards = [...cards];
     this.strict = strict;
     this.originalCards = originalCards || (cards.length > 5 ? cards : null);
     if (holeCards === null || holeCards === undefined) {
@@ -370,11 +371,13 @@ class HandEvaluator {
   }
 
   /**
-   * Gets sorted key card ranks for an evaluation.
+   * Gets key card ranks for an evaluation, in tiebreak order.
+   * Ranks are grouped by how often they appear (so a full house compares its three of a kind
+   * before its pair), then sorted descending. In a wheel straight (A-2-3-4-5) the Ace counts low.
    * 
    * @private
    * @param {Object} evaluation - The evaluation object
-   * @returns {number[]} Array of rank values sorted descending
+   * @returns {number[]} Array of rank values in tiebreak order
    */
   #getKeyCardRanks(evaluation) {
     const handStrength = {
@@ -384,8 +387,11 @@ class HandEvaluator {
     };
     for (const [hand] of Object.entries(handStrength)) {
       if (evaluation[hand]) {
-        const keyCards = evaluation.keyCards[hand] || [];
-        return keyCards.map(c => this.#getRankValue(c)).sort((a, b) => b - a);
+        const ranks = (evaluation.keyCards[hand] || []).map(c => this.#getRankValue(c));
+        const isWheel = (hand === 'isStraight' || hand === 'isStraightFlush') && ranks.includes(13) && ranks.includes(4);
+        const values = isWheel ? ranks.map(r => r === 13 ? 0 : r) : ranks;
+        const counts = values.reduce((acc, r) => (acc[r] = (acc[r] || 0) + 1, acc), {});
+        return values.sort((a, b) => counts[b] - counts[a] || b - a);
       }
     }
     return [];
@@ -457,7 +463,7 @@ class HandEvaluator {
     for (const [key, evaluation] of Object.entries(result)) {
       const strength = this.#getHandStrength(evaluation);
       const bestStrength = bestEval ? this.#getHandStrength(bestEval) : 0;
-      if (!bestEval || strength > bestStrength || (strength === bestStrength && this.#compareEvaluations(evaluation, bestEval) > 0)) {
+      if (!bestEval || strength > bestStrength || (strength === bestStrength && this.#compareEvaluations(evaluation, bestEval) < 0)) {
         bestKey = key;
         bestEval = evaluation;
       }
@@ -1082,13 +1088,14 @@ 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.
+   * Paired cards count once, so a paired hand can still hold a straight draw.
+   * When hole cards are supplied, a hole card must add a rank the board does not already have.
+   * Returns false if the hand is already a straight.
    * 
    * @returns {boolean} True if the hand is an open-ended straight draw, false otherwise
    * @example
-   * const evaluator = new HandEvaluator(['As', 'Ks', 'Qs', 'Js', '9h']);
-   * evaluator.isOpenEndedStraightDraw(); // Returns true (needs T or 9 to complete straight)
+   * const evaluator = new HandEvaluator(['Ks', 'Qs', 'Js', 'Ts', '4h']);
+   * evaluator.isOpenEndedStraightDraw(); // Returns true (needs A or 9 to complete straight)
    */
   #isOpenEndedStraightDraw() {
     if (this.evaluation.isOpenEndedStraightDraw !== undefined) return this.evaluation.isOpenEndedStraightDraw;
@@ -1098,7 +1105,7 @@ class HandEvaluator {
     if (this.evaluation.isFullHouse === undefined) this.#isFullHouse();
     if (this.evaluation.isFourOfAKind === undefined) this.#isFourOfAKind();
     if (this.evaluation.isStraight === undefined) this.#isStraight();
-    if (this.evaluation.isPair || this.evaluation.isTwoPair || this.evaluation.isThreeOfAKind || this.evaluation.isFullHouse || this.evaluation.isFourOfAKind || this.evaluation.isStraight) {
+    if (this.evaluation.isStraight) {
       // Check wheel equivalent before returning false
       if (this.#isOpenEndedStraightDrawWheel()) return this.evaluation.isOpenEndedStraightDraw = true;
       return this.evaluation.isOpenEndedStraightDraw = false;
@@ -1112,8 +1119,8 @@ class HandEvaluator {
 
   /**
    * Determines if the hand is an open-ended straight draw using wheel ranking.
-   * Checks for wheel-equivalent open-ended draws (e.g., A-2-3-4 needs 5 or 2).
-   * Returns false if the hand already contains pairs or higher, or is a wheel straight.
+   * Checks for wheel-equivalent open-ended draws. A-2-3-4 needs only a 5, so it counts as an inside draw.
+   * Paired cards count once. Returns false if the hand is already a wheel straight.
    * 
    * @returns {boolean} True if the hand is a wheel-equivalent open-ended straight draw, false otherwise
    */
@@ -1125,15 +1132,16 @@ class HandEvaluator {
     if (this.evaluation.isFullHouse === undefined) this.#isFullHouse();
     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;
+    if (this.evaluation.isStraightWheel) return this.evaluation.isOpenEndedStraightDrawWheel = false;
     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.
+   * Paired cards count once, so a paired hand can still hold a straight draw.
+   * When hole cards are supplied, a hole card must add a rank the board does not already have.
+   * Returns false if the hand is already a straight.
    * 
    * @returns {boolean} True if the hand is an inside straight draw, false otherwise
    * @example
@@ -1148,7 +1156,7 @@ class HandEvaluator {
     if (this.evaluation.isFullHouse === undefined) this.#isFullHouse();
     if (this.evaluation.isFourOfAKind === undefined) this.#isFourOfAKind();
     if (this.evaluation.isStraight === undefined) this.#isStraight();
-    if (this.evaluation.isPair || this.evaluation.isTwoPair || this.evaluation.isThreeOfAKind || this.evaluation.isFullHouse || this.evaluation.isFourOfAKind || this.evaluation.isStraight) {
+    if (this.evaluation.isStraight) {
       // Check wheel equivalent before returning false
       if (this.#isInsideStraightDrawWheel()) return this.evaluation.isInsideStraightDraw = true;
       return this.evaluation.isInsideStraightDraw = false;
@@ -1164,7 +1172,7 @@ class HandEvaluator {
   /**
    * Determines if the hand is an inside straight draw using wheel ranking.
    * Checks for wheel-equivalent inside draws (e.g., A-2-3-5 needs 4).
-   * Returns false if the hand already contains pairs or higher, or is a wheel straight.
+   * Paired cards count once. Returns false if the hand is already a wheel straight.
    * 
    * @returns {boolean} True if the hand is a wheel-equivalent inside straight draw, false otherwise
    */
@@ -1176,7 +1184,7 @@ class HandEvaluator {
     if (this.evaluation.isFullHouse === undefined) this.#isFullHouse();
     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.isInsideStraightDrawWheel = false;
+    if (this.evaluation.isStraightWheel) return this.evaluation.isInsideStraightDrawWheel = false;
 
     return this.evaluation.isInsideStraightDrawWheel = this.#findStraightDrawWindow([4], true) !== null;
   }
@@ -1696,9 +1704,13 @@ class HandEvaluator {
   }
 
   /**
-   * 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.
+   * Finds 4 cards of distinct, rank-adjacent ranks whose rank span is one of the given distances.
+   * Paired cards count once (a hole card is preferred as the representative of its rank), so a
+   * paired hand such as 8-8-6-5-4 still finds its 8-6-5-4 draw. One-ended draws (A-K-Q-J and
+   * A-2-3-4) count as inside draws, since only one rank completes them. Wheel windows must
+   * contain the Ace. When hole cards are supplied, a
+   * window whose ranks are all already on the board 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)
@@ -1708,11 +1720,24 @@ class HandEvaluator {
   #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));
+    const distinct = [];
+    for (const card of this.cards) {
+      const last = distinct[distinct.length - 1];
+      if (last && rankValue(last) === rankValue(card)) {
+        if (this.holeCards && this.holeCards.includes(card)) distinct[distinct.length - 1] = card;
+        continue;
       }
+      distinct.push(card);
+    }
+    for (let i = 0; i + 4 <= distinct.length; i++) {
+      const window = distinct.slice(i, i + 4);
+      // Wheel ranking only matters when the Ace plays low; other windows are standard draws
+      if (wheel && !window.some(c => c.startsWith('A'))) continue;
+      let distance = rankValue(window[0]) - rankValue(window[3]);
+      // Four in a row capped by the Ace (A-K-Q-J or A-2-3-4) completes at one end only,
+      // so it has the same 4 outs as an inside draw
+      if (distance === 3 && window.some(c => c.startsWith('A'))) distance = 4;
+      if (distances.includes(distance) && this.#addsRankToBoard(window)) return window;
     }
     return null;
   }
@@ -1743,6 +1768,23 @@ class HandEvaluator {
     return cards.some(c => this.holeCards.includes(c));
   }
 
+  /**
+   * Determines whether a straight draw's cards include a rank the board does not already have.
+   * A hole card that only pairs a board rank adds nothing to a straight draw, so when hole cards
+   * are supplied the draw must contain a rank found only in the hole cards. 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 drawing rank is missing from the board
+   */
+  #addsRankToBoard(cards) {
+    if (!this.holeCards) return true;
+    const fullHand = this.originalCards || this.cards;
+    const boardRanks = new Set(fullHand.filter(c => !this.holeCards.includes(c)).map(c => c.slice(0, -1)));
+    return cards.some(c => !boardRanks.has(c.slice(0, -1)));
+  }
+
   // ==================== HIGH CARD ====================
   
   /**
@@ -1766,7 +1808,9 @@ class HandEvaluator {
 
   /**
    * Determines if the hand contains an under pair (pocket pair smaller than all board cards).
-   * Only applicable when evaluating 6+ cards where the pair rank is smaller than all other cards.
+   * With hole cards supplied, the hole cards must be a pocket pair ranked below every board card;
+   * this works on any street, including a 5-card flop. Without hole cards the board is unknown, so
+   * it applies only to 6+ cards where the pair rank is smaller than all other cards.
    * 
    * @returns {boolean} True if the hand is an under pair, false otherwise
    * @example
@@ -1777,6 +1821,13 @@ class HandEvaluator {
   #isUnderPair() {
     if (this.evaluation.isUnderPair !== undefined) return this.evaluation.isUnderPair;
     if (this.evaluation.isPair === undefined) this.#isPair();
+    if (this.evaluation.isPair && this.holeCards) {
+      const [first, second] = this.holeCards;
+      const holeRank = first.slice(0, -1);
+      if (second.slice(0, -1) !== holeRank || this.#getPairRank() !== holeRank) return this.evaluation.isUnderPair = false;
+      const board = (this.originalCards || this.cards).filter(c => !this.holeCards.includes(c));
+      return this.evaluation.isUnderPair = board.every(c => this.#getRankValue(c) > this.#getRankValue(first));
+    }
     if (!this.evaluation.isPair || !this.originalCards || this.originalCards.length < 6) {
       return this.evaluation.isUnderPair = false;
     }

package/package.json

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