Qrono

Appearance

API Reference ​

Complete API reference for Qrono.

The library provides two classes: Qrono, which represents a point in time, and QronoDate, which represents a calendar date.

Factory ​

All Factory methods accept an optional context object as the first argument to configure how the instance handles timezone and DST settings.

qrono(...args) ​

Creates a new Qrono datetime instance.

javascript
import { qrono } from 'qrono'

// Current time
qrono()

// From Date object
qrono(new Date())

// From timestamp (milliseconds)
qrono(1704067200000)

// From string
//
// Conforms to ISO 8601 format except for a few exceptions.
// If no time zone is specified, parsing is performed
// according to the current context (`localtime`).
//
// Format:
// yyyy[[-|/]MM[[-|/]DD]][(T| )HH[:]mm[[:]ss[(.|:)SSS]]][Z|(+|-)hh:mm]
//
qrono('2024-01-15T10:30:00.000Z')

// From components (year, month, day, hour, minute, second, millisecond)
qrono(2024, 1, 15, 10, 30, 0, 0)

// From array
qrono([2024, 1, 15, 10, 30])

// From object
qrono({ year: 2024, month: 1, day: 15 })

// With context options (context as first argument)
qrono({ localtime: true }, '2024-01-15')

qrono.date(...args) ​

Creates a new QronoDate instance (date only, no time component).

javascript
// Today
qrono.date()

// From string
qrono.date('2024-01-15')

// From components
qrono.date(2024, 1, 15)

// From array
qrono.date([2024, 1, 15])

// From object
qrono.date({ year: 2024, month: 1, day: 15 })

Conversion ​

toString() ​

Get the ISO 8601 string representation.

javascript
time.toString()  // "2024-06-15T14:30:00.000Z"

qrono.date('2024-06-15').toString()  // "2024-06-15"

valueOf() ​

Get the numeric value of the instance.
For Qrono, the unit is milliseconds since UNIX epoch.
For QronoDate, the unit is days since UNIX epoch.

javascript
+time  // 1718458200000
+qrono.date('1970-01-02')  // 1

toArray() ​

Get an array of components.

javascript
time.toArray()  // [2024, 6, 15, 14, 30, 0, 0]

qrono.date('2024-06-15').toArray()  // [2024, 6, 15]

toObject() ​

Get an object with named properties.

javascript
time.toObject()
// { year: 2024, month: 6, day: 15, hour: 14, minute: 30, second: 0, millisecond: 0 }

qrono.date('2024-06-15').toObject()
// { year: 2024, month: 6, day: 15 }

nativeDate() ​

Get a native JavaScript Date object.

javascript
time.nativeDate()  // Date instance

toDate() ​

Get a QronoDate instance (date portion only).

javascript
time.toDate()  // QronoDate instance

toDatetime() ​

Converts a QronoDate to a Qrono datetime at midnight.

javascript
qrono.date('2024-06-15').toDatetime().toString()
// "2024-06-15T00:00:00.000Z"

Constants ​

Day of Week ​

These definitions follow ISO 8601, where Monday is 1 and Sunday is 7.

javascript
qrono.monday    // 1
qrono.tuesday   // 2
qrono.wednesday // 3
qrono.thursday  // 4
qrono.friday    // 5
qrono.saturday  // 6
qrono.sunday    // 7

Accessors ​

All component methods work as both getters (no argument) and setters (with argument). Setters return a new instance (immutable).

year() ​

javascript
const time = qrono('2024-06-15')
time.year()      // 2024 (getter)
time.year(2025)  // New instance with year 2025

month() ​

javascript
time.month()    // 6 (getter, 1-12)
time.month(12)  // New instance with month 12

day() ​

javascript
time.day()    // 15 (getter)
time.day(20)  // New instance with day 20

hour() ​

javascript
time.hour()    // 14 (getter, 0-23)
time.hour(10)  // New instance with hour 10

minute() ​

javascript
time.minute()    // 30 (getter, 0-59)
time.minute(45)  // New instance with minute 45

second() ​

javascript
time.second()    // 45 (getter, 0-59)
time.second(30)  // New instance with second 30

millisecond() ​

javascript
time.millisecond()     // 123 (getter, 0-999)
time.millisecond(500)  // New instance with millisecond 500

offset() ​

Returns the time zone offset of the Qrono instance in minutes.
A positive value indicates that the base time is ahead of UTC, and a negative value indicates that it is behind UTC.

TIP

This is the opposite sign convention of JavaScript's Date.prototype.getTimezoneOffset.

javascript
qrono().context({ localtime: false }).offset() // 0
qrono().context({ localtime: true }).offset()  // e.g., 540 (JST)

Context ​

qrono.context(options) ​

Sets the default context for all new instances.

javascript
qrono.context({ localtime: true, disambiguation: 'earlier' })

Parameters:

  • localtime - boolean - Use local time instead of UTC
  • disambiguation - 'compatible' | 'earlier' | 'later' | 'reject' - How to resolve ambiguous local times at DST transitions (default: 'compatible')
    OptionGap (spring-forward)Overlap (fall-back)
    'compatible' (default)Later (DST side)Earlier (DST side)
    'earlier'Earlier (standard side)Earlier (DST side)
    'later'Later (DST side)Later (standard side)
    'reject'Throws RangeErrorThrows RangeError

context() ​

Get or set context options.

javascript
// Get current context
time.context()  // { localtime: false, disambiguation: 'compatible' }

// Set context (returns new instance)
time.context({ localtime: true })

Calculation ​

When a Qrono instance is cast to a number, it represents the milliseconds since the UNIX epoch, just like a Date object. A QronoDate instance uses “days” as its unit. Therefore, expressions like the following work as expected.

javascript
qrono('2021-08-31 12:34') < qrono('2021-09-30 12:34')
const today = qrono.date('2021-08-31')
const tomorrow = qrono.date(today + 1)
tomorrow - today === 1

plus(duration) ​

Add time to the date.
In operations using Object, year, month, and day are calculated literally.
For example, adding one month at the end of a month results in the end of the following month.
hour, minute, second, and millisecond are treated as a duration in calculations.

javascript
time.plus({ month: 2, day: 15 })
time.plus({ hour: 5, minute: 30, second: 45, millisecond: 500 })
time.plus(3600 * 1000)                // add one hour via milliseconds
time.plus([0, 1, 1, 4])               // add 1 month, 1 day, 4 hours
time.plus({ minute: 15, second: 30 }) // add minutes + seconds

QronoDate variants also accept:

javascript
qrono.date('2024-01-01').plus(1)            // +1 day
qrono.date('2024-01-01').plus([0, 1, 1])    // +1 month, +1 day
qrono.date('2024-01-01').plus({ year: 1 })  // same object form

minus(duration) ​

Subtract time from the date.
In operations using Object, year, month, and day are calculated literally.
For example, subtracting { month: 1 } from July 31 results in June 28.
hour, minute, second, and millisecond are treated as a duration in calculations.

javascript
time.minus({ year: 1 })
time.minus({ month: 2, day: 15 })
time.minus({ hour: 5, minute: 30 })
time.minus(15 * 60 * 1000)          // subtract 15 minutes via milliseconds
time.minus([0, 0, 0, 6])            // subtract 6 hours
time.minus({ day: 1, minute: 45 })  // subtract days + minutes

QronoDate variants also accept:

javascript
qrono.date('2024-01-05').minus(2)             // -2 days
qrono.date('2024-01-05').minus([0, 0, 5])     // -5 days
qrono.date('2024-01-05').minus({ month: 1 })  // subtract month

valid() ​

Check if the instance represents a valid date.

javascript
qrono('2024-01-15').valid()        // true
qrono(new Date('invalid')).valid() // false

Comparison ​

isSame(other) ​

Check if two dates are equal.

javascript
time.isSame(qrono('2024-01-15'))  // true or false
time.isSame(new Date())
time.isSame(1704067200000)

isBefore(other) ​

Check if this date is before another.

javascript
time.isBefore(qrono('2024-12-31'))  // true or false

isAfter(other) ​

Check if this date is after another.

javascript
time.isAfter(qrono('2024-01-01'))  // true or false

isSameOrBefore(other) ​

Check if this date is the same or before another.

javascript
time.isSameOrBefore(qrono('2024-12-31'))  // true or false

isSameOrAfter(other) ​

Check if this date is the same or after another.

javascript
time.isSameOrAfter(qrono('2024-01-01'))  // true or false

isBetween(start, end) ​

Check if this date is between two dates (inclusive).

javascript
time.isBetween(qrono('2024-01-01'), qrono('2024-12-31'))  // true or false

Time Unit Boundary ​

startOfYear() ​

Get the start of the year.

javascript
qrono('2024-06-15 14:30:00').startOfYear()
// 2024-01-01T00:00:00.000Z

startOfMonth() ​

Get the start of the month.

javascript
qrono('2024-06-15 14:30:00').startOfMonth()
// 2024-06-01T00:00:00.000Z

startOfDay() ​

Get the start of the day.

javascript
qrono('2024-06-15 14:30:00').startOfDay()
// 2024-06-15T00:00:00.000Z

startOfHour() ​

Get the start of the hour.

javascript
qrono('2024-06-15 14:30:45').startOfHour()
// 2024-06-15T14:00:00.000Z

startOfMinute() ​

Get the start of the minute.

javascript
qrono('2024-06-15 14:30:45').startOfMinute()
// 2024-06-15T14:30:00.000Z

startOfSecond() ​

Get the start of the second.

javascript
qrono('2024-06-15 14:30:45.123').startOfSecond()
// 2024-06-15T14:30:45.000Z

endOfYear() ​

Returns the last day of the year.

javascript
qrono.date('2024-06-15').endOfYear().toString()  // "2024-12-31"

endOfMonth() ​

Returns the last day of the month.

javascript
qrono.date('2024-06-15').endOfMonth().toString()  // "2024-06-30"

Date Information ​

dayOfWeek() ​

Get the day of the week (Monday = 1, Sunday = 7).

javascript
qrono('2024-06-15').dayOfWeek() === qrono.saturday  // 6

dayOfYear() ​

Get the day of the year (1-366).

javascript
qrono('2024-06-15').dayOfYear()  // 167

weekOfYear() ​

Get the ISO week number.

javascript
qrono('2024-06-15').weekOfYear()  // 24

yearOfWeek() ​

Get the year of the ISO week (may differ at year boundaries).

javascript
qrono('2025-12-29').yearOfWeek()  // 2026

isLeapYear() ​

Check if the year is a leap year.

javascript
qrono('2024-01-01').isLeapYear()  // true

daysInMonth() ​

Get the number of days in the current month.

javascript
qrono('2024-02-15').daysInMonth()  // 29

daysInYear() ​

Get the number of days in the current year.

javascript
qrono('2024-01-01').daysInYear()  // 366

weeksInYear() ​

Get the number of ISO weeks in the current year (52 or 53).

javascript
qrono('2024-01-01').weeksInYear()  // 52

Daylight Saving Time ​

hasOffsetChangeInYear() ​

Check if the year has daylight saving time transitions.

javascript
qrono.context({ localtime: true })

qrono(1950, 1, 1).hasOffsetChangeInYear()  // true
qrono(2024, 1, 1).hasOffsetChangeInYear()  // false (in Japan)

isInDst() ​

Check if the current time is in daylight saving time.

javascript
qrono.context({ localtime: true })

qrono('1950-09-10 00:59:59').isInDst()  // true

hasOffsetChangeInDay() ​

Check if the current day has a DST transition.

javascript
qrono.context({ localtime: true })

qrono('1950-05-07').hasOffsetChangeInDay()  // true

minutesInDay() ​

Get the number of minutes in the current day (accounts for DST).

javascript
qrono.context({ localtime: true })

qrono('1950-05-06').minutesInDay()  // 1440
qrono('1950-05-07').minutesInDay()  // 1380 (DST spring forward)
qrono('1950-09-10').minutesInDay()  // 1500 (DST fall back)

© 2021 - present urin