Skip to main content

CalendarDate

Date fields in the database are returned as CalendarDate objects. CalendarDate provides a clean way to deal with dates without worrying about timezone math (though several methods accept an optional zone option when setting the CalendarDate). The name CalendarDate was chosen because Date was already taken by Javascript's time class, and we wanted to emphasize that this class deals with days as the fundamental unit of time.

Creating a CalendarDate​

import { CalendarDate } from '@rvoh/dream'

// relative to today
CalendarDate.today()
CalendarDate.today({ zone: 'America/Chicago' })
CalendarDate.tomorrow()
CalendarDate.yesterday()

// from an ISO string
CalendarDate.fromISO('2024-03-02')
CalendarDate.fromISO('2024-05-05T22:43:36.032-05:00')
CalendarDate.fromISO('2024-05-05T22:43:36.032-08:00', {
  zone: 'America/Chicago',
})

// from an object
CalendarDate.fromObject({ year: 2023, month: 6, day: 16 })

// from a Luxon DateTime
const dateTime = DateTime.fromISO('2024-05-05T17:53:07.397Z')
CalendarDate.fromDateTime(dateTime)

// check validity of the CalendarDate
const calendarDate = CalendarDate.fromISO('2023-02-29')
calendarDate.isValid // false

Converting from a CalendarDate​

const calendarDate = CalendarDate.fromISO('2024-03-02')

// to a string
calendarDate.toISO() // '2024-03-02'
calendarDate.toISODate() // '2024-03-02'
calendarDate.toJSON() // '2024-03-02'
calendarDate.toString() // '2024-03-02'
calendarDate.toLocaleString({ month: 'short', day: 'numeric' }) // 'Mar 2'

// to a Luxon DateTime
calendarDate.toDateTime()

// to a Javascript Date
calendarDate.toJSDate()

// year/month/day parts
calendarDate.year
calendarDate.month
calendarDate.day

Date math​

const calendarDate = CalendarDate.fromISO('2024-03-02')
const otherCalendarDate = CalendarDate.fromISO('2024-02-27')

calendarDate.plus({ days: 4 })
calendarDate.minus({ days: 4 })

CalendarDate.max(calendarDate, otherCalendarDate)
CalendarDate.min(calendarDate, otherCalendarDate)

calendarDate.diff(otherCalendarDate, 'days') // 4
otherCalendarDate.diff(calendarDate, 'days') // -4
calendarDate.diffNow('days')

calendarDate > otherCalendarDate // true
calendarDate < otherCalendarDate // false
calendarDate.equals(otherCalendarDate) // false