Handling Timezone In JavaScript – Spacetime

Preview:

Description:

Spacetime is a pure JavaScript library used to manipulate, traverse, compare, and format dates and times across planet Earth.

Key features:

• Get/set dates and times in remote timezones
• Global support for Daylight Savings Time, leap years + seconds, and hemispheres
• Orient by quarter, season, month, and week
• Remote date comparison
• Written in ES2015 JS, published as ES5, tested for Node and the browser

Installation:

npm install spacetime --save

How to use it:

Include the main JavaScript file on the html page.

<script src="https://unpkg.com/spacetime"></script>

Make a new Date in New York.

var d = spacetime('March 8 2017', 'America/New_York')

API Methods.

// Some helpers
s = spacetime.now()
s = spacetime.today() // This morning
s = spacetime.tomorrow() // Tomorrow morning
s = spacetime.min() // the earliest-possible date (271,821 bc)
s = spacetime.max()
// Date inputs
s = spacetime(1489520157) // Epoch
s = spacetime([2017, 5, 2]) // yyyy, m, d (zero-based months, 1-based days)
s = spacetime('July 2, 2017 5:01:00') // ISO
// Remotely understood date
s = spacetime(1489520157, 'Canada/Pacific')
// Get/set methods
s.date() // 14
s.year() // 2017
s.season() // Spring
s.hour(5) // Change to 5am
s.date(15) // Change to the 15th
s.day('monday') // Change to (this week's) monday
s.month('march') // Change to (this year's) March 1st
s.quarter(2) // Change to April 1st
// Add/subtract methods
s.add(1, 'week')
s.add(3, 'quarters')
s.subtract(2, 'months').add(1,'day')
// Timezone metadata
s.timezone().name // 'Canada/Eastern' (either inferred or explicit)
s.timezone().hemisphere // North
s.timezone().current.offset // -240 (in minutes)
s.timezone().current.isDst // True
// Comparisons
let d = spacetime([2017, 5, 2])
// gt/lt/equals
s.isAfter(d) // True
s.isEqual(d) // False
s.isBefore(d) // False
// Comparison by unit
s.isSame(d, 'year') // True
s.isSame(d, 'date') // False
s.diff(d, 'day') // 5
s.diff(d, 'month') // 0
// Date + time formatting
s.format('time') // '5:01am'
s.format('numeric-uk') // 02/03/2017
s.format('month') // 'April'
s.format('month-short') // 'Apr'
// Calendar-sensitive movement
s.startOf('day') // 12:00am
s.startOf('month') // 12:00am, April 1st
s.endOf('quarter') // 11:59:59pm, June 30th
// Percentage-based information
s.progress().month = 0.23 // We're a quarter way through the month
s.progress().day = 0.48   // Almost noon
s.progress().hour = 0.99  // 59 minutes and 59 seconds
// Misc functions
s.goto('Australia/Brisbane') // Roll into a new timezone, at the same moment
s.clone() // Make a copy
s.isValid() // Sept 32nd → false

Changelog:

v7.10.0 (04/18/2025)

• [fix] – capitalization of “Etc/Utc”
• [new] – .isoFull() method
• [new] – spacetime.fromEpochSeconds() method
• [fix] – getter form of .epochSeconds()

v7.9.0 (04/06/2025)

• [new] – .format(‘sql’)
• [new] – .epochSeconds()
• [fix] – duplicate type for .json()

v7.8.0 (12/01/2024)

• [fix] – 2025 DST-change times for many zones
• [fix] – more .week() issues from
• [new] – initial support for Temporal’s extended-iso RFC3339 fmt
• [new] – adds .format(‘iso-full’) for Temporal support
• [new] – support hot-swap timezone via .timezone(tz)
• [new] – add tz/offset info in .json() response
• [new] – support .json(obj) setter fn
• [fix] – proper capitalization of UTC in .timezone() response
• [fix] – typescript fixes
• [update] – dependencies

v7.7.7 (12/01/2024)

• [fix] – .week() issue
• [update] – 2025 DST changes
• [update] – greenland Nuuk DST change
• [update] – alias choibalsan to ulaanbaatar

v7.6.2 (10/10/2024)

• [fix] – isEqual null on 1970-01-01

v7.6.1 (07/31/2024)

• [new] – add stepCount paramater to .every()
• [update] – minor DST hour changes
• [update] – dependencies

v7.6.0 (02/13/2024)

• [fix] – leap-year string parse issue
• [change] – typescript export changes
• [update] – DST date changes for metlakatla, kiev, ciudad_juarez
• [update] – late DST date changes for gaza, hebron 1

v7.5.0 (12/11/2023)

• 2024 DST changes
• [fix] – offset in Africa/Cairo
• [change] – support i18n config in .since()

v7.4.8 (10/16/2023)

• [fix] – fix for reversed-DST in africa/casablanca and africa/el_aaiun

v7.4.7 (08/23/2023)

• Bugfix

v7.4.6 (08/10/2023)

• Added new zone: America/Ciudad_Juarez

v7.4.5 (07/28/2023)

• [fix] – typescript node16 issue
• [update] – moroccan and palestinian dst dates
• [update] – africa/cairo is back on DST
• [update] – deps

v7.4.4 (05/29/2023)

• Bugfixes

v7.4.3 (04/13/2023)

• [fix] – support leap-years in setting dayOfYear()

v7.4.2 (03/31/2023)

• [change] – Iran off of dst
• [change] – mexico off of dst
• [change] – allow chaining of .i18()
• [change] – typescript update

v7.4.1 (02/02/2023)

• [update] – add etc/unknown timezone

v7.4.0 (12/31/2022)

• [update] – 2023 DST changes for mexico
• [update] – 2023 DST changes for jordan
• [update] – 2023 DST changes for fiji
• [update] – missing seconds, quarters methods
• [new] – {AMPM} uppercase fmt

v7.3.0 (12/09/2022)

• [update] – 2023 DST changes
• [fix] – southern hemisphere december season
• [fix] – Yakutsk timezone

v7.2.0 (09/14/2022)

• [update] – timezone aliases
• [update] – dst changes
• update dependencies

v7.1.4 (04/19/2022)

• bugfixes

v7.1.3 (04/12/2022)

• [fix] – typescript fixes
• [change] – update asia/gaza and asia/hebron dst times
• update dependencies

v7.1.2 (03/01/2022)

• Bugfix

v7.1.1 (02/27/2022)

• [new] – support custom i18n strings for am/pm
• [new] – more alias support for deprecated iana codes
• [fix] – for silent/verbose mode
• update deps

v7.1.0 (01/13/2022)

• [change] – rename cjs build to .cjs

v7.0.2 (01/07/2022)

• Bugfix

v7.0.0 (01/06/2022)

• [change] – update to 2022 DST dates
• [change] – return ‘Sep’ instead of ‘Sept’ in format(‘month-short’) and ‘MMM’
• [change] – convert to ES-modules, + exports fields
• [change] – make .every() results inclusive of start
• [change] – alias old IANA codes to contemporary ones
• [change] – move cal plugin to repo spencermountain/scal
• [new] – add ISO duration to .since() results (thanks Adam)
• [fix] – iso-parsing issues
• [fix] – typescript issue
• [fix] – subtract months issue
• [fix] – unix ‘yy’ format issue
• [change] – return ‘Etc/GMT’ not ‘Etc/GMT+0’
• [change] – update deps

v6.16.3 (08/07/2021)

• [new] – .daysInMonth() method
• [change] – replace deprecated timezone aliases
• [change] – date/day naming inconsistency in add method
• [fix] – typescript fixes
• [fix] – many-year add issue
• [fix] – iso format year-padding for BC years

v6.16.2 (06/14/2021)

• [fix] – offset for asia/baku
• [fix] – date-parser for String parser off by 12 hours in some cases
• update deps

v6.16.1 (05/11/2021)

• [new] – add millisecond pad

v6.16.0 (04/16/2021)

• [change] – improvements to date-sting parsers
• [change] – drop ie11 polyfills in min.js build
• [change] – minify and stop compiling esm build

v6.15.2 (04/14/2021)

• [fix] – .add(n, ‘weekend’)
• update deps

v6.15.1 (04/08/2021)

• [fix] – Fix pacific/chatham iana DST change time

v6.15.0 (04/07/2021)

• [fix] – .time(‘4:88’) now has ceiling of 59m
• [new] – add goFwd params to all (appropriate) setter methods

v6.14.0 (03/13/2021)

• [change] – add missing timezones from indiana and argentina
• [change] – set old timezones as aliases of newer ones
• [new] – add min, max methods
• [change] – comment-out tests that were failing in some timezones

v6.13.1 (03/06/2021)

• hotfix for 0.5 date infinite-loop

v6.13.0 (03/02/2021)

• [change] – support more alt day formats like .day('mo')
• [change] – allow .week() to return 53
• [change] – support swapped-parameters for .each()
• [change] – support swapped-parameters for .isSame()
• update deps

v6.12.5 (02/11/2021)

• [fix] – add/minus by quarter issue

v6.12.4 (02/10/2021)

• [fix] – typescript issue

v6.12.3 (02/04/2021)

• [fix] – fix .every() >= issue
• [fix] – fix today-passthrough in some date formats
• [change] – use updated DST changes
• [change] – support explicit local-timezone
• update deps

v6.12.2 (12/19/2020)

• [change] – support explicit local-timezone
• [change] – support i18n titlecase config
• [fix] – endOf(‘season’) issue
• [fix] – fix character escaping issue in unixFmt method

v6.12.1 (12/02/2020)

• [new] – support for ’97 year format
• [change] – support 13h00 time format
• [change] – support 09.13.2013 and 13.09.2013 formats
• [fix] – .add() issue sometimes effecting quarter/season

v6.11.0 (11/26/2020)

• [change] – support 6-digit millisecond, and lowercase iso
• [change] – first week of year must start > dec 29th
• [fix] – typescript fixes

v6.10.1 (11/21/2020)

• [fix] – keep yukon dst changes
• [fix] – support new-zealand time in ’13h’ format
• update deps

v6.10.0 (11/14/2020)

• [fix] – support whitespace between time and am/pm
• [change] – make empty array + obj equal to null inputs
• [change] – update timezones
• [change] – remove Yukon DST preemptively

v6.9.0 (11/05/2020)

• [fix] – dst-change issues like
• [fix] – inc/dec year issue on exact nye millisecond
• [change] support parsing quarter-names as input
• [change] support parsing season-names as input

v6.8.0 (10/29/2020)

• [fix] major DST issue

v6.7.0 (10/27/2020)

• add missing timezones America/Fort_Nelson, Asia/Qostanay, and America/Nuuk
• fix comparison issue #231 effecting .isSame() and .since() accross different timezones

v6.6.4 (09/15/2020)

• [fix] 45m offset formatting issue

v6.6.3 (08/29/2020)

• support for ‘today’ param with null inputs
• support for ‘today’ param with ‘today/tonight’ inputs
• interpret empty-string input like null input (as ‘now’)
• typescript fixes

v6.6.2 (07/31/2020)

• [fix] for formatting when the output is 0
• [fix] for leap-day in .date() method
• update deps

v6.6.1 (06/27/2020)

• typescript fix

v6.6.0 (06/12/2020)

• support undefined as input (like null)
• fix for missing defaults in object input
• fix major DST add/subtract bug

v6.4.2 (03/28/2020)

• update

v6.4.1 (01/31/2020)

• update

v6.3.0 (11/07/2019)

• fix date calculation

v6.2.1 (11/07/2019)

• update

v6.2.0 (11/02/2019)

• update

v6.0.1 (09/05/2019)

• update

v6.0.0 (08/13/2019)

• update

v5.10.0 (08/07/2019)

• update

v5.9.0 (07/23/2019)

• add support for changing start/end of the week
• allow more flexible .i18n() inputs

v5.8.1 (05/07/2019)

• Readded the .d prop the the spacetime object and added a couple tests around it.

v5.8.0 (05/04/2019)

• faster diff for large-number of months
• more support for esoteric iso formats
• add format(‘iso-month’)
• change fallback behaviour for set failure edge-cases

v5.7.0 (04/14/2019)

• fix diff/since issues, and add 0 bug

v5.6.0 (04/08/2019)

• support typescript types by Jacob Craig
• use given timezone when given a spacetime object as an input
• adds .every(unit, to) method
• set UTC as default fallback timezone

v5.5.0 (03/28/2019)

• update zonefile to 2019

v5.4.0 (03/01/2019)

• all methods now immutable by default.
• move unix-formating out of .format() into .unixFmt()
• support new {hour} oclock-style format templates
• change default .format() response to yyyy-mm-dd
• uppercase month and day names in .dayName()
• support city-names, EST, PDT, etc as input
• set default silent: true to avoid unwanted logging

v5.3.0 (02/25/2019)

• all methods now immutable by default
• move unix-formating out of .format() into .unixFmt()
• support new {hour} oclock-style format templates
• change default .format() response to yyyy-mm-dd
• uppercase month and day names in .dayName()
• support city-names, EST, PDT, etc as input
• set default silent: true to avoid unwanted logging

v5.2.2 (02/23/2019)

• Fix error about timezone
• Fix half hour timezone issues

v5.2.1 (01/09/2018)

• week bugfix

v5.1.0 (12/15/2018)

• titlecase short-forms of months, days in .format()

v5.0.3 (12/14/2018)

• all methods now immutable by default. — existing code will now need to be s = s.add(1,’day’) — (instead of s.add(1,’day’))
• move unix-formating out of .format() into .unixFmt()
• support new {hour} oclock-style format templates
• change default .format() response to yyyy-mm-dd
• uppercase month and day names in .dayName()
• support city-names, EST, PDT, etc as input
• set default silent: true to avoid unwanted logging

v4.5.0 (11/24/2018)

• update a few TZ offsets in eastern-Russia
• updates to 2019 Palestinian dst dates
• fixes for missing immutable setter methods

v4.4.0 (09/02/2018)

• swap interpretation of ISO date offsets -0500 → +5 offset

v4.3.0 (07/28/2018)

• Parse a new date in RFC822 format switches the offset (+/-)

v4.2.2 (06/22/2018)

• adds .extend() method for authoring plugins

v4.2.1 (06/02/2018)

• fix russia hour bug, support 3-term timezones

v4.2.0 (05/31/2018)

• adds isBetween() method