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 is near-perfect with just 4 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!