getWeekNumber

Signature

getWeekNumber(dateStr: string, weekStartsOn?: "monday" | "sunday"): number | null

Calculate the week number based on configurable week start day.

• "monday" (default) is the ISO 8601 week of the week-year: week 1 is the week containing the first Thursday, so late-December days can be week 1 of the next year ("2024-12-31" → 1). The result is 1–53.
• "sunday" is the UTS #35 (Part 4, Week Data) week of the week-year with a Sunday first day and minimal days 1: week 1 is the Sunday-first week containing 1 January, so the last days of December before a mid-week 1 January are week 1 of the next year ("2024-12-31" → 1, "2000-12-31" → 1). The result is 1–53.
• weekStartsOn other than "monday" or "sunday" returns null; undefined is the default.
• Returns null for invalid input, including every shape isValidDate rejects: a date-time, zoned, basic-format or leap-second string, or a non-ISO calendar annotation. The annotations Temporal ignores are accepted ("2024-06-15[u-ca=iso8601]" → 24).
• Compatibility: earlier releases read those shapes loosely ("2024-03-15T10:00" → 11). Pass the date part alone, or use Temporal.PlainDate.from(value).weekOfYear.
• Compatibility: before 1.16.0 "sunday" counted weeks within the calendar year with no week-year rollover, so late-December days could be week 53 or 54.

Parameters

Parameter	Type	Description
dateStr	string	ISO PlainDate string (e.g. “2024-03-15”)
weekStartsOn	"monday" | "sunday"	optional: “monday” (default) or “sunday”

Returns

Week number (1-53), or null on invalid input

Examples

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

getWeekNumber("2024-01-01") // 1

dateStr

output

 

Source

plain/calculate/getWeekNumber.ts