feat(datetime): add month and day of week constants

[a-skua]

Summary

Add month index constants (JAN-DEC) and day of week constants (SUN-SAT) to @std/datetime/constants.

Motivation

In many languages and cultures (such as Japanese, Chinese, and Korean), months are referred to by their ordinal numbers: January is "1月" (month 1), February is "2月" (month 2), and so on.

However, JavaScript's Date object uses 0-based indices for months (0 = January, 11 = December). This mismatch between human intuition and the API frequently leads to off-by-one bugs:

// Intended: March 1st, 2025
// Actual: April 1st, 2025 (oops!)
new Date(2025, 3, 1)

By providing named constants, developers can write clearer, less error-prone code:

import { MAR } from "@std/datetime/constants";

new Date(2025, MAR, 1)  // unambiguously March

import { SAT, SUN } from "@std/datetime/constants";

const day = date.getDay();
if (day === SAT || day === SUN) {
    console.log("It's the weekend!");
}

Changes

• Add month constants: JAN (0) through DEC (11)
• Add day of week constants: SUN (0) through SAT (6)

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.16%. Comparing base (232ad45) to head (a8e5658).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6910   +/-   ##
=======================================
  Coverage   94.15%   94.16%           
=======================================
  Files         583      583           
  Lines       42792    42811   +19     
  Branches     6815     6815           
=======================================
+ Hits        40292    40314   +22     
+ Misses       2448     2446    -2     
+ Partials       52       51    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[timreichen]

Interesting proposal.
I am not sure if that makes sense for std because I think a chunk of the datetime mod will become deprecated after Temporal becomes stable. Temporal fixed the 0-based month confusion by making months 1 based, which ironically would make these constants create off-by-one bugs when initializing dates:

new Temporal.PlainDate(2025, MAR, 1); // incorrect month

[a-skua]

Thank you for pointing that out — I hadn't fully considered the Temporal API implications.

That said, I'm curious about the timeline: even after Temporal stabilizes, when would Date actually become deprecated?
I think, Date will remain in use for quite a while.

To avoid future confusion, what do you think about providing these constants under a more specific path, such as @std/datetime/date/constants? This would make it explicit that these constants are intended for use with the legacy Date API, not Temporal.

-import { MAR } from "@std/datetime/constants";
+import { MAR } from "@std/datetime/date/constants";

new Date(2025, MAR, 1)  // unambiguously March

I fully agree with removing these constants once they are no longer needed.

[kt3k]

Can you make the example more practical one like new Date(2025, MAR, 1);?

[a-skua]

Updated the examples to show practical usage: a8e5658

[kt3k]

I don't think Date will be deprecated, but @std/datetime can be deprecated in the future (We haven't completely decided yet though).

I checked major date libraries such as moment.js, date-fns, day.js, and found that they all still use 0-based month index. I guess maybe these constants still have some utilities. Anyways @std/datetime is still unstable package. I would say let's try them.

[kt3k]

LGTM

[timreichen]

I think the const names should not be abbreviated.

[a-skua]

I understand the preference for non-abbreviated names, but I think:

1. In web development, shorter names can be beneficial — especially when dealing with bundle sizes or when these constants are used frequently in code.
2. Within the @std/datetime module, abbreviations like JAN, FEB, SUN, MON are unambiguous. There's no realistic scenario where these could be misinterpreted as something other than month/day-of-week indices.

[timreichen]

I understand the preference for non-abbreviated names, but I think:

1. In web development, shorter names can be beneficial — especially when dealing with bundle sizes or when these constants are used frequently in code.

2. Within the @std/datetime module, abbreviations like JAN, FEB, SUN, MON are unambiguous. There's no realistic scenario where these could be misinterpreted as something other than month/day-of-week indices.

It is more about consistency in std.
Bundle sizes should not be a concern because bundlers generally are capable of changing declaration names on minification.

[a-skua]

Addressed in #6939