ya-kansuji 0.1.0

package/dist/index.js

@@ -0,0 +1,389 @@
+//#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
+export { UNIT_EXP3, UNIT_EXP4, getFormatter, gov, judicH, judicV, lawyer, registerFormatter, simple, toBigInt, toKan, toNumber };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "ya-kansuji",
+  "version": "0.1.0",
+  "description": "Yet another Japanese kansuji library — converts Japanese numerals (漢数字・大字・全角) to/from numbers",
+  "keywords": [
+    "kansuji",
+    "japanese",
+    "numeral",
+    "漢数字",
+    "大字"
+  ],
+  "license": "MIT",
+  "author": "Tatsuki Sugiura <sugi@nemui.org>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "unpkg": "./dist/index.iife.min.js",
+  "jsdelivr": "./dist/index.iife.min.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "pretest": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm test && npx publint && npx @arethetypeswrong/cli --pack .",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.7",
+    "typescript": "^7.0.2",
+    "unrun": "^0.3.1",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sugi/ya-kansuji-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sugi/ya-kansuji-js/issues"
+  },
+  "homepage": "https://github.com/sugi/ya-kansuji-js#readme"
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+/** 10^1〜10^3 の位を表す漢数字の単位（十・百・千）。 */
+export const UNIT_EXP3 = ['十', '百', '千'] as const
+
+/** 10^4 ごとに繰り上がる漢数字の単位（万・億・兆…無量大数）。 */
+export const UNIT_EXP4 = [
+  '万', '億', '兆', '京', '垓', '𥝱', '穣', '溝', '澗',
+  '正', '載', '極', '恒河沙', '阿僧祇', '那由他', '不可思議', '無量大数',
+] as const
+
+export const KAN_DIGITS = '〇一二三四五六七八九'
+
+// Ruby 版の tr 用ペア文字列と同一。コードポイント単位で位置対応している。
+export const NUM_ALT_CHARS =
+  `${KAN_DIGITS}０１２３４５６７８９零壱壹弌弐貳貮参參弎肆伍陸漆質柒捌玖拾什陌佰阡仟萬秭`
+export const NUM_NORMALIZED_CHARS =
+  '01234567890123456789011122233345677789十十百百千千万𥝱'

package/src/formatter/gov.ts

@@ -0,0 +1,21 @@
+import { groups4 } from '../groups.js'
+
+/**
+ * 「公用文作成の要領」方式で整形する（4桁ごとにアラビア数字＋漢字単位、読点区切り）。
+ *
+ * @param num 0 以上 `10^72 − 1` 以下の bigint
+ * @returns 整形後の文字列。`0n` は `'0'`
+ * @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+ * @example
+ * gov(12340005n) // => '1234万, 5'
+ * gov(10003n)    // => '1万, 3'
+ */
+export function gov(num: bigint): string {
+  if (num === 0n) return '0'
+  const parts: string[] = []
+  for (const [i4, unit4] of groups4(num)) {
+    if (i4 === 0) continue
+    parts.push(`${i4}${unit4}`)
+  }
+  return parts.join(', ')
+}

package/src/formatter/judic.ts

@@ -0,0 +1,42 @@
+import { KAN_DIGITS } from '../constants.js'
+import { groups4 } from '../groups.js'
+
+function judic(num: bigint, zero: string, mapDigits: (s: string) => string): string {
+  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) // => '一二三四万〇〇〇五'
+ */
+export function judicV(num: bigint): string {
+  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) // => '１２３４万０００５'
+ */
+export function judicH(num: bigint): string {
+  return judic(num, '０', (s) =>
+    s.replace(/[0-9]/g, (d) => String.fromCharCode(d.charCodeAt(0) + 0xfee0)),
+  )
+}

package/src/formatter/lawyer.ts

@@ -0,0 +1,22 @@
+import { groups4 } from '../groups.js'
+
+/**
+ * 行政・司法で用いられる方式で整形する（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'
+ */
+export function lawyer(num: bigint): string {
+  if (num === 0n) return '0'
+  let ret = ''
+  for (const [i4, unit4] of groups4(num)) {
+    if (i4 === 0) continue
+    const s = String(i4)
+    ret += (i4 >= 1000 ? `${s[0]},${s.slice(1)}` : s) + unit4
+  }
+  return ret
+}

package/src/formatter/simple.ts

@@ -0,0 +1,30 @@
+import { KAN_DIGITS, UNIT_EXP3 } from '../constants.js'
+import { groups4 } from '../groups.js'
+
+const POWERS_10 = [1, 10, 100, 1000] as const
+
+/**
+ * 標準的な漢数字へ整形する（位ごとに漢数字の単位を使う）。
+ *
+ * @param num 0 以上 `10^72 − 1` 以下の bigint
+ * @returns 漢数字文字列。`0n` は `'零'`
+ * @throws {RangeError} 範囲外の値の場合。負数の整形には {@link toKan} を使う
+ * @example
+ * simple(12345n) // => '一万二千三百四十五'
+ * simple(10003n) // => '一万三'
+ */
+export function simple(num: bigint): string {
+  if (num === 0n) return '零'
+  let ret = ''
+  for (const [i4, unit4] of groups4(num)) {
+    if (i4 === 0) continue
+    for (let j: number = 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
+}

package/src/formatters.ts

@@ -0,0 +1,88 @@
+import { gov } from './formatter/gov.js'
+import { judicH, judicV } from './formatter/judic.js'
+import { lawyer } from './formatter/lawyer.js'
+import { simple } from './formatter/simple.js'
+
+/** フォーマッタに渡す任意のオプション。ビルトインフォーマッタは参照しない。 */
+export type KansujiFormatterOptions = Record<string, unknown>
+
+/**
+ * 非負の bigint を文字列へ整形する関数。{@link toKan} は負数の符号処理を済ませたうえで
+ * 常に 0 以上の値を渡す。
+ */
+export type KansujiFormatter = (num: bigint, options?: KansujiFormatterOptions) => string
+
+const formatters = new Map<string, KansujiFormatter>([
+  ['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` が関数でない場合
+ */
+export function registerFormatter(name: string, formatter: KansujiFormatter): void {
+  if (typeof formatter !== 'function') {
+    throw new TypeError('Registering invalid formatter.')
+  }
+  formatters.set(name, formatter)
+}
+
+/**
+ * 登録済みフォーマッタを名前で取得する。未登録なら `undefined`。
+ *
+ * @param name フォーマッタ名
+ * @returns フォーマッタ関数、なければ `undefined`
+ */
+export function getFormatter(name: string): KansujiFormatter | undefined {
+  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)           // => 'マイナス千二百三十四'
+ */
+export function toKan(
+  num: number | bigint,
+  formatter: string | KansujiFormatter = 'simple',
+  options: KansujiFormatterOptions = {},
+): string {
+  let value: bigint
+  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)
+}