Skip to content

tc39/proposal-temporal

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Folders and files

NameName
Last commit message
Last commit date
Sep 27, 2024
Oct 30, 2024
Mar 13, 2024
Nov 1, 2024
Nov 1, 2024
Jun 29, 2023
Jun 29, 2023
Oct 4, 2021
Oct 4, 2021
May 23, 2023
Apr 13, 2020
Jan 9, 2024
Jan 20, 2021
Sep 24, 2024
Sep 24, 2024
Sep 25, 2024
Feb 25, 2022

Temporal

Provides standard objects and functions for working with dates and times.

Status

This proposal is currently Stage 3 and was reviewed for Stage 3 by Richard Gibson, Bradley Farias, and Daniel Ehrenberg.

This proposal is now in the hands of ECMAScript engine implementers, so the bar for making API changes is extremely high. Nonetheless, changes may occur as the result of feedback from implementation in JS engines. Editorial changes to the spec and bug fixes to the spec, tests, and docs are also ongoing, as is customary for Stage 3 proposals. Additional tests and documentation content are also being added during Stage 3.

Champions

Overview / Motivation

Date has been a long-standing pain point in ECMAScript. This proposes Temporal, a global Object that acts as a top-level namespace (like Math), that brings a modern date/time API to the ECMAScript language. For a detailed breakdown of motivations, see: Fixing JavaScript Date

Principles:

  • All Temporal objects are immutable.
  • Date values can be represented in local calendar systems (why?), but they should be convertable to and from the Proleptic Gregorian Calendar.
  • All time-of-day values are based on a standard 24-hour clock.
  • Leap seconds are not represented.

Specification Text

The specification text can be found here.

Documentation

Reference documentation and examples can be found below.

A cookbook to help you get started and learn the ins and outs of Temporal is available here

Polyfills

Polyfill Repo Status
@js-temporal/polyfill js-temporal/temporal-polyfill Alpha release available
temporal-polyfill fullcalendar/temporal-polyfill Beta release available

If you're working on a polyfill, please file an issue or PR so we can add yours here.

A non-production polyfill was built to validate this proposal. This polyfill continues to live in this repo, but only for the purposes of running tests and powering the documentation "playground" as described below.

DO NOT use this polyfill in your own projects! Instead, please use a polyfill from the table above.

Documentation Playground

When viewing the reference documentation, the non-production polyfill is automatically loaded in your browser, so you can try out Temporal by opening your browser's developer tools console.