Home

Spacetime is a lightweight datetime library, created with the aim of making it easier to work with remote timezones both in client and server-side JavaScript.

It's inspired by the venerable Moment and Moment Timezone.

Perhaps you've heard that entirely unsubstantiated rumor that working with time can be a bit tricky? Us too, so keep an eye out, as Spacetime may have a bug or two 🐛.

If you're scheduling heart surgeries or landing spacecraft, we'd suggest using a library with more institutional hardening.

Considerations

Historical timezone changes

Timezones are political, historically complex, and over a long enough timescale, certain to change.

So instead of doing its own long-running historical timezone bookkeeping, Spacetime ignores that America/Dawson_Creek may have had a different timekeeping system in the late 19th century.

Spacetime assumes that any locales may change timekeeping rules in future years, decades, or centuries, but if what you need is support for past historical timezones, we recommend Moment Timezone.

International date line

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

But if you're in Pacific/Fiji (west of the international date line), and you go to Pacific/Midway (east of the international date line), .goto() will subtract a ton 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 that "now" is still "now" somewhere else.

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 zeroes it out:
s.quarter('q2')
s.seconds() // Now 0

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

However, month() and year() methods are sometimes destructive:

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

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

Locale insensitivity

Spacetime assumes a Gregorian calendar, western number-formatting and numeral system, and English-speaking parsing & formatting. Weeks start on 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-month') // '01'
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 your timezone based on Date().getTimezoneOffset() -- which has been around forever.