nextWeekday

Signature

nextWeekday(value: string, dayOfWeek: number, options?: { inclusive?: boolean; }): string

Return a PlainDate ISO string for the next occurrence of dayOfWeek on or after value.

dayOfWeek uses Temporal’s ISO numbering: 1 (Monday) through 7 (Sunday), consistent with getDayOfWeek/parseDayOfWeekFromDate.

Returns "" on invalid input. Replaces date-fns’s sixteen next* functions with one parameterized call:

date-fns	gmt
`nextMonday`	`nextWeekday(value, 1)`
`nextTuesday`	`nextWeekday(value, 2)`
`nextWednesday`	`nextWeekday(value, 3)`
`nextThursday`	`nextWeekday(value, 4)`
`nextFriday`	`nextWeekday(value, 5)`
`nextSaturday`	`nextWeekday(value, 6)`
`nextSunday`	`nextWeekday(value, 7)`
`nextDay(v, n)`	`nextWeekday(value, n)`

Parameters

Parameter	Type	Description
`value`	`string`	ISO PlainDate string
`dayOfWeek`	`number`	target ISO day of week (1-7, Monday-Sunday)

Options

options

Whether value itself can be the result

Option	Type	Default	Description
`inclusive?`	`boolean`	`false`	Whether `value` counts when it already falls on `dayOfWeek`. `true` returns `value` unchanged; `false` advances a full week.

Returns

ISO PlainDate string for the next occurrence of dayOfWeek, or "" on invalid input

Examples

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

nextWeekday("2024-03-15", 5) // "2024-03-22" (2024-03-15 is already a Friday, so it advances a full week)

Source

plain/calculate/nextWeekday.ts