temporal-polyfill
A lightweight polyfill for Temporal, successor to the JavaScript Date
object
Only 20 kB, spec compliant
Table of Contents
Installation
npm install temporal-polyfill
Import as an ES module without side effects:
import { Temporal } from 'temporal-polyfill'
console.log(Temporal.Now.zonedDateTimeISO().toString())
Or, import globally:
import 'temporal-polyfill/global'
console.log(Temporal.Now.zonedDateTimeISO().toString())
Use a <script>
tags with a CDN link:
<script src='https://cdn.jsdelivr.net/npm/temporal-polyfill@0.2.4/global.min.js'></script>
<script>
console.log(Temporal.Now.zonedDateTimeISO().toString())
</script>
Comparison with @js-temporal/polyfill
Package |
temporal-polyfill
|
@js-temporal/polyfill
|
Repo |
fullcalendar/temporal-polyfill
|
js-temporal/temporal-polyfill
|
Creators | FullCalendar lead dev arshaw | Champions of the Temporal proposal |
Minified+gzip size | 20 KB | 56 KB (+180%) |
Spec compliance |
Strict compliance for built-in types.
Relaxed compliance for subclassing built-in types.
|
Strict compliance for entire API.
|
Spec date |
Apr 2024
|
May 2023
|
BigInt approach | Internally avoids BigInt operations altogether | Internally relies on JSBI |
Global usage in ESM |
import 'temporal-polyfill/global'
| Not currently possible |
Spec Compliance
All calendar systems (ex: chinese
, persian
) and all time zones are supported.
Compliance with the latest version of the Temporal spec (Apr 2024) is near-perfect with the following intentional deviations:
- Custom implementations of Calendars and TimeZones are queried differently. Only affects those subclassing built-in classes, which is extremely rare. See the CALLING entries in the test-skip file.
- There are believed to be 3 bugs in the Temporal spec itself. See SPEC-BUG entries in the test-skip file.
Intl.DateTimeFormat
has not been polyfilled to accept number-offset values for the timeZone
option.- Method descriptors and
Function::length
are not strictly compliant due to ES-related space-saving techniques.
The Official ECMAScript Conformance Test Suite has:
- 7100 total Temporal-related test files
- 6463 passed by
temporal-polyfill
- 491 skipped due to superficial method descriptor non-compliance
- 146 skipped due to other aforementioned intentional deviations
Browser Support
Minimum required browsers for ISO/gregory calendars:
|
Chrome 60 (Jul 2017) | Firefox 55 (Aug 2017) | Safari 11.1 (Mar 2018) | Safari iOS 11.3 (Mar 2018) | Edge 79 (Jan 2020) | Node.js 14 (Apr 2020) |
If you transpile, you can support older browsers down to:
|
Chrome 57 (Mar 2017) | Firefox 52 (Mar 2017) | Safari 10 (Sep 2016) | Safari iOS 10 (Sep 2016) | Edge 15 (Apr 2017) | Node.js 14 (Apr 2020) |
For non-ISO/gregory calendars to work, requirements are higher:
|
Chrome 80 (Feb 2020) | Firefox 76 (May 2020) | Safari 14.1 (Apr 2021) | Safari iOS 14.5 (Apr 2021) | Edge 80 (Feb 2020) | Node.js 14 (Apr 2020) |
BigInt Considerations
This polyfill does NOT depend on BigInt support. Internally, no operations leverage BigInt arithmetics. :thumbsup:
However, if you plan to use methods that accepting/emitting BigInts, your environment must support it. Alternatively, you can avoid using these methods altogether. There's a cheatsheet to help you.
Tree-shakable API
🚧 Coming Soon
For library authors and other devs who are hyper-concerned about bundle size, temporal-polyfill
will be providing an alternate API designed for tree-shaking.
import * as ZonedDateTime from 'temporal-polyfill/fns/zoneddatetime'
const zdt = ZonedDateTime.from({ year: 2024, month: 1, day: 1 })
const s = ZonedDateTime.toString(zdt)