JoshHeaps.Net/JoshHeaps.Net/wwwroot/js/casino/holdem/handRank.js

// What beats what.
//
// The dealer has always been the one who decides who won: the pot wizard asks "who won
// the hand?" and pays whoever gets ticked. That is the right default — most hands are
// won without a showdown, and at a home game the table reads the cards out loud between
// them. But when the board is on the felt and the hands are on their backs, the tool
// knows the answer, and reading it off a screen beats three people counting kickers.
//
// Cards are the same two-character strings the rest of the tool has always stored:
// a rank from `RANKS` and a suit from S, H, D, C. Case is not significant.
//
// Nothing in here touches the DOM, the table, or money. It compares cards, and the pot
// wizard decides what to do about it.
const HandRank = {
    RANKS: "23456789TJQKA",

    // High to low. The number is the hand's category and nothing else — kickers and
    // the rest of the tie-breaking live in the `tiebreak` array beside it.
    STRAIGHT_FLUSH: 8,
    FOUR_OF_A_KIND: 7,
    FULL_HOUSE: 6,
    FLUSH: 5,
    STRAIGHT: 4,
    THREE_OF_A_KIND: 3,
    TWO_PAIR: 2,
    ONE_PAIR: 1,
    HIGH_CARD: 0,

    // 2 through 14. Null for anything that isn't a card, which is how a half-filled
    // slot gets told apart from a bad one.
    rankValue(card) {
        if (typeof card !== "string" || card.length < 2) return null;
        const index = this.RANKS.indexOf(card[0].toUpperCase());
        return index < 0 ? null : index + 2;
    },

    suitOf(card) {
        if (typeof card !== "string" || card.length < 2) return null;
        const suit = card[card.length - 1].toUpperCase();
        return "SHDC".includes(suit) ? suit : null;
    },

    isCard(card) {
        return this.rankValue(card) !== null && this.suitOf(card) !== null;
    },

    // Singular and plural, for reading a hand out loud.
    NAMES: {
        14: ["ace", "aces"], 13: ["king", "kings"], 12: ["queen", "queens"],
        11: ["jack", "jacks"], 10: ["ten", "tens"], 9: ["nine", "nines"],
        8: ["eight", "eights"], 7: ["seven", "sevens"], 6: ["six", "sixes"],
        5: ["five", "fives"], 4: ["four", "fours"], 3: ["three", "threes"],
        2: ["two", "twos"],
    },

    name(rank, plural = false) {
        const pair = this.NAMES[rank];
        return pair ? pair[plural ? 1 : 0] : "?";
    },

    // ---- The five-card hand -------------------------------------------------------

    // Exactly five cards, ranked. Everything else is built on this.
    //
    // Five rather than seven because five is the hand a player actually holds, and it
    // is small enough to check by hand — which is the whole argument for doing it this
    // way. The seven-card version below tries all twenty-one five-card hands and keeps
    // the best, which is a hand of poker's own definition of "your best five" written
    // out literally. A dealer resolves one pot a hand with at most a dozen players in
    // it; two hundred and fifty comparisons of five cards is not a cost worth trading
    // a subtler algorithm's correctness for.
    evaluate5(cards) {
        if (!Array.isArray(cards) || cards.length !== 5) return null;
        if (!cards.every(card => this.isCard(card))) return null;

        const ranks = cards.map(card => this.rankValue(card)).sort((a, b) => b - a);
        const suits = cards.map(card => this.suitOf(card));
        const flush = suits.every(suit => suit === suits[0]);

        // How many of each rank, ordered by how many first and by rank second — so
        // the front of this list is always the rank that decides the hand.
        const counts = new Map();
        ranks.forEach(rank => counts.set(rank, (counts.get(rank) || 0) + 1));
        const groups = [...counts.entries()]
            .sort((a, b) => (b[1] - a[1]) || (b[0] - a[0]));
        const shape = groups.map(([, count]) => count);
        const byGroup = groups.map(([rank]) => rank);

        const straightHigh = this.straightHigh(ranks);

        const made = (category, tiebreak) => ({ category, tiebreak, cards: [...cards] });

        if (flush && straightHigh) return made(this.STRAIGHT_FLUSH, [straightHigh]);
        if (shape[0] === 4) return made(this.FOUR_OF_A_KIND, byGroup);
        if (shape[0] === 3 && shape[1] === 2) return made(this.FULL_HOUSE, byGroup);
        if (flush) return made(this.FLUSH, ranks);
        if (straightHigh) return made(this.STRAIGHT, [straightHigh]);
        if (shape[0] === 3) return made(this.THREE_OF_A_KIND, byGroup);
        if (shape[0] === 2 && shape[1] === 2) return made(this.TWO_PAIR, byGroup);
        if (shape[0] === 2) return made(this.ONE_PAIR, byGroup);
        return made(this.HIGH_CARD, ranks);
    },

    // The top card of the straight these five ranks make, or null.
    //
    // The wheel is the exception the rest of the ordering has to be told about: A-2-3-4-5
    // is a straight, and it is the *lowest* one, so its ace counts as five rather than
    // as fourteen. Getting that wrong is how A-2-3-4-5 comes to beat 10-J-Q-K-A.
    straightHigh(sortedDesc) {
        const distinct = [...new Set(sortedDesc)];
        if (distinct.length !== 5) return null;
        if (distinct[0] - distinct[4] === 4) return distinct[0];
        // Ace, five, four, three, two.
        if (distinct[0] === 14 && distinct[1] === 5 && distinct[4] === 2) return 5;
        return null;
    },

    // ---- The best five out of however many ----------------------------------------

    // The best five-card hand available from five, six or seven cards — hole cards and
    // board together, which is what Hold'em asks for. Returns null if there aren't five
    // real cards, which is the ordinary state of a hand still being dealt.
    best(cards) {
        const real = (cards || []).filter(card => this.isCard(card));
        if (real.length < 5) return null;
        // A card in two places at once is a mis-entry, not a hand — say so rather than
        // ranking a board that has the same king on it twice.
        if (new Set(real.map(card => card.toUpperCase())).size !== real.length) return null;

        let best = null;
        this.eachFive(real, five => {
            const hand = this.evaluate5(five);
            if (!best || this.compare(hand, best) > 0) best = hand;
        });
        return best;
    },

    // Every five-card subset, without building an array of them.
    eachFive(cards, visit) {
        const n = cards.length;
        for (let a = 0; a < n - 4; a++) {
            for (let b = a + 1; b < n - 3; b++) {
                for (let c = b + 1; c < n - 2; c++) {
                    for (let d = c + 1; d < n - 1; d++) {
                        for (let e = d + 1; e < n; e++) {
                            visit([cards[a], cards[b], cards[c], cards[d], cards[e]]);
                        }
                    }
                }
            }
        }
    },

    // Positive if `a` wins, negative if `b` does, zero for a chop. A chop is a real
    // answer here rather than a rounding of one: two players playing the same board
    // split the pot, and the fifth card decides it far more often than a table expects.
    compare(a, b) {
        if (!a && !b) return 0;
        if (!a) return -1;
        if (!b) return 1;
        if (a.category !== b.category) return a.category - b.category;
        const length = Math.max(a.tiebreak.length, b.tiebreak.length);
        for (let i = 0; i < length; i++) {
            const diff = (a.tiebreak[i] || 0) - (b.tiebreak[i] || 0);
            if (diff !== 0) return diff;
        }
        return 0;
    },

    // ---- Saying it out loud -------------------------------------------------------

    // What a dealer says when they turn the hand over. Named to the level that settles
    // it and no further: "two pair, aces and eights" is the call, and the kicker only
    // gets a mention where the tool has had to use one to break a tie.
    describe(hand) {
        if (!hand) return "";
        const [first, second] = hand.tiebreak;
        switch (hand.category) {
            case this.STRAIGHT_FLUSH:
                return first === 14 ? "Royal flush" : `Straight flush, ${this.name(first)} high`;
            case this.FOUR_OF_A_KIND:
                return `Four of a kind, ${this.name(first, true)}`;
            case this.FULL_HOUSE:
                return `Full house, ${this.name(first, true)} full of ${this.name(second, true)}`;
            case this.FLUSH:
                return `Flush, ${this.name(first)} high`;
            case this.STRAIGHT:
                return `Straight, ${this.name(first)} high`;
            case this.THREE_OF_A_KIND:
                return `Three of a kind, ${this.name(first, true)}`;
            case this.TWO_PAIR:
                return `Two pair, ${this.name(first, true)} and ${this.name(second, true)}`;
            case this.ONE_PAIR:
                return `Pair of ${this.name(first, true)}`;
            default:
                return `${this.name(first).charAt(0).toUpperCase()}${this.name(first).slice(1)} high`;
        }
    },

    // The same call with the article a table would put in front of it. Not derivable
    // from the first letter: it is "a full house" and "a flush", but "four of a kind"
    // and "two pair" take none at all, and "an ace high" is not something anybody says.
    // So it belongs to the category, like the name does.
    ARTICLED: {
        8: hand => (hand.tiebreak[0] === 14 ? "a royal flush" : "a"),
        7: () => null,
        6: () => "a",
        5: () => "a",
        4: () => "a",
        3: () => null,
        2: () => null,
        1: () => "a",
        0: () => null,
    },

    // "wins with X" — the phrase, ready to drop into a sentence.
    phrase(hand) {
        if (!hand) return "the best hand";
        const described = this.describe(hand);
        const article = (this.ARTICLED[hand.category] || (() => null))(hand);
        if (article === null) return described.toLowerCase();
        if (article !== "a") return article;
        return `a ${described.toLowerCase()}`;
    },

    // ---- The showdown -------------------------------------------------------------

    // Rank a set of players against a board.
    //
    // `players` is [{ id, cards }, ...] — the two in front of each of them. Every player
    // is returned whether or not they could be ranked, in the order they were given, so
    // the caller can show a row for each and say which ones it could not read. `place`
    // is 1 for the winner and shared by a chop; a player whose cards aren't known has a
    // null hand and no place.
    //
    // `complete` is the question the pot wizard actually asks: can this be trusted to
    // pay the table. It is only true when the board is all five cards and every single
    // player handed in has two of their own — one unknown hand and the tool cannot say
    // who won, only who is winning so far, which is not the same thing and must not be
    // dressed up as it.
    showdown(board, players) {
        const boardCards = (board || []).filter(card => this.isCard(card));
        const boardComplete = boardCards.length === 5;

        const ranked = (players || []).map(player => {
            const hole = (player.cards || []).filter(card => this.isCard(card));
            const hand = hole.length === 2 && boardComplete
                ? this.best([...hole, ...boardCards])
                : null;
            return { id: player.id, cards: hole, hand, place: null };
        });

        const readable = ranked.filter(row => row.hand);
        // A duplicated card anywhere means somebody has been mis-entered, and the
        // ranking would be of a deck that doesn't exist.
        const all = [...boardCards, ...ranked.flatMap(row => row.cards)].map(c => c.toUpperCase());
        const duplicated = new Set(all).size !== all.length;

        const sorted = [...readable].sort((a, b) => this.compare(b.hand, a.hand));
        let place = 0;
        sorted.forEach((row, i) => {
            if (i === 0 || this.compare(row.hand, sorted[i - 1].hand) !== 0) place = i + 1;
            row.place = place;
        });

        const winners = sorted.filter(row => row.place === 1);
        const complete = boardComplete && !duplicated &&
            ranked.length > 0 && readable.length === ranked.length;

        return {
            players: ranked,
            winners: complete ? winners.map(row => row.id) : [],
            boardComplete,
            duplicated,
            complete,
            // Who the tool could not read, so the dialog can name them rather than
            // just declining to help.
            unknown: ranked.filter(row => !row.hand).map(row => row.id),
        };
    },
};

if (typeof module !== "undefined" && module.exports) {
    module.exports = HandRank;
}