Temporal.Calendar.weeksInYear method

ptomato commented 3 years ago

Previous discussion at https://github.com/tc39/proposal-temporal/issues/634 and https://github.com/tc39/proposal-temporal/issues/1058.

Similar to Temporal.Calendar.monthsInYear() and the associated monthsInYear properties on types that have a year (PlainDate, PlainDateTime, PlainYearMonth, ZonedDateTime), the proposal is to add a weeksInYear() method to Temporal.Calendar and weeksInYear properties to the types that have a year.

Proposed semantics would be to return the integer number of the last week of the year. Alternatively, the number of weeks in the "week year" that the date falls in. (For example, 2021-01-01 is in week 53 of 2020 in the ISO calendar week-numbering rules.)

Also needed would be a yearOfWeek() method which returns the week year, or a weekYearOffset() method which returns the difference between the week year and the calendar year.

Advantages:

It's currently not possible to get this information in Temporal. This means that it's not possible to correctly output an ISO year-week-day date, since the year would need to be the week year.

Numbered weeks of the year are fairly commonly used in business contexts in Europe.

Concerns:

See "corner cases" below. This would have to be defined very carefully.

Prior art:

Week year: IYYY in PostgreSQL formatting

Constraints / corner cases:

In the ISO calendar and others based on it, there isn't an integer number of weeks in any particular year.
If dealing with ISO week years, it would be ill-defined which week year a Temporal.PlainYearMonth would fall in.

ptomato commented 3 years ago

Added some information from https://github.com/tc39/proposal-temporal/issues/1374.

khawarizmus commented 4 months ago

If it can help in any way the week-date library I made has this supported both for ISO calendar in Hijri week Calendar (HWC).

You can see both implementation and documentation here: https://github.com/zamanapp/week-dates

js-temporal / proposal-temporal-v2