dayjs-utils

설치

pnpm add @cbcruk/dayjs-utils dayjs

TimeRange에 기준 시각을 넘기려면 Dayjs 객체가 필요하므로 dayjs도 함께 설치합니다. 각 모듈은 필요한 플러그인을 직접 dayjs.extend로 등록하므로, 패키지를 import하면 전역 dayjs에 isBetween(TimeRange), customParseFormat(TimeRange, DateNavigator) 플러그인이 등록됩니다.

사용법

`TimeRange`

매일 반복되는 운영 시간·이벤트 시간대처럼 날짜와 무관한 시간대를 다룹니다. 시각은 기준 시각(now)의 날짜에 붙여 비교합니다.

import dayjs from 'dayjs'
import { TimeRange } from '@cbcruk/dayjs-utils'

const range = new TimeRange('09:00:00', '18:00:00')

range.isActive() // 지금이 09:00:00 이상 18:00:00 미만인지
range.getRemainingTime() // { HH: '02', mm: '30', ss: '00' }

const noon = dayjs().hour(12).minute(0).second(0)
range.isActive(noon) // true
range.isActive(dayjs('2020-01-01T12:00:00')) // true — 넘긴 날짜 기준으로 판정

// endTime이 startTime보다 이르면 자정을 넘는 구간
const night = new TimeRange('22:00:00', '02:00:00')
night.isActive(dayjs('2025-05-07T01:00:00')) // true
night.getRemainingTime(dayjs('2025-05-06T23:30:00')) // { HH: '02', mm: '30', ss: '00' }

TimeRange.parseTime('08:30') // { HH: '08', mm: '30', ss: '00' }
TimeRange.now() // '14:05:09'

`DateNavigator`

import { DateNavigator } from '@cbcruk/dayjs-utils'

const nav = new DateNavigator('2025-05-06')

nav.previous() // '2025-05-05'
nav.next() // '2025-05-06'
nav.set('2025-12-25')
nav.get() // '2025-12-25'

const dotted = new DateNavigator('06.05.2025', 'DD.MM.YYYY')
dotted.next() // '07.05.2025'

new DateNavigator('2025-02-30') // Error: Invalid date string

API

`TimeRange`

`new TimeRange(startTime, endTime)`

두 인자 모두 HH:mm:ss 문자열입니다. 생성 시점에는 검증하지 않습니다.

endTime이 startTime보다 이르면(예: '22:00:00' ~ '02:00:00') 자정을 넘어 다음 날까지 이어지는 구간으로 봅니다. 두 값이 같으면 빈 구간입니다.

`range.isActive(now?)`

now(기본 dayjs())가 [startTime, endTime) 구간에 있으면 true를 반환합니다. 시작은 포함, 끝은 제외합니다. 두 시각은 now와 같은 날짜에 붙여 비교하며, 자정을 넘는 구간은 startTime 이후이거나 endTime 이전이면 true입니다. 시각 형식이 HH:mm:ss(strict)가 아니면 예외 대신 false를 반환합니다.

`range.getRemainingTime(now?)`

now부터 endTime까지 남은 시간을 TimeParts로 반환합니다.

endTime은 now와 같은 날짜 기준입니다. 자정을 넘는 구간에서 now가 그날의 endTime 이후라면 다음 날 endTime까지 계산합니다.
이미 지났으면 { HH: '00', mm: '00', ss: '00' }
startTime 또는 endTime 형식이 잘못됐으면 null
시작 전이어도 startTime이 아니라 endTime까지의 시간을 계산합니다.

`TimeRange.parseTime(time)`

:로 나눠 TimeParts를 반환하고, 없는 단위는 '00'으로 채웁니다. 형식 검증이나 자릿수 보정은 하지 않습니다.

`TimeRange.now()`

현재 시각을 HH:mm:ss 문자열로 반환합니다.

`TimeParts`

type TimeParts = { HH: string; mm: string; ss: string }

`DateNavigator`

`new DateNavigator(initialDate, format?)`

initialDate를 format(기본 'YYYY-MM-DD')으로 strict 파싱해 현재 날짜로 삼습니다. 모든 반환값도 같은 포맷 문자열입니다. 형식이 다르거나('2025-5-6') 존재하지 않는 날짜('2025-02-30')면 Error를 던집니다.

메서드	반환	설명
`next()`	`string`	하루 뒤로 이동 후 날짜 반환
`previous()`	`string`	하루 전으로 이동 후 날짜 반환
`set(date)`	`void`	현재 날짜를 `date`로 교체
`get()`	`string`	현재 날짜 반환
`toString()`	`string`	`get()`과 동일

인스턴스 내부 상태를 직접 바꾸는(mutable) 커서입니다. set(date)도 생성자와 같이 strict 파싱하며, 잘못된 값이면 Error를 던지고 현재 날짜를 유지합니다.

제약

TimeRange는 날짜 없는 시각만 다루므로 여러 날에 걸친(24시간 이상) 구간은 표현할 수 없습니다.
DateNavigator의 format은 dayjs customParseFormat 토큰을 따릅니다. 시각 토큰을 포함한 포맷이라도 이동 단위는 항상 하루입니다.

On this page