--- url: 'https://qronojs.dev/api.md' --- # 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](#factory) * [qrono(...args)](#qrono) 14 overloads * [qrono.date(...args)](#qrono-date) 7 overloads * [Conversion](#conversion) * [.toString()](#tostring) * [.valueOf()](#valueof) * [.toArray()](#toarray) * [.toObject()](#toobject) * [.nativeDate()](#nativedate) * [.toDate()](#todate) * [.toDatetime()](#todatetime) * [Constants](#constants) * [qrono.monday](#day-constants) * [qrono.tuesday](#day-constants) * [qrono.wednesday](#day-constants) * [qrono.thursday](#day-constants) * [qrono.friday](#day-constants) * [qrono.saturday](#day-constants) * [qrono.sunday](#day-constants) * [Accessors](#accessors) * [.year()](#year) 2 overloads 2 overloads * [.month()](#month) 2 overloads 2 overloads * [.day()](#day) 2 overloads 2 overloads * [.hour()](#hour) 2 overloads * [.minute()](#minute) 2 overloads * [.second()](#second) 2 overloads * [.millisecond()](#millisecond) 2 overloads * [.offset()](#offset) * [Context](#context-methods) * [qrono.context()](#default-context) 2 overloads * [.context()](#context) 2 overloads * [Calculation](#calculation) * [.plus(duration)](#plus) 4 overloads 4 overloads * [.minus(duration)](#minus) 4 overloads 4 overloads * [.valid()](#valid) * [Comparison](#comparison) * [.isSame(other)](#issame) 3 overloads 3 overloads * [.isBefore(other)](#isbefore) 3 overloads 3 overloads * [.isAfter(other)](#isafter) 3 overloads 3 overloads * [.isSameOrBefore(other)](#issameorbefore) 3 overloads 3 overloads * [.isSameOrAfter(other)](#issameorafter) 3 overloads 3 overloads * [.isBetween(start, end)](#isbetween) 3 overloads 3 overloads * [Time Unit Boundary](#boundary) * [.startOfYear()](#startofyear) * [.startOfMonth()](#startofmonth) * [.startOfDay()](#startofday) * [.startOfHour()](#startofhour) * [.startOfMinute()](#startofminute) * [.startOfSecond()](#startofsecond) * [.endOfYear()](#endofyear) * [.endOfMonth()](#endofmonth) * [Date Information](#date-info) * [.dayOfWeek()](#dayofweek) * [.dayOfYear()](#dayofyear) * [.weekOfYear()](#weekofyear) * [.yearOfWeek()](#yearofweek) * [.isLeapYear()](#isleapyear) * [.daysInMonth()](#daysinmonth) * [.daysInYear()](#daysinyear) * [.weeksInYear()](#weeksinyear) * [Daylight Saving Time](#dst) * [.hasOffsetChangeInYear()](#hasOffsetChangeInYear) * [.isInDst()](#isindst) * [.hasOffsetChangeInDay()](#hasOffsetChangeInDay) * [.minutesInDay()](#minutesinday) ## Factory {#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) {#qrono} 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) {#qrono-date} 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 {#conversion} ### toString() {#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() {#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() {#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() {#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() {#nativedate} Get a native JavaScript Date object. ```javascript time.nativeDate() // Date instance ``` ### toDate() {#todate} Get a `QronoDate` instance (date portion only). ```javascript time.toDate() // QronoDate instance ``` ### toDatetime() {#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 {#constants} ### Day of Week {#day-constants} 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 {#accessors} All component methods work as both getters (no argument) and setters (with argument). Setters return a new instance (immutable). ### year() {#year} ```javascript const time = qrono('2024-06-15') time.year() // 2024 (getter) time.year(2025) // New instance with year 2025 ``` ### month() {#month} ```javascript time.month() // 6 (getter, 1-12) time.month(12) // New instance with month 12 ``` ### day() {#day} ```javascript time.day() // 15 (getter) time.day(20) // New instance with day 20 ``` ### hour() {#hour} ```javascript time.hour() // 14 (getter, 0-23) time.hour(10) // New instance with hour 10 ``` ### minute() {#minute} ```javascript time.minute() // 30 (getter, 0-59) time.minute(45) // New instance with minute 45 ``` ### second() {#second} ```javascript time.second() // 45 (getter, 0-59) time.second(30) // New instance with second 30 ``` ### millisecond() {#millisecond} ```javascript time.millisecond() // 123 (getter, 0-999) time.millisecond(500) // New instance with millisecond 500 ``` ### offset() {#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 {#context-methods} ### qrono.context(options) {#default-context} 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'`) | Option | Gap (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 `RangeError` | Throws `RangeError` | ### context() {#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 {#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) {#plus} 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) {#minus} 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() {#valid} Check if the instance represents a valid date. ```javascript qrono('2024-01-15').valid() // true qrono(new Date('invalid')).valid() // false ``` ## Comparison {#comparison} ### isSame(other) {#issame} 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) {#isbefore} Check if this date is before another. ```javascript time.isBefore(qrono('2024-12-31')) // true or false ``` ### isAfter(other) {#isafter} Check if this date is after another. ```javascript time.isAfter(qrono('2024-01-01')) // true or false ``` ### isSameOrBefore(other) {#issameorbefore} Check if this date is the same or before another. ```javascript time.isSameOrBefore(qrono('2024-12-31')) // true or false ``` ### isSameOrAfter(other) {#issameorafter} Check if this date is the same or after another. ```javascript time.isSameOrAfter(qrono('2024-01-01')) // true or false ``` ### isBetween(start, end) {#isbetween} 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 {#boundary} ### startOfYear() {#startofyear} Get the start of the year. ```javascript qrono('2024-06-15 14:30:00').startOfYear() // 2024-01-01T00:00:00.000Z ``` ### startOfMonth() {#startofmonth} Get the start of the month. ```javascript qrono('2024-06-15 14:30:00').startOfMonth() // 2024-06-01T00:00:00.000Z ``` ### startOfDay() {#startofday} Get the start of the day. ```javascript qrono('2024-06-15 14:30:00').startOfDay() // 2024-06-15T00:00:00.000Z ``` ### startOfHour() {#startofhour} Get the start of the hour. ```javascript qrono('2024-06-15 14:30:45').startOfHour() // 2024-06-15T14:00:00.000Z ``` ### startOfMinute() {#startofminute} Get the start of the minute. ```javascript qrono('2024-06-15 14:30:45').startOfMinute() // 2024-06-15T14:30:00.000Z ``` ### startOfSecond() {#startofsecond} Get the start of the second. ```javascript qrono('2024-06-15 14:30:45.123').startOfSecond() // 2024-06-15T14:30:45.000Z ``` ### endOfYear() {#endofyear} Returns the last day of the year. ```javascript qrono.date('2024-06-15').endOfYear().toString() // "2024-12-31" ``` ### endOfMonth() {#endofmonth} Returns the last day of the month. ```javascript qrono.date('2024-06-15').endOfMonth().toString() // "2024-06-30" ``` ## Date Information {#date-info} ### dayOfWeek() {#dayofweek} Get the day of the week (Monday = 1, Sunday = 7). ```javascript qrono('2024-06-15').dayOfWeek() === qrono.saturday // 6 ``` ### dayOfYear() {#dayofyear} Get the day of the year (1-366). ```javascript qrono('2024-06-15').dayOfYear() // 167 ``` ### weekOfYear() {#weekofyear} Get the ISO week number. ```javascript qrono('2024-06-15').weekOfYear() // 24 ``` ### yearOfWeek() {#yearofweek} Get the year of the ISO week (may differ at year boundaries). ```javascript qrono('2025-12-29').yearOfWeek() // 2026 ``` ### isLeapYear() {#isleapyear} Check if the year is a leap year. ```javascript qrono('2024-01-01').isLeapYear() // true ``` ### daysInMonth() {#daysinmonth} Get the number of days in the current month. ```javascript qrono('2024-02-15').daysInMonth() // 29 ``` ### daysInYear() {#daysinyear} Get the number of days in the current year. ```javascript qrono('2024-01-01').daysInYear() // 366 ``` ### weeksInYear() {#weeksinyear} Get the number of ISO weeks in the current year (52 or 53). ```javascript qrono('2024-01-01').weeksInYear() // 52 ``` ## Daylight Saving Time {#dst} ### hasOffsetChangeInYear() {#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() {#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() {#hasOffsetChangeInDay} Check if the current day has a DST transition. ```javascript qrono.context({ localtime: true }) qrono('1950-05-07').hasOffsetChangeInDay() // true ``` ### minutesInDay() {#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) ```