poker-extval 2.0.0 → 3.1.0

package/README.md

@@ -5,8 +5,10 @@ A comprehensive poker hand evaluation library for Node.js that evaluates poker h
 ## Features
 
 - **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
 - **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
 - **Multiple Card Support**: Accepts 5 or more cards and evaluates all possible 5-card combinations
 - **Extensive Documentation**: Full JSDoc comments for all methods
@@ -24,15 +26,15 @@ npm install poker-extval
 ```javascript
 const { evaluateHand } = require('poker-extval');
 
-// Evaluate a 5-card hand
+// Evaluate a 5-card hand (strict mode enabled by default)
 const result = evaluateHand(['As', 'Ks', 'Qs', 'Js', 'Ts']);
 console.log(result);
 // {
 //   "As, Ks, Qs, Js, Ts": {
 //     "isRoyalFlush": true,
 //     "isStraightFlush": false,
-//     "isFlush": true,
-//     "isStraight": true,
+//     "isFlush": false,  // Filtered out in strict mode (royal flush is stronger)
+//     "isStraight": false,  // Filtered out in strict mode (royal flush is stronger)
 //     ...
 //   }
 // }
@@ -43,14 +45,43 @@ console.log(result);
 ```javascript
 const { HandEvaluator } = require('poker-extval');
 
-// Create an evaluator instance
+// Create an evaluator instance (strict mode enabled by default)
 const evaluator = new HandEvaluator(['As', 'Ks', 'Qs', 'Js', 'Ts', '9s']);
 
 // Access evaluation results
 const evaluation = evaluator.evaluation;
 // Object with keys for each 5-card combination
+
+// Non-strict mode (all applicable hands marked)
+const nonStrictEvaluator = new HandEvaluator(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
 ```
 
+### 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.
+
+**Example with strict mode (default):**
+```javascript
+const result = evaluateHand(['As', 'Ah', 'Kd', 'Kc', 'Qs']);
+// isTwoPair: true
+// isPair: false (filtered out because two pair is stronger)
+// isTopAndMiddlePair: true
+```
+
+**Example with non-strict mode:**
+```javascript
+const result = evaluateHand(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
+// isTwoPair: true
+// isPair: false (evaluation logic prevents this, not strict mode)
+// isTopAndMiddlePair: true
+```
+
+**Strict Mode Rules:**
+- Only the strongest made hand is marked as true
+- 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)
+
 ### Evaluating Multiple Card Hands
 
 When you provide more than 5 cards, the evaluator generates all possible 5-card combinations:
@@ -100,17 +131,17 @@ The `evaluateHand()` function returns an object where:
 - `isPair` - Exactly one pair
 - `isHighCard` - No made hand
 
-#### Pair Categorization (only true if `isPair` is true)
+#### Pair Categorization (only true if `isPair` is true in strict mode)
 - `isTopPair` - Pair is the highest card
 - `isMiddlePair` - Pair is neither highest nor lowest
 - `isBottomPair` - Pair is the lowest card
 
-#### Two Pair Categorization (only true if `isTwoPair` is true)
+#### Two Pair Categorization (only true if `isTwoPair` is true in strict mode)
 - `isTopAndMiddlePair` - Both pairs are in top two ranks
 - `isTopAndBottomPair` - One pair is highest, other is lowest
 - `isMiddleAndBottomPair` - Both pairs are in middle and bottom ranks
 
-#### Three of a Kind Categorization (only true if `isThreeOfAKind` is true)
+#### Three of a Kind Categorization (only true if `isThreeOfAKind` is true in strict mode)
 - `isTopThreeOfAKind` - Three of a kind is the highest rank
 - `isMiddleThreeOfAKind` - Three of a kind is neither highest nor lowest
 - `isBottomThreeOfAKind` - Three of a kind is the lowest rank
@@ -128,11 +159,15 @@ The `evaluateHand()` function returns an object where:
 - `isInsideStraightDrawWheel` - Inside draw using wheel ranking
 
 #### Card Arrays
-- `keyCards` - Array of cards (sorted) that constitute the made hand or draw
-- `kickerCards` - Array of cards (sorted) that don't constitute the made hand or draw
+- `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**: 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
 
+**Example 1: Royal Flush (strict mode - default)**
+
 ```javascript
 {
   "As, Ks, Qs, Js, Ts": {
@@ -141,10 +176,10 @@ The `evaluateHand()` function returns an object where:
     "isThreeOfAKind": false,
     "isTwoPair": false,
     "isPair": false,
-    "isFlush": true,
-    "isStraight": true,
+    "isFlush": false,  // Filtered out in strict mode (royal flush is stronger)
+    "isStraight": false,  // Filtered out in strict mode (royal flush is stronger)
     "isRoyalFlush": true,
-    "isStraightFlush": true,
+    "isStraightFlush": false,  // Filtered out in strict mode (royal flush is stronger)
     "isTopPair": false,
     "isMiddlePair": false,
     "isBottomPair": false,
@@ -160,8 +195,109 @@ The `evaluateHand()` function returns an object where:
     "isInsideStraightDraw": false,
     "isStraightDraw": false,
     "isHighCard": false,
-    "keyCards": ["As", "Ks", "Qs", "Js", "Ts"],
-    "kickerCards": []
+    "keyCards": {
+      "isRoyalFlush": ["As", "Ks", "Qs", "Js", "Ts"],
+      "isStraightFlush": [],
+      "isFourOfAKind": [],
+      "isFullHouse": [],
+      "isFlush": [],  // Empty in strict mode (royal flush is stronger)
+      "isStraight": [],  // Empty in strict mode (royal flush is stronger)
+      "isThreeOfAKind": [],
+      "isTwoPair": [],
+      "isPair": [],
+      "isTopPair": [],
+      "isMiddlePair": [],
+      "isBottomPair": [],
+      "isTopAndMiddlePair": [],
+      "isTopAndBottomPair": [],
+      "isMiddleAndBottomPair": [],
+      "isTopThreeOfAKind": [],
+      "isMiddleThreeOfAKind": [],
+      "isBottomThreeOfAKind": [],
+      "isFlushDraw": [],
+      "isBackdoorFlushDraw": [],
+      "isOpenEndedStraightDraw": [],
+      "isInsideStraightDraw": [],
+      "isStraightDraw": [],
+      "isStraightWheel": [],
+      "isOpenEndedStraightDrawWheel": [],
+      "isInsideStraightDrawWheel": [],
+      "isHighCard": []
+    },
+    "kickerCards": {
+      "isRoyalFlush": [],
+      "isStraightFlush": [],
+      "isFourOfAKind": [],
+      "isFullHouse": [],
+      "isFlush": [],
+      "isStraight": [],
+      "isThreeOfAKind": [],
+      "isTwoPair": [],
+      "isPair": [],
+      "isTopPair": [],
+      "isMiddlePair": [],
+      "isBottomPair": [],
+      "isTopAndMiddlePair": [],
+      "isTopAndBottomPair": [],
+      "isMiddleAndBottomPair": [],
+      "isTopThreeOfAKind": [],
+      "isMiddleThreeOfAKind": [],
+      "isBottomThreeOfAKind": [],
+      "isFlushDraw": [],
+      "isBackdoorFlushDraw": [],
+      "isOpenEndedStraightDraw": [],
+      "isInsideStraightDraw": [],
+      "isStraightDraw": [],
+      "isStraightWheel": [],
+      "isOpenEndedStraightDrawWheel": [],
+      "isInsideStraightDrawWheel": [],
+      "isHighCard": []
+    }
+  }
+}
+```
+
+**Example 2: Pair with Flush Draw (strict mode - default)**
+
+```javascript
+{
+  "As, Ah, Ks, Qs, Js": {
+    "isPair": true,
+    "isFlushDraw": true,  // Draws can coexist with made hands in strict mode
+    // ... other boolean properties ...
+    "keyCards": {
+      "isPair": ["As", "Ah"],
+      "isFlushDraw": ["As", "Ks", "Qs", "Js"],
+      // ... other hand types with empty arrays ...
+    },
+    "kickerCards": {
+      "isPair": ["Ks", "Qs", "Js"],
+      "isFlushDraw": ["Ah"],
+      // ... other hand types with empty arrays ...
+    }
+  }
+}
+```
+
+**Example 3: Two Pair (strict mode - default)**
+
+```javascript
+{
+  "As, Ah, Kd, Kc, Qs": {
+    "isTwoPair": true,
+    "isPair": false,  // Filtered out in strict mode (two pair is stronger)
+    "isTopAndMiddlePair": true,
+    // ... other boolean properties ...
+    "keyCards": {
+      "isTwoPair": ["As", "Ah", "Kd", "Kc"],
+      "isPair": [],  // Empty in strict mode
+      // ... other hand types with empty arrays ...
+    },
+    "kickerCards": {
+      "isTwoPair": ["Qs"],
+      "isPair": [],  // Empty in strict mode
+      // ... other hand types with empty arrays ...
+    }
   }
 }
 ```
@@ -244,12 +380,13 @@ The test suite includes 572+ tests covering:
 
 ## API Reference
 
-### `evaluateHand(cards)`
+### `evaluateHand(cards, strict)`
 
 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`).
 
 **Returns:**
 - Object mapping sorted hand strings to evaluation objects
@@ -262,17 +399,19 @@ Main function to evaluate poker hands.
 #### Constructor
 
 ```javascript
-new HandEvaluator(cards)
+new HandEvaluator(cards, strict)
 ```
 
 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`).
 
 **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
 
 **Note**: All internal methods are private. Use the `evaluation` property to access evaluation results.
 

package/evaluator.js

@@ -26,14 +26,23 @@ 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
    *   - 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).
    * @throws {Error} If cards is not an array, has fewer than 5 cards, contains invalid format,
    *   invalid rank, invalid suit, or duplicate cards
    * @example
    * const evaluator = new HandEvaluator(['As', 'Ks', 'Qs', 'Js', 'Ts']);
+   * @example
+   * // Strict mode (default) - only strongest hand marked
+   * const strictEvaluator = new HandEvaluator(['As', 'Ah', 'Kd', 'Kc', 'Qs'], true);
+   * @example
+   * // Non-strict mode - all applicable hands marked
+   * const nonStrictEvaluator = new HandEvaluator(['As', 'Ah', 'Kd', 'Kc', 'Qs'], false);
    */
-  constructor(cards) {
+  constructor(cards, strict = true) {
     this.#validateCards(cards);
     this.cards = cards;
+    this.strict = strict;
     this.evaluation = this.#evaluateAllCombinations();
   }
 
@@ -194,8 +203,13 @@ class HandEvaluator {
     // Add keyCards and kickerCards before restoring original evaluation
     // (these methods need access to this.evaluation)
     const evaluation = this.evaluation;
-    evaluation.keyCards = this.#getKeyCards();
-    evaluation.kickerCards = this.#getKickerCards();
+    evaluation.keyCards = this.#buildKeyCardsObject();
+    evaluation.kickerCards = this.#buildKickerCardsObject(evaluation.keyCards);
+    
+    // Apply strict mode filtering if enabled
+    if (this.strict) {
+      this.#applyStrictMode(evaluation);
+    }
     
     // Restore original evaluation
     this.evaluation = originalEvaluation;
@@ -203,6 +217,64 @@ class HandEvaluator {
     return evaluation;
   }
 
+  /**
+   * Applies strict mode filtering to evaluation results.
+   * Only the strongest made hand and stronger draws are kept as true.
+   * 
+   * @private
+   * @param {Object} evaluation - The evaluation object to filter
+   */
+  #applyStrictMode(evaluation) {
+    // Hand strength lookup (strongest = highest number)
+    const handStrength = {
+      isRoyalFlush: 10,
+      isStraightFlush: 9,
+      isFourOfAKind: 8,
+      isFullHouse: 7,
+      isFlush: 6,
+      isStraight: 5,
+      isThreeOfAKind: 4,
+      isTwoPair: 3,
+      isPair: 2,
+      isHighCard: 1
+    };
+    
+    // Find strongest made hand
+    let strongest = 0;
+    for (const [hand, strength] of Object.entries(handStrength)) {
+      if (evaluation[hand]) strongest = Math.max(strongest, strength);
+    }
+    
+    // Disable weaker made hands in single pass
+    for (const [hand, strength] of Object.entries(handStrength)) {
+      if (strength < strongest) evaluation[hand] = false;
+    }
+    
+    // Disable descriptive labels if not matching strongest
+    if (strongest !== 2) {
+      evaluation.isTopPair = false;
+      evaluation.isMiddlePair = false;
+      evaluation.isBottomPair = false;
+    }
+    if (strongest !== 3) {
+      evaluation.isTopAndMiddlePair = false;
+      evaluation.isTopAndBottomPair = false;
+      evaluation.isMiddleAndBottomPair = false;
+    }
+    if (strongest !== 4) {
+      evaluation.isTopThreeOfAKind = false;
+      evaluation.isMiddleThreeOfAKind = false;
+      evaluation.isBottomThreeOfAKind = false;
+    }
+    
+    // Filter draws: made flush or stronger cannot have straight draws
+    if (strongest >= 6) {
+      evaluation.isStraightDraw = false;
+      evaluation.isOpenEndedStraightDraw = false;
+      evaluation.isInsideStraightDraw = false;
+    }
+  }
+
   /**
    * Evaluates all possible 5-card combinations from the input cards.
    * For exactly 5 cards, evaluates directly. For more cards, generates all combinations
@@ -971,6 +1043,390 @@ class HandEvaluator {
     return [];
   }
 
+  // ==================== KEY CARDS EXTRACTION BY HAND TYPE ====================
+  
+  /**
+   * Gets key cards for royal flush (all 5 cards).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if royal flush, empty array otherwise
+   */
+  #getKeyCardsForRoyalFlush() {
+    if (!this.evaluation.isRoyalFlush) return [];
+    return [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for straight flush (all 5 cards).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if straight flush, empty array otherwise
+   */
+  #getKeyCardsForStraightFlush() {
+    if (!this.evaluation.isStraightFlush) return [];
+    return [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for four of a kind (4 cards of same rank).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if four of a kind, empty array otherwise
+   */
+  #getKeyCardsForFourOfAKind() {
+    if (!this.evaluation.isFourOfAKind) return [];
+    const rankCounts = this.#getRankCounts();
+    const fourRank = Object.keys(rankCounts).find(r => rankCounts[r] === 4);
+    return this.cards.filter(c => c.slice(0, -1) === fourRank)
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for full house (all 5 cards).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if full house, empty array otherwise
+   */
+  #getKeyCardsForFullHouse() {
+    if (!this.evaluation.isFullHouse) return [];
+    return [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for flush (all 5 cards of same suit).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if flush, empty array otherwise
+   */
+  #getKeyCardsForFlush() {
+    if (!this.evaluation.isFlush) return [];
+    const suits = this.#countSuits();
+    const flushSuit = Object.keys(suits).find(s => suits[s] === 5);
+    return this.cards.filter(c => c.slice(-1) === flushSuit)
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for straight (5 cards forming straight).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if straight, empty array otherwise
+   */
+  #getKeyCardsForStraight() {
+    if (!this.evaluation.isStraight) return [];
+    return this.#getStraightCards();
+  }
+
+  /**
+   * Gets key cards for three of a kind (3 cards of same rank).
+   * 
+   * @private
+   * @returns {string[]} Array of 3 cards if three of a kind, empty array otherwise
+   */
+  #getKeyCardsForThreeOfAKind() {
+    if (!this.evaluation.isThreeOfAKind) return [];
+    const rankCounts = this.#getRankCounts();
+    const threeRank = Object.keys(rankCounts).find(r => rankCounts[r] === 3);
+    return this.cards.filter(c => c.slice(0, -1) === threeRank)
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for two pair (4 cards forming 2 pairs).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if two pair, empty array otherwise
+   */
+  #getKeyCardsForTwoPair() {
+    if (!this.evaluation.isTwoPair) return [];
+    const rankCounts = this.#getRankCounts();
+    const pairRanks = Object.keys(rankCounts).filter(r => rankCounts[r] === 2);
+    return this.cards.filter(c => pairRanks.includes(c.slice(0, -1)))
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for pair (2 cards of same rank).
+   * 
+   * @private
+   * @returns {string[]} Array of 2 cards if pair, empty array otherwise
+   */
+  #getKeyCardsForPair() {
+    if (!this.evaluation.isPair) return [];
+    const rankCounts = this.#getRankCounts();
+    const pairRank = Object.keys(rankCounts).find(r => rankCounts[r] === 2);
+    return this.cards.filter(c => c.slice(0, -1) === pairRank)
+      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+  }
+
+  /**
+   * Gets key cards for top pair (2 cards if top pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 2 cards if top pair, empty array otherwise
+   */
+  #getKeyCardsForTopPair() {
+    if (!this.evaluation.isTopPair) return [];
+    return this.#getKeyCardsForPair();
+  }
+
+  /**
+   * Gets key cards for middle pair (2 cards if middle pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 2 cards if middle pair, empty array otherwise
+   */
+  #getKeyCardsForMiddlePair() {
+    if (!this.evaluation.isMiddlePair) return [];
+    return this.#getKeyCardsForPair();
+  }
+
+  /**
+   * Gets key cards for bottom pair (2 cards if bottom pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 2 cards if bottom pair, empty array otherwise
+   */
+  #getKeyCardsForBottomPair() {
+    if (!this.evaluation.isBottomPair) return [];
+    return this.#getKeyCardsForPair();
+  }
+
+  /**
+   * Gets key cards for top and middle pair (4 cards if top and middle pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if top and middle pair, empty array otherwise
+   */
+  #getKeyCardsForTopAndMiddlePair() {
+    if (!this.evaluation.isTopAndMiddlePair) return [];
+    return this.#getKeyCardsForTwoPair();
+  }
+
+  /**
+   * Gets key cards for top and bottom pair (4 cards if top and bottom pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if top and bottom pair, empty array otherwise
+   */
+  #getKeyCardsForTopAndBottomPair() {
+    if (!this.evaluation.isTopAndBottomPair) return [];
+    return this.#getKeyCardsForTwoPair();
+  }
+
+  /**
+   * Gets key cards for middle and bottom pair (4 cards if middle and bottom pair).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if middle and bottom pair, empty array otherwise
+   */
+  #getKeyCardsForMiddleAndBottomPair() {
+    if (!this.evaluation.isMiddleAndBottomPair) return [];
+    return this.#getKeyCardsForTwoPair();
+  }
+
+  /**
+   * Gets key cards for top three of a kind (3 cards if top three).
+   * 
+   * @private
+   * @returns {string[]} Array of 3 cards if top three of a kind, empty array otherwise
+   */
+  #getKeyCardsForTopThreeOfAKind() {
+    if (!this.evaluation.isTopThreeOfAKind) return [];
+    return this.#getKeyCardsForThreeOfAKind();
+  }
+
+  /**
+   * Gets key cards for middle three of a kind (3 cards if middle three).
+   * 
+   * @private
+   * @returns {string[]} Array of 3 cards if middle three of a kind, empty array otherwise
+   */
+  #getKeyCardsForMiddleThreeOfAKind() {
+    if (!this.evaluation.isMiddleThreeOfAKind) return [];
+    return this.#getKeyCardsForThreeOfAKind();
+  }
+
+  /**
+   * Gets key cards for bottom three of a kind (3 cards if bottom three).
+   * 
+   * @private
+   * @returns {string[]} Array of 3 cards if bottom three of a kind, empty array otherwise
+   */
+  #getKeyCardsForBottomThreeOfAKind() {
+    if (!this.evaluation.isBottomThreeOfAKind) return [];
+    return this.#getKeyCardsForThreeOfAKind();
+  }
+
+  /**
+   * Gets key cards for flush draw (4 cards of same suit).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if flush draw, empty array otherwise
+   */
+  #getKeyCardsForFlushDraw() {
+    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));
+  }
+
+  /**
+   * Gets key cards for backdoor flush draw (3 cards of same suit).
+   * 
+   * @private
+   * @returns {string[]} Array of 3 cards if backdoor flush draw, empty array otherwise
+   */
+  #getKeyCardsForBackdoorFlushDraw() {
+    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));
+  }
+
+  /**
+   * Gets key cards for open-ended straight draw (4 cards forming draw).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if open-ended straight draw, empty array otherwise
+   */
+  #getKeyCardsForOpenEndedStraightDraw() {
+    if (!this.evaluation.isOpenEndedStraightDraw) return [];
+    return this.#getStraightDrawCards();
+  }
+
+  /**
+   * Gets key cards for inside straight draw (4 cards forming draw).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if inside straight draw, empty array otherwise
+   */
+  #getKeyCardsForInsideStraightDraw() {
+    if (!this.evaluation.isInsideStraightDraw) return [];
+    return this.#getStraightDrawCards();
+  }
+
+  /**
+   * Gets key cards for straight draw (4 cards forming any straight draw).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if straight draw, empty array otherwise
+   */
+  #getKeyCardsForStraightDraw() {
+    if (!this.evaluation.isStraightDraw) return [];
+    return this.#getStraightDrawCards();
+  }
+
+  /**
+   * Gets key cards for wheel straight (5 cards forming wheel).
+   * 
+   * @private
+   * @returns {string[]} Array of 5 cards if wheel straight, empty array otherwise
+   */
+  #getKeyCardsForStraightWheel() {
+    if (!this.evaluation.isStraightWheel) return [];
+    return this.#getStraightCards();
+  }
+
+  /**
+   * Gets key cards for open-ended straight draw wheel (4 cards forming wheel draw).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if wheel open-ended draw, empty array otherwise
+   */
+  #getKeyCardsForOpenEndedStraightDrawWheel() {
+    if (!this.evaluation.isOpenEndedStraightDrawWheel) return [];
+    return this.#getStraightDrawCards();
+  }
+
+  /**
+   * Gets key cards for inside straight draw wheel (4 cards forming wheel draw).
+   * 
+   * @private
+   * @returns {string[]} Array of 4 cards if wheel inside draw, empty array otherwise
+   */
+  #getKeyCardsForInsideStraightDrawWheel() {
+    if (!this.evaluation.isInsideStraightDrawWheel) return [];
+    return this.#getStraightDrawCards();
+  }
+
+  /**
+   * Gets key cards for high card (empty array).
+   * 
+   * @private
+   * @returns {string[]} Always returns empty array
+   */
+  #getKeyCardsForHighCard() {
+    return [];
+  }
+
+  /**
+   * Builds the keyCards object with entries for all hand types.
+   * 
+   * @private
+   * @returns {Object} Object with keys for all hand types, values are arrays of key cards
+   */
+  #buildKeyCardsObject() {
+    return {
+      isRoyalFlush: this.#getKeyCardsForRoyalFlush(),
+      isStraightFlush: this.#getKeyCardsForStraightFlush(),
+      isFourOfAKind: this.#getKeyCardsForFourOfAKind(),
+      isFullHouse: this.#getKeyCardsForFullHouse(),
+      isFlush: this.#getKeyCardsForFlush(),
+      isStraight: this.#getKeyCardsForStraight(),
+      isThreeOfAKind: this.#getKeyCardsForThreeOfAKind(),
+      isTwoPair: this.#getKeyCardsForTwoPair(),
+      isPair: this.#getKeyCardsForPair(),
+      isTopPair: this.#getKeyCardsForTopPair(),
+      isMiddlePair: this.#getKeyCardsForMiddlePair(),
+      isBottomPair: this.#getKeyCardsForBottomPair(),
+      isTopAndMiddlePair: this.#getKeyCardsForTopAndMiddlePair(),
+      isTopAndBottomPair: this.#getKeyCardsForTopAndBottomPair(),
+      isMiddleAndBottomPair: this.#getKeyCardsForMiddleAndBottomPair(),
+      isTopThreeOfAKind: this.#getKeyCardsForTopThreeOfAKind(),
+      isMiddleThreeOfAKind: this.#getKeyCardsForMiddleThreeOfAKind(),
+      isBottomThreeOfAKind: this.#getKeyCardsForBottomThreeOfAKind(),
+      isFlushDraw: this.#getKeyCardsForFlushDraw(),
+      isBackdoorFlushDraw: this.#getKeyCardsForBackdoorFlushDraw(),
+      isOpenEndedStraightDraw: this.#getKeyCardsForOpenEndedStraightDraw(),
+      isInsideStraightDraw: this.#getKeyCardsForInsideStraightDraw(),
+      isStraightDraw: this.#getKeyCardsForStraightDraw(),
+      isStraightWheel: this.#getKeyCardsForStraightWheel(),
+      isOpenEndedStraightDrawWheel: this.#getKeyCardsForOpenEndedStraightDrawWheel(),
+      isInsideStraightDrawWheel: this.#getKeyCardsForInsideStraightDrawWheel(),
+      isHighCard: this.#getKeyCardsForHighCard()
+    };
+  }
+
+  /**
+   * Builds the kickerCards object with entries for all hand types.
+   * 
+   * @private
+   * @param {Object} keyCardsObj - The keyCards object
+   * @returns {Object} Object with keys for all hand types, values are arrays of kicker cards
+   */
+  #buildKickerCardsObject(keyCardsObj) {
+    const sortedCards = [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+    const result = {};
+    
+    for (const [handType, keyCards] of Object.entries(keyCardsObj)) {
+      if (handType === 'isHighCard') {
+        result[handType] = sortedCards;
+      } else if (keyCards.length === 0) {
+        result[handType] = [];
+      } else {
+        const keyCardsSet = new Set(keyCards);
+        result[handType] = this.cards
+          .filter(c => !keyCardsSet.has(c))
+          .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
+      }
+    }
+    
+    return result;
+  }
+
   /**
    * Helper method to extract the 4 cards that form a straight draw.
    * Handles both standard and wheel straight draws.
@@ -1010,107 +1466,6 @@ class HandEvaluator {
     return [];
   }
 
-  /**
-   * Determines the primary made hand or draw and extracts the key cards.
-   * Assumes cards are already sorted and evaluation is complete.
-   * 
-   * @private
-   * @returns {string[]} Array of key cards, sorted from highest to lowest rank
-   */
-  #getKeyCards() {
-    // Ensure cards are sorted once (they likely already are from evaluation)
-    const sortedCards = [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    
-    // Calculate these once and reuse
-    const rankCounts = this.#getRankCounts();
-    const suits = this.#countSuits();
-    
-    // Use evaluation results directly - no re-checking
-    // Check made hands in priority order
-    if (this.evaluation.isRoyalFlush || this.evaluation.isStraightFlush || 
-        this.evaluation.isFullHouse) {
-      return sortedCards; // All 5 cards are key cards
-    }
-    
-    if (this.evaluation.isStraight) {
-      return this.#getStraightCards();
-    }
-    
-    if (this.evaluation.isFourOfAKind) {
-      const fourRank = Object.keys(rankCounts).find(r => rankCounts[r] === 4);
-      return sortedCards.filter(c => c.slice(0, -1) === fourRank)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isFlush) {
-      const flushSuit = Object.keys(suits).find(s => suits[s] === 5);
-      return sortedCards.filter(c => c.slice(-1) === flushSuit)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isThreeOfAKind) {
-      const threeRank = Object.keys(rankCounts).find(r => rankCounts[r] === 3);
-      return sortedCards.filter(c => c.slice(0, -1) === threeRank)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isTwoPair) {
-      const pairRanks = Object.keys(rankCounts).filter(r => rankCounts[r] === 2);
-      return sortedCards.filter(c => pairRanks.includes(c.slice(0, -1)))
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isPair) {
-      const pairRank = Object.keys(rankCounts).find(r => rankCounts[r] === 2);
-      return sortedCards.filter(c => c.slice(0, -1) === pairRank)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    // Check draws (only if no made hand)
-    if (this.evaluation.isFlushDraw) {
-      const flushSuit = Object.keys(suits).find(s => suits[s] === 4);
-      return sortedCards.filter(c => c.slice(-1) === flushSuit)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isBackdoorFlushDraw) {
-      const flushSuit = Object.keys(suits).find(s => suits[s] === 3);
-      return sortedCards.filter(c => c.slice(-1) === flushSuit)
-        .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    if (this.evaluation.isOpenEndedStraightDraw || this.evaluation.isInsideStraightDraw) {
-      const drawCards = this.#getStraightDrawCards();
-      // Only return if we actually found draw cards (safety check)
-      if (drawCards.length === 4) {
-        return drawCards;
-      }
-    }
-    
-    // High card or no hand/draw
-    return [];
-  }
-
-  /**
-   * Gets the kicker cards (cards not in the made hand or draw).
-   * 
-   * @private
-   * @returns {string[]} Array of kicker cards, sorted from highest to lowest rank
-   */
-  #getKickerCards() {
-    const keyCards = this.#getKeyCards();
-    if (keyCards.length === 0) {
-      // All cards are kickers (high card)
-      return [...this.cards].sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-    }
-    
-    // Use Set for O(1) lookup
-    const keyCardsSet = new Set(keyCards);
-    return this.cards
-      .filter(c => !keyCardsSet.has(c))
-      .sort((a, b) => this.#getRankValue(b) - this.#getRankValue(a));
-  }
-
   // ==================== HIGH CARD ====================
   
   /**
@@ -1140,10 +1495,12 @@ class HandEvaluator {
  * Generates all 5-card combinations and evaluates each one.
  * 
  * @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.
  * @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) {
-  const evaluator = new HandEvaluator(cards);
+function evaluateHand(cards, strict = true) {
+  const evaluator = new HandEvaluator(cards, strict);
   return evaluator.evaluation;
 }
 

package/package.json

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