Temporal

Table of Contents

Introduction

Date has been a long-standing pain point in ECMAScript. This is a proposal for 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 look at some of the problems with Date, and the motivations for Temporal, see: Fixing JavaScript Date.

Temporal fixes these problems by:

Cookbook

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

API Documentation

Temporal.Absolute

A Temporal.Absolute represents a fixed point in time, without regard to calendar or location.

See Temporal.Absolute Documentation for more detailed documentation.

Temporal.TimeZone

A Temporal.TimeZone represents an IANA time zone, a specific UTC offset or UTC itself. Because of this Temporal.TimeZone can be used to convert between Temporal.Absolute and Temporal.DateTime as well as finding out the offset at a specific Temporal.Absolute.

See Temporal.TimeZone Documentation for more detailed documentation.

Temporal.DateTime

A Temporal.DateTime represents a calendar date and wall-clock time. That means it does not carry time zone information. However it can be converted to a Temporal.Absolute using a Temporal.TimeZone.

This can also be converted to object containing only partial information such as Temporal.Date and Temporal.Time.

See Temporal.DateTime Documentation for more detailed documentation.

Temporal.Time

A Temporal.Time object represents a wall-clock time. Since there is no date component this can not be directly translated to an absolute point in time. However it can be converted to a Temporal.Absolute by combining with a Temporal.Date using a Temporal.TimeZone.

See Temporal.Time Documentation for more detailed documentation.

Temporal.Date

A Temporal.Date object represents a calendar date. This means there is no way to convert this to an absolute point in time, however combining with a Temporal.Time a Temporal.DateTime can be obtained which in turn can be pinned to the absolute timeline.

This can also be converted to partial dates such as Temporal.YearMonth and Temporal.MonthDay.

See Temporal.Date Documentation for more detailed documentation.

Temporal.YearMonth

A date without a day component. This is useful to express things like "the November 2010 meeting".

See Temporal.YearMonth Documentation for more detailed documentation.

Temporal.MonthDay

A date without a year component. This is useful to express things like "Bastille-Day is on the 14th of July".

See Temporal.MonthDay Documentation for more detailed documentation.

Temporal.Duration

A Temporal.Duration expresses a length of time. This is used for date/time maths.

See Temporal.Duration Documentation for more detailed documentation.

Temporal.now

See Temporal.now Documentation for more detailed documentation.

Temporal.Calendar

A Temporal.Calendar represents a calendar system. Most code will use the ISO 8601 calendar, but other calendar systems are available.

See Temporal.Calendar Documentation for more detailed documentation.

Object Relationship

graph LR; timezone(TimeZone); subgraph " "; absolute(Absolute); end; subgraph " "; datetime(DateTime); date(Date); yearmonth(YearMonth); monthday(MonthDay); time(Time); datetime --- date; datetime --- time; date --- yearmonth; date --- monthday; end; absolute === timezone; timezone === datetime;