phone-format-kr

Korean phone number formatter and validator.

한국 전화번호 포맷터 및 유효성 검사 라이브러리입니다.

Installation / 설치

npm install phone-format-kr

yarn add phone-format-kr

pnpm add phone-format-kr

Usage / 사용법

Basic Formatting / 기본 포맷팅

import { formatPhone } from 'phone-format-kr';

formatPhone('01012345678');     // "010-1234-5678"
formatPhone('0212345678');      // "02-1234-5678"
formatPhone('03112345678');     // "031-1234-5678"
formatPhone('15771577');        // "1577-1577"
formatPhone('0801234567');      // "080-123-4567"
formatPhone('07012345678');     // "070-1234-5678"

Validation / 유효성 검사

import { isValidPhone } from 'phone-format-kr';

isValidPhone('01012345678');    // true
isValidPhone('0101234567');     // false (wrong length / 자릿수 오류)
isValidPhone('hello');          // false
isValidPhone('abc01012345678'); // false (contains letters / 문자 포함)

Options / 옵션

import { formatPhone } from 'phone-format-kr';

// Custom delimiter / 구분자 변경
formatPhone('01012345678', { delimiter: '.' });  // "010.1234.5678"
formatPhone('01012345678', { delimiter: ' ' });  // "010 1234 5678"

// Mask middle digits / 중간 자릿수 마스킹
formatPhone('01012345678', { mask: true });      // "010-****-5678"

// Combine options / 옵션 조합
formatPhone('01012345678', { delimiter: '.', mask: true }); // "010.****.5678"

International Format / 국제 번호 형식

import { formatPhone } from 'phone-format-kr';

// +82 format is automatically converted / +82 형식 자동 변환
formatPhone('+82-10-1234-5678');  // "010-1234-5678"
formatPhone('+82-2-1234-5678');   // "02-1234-5678"

Get Phone Type / 전화번호 유형 확인

import { getPhoneType } from 'phone-format-kr';

getPhoneType('01012345678');   // "mobile"
getPhoneType('0212345678');    // "seoul"
getPhoneType('03112345678');   // "regional"
getPhoneType('15771577');      // "representative"
getPhoneType('0801234567');    // "tollFree"
getPhoneType('07012345678');   // "voip"

Parse Phone Number / 전화번호 파싱

import { parsePhone } from 'phone-format-kr';

parsePhone('01012345678');
// { type: 'mobile', parts: ['010', '1234', '5678'] }

parsePhone('0212345678');
// { type: 'seoul', parts: ['02', '1234', '5678'] }

parsePhone('15771577');
// { type: 'representative', parts: ['1577', '1577'] }

API

formatPhone(phone, options?)

Formats a Korean phone number.

한국 전화번호를 포맷팅합니다.

| Parameter | Type | Description | |-----------|------|-------------| | phone | string \| number | Phone number to format / 포맷팅할 전화번호 | | options.delimiter | string | Separator between groups (default: "-") / 구분자 (기본값: "-") | | options.mask | boolean | Mask middle digits (default: false) / 중간 자릿수 마스킹 (기본값: false) |

Returns: string | null - Formatted phone number or null if invalid / 포맷된 전화번호 또는 유효하지 않으면 null

isValidPhone(phone)

Validates a Korean phone number.

한국 전화번호의 유효성을 검사합니다.

| Parameter | Type | Description | |-----------|------|-------------| | phone | string \| number | Phone number to validate / 검사할 전화번호 |

Returns: boolean - true if valid, false otherwise / 유효하면 true, 아니면 false

getPhoneType(phone)

Gets the type of a Korean phone number.

한국 전화번호의 유형을 반환합니다.

| Parameter | Type | Description | |-----------|------|-------------| | phone | string \| number | Phone number / 전화번호 |

Returns: PhoneType - One of: 'mobile', 'seoul', 'regional', 'representative', 'tollFree', 'voip', 'unknown'

parsePhone(phone)

Parses a Korean phone number into components.

한국 전화번호를 구성 요소로 파싱합니다.

| Parameter | Type | Description | |-----------|------|-------------| | phone | string \| number | Phone number / 전화번호 |

Returns: { type: PhoneType, parts: string[] } | null - Parsed result or null if invalid / 파싱 결과 또는 유효하지 않으면 null

Supported Phone Types / 지원하는 전화번호 유형

| Type | Prefix | Format | Example | |------|--------|--------|---------| | Mobile / 휴대폰 | 010, 011, 016, 017, 018, 019 | 3-4-4 | 010-1234-5678 | | Seoul / 서울 | 02 | 2-3-4 or 2-4-4 | 02-123-4567, 02-1234-5678 | | Regional / 지역 | 031-064 | 3-3-4 or 3-4-4 | 031-123-4567, 031-1234-5678 | | VoIP / 인터넷전화 | 070 | 3-4-4 | 070-1234-5678 | | Toll-free / 수신자부담 | 080 | 3-3-4 | 080-123-4567 | | Representative / 대표번호 | 15xx, 16xx, 18xx | 4-4 | 1577-1577 |

Error Handling / 에러 처리

This library does not throw exceptions. Instead, it returns null or false for invalid inputs.

이 라이브러리는 예외를 던지지 않습니다. 대신 유효하지 않은 입력에 대해 null 또는 false를 반환합니다.

// Invalid inputs return null or false / 유효하지 않은 입력은 null 또는 false 반환
formatPhone('');              // null
formatPhone('hello');         // null
formatPhone('abc01012345678'); // null (contains letters / 문자 포함)
formatPhone('0101234567');    // null (wrong length / 자릿수 오류)

isValidPhone('');             // false
isValidPhone('hello');        // false

License

MIT License - see LICENSE for details.

Repository

https://github.com/youngsikkk/phone-format-kr

Contributing / 기여하기

Contributions are welcome! Please feel free to submit a Pull Request.

기여를 환영합니다! Pull Request를 자유롭게 제출해 주세요.