feat(datetime): add iso week support

[timreichen]

Adds w and ww week iso token support for parsing and formatting. I am not too sure if this implementation takes care of all edge cases. I would be grateful if someone could take a look and maybe even add more test cases.

[jsejcksn]

Reference: ISO week date - Wikipedia

In order to be able to represent ISO week dates, introduction of additional tokens are necessary because the ISO week year number is not the same as the Gregorian (local) year number. Here's an example:

// year is same
new Date(2022, 11, 31) // Sat 31 Dec 2022, ISO week year = 2022, ISO week number = 52, day of week = 6

// year differs
new Date(2023,  0,  1) // Sun  1 Jan 2023, ISO week year = 2022, ISO week number = 52, day of week = 7

// year is same
new Date(2023,  0,  2) // Mon  2 Jan 2023, ISO week year = 2023, ISO week number =  1, day of week = 1

Discrete tokens should be made available for…

• ISO week year
• ISO week number
• day of week

…in order to parse and format standard ISO week date strings like:

new Date(2023,  0,  1) // ISO week date format: "2022-W52-7"

For reference, here's an excerpt from Luxon's table of tokens:

(Examples below given for 2014-08-06T13:07:04.054 considered as a local time in America/New_York).

Standalone token	Format token	Description	Example
c	E	day of the week, as number from 1-7 (Monday is 1, Sunday is 7)	3
ccc	EEE	day of the week, as an abbreviate localized string	Wed
cccc	EEEE	day of the week, as an unabbreviated localized string	Wednesday
ccccc	EEEEE	day of the week, as a single localized letter	W
y		year, unpadded	2014
yy		two-digit year	14
yyyy		four- to six- digit year, pads to 4	2014
kk		ISO week year, unpadded	14
kkkk		ISO week year, padded to 4	2014
W		ISO week number, unpadded	32
WW		ISO week number, padded to 2	32
ii		Local week year, unpadded	14
iiii		Local week year, padded to 4	2014
n		Local week number, unpadded	32
nn		Local week number, padded to 2	32

[timreichen]

Reference: ISO week date - Wikipedia

In order to be able to represent ISO week dates, introduction of additional tokens are necessary because the ISO week year number is not the same as the Gregorian (local) year number. Here's an example:

// year is same
new Date(2022, 11, 31) // Sat 31 Dec 2022, ISO week year = 2022, ISO week number = 52, day of week = 6

// year differs
new Date(2023,  0,  1) // Sun  1 Jan 2023, ISO week year = 2022, ISO week number = 52, day of week = 7

// year is same
new Date(2023,  0,  2) // Mon  2 Jan 2023, ISO week year = 2023, ISO week number =  1, day of week = 1

Discrete tokens should be made available for…

• ISO week year
• ISO week number
• day of week

…in order to parse and format standard ISO week date strings like:

new Date(2023,  0,  1) // ISO week date format: "2022-W52-7"

For reference, here's an excerpt from Luxon's table of tokens:

(Examples below given for 2014-08-06T13:07:04.054 considered as a local time in America/New_York).

Standalone token Format token Description Example

c E day of the week, as number from 1-7 (Monday is 1, Sunday is 7) 3

ccc EEE day of the week, as an abbreviate localized string Wed

cccc EEEE day of the week, as an unabbreviated localized string Wednesday

ccccc EEEEE day of the week, as a single localized letter W

y

year, unpadded 2014

yy

two-digit year 14

yyyy

four- to six- digit year, pads to 4 2014

kk

ISO week year, unpadded 14

kkkk

ISO week year, padded to 4 2014

W

ISO week number, unpadded 32

WW

ISO week number, padded to 2 32

ii

Local week year, unpadded 14

iiii

Local week year, padded to 4 2014

n

Local week number, unpadded 32

nn

Local week number, padded to 2 32

Oh, I see. Hmm,

Reference: ISO week date - Wikipedia

In order to be able to represent ISO week dates, introduction of additional tokens are necessary because the ISO week year number is not the same as the Gregorian (local) year number. Here's an example:

// year is same
new Date(2022, 11, 31) // Sat 31 Dec 2022, ISO week year = 2022, ISO week number = 52, day of week = 6

// year differs
new Date(2023,  0,  1) // Sun  1 Jan 2023, ISO week year = 2022, ISO week number = 52, day of week = 7

// year is same
new Date(2023,  0,  2) // Mon  2 Jan 2023, ISO week year = 2023, ISO week number =  1, day of week = 1

Discrete tokens should be made available for…

• ISO week year
• ISO week number
• day of week

…in order to parse and format standard ISO week date strings like:

new Date(2023,  0,  1) // ISO week date format: "2022-W52-7"

For reference, here's an excerpt from Luxon's table of tokens:

(Examples below given for 2014-08-06T13:07:04.054 considered as a local time in America/New_York).

Standalone token Format token Description Example

c E day of the week, as number from 1-7 (Monday is 1, Sunday is 7) 3

ccc EEE day of the week, as an abbreviate localized string Wed

cccc EEEE day of the week, as an unabbreviated localized string Wednesday

ccccc EEEEE day of the week, as a single localized letter W

y

year, unpadded 2014

yy

two-digit year 14

yyyy

four- to six- digit year, pads to 4 2014

kk

ISO week year, unpadded 14

kkkk

ISO week year, padded to 4 2014

W

ISO week number, unpadded 32

WW

ISO week number, padded to 2 32

ii

Local week year, unpadded 14

iiii

Local week year, padded to 4 2014

n

Local week number, unpadded 32

nn

Local week number, padded to 2 32

Hmm, I see. Is there an official standard for these tokens?

[jsejcksn]

Is there an official standard for these tokens?

@timreichen I found the Unicode Date Field Symbol Table (UTS report, ICU Docs), but it doesn't include the ISO week calendar variants.

strftime in C and in Python are completely different from the token list used by Luxon. I shared the Luxon list because the team has had many years to carefully consider the newer (breaking) token choices when compared to what was used in Moment.js.

[timreichen]

Is there an official standard for these tokens?

@timreichen I found the Unicode Date Field Symbol Table (UTS report, ICU Docs), but it doesn't include the ISO week calendar variants.

strftime in C and in Python are completely different from the token list used by Luxon. I shared the Luxon list because the team has had many years to carefully consider the newer (breaking) token choices when compared to what was used in Moment.js.

Hmm, the current implementation uses LDML symbols. The problem is that Luxon uses W and WW for iso week, which is not compatible with LDML, as W is for Week of Month.

[jsejcksn]

Hmm, the current implementation uses LDML symbols.

Is this coincidental or was it intentional?

The problem is that Luxon uses W and WW for iso week, which is not compatible with LDML, as W is for Week of Month.

Is compatibility with LDML a requirement? Supporting the ISO week calendar means using tokens that don't exist in that spec now, and will risk breaking compatibility in the future case that they're added to LDML and differ from what is chosen here. I think that offering support for missing features is more useful than rigid compatibility.

[timreichen]

Hmm, the current implementation uses LDML symbols.

Is this coincidental or was it intentional?

The problem is that Luxon uses W and WW for iso week, which is not compatible with LDML, as W is for Week of Month.

Is compatibility with LDML a requirement? Supporting the ISO week calendar means using tokens that don't exist in that spec now, and will risk breaking compatibility in the future case that they're added to LDML and differ from what is chosen here. I think that offering support for missing features is more useful than rigid compatibility.

I am not sure if this is LDML a requirement. But I think it would be a good idea std to follow an established standards in general. Weird that there seems to be no standardized tokens for iso week and friends...

[timreichen]

@jsejcksn might your use case be possible to solve with the now supported temporal?

[jsejcksn]

@jsejcksn might your use case be possible to solve with the now supported temporal?

@timreichen No(t yet), refer to https://github.com/denoland/deno_std/issues/3928#issuecomment-1888285565

[iuioiua]

What's the current status of this PR, @timreichen?

[timreichen]

What's the current status of this PR, @timreichen?

Apparently this PR doesn't solve the raised issue. So it can be closed imo. Or do we want to add support for w and ww in any case?

[iuioiua]

Ok. Let's close this. Thanks for the input @timreichen and @jsejcksn.