https://github.com/fullcalendar/temporal-polyfill
A lightweight polyfill for Temporal, successor to the JavaScript Date object
https://github.com/fullcalendar/temporal-polyfill
Last synced: 4 months ago
JSON representation
A lightweight polyfill for Temporal, successor to the JavaScript Date object
- Host: GitHub
- URL: https://github.com/fullcalendar/temporal-polyfill
- Owner: fullcalendar
- License: mit
- Created: 2021-05-04T04:15:57.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-04-13T15:49:25.000Z (over 1 year ago)
- Last Synced: 2024-05-23T02:39:43.037Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 6.64 MB
- Stars: 179
- Watchers: 8
- Forks: 13
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome - fullcalendar/temporal-polyfill - A lightweight polyfill for Temporal, successor to the JavaScript Date object (TypeScript)
README
# temporal-polyfill
A lightweight polyfill for [Temporal](https://tc39.es/proposal-temporal/docs/), successor to the JavaScript `Date` object
Only 20 kB, [spec compliant](#spec-compliance)
## Table of Contents
- [Installation](#installation)
- [Comparison with `@js-temporal/polyfill`](#comparison-with-js-temporalpolyfill)
- [Spec Compliance](#spec-compliance)
- [Browser Support](#browser-support)
- [BigInt Considerations](#bigint-considerations)
- [Tree-shakable API](#tree-shakable-api) (coming soon)
## Installation
```
npm install temporal-polyfill
```
Import as an ES module without side effects:
```js
import { Temporal } from 'temporal-polyfill'
console.log(Temporal.Now.zonedDateTimeISO().toString())
```
Or, import globally:
```js
import 'temporal-polyfill/global'
console.log(Temporal.Now.zonedDateTimeISO().toString())
```
Use a `` tags with a CDN link:
```html
<script src='https://cdn.jsdelivr.net/npm/temporal-polyfill@0.3.0/global.min.js'>
console.log(Temporal.Now.zonedDateTimeISO().toString())
```
## 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
19.8 KB
51.9 KB (+162%)
Spec date
Mar 2025
Mar 2025
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 is near-perfect [with just 4 intentional deviations](https://github.com/fullcalendar/temporal-polyfill/blob/main/packages/temporal-polyfill/scripts/test262-config/expected-failures.txt).
## 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, 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) support. Internally, no operations leverage BigInt arithmetics. :thumbsup:
However, if you plan to use methods that accept/emit BigInts, your environment must support it. Alternatively, you can avoid using these methods altogether. [There's a cheatsheet](https://gist.github.com/arshaw/1ef4bf945d68654b86cef2dd8471c48f) 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.
```js
import * as ZonedDateTime from 'temporal-polyfill/fns/zoneddatetime'
const zdt = ZonedDateTime.from({ year: 2024, month: 1, day: 1 })
const s = ZonedDateTime.toString(zdt) // not how you normally call a method!
```