Spacetime

A lightweight javascript timezone library

Date & time
spencermountain/spacetimespacetime.how/spacetime

README

spacetime logo

Isn't it weird how we can do math in our head, but not date math?

- how many days until the end of the year?
-what time was it, 11 hours ago?
-is it lunchtime in france?

and worse - there is no real _date calculator_.

people end up asking google, and going to weird websites.
that's bad.
spacetime is a date-calculator,

It's very small, and very handy.

  1. ``` js
  2. let s = spacetime.now()

  4. s.diff(s.endOf('year'), 'days')
  5. // 292

  7. s.minus(11, 'hours').time()
  8. // 6:50am

  10. s = s.now('Europe/Paris')
  11. s.isAfter(s.time('11:00am'))
  12. // true 🥐
  13. ```


- calculate time in remote timezones
- support daylight savings, leap years, and hemispheres
- Moment-like API _(but immutable)_
- Orient time by quarter, season, month, week..
- _Zero Dependencies_ - (no _Intl API_)
- weighs about 40kb.
- has a cool _plugin thing_.



  1. ``` html
  2. <script src="https://unpkg.com/spacetime"></script>
  3. <script>
  4.   var d = spacetime('March 1 2012', 'America/New_York')
  5.   //set the time
  6.   d = d.time('4:20pm')
  8.   d = d.goto('America/Los_Angeles')
  9.   d.time()
  10.   //'1:20pm'
  11. </script>
  12. ```



npm install spacetime

  1. ``` js
  2. const spacetime = require('spacetime')
  3. let d = spacetime.now('Europe/Paris')
  4. d.dayName()
  5. //'Wednesday'
  6. d.isAsleep()
  7. //true
  8. ```

typescript / babel / deno:

  1. ```ts
  2. import spacetime from 'spacetime'
  3. let d = spacetime.now()
  4. d.format('nice')
  5. //'Apr 1st, 4:32pm'
  6. ```

ts docs

      Demo
        •    
      Full API


plugins:

spacetime-geo • spacetime-daylight • spacetime-age
spacetime-calendar • week-of-month • week-start

Date Inputs:


we can parse _all the normal stuff_, and some fancy stuff:

  1. ``` js
  2. //epoch
  3. s = spacetime(1489520157124)

  5. //array [yyyy, m, d] (zero-based months, 1-based days)
  6. s = spacetime([2017, 5, 2])

  8. //iso
  9. s = spacetime('July 2, 2017 5:01:00')

  11. // All inputs accept a timezone, as 2nd param:
  12. s = spacetime(1489520157124, 'Canada/Pacific')
  13. s = spacetime('2019/05/15', 'Canada/Pacific')

  15. // or set the offset right in the date-string (ISO-8601)
  16. s = spacetime('2017-04-03T08:00:00-0700')
  17. // 'Etc/GMT-7'

  19. // Some helpers
  20. s = spacetime.now()
  21. s = spacetime.today() // This morning
  22. s = spacetime.tomorrow() // Tomorrow morning
  23. s = spacetime.min() // the earliest-possible date (271,821 bc)
  24. s = spacetime.max() // the furthest-possible future date (27k years from now)

  26. // To get the native Date object back
  27. // NOTE: this returns the date in the local browsers timezone
  28. jsDate = spacetimeDate.toNativeDate()
  29. ```

for fancier natural-language inputs, use compromise-dates.


Get & Set dates:


you can whip things around, but stay intuitive

  1. ``` js
  2. s.date() // 14
  3. s.year() // 2017
  4. s.season() // Spring
  5. s = s.hour(5) // Change to 5am
  6. s = s.date(15) // Change to the 15th

  8. s = s.day('monday') // Change to (this week's) monday
  9. s = s.day('monday', true) // go forward to monday
  10. s = s.day('monday', false) // go backward to monday

  12. s = s.month('march') // Change to (this year's) March 1st
  13. s = s.quarter(2) // Change to April 1st
  14. s.era() // 'BC'/'AD'
  15. s.decade() // 2000
  16. s.century() // 21

  18. // Percentage-based information
  19. s.progress().month = 0.23 // We're a quarter way through the month
  20. s.progress().day = 0.48 // Almost noon
  21. s.progress().hour = 0.99 // 59 minutes and 59 seconds

  23. // Add/subtract methods
  24. s = s.add(1, 'week')
  25. s = s.add(3, 'quarters')
  26. s = s.subtract(2, 'months').add(1, 'day')

  28. // start-of/end-of
  29. s = s.startOf('day') // 12:00am
  30. s = s.startOf('month') // 12:00am, April 1st
  31. s = s.endOf('quarter') // 11:59:59pm, June 30th

  33. s = s.nearest('hour') //round up/down to the hour
  34. s = s.nearest('quarter-hour') //5:15, 5:30, 5:45..
  35. s = s.next('month') //start of the next month
  36. s = s.last('year') //start of the last year

  38. // fill-in all dates between a range
  39. s.every('week', 'Jan 1st 2020') // (in tz of starting-date)

  41. //utilities:
  42. s.clone() // Make a copy
  43. s.isValid() // Sept 32nd → false
  44. s.isAwake() // it's between 8am → 10pm
  45. s.json() // get values in every unit as key-val object
  46. ```

if it's **_9am on tuesday_**, and you add a week, it will still be 9am on tuesday.
... even if some crazy changes happen.

setter methods also support a handy 2nd param that controls whether it should be set forward, or backward.

  1. ``` js
  2. s = s.time('4:00pm') // 4pm today
  3. s = s.time('4:00pm', true) // the next 4pm in the future
  4. s = s.time('4:00pm', false) // the most-recent 4pm

  6. s = s.set('march 5th 2020')
  7. s = s.set('march 4th') // 2020 (same year)
  8. s = s.set('march 4th', true) // 2021
  9. s = s.set('march 6th', false) // 2019
  10. ```

it's actually a little surprising how helpful this is.


Comparisons:


  1. ``` js
  2. let s = spacetime([2017, 5, 2])
  3. let start = s.subtract(1, 'milliseconds')
  4. let end = s.add(1, 'milliseconds')

  6. // gt/lt/equals
  7. s.isAfter(d) // True
  8. s.isEqual(d) // False
  9. s.isBefore(d) // False
  10. s.isBetween(start, end, inclusive?) // True

  12. // Comparison by unit
  13. s.isSame(d, 'year') // True
  14. s.isSame(d, 'date') // False
  15. s.diff(d, 'day') // 5
  16. s.diff(d, 'month') // 0

  18. //make a human-readable diff
  19. let before = spacetime([2018, 3, 28])
  20. let now = spacetime([2017, 3, 28]) //one year later
  21. now.since(before)
  22. // {diff: { months: 11, days: 30, ...},  rounded: 'in 12 months'  }
  23. ```

all comparisons are done with sensitivity of timezone - _8am EST_ is < _8am PST_.


Timezones:


the best way to describe a timezone is an IANA code:

  1. ``` js
  2. // Roll into a new timezone, at the same moment
  3. s = s.goto('Australia/Brisbane')
  4. ```

if you want to support relaxed timezone names like 'EST', Eastern time, use timezone-soft

  1. ``` js
  2. spacetime.extend(require('timezone-soft'))

  4. s = s.goto('milwaukee') // 'America/Chicago'
  5. s = s.goto('-7h') // UTC-7
  6. s = s.goto('GMT+8') // -8h!
  7. // (these should be used with some caution)
  8. ```

play-around with timezones, and their DST-changes:

  1. ``` js
  2. //list timezones by their current time
  3. spacetime.whereIts('8:30pm', '9:30pm') // ['America/Winnipeg', 'America/Yellowknife'... ]
  4. spacetime.whereIts('9am') //(within this hour)

  6. // Timezone metadata
  7. s.timezone().name // 'Canada/Eastern' (either inferred or explicit)
  8. s.hemisphere() // North
  9. s.timezone().current.offset // -4 (in hours)
  10. s.hasDST() // True
  11. s.isDST() // True

  13. //list all timezones
  14. spacetime.timezones()
  15. ```

you can flip-around the world pretty quick.

spacetime will use your local timezone, by default:

.goto(null) will pluck your current tz safely from your browser or computer.

  1. ``` js
  2. spacetime().time('4:30pm').goto('Europe/Paris').goto(null).time()
  3. // 4:30pm
  4. ```


Date Formatting:


it's _a pretty-sensible process_ to create nice-looking dates:

  1. ``` js
  2. // Date + time formatting
  3. s.format('time') // '5:01am'
  4. s.format('numeric-uk') // 02/03/2017
  5. s.format('month') // 'April'
  6. s.format('month-short') // 'Apr'
  7. s.format('month-pad') // '03'
  8. s.format('iso-month') // '04'

  10. //if you want more complex formats, use {}'s
  11. s.format('{year}-{date-pad}-{month-pad}') // '2018-02-02'
  12. s.format("{hour} o'clock") // '2 o'clock'
  13. s.format('{time}{ampm} sharp') // '2:30pm sharp'

  15. //if you prefer, you can also use unix-formatting
  16. s.unixFmt('yyyy.MM.dd h:mm a') // '2017.Nov.16 11:34 AM'
  17. ```



Limitations & caveats


◆ Historical timezone info


DST changes move around all the time, and timezones pop-in and out of existence.
We store and use only the latest DST information, and apply it to historical dates.

◆ International date line


.goto() never crosses the date-line. This is mostly the intuitive behaviour.

But if you're in Fiji (just west of the date line), and you go to Midway (just east of the date line), .goto() will subtract a bunch of hours, instead of just adding one.

◆ Destructive changes


if it's 2:30pm and you add a month, it should still be 2:30pm. Some changes are more destructive than others. Many of thse choices are subjective, but also sensible.

◆ 0-based vs 1-based ...


for better or worse we copy the JavaScript spec for 0-based months, and 1-based dates.

ISO-formatting is different, so keep on your toes.

see more considerations and gotchas

Daylight-savings gotchas


We've written in detail about how spacetime handles Daylight-savings changes here

Fall DST changes have an hour that is repeated twice. There are a lot of tricky situations that come from this.
Add 10 minutes at 1:55am, and a spacetime diff may show -50mins. Within an hour of this change, some spacetime methods may be off-by-one hour.

Springtime DST changes are generally smoother than Fall ones.



Config:


Ambiguity warnings:


javascript dates use millisecond-epochs, instead of second-epochs, like some other languages.
This is a common bug, and spacetime can warn if you set an epoch within January 1970.
to enable:

  1. ``` js
  2. let s = spacetime(123456, 'UTC', {
  3.   silent: false
  4. })
  5. s.log() // "Jan 1st, 12:02am"
  6. ```

There is another situation where you may see a console.warn - if you give it a timezone, but then set a ISO-date string with a different offset, like 2017-04-03T08:00:00-0700 (-7hrs UTC offset).
It sets the timezone to UTC-7, but also gives a warning.

  1. ``` js
  2. let s = spacetime('2017-04-03T08:00:00-0700', 'Canada/Eastern', {
  3.   silent: false
  4. })
  5. s.timezone().name // "Etc/GMT-7"
  6. ```

Configure 'today' context:


spacetime makes some assumptions about some string inputs:

  1. ``` js
  2. // assumes start of month
  3. let s = spacetime('June 1992')
  4. s.date() // 1

  6. // assumes current year
  7. let s = spacetime('June 5th')
  8. s.year() // 2020 (or whatever it is now)

  10. // assumes Jan 1st
  11. let s = spacetime('2030')
  12. s.month() // 'January'
  13. ```

you can configure this assumed date (usually for testing) by passing it in as an option:

  1. ``` js
  2. let today = {
  3.   month: 3,
  4.   date: 4,
  5.   year: 1996
  6. }
  7. let s = spacetime('June 5th', null, { today: today })
  8. s.year() // 1996
  9. ```

it also works for spacetime.now(tz, {today:today}) and others.

Extending/Plugins:


you can throw any methods onto the Spacetime class you want, with spacetime.extend():

  1. ``` js
  2. spacetime.extend({
  3.   isHappyHour: function () {
  4.     return this.hour() === 16
  5.   }
  6. })

  8. let s = spacetime.now('Australia/Adelaide')
  9. s.isHappyHour()
  10. //false

  12. s = s.time('4:30pm')
  13. s.isHappyHour()
  14. //true
  15. ```

DD/MM/YYY interpretation:


by default spacetime uses the American interpretation of ambiguous date formats, like javascript does:

  1. ``` js
  2. spacetime('12/01/2018') //dec 1st

  4. // unless it's clear (>12):
  5. spacetime('13/01/2018') //jan 13th
  6. ```

you can change this behaviour by passing in a dmy option, like this:

  1. ``` js
  2. spacetime('12/01/2018', null, { dmy: true }) //jan 12th
  3. ```

this format is more common in britain, and south america.

Custom languages:


  1. ``` js
  2. let s = spacetime.now()
  3. s.i18n({
  4.   days: {
  5.     long: ['domingo', 'lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado'],
  6.     short: ['dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb']
  7.   },
  8.   months: {
  9.     long: [...],
  10.     short: ['ene', 'feb', 'mar', 'abr', 'may', 'jun', 'jul', 'ago', 'sep', 'oct', 'nov', 'dic'],
  11.   },
  12.   ampm: {
  13.     am: ' a. m.',
  14.     pm: ' a. m.'
  15.   },
  16.   useTitleCase: true // automatically in .format()
  17. });
  18. s.format('day') //'Sábado'
  19. ```

Configure start of week:


by default, the start of the week is monday.

You can determine the week by the official country setting, with spacetime-week

  1. ``` js
  2. let s = spacetime.now()
  3. s = s.weekStart('sunday')

  5. s = s.startOf('week')
  6. s.dayName()
  7. //sunday

  9. s = s.endOf('week')
  10. s.dayName()
  11. //saturday
  12. ```



See also:


- luxon - a small library from the clever moment people
- date-fns - an battle-hardened client-side Date utility
- sugarjs/dates - well-made date fns + timezone math
- Intl.DateTimeFormat - some _sorta-green_ in-browser date utilities

thank you to the amazing timeanddate.com

Apache 2.0