CombinationValue

牌点数解析器接口及其内置实现。

概述

CombinationValue 模块位于 src/combination/CombinationValue.ts，负责将 Card 的多种形态（数字 rank / 字符串 rank / 数字 value）统一映射为可比较的数值，供 CombinationDetector 与 CardQuery 等模块使用。

自定义游戏可注入自定义 RankResolver 以改变牌大小语义（如让 A 视为最低牌）。

RankResolver 接口

牌点数解析器接口。将 Card 的 rank/value 等多种形态统一映射为可比较的数值，供 CombinationDetector、CardQuery 等模块使用。

interface RankResolver {
  resolveRank(card: Card): number
}

resolveRank()

解析给定卡牌的可比较点数值。

resolveRank(card: Card): number

参数

参数	类型	必填	默认值	说明
card	Card	是	—	待解析的卡牌

返回值

number：该牌的点数数值。

抛错

当卡牌没有任何可识别的点数信息时抛出 Error。

StandardPokerRankResolver

标准扑克点数解析器：A 视为最高牌（14）。

class StandardPokerRankResolver implements RankResolver {
  resolveRank(card: Card): number
}

解析优先级

1. 若 card.rank 为 number，直接返回该数值。
2. 若 card.rank 为 string：
   • 先查 POKER_HIGH 映射表（如 'A' → 14，'J' → 11，'10' → 10 等）；
   • 命中则返回表中值；
   • 否则尝试 Number(card.rank)，若为有限数值则返回之。
3. 若 card.value 为 number，返回该值。
4. 否则抛出 Error，消息形如 Cannot resolve rank for card ${id} (rank=..., value=...)。

POKER_HIGH 映射表

模块内部私有常量，不可外部访问，但解析器内部按以下映射工作：

字符串 rank	数值
'A'	14
'2' ~ '10'	2 ~ 10
'J'	11
'Q'	12
'K'	13

示例

import { StandardPokerRankResolver } from '../combination/CombinationValue.js'
import type { Card } from '../card/Card.js'

const resolver = new StandardPokerRankResolver()

const ace: Card = { id: 'c1', type: 'standard', rank: 'A', data: {} }
resolver.resolveRank(ace) // -> 14

const ten: Card = { id: 'c2', type: 'standard', rank: '10', data: {} }
resolver.resolveRank(ten) // -> 10

const numFive: Card = { id: 'c3', type: 'standard', rank: 5, data: {} }
resolver.resolveRank(numFive) // -> 5

const byValue: Card = { id: 'c4', type: 'standard', value: 7, data: {} }
resolver.resolveRank(byValue) // -> 7

LowAceRankResolver

将 A 视为最低牌（1）的点数解析器。常用于「低 A 顺子」（如 A-2-3-4-5）场景；其余牌委托给 fallback Resolver 处理，默认 fallback 为 StandardPokerRankResolver。

class LowAceRankResolver implements RankResolver {
  constructor(fallback: RankResolver = new StandardPokerRankResolver())
  resolveRank(card: Card): number
}

构造函数

new LowAceRankResolver(fallback?: RankResolver)

参数

参数	类型	必填	默认值	说明
fallback	RankResolver	否	new StandardPokerRankResolver()	处理非 A 牌的回退解析器

resolveRank()

resolveRank(card: Card): number

行为

• 若 card.rank 为字符串 'A'，返回 1。
• 否则委托给 fallback.resolveRank(card)。

示例

import { LowAceRankResolver } from '../combination/CombinationValue.js'
import type { Card } from '../card/Card.js'

const resolver = new LowAceRankResolver()

const ace: Card = { id: 'c1', type: 'standard', rank: 'A', data: {} }
resolver.resolveRank(ace) // -> 1

const king: Card = { id: 'c2', type: 'standard', rank: 'K', data: {} }
resolver.resolveRank(king) // -> 13（回退到 StandardPokerRankResolver）

注意事项

• StandardPokerRankResolver 与 LowAceRankResolver 都不持有可变状态，可全局共享实例。
• 这两个解析器不感知任何游戏专属牌型规则；如需自定义大小语义（如让 2 大于 A，或将鬼牌视为最大），请实现自定义 RankResolver。
• 当卡牌既无 rank 又无 value，或 rank 字符串既不在映射表中又无法 Number(...) 解析时，StandardPokerRankResolver.resolveRank() 会抛错。调用方需保证卡牌已具备可识别的点数信息。