getLocaleWeekYear

Signature

getLocaleWeekYear(value: string, locale: string | string[], options?: { minimalDays?: number; }): number | null

Return the locale-relative week-numbering year value belongs to, from locale’s first day of week and a minimal-days-in-first-week rule.

Distinct from value’s calendar year, for the same reason getWeekYear is: late-December and early-January dates can belong to a neighbouring week-year.
Week 1 is the week starting on locale’s first day of week that holds at least minimalDays days of January (UTS #35 Part 4, Week Data). The first day of week comes from Intl.Locale.prototype.getWeekInfo.
The minimal-days rule comes from the caller, never the runtime, so one input has one answer everywhere. ECMA-402 does not expose a locale’s minimal days: Intl Locale Info returns only firstDay and weekend (tc39/proposal-intl-locale-info#86), so older runtimes that still reported it disagreed with newer ones about the same date. Pass CLDR’s value when you need a locale’s own rule: in CLDR 48 weekData, the world default (001) is 1, as in US, CA, MX, JP and CN, and 4 is set for a list of mostly European regions such as GB, DE and FR.
Returns null if value or locale is invalid.
Compatibility: before 1.16.0 the default read the runtime’s minimalDays where one was exposed (Node 22), so a locale such as en-US got 1 there and 4 on Node 24 and later. Pass { minimalDays: 1 } to keep the Node 22 result for such a locale on every runtime.

Parameter	Type	Description
`value`	`string`	ISO PlainDate string
`locale`	`string` \| `string[]`	BCP 47 locale tag (e.g. “en-US”, “fr-FR”), or a preference list of tags (ECMA-402; the first with locale data is read). Required: omitted, or an empty list (which ECMA-402 would resolve to the host default), returns null

options

The minimal-days-in-first-week rule

Option	Type	Default	Description
`minimalDays?`	`number`	`4`	How many days of January the first week must hold to be week 1 (UTS #35 Part 4, Week Data). `4` is the ISO 8601 rule; `1` puts January 1 in week 1 every year, as CLDR’s world default does. A value that is not an integer from 1 to 7 returns `null`.

locale-relative week-numbering year, or null on invalid input

import { getLocaleWeekYear } from "@northguild/gmt/plain/calculate";

getLocaleWeekYear("2024-06-15", "en-US") // 2024