Skip to content

Latest commit

 

History

History

temporal-2020-04

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
images
images
 
 
README.md
README.md
 
 
index.html
index.html
 
 

README.md

Temporal.Calendar

Welcome to Temporal! Let's start programming.

let date = Temporal.now.date();
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Nisan 6, 5780'

date = date.plus({months: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Iyar 6, 5780'

date = date.plus({months: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Sivan 7, 5780'

// 'Tamuz 8, 5780'
// 'Av 9, 5780'
// 'Elul 10, 5780'
// 'Tishri 12, 5781'

date = date.plus({years: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Tishri 24, 5782'

date = date.plus({years: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Tishri 5, 5783'
  • While everyone in 2020 mostly agrees with the concept of a solar day, months and years are concepts that are inherently calendar-dependent.
  • Any date-time arithmetic that is rooted in the ISO calendar involving months and years is bound to give unexpected results that will carry over poorly to other calendars.
  • TL:DR; any arithmetic with units larger than days cannot be satisfactorily done in a calendar-agnostic way.

We cannot have our cake and eat it too.

What are our options?

height:500px

What even is Temporal.Calendar?

  • Mechanism to allow arbitrary calendar systems to be implemented on top of Temporal.
  • This will be taken care of for most users out of the box, and doesn't require any extra know-how.
  • Can be used to implement non-built-in calendar systems.
  • Plan to expose non-ISO, commonly-used regional calendars via ECMA-402.
  • Everything else in userland.

What even is Temporal.Calendar?

How does it look like?

class MyCalendar extends Temporal.Calendar {
  id: string;

  // Projection
  toISO(input: Temporal.Date): Temporal.Date;
  fromISO(input: Temporal.Date): Temporal.Date;

  // Construction
  dateFromFields(fields: object): Temporal.Date;

  // Arithmetic
  plus(input: Temporal.Date, duration: Temporal.Duration, options: object): Temporal.Date;
  minus(input: Temporal.Date, duration: Temporal.Duration, options: object): Temporal.Date;
  difference(left: Temporal.Date, right: Temporal.Date, options: object): Temporal.Duration;

  // Accessors
}

What even is Temporal.Calendar?

How will it work? (using Temporal.Date as an example)

  • Previously, Temporal.Date had three internal slots: year, month and day.
  • Now, it has four slots: [[IsoYear]], [[IsoMonth]], [[IsoDay]] and [[Calendar]].
  • The corresponding fields on Temporal.Date.prototype should forward requests to the calendar.
  • Calendars can add calendar-specific accessors, eg: yearType for the Hebrew Calendar.
  • An instance is expected to have stateless behavior; i.e., all methods should be deterministic.
  • (There would be no mechanism to enforce this for userland calendars, but the author should ensure this in order to prevent unexpected behavior such as lack of round-tripping.)

What even is Temporal.Calendar?

How would people use it?

let date = Temporal.now.date();  // a Temporal.Date

console.log(date.withCalendar("iso").month);  // 11, i.e. November
console.log(date.withCalendar("hebrew").month);  // 2, i.e. Heshvan
console.log(date.withCalendar("japanese").era); // "reiwa"

What even is Temporal.Calendar?

How would people use it?

let date = Temporal.now.date();

console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Nisan 7, 5780'

date = date.withCalendar('hebrew');

date = date.plus({months: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Iyar 7, 5780'

date = date.plus({months: 1})
console.log(d.toLocaleString('en-US-u-ca-hebrew', {day: 'numeric', month: 'long', year: 'numeric'}));
// 'Sivan 7, 5780'

// 'Tamuz 7, 5780'
// 'Av 7, 5780'
// 'Elul 7, 5780'
// 'Tishri 7, 5781'

What even is Temporal.Calendar?

What about Lunar and Lunisolar calendars?

  • Temporal.Date has three components: Year, Month and Day.
  • Take out any one, and it becomes impossible to perform Calendar conversions.
  • Example: Rosh Hashanah, 1 Tishrei in the Hebrew Calendar.
    • 2019: 30th September
    • 2020: 19th September
    • 2021: 7th September
    • 2022: 26th September
  • Question: Eid al-Fitr, 1 Shawwal in the Islamic Calendar.
  • Answer: Don't even ask.

What even is Temporal.Calendar?

What about Lunar and Lunisolar calendars?

  • The above model solves all remaining issues with solar calendars.
  • Lunar and Lunisolar calendars don't have clear overlaps with ISO, therefore need more information to properly disambiguate.
  • We will add a [[RefIsoYear]] and [[RefIsoDay]] slot to Temporal.MonthDay and Temporal.YearMonth classes respectively, to assist disambiguation.
  • They will be ignored whenever they're not required.

Next Steps

  • Reach consensus on the last few standing issues.
  • Convert working draft into proper spec text.
  • Add calendar support to polyfill.