@pai-forge/riichi-mahjong 0.3.3 → 0.3.5

package/dist/index.d.ts

@@ -1,3 +1,25 @@
+declare const __tehai13Brand: unique symbol;
+
+declare const __tehai14Brand: unique symbol;
+
+/**
+ * 手牌がTehai13（有効枚数13枚）であることを表明します。
+ * バリデーション成功後、引数を Tehai13 型にナローイングします。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ */
+export declare function assertTehai13<T extends HaiKindId | HaiId>(tehai: Tehai<T>): asserts tehai is Tehai13<T>;
+
+/**
+ * 手牌がTehai14（有効枚数14枚）であることを表明します。
+ * バリデーション成功後、引数を Tehai14 型にナローイングします。
+ * @throws {ShoushaiError} 枚数が不足している場合
+ * @throws {TahaiError} 枚数が超過している場合
+ * @throws {InvalidHaiQuantityError} 同一種の牌が5枚以上ある場合
+ * @throws {DuplicatedHaiIdError} 物理牌モードでIDが重複している場合
+ */
+export declare function assertTehai14<T extends HaiKindId | HaiId>(tehai: Tehai<T>): asserts tehai is Tehai14<T>;
+
 /**
  * 基本的な面子構造 (ジェネリック)
  *
@@ -42,7 +64,12 @@ export declare function calculateScoreForTehai(tehai: Tehai14, config: Readonly<
  */
 export declare function calculateShanten(tehai: Tehai13, useChiitoitsu?: boolean, useKokushi?: boolean): number;
 
-declare interface ChiitoitsuHouraStructure {
+/**
+ * 七対子の和了構造 (ChiitoitsuHouraStructure)
+ *
+ * 7つの対子で和了した場合の構造。
+ */
+export declare interface ChiitoitsuHouraStructure {
     readonly type: "Chiitoitsu";
     readonly pairs: readonly [
     Toitsu,
@@ -96,10 +123,31 @@ export declare function countDora(tehai: Tehai, indicators: readonly HaiKindId[]
  * 手牌の構造役を検出する
  *
  * @param tehai 判定対象の手牌
- * @param agariHai 和了牌
+ * @param config 役判定コンフィグ（和了牌、場風、自風、ドラ表示牌など）
  * @returns 成立した役と翻数のリスト（最も高得点となる解釈の結果）
  */
-export declare function detectYaku(tehai: Tehai14, agariHai: HaiKindId, bakaze?: HaiKindId, jikaze?: HaiKindId, doraMarkers?: readonly HaiKindId[], uraDoraMarkers?: readonly HaiKindId[], isTsumo?: boolean): YakuResult;
+export declare function detectYaku(tehai: Tehai14, config: DetectYakuConfig): YakuResult;
+
+/**
+ * 役判定コンフィグ (DetectYakuConfig)
+ *
+ * detectYaku に渡す設定オブジェクト。
+ * 和了牌、場風、自風、ドラ表示牌などをまとめて指定する。
+ */
+export declare interface DetectYakuConfig {
+    /** 和了牌 */
+    readonly agariHai: HaiKindId;
+    /** 場風牌 */
+    readonly bakaze?: Kazehai;
+    /** 自風牌 */
+    readonly jikaze?: Kazehai;
+    /** ドラ表示牌のリスト */
+    readonly doraMarkers?: readonly HaiKindId[];
+    /** 裏ドラ表示牌のリスト */
+    readonly uraDoraMarkers?: readonly HaiKindId[];
+    /** ツモ和了かどうか */
+    readonly isTsumo?: boolean;
+}
 
 /**
  * 牌IDが重複している場合のエラー
@@ -131,6 +179,63 @@ declare type ExtendedMspzString = string & {
  */
 export declare type Fu = 20 | 25 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 | 110;
 
+/**
+ * 符の構成要素 (FuDetails)
+ *
+ * 符計算の内訳を保持するインターフェース。
+ */
+export declare interface FuDetails {
+    /**
+     * 符底 (FuTei)
+     *
+     * 一般的な和了形: 20符
+     * 七対子: 25符
+     */
+    readonly base: 20 | 25;
+    /**
+     * 面子符の合計 (MentsuFu)
+     *
+     * 刻子・槓子による加算符。順子は0符。
+     */
+    readonly mentsu: number;
+    /**
+     * 雀頭符 (JantouFu)
+     *
+     * 役牌の対子による加算符。
+     */
+    readonly jantou: number;
+    /**
+     * 待ち符 (MachiFu)
+     *
+     * 単騎・嵌張・辺張待ちによる加算符（2符）。
+     */
+    readonly machi: number;
+    /**
+     * 和了符 (AgariFu)
+     *
+     * ツモ和了: 2符
+     * 門前ロン: 10符
+     */
+    readonly agari: number;
+}
+
+/**
+ * 符計算結果 (FuResult)
+ */
+export declare interface FuResult {
+    /**
+     * 最終的な符数 (Total)
+     *
+     * 内訳の合計を10符単位で切り上げたもの。
+     * (例: 22符 -> 30符)
+     */
+    readonly total: Fu;
+    /**
+     * 計算の内訳
+     */
+    readonly details: FuDetails;
+}
+
 /**
  * 副露 (Furo)
  *
@@ -298,7 +403,12 @@ export declare type HaiType = (typeof HaiType)[keyof typeof HaiType];
  */
 export declare type Hansu = 1 | 2 | 3 | 5 | 6 | 13 | 26;
 
-declare type HouraStructure = MentsuHouraStructure | ChiitoitsuHouraStructure | KokushiHouraStructure;
+/**
+ * 和了構造 (HouraStructure)
+ *
+ * 面子手、七対子、国士無双のいずれかの和了構造。
+ */
+export declare type HouraStructure = MentsuHouraStructure | ChiitoitsuHouraStructure | KokushiHouraStructure;
 
 /**
  * 未完成面子 (IncompletedMentsu)
@@ -419,7 +529,12 @@ export declare type Kazehai = typeof HaiKind.Ton | typeof HaiKind.Nan | typeof H
  */
 export declare function kindIdToHaiType(kind: HaiKindId): HaiType;
 
-declare interface KokushiHouraStructure {
+/**
+ * 国士無双の和了構造 (KokushiHouraStructure)
+ *
+ * 13種の么九牌で和了した場合の構造。
+ */
+export declare interface KokushiHouraStructure {
     readonly type: "Kokushi";
     /** 13種類の么九牌（重複なし） */
     readonly yaochu: readonly HaiKindId[];
@@ -429,7 +544,7 @@ declare interface KokushiHouraStructure {
 
 /** 子のツモ和了時の支払い */
 export declare interface KoTsumo {
-    type: "koTsumo";
+    readonly type: "koTsumo";
     /** [子の支払い, 親の支払い] */
     readonly amount: readonly [number, number];
 }
@@ -475,7 +590,12 @@ export declare class MahjongError extends Error {
  */
 export declare type Mentsu<T extends HaiKindId | HaiId = HaiKindId> = CompletedMentsu<T> | IncompletedMentsu<T>;
 
-declare interface MentsuHouraStructure {
+/**
+ * 面子手の和了構造 (MentsuHouraStructure)
+ *
+ * 4面子1雀頭の形で和了した場合の構造。
+ */
+export declare interface MentsuHouraStructure {
     readonly type: "Mentsu";
     readonly fourMentsu: readonly [
     CompletedMentsu,
@@ -499,6 +619,18 @@ export declare const MentsuType: {
 
 export declare type MentsuType = (typeof MentsuType)[keyof typeof MentsuType];
 
+/**
+ * MSPZ文字列の解析エラー
+ *
+ * MSPZ形式の文字列が不正な場合にスローされます。
+ */
+export declare class MspzParseError extends MahjongError {
+    /**
+     *
+     */
+    constructor(message?: string);
+}
+
 /**
  * 標準的なMSPZ形式の文字列（拡張記法を含まない）
  */
@@ -520,9 +652,9 @@ export declare class NoYakuError extends ChomboError {
 
 /** 親のツモ和了時の支払い */
 export declare interface OyaTsumo {
-    type: "oyaTsumo";
+    readonly type: "oyaTsumo";
     /** 子全員が支払う点数（オール） */
-    amount: number;
+    readonly amount: number;
 }
 
 /**
@@ -548,24 +680,60 @@ export declare type Payment = Ron | KoTsumo | OyaTsumo;
 
 /** ロン和了時の支払い */
 export declare interface Ron {
-    type: "ron";
+    readonly type: "ron";
     /** 振り込んだプレイヤーが支払う点数 */
-    amount: number;
+    readonly amount: number;
 }
 
 export declare interface ScoreCalculationConfig {
     /** 和了牌 */
-    agariHai: HaiKindId;
+    readonly agariHai: HaiKindId;
     /** ツモ和了かどうか (必須) */
-    isTsumo: boolean;
+    readonly isTsumo: boolean;
     /** 自風 (必須) */
-    jikaze: Kazehai;
+    readonly jikaze: Kazehai;
     /** 場風 (必須) */
-    bakaze: Kazehai;
+    readonly bakaze: Kazehai;
     /** ドラ表示牌 (必須、なければ空配列) */
-    doraMarkers: readonly HaiKindId[];
+    readonly doraMarkers: readonly HaiKindId[];
     /** 裏ドラ表示牌 (任意) */
-    uraDoraMarkers?: readonly HaiKindId[];
+    readonly uraDoraMarkers?: readonly HaiKindId[];
+}
+
+/**
+ * 点数計算で選択された構造解釈の詳細情報 (ScoreDetail)
+ *
+ * calculateScoreForTehai が最高得点として選択した構造解釈に紐づく情報。
+ *
+ * 同一手牌でも面子分解（構造解釈）によって待ちの形が変わり、
+ * 結果として符・得点が異なる場合がある。
+ * ライブラリは内部で最高得点の構造を選択するが、その選択結果を
+ * 利用側に公開しないと、利用側が独自に構造を解釈した際にライブラリと
+ * 異なる符の内訳を表示してしまうバグが発生する。
+ *
+ * このインターフェースにより、利用側はライブラリが採用した構造解釈と
+ * 完全に一致する符の内訳を表示できる。
+ */
+export declare interface ScoreDetail {
+    /** ライブラリが最高得点として選択した和了構造（面子分解） */
+    readonly structure: HouraStructure;
+    /**
+     * 選択された構造における待ちの形
+     *
+     * 面子手の場合のみ判定される。七対子・国士無双の場合は undefined。
+     * 同じアガリ牌が順子と雀頭の両方に含まれる場合、符が高くなる
+     * 待ち形（例: 両面より単騎）が採用される。
+     */
+    readonly machiType: MachiType | undefined;
+    /**
+     * 選択された構造に基づく符計算の内訳
+     *
+     * total は最終的な符数（10符単位切り上げ）、details は各構成要素の符。
+     * 利用側で符の内訳を表示する際は、この値をそのまま使用すること。
+     */
+    readonly fuResult: FuResult;
+    /** 成立した役と翻数のリスト（ドラを含まない） */
+    readonly yakuResult: YakuResult;
 }
 
 /**
@@ -594,10 +762,21 @@ declare const ScoreLevel: {
 declare type ScoreLevel = (typeof ScoreLevel)[keyof typeof ScoreLevel];
 
 export declare interface ScoreResult {
-    han: number;
-    fu: Fu;
-    scoreLevel: ScoreLevel;
-    payment: Payment;
+    readonly han: number;
+    readonly fu: Fu;
+    readonly scoreLevel: ScoreLevel;
+    readonly payment: Payment;
+    /**
+     * ライブラリが最高得点として選択した構造解釈の詳細情報
+     *
+     * 手牌には複数の面子分解が存在しうるが、ライブラリ内部で最高得点の
+     * 構造が選択される。この選択結果を外部に公開しないと、利用側で
+     * 符の内訳を正確に表示できないため追加された。
+     *
+     * 利用側で符の内訳や待ちの形を表示する際は、独自に構造解釈を行わず、
+     * このフィールドの値をそのまま使用すること。
+     */
+    readonly detail?: ScoreDetail;
 }
 
 /**
@@ -671,13 +850,23 @@ export declare interface Tehai<T extends HaiKindId | HaiId = HaiKindId> {
 
 /**
  * ツモる前の手牌 (13枚)
+ *
+ * Branded Type により Tehai14 と型レベルで区別される。
+ * 生成には createTehai13（テスト用）や assertTehai13 を使用する。
  */
-export declare type Tehai13<T extends HaiKindId | HaiId = HaiKindId> = Tehai<T>;
+export declare interface Tehai13<T extends HaiKindId | HaiId = HaiKindId> extends Tehai<T> {
+    readonly [__tehai13Brand]: never;
+}
 
 /**
  * ツモった後の手牌 (14枚)
+ *
+ * Branded Type により Tehai13 と型レベルで区別される。
+ * 生成には createTehai（テスト用）や assertTehai14 を使用する。
  */
-export declare type Tehai14<T extends HaiKindId | HaiId = HaiKindId> = Tehai<T>;
+export declare interface Tehai14<T extends HaiKindId | HaiId = HaiKindId> extends Tehai<T> {
+    readonly [__tehai14Brand]: never;
+}
 
 /**
  * 手牌役 (TehaiYaku)