getDatesForDay

`getDatesForDay()`

Returns ISO date strings or Chronos instances for each occurrence of a weekday.

Signature

// Relative range signature
static getDatesForDay<F extends ISODateFormat | 'chronos' = 'local'>(
    day: WeekDay,
    options?: RelativeRangeOptions<F>
): DateRangeResult<F>;

// Absolute range signature
static getDatesForDay<F extends ISODateFormat | 'chronos' = 'local'>(
    day: WeekDay,
    options?: DateRangeOptions<F>
): DateRangeResult<F>;

Parameters

Parameter	Type	Required	Default	Description
`day`	`WeekDay`	✅	-	Target weekday name (case-sensitive)
`span`	`number`	❌	`4`	Number of time units for relative range
`unit`	`TimeUnit`	❌	`'week'`	Unit for relative range ('day'/'week'/'month'/'year')
`from`	`ChronosInput`	❌	Current date	Start date for absolute range
`to`	`ChronosInput`	❌	4 weeks from now	End date for absolute range
`format`	`'local'\|'utc'\|'chronos'`	❌	`'local'`	Output format for ISO strings or `Chronos` instances
`roundDate`	`boolean`	❌	`false`	Round dates to start of day

Common Parameter

day: The weekday to match (case-sensitive full day name)
- Type: WeekDay ('Monday' | 'Tuesday' | ... | 'Sunday')
- Example: 'Wednesday', 'Friday'

Options (Differ by Signature)

interface RelativeRangeOptions {
  span?: number;    // Duration quantity (default: 4)
  unit?: TimeUnit;  // 'day' | 'week' | 'month' | 'year' (default: 'week')
  format?: 'local' | 'utc' | 'chronos'; // Output format (default: 'local')
  roundDate?: boolean; // Round to start of day (default: false)
}

Return Type

DateRangeResult<F> - Array of ISO date strings or Chronos instances based on the format option.

Tips

When format is chronos, the method returns an array of Chronos instances.
Thus you can call any method of Chronos on each element of the returned array.
Note: Each Chronos instance will be in the same time zone as the original instance.

Behavior

Finds all occurrences of the specified weekday within:
- A relative time span from now (when using span/unit)
- Or between two fixed dates (when using from/to)
Returns dates in chronological order
Empty array if no matches found in range

Note

When using Chronos instances for from and/or to, ensure both are created in the same time zone to avoid mismatched boundaries.
Mixing zones may shift the interpreted start or end by several hours, which can cause the range to include or exclude incorrect weekdays.

Examples

playground.ts

Notes

When format: 'local' (default):
- Output includes local timezone offset (e.g., +06:00)
- Uses toLocalISOString() internally
When format: 'utc':
- Output is in UTC/Zulu time (ends with Z)
- Uses toISOString() internally
When format: 'chronos':
- Output is an array of Chronos instances
- Each instance preserves the original metadata
The method always starts searching from:
- Current date (for relative ranges)
- The from date (for absolute ranges)
Weekday names must exactly match: 'Monday', 'Tuesday', etc. (case-sensitive English day-names)
When roundDate: true, all times are set to 00:00:00
Default range is 4 weeks when no dates specified

Similar Instance Method

getDatesInRange

On this page