poker-extval 1.1.0 → 3.0.0

package/README.md

@@ -49,12 +49,6 @@ 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
-
-// Use utility methods
-evaluator.sort(); // Sort cards by rank
-evaluator.getDistance(); // Get distance between highest and lowest card
-evaluator.countSuits(); // Count suits in hand
-evaluator.countRanks(); // Count ranks in hand
 ```
 
 ### Evaluating Multiple Card Hands
@@ -126,12 +120,19 @@ The `evaluateHand()` function returns an object where:
 - `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)
+- `isStraightDraw` - Any type of straight draw (open-ended or inside, standard or wheel)
 
 #### Wheel Straight Support
 - `isStraightWheel` - Wheel straight (A-2-3-4-5)
 - `isOpenEndedStraightDrawWheel` - Open-ended draw using wheel ranking
 - `isInsideStraightDrawWheel` - Inside draw using wheel ranking
 
+#### Card Arrays
+- `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
 
 ```javascript
@@ -159,7 +160,88 @@ The `evaluateHand()` function returns an object where:
     "isBackdoorFlushDraw": false,
     "isOpenEndedStraightDraw": false,
     "isInsideStraightDraw": false,
-    "isHighCard": false
+    "isStraightDraw": false,
+    "isHighCard": false,
+    "keyCards": {
+      "isRoyalFlush": ["As", "Ks", "Qs", "Js", "Ts"],
+      "isStraightFlush": [],
+      "isFourOfAKind": [],
+      "isFullHouse": [],
+      "isFlush": ["As", "Ks", "Qs", "Js", "Ts"],
+      "isStraight": ["As", "Ks", "Qs", "Js", "Ts"],
+      "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**
+
+```javascript
+{
+  "As, Ah, Ks, Qs, Js": {
+    "isPair": true,
+    "isFlushDraw": true,
+    // ... 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 ...
+    }
   }
 }
 ```
@@ -265,16 +347,14 @@ new HandEvaluator(cards)
 
 Creates a new HandEvaluator instance.
 
-#### Methods
+**Parameters:**
+- `cards` (string[]): Array of 5 or more card strings
 
-- `sort(cards?)` - Sort cards by rank (highest to lowest)
-- `sortWheel(cards?)` - Sort cards using wheel ranking (Ace low)
-- `getDistance(cards?)` - Calculate distance between highest and lowest card
-- `getDistanceWheel(cards?)` - Calculate distance using wheel ranking
-- `countSuits()` - Count occurrences of each suit
-- `countRanks()` - Count occurrences of each rank (sorted)
+**Properties:**
+- `evaluation` - Object mapping sorted hand strings to evaluation objects (same format as `evaluateHand()` return value)
+- `cards` - Array of input cards
 
-All evaluation methods (e.g., `isPair()`, `isFlush()`, etc.) are available but typically accessed through the `evaluation` property.
+**Note**: All internal methods are private. Use the `evaluation` property to access evaluation results.
 
 ## License