getFiscalPeriod

Signature

getFiscalPeriod(value: string, calendar: FiscalCalendar): { year: number; period: number; week: number; } | null

Return the fiscal year, period and week value falls in, for a 52/53-week retail calendar.

• 52 × 7 is 364 days, so a 52-week fiscal year drifts a day or two against the sun every year and a 53rd week is inserted every five or six to pull it back. Both the drift and the insertion fall out of calendar — nothing here is bundled, because there is no single correct retail calendar.
• calendar.pattern is the weeks-per-period shape of a quarter: "4-5-4" (the NRF retail standard), "4-4-5" or "5-4-4". Four quarters of 13 weeks make the 52-week year.
• calendar.yearEndsOn states the year-end rule, by example, not one year’s end. Fiscal years end on that date’s weekday, on the occurrence nearest that date’s month and day. The NRF’s published rule — “the Saturday nearest to January 31” (NRF 4-5-4 calendar) — is "2026-01-31", a Saturday falling exactly on January 31. Passing a published year end from a 53-week year instead ("2024-02-03") states a different rule, because that date sits three days off the target the rule is centred on, and yields a different, self-consistent calendar.
• Weeks are numbered through the fiscal year as the NRF publishes them. A 53rd week is appended to period 12 — the NRF adds it “to the end of the calendar” — which makes a 4-5-4 year’s final quarter 4-5-5.
• The year label follows the NRF: fiscal 2023 runs 2023-01-29 to 2024-02-03. Organisations labelling by the end year should add one.
• year is not a unique key for a rule anchored near 1 January. A 52/53-week year is 364 or 371 days, so it drifts against the calendar, and no label taken from a calendar year survives that for every anchor. Under yearEndsOn: "2022-12-31" — the Saturday nearest to 31 December — two consecutive fiscal years both start in 2023 and share the label, and 2020, 2025 and 2031 label no fiscal year at all. Grouping by year there merges 104 weeks and drops a year. "2027-01-02" states a different rule, the Saturday nearest to 2 January: it too gives 2023 twice, merging 105 weeks, and skips 2018, 2024 and 2029. January/February anchors like the NRF’s are unaffected. If your rule sits near a year boundary, key on the fiscal year’s own start date — which yearEndsOn determines, and which is yours to enumerate — not on year. GMT does not invent a label the inputs do not fix.
• A yearEndsOn month-day that does not exist in a year follows Temporal’s overflow: "constrain": a February 29 rule reads February 28 in common years. A rule tied to the end of a month (the weekday nearest to, or last in, the month’s final days) would put a February 28 anchor on February 29 in leap years; this does not — state such a rule with a date that exists every year.
• Whether a fiscal year has 52 or 53 weeks is derived from the gap between its own two ends, never assumed from a table.
• value must be zoneless — an ISO date or datetime, as isValidIsoDateLike accepts. See getIsoWeekDate for why a moment is not accepted here.
• Returns null on invalid input, including an unrecognised pattern or a yearEndsOn that is not a plain ISO date. Both share the sentinel with a date that cannot be placed, so check the calendar with isValidFiscalPattern and isValidDate first to tell a misconfigured calendar apart from an unusable date.

Parameters

Parameter	Type	Description
value	string	zoneless ISO 8601 date or datetime string (e.g. “2024-06-15”)
calendar	FiscalCalendar	{ pattern: “4-5-4” | “4-4-5” | “5-4-4”, yearEndsOn: ISO date stating the rule }

Returns

{ year, period, week }, or null on invalid input

Members

Member	Type	Description
year	number	The calendar year the fiscal year starts in, not the year it ends in. Two consecutive fiscal years can share this label when yearEndsOn sits near 1 January.
period	number	The period of the fiscal year, 1 through 12. Each period is four or five weeks long as calendar.pattern sets, and a 53rd week belongs to period 12.
week	number	The week of the fiscal year, 1 through 52, or 53 in a year with an inserted week. Week 1 starts on the fiscal year’s first day.

Types

FiscalCalendar

Caller-supplied 52/53-week fiscal calendar. GMT bundles none.

import type { FiscalCalendar } from "@northguild/gmt";

Member	Type	Description
pattern	"4-5-4" | "4-4-5" | "5-4-4" (FiscalPattern)	The weeks per period within each quarter.
yearEndsOn	string	The year-end rule, stated as one ISO date: fiscal years end on this date’s weekday, on the occurrence nearest this date’s month and day. For the NRF retail calendar — “the Saturday nearest to January 31” — that is "2026-01-31".

Related types

• FiscalPattern

Examples

import { getFiscalPeriod } from "@northguild/gmt/calendar/calculate";

getFiscalPeriod("2024-06-15", { pattern: "4-5-4", yearEndsOn: "2026-01-31" }) // { year: 2024, period: 5, week: 19 }

valuecalendar

output

 

Source

calendar/calculate/getFiscalPeriod.ts