swingmobility-utils/dist/index.d.mts

Swing 공통 유틸리티 함수

/**
 * 이름 마스킹 함수
 * 규칙:
 * - 1자리: 그대로 출력
 * - 2자리: 첫 글자 + '*'
 * - 3자리: 첫 글자 + '*' + 마지막 글자
 * - 4자리 이상: 뒷 2자리를 '**'로 대체
 */
declare const maskName: (name?: string | null) => string;
/**
 * 생년월일 마스킹 함수
 * 규칙:
 * - "YYYYMMDD" 형식: YYYY + '**' + DD
 * - "YYYY-MM-DD" 형식: YYYY-**-DD
 */
declare const maskBirthDate: (birth?: string | null) => string;
/**
 * 전화번호 마스킹 함수
 * @param phone 전화번호(문자열 또는 숫자)
 * @param hasHyphen 하이픈 추가 여부 (기본값: true)
 * @param showErrorPattern 잘못된 전화번호 패턴 반환 여부 (기본값: true)
 * @returns 마스킹된 전화번호 또는 오류 패턴
 */
declare const maskPhone: (phone?: string | number | null, hasHyphen?: boolean, showErrorPattern?: boolean) => string;
/**
 * 이메일 마스킹 함수
 * 규칙: 로컬 파트('@' 앞)에서 앞 2자리는 그대로, 나머지를 '*'로 대체 (도메인은 그대로)
 * 예: "example@gmail.com" → "ex*****@gmail.com"
 */
declare const maskEmail: (email?: string | null) => string;
/**
 * 주소 마스킹 함수
 * 규칙: 시/군/구까지만 표기하고, 그 이하(동, 도로명, 번지 등)는 길이에 맞춰 '*'로 마스킹 처리
 * 예:
 *  - "서울특별시 구로구 구로로111길 111" → "서울특별시 구로구 ****** ***"
 *  - "경기도 용인시 용인구 용용용동 123" → "경기도 용인시 용인구 **** ***"
 */
declare const maskToSigungu: (address?: string | null) => string;
/**
 * 주민등록번호 마스킹 함수
 * 규칙: 13자리 주민등록번호에서, 생년월일인 6자리와 성별 구분코드인 1자리가 그대로, 나머지 7자리는 '*'로 마스킹
 * -가 빠진 경우: "1234561234567" → "123456-1******"
 * 예: "123456-1234567" → "123456-1******"
 */
declare const maskRRN: (rrn?: string | null) => string;
/**
 * 계좌번호 마스킹 함수
 * 규칙: 첫 4자리 끝 4자리가 그대로, 나머지 가운데 자리는는 '*'로 마스킹
 */
declare const maskAccount: (account?: string | null) => string;

/**
 * 통화 관련 포맷팅 유틸리티 함수
 */
/**
 * 금액을 한국어 통화 형식으로 포맷팅합니다.
 * @param amount 포맷팅할 금액
 * @returns 포맷팅된 금액 문자열 (예: "₩10,000")
 */
declare function formatCurrency(amount: number): string;

/**
 * 숫자 포맷팅 관련 유틸리티 함수
 */
/**
 * 숫자에 천 단위 구분 기호를 추가합니다.
 * @param num 포맷팅할 숫자
 * @returns 천 단위 구분 기호가 포함된 문자열 (예: "1,234,567")
 */
declare function formatNumber(num: number): string;

/**
 * 날짜 및 요일 관련 유틸리티 함수
 */
/**
 * 요일 타입 정의 (숫자로 0-6, 일요일부터 시작)
 */
type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
/**
 * 요일 형식 타입
 */
type DayFormat = 'ko-short' | 'ko-long' | 'en-short' | 'en-short-caps' | 'en-long' | 'en-long-caps';
/**
 * Date 객체에서 요일을 추출하여 원하는 형식으로 반환합니다.
 *
 * @param date 날짜 객체
 * @param format 요일 형식 ('ko-short', 'ko-long', 'en-short', 'en-short-caps', 'en-long', 'en-long-caps')
 * @returns 지정된 형식의 요일 문자열
 *
 * @example
 * // 오늘이 월요일인 경우
 * getDayOfWeek(new Date(), 'ko-short') // '월'
 * getDayOfWeek(new Date(), 'ko-long') // '월요일'
 * getDayOfWeek(new Date(), 'en-short') // 'mon'
 */
declare function getDayOfWeek(date: Date, format?: DayFormat): string;
/**
 * 특정 요일 문자열을 다른 형식으로 변환합니다.
 *
 * @param day 변환할 요일 문자열 (예: '월', '월요일', 'mon', 'MON', 'monday' 등)
 * @param targetFormat 변환할 대상 형식
 * @returns 변환된 요일 문자열, 일치하는 요일이 없으면 null 반환
 *
 * @example
 * convertDayFormat('월', 'en-short') // 'mon'
 * convertDayFormat('monday', 'ko-long') // '월요일'
 */
declare function convertDayFormat(day: string, targetFormat: DayFormat): string | null;
/**
 * 요일 문자열로부터 Date 객체의 요일 인덱스(0-6)를 반환합니다.
 *
 * @param day 요일 문자열 (모든 형식 가능)
 * @returns 요일 인덱스 (0: 일요일, 1: 월요일, ...), 일치하는 요일이 없으면 null 반환
 *
 * @example
 * getDayIndex('월') // 1
 * getDayIndex('Monday') // 1
 */
declare function getDayIndex(day: string): DayOfWeek | null;
/**
 * 특정 날짜의 해당 주의 모든 요일 날짜를 배열로 반환합니다.
 *
 * @param date 기준 날짜
 * @param startFromSunday 일요일부터 시작할지 여부 (기본값: true)
 * @returns 해당 주의 날짜 배열
 *
 * @example
 * // 2025-04-24 (목요일)을 기준으로 하는 경우
 * getWeekDays(new Date('2025-04-24'))
 * // [2025-04-20(일), 2025-04-21(월), ..., 2025-04-26(토)]
 */
declare function getWeekDays(date: Date, startFromSunday?: boolean): Date[];
/**
 * 두 날짜가 같은 요일인지 확인합니다.
 *
 * @param date1 첫번째 날짜
 * @param date2 두번째 날짜
 * @returns 같은 요일이면 true, 아니면 false
 *
 * @example
 * isSameDay(new Date('2025-04-21'), new Date('2025-04-28')) // true (둘 다 월요일)
 */
declare function isSameDayOfWeek(date1: Date, date2: Date): boolean;
/**
 * 특정 요일에 해당하는 가장 가까운 날짜를 찾습니다.
 *
 * @param targetDay 찾을 요일 (요일 문자열 - 모든 형식 가능)
 * @param baseDate 기준 날짜 (기본값: 현재 날짜)
 * @param searchForward 앞으로 검색할지 여부 (true: 미래 방향, false: 과거 방향)
 * @returns 가장 가까운 해당 요일의 날짜
 *
 * @example
 * // 오늘이 목요일인 경우
 * getNextDayOfWeek('월') // 다음 월요일
 * getNextDayOfWeek('월', undefined, false) // 지난 월요일
 */
declare function getNextDayOfWeek(targetDay: string, baseDate?: Date, searchForward?: boolean): Date | null;
/**
 * 특정 날짜가 주말인지 확인합니다.
 *
 * @param date 확인할 날짜
 * @returns 주말(토요일 또는 일요일)이면 true, 아니면 false
 *
 * @example
 * isWeekend(new Date('2025-04-26')) // true (토요일)
 */
declare function isWeekend(date: Date): boolean;
/**
 * 특정 날짜가 평일인지 확인합니다.
 *
 * @param date 확인할 날짜
 * @returns 평일(월~금)이면 true, 아니면 false
 *
 * @example
 * isWeekday(new Date('2025-04-24')) // true (목요일)
 */
declare function isWeekday(date: Date): boolean;
/**
 * 한국 표준시(KST)를 기준으로 날짜 문자열을 반환합니다.
 * 사용자의 로컬 시간대와 관계없이 항상 KST 기준으로 계산합니다.
 *
 * @returns "YYYY-MM-DD" 형태의 KST 기준 날짜 문자열
 *
 * @example
 * getKstDateString() // "2025-04-24"
 */
declare function getKstDateString(): string;
/**
 * 날짜가 선택 불가능한 날짜인지 반환합니다.
 *
 * @param date 선택된 Date 객체
 * @param startDateStr 시작일 문자열 ("YYYY-MM-DD")
 * @param endDateStr 종료일 문자열 ("YYYY-MM-DD")
 * @param today 기준 날짜 (default: new Date())
 * @returns 불가능한 날짜면 true, 가능하면 false
 *
 * @example
 * isDateDisabled(new Date('2025-04-30'), '2025-04-24', '2025-04-28') // true (범위 밖)
 */
declare function isDateDisabled(date: Date, startDateStr: string, endDateStr: string, today?: Date): boolean;
/**
 * 기본으로 열릴 Date 객체를 반환합니다.
 *
 * @param startDateStr 시작일 문자열 ("YYYY-MM-DD")
 * @param endDateStr 종료일 문자열 ("YYYY-MM-DD")
 * @param today 기준 날짜 (default: new Date())
 * @returns 기본으로 표시할 달(월)의 Date 객체
 *
 * @example
 * getDefaultOpenMonth('2025-03-15', '2025-04-28') // 2025-03-15 또는 today 에 따라 적절한 날짜
 */
declare function getDefaultOpenMonth(startDateStr: string, endDateStr: string, today?: Date): Date;
/**
 * 주차를 한글로 변환하여 반환합니다.
 *
 * @param date Date 객체
 * @returns "YYYY년 MM월 N주차" 형태의 문자열
 *
 * @example
 * getKoreanWeekOfMonth(new Date('2025-04-24')) // "2025년 4월 4주차"
 */
declare function getKoreanWeekOfMonth(date: Date): string;
/**
 * 날짜 포맷팅을 안전하게 처리하는 함수
 * 유효하지 않은 날짜나 오류 발생 시 '-'를 반환합니다.
 *
 * @param dateValue 날짜 값 (문자열, 타임스태프, undefined 등)
 * @param formatString 포맷 문자열 (yyyy: 년, MM: 월(2자리), dd: 일(2자리) 등)
 * @returns 포맷팅된 날짜 문자열 또는 '-'
 *
 * @example
 * formatSafeDate('2025-04-24', 'yyyy년 MM월 dd일') // "2025년 04월 24일"
 * formatSafeDate(1714022400, 'yyyy/MM/dd') // "2024/04/25"
 * formatSafeDate(undefined, 'yyyy/MM/dd') // "-"
 */
declare function formatSafeDate(dateValue: string | number | undefined, formatString: string): string;
/**
 * Date 객체를 Unix Epoch 시간(초 단위)으로 변환합니다.
 *
 * @param date 변환할 Date 객체
 * @returns 초 단위의 Unix 타임스킬프
 *
 * @example
 * dateToUnixEpoch(new Date('2025-04-24T00:00:00Z')) // 1745222400
 */
declare function dateToUnixEpoch(date: Date): number;
/**
 * Unix Epoch 시간(초 단위)을 밀리초 단위로 변환합니다.
 *
 * @param epochSeconds 초 단위 Unix 타임스킬프
 * @returns 밀리초 단위 타임스킬프
 *
 * @example
 * unixEpochToMilliseconds(1745222400) // 1745222400000
 */
declare function unixEpochToMilliseconds(epochSeconds: number): number;
/**
 * Unix Epoch 시간(초 단위)을 Date 객체로 변환합니다.
 *
 * @param epochSeconds 초 단위 Unix 타임스킬프
 * @returns 변환된 Date 객체
 *
 * @example
 * unixEpochToDate(1745222400) // new Date('2025-04-24T00:00:00Z')
 */
declare function unixEpochToDate(epochSeconds: number): Date;
/**
 * Epoch 밀리초를 Date 객체로 변환합니다.
 *
 * @param epochMilliseconds 밀리초 단위 타임스킬프
 * @returns 변환된 Date 객체
 *
 * @example
 * epochMillisecondsToDate(1745222400000) // new Date('2025-04-24T00:00:00Z')
 */
declare function epochMillisecondsToDate(epochMilliseconds: number): Date;
/**
 * Epoch 밀리초를 지정된 형식의 문자열로 포맷팅합니다.
 *
 * @param epochMilliseconds 밀리초 단위 타임스킬프
 * @param format 포맷 문자열 (기본값: 'yyyy-MM-dd')
 * @returns 포맷팅된 날짜 문자열
 *
 * @example
 * formatEpochMilliseconds(1745222400000) // "2025-04-24"
 * formatEpochMilliseconds(1745222400000, 'yyyy년 MM월 dd일') // "2025년 04월 24일"
 */
declare function formatEpochMilliseconds(epochMilliseconds: number, format?: string): string;

/**
 * 유효성 검사 관련 유틸리티 함수
 */
/**
 * 한국 주민등록번호 형식이 유효한지 검사합니다.
 * @param rrn 검사할 주민등록번호 (하이픈 포함 또는 미포함)
 * @returns 유효 여부
 */
declare function isValidRRN(rrn: string): boolean;
/**
 * 한국 휴대폰 번호 형식이 유효한지 검사합니다.
 * @param phone 검사할 휴대폰 번호 (하이픈 포함 또는 미포함)
 * @returns 유효 여부
 */
declare function isValidPhoneNumber(phone: string): boolean;
/**
 * 이메일 주소 형식이 유효한지 검사합니다.
 * @param email 검사할 이메일 주소
 * @returns 유효 여부
 */
declare function isValidEmail(email: string): boolean;

/**
 * 배열 관련 유틸리티 함수
 */
/**
 * 배열에서 중복 요소를 제거합니다.
 */
declare function removeDuplicates<T>(array: T[]): T[];
/**
 * 배열을 지정된 크기의 청크로 분할합니다.
 */
declare function chunk<T>(array: T[], size: number): T[][];
/**
 * 배열을 지정된 프로퍼티를 기준으로 정렬합니다.
 */
declare function sortByProperty<T>(array: T[], property: keyof T): T[];

export { type DayFormat, type DayOfWeek, chunk, convertDayFormat, dateToUnixEpoch, epochMillisecondsToDate, formatCurrency, formatEpochMilliseconds, formatNumber, formatSafeDate, getDayIndex, getDayOfWeek, getDefaultOpenMonth, getKoreanWeekOfMonth, getKstDateString, getNextDayOfWeek, getWeekDays, isDateDisabled, isSameDayOfWeek, isValidEmail, isValidPhoneNumber, isValidRRN, isWeekday, isWeekend, maskAccount, maskBirthDate, maskEmail, maskName, maskPhone, maskRRN, maskToSigungu, removeDuplicates, sortByProperty, unixEpochToDate, unixEpochToMilliseconds };