poker-extval 3.3.0 → 3.3.2

package/README.md

@@ -97,6 +97,7 @@ 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`.
 
@@ -210,6 +211,10 @@ 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.
+
+**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
@@ -479,6 +484,10 @@ Creates a new HandEvaluator instance.
 
 **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

@@ -954,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
@@ -966,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
@@ -984,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 ====================
@@ -1080,7 +1082,9 @@ 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.
-   * 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
@@ -1095,13 +1099,12 @@ 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;
     }
-    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;
@@ -1111,7 +1114,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).
-   * 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 open-ended straight draw, false otherwise
    */
@@ -1123,15 +1126,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;
-    this.#sortWheel();
-    return this.evaluation.isOpenEndedStraightDrawWheel = this.#getDistanceWheel(this.cards.slice(0,4)) === 3 || this.#getDistanceWheel(this.cards.slice(1,5)) === 3;
+    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.
-   * 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
@@ -1146,14 +1150,13 @@ 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;
     }
 
-    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;
@@ -1163,7 +1166,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
    */
@@ -1175,10 +1178,9 @@ 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;
 
-    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;
   }
 
   /**
@@ -1454,8 +1456,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);
   }
 
   /**
@@ -1468,8 +1469,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);
   }
 
   /**
@@ -1480,7 +1480,7 @@ class HandEvaluator {
    */
   #getKeyCardsForOpenEndedStraightDraw() {
     if (!this.evaluation.isOpenEndedStraightDraw) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([3]);
   }
 
   /**
@@ -1491,7 +1491,7 @@ class HandEvaluator {
    */
   #getKeyCardsForInsideStraightDraw() {
     if (!this.evaluation.isInsideStraightDraw) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([4]);
   }
 
   /**
@@ -1577,7 +1577,7 @@ class HandEvaluator {
    */
   #getKeyCardsForOpenEndedStraightDrawWheel() {
     if (!this.evaluation.isOpenEndedStraightDrawWheel) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([3]);
   }
 
   /**
@@ -1588,7 +1588,7 @@ class HandEvaluator {
    */
   #getKeyCardsForInsideStraightDrawWheel() {
     if (!this.evaluation.isInsideStraightDrawWheel) return [];
-    return this.#getStraightDrawCards();
+    return this.#getStraightDrawCards([4]);
   }
 
   /**
@@ -1685,41 +1685,91 @@ 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));
+  #getStraightDrawCards(distances = [3, 4]) {
+    return this.#findStraightDrawWindow(distances, false) || this.#findStraightDrawWindow(distances, true) || [];
+  }
+
+  /**
+   * 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
+   * 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)
+   * @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();
+    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);
     }
-    const lastFourDistWheel = this.#getDistanceWheel(lastFourWheel);
-    if (lastFourDistWheel === 3 || lastFourDistWheel === 4) {
-      return [...lastFourWheel].sort((a, b) => this.#getRankValueWheel(b) - this.#getRankValueWheel(a));
+    for (let i = 0; i + 4 <= distinct.length; i++) {
+      const window = distinct.slice(i, i + 4);
+      const distance = rankValue(window[0]) - rankValue(window[3]);
+      if (distances.includes(distance) && this.#addsRankToBoard(window)) return window;
     }
-    
-    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));
+  }
+
+  /**
+   * 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 ====================

package/package.json

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