dinero-best-practices

Dinero.js のベストプラクティス

お金を安全に作成、計算、フォーマットするための JavaScript／TypeScript ライブラリである Dinero.js を扱う際の基本ルールです。影響度に基づいて優先順位を付けた 4 つのカテゴリのルールが含まれています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• ユーザー入力、API レスポンス、またはデータベースの値から Dinero オブジェクトを作成する場合
• 金額の算術演算（加算、分割、乗算）を行う場合
• number と bigint のどちらの計算機を使用するか選ぶ場合
• dinero.js、dinero.js/currencies、または dinero.js/bigint からインポートする場合
• 価格、費用、税金、またはあらゆる金銭計算を扱う場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	オブジェクトの作成	CRITICAL	creation-
2	算術演算	CRITICAL	arithmetic-
3	精度	HIGH	precision-
4	インポート	MEDIUM	imports-

クイックリファレンス

1. オブジェクトの作成（CRITICAL）

• creation-minor-units - 金額は常に最小通貨単位の整数で渡します
• creation-from-floats - ヘルパーを使って浮動小数点数の入力を最小通貨単位に変換します
• creation-zero-exponent - 指数が 0 の通貨（例：JPY）には、主要通貨単位を直接渡します

2. 算術演算（CRITICAL）

• arithmetic-immutability - すべての演算は新しいオブジェクトを返すため、戻り値を保持します
• arithmetic-allocate-not-divide - 金額の分割には手動での除算ではなく、allocate を使用します
• arithmetic-scaled-amounts - 生の小数を乗算してはいけません。スケーリングした金額を使用します
• arithmetic-percentages - パーセンテージの計算には allocate またはスケーリングした multiply を使用します

3. 精度（HIGH）

• precision-bigint - 金額が Number.MAX_SAFE_INTEGER を超える場合は、dinero.js/bigint を使用します
• precision-crypto - 暗号資産は指数が大きいため、bigint が必要です
• precision-trim-scale - 連続した演算の後に末尾のゼロを取り除くには、trimScale を使用します

4. インポート（MEDIUM）

• imports-tree-shaking - 使用するものだけをインポートします。単独の関数を使うとツリーシェイキングが可能になります
• imports-bigint-currencies - 計算機の型を一致させます。dinero.js/bigint と併せて dinero.js/bigint/currencies を使用します

使い方

詳しい説明とコード例については、各ルールファイルをお読みください。

rules/creation-minor-units.md
rules/arithmetic-allocate-not-divide.md

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡潔な説明
• 誤ったコード例とその説明
• 正しいコード例とその説明
• 補足情報と参考資料