Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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: 3 months ago
JSON representation

A lightweight polyfill for Temporal, successor to the JavaScript Date object

Awesome Lists containing this project

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/[email protected]/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

    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](https://github.com/fullcalendar/temporal/blob/main/packages/temporal-polyfill/scripts/test262-config/expected-failures.txt).

- There are believed to be 3 bugs in the Temporal spec itself. See SPEC-BUG entries in the [test-skip file](https://github.com/fullcalendar/temporal/blob/main/packages/temporal-polyfill/scripts/test262-config/expected-failures.txt).

- `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](https://github.com/tc39/test262) has:



- 7102 *total* Temporal-related test files

- 6477 *passed* by `temporal-polyfill`

- 491 *skipped* due to superficial method descriptor non-compliance

- 134 *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, 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!

```