diff --git a/ai/contributing/decisions-index.md b/ai/contributing/decisions-index.md index f552d89..b08eef3 100644 --- a/ai/contributing/decisions-index.md +++ b/ai/contributing/decisions-index.md @@ -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. @@ -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) diff --git a/ai/contributing/decisions.md b/ai/contributing/decisions.md index a060aea..ebbc0af 100644 --- a/ai/contributing/decisions.md +++ b/ai/contributing/decisions.md @@ -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) diff --git a/docs/src/content/docs/guides/formatting.md b/docs/src/content/docs/guides/formatting.md index d8bd215..944e11a 100644 --- a/docs/src/content/docs/guides/formatting.md +++ b/docs/src/content/docs/guides/formatting.md @@ -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. @@ -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. | diff --git a/docs/src/content/docs/guides/from-dayjs.md b/docs/src/content/docs/guides/from-dayjs.md index 2b3cfd5..308fd3a 100644 --- a/docs/src/content/docs/guides/from-dayjs.md +++ b/docs/src/content/docs/guides/from-dayjs.md @@ -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. @@ -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 @@ -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 | diff --git a/docs/src/content/docs/guides/from-moment.md b/docs/src/content/docs/guides/from-moment.md index 88f7314..5227563 100644 --- a/docs/src/content/docs/guides/from-moment.md +++ b/docs/src/content/docs/guides/from-moment.md @@ -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. @@ -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 | diff --git a/docs/src/content/docs/guides/internationalization.md b/docs/src/content/docs/guides/internationalization.md index e9ce706..76f6ffd 100644 --- a/docs/src/content/docs/guides/internationalization.md +++ b/docs/src/content/docs/guides/internationalization.md @@ -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 diff --git a/src/helpers/tokens.js b/src/helpers/tokens.js index b43a2ac..f902ba0 100644 --- a/src/helpers/tokens.js +++ b/src/helpers/tokens.js @@ -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]], diff --git a/test/format/tokens.test.js b/test/format/tokens.test.js index 29d4f5f..d6c40d8 100644 --- a/test/format/tokens.test.js +++ b/test/format/tokens.test.js @@ -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'); }); @@ -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( @@ -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}'` }), ); @@ -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' })); } });