poker-extval 3.0.0 → 3.1.1

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
@@ -135,6 +166,8 @@ The `evaluateHand()` function returns an object where:
 
 ### Example Response
 
+**Example 1: Royal Flush (strict mode - default)**
+
 ```javascript
 {
   "As, Ks, Qs, Js, Ts": {
@@ -143,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,
@@ -167,8 +200,8 @@ The `evaluateHand()` function returns an object where:
       "isStraightFlush": [],
       "isFourOfAKind": [],
       "isFullHouse": [],
-      "isFlush": ["As", "Ks", "Qs", "Js", "Ts"],
-      "isStraight": ["As", "Ks", "Qs", "Js", "Ts"],
+      "isFlush": [],  // Empty in strict mode (royal flush is stronger)
+      "isStraight": [],  // Empty in strict mode (royal flush is stronger)
       "isThreeOfAKind": [],
       "isTwoPair": [],
       "isPair": [],
@@ -224,13 +257,13 @@ The `evaluateHand()` function returns an object where:
 }
 ```
 
-**Example 2: Pair with Flush Draw**
+**Example 2: Pair with Flush Draw (strict mode - default)**
 
 ```javascript
 {
   "As, Ah, Ks, Qs, Js": {
     "isPair": true,
-    "isFlushDraw": true,
+    "isFlushDraw": true,  // Draws can coexist with made hands in strict mode
     // ... other boolean properties ...
     "keyCards": {
       "isPair": ["As", "Ah"],
@@ -246,6 +279,29 @@ The `evaluateHand()` function returns an object where:
 }
 ```
 
+**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 ...
+    }
+  }
+}
+```
+
 ## Performance Benchmarks
 
 This library prioritizes **extensiveness and accuracy over raw speed**. The evaluation system is designed to provide comprehensive analysis of all possible hand combinations, which means:
@@ -324,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
@@ -342,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();
   }
 
@@ -197,12 +206,190 @@ class HandEvaluator {
     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;
     
     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;
+    }
+  }
+
+  /**
+   * Gets the hand strength value for an evaluation.
+   * 
+   * @private
+   * @param {Object} evaluation - The evaluation object
+   * @returns {number} Hand strength (10 = Royal Flush, 1 = High Card, 0 = no made hand)
+   */
+  #getHandStrength(evaluation) {
+    const handStrength = {
+      isRoyalFlush: 10, isStraightFlush: 9, isFourOfAKind: 8,
+      isFullHouse: 7, isFlush: 6, isStraight: 5, isThreeOfAKind: 4,
+      isTwoPair: 3, isPair: 2, isHighCard: 1
+    };
+    for (const [hand, strength] of Object.entries(handStrength)) {
+      if (evaluation[hand]) return strength;
+    }
+    return 0;
+  }
+
+  /**
+   * Gets sorted key card ranks for an evaluation.
+   * 
+   * @private
+   * @param {Object} evaluation - The evaluation object
+   * @returns {number[]} Array of rank values sorted descending
+   */
+  #getKeyCardRanks(evaluation) {
+    const handStrength = {
+      isRoyalFlush: 10, isStraightFlush: 9, isFourOfAKind: 8,
+      isFullHouse: 7, isFlush: 6, isStraight: 5, isThreeOfAKind: 4,
+      isTwoPair: 3, isPair: 2, isHighCard: 1
+    };
+    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);
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Gets sorted kicker ranks for an evaluation.
+   * 
+   * @private
+   * @param {Object} evaluation - The evaluation object
+   * @returns {number[]} Array of rank values sorted descending
+   */
+  #getKickerRanks(evaluation) {
+    const handStrength = {
+      isRoyalFlush: 10, isStraightFlush: 9, isFourOfAKind: 8,
+      isFullHouse: 7, isFlush: 6, isStraight: 5, isThreeOfAKind: 4,
+      isTwoPair: 3, isPair: 2, isHighCard: 1
+    };
+    for (const [hand] of Object.entries(handStrength)) {
+      if (evaluation[hand]) {
+        const kickers = evaluation.kickerCards[hand] || [];
+        return kickers.map(c => this.#getRankValue(c)).sort((a, b) => b - a);
+      }
+    }
+    return [];
+  }
+
+  /**
+   * Compares two evaluations to determine which is better.
+   * 
+   * @private
+   * @param {Object} eval1 - First evaluation object
+   * @param {Object} eval2 - Second evaluation object
+   * @returns {number} Positive if eval2 is better, negative if eval1 is better, 0 if equal
+   */
+  #compareEvaluations(eval1, eval2) {
+    const strength1 = this.#getHandStrength(eval1);
+    const strength2 = this.#getHandStrength(eval2);
+    if (strength1 !== strength2) return strength2 - strength1;
+    
+    const keyRanks1 = this.#getKeyCardRanks(eval1);
+    const keyRanks2 = this.#getKeyCardRanks(eval2);
+    for (let i = 0; i < Math.max(keyRanks1.length, keyRanks2.length); i++) {
+      const rank1 = keyRanks1[i] || 0;
+      const rank2 = keyRanks2[i] || 0;
+      if (rank1 !== rank2) return rank2 - rank1;
+    }
+    
+    const kickerRanks1 = this.#getKickerRanks(eval1);
+    const kickerRanks2 = this.#getKickerRanks(eval2);
+    for (let i = 0; i < Math.max(kickerRanks1.length, kickerRanks2.length); i++) {
+      const rank1 = kickerRanks1[i] || 0;
+      const rank2 = kickerRanks2[i] || 0;
+      if (rank1 !== rank2) return rank2 - rank1;
+    }
+    return 0;
+  }
+
+  /**
+   * Finds the best combination from a result object.
+   * 
+   * @private
+   * @param {Object} result - Object mapping hand keys to evaluation objects
+   * @returns {Object} Object with only the best combination
+   */
+  #findBestCombination(result) {
+    let bestKey = null;
+    let bestEval = null;
+    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)) {
+        bestKey = key;
+        bestEval = evaluation;
+      }
+    }
+    return bestKey ? { [bestKey]: bestEval } : result;
+  }
+
   /**
    * Evaluates all possible 5-card combinations from the input cards.
    * For exactly 5 cards, evaluates directly. For more cards, generates all combinations
@@ -218,26 +405,22 @@ class HandEvaluator {
    * // With 7 cards: returns object with 21 key-value pairs (C(7,5) = 21)
    */
   #evaluateAllCombinations() {
-    // If exactly 5 cards, evaluate directly and wrap in the new format
     if (this.cards.length === 5) {
       const key = this.#formatHandKey(this.cards);
       const evaluation = this.#evaluateSingleHand();
       return { [key]: evaluation };
     }
     
-    // For more than 5 cards, generate all combinations
     const combinations = this.#generateCombinations(this.cards, 5);
     const result = {};
     for (const combination of combinations) {
       const key = this.#formatHandKey(combination);
-      // Create a temporary evaluator with the 5-card combination
-      // This will evaluate directly since it's exactly 5 cards
-      const tempEvaluator = new HandEvaluator(combination);
-      // Extract the evaluation object from the single key-value pair
+      const tempEvaluator = new HandEvaluator(combination, this.strict);
       const evaluationKey = Object.keys(tempEvaluator.evaluation)[0];
       result[key] = tempEvaluator.evaluation[evaluationKey];
     }
-    return result;
+    
+    return this.strict ? this.#findBestCombination(result) : result;
   }
 
   /**
@@ -1423,10 +1606,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": "3.0.0",
+  "version": "3.1.1",
   "description": "Poker hand evaluator with comprehensive test suite",
   "main": "evaluator.js",
   "files": [