hangul-toolkit 0.1.0

package/dist/index.js

@@ -0,0 +1,434 @@
+// src/syllable.ts
+var HANGUL_BASE = 44032;
+var CHOSEONG_COUNT = 19;
+var JUNGSEONG_COUNT = 21;
+var JONGSEONG_COUNT = 28;
+var CHOSEONG_LIST = [
+  "\u3131",
+  "\u3132",
+  "\u3134",
+  "\u3137",
+  "\u3138",
+  "\u3139",
+  "\u3141",
+  "\u3142",
+  "\u3143",
+  "\u3145",
+  "\u3146",
+  "\u3147",
+  "\u3148",
+  "\u3149",
+  "\u314A",
+  "\u314B",
+  "\u314C",
+  "\u314D",
+  "\u314E"
+];
+var JUNGSEONG_LIST = [
+  "\u314F",
+  "\u3150",
+  "\u3151",
+  "\u3152",
+  "\u3153",
+  "\u3154",
+  "\u3155",
+  "\u3156",
+  "\u3157",
+  "\u3158",
+  "\u3159",
+  "\u315A",
+  "\u315B",
+  "\u315C",
+  "\u315D",
+  "\u315E",
+  "\u315F",
+  "\u3160",
+  "\u3161",
+  "\u3162",
+  "\u3163"
+];
+var JONGSEONG_LIST = [
+  "",
+  "\u3131",
+  "\u3132",
+  "\u3133",
+  "\u3134",
+  "\u3135",
+  "\u3136",
+  "\u3137",
+  "\u3139",
+  "\u313A",
+  "\u313B",
+  "\u313C",
+  "\u313D",
+  "\u313E",
+  "\u313F",
+  "\u3140",
+  "\u3141",
+  "\u3142",
+  "\u3144",
+  "\u3145",
+  "\u3146",
+  "\u3147",
+  "\u3148",
+  "\u314A",
+  "\u314B",
+  "\u314C",
+  "\u314D",
+  "\u314E"
+];
+var CHO_SET = new Set(CHOSEONG_LIST);
+var JUNG_SET = new Set(JUNGSEONG_LIST);
+var JONG_SET = new Set(JONGSEONG_LIST.filter((j) => j !== ""));
+var COMPLEX_JUNGSEONG = {
+  "\u3158": "\u3157\u314F",
+  "\u3159": "\u3157\u3150",
+  "\u315A": "\u3157\u3163",
+  "\u315D": "\u315C\u3153",
+  "\u315E": "\u315C\u3154",
+  "\u315F": "\u315C\u3163",
+  "\u3162": "\u3161\u3163"
+};
+var COMPLEX_JONGSEONG = {
+  "\u3133": "\u3131\u3145",
+  "\u3135": "\u3134\u3148",
+  "\u3136": "\u3134\u314E",
+  "\u313A": "\u3139\u3131",
+  "\u313B": "\u3139\u3141",
+  "\u313C": "\u3139\u3142",
+  "\u313D": "\u3139\u3145",
+  "\u313E": "\u3139\u314C",
+  "\u313F": "\u3139\u314D",
+  "\u3140": "\u3139\u314E",
+  "\u3144": "\u3142\u3145"
+};
+var REVERSE_JUNGSEONG = Object.fromEntries(
+  Object.entries(COMPLEX_JUNGSEONG).map(([k, v]) => [v, k])
+);
+var REVERSE_JONGSEONG = Object.fromEntries(
+  Object.entries(COMPLEX_JONGSEONG).map(([k, v]) => [v, k])
+);
+function isHangulSyllable(char) {
+  if (!char || char.length !== 1) return false;
+  const code = char.charCodeAt(0);
+  return code >= HANGUL_BASE && code < HANGUL_BASE + CHOSEONG_COUNT * JUNGSEONG_COUNT * JONGSEONG_COUNT;
+}
+function decompose(char) {
+  if (!isHangulSyllable(char)) {
+    throw new Error(`decompose: '${char}' is not a Hangul syllable`);
+  }
+  const offset = char.charCodeAt(0) - HANGUL_BASE;
+  const choseongIndex = Math.floor(offset / (JUNGSEONG_COUNT * JONGSEONG_COUNT));
+  const jungseongIndex = Math.floor(offset % (JUNGSEONG_COUNT * JONGSEONG_COUNT) / JONGSEONG_COUNT);
+  const jongseongIndex = offset % JONGSEONG_COUNT;
+  return {
+    choseong: CHOSEONG_LIST[choseongIndex],
+    jungseong: JUNGSEONG_LIST[jungseongIndex],
+    jongseong: jongseongIndex === 0 ? null : JONGSEONG_LIST[jongseongIndex]
+  };
+}
+function compose(choseong, jungseong, jongseong) {
+  const choIndex = CHOSEONG_LIST.indexOf(choseong);
+  const jungIndex = JUNGSEONG_LIST.indexOf(jungseong);
+  const jongIndex = jongseong ? JONGSEONG_LIST.indexOf(jongseong) : 0;
+  if (choIndex < 0 || jungIndex < 0 || jongIndex < 0) {
+    throw new Error(`compose: invalid jamo combination (${choseong}, ${jungseong}, ${jongseong ?? ""})`);
+  }
+  return String.fromCharCode(HANGUL_BASE + (choIndex * JUNGSEONG_COUNT + jungIndex) * JONGSEONG_COUNT + jongIndex);
+}
+function hasBatchim(char) {
+  if (!char) return false;
+  const last = char[char.length - 1];
+  if (!isHangulSyllable(last)) return false;
+  return (last.charCodeAt(0) - HANGUL_BASE) % JONGSEONG_COUNT !== 0;
+}
+function disassemble(text) {
+  let result = "";
+  for (const char of text) {
+    if (!isHangulSyllable(char)) {
+      result += char;
+      continue;
+    }
+    const { choseong, jungseong, jongseong } = decompose(char);
+    result += choseong;
+    result += COMPLEX_JUNGSEONG[jungseong] ?? jungseong;
+    if (jongseong) {
+      result += COMPLEX_JONGSEONG[jongseong] ?? jongseong;
+    }
+  }
+  return result;
+}
+function assemble(jamo) {
+  const chars = [...jamo];
+  let result = "";
+  let i = 0;
+  while (i < chars.length) {
+    const cho = chars[i];
+    if (!CHO_SET.has(cho)) {
+      result += cho;
+      i += 1;
+      continue;
+    }
+    let jung = "";
+    let jungLen = 0;
+    const v1 = chars[i + 1] ?? "";
+    const v2 = chars[i + 2] ?? "";
+    if (v1 && v2 && REVERSE_JUNGSEONG[v1 + v2]) {
+      jung = REVERSE_JUNGSEONG[v1 + v2];
+      jungLen = 2;
+    } else if (v1 && JUNG_SET.has(v1)) {
+      jung = v1;
+      jungLen = 1;
+    }
+    if (!jung) {
+      result += cho;
+      i += 1;
+      continue;
+    }
+    let jong;
+    let jongLen = 0;
+    const c1 = chars[i + 1 + jungLen] ?? "";
+    const c2 = chars[i + 2 + jungLen] ?? "";
+    const afterCompound = chars[i + 3 + jungLen] ?? "";
+    if (c1 && c2 && REVERSE_JONGSEONG[c1 + c2] && !JUNG_SET.has(afterCompound)) {
+      jong = REVERSE_JONGSEONG[c1 + c2];
+      jongLen = 2;
+    } else if (c1 && JONG_SET.has(c1) && !JUNG_SET.has(c2)) {
+      jong = c1;
+      jongLen = 1;
+    }
+    result += compose(cho, jung, jong);
+    i += 1 + jungLen + jongLen;
+  }
+  return result;
+}
+
+// src/josa.ts
+var JOSA_PAIRS = {
+  "\uC740/\uB294": ["\uC740", "\uB294"],
+  "\uC774/\uAC00": ["\uC774", "\uAC00"],
+  "\uC744/\uB97C": ["\uC744", "\uB97C"],
+  "\uACFC/\uC640": ["\uACFC", "\uC640"],
+  "\uC73C\uB85C/\uB85C": ["\uC73C\uB85C", "\uB85C"],
+  "\uC774\uB098/\uB098": ["\uC774\uB098", "\uB098"],
+  "\uC774\uB791/\uB791": ["\uC774\uB791", "\uB791"],
+  "\uC544/\uC57C": ["\uC544", "\uC57C"],
+  "\uC774\uC5EC/\uC5EC": ["\uC774\uC5EC", "\uC5EC"],
+  "\uC774\uC5D0\uC694/\uC608\uC694": ["\uC774\uC5D0\uC694", "\uC608\uC694"],
+  "\uC774\uC5C8/\uC600": ["\uC774\uC5C8", "\uC600"],
+  "\uC774\uACE0/\uACE0": ["\uC774\uACE0", "\uACE0"],
+  "\uC774\uB4E0/\uB4E0": ["\uC774\uB4E0", "\uB4E0"],
+  "\uC774\uC57C\uB9D0\uB85C/\uC57C\uB9D0\uB85C": ["\uC774\uC57C\uB9D0\uB85C", "\uC57C\uB9D0\uB85C"],
+  "\uC774\uB098\uB9C8/\uB098\uB9C8": ["\uC774\uB098\uB9C8", "\uB098\uB9C8"],
+  "\uC774\uC57C/\uC57C": ["\uC774\uC57C", "\uC57C"]
+};
+var DIGIT_HAS_BATCHIM = [true, true, false, true, false, false, true, true, true, false];
+var DIGIT_ENDS_WITH_RIEUL = [false, true, false, false, false, false, false, true, true, false];
+function lastCharInfo(word) {
+  const last = word[word.length - 1];
+  if (last >= "0" && last <= "9") {
+    const d = last.charCodeAt(0) - 48;
+    return { hasBatchim: DIGIT_HAS_BATCHIM[d], endsWithRieul: DIGIT_ENDS_WITH_RIEUL[d] };
+  }
+  if (isHangulSyllable(last)) {
+    const jongIndex = (last.charCodeAt(0) - 44032) % 28;
+    return {
+      hasBatchim: jongIndex !== 0,
+      endsWithRieul: jongIndex === 8
+      // 'ㄹ'
+    };
+  }
+  return { hasBatchim: false, endsWithRieul: false };
+}
+function pickJosa(word, pair) {
+  const particles = JOSA_PAIRS[pair];
+  if (!particles) {
+    throw new Error(
+      `pickJosa: unsupported particle pair '${pair}'. Supported: ${Object.keys(JOSA_PAIRS).join(", ")}`
+    );
+  }
+  if (!word) return particles[1];
+  const { hasBatchim: bat, endsWithRieul } = lastCharInfo(word);
+  if (pair === "\uC73C\uB85C/\uB85C") {
+    return !bat || endsWithRieul ? "\uB85C" : "\uC73C\uB85C";
+  }
+  return bat ? particles[0] : particles[1];
+}
+function josa(word, pair) {
+  const text = String(word);
+  return text + pickJosa(text, pair);
+}
+function supportedJosaPairs() {
+  return Object.keys(JOSA_PAIRS);
+}
+
+// src/number.ts
+var DIGITS = ["", "\uC77C", "\uC774", "\uC0BC", "\uC0AC", "\uC624", "\uC721", "\uCE60", "\uD314", "\uAD6C"];
+var SMALL_UNITS = ["", "\uC2ED", "\uBC31", "\uCC9C"];
+var BIG_UNITS = ["", "\uB9CC", "\uC5B5", "\uC870", "\uACBD", "\uD574"];
+function fourDigitsToKorean(n) {
+  const str = String(n);
+  let result = "";
+  for (let i = 0; i < str.length; i++) {
+    const digit = Number(str[i]);
+    if (digit === 0) continue;
+    const unit = SMALL_UNITS[str.length - 1 - i];
+    if (digit === 1 && unit !== "") {
+      result += unit;
+    } else {
+      result += DIGITS[digit] + unit;
+    }
+  }
+  return result;
+}
+function numberToKorean(num) {
+  if (!Number.isSafeInteger(num)) {
+    throw new RangeError("numberToKorean: value must be a safe integer");
+  }
+  if (num === 0) return "\uC601";
+  let prefix = "";
+  let n = num;
+  if (n < 0) {
+    prefix = "\uB9C8\uC774\uB108\uC2A4 ";
+    n = -n;
+  }
+  const groups = [];
+  while (n > 0) {
+    groups.push(n % 1e4);
+    n = Math.floor(n / 1e4);
+  }
+  if (groups.length > BIG_UNITS.length) {
+    throw new RangeError(`numberToKorean: numbers up to ${BIG_UNITS.length - 1} * 10^4 scale are supported`);
+  }
+  let result = "";
+  for (let i = groups.length - 1; i >= 0; i--) {
+    const group = groups[i];
+    if (group === 0) continue;
+    if (group === 1 && i > 0) {
+      result += "\uC77C" + BIG_UNITS[i];
+    } else {
+      result += fourDigitsToKorean(group) + BIG_UNITS[i];
+    }
+  }
+  return prefix + result;
+}
+function formatWon(amount) {
+  return numberToKorean(amount) + "\uC6D0";
+}
+
+// src/pii.ts
+var DEFAULT_TYPES = ["rrn", "phone", "email", "card", "driverLicense"];
+var PATTERN_PRIORITY = ["rrn", "driverLicense", "card", "phone", "email", "account"];
+var PATTERNS = {
+  // 주민등록번호 / 외국인등록번호
+  rrn: /\b\d{6}-?[1-4]\d{6}\b/g,
+  // 운전면허번호
+  driverLicense: /\b\d{2}-\d{2}-\d{6}-\d{2}\b/g,
+  // 신용카드 번호
+  card: /\b\d{4}[- ]\d{4}[- ]\d{4}[- ]\d{4}\b/g,
+  // 휴대폰(010~019) + 일반전화(02, 031~064)
+  phone: /\b0(?:1[016789]|2|[3-6]\d)-?\d{3,4}-?\d{4}\b/g,
+  email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+  // 계좌번호 (오탐 가능성이 있어 기본 비활성)
+  account: /\b\d{3,6}-\d{2,6}-\d{2,7}\b/g
+};
+function collectMatches(text, types) {
+  const matches = [];
+  for (const type of PATTERN_PRIORITY) {
+    if (!types.includes(type)) continue;
+    const pattern = new RegExp(PATTERNS[type].source, PATTERNS[type].flags);
+    let m;
+    while ((m = pattern.exec(text)) !== null) {
+      matches.push({ type, value: m[0], start: m.index, end: m.index + m[0].length });
+    }
+  }
+  const accepted = [];
+  const sorted = matches.sort(
+    (a, b) => PATTERN_PRIORITY.indexOf(a.type) - PATTERN_PRIORITY.indexOf(b.type) || a.start - b.start
+  );
+  for (const match of sorted) {
+    const overlaps = accepted.some((a) => match.start < a.end && a.start < match.end);
+    if (!overlaps) accepted.push(match);
+  }
+  return accepted.sort((a, b) => a.start - b.start);
+}
+function detectPII(text, types = [...PATTERN_PRIORITY]) {
+  return collectMatches(text, types);
+}
+function maskPII(text, options = {}) {
+  const { types = DEFAULT_TYPES, maskChar = "*", keepLast = 0 } = options;
+  const matches = collectMatches(text, types);
+  let result = text;
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const { start, end, value } = matches[i];
+    const alnumCount = (value.match(/[A-Za-z0-9]/g) ?? []).length;
+    const keep = Math.max(0, Math.min(keepLast, alnumCount));
+    let seen = 0;
+    const masked = [...value].map((ch) => {
+      if (!/[A-Za-z0-9]/.test(ch)) return ch;
+      seen += 1;
+      return seen > alnumCount - keep ? ch : maskChar;
+    }).join("");
+    result = result.slice(0, start) + masked + result.slice(end);
+  }
+  return result;
+}
+function maskName(name, maskChar = "*") {
+  const chars = [...name.trim()];
+  if (chars.length <= 1) return name;
+  if (chars.length === 2) return chars[0] + maskChar;
+  return chars[0] + maskChar.repeat(chars.length - 2) + chars[chars.length - 1];
+}
+
+// src/validate.ts
+function isValidRRN(input) {
+  const digits = input.replace(/-/g, "");
+  if (!/^\d{13}$/.test(digits)) return false;
+  const month = Number(digits.slice(2, 4));
+  const day = Number(digits.slice(4, 6));
+  if (month < 1 || month > 12 || day < 1 || day > 31) return false;
+  const weights = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5];
+  let sum = 0;
+  for (let i = 0; i < 12; i++) {
+    sum += Number(digits[i]) * weights[i];
+  }
+  const check = (11 - sum % 11) % 10;
+  return check === Number(digits[12]);
+}
+function isValidBusinessNumber(input) {
+  const digits = input.replace(/-/g, "");
+  if (!/^\d{10}$/.test(digits)) return false;
+  const weights = [1, 3, 7, 1, 3, 7, 1, 3];
+  let sum = 0;
+  for (let i = 0; i < 8; i++) {
+    sum += Number(digits[i]) * weights[i];
+  }
+  sum += Math.floor(Number(digits[8]) * 5 / 10);
+  const check = (10 - sum % 10) % 10;
+  return check === Number(digits[9]);
+}
+function isValidPhoneNumber(input) {
+  return /^0(?:1[016789]|2|[3-6]\d)-?\d{3,4}-?\d{4}$/.test(input);
+}
+export {
+  CHOSEONG_LIST,
+  JONGSEONG_LIST,
+  JUNGSEONG_LIST,
+  assemble,
+  compose,
+  decompose,
+  detectPII,
+  disassemble,
+  formatWon,
+  hasBatchim,
+  isHangulSyllable,
+  isValidBusinessNumber,
+  isValidPhoneNumber,
+  isValidRRN,
+  josa,
+  maskName,
+  maskPII,
+  numberToKorean,
+  pickJosa,
+  supportedJosaPairs
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "hangul-toolkit",
+  "version": "0.1.0",
+  "description": "한국어 텍스트 처리 유틸리티 — 조사 선택, 자소 분해/조합, 숫자→한글 변환, 개인정보(PII) 마스킹 / Korean text utilities: josa picker, syllable disassemble/assemble, number-to-Korean, PII masking for LLM preprocessing",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "hangul",
+    "korean",
+    "한글",
+    "한국어",
+    "josa",
+    "조사",
+    "pii",
+    "masking",
+    "개인정보",
+    "llm",
+    "korean-text",
+    "nlp"
+  ],
+  "license": "MIT",
+  "author": "feelyday",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/feelyday/hangul-toolkit.git"
+  },
+  "bugs": "https://github.com/feelyday/hangul-toolkit/issues",
+  "homepage": "https://github.com/feelyday/hangul-toolkit#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}