rollDate

Signature

rollDate(value: string, convention: RollConvention, calendar: BusinessCalendar): string

Move a local date onto a working day according to convention.

Every industry answers “what if it lands on a non-working day” differently, so the convention is always explicit — there is no default.

Convention	Behaviour
`following`	Forward to the next working day; a working day is left alone
`modifiedFollowing`	Forward, unless that crosses into the next month, then backward
`preceding`	Backward to the previous working day; a working day is left alone
`modifiedPreceding`	Backward, unless that crosses into the previous month, then forward
`endOfMonth`	The last working day of `value`’s own month, wherever in the month it falls
`none`	Return `value` unadjusted, working day or not

following and preceding are on or after and on or before: they return value itself when it is already a working day. For the strict neighbours use nextBusinessDay and previousBusinessDay.
following, modifiedFollowing and preceding are the three conventions ISDA 2006 Definitions §4.12(a) defines, in (i)–(iii), and match that text: (iii) reads “if ‘Preceding’ is specified, that date will be the first preceding day that is a Business Day”. §4.12(a) has no Modified Preceding; modifiedPreceding follows FpML’s BusinessDayConventionEnum MODPRECEDING: “adjusted to the first preceding day that is a business day unless that day falls in the previous calendar month, in which case … the first following day”. none is what OpenGamma Strata calls NO_ADJUST. No TC39, ECMA or RFC standard governs them.
endOfMonth is not an ISDA business-day convention, and not the industry “EOM rule”, which is a schedule rule: hold every date in a schedule to its month’s last day once the anchor is one. It is GMT’s primitive for building that rule. It always snaps to the last working day on or before the month’s final day, even from mid-month — leaving the month only if that whole month is closed, as a works shutdown would make it. A forward from a month-end anchor settles on the last working day of the target month, so the caller tests the anchor for month-end and applies this to the unadjusted target. Applied to a month-end date it agrees with modifiedFollowing.
value and calendar.holidays are local dates; calendar.timeZone is not read. A caller holding an instant reduces it to a local date first, with floorToZone.
Returns "" when value is not a valid ISO PlainDate, when convention is not one GMT implements, when calendar is not a valid BusinessCalendar, and when the walk runs past 200,000 calendar days without finding a working day. Narrow the convention with isValidRollConvention to tell a misconfigured contract term apart from a bad date.

Parameters

Parameter	Type	Description
`value`	`string`	ISO PlainDate string to roll
`convention`	`RollConvention`	RollConvention to apply
`calendar`	`BusinessCalendar`	BusinessCalendar naming the weekend days and holidays

Returns

ISO PlainDate string of the rolled date, or "" on invalid input

Examples

import { rollDate } from "@northguild/gmt/calendar/business";

rollDate("2024-05-31", "following", { weekend: [6, 7], holidays: ["2024-05-31"], timeZone: "America/New_York" }) // "2024-06-03"

Source

calendar/business/rollDate.ts