ya-kansuji 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+このプロジェクトの主な変更点を記録する。書式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) に準拠し、[Semantic Versioning](https://semver.org/lang/ja/) に従う。
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-14
+
+初回リリース。Ruby gem [ya_kansuji](https://github.com/sugi/ya_kansuji) 1.1.0 の TypeScript/JavaScript 移植版。
+
+### Added
+
+- 読み取り: `toNumber` / `toBigInt` — 漢数字・大字・全角数字・カンマ表現・位取り・単位なし表記が混在したテキストを数値へ変換。
+- フォーマット: `toKan` と 5 つのビルトインフォーマッタ（`simple` / `gov` / `lawyer` / `judicV` / `judicH`）。
+- `registerFormatter` / `getFormatter` によるフォーマッタプラグイン機構。
+- ESM・CommonJS・IIFE（CDN 用）ビルドと型定義を同梱。
+
+[Unreleased]: https://github.com/sugi/ya-kansuji-js/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sugi/ya-kansuji-js/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tatsuki Sugiura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# ya-kansuji
+
+[![CI](https://github.com/sugi/ya-kansuji-js/actions/workflows/ci.yml/badge.svg)](https://github.com/sugi/ya-kansuji-js/actions/workflows/ci.yml)
+
+Yet another (ultimate) Japanese Kansuji library for JavaScript/TypeScript.
+
+`ya-kansuji` は Ruby gem [ya_kansuji](https://github.com/sugi/ya_kansuji) の TypeScript/JavaScript 移植版です。漢数字・大字・全角数字混じりのテキストと数値を相互変換します。対応する Ruby 版は ya_kansuji 1.1.0 です。
+
+現状のサポートは日本語で万進な10進数だけです。歴史的に使われたことのあった万万進や他の漢字圏の漢数字はサポートしていません。
+
+## 機能
+
+* 読み取り: 以下の混在したテキストを数値に変換できます
+  * 漢数字 (二万三千五百六十七)
+  * 全角数字 (１２３４)
+  * 単位なし / ゼロ (一六九〇)
+  * 位取り (2億0010万 / 千〇〇二)
+  * 大字 (千皕卅肆)
+  * カンマ表現 (12,345 / 5億3,456万 / 二万、五十)
+* 数値から漢数字、漢字混じり数値文字列へのフォーマット
+  * 複数のビルトインフォーマッタ
+  * フォーマッタプラグイン機構
+
+## インストール
+
+```bash
+npm install ya-kansuji
+```
+
+## 使い方
+
+### 読み取り (漢数字 → 数値)
+
+`toNumber` に文字列を渡すと数値 (`number`) に変換できます。読み取りに関してオプションはありません。
+
+```ts
+import { toNumber } from 'ya-kansuji'
+
+toNumber('一〇二四') // => 1024
+```
+
+無量大数 (10^68) など `Number.MAX_SAFE_INTEGER` を超える値を扱う場合は、`bigint` を返す `toBigInt` を使ってください。`toNumber` は範囲を超える値に対して `RangeError` を投げます。
+
+```ts
+import { toBigInt, toNumber } from 'ya-kansuji'
+
+toBigInt('一無量大数') // => 100000000000000000000000000000000000000000000000000000000000000000000n
+toNumber('一無量大数') // throws RangeError
+```
+
+先頭の「マイナス」は負の符号として解釈します。ASCII の `-` や Unicode の `−` (U+2212) は符号として扱いません。
+
+```ts
+toNumber('マイナス千二百三十四') // => -1234
+toNumber('マイナス 五十')        // => -50 (区切り文字は除去してから照合します)
+toNumber('2019-04')             // => 2019
+```
+
+### フォーマット (数値 → 漢数字)
+
+`toKan` に数値 (`number` または `bigint`) を渡すと、漢数字や漢字混じりの文字列に変換します。
+
+```ts
+import { toKan } from 'ya-kansuji'
+
+toKan(12345) // => '一万二千三百四十五'
+```
+
+第2引数にフォーマッタ名を渡すことで、出力形式を切り替えられます。
+
+```ts
+toKan(12340005, 'simple')  // => '千二百三十四万五'
+toKan(12340005, 'gov')     // => '1234万, 5'
+toKan(12340005, 'lawyer')  // => '1,234万5'
+toKan(12340005, 'judic_v') // => '一二三四万〇〇〇五'
+toKan(12340005, 'judic_h') // => '１２３４万０００５'
+```
+
+現在あるビルトインフォーマッタは以下のとおりです (`toKan(10003, ...)` の実出力):
+
+| フォーマッタ | 説明 | 出力例 |
+| --- | --- | --- |
+| `simple` | 標準 | `一万三` |
+| `gov` | 「公用文作成の要領」方式 | `1万, 3` |
+| `lawyer` | 行政司法協会方式 | `1万3` |
+| `judic_v` | 裁判判例縦書き方式 | `一万〇〇〇三` |
+| `judic_h` | 最高裁判例横書き方式 | `１万０００３` |
+
+負数を渡すと先頭に「マイナス」を付け、絶対値をフォーマッタに渡します。フォーマッタが受け取るのは常に非負の値です。
+
+```ts
+toKan(-1234)         // => 'マイナス千二百三十四'
+toKan(-10003, 'gov') // => 'マイナス1万, 3'
+```
+
+非整数の `number`、および `Number.MAX_SAFE_INTEGER` (2^53 - 1) を超える `number` は受け付けず、`RangeError` を投げます。
+より大きな値は `bigint` で渡せますが、組み込みフォーマッタが表現できる範囲は絶対値が `10^72 - 1` 以下です。
+範囲を超える値には `RangeError` を投げます。
+
+```ts
+toKan(1.5) // throws RangeError
+toKan(10n ** 72n) // throws RangeError
+```
+
+`simple`、`gov`、`lawyer`、`judicV`、`judicH` を直接呼び出す場合、入力は `0n` 以上 `10n ** 72n - 1n` 以下でなければなりません。
+負数や範囲を超える値には `RangeError` を投げます。
+負数をフォーマットする場合は、符号処理を行う `toKan` を使用してください。
+
+#### 独自フォーマッタ
+
+`registerFormatter` を使うと独自のフォーマッタを登録できます。第1引数に名前、第2引数に `(num: bigint, options?) => string` の関数を渡します。
+
+```ts
+import { registerFormatter, toKan } from 'ya-kansuji'
+
+registerFormatter('hoge', (num) => {
+  if (num === 0n) return ''
+  if (num === 1n) return 'いち'
+  if (num === 2n) return 'に'
+  return 'たくさん'
+})
+
+toKan(2, 'hoge')   // => 'に'
+toKan(123, 'hoge') // => 'たくさん'
+```
+
+登録済みフォーマッタは `getFormatter(name)` で取得できます。`toKan` の第2引数にはフォーマッタ名の代わりに関数を直接渡すこともできます。
+
+ESM 版 (`dist/index.js`) と CJS 版 (`dist/index.cjs`) はそれぞれ別モジュールとしてロードされ、フォーマッタのレジストリ (`Map`) を共有しません。`registerFormatter` で登録したフォーマッタを使う側は、登録した側と同じモジュール形式 (`import` または `require`) で `ya-kansuji` を読み込んでください。
+
+### CDN での使用
+
+npm 経由のインストールなしに、CDN から直接読み込むこともできます。
+
+```html
+<!-- script タグ (グローバル YaKansuji) -->
+<script src="https://cdn.jsdelivr.net/npm/ya-kansuji@0.1.0/dist/index.iife.min.js"></script>
+<script>
+  console.log(YaKansuji.toKan(1234)); // => 千二百三十四
+</script>
+
+<!-- ES Modules -->
+<script type="module">
+  import { toNumber } from 'https://cdn.jsdelivr.net/npm/ya-kansuji@0.1.0/+esm';
+  console.log(toNumber('九億６千万卌一')); // => 960000041
+</script>
+```
+
+## Ruby 版との差分
+
+Ruby 版 [ya_kansuji](https://github.com/sugi/ya_kansuji) からの移植にあたり、以下の点が異なります。
+
+1. **標準クラスの拡張は移植していません。** Ruby 版にある `String#to_i` の置き換えや `Integer#to_kan` の追加 (`core_ext` / `CoreRefine`) に相当する機能はありません。常に `toNumber` / `toBigInt` / `toKan` を明示的に呼び出してください。
+2. **`toKan` は非整数・安全範囲外の `number` を受け付けません。** 負数は Ruby 版 1.1.0 と同様に先頭へ「マイナス」を付け、絶対値をフォーマッタに渡して処理します (`toKan(-1234)` → `'マイナス千二百三十四'`、Ruby の `to_kan(-1234)` と一致)。一方、Ruby 版は `to_kan` の内部で `to_i` を呼ぶため小数は `Float#to_i` で暗黙に切り捨てて処理が通ります (`to_kan(1.5)` → `"一"`、`to_kan(-0.5)` → `"零"`) が、JS 版は安全整数でない `number` を `RangeError` にします。加えて `Number.MAX_SAFE_INTEGER` (2^53 - 1) を超える `number` を渡した場合も JS 版は `RangeError` です。`bigint` では絶対値 `10^72 - 1` まで扱えます。
+3. **`to_i` に相当する変換が `toBigInt` / `toNumber` の2関数に分かれています。** 無量大数 (10^68) は JavaScript の `Number.MAX_SAFE_INTEGER` (2^53 - 1) を大きく超えるため、常に安全な `bigint` を返す `toBigInt` と、安全な範囲を超えると `RangeError` を投げる `toNumber` を用途に応じて使い分けます。
+
+### 既知の非互換
+
+かつて Ruby 版 `YaKansuji::REGEXP_PART` は 1.0.x まで、正規表現の文字クラスに配列を `#{}` 展開しており、`Array#to_s` (= `inspect`) の結果 (`["十", "百", ...]` のような、ダブルクォートやカンマを含む文字列表現) をそのまま埋め込む事故を起こしていました。この副作用で 1.0.x の `YaKansuji.to_i` は数値列中に `"` (U+0022) が混ざっていても無視して受理していました (`to_i('1"000')` → `1000`)。JS 版はこの事故を再現していないため、以前から `toBigInt('1"000')` は `"` の手前で読み取りが止まり `1` を返しており、**ya_kansuji 1.1.0 でこのバグが修正された結果、両者の挙動は一致しました** (Ruby 1.1.0 の `to_i('1"000')` も `1`)。
+
+空白除去の実装は Ruby 版の `[[:space:]]` と JS 版の `\s` とで対象が完全には一致せず、U+0085 (NEL) と U+FEFF (BOM) の2コードポイントだけ挙動が異なります (Ruby は NEL を空白として除去し BOM は除去しない、JS はその逆)。
+
+## License
+
+The package is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+Tatsuki Sugiura <sugi@nemui.org>

package/dist/index.cjs

@@ -0,0 +1,401 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/constants.ts
+/** 10^1〜10^3 の位を表す漢数字の単位（十・百・千）。 */
+const UNIT_EXP3 = [
+	"十",
+	"百",
+	"千"
+];
+/** 10^4 ごとに繰り上がる漢数字の単位（万・億・兆…無量大数）。 */
+const UNIT_EXP4 = [
+	"万",
+	"億",
+	"兆",
+	"京",
+	"垓",
+	"𥝱",
+	"穣",
+	"溝",
+	"澗",
+	"正",
+	"載",
+	"極",
+	"恒河沙",
+	"阿僧祇",
+	"那由他",
+	"不可思議",
+	"無量大数"
+];
+const KAN_DIGITS = "〇一二三四五六七八九";
+const NUM_ALT_CHARS = `${KAN_DIGITS}０１２３４５６７８９零壱壹弌弐貳貮参參弎肆伍陸漆質柒捌玖拾什陌佰阡仟萬秭`;
+const NUM_NORMALIZED_CHARS = "01234567890123456789011122233345677789十十百百千千万𥝱";
+//#endregion
+//#region src/parse.ts
+const altChars = Array.from(NUM_ALT_CHARS);
+const normChars = Array.from(NUM_NORMALIZED_CHARS);
+const NORMALIZE_MAP = new Map(altChars.map((c, i) => [c, normChars[i]]));
+const SEPARATORS = /* @__PURE__ */ new Set([
+	",",
+	"，",
+	"、",
+	"	",
+	"\n",
+	"\v",
+	"\f",
+	"\r",
+	" ",
+	"\xA0",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	" ",
+	"\u2028",
+	"\u2029",
+	" ",
+	" ",
+	"　",
+	""
+]);
+const DIGIT_VALUES = [
+	0n,
+	1n,
+	2n,
+	3n,
+	4n,
+	5n,
+	6n,
+	7n,
+	8n,
+	9n
+];
+const SPECIAL_NUMBER_VALUES = /* @__PURE__ */ new Map([
+	["卄", 20n],
+	["廿", 20n],
+	["卅", 30n],
+	["丗", 30n],
+	["卌", 40n],
+	["皕", 200n]
+]);
+const SINGLE_UNITS = [...UNIT_EXP3, ...UNIT_EXP4.filter((u) => Array.from(u).length === 1)];
+const MULTI_UNITS = UNIT_EXP4.filter((u) => Array.from(u).length > 1);
+const CHAR_CLASS = [.../* @__PURE__ */ new Set([
+	...altChars,
+	...normChars,
+	...SINGLE_UNITS,
+	...SPECIAL_NUMBER_VALUES.keys()
+])].join("");
+const PART_SOURCE = `${MULTI_UNITS.join("|")}|[${CHAR_CLASS}]`;
+const KANSUJI_REGEXP = new RegExp(`(?:マイナス)?(?:${PART_SOURCE})+`, "u");
+const PART_REGEXP = new RegExp(PART_SOURCE, "gu");
+function createUnitValues(units, base) {
+	let value = base;
+	return new Map(units.map((unit) => {
+		const entry = [unit, value];
+		value *= base;
+		return entry;
+	}));
+}
+const UNIT_EXP3_VALUES = createUnitValues(UNIT_EXP3, 10n);
+const UNIT_EXP4_VALUES = createUnitValues(UNIT_EXP4, 10000n);
+const MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
+function clean(str) {
+	let result = "";
+	for (const c of str) {
+		const normalized = NORMALIZE_MAP.get(c) ?? c;
+		if (!SEPARATORS.has(normalized)) result += normalized;
+	}
+	return result;
+}
+/**
+* 漢数字・大字・全角数字が混じったテキストを bigint に変換する。
+*
+* 照合前にカンマ・読点・各種空白などの区切り文字を除去し、先頭から連続してマッチする
+* 数値表現だけを読み取る（例: `toBigInt('五x六')` は `5n`）。マッチしなければ `0n` を返す。
+* 先頭の「マイナス」は負号として扱うが、ASCII の `-` や U+2212（−）は負号として扱わない。
+* 値の上限はなく、無量大数（10^68）を超える大きさもそのまま扱える。
+*
+* @param str 変換対象の文字列
+* @returns テキストが表す整数値
+* @example
+* toBigInt('一〇二四')       // => 1024n
+* toBigInt('マイナス千二百') // => -1200n
+* toBigInt('一無量大数')     // => 10n ** 68n
+*/
+function toBigInt(str) {
+	const cleaned = clean(String(str));
+	const matched = KANSUJI_REGEXP.exec(cleaned);
+	if (!matched) return 0n;
+	const matchedText = matched[0];
+	if (matchedText === void 0) return 0n;
+	let ret3 = 0n;
+	let ret4 = 0n;
+	let curnum = null;
+	for (const c of matchedText.match(PART_REGEXP) ?? []) if (c >= "1" && c <= "9") {
+		const digit = DIGIT_VALUES[c.charCodeAt(0) - 48];
+		curnum = (curnum ?? 0n) * 10n + digit;
+	} else if (c === "0") {
+		if (curnum !== null) curnum *= 10n;
+	} else {
+		const specialNumber = SPECIAL_NUMBER_VALUES.get(c);
+		if (specialNumber !== void 0) {
+			ret3 += specialNumber;
+			curnum = null;
+		} else {
+			const unit4 = UNIT_EXP4_VALUES.get(c);
+			if (unit4 !== void 0) {
+				if (curnum !== null) {
+					ret3 += curnum;
+					curnum = null;
+				}
+				if (ret3 === 0n) ret3 = 1n;
+				ret4 += ret3 * unit4;
+				ret3 = 0n;
+			} else {
+				const unit3 = UNIT_EXP3_VALUES.get(c);
+				if (unit3 !== void 0) {
+					curnum ??= 1n;
+					ret3 += curnum * unit3;
+					curnum = null;
+				}
+			}
+		}
+	}
+	if (curnum !== null) ret3 += curnum;
+	const ret = ret4 + ret3;
+	return matchedText.startsWith("マイナス") ? -ret : ret;
+}
+/**
+* {@link toBigInt} と同じ規則でテキストを解釈し、`number` として返す。
+*
+* 結果の絶対値が `Number.MAX_SAFE_INTEGER`（2^53 − 1）を超える場合は `RangeError` を
+* 投げる。安全整数を超えうる値を扱うときは {@link toBigInt} を使うこと。
+*
+* @param str 変換対象の文字列
+* @returns テキストが表す数値
+* @throws {RangeError} 値が安全整数の範囲を超える場合
+* @example
+* toNumber('一〇二四')   // => 1024
+* toNumber('一無量大数') // throws RangeError
+*/
+function toNumber(str) {
+	const value = toBigInt(str);
+	if (value > MAX_SAFE_BIGINT || value < -MAX_SAFE_BIGINT) throw new RangeError(`kansuji value exceeds Number.MAX_SAFE_INTEGER: ${str}`);
+	return Number(value);
+}
+//#endregion
+//#region src/groups.ts
+const GROUP_BASE = 10000n;
+const GROUP_UNITS = ["", ...UNIT_EXP4];
+const GROUP_COUNT = GROUP_UNITS.length;
+const MAX_EXCLUSIVE = GROUP_BASE ** BigInt(GROUP_COUNT);
+const MAX_DIGITS = GROUP_COUNT * 4;
+function groups4(num) {
+	if (num < 0n || num >= MAX_EXCLUSIVE) throw new RangeError(`Kansuji formatters require a bigint between 0 and 10^${MAX_DIGITS} - 1`);
+	const ret = [];
+	let value = num;
+	let unitIndex = 0;
+	do {
+		const unit = GROUP_UNITS[unitIndex];
+		if (unit === void 0) throw new RangeError(`Kansuji formatters require a bigint between 0 and 10^${MAX_DIGITS} - 1`);
+		ret.push([Number(value % GROUP_BASE), unit]);
+		value /= GROUP_BASE;
+		unitIndex++;
+	} while (value > 0n);
+	return ret.reverse();
+}
+//#endregion
+//#region src/formatter/gov.ts
+/**
+* 「公用文作成の要領」方式で整形する（4桁ごとにアラビア数字＋漢字単位、読点区切り）。
+*
+* @param num 0 以上 `10^72 − 1` 以下の bigint
+* @returns 整形後の文字列。`0n` は `'0'`
+* @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+* @example
+* gov(12340005n) // => '1234万, 5'
+* gov(10003n)    // => '1万, 3'
+*/
+function gov(num) {
+	if (num === 0n) return "0";
+	const parts = [];
+	for (const [i4, unit4] of groups4(num)) {
+		if (i4 === 0) continue;
+		parts.push(`${i4}${unit4}`);
+	}
+	return parts.join(", ");
+}
+//#endregion
+//#region src/formatter/judic.ts
+function judic(num, zero, mapDigits) {
+	if (num === 0n) return zero;
+	let ret = "";
+	let head = true;
+	for (const [i4, unit4] of groups4(num)) {
+		if (i4 === 0) continue;
+		ret += (head ? String(i4) : String(i4).padStart(4, "0")) + unit4;
+		head = false;
+	}
+	return mapDigits(ret);
+}
+/**
+* 裁判判例の縦書き方式で整形する（4桁ごとに漢数字、下位グループはゼロ埋め、単位は漢字）。
+*
+* @param num 0 以上 `10^72 − 1` 以下の bigint
+* @returns 整形後の文字列。`0n` は `'〇'`
+* @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+* @example
+* judicV(12340005n) // => '一二三四万〇〇〇五'
+*/
+function judicV(num) {
+	return judic(num, "〇", (s) => s.replace(/[0-9]/g, (d) => KAN_DIGITS.charAt(Number(d))));
+}
+/**
+* 最高裁判例の横書き方式で整形する（4桁ごとに全角数字、下位グループはゼロ埋め）。
+*
+* @param num 0 以上 `10^72 − 1` 以下の bigint
+* @returns 整形後の文字列。`0n` は `'０'`
+* @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+* @example
+* judicH(12340005n) // => '１２３４万０００５'
+*/
+function judicH(num) {
+	return judic(num, "０", (s) => s.replace(/[0-9]/g, (d) => String.fromCharCode(d.charCodeAt(0) + 65248)));
+}
+//#endregion
+//#region src/formatter/lawyer.ts
+/**
+* 行政・司法で用いられる方式で整形する（4桁ごとにアラビア数字＋漢字単位、千の位にカンマ）。
+*
+* @param num 0 以上 `10^72 − 1` 以下の bigint
+* @returns 整形後の文字列。`0n` は `'0'`
+* @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+* @example
+* lawyer(12340005n) // => '1,234万5'
+* lawyer(10003n)    // => '1万3'
+*/
+function lawyer(num) {
+	if (num === 0n) return "0";
+	let ret = "";
+	for (const [i4, unit4] of groups4(num)) {
+		if (i4 === 0) continue;
+		const s = String(i4);
+		ret += (i4 >= 1e3 ? `${s[0]},${s.slice(1)}` : s) + unit4;
+	}
+	return ret;
+}
+//#endregion
+//#region src/formatter/simple.ts
+const POWERS_10 = [
+	1,
+	10,
+	100,
+	1e3
+];
+/**
+* 標準的な漢数字へ整形する（位ごとに漢数字の単位を使う）。
+*
+* @param num 0 以上 `10^72 − 1` 以下の bigint
+* @returns 漢数字文字列。`0n` は `'零'`
+* @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+* @example
+* simple(12345n) // => '一万二千三百四十五'
+* simple(10003n) // => '一万三'
+*/
+function simple(num) {
+	if (num === 0n) return "零";
+	let ret = "";
+	for (const [i4, unit4] of groups4(num)) {
+		if (i4 === 0) continue;
+		for (let j = UNIT_EXP3.length; j >= 0; j--) {
+			const unit3 = UNIT_EXP3[j - 1] ?? "";
+			const i3 = Math.floor(i4 / (POWERS_10[j] ?? 1)) % 10;
+			if (i3 === 0) continue;
+			ret += i3 === 1 && unit3 !== "" ? unit3 : KAN_DIGITS.charAt(i3) + unit3;
+		}
+		ret += unit4;
+	}
+	return ret;
+}
+//#endregion
+//#region src/formatters.ts
+const formatters = /* @__PURE__ */ new Map([
+	["simple", simple],
+	["gov", gov],
+	["lawyer", lawyer],
+	["judic_v", judicV],
+	["judic_h", judicH]
+]);
+/**
+* フォーマッタを名前付きで登録する。既存の同名フォーマッタ（ビルトイン含む）は警告なく
+* 上書きされる。
+*
+* レジストリは ESM 版と CJS 版で共有されない。登録側と利用側は同じモジュール形式
+* (`import` または `require`) で `ya-kansuji` を読み込むこと。
+*
+* @param name フォーマッタ名。{@link toKan} の第2引数に渡して選択する
+* @param formatter `(num: bigint, options?) => string`。`num` は常に 0 以上
+* @throws {TypeError} `formatter` が関数でない場合
+*/
+function registerFormatter(name, formatter) {
+	if (typeof formatter !== "function") throw new TypeError("Registering invalid formatter.");
+	formatters.set(name, formatter);
+}
+/**
+* 登録済みフォーマッタを名前で取得する。未登録なら `undefined`。
+*
+* @param name フォーマッタ名
+* @returns フォーマッタ関数、なければ `undefined`
+*/
+function getFormatter(name) {
+	return formatters.get(name);
+}
+/**
+* 数値を漢数字・漢字混じりの文字列へ整形する。
+*
+* 負数は先頭に「マイナス」を付け、絶対値をフォーマッタに渡す（フォーマッタが受け取るのは
+* 常に非負値）。`number` は安全整数でなければならず、より大きな値は `bigint` で渡すこと。
+* ビルトインフォーマッタが表現できるのは絶対値 `10^72 − 1` まで。
+*
+* @param num 変換対象。`number`（安全整数）または `bigint`
+* @param formatter フォーマッタ名、またはフォーマッタ関数。既定は `'simple'`
+* @param options フォーマッタへ渡すオプション（ビルトインは未使用）
+* @returns 整形後の文字列
+* @throws {RangeError} `num` が非整数、安全整数を超える `number`、またはビルトイン
+*   フォーマッタの表現範囲を超える場合
+* @throws {TypeError} 指定した名前のフォーマッタが見つからない場合
+* @example
+* toKan(12345)           // => '一万二千三百四十五'
+* toKan(12340005, 'gov') // => '1234万, 5'
+* toKan(-1234)           // => 'マイナス千二百三十四'
+*/
+function toKan(num, formatter = "simple", options = {}) {
+	let value;
+	if (typeof num === "bigint") value = num;
+	else if (Number.isSafeInteger(num)) value = BigInt(num);
+	else throw new RangeError(`toKan requires a safe integer or bigint: ${num}`);
+	if (value < 0n) return `マイナス${toKan(-value, formatter, options)}`;
+	const fn = typeof formatter === "function" ? formatter : formatters.get(formatter);
+	if (!fn) throw new TypeError(`Unable to find formatter ${String(formatter)}`);
+	return fn(value, options);
+}
+//#endregion
+exports.UNIT_EXP3 = UNIT_EXP3;
+exports.UNIT_EXP4 = UNIT_EXP4;
+exports.getFormatter = getFormatter;
+exports.gov = gov;
+exports.judicH = judicH;
+exports.judicV = judicV;
+exports.lawyer = lawyer;
+exports.registerFormatter = registerFormatter;
+exports.simple = simple;
+exports.toBigInt = toBigInt;
+exports.toKan = toKan;
+exports.toNumber = toNumber;