Ready to take your JavaScript development to the next level? Meet npm Enterprise - the ultimate in enterprise JavaScript. Learn more »

spacetime

5.2.2 • Public • Published
  • 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)
  • only 50KB.
<script src="https://unpkg.com/spacetime"></script>
<script>
  var d = spacetime('March 1 2012', 'America/New_York')
  //set the time
  d = d.time('4:20pm')
 
  d = d.goto('America/Los_Angeles')
  d.time()
  //'1:20pm'
</script> 

npm install spacetime

const spacetime = require('spacetime')
let d = spacetime.now('Europe/Paris')
d.dayName()
//'Wednesday'
d.isAsleep()
//true

Date Inputs:

//epoch
= spacetime(1489520157)
//array [yyyy, m, d] (zero-based months, 1-based days)
= spacetime([2017, 5, 2])
//iso
= spacetime('July 2, 2017 5:01:00')
 
// All inputs accept a timezone, as 2nd param:
= spacetime(1489520157, 'Canada/Pacific')
= spacetime('2019/05/15', 'Canada/Pacific')
 
// or set the offset right in the date-string (ISO-8601)
= spacetime('2017-04-03T08:00:00-0700')
// 'Etc/GMT-7'
 
// Some helpers
= spacetime.now()
= spacetime.today() // This morning
= spacetime.tomorrow() // Tomorrow morning

Get & Set dates:

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
s.era() // 'BC'/'AD'
 
// 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
 
// Add/subtract methods
= s.add(1, 'week')
= s.add(3, 'quarters')
= s.subtract(2, 'months').add(1,'day')
 
// start-of/end-of
= s.startOf('day') // 12:00am
= s.startOf('month') // 12:00am, April 1st
= s.endOf('quarter') // 11:59:59pm, June 30th
 
= s.nearest('hour')//round up/down to the hour
= s.nearest('quarter-hour')//5:15, 5:30, 5:45..
= s.next('month') //start-of the next month
= s.last('year') //start-of the last year
 
//utilities:
s.clone() // Make a copy
s.isValid() // Sept 32nd → false
s.isAwake() // it's between 8am → 10pm

Comparisons:

let s = spacetime([2017, 5, 2])
let start = s.subtract(1, 'milliseconds')
let end = s.add(1, 'milliseconds')
 
// gt/lt/equals
s.isAfter(d) // True
s.isEqual(d) // False
s.isBefore(d) // False
s.isBetween(start, end) // True
 
// Comparison by unit
s.isSame(d, 'year') // True
s.isSame(d, 'date') // False
s.diff(d, 'day') // 5
s.diff(d, 'month') // 0
 
//make a human-readable diff
let before = spacetime([2018, 3, 28])
let now = spacetime([2017, 3, 28]) //one year later
now.since(before)
/* {
    diff: {
      years: 0,
      months: 11,
      days: 30,
      hours: 23,
      minutes: 59,
      seconds: 59
    },
    rounded: 'in 12 months',
    qualified: 'in almost 12 months',
    precise: 'in 11 months, 30 days'
  }
*/

it's sometimes confusing how .diff() and .since() understand things:

spacetime('January 1 2017').diff('December 30 2016', 'year')
// returns 1
spacetime('January 1 2017').since('December 31 2016').diff
// returns {years:0, months:0, days:1}

Timezones:

// Roll into a new timezone, at the same moment
= s.goto('Australia/Brisbane')

this is the safest way to declare a timezone, using an IANA name.

Spacetime also supports more informal timezone names, like:

= s.goto('Jamaica') // "America/Jamaica"
= s.goto('Eastern Time') // "America/New_York"
= s.goto('PST') // automatically becomes 'PDT' in the summer
= s.goto('-7h') // UTC-7
= s.goto('GMT+8') // -8h!
= s.goto('bst') //"British summer time" +1 (sorry Bougainville!)
// (these should be used with some caution)
//list timezones by their \ time
spacetime.whereIts('8:30pm','9:30pm') // ['America/Winnipeg', 'America/Yellowknife'... ]
spacetime.whereIts('9am') //(within this hour)
 
// Timezone metadata
s.timezone().name // 'Canada/Eastern' (either inferred or explicit)
s.hemisphere() // North
s.timezone().current.offset // -4 (in hours)
s.hasDST() // True
s.isDST() // True
 
//list all timezones
s.timezones

Date Formatting:

// Date + time formatting
s.format('time') // '5:01am'
s.format('numeric-uk') // 02/03/2017
s.format('month') // 'April'
s.format('month-short') // 'Apr'
s.format('month-pad') // '04'
 
//if you want more complex formats, use {}'s
s.format('{year}-{date-pad}-{month-pad}') // '2018-02-02'
s.format('{hour} o\'clock') // '2 o'clock'
s.format('{time}{ampm} sharp') // '2:30pm sharp'
 
//if you prefer, you can also use unix-formatting
s.unixFmt('yyyy.MM.dd h:mm a')// '2017.Nov.16 11:34 AM'

Options

Ambiguity warnings:

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

let s = spacetime(123456, 'UTC', {
  silent: true
})
s.log() // "Jan 1st, 12:02am"

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.

let s = spacetime('2017-04-03T08:00:00-0700', 'Canada/Eastern', {
  silent: true
})
s.timezone().name // "Etc/GMT-7"

Extending/Plugins:

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

spacetime.extend({
  isHappyHour: function() {
    return this.hour() === 16
  }
})
 
let s = spacetime.now('Australia/Adelaide')
s.isHappyHour()
//false
 
= s.time('4:30pm')
s.isHappyHour()
//true

Custom languages:

a.i18n({
  days: {
    long: ['domingo', 'lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado'],
    short: ['dom', 'lun', 'mar', 'mié', 'jue', 'vie', 'sáb']
  },
  months: {
    long: [...],
    short: ['ene', 'feb', 'mar', 'abr', 'may', 'jun', 'jul', 'ago', 'sep', 'oct', 'nov', 'dic'],
  }
});
a.format('day') //'Sábado'

More info, considerations, & caveats

See also:

Thank you to the amazing timeanddate.com

Made with caution + great-patience,

Apache 2.0

Keywords

none

install

npm i spacetime

Downloadsweekly downloads

2,238

version

5.2.2

license

Apache-2.0

homepage

github.com

repository

Gitgithub

last publish

collaborators

  • avatar
  • avatar
  • avatar
Report a vulnerability