getWeeksInLocaleWeekYear

Signature

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

Return the number of weeks (52 or 53) in the locale week-numbering year containing value, from locale’s first day of week and a minimal-days-in-first-week rule.

getWeeksInYear’s locale-relative counterpart: that function uses the fixed ISO rule, this one uses locale’s first day of week, and the two can disagree on the same date.
Computed as the calendar days between this week-year’s start and the next one’s, divided by 7 — always whole, since both starts fall on the locale’s first day of week. Counted by day arithmetic, so a start outside the representable range still counts.
The minimal-days rule comes from the caller, never the runtime: ECMA-402 does not expose a locale’s minimal days (tc39/proposal-intl-locale-info#86). CLDR 48’s world default is 1 (US included) and 4 is set for mostly European regions; pass the locale’s value when you need its own rule. See getLocaleWeekYear.
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.

Parameters

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

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

Returns

52 or 53, or null on invalid input

Examples

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

getWeeksInLocaleWeekYear("2024-06-15", "en-US") // 52

Source

plain/calculate/getWeeksInLocaleWeekYear.ts