Author: | spencermountain |
---|---|
Views Total: | 1 view |
Official Page: | Go to website |
Last Update: | April 18, 2025 |
License: | MIT |
Preview:

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 s = spacetime.min() // the earliest-possible date (271,821 bc) s = spacetime.max() // 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:
v7.10.0 (04/18/2025)
- [fix] – capitalization of “Etc/Utc”
- [new] – .isoFull() method
- [new] – spacetime.fromEpochSeconds() method
- [fix] – getter form of .epochSeconds()
v7.9.0 (04/06/2025)
- [new] – .format(‘sql’)
- [new] – .epochSeconds()
- [fix] – duplicate type for .json()
v7.8.0 (12/01/2024)
- [fix] – 2025 DST-change times for many zones
- [fix] – more .week() issues from
- [new] – initial support for Temporal’s extended-iso RFC3339 fmt
- [new] – adds .format(‘iso-full’) for Temporal support
- [new] – support hot-swap timezone via .timezone(tz)
- [new] – add tz/offset info in .json() response
- [new] – support .json(obj) setter fn
- [fix] – proper capitalization of UTC in .timezone() response
- [fix] – typescript fixes
- [update] – dependencies
v7.7.7 (12/01/2024)
- [fix] – .week() issue
- [update] – 2025 DST changes
- [update] – greenland Nuuk DST change
- [update] – alias choibalsan to ulaanbaatar
v7.6.2 (10/10/2024)
- [fix] – isEqual null on 1970-01-01
v7.6.1 (07/31/2024)
- [new] – add stepCount paramater to .every()
- [update] – minor DST hour changes
- [update] – dependencies
v7.6.0 (02/13/2024)
- [fix] – leap-year string parse issue
- [change] – typescript export changes
- [update] – DST date changes for metlakatla, kiev, ciudad_juarez
- [update] – late DST date changes for gaza, hebron 1
v7.5.0 (12/11/2023)
- 2024 DST changes
- [fix] – offset in Africa/Cairo
- [change] – support i18n config in .since()
v7.4.8 (10/16/2023)
- [fix] – fix for reversed-DST in africa/casablanca and africa/el_aaiun
v7.4.7 (08/23/2023)
- Bugfix
v7.4.6 (08/10/2023)
- Added new zone: America/Ciudad_Juarez
v7.4.5 (07/28/2023)
- [fix] – typescript node16 issue
- [update] – moroccan and palestinian dst dates
- [update] – africa/cairo is back on DST
- [update] – deps
v7.4.4 (05/29/2023)
- Bugfixes
v7.4.3 (04/13/2023)
- [fix] – support leap-years in setting dayOfYear()
v7.4.2 (03/31/2023)
- [change] – Iran off of dst
- [change] – mexico off of dst
- [change] – allow chaining of .i18()
- [change] – typescript update
v7.4.1 (02/02/2023)
- [update] – add etc/unknown timezone
v7.4.0 (12/31/2022)
- [update] – 2023 DST changes for mexico
- [update] – 2023 DST changes for jordan
- [update] – 2023 DST changes for fiji
- [update] – missing seconds, quarters methods
- [new] – {AMPM} uppercase fmt
v7.3.0 (12/09/2022)
- [update] – 2023 DST changes
- [fix] – southern hemisphere december season
- [fix] – Yakutsk timezone
v7.2.0 (09/14/2022)
- [update] – timezone aliases
- [update] – dst changes
- update dependencies
v7.1.4 (04/19/2022)
- bugfixes
v7.1.3 (04/12/2022)
- [fix] – typescript fixes
- [change] – update asia/gaza and asia/hebron dst times
- update dependencies
v7.1.2 (03/01/2022)
- Bugfix
v7.1.1 (02/27/2022)
- [new] – support custom i18n strings for am/pm
- [new] – more alias support for deprecated iana codes
- [fix] – for silent/verbose mode
- update deps
v7.1.0 (01/13/2022)
- [change] – rename cjs build to .cjs
v7.0.2 (01/07/2022)
- Bugfix
v7.0.0 (01/06/2022)
- [change] – update to 2022 DST dates
- [change] – return ‘Sep’ instead of ‘Sept’ in format(‘month-short’) and ‘MMM’
- [change] – convert to ES-modules, + exports fields
- [change] – make .every() results inclusive of start
- [change] – alias old IANA codes to contemporary ones
- [change] – move cal plugin to repo spencermountain/scal
- [new] – add ISO duration to .since() results (thanks Adam)
- [fix] – iso-parsing issues
- [fix] – typescript issue
- [fix] – subtract months issue
- [fix] – unix ‘yy’ format issue
- [change] – return ‘Etc/GMT’ not ‘Etc/GMT+0’
- [change] – update deps
v6.16.3 (08/07/2021)
- [new] – .daysInMonth() method
- [change] – replace deprecated timezone aliases
- [change] – date/day naming inconsistency in add method
- [fix] – typescript fixes
- [fix] – many-year add issue
- [fix] – iso format year-padding for BC years
v6.16.2 (06/14/2021)
- [fix] – offset for asia/baku
- [fix] – date-parser for String parser off by 12 hours in some cases
- update deps
v6.16.1 (05/11/2021)
- [new] – add millisecond pad
v6.16.0 (04/16/2021)
- [change] – improvements to date-sting parsers
- [change] – drop ie11 polyfills in min.js build
- [change] – minify and stop compiling esm build
v6.15.2 (04/14/2021)
- [fix] – .add(n, ‘weekend’)
- update deps
v6.15.1 (04/08/2021)
- [fix] – Fix pacific/chatham iana DST change time
v6.15.0 (04/07/2021)
- [fix] – .time(‘4:88’) now has ceiling of 59m
- [new] – add goFwd params to all (appropriate) setter methods
v6.14.0 (03/13/2021)
- [change] – add missing timezones from indiana and argentina
- [change] – set old timezones as aliases of newer ones
- [new] – add min, max methods
- [change] – comment-out tests that were failing in some timezones
v6.13.1 (03/06/2021)
- hotfix for 0.5 date infinite-loop
v6.13.0 (03/02/2021)
- [change] – support more alt day formats like
.day('mo')
- [change] – allow
.week()
to return 53 - [change] – support swapped-parameters for
.each()
- [change] – support swapped-parameters for
.isSame()
- update deps
v6.12.5 (02/11/2021)
- [fix] – add/minus by quarter issue
v6.12.4 (02/10/2021)
- [fix] – typescript issue
v6.12.3 (02/04/2021)
- [fix] – fix .every() >= issue
- [fix] – fix today-passthrough in some date formats
- [change] – use updated DST changes
- [change] – support explicit local-timezone
- update deps
v6.12.2 (12/19/2020)
- [change] – support explicit local-timezone
- [change] – support i18n titlecase config
- [fix] – endOf(‘season’) issue
- [fix] – fix character escaping issue in unixFmt method
v6.12.1 (12/02/2020)
- [new] – support for ’97 year format
- [change] – support 13h00 time format
- [change] – support 09.13.2013 and 13.09.2013 formats
- [fix] – .add() issue sometimes effecting quarter/season
v6.11.0 (11/26/2020)
- [change] – support 6-digit millisecond, and lowercase iso
- [change] – first week of year must start > dec 29th
- [fix] – typescript fixes
v6.10.1 (11/21/2020)
- [fix] – keep yukon dst changes
- [fix] – support new-zealand time in ’13h’ format
- update deps
v6.10.0 (11/14/2020)
- [fix] – support whitespace between time and am/pm
- [change] – make empty array + obj equal to null inputs
- [change] – update timezones
- [change] – remove Yukon DST preemptively
v6.9.0 (11/05/2020)
- [fix] – dst-change issues like
- [fix] – inc/dec year issue on exact nye millisecond
- [change] support parsing quarter-names as input
- [change] support parsing season-names as input
v6.8.0 (10/29/2020)
- [fix] major DST issue
v6.7.0 (10/27/2020)
- add missing timezones America/Fort_Nelson, Asia/Qostanay, and America/Nuuk
- fix comparison issue #231 effecting .isSame() and .since() accross different timezones
v6.6.4 (09/15/2020)
- [fix] 45m offset formatting issue
v6.6.3 (08/29/2020)
- support for ‘today’ param with null inputs
- support for ‘today’ param with ‘today/tonight’ inputs
- interpret empty-string input like null input (as ‘now’)
- typescript fixes
v6.6.2 (07/31/2020)
- [fix] for formatting when the output is 0
- [fix] for leap-day in .date() method
- update deps
v6.6.1 (06/27/2020)
- typescript fix
v6.6.0 (06/12/2020)
- support undefined as input (like null)
- fix for missing defaults in object input
- fix major DST add/subtract bug
v6.4.2 (03/28/2020)
- update
v6.4.1 (01/31/2020)
- update
v6.3.0 (11/07/2019)
- fix date calculation
v6.2.1 (11/07/2019)
- update
v6.2.0 (11/02/2019)
- update
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