DateUtils는 날짜 포맷 변환, 날짜 계산, 요일 조회, 시간 포맷 등 프로젝트에서 자주 사용하는 날짜 기능을 제공합니다.

다양한 입력 형식을 지원하며 일관된 날짜 처리를 통해 개발 생산성을 높일 수 있습니다.

coForward DateUtils는 날짜 값을 Date 객체로 파싱하고, 날짜·시간·요일을 화면 표시용 문자열로 변환하는 사내 공통 JavaScript 유틸입니다.

실제 클래스명은 DateFormat이며, dateUtils.js에서 기본 export로 제공됩니다.

이 문서에서 다루는 기능

필수 준비물

• dateUtils.js 파일
• ES Module을 지원하는 브라우저 또는 프로젝트 번들러

2-1. 클래스 불러오기

페이지용 JavaScript 파일에서 클래스를 import합니다.

// date-page.js
import DateFormat from '/path/to/dateUtils.js';

2-2. HTML 예시

<p>오늘 날짜: <span id="todayText"></span></p>
<p>현재 시간: <span id="timeText"></span></p>

<script type="module" src="/js/date-page.js"></script>

DateFormat은 생성자에 날짜 값을 전달해 사용합니다.

import DateFormat from '/path/to/dateUtils.js';

const date = new DateFormat('2026-07-13');

console.log(date.format('YYYY-MM-DD'));
console.log(date.dayOfWeek(false, 'ko'));

기본 적용 순서

클래스 import
↓
인스턴스 생성
↓
포맷 또는 계산 메서드 호출
↓
화면에 결과 반영

생성자에 사용할 수 있는 값

정적 생성 메서드

const date = DateFormat.of('2026-07-13');

DateFormat.of(value)는 new DateFormat(value)와 같은 방식으로 새 인스턴스를 반환합니다.

기본 날짜 문자열

const date = new DateFormat('2026-07-13');

console.log(date.formatYmd('2026-07-13'));      // 20260713
console.log(date.formatYmd('2026-07-13', '-')); // 2026-07-13
console.log(date.formatYmd('20260713', '.'));   // 2026.07.13

formatYmd(value, gubun)은 전달한 날짜 값을 YYYYMMDD 또는 구분자가 포함된 형식으로 반환합니다.

사용자 지정 포맷

const date = new DateFormat('2026-07-13T09:05:07');

console.log(date.format());                         // 2026-07-13
console.log(date.format('YYYY.MM.DD'));             // 2026.07.13
console.log(date.format('yy/m/d'));                 // 26/7/13
console.log(date.format('YYYY-MM-DD hh:mm:ss'));    // 2026-07-13 09:05:07
console.log(date.format('YYYY-MM-DD W', 'ko'));     // 2026-07-13 월
console.log(date.format('YYYY-MM-DD W', 'en'));     // 2026-07-13 Mon

포맷 토큰

현재 인스턴스 시간 표시

const date = new DateFormat('2026-07-13T09:05:07');

console.log(date.getTime());        // 09:05:07
console.log(date.getTime(null, false)); // 09:05

시간 문자열 변환

const date = new DateFormat();

console.log(date.getTime('090507'));       // 09:05:07
console.log(date.getTime('0905'));         // 09:05:00
console.log(date.getTime('090507', false)); // 09:05

getTime(value, includeSeconds)는 HHmmss 또는 HHmm 문자열을 HH:mm:ss 또는 HH:mm으로 변환합니다.

일 단위 이동

const date = new DateFormat('2026-07-13');

console.log(date.getShiftedDate(1, '2026-07-13', '-'));  // 2026-07-14
console.log(date.getShiftedDate(-7, '2026-07-13', '-')); // 2026-07-06

getShiftedDate(offset, dateStr, gubun)은 기준일에서 offset일만큼 이동한 날짜를 반환합니다.

월 단위 이동

const date = new DateFormat('2026-07-13');

console.log(date.getAddMonths(1));           // 2026-08-13
console.log(date.getAddMonths(1, 'last'));   // 2026-09-30

getAddMonths(month, mode, dateStr, gubun)은 인스턴스 기준일에서 month개월 이동한 날짜를 반환합니다.

const nextMonth = new DateFormat('2026-07-13').getAddMonths(1);
const twoMonthsLater = new DateFormat('2026-07-13').getAddMonths(2);

날짜 차이

const date = new DateFormat('2026-07-13');

console.log(date.getDateDiff('2026-07-10')); // 3

getDateDiff(other)는 인스턴스 날짜에서 other를 뺀 일 수를 반환합니다.

const date = new DateFormat('2026-07-13');

console.log(date.dayOfWeek(false, 'ko')); // 월
console.log(date.dayOfWeek(false, 'en')); // Mon
console.log(date.dayOfWeek('2026-07-14', 'ko')); // 화

dayOfWeek(dateStr, lang)은 지정한 날짜의 요일을 반환합니다. dateStr이 없으면 인스턴스 날짜를 사용합니다.

Date 객체 반환

const date = new DateFormat('2026-07-13');
const rawDate = date.toDate();

console.log(rawDate instanceof Date); // true

toDate()는 내부 Date 객체를 반환합니다.

ISO 문자열 반환

const date = new DateFormat('2026-07-13T09:05:07');

console.log(date.toString());

toString()은 내부 Date 객체의 toISOString() 결과를 반환합니다.

Date 객체 여부 확인

console.log(DateFormat.isDate(new Date())); // true
console.log(DateFormat.isDate('2026-07-13')); // false

DateFormat.isDate(value)는 값이 Date 객체인지 확인합니다.

아래 예제는 오늘 날짜, 요일, 현재 시간, 7일 뒤 날짜를 화면에 표시합니다.

HTML

<p>오늘: <span id="todayText"></span></p>
<p>요일: <span id="weekText"></span></p>
<p>현재 시간: <span id="timeText"></span></p>
<p>7일 뒤: <span id="afterSevenDaysText"></span></p>

<script type="module" src="/js/date-page.js"></script>

JavaScript

import DateFormat from '/path/to/dateUtils.js';

const todayText = document.getElementById('todayText');
const weekText = document.getElementById('weekText');
const timeText = document.getElementById('timeText');
const afterSevenDaysText = document.getElementById('afterSevenDaysText');

if (!todayText || !weekText || !timeText || !afterSevenDaysText) {
    throw new Error('날짜 표시 요소를 찾을 수 없습니다.');
}

const now = new DateFormat();

todayText.textContent = now.format('YYYY-MM-DD');
weekText.textContent = now.dayOfWeek(false, 'ko');
timeText.textContent = now.getTime(null, false);
afterSevenDaysText.textContent = new DateFormat().getShiftedDate(7, null, '-');

날짜 파싱 실패 오류가 발생합니다.

DateFormat은 new Date(value)로 파싱할 수 없는 값이면 오류를 발생시킵니다.

new DateFormat('잘못된 날짜'); // Error: 날짜 파싱 실패

다음 형식을 우선 사용합니다.

• YYYY-MM-DD
• YYYY-MM-DDTHH:mm:ss
• YYYYMMDD
• Date 객체

formatYmd() 결과가 빈 문자열입니다.

formatYmd()는 인자 value가 없으면 빈 문자열을 반환합니다.

const date = new DateFormat('2026-07-13');

console.log(date.formatYmd()); // ''
console.log(date.format());    // 2026-07-13

인스턴스 날짜를 출력하려면 format()을 사용합니다.

월 계산 결과가 예상과 다릅니다.

getAddMonths()는 호출할 때마다 인스턴스 내부 Date 객체를 변경합니다. 같은 기준일로 여러 계산을 해야 하면 새 인스턴스를 사용합니다.

const oneMonth = new DateFormat('2026-07-13').getAddMonths(1);
const twoMonths = new DateFormat('2026-07-13').getAddMonths(2);

getDateDiff() 사용 시 주의사항

안정 사용 기준에서는 두 번째 base 인자를 사용하지 않는 것을 권장합니다.

const date = new DateFormat('2026-07-13');
console.log(date.getDateDiff('2026-07-10'));

UTC 기준 날짜를 확인하십시오.

toString()은 Date.prototype.toISOString()을 사용하므로 UTC 기준 문자열을 반환합니다. 화면 표시용 날짜는 format()을 사용합니다.

주요 생성 방식

주요 정적 메서드

주요 인스턴스 메서드

© team coForward