Home

Spacetime is a small-and-punchy dateTime library, which hopes to make it easier to work with remote timezones in javascript on both client-and-serverside.

It is based, with love, on moment-timezone.

Something this tricky is going to have bugs 🐛. If you are scheduling heart surguries, or landing spacecraft, please use a library with more institutional hardening.

Considerations:

* Historical timezone changes

Spacetime ignores the fact that timezones change.

Timezone details are political, historically-complex, and certain to change. Spacetime ignores that America/Dawsons_Creek may have had a different timekeeping system in the 1600s, and that it may change timekeeping rules in future centuries or decades. If you need support for historical timezones, we recommend moment-timezone.

* International date line

If you're in London, and you set the timezone to be in Paris, it is intuitive that you travel 1 hour 'to the right'.

But if you're in Pacific/Fiji (right side of the map), and you goto Pacific/Midway (left side of the map), .goto() will subtract a tonne of hours, instead of just adding one. The .goto() method will never pass the international date line, because the method will always respect the idea of 'now over-there', instead of some kind of geographical-movement.

* Destructive-changes

when making changes, some commands are 'greedy' to smaller values, and others are not. For example:

s= spacetime().seconds(5)
s.year(2025)
s.seconds()//still 5

//but this method 0's it out:
s.quarter('q2')
s.seconds()//now 0

The destructive methods include week(), quarter(), season(), time().

month() and year() methods are sometimes destructive -

s = spacetime('March 30 2016')
s.month('february')
// 'February 28th` - there is no Feb 30th

Likewise, if it's february 29th, and you move to a non-leap year, it becomes feb 28th.

* locale-insensitivity

spacetime assumes a gregorian calendar and western number-formatting and numeral system, and english-speaking parsing & formatting. Weeks start on a sunday (day = 0). Spacetime supports all IANA timezones, but it does not support local idioms for non-western date-times.

* 0-based months

for better or worse, spacetime copies the javascript spec for 0-based months, but 1-based dates.

s = spacetime.now()
s.month(0) //january
s.date(1)  //1st

the only exception is in handling ISO-formatted inputs and outputs:

s = spacetime('2016/01/01')
s.monthName() // 'january'
s.month() // 0
s.format('iso-short') //2016-01-01

keep on your toes! Missing this is (understandably) very common.

* Browser-sensitivities

spacetime doesn't depend on, but works better with the Internationalization API, which has high-support now among browsers. If you run spacetime on a browser without Intl, it will try to guess the timezone based on Date().getTimezoneOffset() - which has been around forever.