hangul-toolkit 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,141 @@
+/**
+ * 한글 음절 분해/조합 유틸리티
+ * Hangul syllable decomposition & composition
+ */
+declare const CHOSEONG_LIST: readonly ["ㄱ", "ㄲ", "ㄴ", "ㄷ", "ㄸ", "ㄹ", "ㅁ", "ㅂ", "ㅃ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅉ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+declare const JUNGSEONG_LIST: readonly ["ㅏ", "ㅐ", "ㅑ", "ㅒ", "ㅓ", "ㅔ", "ㅕ", "ㅖ", "ㅗ", "ㅘ", "ㅙ", "ㅚ", "ㅛ", "ㅜ", "ㅝ", "ㅞ", "ㅟ", "ㅠ", "ㅡ", "ㅢ", "ㅣ"];
+declare const JONGSEONG_LIST: readonly ["", "ㄱ", "ㄲ", "ㄳ", "ㄴ", "ㄵ", "ㄶ", "ㄷ", "ㄹ", "ㄺ", "ㄻ", "ㄼ", "ㄽ", "ㄾ", "ㄿ", "ㅀ", "ㅁ", "ㅂ", "ㅄ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+interface DecomposedSyllable {
+    choseong: string;
+    jungseong: string;
+    jongseong: string | null;
+}
+/** 한글 음절(가~힣)인지 확인 */
+declare function isHangulSyllable(char: string): boolean;
+/** 음절을 초성/중성/종성으로 분해 */
+declare function decompose(char: string): DecomposedSyllable;
+/** 초성/중성(/종성)을 조합해 음절 생성 */
+declare function compose(choseong: string, jungseong: string, jongseong?: string | null): string;
+/** 문자가 받침(종성)으로 끝나는지 확인 */
+declare function hasBatchim(char: string): boolean;
+/**
+ * 문자열을 자모 단위로 분해
+ * @example disassemble('값') // 'ㄱㅏㅂㅅ'
+ * @example disassemble('한글') // 'ㅎㅏㄴㄱㅡㄹ'
+ */
+declare function disassemble(text: string): string;
+/**
+ * 자모 나열을 음절로 조합 (disassemble의 역함수)
+ * @example assemble('ㄱㅏㅂㅅ') // '값'
+ * @example assemble('ㄱㅏㅂㅅㅏ') // '갑사'
+ */
+declare function assemble(jamo: string): string;
+
+/**
+ * 한국어 조사(은/는, 이/가, 을/를...) 자동 선택
+ * Automatic Korean particle (josa) picker
+ */
+type JosaPair = readonly [string, string];
+/** 지원하는 조사 쌍: [받침 있음, 받침 없음] */
+declare const JOSA_PAIRS: Record<string, JosaPair>;
+/**
+ * 단어에 맞는 조사를 골라 반환
+ * @example pickJosa('사과', '은/는') // '는'
+ * @example pickJosa('책', '은/는')   // '은'
+ * @example pickJosa('서울', '으로/로') // '로'
+ */
+declare function pickJosa(word: string, pair: keyof typeof JOSA_PAIRS | string): string;
+/**
+ * 단어 뒤에 올바른 조사를 붙여 반환
+ * @example josa('사과', '을/를')  // '사과를'
+ * @example josa('부산', '으로/로') // '부산으로'
+ * @example josa('3', '이/가')     // '3이' (숫자는 발음 기준)
+ */
+declare function josa(word: string | number, pair: keyof typeof JOSA_PAIRS | string): string;
+/** 지원하는 조사 쌍 목록 */
+declare function supportedJosaPairs(): string[];
+
+/**
+ * 숫자 → 한글 수사 변환
+ * Number to Korean words
+ */
+/**
+ * 정수를 한글 수사로 변환
+ * @example numberToKorean(0)         // '영'
+ * @example numberToKorean(1004)      // '천사'
+ * @example numberToKorean(123456789) // '일억이천삼백사십오만육천칠백팔십구'
+ */
+declare function numberToKorean(num: number): string;
+/**
+ * 금액을 한글로 변환 (원 단위)
+ * @example formatWon(50000) // '오만원'
+ * @example formatWon(1234567) // '백이십삼만사천오백육십칠원'
+ */
+declare function formatWon(amount: number): string;
+
+/**
+ * 한국어 텍스트 개인정보(PII) 탐지 및 마스킹
+ * 프롬프트를 LLM API로 별내기 전 전처리 용도로 설계
+ *
+ * Korean PII detection & masking — designed for preprocessing
+ * prompts before sending them to LLM APIs
+ */
+type PIIType = 'rrn' | 'phone' | 'email' | 'card' | 'driverLicense' | 'account';
+interface PIIMatch {
+    type: PIIType;
+    value: string;
+    start: number;
+    end: number;
+}
+interface MaskPIIOptions {
+    /** 마스킹할 PII 유형 (기본: rrn, phone, email, card, driverLicense) */
+    types?: PIIType[];
+    /** 마스킹 문자 (기본: '*') */
+    maskChar?: string;
+    /** 마지막 N글자는 남겨두기 (기본: 0 = 전부 마스킹) */
+    keepLast?: number;
+}
+/**
+ * 텍스트에서 개인정보 패턴 탐지
+ * @example detectPII('연락처 010-1234-5678')
+ * // [{ type: 'phone', value: '010-1234-5678', start: 4, end: 17 }]
+ */
+declare function detectPII(text: string, types?: PIIType[]): PIIMatch[];
+/**
+ * 텍스트 내 개인정보를 마스킹 (구분자 -, 공백은 유지)
+ * @example maskPII('연락처 010-1234-5678')
+ * // '연락처 ***-****-****'
+ * @example maskPII('카드 1234-5678-9012-3456', { keepLast: 4 })
+ * // '카드 ****-****-****-3456'
+ */
+declare function maskPII(text: string, options?: MaskPIIOptions): string;
+/**
+ * 한국어 이름 마스킹
+ * @example maskName('김철수') // '김*수'
+ * @example maskName('홍길')   // '홍*'
+ * @example maskName('남궁민수') // '남**수'
+ */
+declare function maskName(name: string, maskChar?: string): string;
+
+/**
+ * 한국 각종 번호 유효성 검증
+ * Validators for Korean identification numbers
+ */
+/**
+ * 주민등록번호 유효성 검증 (체크섬 포함)
+ * @example isValidRRN('900101-1******') // 체크섬이 맞으면 true
+ */
+declare function isValidRRN(input: string): boolean;
+/**
+ * 사업자등록번호 유효성 검증 (체크섬 포함)
+ * @example isValidBusinessNumber('123-45-67890')
+ */
+declare function isValidBusinessNumber(input: string): boolean;
+/**
+ * 한국 전화번호 형식 검증 (휴대폰 + 일반전화)
+ * @example isValidPhoneNumber('010-1234-5678') // true
+ * @example isValidPhoneNumber('02-123-4567')   // true
+ */
+declare function isValidPhoneNumber(input: string): boolean;
+
+export { CHOSEONG_LIST, type DecomposedSyllable, JONGSEONG_LIST, JUNGSEONG_LIST, type MaskPIIOptions, type PIIMatch, type PIIType, assemble, compose, decompose, detectPII, disassemble, formatWon, hasBatchim, isHangulSyllable, isValidBusinessNumber, isValidPhoneNumber, isValidRRN, josa, maskName, maskPII, numberToKorean, pickJosa, supportedJosaPairs };

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 한글 음절 분해/조합 유틸리티
+ * Hangul syllable decomposition & composition
+ */
+declare const CHOSEONG_LIST: readonly ["ㄱ", "ㄲ", "ㄴ", "ㄷ", "ㄸ", "ㄹ", "ㅁ", "ㅂ", "ㅃ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅉ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+declare const JUNGSEONG_LIST: readonly ["ㅏ", "ㅐ", "ㅑ", "ㅒ", "ㅓ", "ㅔ", "ㅕ", "ㅖ", "ㅗ", "ㅘ", "ㅙ", "ㅚ", "ㅛ", "ㅜ", "ㅝ", "ㅞ", "ㅟ", "ㅠ", "ㅡ", "ㅢ", "ㅣ"];
+declare const JONGSEONG_LIST: readonly ["", "ㄱ", "ㄲ", "ㄳ", "ㄴ", "ㄵ", "ㄶ", "ㄷ", "ㄹ", "ㄺ", "ㄻ", "ㄼ", "ㄽ", "ㄾ", "ㄿ", "ㅀ", "ㅁ", "ㅂ", "ㅄ", "ㅅ", "ㅆ", "ㅇ", "ㅈ", "ㅊ", "ㅋ", "ㅌ", "ㅍ", "ㅎ"];
+interface DecomposedSyllable {
+    choseong: string;
+    jungseong: string;
+    jongseong: string | null;
+}
+/** 한글 음절(가~힣)인지 확인 */
+declare function isHangulSyllable(char: string): boolean;
+/** 음절을 초성/중성/종성으로 분해 */
+declare function decompose(char: string): DecomposedSyllable;
+/** 초성/중성(/종성)을 조합해 음절 생성 */
+declare function compose(choseong: string, jungseong: string, jongseong?: string | null): string;
+/** 문자가 받침(종성)으로 끝나는지 확인 */
+declare function hasBatchim(char: string): boolean;
+/**
+ * 문자열을 자모 단위로 분해
+ * @example disassemble('값') // 'ㄱㅏㅂㅅ'
+ * @example disassemble('한글') // 'ㅎㅏㄴㄱㅡㄹ'
+ */
+declare function disassemble(text: string): string;
+/**
+ * 자모 나열을 음절로 조합 (disassemble의 역함수)
+ * @example assemble('ㄱㅏㅂㅅ') // '값'
+ * @example assemble('ㄱㅏㅂㅅㅏ') // '갑사'
+ */
+declare function assemble(jamo: string): string;
+
+/**
+ * 한국어 조사(은/는, 이/가, 을/를...) 자동 선택
+ * Automatic Korean particle (josa) picker
+ */
+type JosaPair = readonly [string, string];
+/** 지원하는 조사 쌍: [받침 있음, 받침 없음] */
+declare const JOSA_PAIRS: Record<string, JosaPair>;
+/**
+ * 단어에 맞는 조사를 골라 반환
+ * @example pickJosa('사과', '은/는') // '는'
+ * @example pickJosa('책', '은/는')   // '은'
+ * @example pickJosa('서울', '으로/로') // '로'
+ */
+declare function pickJosa(word: string, pair: keyof typeof JOSA_PAIRS | string): string;
+/**
+ * 단어 뒤에 올바른 조사를 붙여 반환
+ * @example josa('사과', '을/를')  // '사과를'
+ * @example josa('부산', '으로/로') // '부산으로'
+ * @example josa('3', '이/가')     // '3이' (숫자는 발음 기준)
+ */
+declare function josa(word: string | number, pair: keyof typeof JOSA_PAIRS | string): string;
+/** 지원하는 조사 쌍 목록 */
+declare function supportedJosaPairs(): string[];
+
+/**
+ * 숫자 → 한글 수사 변환
+ * Number to Korean words
+ */
+/**
+ * 정수를 한글 수사로 변환
+ * @example numberToKorean(0)         // '영'
+ * @example numberToKorean(1004)      // '천사'
+ * @example numberToKorean(123456789) // '일억이천삼백사십오만육천칠백팔십구'
+ */
+declare function numberToKorean(num: number): string;
+/**
+ * 금액을 한글로 변환 (원 단위)
+ * @example formatWon(50000) // '오만원'
+ * @example formatWon(1234567) // '백이십삼만사천오백육십칠원'
+ */
+declare function formatWon(amount: number): string;
+
+/**
+ * 한국어 텍스트 개인정보(PII) 탐지 및 마스킹
+ * 프롬프트를 LLM API로 별내기 전 전처리 용도로 설계
+ *
+ * Korean PII detection & masking — designed for preprocessing
+ * prompts before sending them to LLM APIs
+ */
+type PIIType = 'rrn' | 'phone' | 'email' | 'card' | 'driverLicense' | 'account';
+interface PIIMatch {
+    type: PIIType;
+    value: string;
+    start: number;
+    end: number;
+}
+interface MaskPIIOptions {
+    /** 마스킹할 PII 유형 (기본: rrn, phone, email, card, driverLicense) */
+    types?: PIIType[];
+    /** 마스킹 문자 (기본: '*') */
+    maskChar?: string;
+    /** 마지막 N글자는 남겨두기 (기본: 0 = 전부 마스킹) */
+    keepLast?: number;
+}
+/**
+ * 텍스트에서 개인정보 패턴 탐지
+ * @example detectPII('연락처 010-1234-5678')
+ * // [{ type: 'phone', value: '010-1234-5678', start: 4, end: 17 }]
+ */
+declare function detectPII(text: string, types?: PIIType[]): PIIMatch[];
+/**
+ * 텍스트 내 개인정보를 마스킹 (구분자 -, 공백은 유지)
+ * @example maskPII('연락처 010-1234-5678')
+ * // '연락처 ***-****-****'
+ * @example maskPII('카드 1234-5678-9012-3456', { keepLast: 4 })
+ * // '카드 ****-****-****-3456'
+ */
+declare function maskPII(text: string, options?: MaskPIIOptions): string;
+/**
+ * 한국어 이름 마스킹
+ * @example maskName('김철수') // '김*수'
+ * @example maskName('홍길')   // '홍*'
+ * @example maskName('남궁민수') // '남**수'
+ */
+declare function maskName(name: string, maskChar?: string): string;
+
+/**
+ * 한국 각종 번호 유효성 검증
+ * Validators for Korean identification numbers
+ */
+/**
+ * 주민등록번호 유효성 검증 (체크섬 포함)
+ * @example isValidRRN('900101-1******') // 체크섬이 맞으면 true
+ */
+declare function isValidRRN(input: string): boolean;
+/**
+ * 사업자등록번호 유효성 검증 (체크섬 포함)
+ * @example isValidBusinessNumber('123-45-67890')
+ */
+declare function isValidBusinessNumber(input: string): boolean;
+/**
+ * 한국 전화번호 형식 검증 (휴대폰 + 일반전화)
+ * @example isValidPhoneNumber('010-1234-5678') // true
+ * @example isValidPhoneNumber('02-123-4567')   // true
+ */
+declare function isValidPhoneNumber(input: string): boolean;
+
+export { CHOSEONG_LIST, type DecomposedSyllable, JONGSEONG_LIST, JUNGSEONG_LIST, type MaskPIIOptions, type PIIMatch, type PIIType, assemble, compose, decompose, detectPII, disassemble, formatWon, hasBatchim, isHangulSyllable, isValidBusinessNumber, isValidPhoneNumber, isValidRRN, josa, maskName, maskPII, numberToKorean, pickJosa, supportedJosaPairs };