temporal-polyfill

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

Only 20 kB, spec compliant

Table of Contents

• Installation
• Comparison with @js-temporal/polyfill
• Spec Compliance
• Browser Support
• BigInt Considerations
• Tree-shakable API (coming soon)

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

• 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 support. Internally, no operations leverage BigInt arithmetics. 👍

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 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) // not how you normally call a method!