/temporal-polyfill

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

Primary LanguageTypeScript

temporal-polyfill

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

Only 20 kB, with near-perfect spec compliance.

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.3/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 common API.
Relaxed compliance for subclassing
built-in types. 		Strict compliance for entire API.
Spec date Mar 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 time zones are supported.

Compliance with the latest version of the Temporal spec (Nov 2023) is near-perfect with the following intentional deviations:

  • Duration::toString does not display units greater than Number.MAX_SAFE_INTEGER according to spec. Precision is chosen differently.
  • 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, one of which has been reported. 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:

  • 6968 total Temporal-related test files
  • 6327 passed by temporal-polyfill
  • 495 skipped due to superficial method descriptor non-compliance
  • 146 skipped due to other aforementioned intentional deviations

Browser Support

Minimum required browsers:
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)

BigInt Considerations

This polyfill works fine in environments that do not support BigInt.

However, to use methods that accept/emit them, your browser must support BigInt.

Here's how to sidestep this browser compatibility issue:

❌ Avoid microseconds/nanoseconds ✅ Use milliseconds instead
instant.epochMicroseconds instant.epochMilliseconds
instant.epochNanoseconds instant.epochMilliseconds
Temporal.Instant.fromEpochMicroseconds(micro) Temporal.Instant.fromEpochMilliseconds(milli)
Temporal.Instant.fromEpochNanoseconds(nano) Temporal.Instant.fromEpochMilliseconds(milli)
new Temporal.Instant(nano) Temporal.Instant.fromEpochMilliseconds(milli)
zonedDateTime.epochMicroseconds zonedDateTime.epochMilliseconds
zonedDateTime.epochNanoseconds zonedDateTime.epochMilliseconds
new Temporal.ZonedDateTime(nano, tz, cal) Temporal.Instant.fromEpochMilliseconds(milli)
  .toZonedDateTimeISO() // or toZonedDateTime

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!