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.14%. Comparing base (7bb3552) to head (43a42ca).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6910   +/-   ##
=======================================
  Coverage   94.14%   94.14%           
=======================================
  Files         583      583           
  Lines       42806    42825   +19     
  Branches     6815     6815           
=======================================
+ Hits        40300    40318   +18     
- Misses       2456     2457    +1     
  Partials       50       50           

☔ 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.