Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions ai/contributing/decisions-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Active decisions grouped by area, newest first.
- [L117](decisions.md#adjacent-unit-boundaries-use-startofnext-and-startofprevious-instead-of-overloading-next-and-previous-2026-11-19) · Adjacent unit boundaries use `startOfNext()` and `startOfPrevious()` instead of overloading `next()` and `previous()` (2026-11-19)
- Reopen: callers consistently try unit names in `next()` and `previous()`, or expect numeric weekdays in `startOfNext()`.
- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17)
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` returns `7`, or request the `E` token.
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`.
- [L57](decisions.md#default-week-boundaries-follow-the-locale-while-weekofyear-stays-iso-monday-2026-11-14) · Default week boundaries follow the locale while `weekOfYear` stays ISO Monday (2026-11-14)
- Reopen: server code accidentally partitions stored weekly aggregates differently across requests carrying different `.locale()` tags.

Expand Down Expand Up @@ -95,7 +95,7 @@ Every entry in file order.
- [L93](decisions.md#unix-timestamp-properties-include-their-unit-epochseconds-epochmilliseconds-epochnanoseconds-with-no-bare-epoch-2026-11-17) · Unix timestamp properties include their unit (`epochSeconds`, `epochMilliseconds`, `epochNanoseconds`) with no bare `.epoch` (2026-11-17)
- Reopen: migration feedback shows omitting `.epoch` causes widespread friction without preventing real seconds-vs-milliseconds bugs.
- [L99](decisions.md#numeric-day-of-the-week-is-dayofweek-1-7-while-token-d-keeps-moments-0-6-2026-11-17) · Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17)
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` returns `7`, or request the `E` token.
- Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`.
- [L105](decisions.md#duration-uses-balance-without-a-normalize-alias-and-totalunit-instead-of-inunit-2026-11-17) · `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17)
- Reopen: cold-reader studies or user issues show callers repeatedly reaching for `duration.in(unit)` or `duration.normalize()`.
- [L111](decisions.md#ranges-accept-for-for-durations-alongside-to-and-only-calendardate-has-through-2026-11-17) · Ranges accept `.for()` for durations alongside `.to()`, and only `CalendarDate` has `.through()` (2026-11-17)
Expand Down
4 changes: 2 additions & 2 deletions ai/contributing/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,9 +98,9 @@ Reopen: migration feedback shows omitting `.epoch` causes widespread friction wi

## Numeric day of the week is `dayOfWeek` (`1`-`7`) while token `d` keeps Moment's `0`-`6` (2026-11-17)

Naming the `1`-`7` property `.weekday` made `sunday.weekday` return `7` while `sunday.isWeekday()` returned `false`, and collided with custom display names in `configure({ weekdayNames })`. Format token `d` keeps `0` = Sunday through `6` = Saturday to match Moment and Day.js token strings, omitting the ISO `1`-`7` token `E` until requested.
Naming the `1`-`7` property `.weekday` made `sunday.weekday` return `7` while `sunday.isWeekday()` returned `false`, and collided with custom display names in `configure({ weekdayNames })`. Format token `d` keeps `0` = Sunday through `6` = Saturday to match Moment and Day.js alongside `E` for ISO `1`-`7`.

Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` returns `7`, or request the `E` token.
Reopen: callers hit bugs from `format('d')` returning `0` on Sunday while `.dayOfWeek` and `format('E')` return `7`.

## `Duration` uses `balance()` without a `normalize()` alias, and `total(unit)` instead of `in(unit)` (2026-11-17)

Expand Down
5 changes: 3 additions & 2 deletions docs/src/content/docs/guides/formatting.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Formatting
lede: Format dates, times, ranges, and durations with Intl presets, locale tags, token patterns, and relative phrases.
updated: 2026-11-16
updated: 2026-11-20
---

Native Dates uses the platform's built-in `Intl` formatters and caches them automatically. You get localized output across languages and regions without adding locale files to your bundle.
Expand Down Expand Up @@ -128,7 +128,8 @@ Month and weekday names inside token patterns come from `Intl` in the active loc
| `D`, `DD` | `'5'`, `'05'` | Day of the month, unpadded or zero-padded. |
| `Do` | `'16th'` | Day of the month with English ordinals, the locale's day marker like `'6.'` or `'6日'`, or custom [`ordinals`](/api/configure/). |
| `DDD`, `DDDD` | `'320'`, `'045'` | Day of the year, unpadded or zero-padded to three digits. |
| `d` | `'1'` | Day of the week from 0 to 6, starting on Sunday at 0. |
| `E` | `'7'` | ISO day of the week from 1 on Monday through 7 on Sunday, matching `dayOfWeek`. |
| `d` | `'0'` | Day of the week from 0 on Sunday through 6 on Saturday, matching Moment and Day.js. |
| `dd`, `ddd`, `dddd` | `'Mo'`, `'Mon'`, `'Monday'` | Localized shortest, abbreviated, or full weekday name, customizable via [`weekdayNames`](/api/configure/). |
| `W`, `WW` | `'47'`, `'05'` | ISO week of the year, unpadded or zero-padded. |
| `H`, `HH` | `'9'`, `'09'` | Hour on the 24-hour clock, unpadded or zero-padded. |
Expand Down
6 changes: 3 additions & 3 deletions docs/src/content/docs/guides/from-dayjs.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Coming from Day.js
lede: Replace dayjs() wrappers and plugin chains with dedicated date types, 1-indexed months, built-in ranges, and zero-setup time zones.
updated: 2026-11-12
updated: 2026-11-20
---

Day.js wraps a JavaScript date in a single `dayjs()` object and adds time zones, UTC, ranges, and durations through plugins. Moving here keeps the lightweight, immutable style while giving calendar days, clock times, moments, partial dates, ranges, and durations their own types in core.
Expand Down Expand Up @@ -43,7 +43,7 @@ d.dayOfWeek; // 1, Monday
```

:::warning[Check month and weekday numbers]
Day.js numbers months from 0 to 11 and starts weekdays on Sunday at 0. Here, `month` runs from 1 through 12, and `dayOfWeek` runs from 1 on Monday through 7 on Sunday.
Day.js numbers months from 0 to 11 and starts weekdays on Sunday at 0. Here, `month` runs from 1 through 12, and `dayOfWeek` runs from 1 on Monday through 7 on Sunday. In token patterns, `'E'` prints ISO 1 through 7 while `'d'` keeps Day.js's 0 through 6.
:::

## Time zones, durations, and ranges built in
Expand Down Expand Up @@ -99,7 +99,7 @@ date('Nov 16, 2026', { loose: true }); // CalendarDate(2026-11-16)
|---|---|---|
| `dayjs()` | `now()` or `today()` | Choose an exact moment or a calendar day |
| `d.month()`, `d.date()` | `d.month`, `d.day` | Plain properties with months from 1 to 12 |
| `d.day()`, `d.isoWeekday()` | `d.dayOfWeek` | ISO day of the week from 1 on Monday to 7 on Sunday |
| `d.day()`, `d.isoWeekday()` | `d.dayOfWeek` | ISO 1 on Monday to 7 on Sunday, with tokens `'E'` for 1–7 and `'d'` for 0–6 |
| `d.unix()`, `d.valueOf()` | `dt.epochSeconds`, `dt.epochMilliseconds` | Each count since 1970 names its unit |
| `d.add(2, 'day')` | `d.plus(2, 'days')` | `add()` and `subtract()` aliases also work |
| `dayjs.tz(x, zone)` | `datetime(x, zone)` | Built into core with no `timezone` plugin |
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/guides/from-moment.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Coming from Moment
lede: Move off Moment and moment-timezone to immutable values, built-in tokens and ranges, zero bundled timezone data, and incremental Date interop.
updated: 2026-11-12
updated: 2026-11-20
---

Moment and `moment-timezone` carried JavaScript date handling for years, at the cost of mutable objects, zero-indexed months, and heavy timezone bundles.
Expand Down Expand Up @@ -88,7 +88,7 @@ quarter.overlaps(date('2026-12-15').to('2027-01-15')); // true
| `m.clone().add(7, 'days')` | `d.plus(7, 'days')` | Always immutable, and `add()` alias works too |
| `m.tz('Europe/Berlin')` | `dt.in('Europe/Berlin')` | Views the same moment in another zone |
| `m.month()`, `m.date()` | `d.month`, `d.day` | Plain properties with months from 1 to 12 |
| `m.day()`, `m.isoWeekday()` | `d.dayOfWeek` | ISO day of the week from 1 on Monday to 7 on Sunday |
| `m.day()`, `m.isoWeekday()` | `d.dayOfWeek` | ISO 1 on Monday to 7 on Sunday, with tokens `'E'` for 1–7 and `'d'` for 0–6 |
| `m.unix()`, `m.valueOf()` | `dt.epochSeconds`, `dt.epochMilliseconds` | Each count since 1970 names its unit |
| `b.diff(a, 'hours', true)` | `a.until(b, 'hours')` | Fractional total in the requested unit |
| `moment.duration(2, 'h')` | `hours(2)` or `duration('2h')` | Built into core |
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/internationalization.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ function weekKey(day) {
}
```

ISO week numbers read from `weekOfYear` and the `'W'` token always count weeks from Monday.
ISO week numbers from `weekOfYear` and `'W'` always count weeks from Monday. ISO weekday numbers from `dayOfWeek` and `'E'` follow the same Monday-first numbering.

## One-off calendar and dialect overrides

Expand Down
1 change: 1 addition & 0 deletions src/helpers/tokens.js
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@ const tokenReaders = {
DDD: ['dayOfYear', (subject) => String(subject.dayOfYear)],
DDDD: ['dayOfYear', (subject) => pad(subject.dayOfYear, 3)],
d: ['dayOfWeek', (subject) => String(subject.dayOfWeek % 7)], // Sunday = 0 (Moment/Day.js convention)
E: ['dayOfWeek', (subject) => String(subject.dayOfWeek)],
dd: ['dayOfWeek', (subject, locale) => names(locale).dd[subject.dayOfWeek - 1]],
ddd: ['dayOfWeek', (subject, locale) => names(locale).ddd[subject.dayOfWeek - 1]],
dddd: ['dayOfWeek', (subject, locale) => names(locale).dddd[subject.dayOfWeek - 1]],
Expand Down
14 changes: 11 additions & 3 deletions test/format/tokens.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,14 @@ describe('weekday and ISO week tokens', () => {
expect(date('2026-11-14').format('d')).toBe('6');
});

it('formats E as ISO day of the week from 1 for Monday through 7 for Sunday', () => {
expect(standup.format('E')).toBe('1');
expect(friday.format('E')).toBe('5');
expect(date('2026-11-14').format('E')).toBe('6');
expect(date('2026-11-15').format('E')).toBe('7');
expect(datetime('2026-11-15T20:00', 'America/Los_Angeles').format('E')).toBe('7');
});

it('formats dd, ddd, and dddd as narrow, short, and long weekday names', () => {
expect(date('2026-11-16').format('dd ddd dddd', 'en-US')).toBe('Mo Mon Monday');
});
Expand Down Expand Up @@ -258,7 +266,7 @@ describe('invalid patterns and unsupported tokens', () => {
);
});

it.each(['HH:mm:ss.SSSSSS', 'YYYYYY', 'MMMMM', 'SSSS', 'hhh', 'ZZZ', 'DDDo'])(
it.each(['HH:mm:ss.SSSSSS', 'YYYYYY', 'MMMMM', 'SSSS', 'hhh', 'ZZZ', 'DDDo', 'EE'])(
'throws unknownFormat for overlong repeated token pattern %j',
(pattern) => {
expect(() => standup.format(pattern)).toThrowError(
Expand All @@ -280,7 +288,7 @@ describe('invalid patterns and unsupported tokens', () => {
});

it('throws unsupportedToken when formatting Time with date, week, or timezone tokens', () => {
for (const token of ['YYYY', 'MMMM', 'D', 'dddd', 'W', 'Z']) {
for (const token of ['YYYY', 'MMMM', 'D', 'E', 'dddd', 'W', 'Z']) {
expect(() => time('17:30').format(token)).toThrowError(
expect.objectContaining({ code: 'unsupportedToken', at: `${token} in '${token}'` }),
);
Expand All @@ -297,7 +305,7 @@ describe('invalid patterns and unsupported tokens', () => {
});

it('throws unsupportedToken when formatting MonthDay with weekday, day-of-year, or week tokens', () => {
for (const token of ['d', 'dddd', 'DDD', 'W']) {
for (const token of ['d', 'E', 'dddd', 'DDD', 'W']) {
expect(() => monthDay('11-16').format(token)).toThrowError(expect.objectContaining({ code: 'unsupportedToken' }));
}
});
Expand Down