kr-kit

Practical TypeScript utilities for Korean web and mobile services.

kr-kit helps with common Korean service requirements:

• Korean phone number normalization, formatting, validation, parsing
• Korean business registration number formatting and checksum validation
• KRW formatting and Korean amount string parsing (만, 억, 조, 경)
• Personal data masking helpers
• KST-based date formatting and Korean relative-time formatting
• Business-day / settlement / cutoff utilities for Korean operations

Why kr-kit?

When building Korean services, global teams repeatedly hit local rules:

• Phone formats vary (010, 02, 031, 1577)
• KRW is shown with Korean units (만, 억, 조)
• Inputs often arrive as mixed formats (+82, spaces, hyphens)
• Product UI needs Korean-friendly date and relative-time text
• Operations often need KST cutoff and business-day settlement handling

This package gives you a clean, typed utility layer for those patterns.

Installation

npm install kr-kit

Quick Start

import {
  normalizePhone,
  parsePhone,
  formatBusinessNumber,
  isValidBusinessNumber,
  formatKRW,
  parseKoreanAmount,
  formatKoreanDateTime,
  formatRelativeTimeKO,
  isBusinessDayKST,
  getSettlementDateKST
} from 'kr-kit';

normalizePhone('+82 10-1234-5678');
// '01012345678'

parsePhone('+82 10-1234-5678');
// {
//   input: '+82 10-1234-5678',
//   normalized: '01012345678',
//   formatted: '010-1234-5678',
//   type: 'mobile',
//   isValid: true,
//   e164: '+821012345678'
// }

formatBusinessNumber('2208162517');
// '220-81-62517'

isValidBusinessNumber('2208162517');
// true

formatKRW(1200000);
// '1,200,000원'

parseKoreanAmount('3조 2억 4천만 5백');
// 3000240000500

formatKoreanDateTime('2026-04-22T01:30:00.000Z');
// '2026.04.22 10:30'

formatRelativeTimeKO('2026-04-22T09:10:00.000+09:00', {
  now: '2026-04-22T10:00:00.000+09:00'
});
// '50분 전'

isBusinessDayKST('2026-04-24T10:00:00+09:00');
// true

getSettlementDateKST('2026-04-22T18:00:00+09:00', {
  cutoffHour: 17,
  businessDelayDays: 1
});
// 2026-04-24(KST) as Date

API

Phone

• formatPhone(input: string): string
• normalizePhone(input: string): string
• parsePhone(input: string): ParsePhoneResult
• isValidPhone(input: string): boolean
• getPhoneType(input: string): PhoneType

PhoneType:

• 'mobile' | 'seoul' | 'local' | 'internet' | 'tollFree' | 'business' | 'unknown'

ParsePhoneResult:

interface ParsePhoneResult {
  input: string;
  normalized: string;
  formatted: string;
  type: PhoneType;
  isValid: boolean;
  e164: string | null;
}

Notes:

• International prefixes like +82 / 0082 are normalized to local form (0...).
• Handles both +82 10... and +82 010... mobile inputs as 010....
• Keeps representative numbers (1577-1234, etc.) without forcing a leading 0.
• e164 is null for unsupported or non-E.164-friendly types (for example, business, unknown).

Business Number

• formatBusinessNumber(input: string): string
• isValidBusinessNumber(input: string): boolean

Validation notes:

• Includes checksum validation for Korean business registration number format.
• Rejects all-zero placeholder input (0000000000).

Currency

• formatKRW(amount: number): string
• formatKRWWithSymbol(amount: number): string
• formatKoreanAmountUnit(amount: number): string
• parseKoreanAmount(input: string): number

parseKoreanAmount supports:

• Plain numbers: "12345"
• Korean units: "2천5백만", "1억 2,000만", "3조 2억 4천만 5백"
• Units: 만, 억, 조, 경

Safety:

• Throws if parsed value exceeds Number.MAX_SAFE_INTEGER

Masking

• maskName(name: string): string
• maskPhone(input: string): string
• maskBusinessNumber(input: string): string

Date (KST)

• toKST(input: Date | string | number): Date
• isSameKSTDay(a: Date | string | number, b: Date | string | number): boolean
• formatKoreanDate(input: Date | string | number): string
• formatKoreanDateTime(input: Date | string | number): string
• getKoreanDayOfWeek(input: Date | string | number): string
• formatRelativeTimeKO(input: Date | string | number, options?: RelativeTimeOptions): string

interface RelativeTimeOptions {
  now?: Date | string | number;
}

Time (KST Business Ops)

• isWeekendKST(input: Date | string | number): boolean
• isKoreanPublicHolidayKST(input: Date | string | number, options?: BusinessDayOptions): boolean
• isBusinessDayKST(input: Date | string | number, options?: BusinessDayOptions): boolean
• addBusinessDaysKST(input: Date | string | number, businessDays: number, options?: BusinessDayOptions): Date
• getNextBusinessDayKST(input: Date | string | number, options?: BusinessDayOptions): Date
• isCutoffPassedKST(options: CutoffOptions): boolean
• getSettlementDateKST(now: Date | string | number, options?: SettlementOptions): Date

interface BusinessDayOptions {
  holidays?: Array<Date | string | number>; // extra custom holidays
}

interface CutoffOptions {
  hour: number;
  minute?: number;
  now?: Date | string | number;
}

interface SettlementOptions {
  cutoffHour?: number; // default 17
  cutoffMinute?: number; // default 0
  businessDelayDays?: number; // default 1
  holidays?: Array<Date | string | number>;
}

Built-in fixed holidays:

• 01-01, 03-01, 05-05, 06-06, 08-15, 10-03, 10-09, 12-25

Example Scenarios

1) Normalize and save user phone input

import { normalizePhone, isValidPhone } from 'kr-kit';

const normalized = normalizePhone('+82 10-1234-5678');

if (!isValidPhone(normalized)) {
  throw new Error('Invalid phone number');
}

// Save: 01012345678

2) Parse Korean amount text from admin input

import { parseKoreanAmount } from 'kr-kit';

const value = parseKoreanAmount('1억 2,000만');
// 120000000

3) Display Korean-friendly feed time

import { formatRelativeTimeKO } from 'kr-kit';

formatRelativeTimeKO('2026-04-22T09:10:00.000+09:00', {
  now: '2026-04-22T10:00:00.000+09:00'
});
// '50분 전'

4) Apply settlement cutoff logic

import { getSettlementDateKST } from 'kr-kit';

const settlement = getSettlementDateKST('2026-04-22T18:00:00+09:00', {
  cutoffHour: 17,
  businessDelayDays: 1
});
// -> 2026-04-24(KST)

Development

npm install
npm run test
npm run build

Versioning

This project follows semantic versioning. See CHANGELOG.md for release history.

License

MIT