@pai-forge/riichi-mahjong 0.3.4 → 0.3.6

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+import { Result } from 'neverthrow';
+
+declare const __tehai13Brand: unique symbol;
+
+declare const __tehai14Brand: unique symbol;
+
 /**
  * 基本的な面子構造 (ジェネリック)
  *
@@ -40,8 +46,13 @@ export declare function calculateScoreForTehai(tehai: Tehai14, config: Readonly<
  * @param tehai 手牌
  * @returns シャンテン数
  */
-export declare function calculateShanten(tehai: Tehai13, useChiitoitsu?: boolean, useKokushi?: boolean): number;
+export declare function calculateShanten(tehai: Tehai13, useChiitoitsu?: boolean, useKokushi?: boolean): Result<number, TehaiError>;
 
+/**
+ * 七対子の和了構造 (ChiitoitsuHouraStructure)
+ *
+ * 7つの対子で和了した場合の構造。
+ */
 export declare interface ChiitoitsuHouraStructure {
     readonly type: "Chiitoitsu";
     readonly pairs: readonly [
@@ -96,10 +107,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が重複している場合のエラー
@@ -355,6 +387,11 @@ export declare type HaiType = (typeof HaiType)[keyof typeof HaiType];
  */
 export declare type Hansu = 1 | 2 | 3 | 5 | 6 | 13 | 26;
 
+/**
+ * 和了構造 (HouraStructure)
+ *
+ * 面子手、七対子、国士無双のいずれかの和了構造。
+ */
 export declare type HouraStructure = MentsuHouraStructure | ChiitoitsuHouraStructure | KokushiHouraStructure;
 
 /**
@@ -476,6 +513,11 @@ export declare type Kazehai = typeof HaiKind.Ton | typeof HaiKind.Nan | typeof H
  */
 export declare function kindIdToHaiType(kind: HaiKindId): HaiType;
 
+/**
+ * 国士無双の和了構造 (KokushiHouraStructure)
+ *
+ * 13種の么九牌で和了した場合の構造。
+ */
 export declare interface KokushiHouraStructure {
     readonly type: "Kokushi";
     /** 13種類の么九牌（重複なし） */
@@ -486,7 +528,7 @@ export declare interface KokushiHouraStructure {
 
 /** 子のツモ和了時の支払い */
 export declare interface KoTsumo {
-    type: "koTsumo";
+    readonly type: "koTsumo";
     /** [子の支払い, 親の支払い] */
     readonly amount: readonly [number, number];
 }
@@ -532,6 +574,11 @@ export declare class MahjongError extends Error {
  */
 export declare type Mentsu<T extends HaiKindId | HaiId = HaiKindId> = CompletedMentsu<T> | IncompletedMentsu<T>;
 
+/**
+ * 面子手の和了構造 (MentsuHouraStructure)
+ *
+ * 4面子1雀頭の形で和了した場合の構造。
+ */
 export declare interface MentsuHouraStructure {
     readonly type: "Mentsu";
     readonly fourMentsu: readonly [
@@ -556,6 +603,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形式の文字列（拡張記法を含まない）
  */
@@ -577,9 +636,9 @@ export declare class NoYakuError extends ChomboError {
 
 /** 親のツモ和了時の支払い */
 export declare interface OyaTsumo {
-    type: "oyaTsumo";
+    readonly type: "oyaTsumo";
     /** 子全員が支払う点数（オール） */
-    amount: number;
+    readonly amount: number;
 }
 
 /**
@@ -589,7 +648,7 @@ export declare interface OyaTsumo {
  * @param input 拡張MSPZ形式の文字列
  * @returns 手牌オブジェクト
  */
-export declare function parseExtendedMspz(input: string): Tehai;
+export declare function parseExtendedMspz(input: string): Result<Tehai, MspzParseError>;
 
 /**
  * 標準的なMSPZ文字列（例: "123m456p..."）を解析して手牌オブジェクトを生成します。
@@ -598,31 +657,31 @@ export declare function parseExtendedMspz(input: string): Tehai;
  * @param input MSPZ形式の文字列
  * @returns 手牌オブジェクト
  */
-export declare function parseMspz(input: string): Tehai;
+export declare function parseMspz(input: string): Result<Tehai, MspzParseError>;
 
 /** 支払い情報 */
 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[];
 }
 
 /**
@@ -687,10 +746,10 @@ 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;
     /**
      * ライブラリが最高得点として選択した構造解釈の詳細情報
      *
@@ -701,7 +760,7 @@ export declare interface ScoreResult {
      * 利用側で符の内訳や待ちの形を表示する際は、独自に構造解釈を行わず、
      * このフィールドの値をそのまま使用すること。
      */
-    detail?: ScoreDetail;
+    readonly detail?: ScoreDetail;
 }
 
 /**
@@ -775,13 +834,25 @@ 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;
+}
+
+declare type TehaiError = ShoushaiError | TahaiError | InvalidHaiQuantityError | DuplicatedHaiIdError;
 
 /**
  * 手牌役 (TehaiYaku)
@@ -801,15 +872,21 @@ declare type Toitsu<T extends HaiKindId | HaiId = HaiKindId> = BaseMentsu<T> & {
 };
 
 /**
- * 手牌がTehai13またはTehai14（有効枚数が13または14枚）であるか検証します。
- * シャンテン計算や待ち判定など、13枚/14枚の区別なく手牌として扱いたい場合に使用します。
  *
- * @throws {ShoushaiError} 枚数が不足している場合 (< 13)
- * @throws {TahaiError} 枚数が超過している場合 (> 14)
- * @throws {InvalidHaiQuantityError} 同一種の牌が5枚以上ある場合
- * @throws {DuplicatedHaiIdError} 物理牌モードでIDが重複している場合
  */
-export declare function validateTehai<T extends HaiKindId | HaiId>(tehai: Tehai<T>): void;
+export declare function validateTehai<T extends HaiKindId | HaiId>(tehai: Tehai<T>): Result<Tehai<T>, TehaiError>;
+
+/**
+ * 手牌がTehai13（有効枚数13枚）であるか検証し、スマートコンストラクタとして機能します。
+ * バリデーション成功後、Tehai13 型にナローイングされたオブジェクトをResultで返します。
+ */
+export declare function validateTehai13<T extends HaiKindId | HaiId>(tehai: Tehai<T>): Result<Tehai13<T>, TehaiError>;
+
+/**
+ * 手牌がTehai14（有効枚数14枚）であるか検証し、スマートコンストラクタとして機能します。
+ * バリデーション成功後、Tehai14 型にナローイングされたオブジェクトをResultで返します。
+ */
+export declare function validateTehai14<T extends HaiKindId | HaiId>(tehai: Tehai<T>): Result<Tehai14<T>, TehaiError>;
 
 /**
  * 役牌 (Yakuhai)