@tubular/time

Not all days are 24 hours. Some are 23 hours, or 25, or even 23.5 or 24.5 or 47 hours. Some minutes are 61 seconds long. How about a Thursday followed directly by a Saturday, giving Friday the slip? Or a September only 19 days long? This is a date/time library for handling both day-to-day situations (so to speak) and some weird ones too.

![npm](https://www.npmjs.com/package/@tubular/time/) ![Coverage Status](https://coveralls.io/github/kshetline/tubular_time) ![npm downloads](https://npmjs.org/package/@tubular/time/) !npm bundle size (scoped) !license

Key features

* Mutable and immutable DateTime objects supporting the Gregorian and Julian calendar systems, with settable crossover.
* IANA timezone support, with features beyond formatting time for particular timezones, such as parsing, accessible listings of all available timezones (single-array list, grouped by UTC offset, or grouped by region), timezone transition history, and live updates of timezone definitions.
* Supports leap seconds and conversions between TAI (International Atomic Time) and UTC (Universal Coordinated Time).
* Supports and recognizes negative Daylight Saving Time.
* Extensive date/time manipulation and calculation capabilities.
* Many features available using a familiar Moment.js-style API.
* Astronomical time conversions among TDT (Terrestrial Dynamic Time), UT1, UTC, and TAI.
* Local mean time, by geographic longitude, to one minute (of time) resolution.
* Astronomical time conversions among TDT (Terrestrial Dynamic Time), UT1, UTC and TAI, as well as local mean time, by geographic longitude, to one minute (of time) resolution.
* Internationalization via JavaScript’s Intl Internationalization API, with additional built-in i18n support for issues not covered by Intl, and US-English fallback for environments without Intl support.
* Package suitable for tree shaking and Angular optimization.
* Full TypeScript typing support.

October 1582

@tubular/time is a collection of date and time classes and functions, providing extensive internationalized date/time parsing and formatting capabilities, date/time manipulations such as field-specific add/subtract, set, and roll; calendar computations; support for live-updatable IANA time zones; and a settable Julian/Gregorian calendar switchover date.

This library was originally developed for an astronomy website, , and has some features of particular interest for astronomy and historical events, but has been expanded to provide many features similar to the now-legacy-status Moment.js.

Unlike Moment.js, IANA timezone handling is built in, not a separate module, with a compact set of timezone definitions that reach roughly five years into the past and five years into the future, expanded into the past and future using Daylight Saving Time rules and/or values extracted from Intl.DateTimeFormat. Unlike the Intl API, the full list of available timezones is exposed, facilitating the creation of timezone selection interfaces.

Two alternate large timezone definition sets, of approximately 280K each, are available, each serving slightly different purposes. These definitions can be bundled at compile time, or loaded dynamically at run time. You can also download live updates when the IANA Time Zone Database is updated.

- Installation
- Via npm
- Via `

For the old-fashioned UMD approach (which can save you from about 560K of extra data):

`html`

_(...or /data/timezone-large.js")_

The script element just above the index.js URL is an example of _optionally_ loading extended timezone definitions. Such a script element, if used, should precede the index.js script.

The @tubular/time package will be available via the global variable tbTime. tbTime.ttime is the default function, and other functions, classes, and constants will also be available on this variable, such as tbTime.DateTime, tbTime.julianDay, tbTime.TIME_MS, etc.

`Basic usage`

While there are a wide range of functions and classes available from @tubular/time, the workhorse is the ttime() function, which produces immutable instances of the DateTime class.

`$3`

DateTime instances can be created in many ways. The simplest way is to create a current-time instance, done by passing no arguments at all. Dates and times can also be expressed as strings, objects, and arrays of numbers.

When dealing with Daylight Saving Time, and days when clocks are turned backward, some hour/minute combinations are repeated. The time might be 1:59, go back to 1:00, then forward again to 1:59, and only after hitting 1:59 for this second time during the day, move forward to 2:00.

By default, any ambiguous time is treated as the earlier time, the first occurrence of that time during a day. You can, however, use either an explicit UTC offset or a subscript 2 (₂), to indicate the later time.

ttime('11/7/2021 1:25 AM America/Denver', 'MM/DD/YYYY h:m a z').toString()→DateTime<2021-11-07T01:25:00.000 -06:00§>

ttime('11/7/2021 1:25₂ AM America/Denver', 'MM/DD/YYYY h:m a z').toString()→DateTime<2021-11-07T01:25:00.000₂-07:00>

ttime('2021-11-07 01:25 -07:00 America/Denver').toString()→DateTime<2021-11-07T01:25:00.000₂-07:00>

`Formatting output`

Dates and times can be formatted in many ways, using a broad selection of format tokens, described in the table below.

For the greatest adherence to localized formats for dates and times, you can use the IXX format strings, which call directly upon Intl.DateTimeFormat (if available) to create localized dates, times, and combined date/times.

You can also produce more customized, flexible formatting, specifying the order, positioning, and style (text vs. number, fully spelled out or abbreviated, with or without leading zeros) of each date/time field, with embedded punctuation and text as desired.

For example:

ttime().format('ddd MMM D, y N [at] h:mm A z')→Wed Feb 3, 2021 AD at 8:59 PM EST

ttime().toLocale('de').format('ddd MMM D, y N [at] h:mm A z')→Mi 02 3, 2021 n. Chr. at 9:43 PM GMT-5

Please note that most unaccented Latin letters (a-z, A-Z) are interpreted as special formatting characters, as well as the tilde (~), so when using those characters as literal text they should be surrounded with square brackets, as with the word “at” in the example above.

`$3`

A few of the formatting tokens below can have an optional trailing tilde (~) added. This is for special handling of Chinese, Japanese, and Korean (CJK) date notation. The ~ is replaced, where appropriate, with 年, 月, or 日 for Chinese and Japanese, and with 년, 월, or 일 for Korean. Korean formatting also adds a space character when the following character is a letter or digit, but not when punctuation or the end of the format string comes next.

For all other languages, ~ is replaced with a space character when the following character is a letter or digit, or simply removed when followed by punctuation or the end of the format string.

For example:

ttime().toLocale('zh').format('MMM~YYYY~')→8月2021年

ttime().toLocale('es').format('MMM~YYYY~')→ago 2021

`Format string tokens`

Moment.js formats not supported by @tubular/time: DDDo, Wo, wo, yo

@tubular/time formats not supported by Moment.js: KK, K, kk, k, ZZZ, V, v, R, r, n, IXX (IFF, IFL, IFM... IxM, IxS)

`Moment.js-style localized formats`

| | Token | Output | |---------------------------------------------------|------:|----------------------------------------| | Month name, day of month, day of week, year, time | LLLL | Thursday, September 4, 1986 at 8:30 PM | | | llll | Thu, Sep 4, 1986 8:30 PM | | Month name, day of month, year, time | LLL | September 4, 1986 8:30 PM | | | lll | Sep 4, 1986 8:30 PM | | Month name, day of month, year | LL | September 4, 1986 | | | ll | Sep 4, 1986 | | Month numeral, day of month, year | L | 09/04/1986 | | | l | 9/4/1986 | | Time with seconds | LTS | 8:30:25 PM | | Time | LT | 8:30 PM |

`@tubular/time` Intl.DateTimeFormat `shorthand string formats`

These start with a capital letter I, followed by one letter for the date format, which corresponds to the dateStyle option of Intl.DateTimeFormat, and one letter for the time format, corresponding to the timeStyle option.

The capital letters F, L, M, and S correspond to the option values 'full', 'long', 'medium', and 'short'. ILS thus specifies a long style date and a short style time. IL is a long style date alone, without time. IxS is a short style time without a date.

`$3`

| Format | Output | |--------|-------------------------------------------------------------------| | IFF |Thursday, September 4, 1986 at 8:30:00 PM Eastern Daylight Time| | ILM |September 4, 1986 at 8:30:00 PM| | IS |9/4/86| | IxL |8:30:00 PM EDT |

You can also augment these formats with brace-enclosed Intl.DateTimeFormatOptions, such as:

IMM{hourCycle:23h}

...which will start with whatever the localized time formatting is and force it into 24-hour time, whether the standard localized form is a 12- or 24-hour format. Note that no quotes are placed around the option values, as they would be in JavaScript/TypeScript code.

`Pre-defined formats`

`javascript ttime.DATETIME_LOCAL = 'Y-MM-DD[T]HH:mm'; ttime.DATETIME_LOCAL_SECONDS = 'Y-MM-DD[T]HH:mm:ss'; ttime.DATETIME_LOCAL_MS = 'Y-MM-DD[T]HH:mm:ss.SSS'; ttime.DATE = 'Y-MM-DD'; ttime.TIME = 'HH:mm'; ttime.TIME_SECONDS = 'HH:mm:ss'; ttime.TIME_MS = 'HH:mm:ss.SSS'; ttime.WEEK = 'GGGG-[W]WW'; ttime.WEEK_AND_DAY = 'GGGG-[W]WW-E'; ttime.WEEK_LOCALE = 'gggg-[w]ww'; ttime.WEEK_AND_DAY_LOCALE = 'gggg-[w]ww-e'; ttime.MONTH = 'Y-MM';`

`Parsing with a format string, and optionally a locale`

(_As viewed via formatted output_)

| | .format('IMM') | |-------------------------------------------------------|----------------------------| |ttime('02/03/32', 'MM-DD-YY') | Feb 3, 2032, 12:00:00 AM| |ttime('02/03/32', 'DD-MM-YY') | Mar 2, 2032, 12:00:00 AM| |ttime('02/03/32 4:30 pm', 'DD-MM-YY hh:mm a', 'fr') | 2 mars 2032 à 16:30:00| |ttime('02/03/32', 'DD-MM-YYYY') | Mar 2, 0032, 12:00:00 AM| |ttime('2032-03-02T16:30', null, 'ru') | 2 мар. 2032 г., 16:30:00| |ttime('2032-03-02T16:30', null, 'ar-sa') | ٠٢‏/٠٣‏/٢٠٣٢ ٤:٣٠:٠٠ م| |ttime('2032-03-02T16:30', null, 'zh-cn') | 2032年3月2日下午4:30:00 |

`Converting timezones`

ttime('2005-10-10 16:30 America/Los_Angeles').tz('Europe/Warsaw').toString()→DateTime<2005-10-11T01:30:00.000 +02:00>

Please note that if you pass a second argument of true, the timezone is changed, _but the wall time stays the same._ This same option to preserve wall time is available for the utc() and local() methods, where the optional boolean value will be the one and only argument.

ttime('2005-10-10 16:30 America/Los_Angeles').tz('Europe/Warsaw', true).toString()→DateTime<2005-10-10T16:30:00.000 +02:00>

ttime('2005-10-10 16:30 America/Los_Angeles').utc().toString()→DateTime<2005-10-10T23:30:00.000 +00:00>

ttime('2005-10-10 16:30 America/Los_Angeles').utc().toString(true)→DateTime<2005-10-10T16:30:00.000 +00:00>

// Local zone is America/New_Yorkttime('2005-10-10 16:30 America/Los_Angeles').local().toString()→DateTime<2005-10-10T19:30:00.000 +04:00>

`Converting locales`

ttime('7. helmikuuta 2021', 'IL', 'fi').toLocale('de').format('IL')→7. Februar 2021

`Defining and updating timezones`

These functions define the size and behavior of the IANA timezone definitions used by @tubular/time:

`typescript ttime.initTimezoneSmall(); ttime.initTimezoneLarge(); ttime.initTimezoneLargeAlt();`

By default, @tubular/time is set up using initTimezoneSmall(). This covers explicitly defined timezone information for roughly the release date of the version of @tubular/time you’re using, +/- five years, supplemented by rules-based extensions (i.e. knowing that for a particular timezone, say, “DST starts on the last Sunday of March and ends on the last Sunday of October”), and further supplemented by information extracted from Intl, when available.

With proper tree-shaking, the code footprint of @tubular/time should be less than 150K when using the small timezone definitions.

Using initTimezoneLarge() provides the full IANA timezone database. Using this will increase code size by about 280K, presuming that your build process is smart enough to have otherwise excluded unused code in the first place.

initTimezoneLargeAlt() provides a slight variant of the full IANA timezone database, and is also roughly 280K. This variant rounds all timezone offsets to full minutes, and adjusts a small number of fairly old historical changes by a few hours so that only the time-of-day ever goes backward, never the calendar date. It’s generally more than enough trouble for software to cope with missing and/or repeated hours during a day; initTimezoneLargeAlt() makes sure the date/time can’t be, say, the 19th of the month, then the 18th, and then the 19th again, as happens with the unmodified America/Juneau timezone during October 1867.

For browser-based inclusion of timezone definitions, if not relying on a tool like webpack to handle such issues for you, you can also include full timezone definitions this way:

`html`

...or...

`html`

Either of these should appear _before_ the script tag that loads @tubular/time itself.

`$3`

Timezone definitions can be updated live as well. Different polling methods are needed for Node.js code or browser-hosted code, since both environments access web resources in very different ways (and browsers have CORS issues, which Node.js does not).

To be informed when a live timezone update takes place, add and remove update listeners using these functions:

`typescript function addZonesUpdateListener(listener: (result: boolean | Error) => void): void; function removeZonesUpdateListener(listener: (result: boolean | Error) => void): void; function clearZonesUpdateListeners(): void`

The result received by a callback is true if an update was successful, and caused changes in timezone definitions, false if successful, but no changes occurred, or an instance of Error, indicating an error (probably an HTTP failure) has occurred.

For example:

`typescript const listener = result => console.log(result); // Keep in a variable if removal is needed later

ttime.addZonesUpdateListener(listener);

// Later on in the code...

ttime.removeZonesUpdateListener(listener);`

Why use a listener? Because you might want to recalculate previously calculated times, which possibly have changed due to timezone definition changes. For example, imagine you have a video meeting scheduled for 10:00 in a client’s timezone, which, when you first schedule it, was going to be 15:00 in your timezone. Between the time you scheduled the meeting, however, and when the meeting actually takes place, the switch to Daylight Saving Time is canceled for the client’s timezone. If you still intend to talk to your client at 10:00 their time, you have to meet at 16:00 in your timezone instead.

To poll for timezone updates at a regular interval, use:

`typescript function pollForTimezoneUpdates(zonePoller: IZonePoller | false, name: ZoneOptions = 'small', intervalDays = 1): void;`

* zonePoller: Either zonePollerBrowser (from tbTime.zonePollerBrowser) or zonePollerNode (using import or require, from '@tubular/time'). If you pass the boolean value false, polling ceases. *name: One of 'small', 'large', or 'large-alt'. Defaults to 'small'. *intervalDays: Frequency of polling, in days. Defaults to 1 day. The fastest allowed rate is once per hour (~0.04167 days).

You can also do a one-off request:

`typescript function getTimezones(zonePoller: IZonePoller | false, name: ZoneOptions = 'small'): Promise;`

zonePoller and name are the same as above. Any periodic polling done by pollForTimezoneUpdates() is canceled. You can get a response via registered listeners, but this function also returns a Promise. The promise either resolves to a boolean value or is rejected with an Error.

`The` YMDDate `and` DateAndTime `objects`

YMDDate:

`json5 { y: 2021, // short for year q: 1, // short for quarter m: 2, // short for month d: 4, // short for day dow: 4, // short for dayOfWeek (output only) dowmi: 1, // dayOfWeekMonthIndex (output only) dy: 35, // short for dayOfYear n: 18662, // short for epochDay j: false, // short for isJulian

year: 2021, quarter: 1, // quarter of the year 1-4 month: 2, day: 4, dayOfWeek: 4, // Day of week as 0-6 for Sunday-Saturday (output only) dayOfWeekMonthIndex: 1, // Day of week month index, 1-5, e.g. 2 for 2nd Tuesday of the month (output only) dayOfYear: 35, epochDay: 18662, // days since January, 1 1970 isJulian: false, // true if a Julian calendar date instead of a Gregorian date

yw: 2021, // short for yearByWeek w: 5, // short for week dw: 4, // short for dayByWeek yearByWeek: 2021, // year that accompanies an ISO year/week/day-of-week style date week: 5, // week that accompanies an ISO year/week/day-of-week style date dayByWeek: 4, // day that accompanies an ISO year/week/day-of-week style date

ywl: 2021, // short for yearByWeekLocale wl: 6, // short for weekLocale dwl: 5, // short for dayByWeekLocale yearByWeekLocale: 2021, // year that accompanies a locale-specific year/week/day-of-week style date weekLocale: 6, // week that accompanies a locale-specific year/week/day-of-week style date dayByWeekLocale: 5, // day that accompanies a locale-specific year/week/day-of-week style date

error: 'Error description if applicable, otherwise undefined' }`

DateAndTime, which extends the YMDDate interface:

`json5 { hrs: 0, // short for hour min: 18, // short for minute sec: 32, // short for second hour: 0, minute: 18, second: 32, millis: 125, // 0-999 milliseconds part of time

utcOffset: -18000, // offset (in seconds) from UTC, negative west from 0°, including DST offset when applicable dstOffset: 0, // DST offset, in minutes - usually positive, but can be negative (output only) occurrence: 1, // usually 1, but can be 2 for the second occurrence of the same wall clock time during a single day, caused by clock being turned back for DST deltaTai: 37, // How much (in seconds) TAI exceeds UTC or UT1 at given moment in time (output only) /* In the well-defined range for UTC, deltaTai is always an integer value. Outside that range it can be a non-integer with millisecond precision. */

jde: 2459249.722008264, // Julian days, ephemeris mjde: 59249.22200826416, // Modified Julian days, ephemeris jdu: 2459249.7212051502, // Julian days, UT mjdu: 59249.22120515024 // Modified Julian days, UT }`

When using a YMDDate or DateAndTime object to create a DateTime instance, you need only set a minimal number of fields to specify the date and/or time you are trying to specify. You can use either short or long names for fields (if you use both, the short form takes priority).

At minimum, you must specify a date or a time. If you only specify a date, the time will be treated as midnight at the start of that date. If you only specify a time, you can create a special dateless time instance. You can also, of course, specify both date and time together.

In specifying a date, the date fields have the following priority:

* n / epochDay: Number of days before/after epoch day 0, which is January 1, 1970. *y / year: A normal calendar year. Along with the year, you can specify: * Nothing more, in which case the date is treated as January 1 of that year. *m / month: The month (a normal 1–12 month, not the weird 0–11 month the JavaScript Dateuses!). * If nothing more is given, the date is treated as the first of the month. *d / day: The date of the month. *dy / dayOfYear: The 1-based number of days into the year, such that 32 means February 1. *yw / yearByWeek: An ISO week-based calendar year, where each week starts on Monday. This year is the same as the normal calendar year for most of the calendar year, except for, possibly, a few days at the beginning and end of the year. Week 1 is the first week which contains January 4. Along with this style of year, you can specify: * Nothing more, in which case the date is treated as the first day of the first week of the year. *w / week: The 1-based week number. * If nothing more, the date is treated as the first day of the given week. *dw / dayByWeek: The 1-based day of the given week. *ywl / yearByWeekLocale, etc.: These fields work the same as yw / yearByWeek, etc., except that they apply to locale-specific rules for the day of the week on which each week starts, and for the definition of the first week of the year.

In specifying a time, the minimum needed is a 0–23 value for hrs / hour. All other unspecified time fields will be treated as 0.

Astronomical time fields will supersede any of the above date fields.

As discussed earlier, concerning parsing time strings, ambiguous times due to Daylight Saving Time default to the earlier of two times. You can, however, use occurrence: 2 to explicitly specify the later time. An explicit utcOffset can also accomplish this disambiguation.

`Reading individual` DateTime `fields`

As an output from a DateTime instance, such as what you get from ttime().wallTime, all DateAndTime fields will be filled in with synchronized values. ttime().wallTime.hour provides the hour value, ttime().wallTime.utcOffset provides the UTC offset in seconds for the given time, etc.

ttime().wallTimeShort returns a DateAndTime object with all available short-form field names, and ttime().wallTimeLong only long-form field names. ttime().wallTimeSparse returns a DateAndTime object with a minimal set of short-form field names: y, m, d, hrs, min, sec, millis.

`Modifying` DateTime `values`

There are six main methods for modifying a DateTime value:

* add(field: DateTimeField | DateTimeFieldName, amount: number, variableDays = true): DateTime*subtract(field: DateTimeField | DateTimeFieldName, amount: number, variableDays = true): DateTime*roll(field: DateTimeField | DateTimeFieldName, amount: number, minYear = 1900, maxYear = 2099)*set(field: DateTimeField | DateTimeFieldName, value: number, loose = false): DateTime*startOf(field: DateTimeField | DateTimeFieldName): DateTime*endOf(field: DateTimeField | DateTimeFieldName): DateTime

> Before going further, it needs to be mentioned that DateTime instances can be either locked, and thus immutable, or unlocked. Instances generated using ttime(...) are locked. Instances created using the DateTime constructor (covered later in this document) are created unlocked, but can be locked after creation.

When you use the add/subtract/roll/set methods on a locked instance, a new modified and locked instance is returned. When used on an unlocked instance, these methods modify that instance itself, and a reference to the modified instance is returned.

`$3`

> subtract() is nothing more than a convenience method which negates the amount being added, and then calls add(). The documentation that follows is in terms of the add() method alone, but applies, with this negation, to the subtract() method as well.

An example of using add():

ttime().add('year', 1) or ttime().add(DateTimeField.YEAR, 1)

The above produces a date one year later than the current time. In most cases, this means that the resulting date has the same month and date, but in the case of a leap day:

ttime('2024-02-29').add('year', 1).toIsoString(10) → 2025-02-28

...the date is pinned to 28 so that an invalid date is not created. Similarly, when adding months, invalid dates are prevented:

ttime('2021-01-31').add(DateTimeField.MONTH, 1).toIsoString(10) → 2021-02-28

You can add using the following fields: MILLI, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, QUARTER, YEAR, YEAR_WEEK, and YEAR_WEEK_LOCALE, as provided by the DateTimeField enum, or their string equivalents ('milli', 'millis', 'millisecond', 'milliseconds'... 'day', 'days', 'date', 'month', 'months', etc.).

_(There are further fields defined for dealing with leap seconds and TAI, described later.)_

For fields MILLI through HOUR, fixed units of time, multiplied by the amount you pass, are applied. When dealing with months, quarters, and years, the variable lengths of months, quarters, and years apply.

DAY` amounts can be handled either way, as variable in length (due to possible effects

@tubular/time

@tubular/time

Key features

Reading individual DateTime fields

Modifying DateTime values

$3

@tubular/time

@tubular/time

Key features

Reading individual DateTime fields

Modifying DateTime values

$3

Dist Tags

`Reading individual` DateTime `fields`

`Modifying` DateTime `values`

`$3`

`Reading individual` DateTime `fields`

`Modifying` DateTime `values`

`$3`