Handling Timezone In JavaScript – Spacetime

Category: Date & Time , Javascript , Recommended | September 5, 2019
Author: spencermountain
Views Total: 2,196
Official Page: Go to website
Last Update: September 5, 2019
License: MIT

Preview:

Handling Timezone In JavaScript – Spacetime

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

// 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:

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

You Might Be Interested In:


Leave a Reply