@creatiosoft/poker-odds-calculator 1.0.0

package/README.md

@@ -0,0 +1,354 @@
+# @creatiosoft/poker-odds-calculator
+
+A TypeScript package that calculates winning probability for poker hands across all major variants using **Monte Carlo simulation**.
+
+Supports **NLH**, **PLO4**, **PLO5**, and **PLO6**.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Understanding the Result](#understanding-the-result)
+- [What is Monte Carlo Simulation?](#what-is-monte-carlo-simulation)
+- [How We Use It](#how-we-use-it)
+- [Why Not Use poker-evaluator's Built-in Odds?](#why-not-use-poker-evaluators-built-in-odds)
+- [Supported Variants](#supported-variants)
+- [Card Format](#card-format)
+- [Accuracy vs Iterations](#accuracy-vs-iterations)
+
+---
+
+## Installation
+
+```bash
+npm install @creatiosoft/poker-odds-calculator
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { calculateOdds, calculateTableOdds } from '@creatiosoft/poker-odds-calculator';
+
+// How likely am I to win with pocket Aces against 2 unknown opponents?
+const result = calculateOdds({
+  variant: 'NLH',
+  holeCards: ['Ah', 'As'],
+  communityCards: [],
+  playerCount: 3,
+  iterations: 5000
+});
+
+console.log(result.winRate);      // e.g. 0.73  → 73% chance to win outright
+console.log(result.splitRates);   // e.g. [{ rate: 0.01, ways: 2 }] → 1% chance to split with 1 player
+```
+
+---
+
+## API Reference
+
+### `calculateOdds(input)` — Single Player
+
+Use this when **only your cards are known** and opponents' cards are random (the most common real-time table scenario).
+
+```typescript
+calculateOdds({
+  variant:        'PLO4',          // game variant (see Supported Variants)
+  holeCards:      ['Ah','As','Kh','Kd'],  // your hole cards
+  communityCards: ['2c','7h','Jd'],       // board cards dealt so far (0–5)
+  playerCount:    3,               // total players including you
+  iterations:     5000             // Monte Carlo cycles (optional, default 1000)
+}): PlayerOdds
+```
+
+**Returns:** `PlayerOdds` — your odds only (player 0).
+
+---
+
+### `calculateTableOdds(input)` — All Players Known
+
+Use this when **all hole cards are visible** — e.g. a run-it-out, a showdown analysis, or a training tool.
+
+```typescript
+calculateTableOdds({
+  variant:        'NLH',
+  hands: [
+    ['Ah', 'As'],   // player 0
+    ['Kh', 'Kd'],   // player 1
+    ['Qh', 'Qd'],   // player 2
+  ],
+  communityCards: ['2c', '7h', 'Jd'],
+  iterations:     5000
+}): TableOdds
+```
+
+**Returns:** `TableOdds` — an array of `PlayerOdds`, one per player, in the same order as `hands`.
+
+---
+
+## Understanding the Result
+
+### `PlayerOdds`
+
+```typescript
+{
+  winRate:    0.72,   // fraction of simulated games this player wins outright
+  splitRates: [
+    { rate: 0.03, ways: 2 },   // 3% of games end in a 2-way split
+    { rate: 0.01, ways: 3 },   // 1% of games end in a 3-way split
+  ]
+}
+```
+
+#### `winRate`
+The fraction of iterations where **this player won the entire pot outright** — no ties, no splits. A value of `0.72` means the player wins 72 out of every 100 simulated hands.
+
+#### `splitRates`
+An array describing **how often the pot is split** and **how many players share it**.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `rate` | `number` | Fraction of iterations where the pot was split this way |
+| `ways` | `number` | How many players split the pot (2 = heads-up tie, 3 = three-way tie, …) |
+
+**Example — reading a split result:**
+```
+winRate:    0.68
+splitRates: [{ rate: 0.04, ways: 2 }]
+```
+This means:
+- 68% of the time → you win the whole pot
+- 4% of the time → you and exactly one other player tie (split 50/50)
+- 28% of the time → you lose
+
+**Expected pot share formula:**
+```
+expectedShare = winRate + Σ (splitRate.rate / splitRate.ways)
+             = 0.68 + (0.04 / 2)
+             = 0.68 + 0.02
+             = 0.70   →  you expect 70% of the pot on average
+```
+
+#### `TableOdds`
+```typescript
+{
+  players: [PlayerOdds, PlayerOdds, ...]  // same order as the hands[] you passed in
+}
+```
+
+The `winRate` values across all players **do not sum to 1** — splits account for the remainder. But `winRate + splitContribution` summed across all players **does** equal 1 (the whole pot is always distributed).
+
+---
+
+## What is Monte Carlo Simulation?
+
+Monte Carlo simulation is a technique for estimating probabilities by **running a scenario thousands of times with random inputs** and counting outcomes.
+
+In poker, the number of possible combinations of cards is astronomically large. For example, dealing 2 unknown opponents on a blank board has over 1 billion possible runouts. Calculating exact probabilities by enumerating every combination would take too long for real-time use.
+
+**Monte Carlo solves this by sampling:**
+
+> Instead of checking all 1 billion possibilities, deal out the remaining cards randomly 5,000 times. Count how often you win. 5,000 samples gives you a result accurate to within ~1%.
+
+### Analogy
+
+Imagine you want to know the probability of rolling two dice and getting a sum of 7. You could:
+- **Exact method:** list all 36 combinations, count the 6 that sum to 7 → 6/36 = 16.7%
+- **Monte Carlo:** roll the dice 10,000 times, count the 7s → you'll get roughly 16.7%
+
+For poker, the "exact method" is too slow for real-time use. Monte Carlo gives us a fast, accurate-enough answer.
+
+---
+
+## How We Use It
+
+Here is exactly what happens inside each call to `calculateOdds`:
+
+### Step 1 — Build the Remaining Deck
+
+We start with a full 52-card deck and remove every card that is already known (your hole cards + any community cards already dealt).
+
+```
+Full deck (52 cards)
+− your hole cards (2–6 cards)
+− community cards already on board (0–5 cards)
+= remaining deck (41–50 cards)
+```
+
+### Step 2 — Run N Iterations
+
+For each iteration:
+
+**1. Shuffle** the remaining deck using the Fisher-Yates algorithm (the same unbiased shuffle used in `poker-evaluator`).
+
+**2. Deal** cards to fill in the unknowns:
+- Each opponent gets hole cards dealt from the top of the shuffled deck
+- The community cards are completed to 5 if not already
+
+**3. Evaluate** each player's best hand using the correct rule for the variant (see below).
+
+**4. Find the winner** — the player with the highest hand value wins. If multiple players have equal values, the pot is split.
+
+**5. Record** the result — increment that player's win or split counter.
+
+### Step 3 — Calculate Rates
+
+After all iterations:
+```
+winRate  = wins[player] / totalIterations
+splitRate = splits[player][ways-2] / totalIterations
+```
+
+### Hand Evaluation per Variant
+
+This is where our package differs from `poker-evaluator`'s built-in odds calculator:
+
+| Variant | Rule | How we evaluate |
+|---|---|---|
+| NLH | Best 5 from any 7 cards | Pass all 7 cards to `evalHand` — it picks the best 5 |
+| PLO4 | Exactly 2 hole + 3 board | Generate all C(4,2)=6 hole pairs × C(5,3)=10 board triples = **60 combinations**, evaluate each, take the best |
+| PLO5 | Exactly 2 hole + 3 board | C(5,2)=10 × C(5,3)=10 = **100 combinations** per player |
+| PLO6 | Exactly 2 hole + 3 board | C(6,2)=15 × C(5,3)=10 = **150 combinations** per player |
+
+For NLH the library's own `evalHand` does the work. For PLO we enumerate every legal 2+3 combination ourselves, call `evalHand` on each 5-card hand, and take the highest value.
+
+### Visual Walkthrough — One Iteration (PLO4, 2 Players)
+
+```
+Your hand : [Ah, As, Kh, Kd]      (known)
+Board     : [2c, 7h, Jd]          (known, flop)
+Deck left : 45 cards
+
+Shuffle deck → [Qc, 3h, 9s, Tc, 6d, ...]
+
+Deal opponent: Qc, 3h  (first 2 from shuffled deck)
+Complete board: 9s, Tc  (next 2 cards → board = [2c,7h,Jd,9s,Tc])
+
+Evaluate YOUR hand (PLO4 — must use exactly 2 hole + 3 board):
+  Ah+As + 2c+7h+Jd → evalHand([Ah,As,2c,7h,Jd]) → one pair aces
+  Ah+As + 2c+7h+9s → evalHand([Ah,As,2c,7h,9s]) → one pair aces
+  Ah+As + 2c+7h+Tc → evalHand([Ah,As,2c,7h,Tc]) → one pair aces
+  Ah+Kh + 2c+7h+Jd → evalHand([Ah,Kh,2c,7h,Jd]) → high card
+  Ah+As + Jd+9s+Tc → evalHand([Ah,As,Jd,9s,Tc]) → one pair aces
+  ... (60 total combos)
+  Best value for you → one pair aces (value: 3553)
+
+Evaluate OPPONENT hand [Qc, 3h] (PLO4):
+  Qc+3h + 2c+7h+Jd → high card queen
+  ... (60 combos)
+  Best value for opponent → high card queen (value: 1210)
+
+3553 > 1210 → YOU WIN this iteration
+wins[0]++
+```
+
+Repeat 5000 times → `winRate = wins[0] / 5000`
+
+---
+
+## Why Not Use poker-evaluator's Built-in Odds?
+
+`poker-evaluator` ships `winningOddsForPlayer` and `winningOddsForTable` but they are **NLH-only**. Two lines in their source code make this impossible to reuse for PLO:
+
+```javascript
+// poker-evaluator source — hardcoded 2 hole cards, no way to change
+var card1 = numHands[p][0] ?? startingDeck[deckPosition++];
+var card2 = numHands[p][1] ?? startingDeck[deckPosition++];
+holeCards.push([card1, card2]);  // ← always 2 cards, PLO needs 4/5/6
+
+// NLH rule: best 5 from any 7
+evalHand([...hand, ...communityCards]).value  // ← wrong for PLO
+// PLO rule: must use exactly 2 from hole + 3 from board
+```
+
+We **reuse** `evalHand` (the fast O(1) lookup table) and write our own loop around it that correctly handles variable hole card counts and the PLO 2+3 constraint.
+
+---
+
+## Supported Variants
+
+| Variant | Hole Cards | Evaluation Rule |
+|---|---|---|
+| `NLH` | 2 | Best 5 from any 7 (hole + board) |
+| `PLO4` | 4 | Exactly 2 from hole + exactly 3 from board |
+| `PLO5` | 5 | Exactly 2 from hole + exactly 3 from board |
+| `PLO6` | 6 | Exactly 2 from hole + exactly 3 from board |
+
+---
+
+## Card Format
+
+```
+<rank><suit>
+
+Ranks : A  K  Q  J  T  9  8  7  6  5  4  3  2
+Suits : s (spades)  h (hearts)  d (diamonds)  c (clubs)
+
+Examples:
+  'As' → Ace of Spades
+  'Kh' → King of Hearts
+  'Td' → Ten of Diamonds
+  '2c' → Two of Clubs
+```
+
+---
+
+## Accuracy vs Iterations
+
+Both `winRate` and `splitRates` become more accurate as you increase `iterations`. More iterations = smaller margin of error but slower response.
+
+| Iterations | Typical error | Time (NLH) | Time (PLO4) | Recommended for |
+|---:|---:|---:|---:|---|
+| 1 000 | ±2–3% | ~13 ms | ~200 ms | Development / unit tests |
+| 5 000 | ±1% | ~44 ms | ~990 ms | Real-time display at the table |
+| 10 000 | ±0.5% | ~100 ms | ~2 000 ms | High-accuracy analysis |
+| 100 000 | ±0.1% | ~1 s | ~20 s | Pre-computation / batch jobs |
+
+For **real-time use** in a running game, 5 000 iterations is the recommended balance — fast enough to feel instant for NLH, and accurate to within 1%.
+
+For PLO at real-time speed, consider running the simulation in a **Node.js worker thread** so it does not block the main event loop.
+
+---
+
+## Full Example
+
+```typescript
+import { calculateOdds, calculateTableOdds } from '@creatiosoft/poker-odds-calculator';
+
+// ── Example 1: Your hand only (most common) ──────────────────────────────────
+
+const myOdds = calculateOdds({
+  variant: 'PLO4',
+  holeCards: ['Ah', 'As', 'Kh', 'Kd'],   // double-suited aces and kings
+  communityCards: ['2c', '7h', 'Jd'],     // flop is out
+  playerCount: 3,                          // you + 2 opponents
+  iterations: 5000
+});
+
+console.log(`Win rate   : ${(myOdds.winRate * 100).toFixed(1)}%`);
+myOdds.splitRates.forEach(s =>
+  console.log(`${s.ways}-way split: ${(s.rate * 100).toFixed(1)}%`)
+);
+
+// ── Example 2: Full table (all hands known) ──────────────────────────────────
+
+const table = calculateTableOdds({
+  variant: 'NLH',
+  hands: [
+    ['Ah', 'As'],   // player 0 — pocket aces
+    ['Kh', 'Kd'],   // player 1 — pocket kings
+  ],
+  communityCards: [],   // preflop
+  iterations: 10000
+});
+
+table.players.forEach((p, i) =>
+  console.log(`Player ${i}: ${(p.winRate * 100).toFixed(1)}% win`)
+);
+// Player 0: 81.2% win
+// Player 1: 17.8% win
+```

package/dist/constants/deck.const.d.ts

@@ -0,0 +1,3 @@
+export declare const FULL_DECK: string[];
+export declare const HOLE_CARD_COUNT: Record<string, number>;
+//# sourceMappingURL=deck.const.d.ts.map

package/dist/constants/deck.const.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deck.const.d.ts","sourceRoot":"","sources":["../../src/constants/deck.const.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,SAAS,EAAE,MAAM,EAA8C,CAAC;AAE7E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKlD,CAAC"}

package/dist/constants/deck.const.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOLE_CARD_COUNT = exports.FULL_DECK = void 0;
+const RANKS = ['2', '3', '4', '5', '6', '7', '8', '9', 'T', 'J', 'Q', 'K', 'A'];
+const SUITS = ['c', 'd', 'h', 's'];
+exports.FULL_DECK = RANKS.flatMap(r => SUITS.map(s => r + s));
+exports.HOLE_CARD_COUNT = {
+    NLH: 2,
+    PLO4: 4,
+    PLO5: 5,
+    PLO6: 6,
+};
+//# sourceMappingURL=deck.const.js.map

package/dist/constants/deck.const.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deck.const.js","sourceRoot":"","sources":["../../src/constants/deck.const.ts"],"names":[],"mappings":";;;AAAA,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAChF,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEtB,QAAA,SAAS,GAAa,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEhE,QAAA,eAAe,GAA2B;IACrD,GAAG,EAAE,CAAC;IACN,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;CACR,CAAC"}

package/dist/evaluator/nlh.evaluator.d.ts

@@ -0,0 +1,2 @@
+export declare function evalNLH(holeCards: string[], boardCards: string[]): number;
+//# sourceMappingURL=nlh.evaluator.d.ts.map

package/dist/evaluator/nlh.evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nlh.evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/nlh.evaluator.ts"],"names":[],"mappings":"AAEA,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAEzE"}

package/dist/evaluator/nlh.evaluator.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evalNLH = evalNLH;
+const poker_evaluator_1 = require("poker-evaluator");
+function evalNLH(holeCards, boardCards) {
+    return (0, poker_evaluator_1.evalHand)([...holeCards, ...boardCards]).value;
+}
+//# sourceMappingURL=nlh.evaluator.js.map

package/dist/evaluator/nlh.evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nlh.evaluator.js","sourceRoot":"","sources":["../../src/evaluator/nlh.evaluator.ts"],"names":[],"mappings":";;AAEA,0BAEC;AAJD,qDAA2C;AAE3C,SAAgB,OAAO,CAAC,SAAmB,EAAE,UAAoB;IAC/D,OAAO,IAAA,0BAAQ,EAAC,CAAC,GAAG,SAAS,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;AACvD,CAAC"}

package/dist/evaluator/omaha.evaluator.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Evaluates an Omaha hand (PLO4/5/6) using the mandatory 2-from-hole + 3-from-board rule.
+ * Returns the highest hand value (higher = stronger).
+ */
+export declare function evalOmaha(holeCards: string[], boardCards: string[]): number;
+//# sourceMappingURL=omaha.evaluator.d.ts.map

package/dist/evaluator/omaha.evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"omaha.evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluator/omaha.evaluator.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAY3E"}

package/dist/evaluator/omaha.evaluator.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evalOmaha = evalOmaha;
+const poker_evaluator_1 = require("poker-evaluator");
+const combination_1 = require("../utils/combination");
+/**
+ * Evaluates an Omaha hand (PLO4/5/6) using the mandatory 2-from-hole + 3-from-board rule.
+ * Returns the highest hand value (higher = stronger).
+ */
+function evalOmaha(holeCards, boardCards) {
+    const holeCombos = (0, combination_1.combinations)(holeCards, 2);
+    const boardCombos = (0, combination_1.combinations)(boardCards, 3);
+    let bestValue = -1;
+    for (const hc of holeCombos) {
+        for (const bc of boardCombos) {
+            const value = (0, poker_evaluator_1.evalHand)([...hc, ...bc]).value;
+            if (value > bestValue)
+                bestValue = value;
+        }
+    }
+    return bestValue;
+}
+//# sourceMappingURL=omaha.evaluator.js.map

package/dist/evaluator/omaha.evaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"omaha.evaluator.js","sourceRoot":"","sources":["../../src/evaluator/omaha.evaluator.ts"],"names":[],"mappings":";;AAOA,8BAYC;AAnBD,qDAA2C;AAC3C,sDAAoD;AAEpD;;;GAGG;AACH,SAAgB,SAAS,CAAC,SAAmB,EAAE,UAAoB;IACjE,MAAM,UAAU,GAAG,IAAA,0BAAY,EAAC,SAAS,EAAE,CAAC,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,IAAA,0BAAY,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAEhD,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;IACnB,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,IAAA,0BAAQ,EAAC,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7C,IAAI,KAAK,GAAG,SAAS;gBAAE,SAAS,GAAG,KAAK,CAAC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { CalculateOddsInput, CalculateTableOddsInput, PlayerOdds, TableOdds } from './types/odds.interface';
+export type { Variant } from './types/variant.type';
+export type { Card } from './types/card.type';
+export type { Split, PlayerOdds, TableOdds, CalculateOddsInput, CalculateTableOddsInput, } from './types/odds.interface';
+/**
+ * Calculates win odds for a single player against N-1 unknown opponents.
+ * The caller's hole cards are known; all other hands are randomly simulated.
+ */
+export declare function calculateOdds(input: CalculateOddsInput): PlayerOdds;
+/**
+ * Calculates win odds for all players when all hole cards are known (e.g. a run-it-out scenario).
+ */
+export declare function calculateTableOdds(input: CalculateTableOddsInput): TableOdds;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,UAAU,EACV,SAAS,EACV,MAAM,wBAAwB,CAAC;AAEhC,YAAY,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,YAAY,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,YAAY,EACV,KAAK,EACL,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAShC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CAiBnE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,CAU5E"}

package/dist/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateOdds = calculateOdds;
+exports.calculateTableOdds = calculateTableOdds;
+const monteCarlo_1 = require("./simulator/monteCarlo");
+const DEFAULT_ITERATIONS = {
+    NLH: 1000,
+    PLO4: 500,
+    PLO5: 300,
+    PLO6: 200,
+};
+/**
+ * Calculates win odds for a single player against N-1 unknown opponents.
+ * The caller's hole cards are known; all other hands are randomly simulated.
+ */
+function calculateOdds(input) {
+    const iterations = input.iterations ?? DEFAULT_ITERATIONS[input.variant];
+    const knownHands = [
+        input.holeCards,
+        ...Array(input.playerCount - 1).fill([]),
+    ];
+    const result = (0, monteCarlo_1.runMonteCarlo)({
+        variant: input.variant,
+        knownHands,
+        community: input.communityCards,
+        playerCount: input.playerCount,
+        iterations,
+    });
+    return result.players[0];
+}
+/**
+ * Calculates win odds for all players when all hole cards are known (e.g. a run-it-out scenario).
+ */
+function calculateTableOdds(input) {
+    const iterations = input.iterations ?? DEFAULT_ITERATIONS[input.variant];
+    return (0, monteCarlo_1.runMonteCarlo)({
+        variant: input.variant,
+        knownHands: input.hands,
+        community: input.communityCards,
+        playerCount: input.hands.length,
+        iterations,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;AA6BA,sCAiBC;AAKD,gDAUC;AA7DD,uDAAuD;AAkBvD,MAAM,kBAAkB,GAA2B;IACjD,GAAG,EAAG,IAAI;IACV,IAAI,EAAG,GAAG;IACV,IAAI,EAAG,GAAG;IACV,IAAI,EAAG,GAAG;CACX,CAAC;AAEF;;;GAGG;AACH,SAAgB,aAAa,CAAC,KAAyB;IACrD,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAEzE,MAAM,UAAU,GAAG;QACjB,KAAK,CAAC,SAAS;QACf,GAAG,KAAK,CAAW,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;KACnD,CAAC;IAEF,MAAM,MAAM,GAAG,IAAA,0BAAa,EAAC;QAC3B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU;QACV,SAAS,EAAE,KAAK,CAAC,cAAc;QAC/B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU;KACX,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,KAA8B;IAC/D,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAEzE,OAAO,IAAA,0BAAa,EAAC;QACnB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,KAAK;QACvB,SAAS,EAAE,KAAK,CAAC,cAAc;QAC/B,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM;QAC/B,UAAU;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/simulator/deck.d.ts

@@ -0,0 +1,3 @@
+export declare function buildRemainingDeck(knownCards: string[]): string[];
+export declare function shuffleDeck(deck: string[]): void;
+//# sourceMappingURL=deck.d.ts.map

package/dist/simulator/deck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deck.d.ts","sourceRoot":"","sources":["../../src/simulator/deck.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGjE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAKhD"}

package/dist/simulator/deck.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRemainingDeck = buildRemainingDeck;
+exports.shuffleDeck = shuffleDeck;
+const deck_const_1 = require("../constants/deck.const");
+function buildRemainingDeck(knownCards) {
+    const known = new Set(knownCards.map(c => c.toLowerCase()));
+    return deck_const_1.FULL_DECK.filter(card => !known.has(card.toLowerCase()));
+}
+function shuffleDeck(deck) {
+    for (let i = deck.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [deck[i], deck[j]] = [deck[j], deck[i]];
+    }
+}
+//# sourceMappingURL=deck.js.map

package/dist/simulator/deck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deck.js","sourceRoot":"","sources":["../../src/simulator/deck.ts"],"names":[],"mappings":";;AAEA,gDAGC;AAED,kCAKC;AAZD,wDAAoD;AAEpD,SAAgB,kBAAkB,CAAC,UAAoB;IACrD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAC5D,OAAO,sBAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAgB,WAAW,CAAC,IAAc;IACxC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC"}

package/dist/simulator/monteCarlo.d.ts

@@ -0,0 +1,11 @@
+import { Variant } from '../types/variant.type';
+import { TableOdds } from '../types/odds.interface';
+export interface SimulationConfig {
+    variant: Variant;
+    knownHands: string[][];
+    community: string[];
+    playerCount: number;
+    iterations: number;
+}
+export declare function runMonteCarlo(config: SimulationConfig): TableOdds;
+//# sourceMappingURL=monteCarlo.d.ts.map

package/dist/simulator/monteCarlo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monteCarlo.d.ts","sourceRoot":"","sources":["../../src/simulator/monteCarlo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAMpD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IACvB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAwDjE"}

package/dist/simulator/monteCarlo.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMonteCarlo = runMonteCarlo;
+const deck_const_1 = require("../constants/deck.const");
+const deck_1 = require("./deck");
+const nlh_evaluator_1 = require("../evaluator/nlh.evaluator");
+const omaha_evaluator_1 = require("../evaluator/omaha.evaluator");
+function runMonteCarlo(config) {
+    const { variant, knownHands, community, playerCount, iterations } = config;
+    const holeCount = deck_const_1.HOLE_CARD_COUNT[variant];
+    const t0 = performance.now();
+    const allKnown = [...community, ...knownHands.flat()];
+    const deck = (0, deck_1.buildRemainingDeck)(allKnown);
+    const wins = new Array(playerCount).fill(0);
+    const splits = Array.from({ length: playerCount }, () => new Array(playerCount - 1).fill(0));
+    for (let i = 0; i < iterations; i++) {
+        (0, deck_1.shuffleDeck)(deck);
+        let pos = 0;
+        const hands = [];
+        for (let p = 0; p < playerCount; p++) {
+            const known = knownHands[p] ?? [];
+            const needed = holeCount - known.length;
+            hands.push([...known, ...deck.slice(pos, pos + needed)]);
+            pos += needed;
+        }
+        const board = [...community];
+        while (board.length < 5)
+            board.push(deck[pos++]);
+        const values = hands.map(hand => variant === 'NLH' ? (0, nlh_evaluator_1.evalNLH)(hand, board) : (0, omaha_evaluator_1.evalOmaha)(hand, board));
+        const best = Math.max(...values);
+        const winners = values.reduce((acc, v, idx) => {
+            if (v === best)
+                acc.push(idx);
+            return acc;
+        }, []);
+        if (winners.length === 1) {
+            wins[winners[0]]++;
+        }
+        else {
+            winners.forEach(idx => splits[idx][winners.length - 2]++);
+        }
+    }
+    const elapsed = (performance.now() - t0).toFixed(1);
+    console.log(`[${variant}] ${iterations} iterations, ${playerCount} players → ${elapsed}ms`);
+    return {
+        players: wins.map((w, p) => ({
+            winRate: w / iterations,
+            splitRates: splits[p]
+                .map((s, i) => ({ rate: s / iterations, ways: i + 2 }))
+                .filter(s => s.rate > 0),
+        })),
+    };
+}
+//# sourceMappingURL=monteCarlo.js.map

package/dist/simulator/monteCarlo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"monteCarlo.js","sourceRoot":"","sources":["../../src/simulator/monteCarlo.ts"],"names":[],"mappings":"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"}

package/dist/types/card.type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Standard card notation: rank + suit
+ * Ranks: A K Q J T 9 8 7 6 5 4 3 2
+ * Suits: s (spades) h (hearts) d (diamonds) c (clubs)
+ * Example: "As", "Kh", "Td", "2c"
+ */
+export type Card = string;
+//# sourceMappingURL=card.type.d.ts.map

package/dist/types/card.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.type.d.ts","sourceRoot":"","sources":["../../src/types/card.type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,CAAC"}

package/dist/types/card.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=card.type.js.map

package/dist/types/card.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.type.js","sourceRoot":"","sources":["../../src/types/card.type.ts"],"names":[],"mappings":""}

package/dist/types/odds.interface.d.ts

@@ -0,0 +1,25 @@
+export interface Split {
+    rate: number;
+    ways: number;
+}
+export interface PlayerOdds {
+    winRate: number;
+    splitRates: Split[];
+}
+export interface TableOdds {
+    players: PlayerOdds[];
+}
+export interface CalculateOddsInput {
+    variant: import('./variant.type').Variant;
+    holeCards: string[];
+    communityCards: string[];
+    playerCount: number;
+    iterations?: number;
+}
+export interface CalculateTableOddsInput {
+    variant: import('./variant.type').Variant;
+    hands: string[][];
+    communityCards: string[];
+    iterations?: number;
+}
+//# sourceMappingURL=odds.interface.d.ts.map

package/dist/types/odds.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"odds.interface.d.ts","sourceRoot":"","sources":["../../src/types/odds.interface.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,KAAK,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,gBAAgB,EAAE,OAAO,CAAC;IAC1C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,gBAAgB,EAAE,OAAO,CAAC;IAC1C,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/odds.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=odds.interface.js.map

package/dist/types/odds.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"odds.interface.js","sourceRoot":"","sources":["../../src/types/odds.interface.ts"],"names":[],"mappings":""}

package/dist/types/variant.type.d.ts

@@ -0,0 +1,2 @@
+export type Variant = 'NLH' | 'PLO4' | 'PLO5' | 'PLO6';
+//# sourceMappingURL=variant.type.d.ts.map

package/dist/types/variant.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant.type.d.ts","sourceRoot":"","sources":["../../src/types/variant.type.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC"}

package/dist/types/variant.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=variant.type.js.map

package/dist/types/variant.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant.type.js","sourceRoot":"","sources":["../../src/types/variant.type.ts"],"names":[],"mappings":""}

package/dist/utils/combination.d.ts

@@ -0,0 +1,2 @@
+export declare function combinations<T>(set: T[], k: number): T[][];
+//# sourceMappingURL=combination.d.ts.map

package/dist/utils/combination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combination.d.ts","sourceRoot":"","sources":["../../src/utils/combination.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAc1D"}

package/dist/utils/combination.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.combinations = combinations;
+function combinations(set, k) {
+    if (k > set.length || k <= 0)
+        return [];
+    if (k === set.length)
+        return [set];
+    if (k === 1)
+        return set.map(item => [item]);
+    const result = [];
+    for (let i = 0; i <= set.length - k; i++) {
+        const head = set.slice(i, i + 1);
+        const tailCombos = combinations(set.slice(i + 1), k - 1);
+        for (const tail of tailCombos) {
+            result.push([...head, ...tail]);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=combination.js.map

package/dist/utils/combination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"combination.js","sourceRoot":"","sources":["../../src/utils/combination.ts"],"names":[],"mappings":";;AAAA,oCAcC;AAdD,SAAgB,YAAY,CAAI,GAAQ,EAAE,CAAS;IACjD,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,IAAI,CAAC,KAAK,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5C,MAAM,MAAM,GAAU,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@creatiosoft/poker-odds-calculator",
+  "version": "1.0.0",
+  "description": "Monte Carlo poker odds calculator for NLH, PLO4, PLO5, and PLO6",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "Creatiosoft",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "keywords": ["poker", "odds", "calculator", "nlh", "plo", "omaha", "monte-carlo"],
+  "license": "MIT",
+  "dependencies": {
+    "poker-evaluator": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/constants/deck.const.ts

@@ -0,0 +1,11 @@
+const RANKS = ['2', '3', '4', '5', '6', '7', '8', '9', 'T', 'J', 'Q', 'K', 'A'];
+const SUITS = ['c', 'd', 'h', 's'];
+
+export const FULL_DECK: string[] = RANKS.flatMap(r => SUITS.map(s => r + s));
+
+export const HOLE_CARD_COUNT: Record<string, number> = {
+  NLH: 2,
+  PLO4: 4,
+  PLO5: 5,
+  PLO6: 6,
+};

package/src/evaluator/nlh.evaluator.ts

@@ -0,0 +1,5 @@
+import { evalHand } from 'poker-evaluator';
+
+export function evalNLH(holeCards: string[], boardCards: string[]): number {
+  return evalHand([...holeCards, ...boardCards]).value;
+}

package/src/evaluator/omaha.evaluator.ts

@@ -0,0 +1,20 @@
+import { evalHand } from 'poker-evaluator';
+import { combinations } from '../utils/combination';
+
+/**
+ * Evaluates an Omaha hand (PLO4/5/6) using the mandatory 2-from-hole + 3-from-board rule.
+ * Returns the highest hand value (higher = stronger).
+ */
+export function evalOmaha(holeCards: string[], boardCards: string[]): number {
+  const holeCombos = combinations(holeCards, 2);
+  const boardCombos = combinations(boardCards, 3);
+
+  let bestValue = -1;
+  for (const hc of holeCombos) {
+    for (const bc of boardCombos) {
+      const value = evalHand([...hc, ...bc]).value;
+      if (value > bestValue) bestValue = value;
+    }
+  }
+  return bestValue;
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+import { runMonteCarlo } from './simulator/monteCarlo';
+import {
+  CalculateOddsInput,
+  CalculateTableOddsInput,
+  PlayerOdds,
+  TableOdds,
+} from './types/odds.interface';
+
+export type { Variant } from './types/variant.type';
+export type { Card } from './types/card.type';
+export type {
+  Split,
+  PlayerOdds,
+  TableOdds,
+  CalculateOddsInput,
+  CalculateTableOddsInput,
+} from './types/odds.interface';
+
+const DEFAULT_ITERATIONS: Record<string, number> = {
+  NLH:  1000,
+  PLO4:  500,
+  PLO5:  300,
+  PLO6:  200,
+};
+
+/**
+ * Calculates win odds for a single player against N-1 unknown opponents.
+ * The caller's hole cards are known; all other hands are randomly simulated.
+ */
+export function calculateOdds(input: CalculateOddsInput): PlayerOdds {
+  const iterations = input.iterations ?? DEFAULT_ITERATIONS[input.variant];
+
+  const knownHands = [
+    input.holeCards,
+    ...Array<string[]>(input.playerCount - 1).fill([]),
+  ];
+
+  const result = runMonteCarlo({
+    variant: input.variant,
+    knownHands,
+    community: input.communityCards,
+    playerCount: input.playerCount,
+    iterations,
+  });
+
+  return result.players[0];
+}
+
+/**
+ * Calculates win odds for all players when all hole cards are known (e.g. a run-it-out scenario).
+ */
+export function calculateTableOdds(input: CalculateTableOddsInput): TableOdds {
+  const iterations = input.iterations ?? DEFAULT_ITERATIONS[input.variant];
+
+  return runMonteCarlo({
+    variant: input.variant,
+    knownHands: input.hands,
+    community: input.communityCards,
+    playerCount: input.hands.length,
+    iterations,
+  });
+}

package/src/simulator/deck.ts

@@ -0,0 +1,13 @@
+import { FULL_DECK } from '../constants/deck.const';
+
+export function buildRemainingDeck(knownCards: string[]): string[] {
+  const known = new Set(knownCards.map(c => c.toLowerCase()));
+  return FULL_DECK.filter(card => !known.has(card.toLowerCase()));
+}
+
+export function shuffleDeck(deck: string[]): void {
+  for (let i = deck.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [deck[i], deck[j]] = [deck[j], deck[i]];
+  }
+}

package/src/simulator/monteCarlo.ts

@@ -0,0 +1,72 @@
+import { Variant } from '../types/variant.type';
+import { TableOdds } from '../types/odds.interface';
+import { HOLE_CARD_COUNT } from '../constants/deck.const';
+import { buildRemainingDeck, shuffleDeck } from './deck';
+import { evalNLH } from '../evaluator/nlh.evaluator';
+import { evalOmaha } from '../evaluator/omaha.evaluator';
+
+export interface SimulationConfig {
+  variant: Variant;
+  knownHands: string[][];
+  community: string[];
+  playerCount: number;
+  iterations: number;
+}
+
+export function runMonteCarlo(config: SimulationConfig): TableOdds {
+  const { variant, knownHands, community, playerCount, iterations } = config;
+  const holeCount = HOLE_CARD_COUNT[variant];
+  const t0 = performance.now();
+
+  const allKnown = [...community, ...knownHands.flat()];
+  const deck = buildRemainingDeck(allKnown);
+
+  const wins = new Array<number>(playerCount).fill(0);
+  const splits = Array.from({ length: playerCount }, () =>
+    new Array<number>(playerCount - 1).fill(0)
+  );
+
+  for (let i = 0; i < iterations; i++) {
+    shuffleDeck(deck);
+    let pos = 0;
+
+    const hands: string[][] = [];
+    for (let p = 0; p < playerCount; p++) {
+      const known = knownHands[p] ?? [];
+      const needed = holeCount - known.length;
+      hands.push([...known, ...deck.slice(pos, pos + needed)]);
+      pos += needed;
+    }
+
+    const board = [...community];
+    while (board.length < 5) board.push(deck[pos++]);
+
+    const values = hands.map(hand =>
+      variant === 'NLH' ? evalNLH(hand, board) : evalOmaha(hand, board)
+    );
+
+    const best = Math.max(...values);
+    const winners = values.reduce<number[]>((acc, v, idx) => {
+      if (v === best) acc.push(idx);
+      return acc;
+    }, []);
+
+    if (winners.length === 1) {
+      wins[winners[0]]++;
+    } else {
+      winners.forEach(idx => splits[idx][winners.length - 2]++);
+    }
+  }
+
+  const elapsed = (performance.now() - t0).toFixed(1);
+  console.log(`[${variant}] ${iterations} iterations, ${playerCount} players → ${elapsed}ms`);
+
+  return {
+    players: wins.map((w, p) => ({
+      winRate: w / iterations,
+      splitRates: splits[p]
+        .map((s, i) => ({ rate: s / iterations, ways: i + 2 }))
+        .filter(s => s.rate > 0),
+    })),
+  };
+}

package/src/types/card.type.ts

@@ -0,0 +1,7 @@
+/**
+ * Standard card notation: rank + suit
+ * Ranks: A K Q J T 9 8 7 6 5 4 3 2
+ * Suits: s (spades) h (hearts) d (diamonds) c (clubs)
+ * Example: "As", "Kh", "Td", "2c"
+ */
+export type Card = string;

package/src/types/odds.interface.ts

@@ -0,0 +1,28 @@
+export interface Split {
+  rate: number;
+  ways: number;
+}
+
+export interface PlayerOdds {
+  winRate: number;
+  splitRates: Split[];
+}
+
+export interface TableOdds {
+  players: PlayerOdds[];
+}
+
+export interface CalculateOddsInput {
+  variant: import('./variant.type').Variant;
+  holeCards: string[];
+  communityCards: string[];
+  playerCount: number;
+  iterations?: number;
+}
+
+export interface CalculateTableOddsInput {
+  variant: import('./variant.type').Variant;
+  hands: string[][];
+  communityCards: string[];
+  iterations?: number;
+}

package/src/types/variant.type.ts

@@ -0,0 +1 @@
+export type Variant = 'NLH' | 'PLO4' | 'PLO5' | 'PLO6';

package/src/utils/combination.ts

@@ -0,0 +1,15 @@
+export function combinations<T>(set: T[], k: number): T[][] {
+  if (k > set.length || k <= 0) return [];
+  if (k === set.length) return [set];
+  if (k === 1) return set.map(item => [item]);
+
+  const result: T[][] = [];
+  for (let i = 0; i <= set.length - k; i++) {
+    const head = set.slice(i, i + 1);
+    const tailCombos = combinations(set.slice(i + 1), k - 1);
+    for (const tail of tailCombos) {
+      result.push([...head, ...tail]);
+    }
+  }
+  return result;
+}