poker-extval 3.3.2 → 3.3.4

package/README.md

@@ -126,6 +126,9 @@ const result = evaluateHand(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
 - Descriptive labels (isTopPair, etc.) are only true if they match the strongest hand
 - Made flush or stronger cannot have straight draws (flush > straight)
 - Draws can coexist when no made hand exists (flush draw + straight draw is valid)
+- With 6 or more cards, draws are collected from **every** 5-card combination, not just the best one, so a draw using a card outside the best five is still reported. Straight draws are dropped once a straight or better is made, and flush draws once a flush or better is made. `isComboDraw` is true when the whole hand has both a flush draw and a straight draw.
+
+**Draws by street**: the number of cards sets the street. With 5 cards (the flop) every draw is possible; with 6 (the turn) there is no `isBackdoorFlushDraw`, since one card to come cannot complete it; with 7 (the river) there are no draws at all. This applies in both modes.
 
 ### Evaluating Multiple Card Hands
 
@@ -191,6 +194,8 @@ 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
 
+**Note**: With `holeCards`, pair and three of a kind positions are judged against the **whole board**, including board cards left out of the 5-card combination: top means at or above the highest board card (so a pocket pair above the board is top pair), bottom means at or below the lowest, middle is anything between. A pair or three of a kind made only of board cards gets no position. Without `holeCards` the board is unknown, so positions are judged within the 5-card combination. Two pair positions are always judged within the 5-card combination.
+
 #### 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
@@ -201,14 +206,14 @@ 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.

package/evaluator.js

@@ -36,6 +36,31 @@ const HOLE_CARD_CATEGORIES = new Set([
   'isTwoUndercards'
 ]);
 
+/**
+ * Draw properties. On 6+ cards they describe the whole hand rather than one 5-card combination,
+ * so strict mode collects them from every combination (see #mergeDraws).
+ *
+ * @constant {string[]}
+ */
+const DRAW_PROPERTIES = [
+  'isFlushDraw',
+  'isBackdoorFlushDraw',
+  'isOpenEndedStraightDraw',
+  'isInsideStraightDraw',
+  'isStraightDraw',
+  'isOpenEndedStraightDrawWheel',
+  'isInsideStraightDrawWheel',
+  'isComboDraw'
+];
+
+const STRAIGHT_DRAW_PROPERTIES = [
+  'isOpenEndedStraightDraw',
+  'isInsideStraightDraw',
+  'isStraightDraw',
+  'isOpenEndedStraightDrawWheel',
+  'isInsideStraightDrawWheel'
+];
+
 class HandEvaluator {
   /**
    * Creates an instance of HandEvaluator.
@@ -65,7 +90,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) {
@@ -271,6 +297,7 @@ class HandEvaluator {
     this.#isInsideStraightDraw();
     this.#isStraightDraw();
     this.#isComboDraw();
+    this.#clearDrawsForStreet();
     this.#isUnderPair();
     this.#isOvercards();
     this.#isHighCard();
@@ -370,11 +397,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 +413,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 +489,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;
       }
@@ -495,7 +527,70 @@ class HandEvaluator {
       result[key] = tempEvaluator.evaluation[evaluationKey];
     }
     
-    return this.strict ? this.#findBestCombination(result) : result;
+    if (!this.strict) return result;
+    const best = this.#findBestCombination(result);
+    this.#mergeDraws(Object.values(best)[0], result);
+    return best;
+  }
+
+  /**
+   * Removes draws that can no longer complete, based on how many cards the full hand holds:
+   * 5 cards is the flop (two cards to come), 6 is the turn (one card to come, so a backdoor
+   * draw cannot complete) and 7 or more is the river (no cards to come, so there are no draws).
+   *
+   * @private
+   */
+  #clearDrawsForStreet() {
+    const cardCount = (this.originalCards || this.cards).length;
+    if (cardCount >= 7) {
+      for (const draw of DRAW_PROPERTIES) this.evaluation[draw] = false;
+    } else if (cardCount === 6) {
+      this.evaluation.isBackdoorFlushDraw = false;
+    }
+  }
+
+  /**
+   * In strict mode with 6+ cards only the best 5-card combination is returned, but a draw can
+   * use cards outside it (e.g. the hole card that makes four to a flush). Copies onto the best
+   * evaluation every draw found in any combination, with that combination's key and kicker
+   * cards, then drops draws the made hand already beats and recomputes the combo draw for the
+   * whole hand.
+   *
+   * @private
+   * @param {Object} best - The evaluation of the best combination (modified in place)
+   * @param {Object<string, Object>} result - Evaluations of every combination
+   */
+  #mergeDraws(best, result) {
+    const clear = draw => {
+      best[draw] = false;
+      best.keyCards[draw] = [];
+      best.kickerCards[draw] = [];
+    };
+    for (const draw of DRAW_PROPERTIES) {
+      if (draw === 'isComboDraw' || best[draw]) continue;
+      const source = Object.values(result).find(evaluation => evaluation[draw]);
+      if (!source) continue;
+      best[draw] = true;
+      best.keyCards[draw] = source.keyCards[draw];
+      best.kickerCards[draw] = source.kickerCards[draw];
+    }
+
+    // A made straight or better needs no straight draw; a made flush or better needs no flush draw
+    const strongest = this.#getHandStrength(best);
+    if (strongest >= 5) STRAIGHT_DRAW_PROPERTIES.forEach(clear);
+    if (strongest >= 6) ['isFlushDraw', 'isBackdoorFlushDraw'].forEach(clear);
+
+    if (best.isComboDraw || !(best.isFlushDraw && best.isStraightDraw)) {
+      if (!(best.isFlushDraw && best.isStraightDraw)) clear('isComboDraw');
+      return;
+    }
+    best.isComboDraw = true;
+    const keyCards = [...new Set([...best.keyCards.isFlushDraw, ...best.keyCards.isStraightDraw])]
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+    best.keyCards.isComboDraw = keyCards;
+    best.kickerCards.isComboDraw = this.cards
+      .filter(c => !keyCards.includes(c))
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
   }
 
   /**
@@ -791,6 +886,8 @@ class HandEvaluator {
     if (this.evaluation.isTopPair !== undefined) return this.evaluation.isTopPair;
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (!this.evaluation.isPair) return this.evaluation.isTopPair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isTopPair = position === 'top';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isTopPair = rankCounts[this.cards[0].slice(0, -1)] === 2;
   }
@@ -809,6 +906,8 @@ class HandEvaluator {
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (this.evaluation.isTwoPair === undefined) this.#isTwoPair();
     if (!this.evaluation.isPair || this.evaluation.isTwoPair) return this.evaluation.isMiddlePair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isMiddlePair = position === 'middle';
     const ranks = this.#getRankCountsSorted();
     return this.evaluation.isMiddlePair = ranks.length === 4 && (ranks[1].count === 2 || ranks[2].count === 2);
   }
@@ -826,6 +925,8 @@ class HandEvaluator {
     if (this.evaluation.isBottomPair !== undefined) return this.evaluation.isBottomPair;
     if (this.evaluation.isPair === undefined) this.#isPair();
     if (!this.evaluation.isPair) return this.evaluation.isBottomPair = false;
+    const position = this.#getBoardPosition(this.#getPairRank());
+    if (position !== null) return this.evaluation.isBottomPair = position === 'bottom';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isBottomPair = rankCounts[this.cards[this.cards.length - 1].slice(0, -1)] === 2;
   }
@@ -898,6 +999,8 @@ class HandEvaluator {
     if (this.evaluation.isTopThreeOfAKind !== undefined) return this.evaluation.isTopThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isTopThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isTopThreeOfAKind = position === 'top';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isTopThreeOfAKind = rankCounts[this.cards[0].slice(0, -1)] === 3;
   }
@@ -915,6 +1018,8 @@ class HandEvaluator {
     if (this.evaluation.isMiddleThreeOfAKind !== undefined) return this.evaluation.isMiddleThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isMiddleThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isMiddleThreeOfAKind = position === 'middle';
     const ranks = this.#getRankCountsSorted();
     return this.evaluation.isMiddleThreeOfAKind = ranks.length === 3 && ranks[1].count === 3;
   }
@@ -932,6 +1037,8 @@ class HandEvaluator {
     if (this.evaluation.isBottomThreeOfAKind !== undefined) return this.evaluation.isBottomThreeOfAKind;
     if (this.evaluation.isThreeOfAKind === undefined) this.#isThreeOfAKind();
     if (!this.evaluation.isThreeOfAKind) return this.evaluation.isBottomThreeOfAKind = false;
+    const position = this.#getBoardPosition(this.#getTripsRank());
+    if (position !== null) return this.evaluation.isBottomThreeOfAKind = position === 'bottom';
     const rankCounts = this.#getRankCounts();
     return this.evaluation.isBottomThreeOfAKind = rankCounts[this.cards[this.cards.length - 1].slice(0, -1)] === 3;
   }
@@ -1088,8 +1195,8 @@ class HandEvaluator {
    * 
    * @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;
@@ -1113,7 +1220,7 @@ 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).
+   * 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
@@ -1700,7 +1807,9 @@ class HandEvaluator {
   /**
    * 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. When hole cards are supplied, 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.
    * 
@@ -1723,7 +1832,12 @@ class HandEvaluator {
     }
     for (let i = 0; i + 4 <= distinct.length; i++) {
       const window = distinct.slice(i, i + 4);
-      const distance = rankValue(window[0]) - rankValue(window[3]);
+      // 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;
@@ -1795,7 +1909,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
@@ -1806,6 +1922,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;
     }
@@ -1829,6 +1952,42 @@ class HandEvaluator {
     }
     return null;
   }
+
+  /**
+   * Gets the rank of the three of a kind in the current hand.
+   *
+   * @private
+   * @returns {string|null} The rank of the three of a kind, or null if none exists
+   */
+  #getTripsRank() {
+    const rankCounts = this.#getRankCounts();
+    return Object.keys(rankCounts).find(rank => rankCounts[rank] === 3) || null;
+  }
+
+  /**
+   * Classifies a paired (or tripled) rank against the whole board, including board cards outside
+   * the current 5-card combination. Requires hole cards: without them the board is unknown and
+   * positions fall back to the 5-card combination.
+   *
+   * - 'top': the rank is at or above the highest board card (top pair, or a pocket pair above the board)
+   * - 'bottom': the rank is at or below the lowest board card
+   * - 'middle': anything in between
+   * - 'none': no hole card has this rank, so the pair or trips belongs to the board
+   *
+   * @private
+   * @param {string|null} rank - The rank to classify
+   * @returns {string|null} The position, or null if no hole cards were supplied
+   */
+  #getBoardPosition(rank) {
+    if (!this.holeCards) return null;
+    if (!rank || !this.holeCards.some(c => c.slice(0, -1) === rank)) return 'none';
+    const fullHand = this.originalCards || this.cards;
+    const boardValues = fullHand.filter(c => !this.holeCards.includes(c)).map(c => this.#getRankValue(c));
+    const value = this.#getRankValue(rank + 's');
+    if (value >= Math.max(...boardValues)) return 'top';
+    if (value <= Math.min(...boardValues)) return 'bottom';
+    return 'middle';
+  }
   
   // ==================== OVERCARDS ====================
 

package/package.json

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