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

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

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 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!