Class: Weekday

Enumeration for the days of the week.

A Weekday behaves like an enumeration of the seven weekdays. Calling implementation: calling the constructor or Weekday.from() with a value returns one of the predefined singletons (e.g. Weekday.MONDAY). The class provides numerous helpers for navigating and comparing weekdays, including methods that return the next/previous occurrence, compute the distance between days, and translate between Date objects and weekday values.

Input values accepted everywhere include: - an integer 0–6 (or any integer, will be taken modulo 7) - a floating-point number interpreted as a Unix timestamp in seconds - a string containing either a day name (case-insensitive) or an ISO date (YYYY-MM-DD) - a Date object - another Weekday instance

Invalid or unrecognizable inputs will cause the factory methods to throw a TypeError or RangeError.

All public operations are synchronous and side‑effect free.

Examples:

Weekday.from(0) === Weekday.MONDAY;
Weekday.from("2024-01-01"); // Monday
Weekday.from(new Date(2024, 0, 1)); // Monday
Weekday.MONDAY.next(); // Tuesday
Weekday.FRIDAY.next([Weekday.MONDAY, Weekday.WEDNESDAY]); // Monday

Properties

value

readonly value: number

Defined in: utils/days.ts:64

The internal value of the weekday, normalized to the range 0..6. This is used for all internal calculations and comparisons.

FRIDAY

readonly static FRIDAY: Weekday

Defined in: utils/days.ts:76

MONDAY

readonly static MONDAY: Weekday

Defined in: utils/days.ts:72

SATURDAY

readonly static SATURDAY: Weekday

Defined in: utils/days.ts:77

SUNDAY

readonly static SUNDAY: Weekday

Defined in: utils/days.ts:78

THURSDAY

readonly static THURSDAY: Weekday

Defined in: utils/days.ts:75

TUESDAY

readonly static TUESDAY: Weekday

Defined in: utils/days.ts:73

WEDNESDAY

readonly static WEDNESDAY: Weekday

Defined in: utils/days.ts:74

Methods

closest()

closest(day?): number

Defined in: utils/days.ts:367

Days to the closest occurrence of day, positive for future, negative for past.

If day equals this returns 0. This method chooses the shorter of the forward (until) and backward (since) distances; when equal the forward distance is returned.

Parameters

day?

target weekday.

DayInput | Weekday | null

Returns

number

signed distance in days.

Example

Weekday.MONDAY.closest(Weekday.FRIDAY); // -3 (closest is previous)
Weekday.MONDAY.closest(Weekday.SUNDAY); // 6

closest_date()

closest_date(from_date?): Date

Defined in: utils/days.ts:461

Closest calendar date with this weekday (past or future).

Parameters

from_date?

reference date; defaults to today.

DayInput | null

Returns

Date

Example

Weekday.MONDAY.closest_date("2024-01-03"); // 2024-01-01

furthest()

furthest(day?): number

Defined in: utils/days.ts:391

Signed days to the furthest occurrence of day from this.

The complement of closest; returns 7 if day === this.

Parameters

day?

target weekday.

DayInput | Weekday | null

Returns

number

signed distance in days.

Example

Weekday.MONDAY.furthest(Weekday.FRIDAY); // 4 (Friday in future)
Weekday.MONDAY.furthest(Weekday.MONDAY); // 7

furthest_date()

furthest_date(from_date?): Date

Defined in: utils/days.ts:484

Furthest calendar date with this weekday from from_date.

When from_date already matches the weekday, the result is exactly one week later.

Parameters

from_date?

DayInput | null

Returns

Date

Example

Weekday.MONDAY.furthest_date("2024-01-01"); // 2024-01-08

next()

next(days?): Weekday

Defined in: utils/days.ts:268

Get the next weekday after this, optionally restricted to a set of days.

If days is null or undefined, simply returns the following day of the week (e.g. Monday → Tuesday). When a target or collection of targets is provided, the method finds the next occurrence among them, wrapping back to the first candidate if necessary.

Parameters

days?

target day(s) as a DayInput or iterable thereof.

DayInput | Weekday | Iterable\<DayInput | Weekday, any, any> | null

Returns

Weekday

the Weekday representing the next day.

Throws

TypeError when an element of days cannot be converted.

Example

Weekday.WEDNESDAY.next(); // Thursday
Weekday.WEDNESDAY.next(Weekday.MONDAY); // Monday (wraps)
Weekday.FRIDAY.next([1, 3]); // Tuesday (1=Tuesday,3=Thursday)

next_date()

next_date(from_date?, closest?): Date

Defined in: utils/days.ts:416

Calculate the next calendar date falling on this weekday.

Parameters

from_date?

starting point (see Weekday.get_date); defaults to today when omitted.

DayInput | null

closest?

boolean = false

if true, return from_date when it already matches.

Returns

Date

a Date for the next matching weekday.

Throws

TypeError/RangeError from Weekday.get_date on invalid input.

Example

Weekday.FRIDAY.next_date("2024-01-03"); // 2024-01-05
Weekday.WEDNESDAY.next_date(new Date(2024, 0, 3), true); // same day

previous()

previous(days?): Weekday

Defined in: utils/days.ts:294

Get the previous weekday before this, optionally restricted to targets.

Behavior mirrors next but searches backward; wrapping occurs when no earlier candidate exists.

Parameters

days?

single or multiple DayInput targets.

DayInput | Weekday | Iterable\<DayInput | Weekday, any, any> | null

Returns

Weekday

the previous matching Weekday.

Throws

TypeError when an element of days cannot be converted.

previous_date()

previous_date(from_date?, closest?): Date

Defined in: utils/days.ts:439

Calendar date of the previous occurrence of this weekday.

Parameters mirror next_date.

Parameters

from_date?

DayInput | null

closest?

boolean = false

Returns

Date

Example

Weekday.MONDAY.previous_date("2024-01-03"); // 2024-01-01
Weekday.WEDNESDAY.previous_date(new Date(2024,0,3), true); // same day

since()

since(day?): number

Defined in: utils/days.ts:345

Number of days since the previous occurrence of a given weekday.

Works like until but counts backward; result spans 1..7.

Parameters

day?

target weekday.

DayInput | Weekday | null

Returns

number

days since last target.

Example

Weekday.WEDNESDAY.since(Weekday.MONDAY); // 2
Weekday.MONDAY.since(Weekday.MONDAY); // 7

toString()

toString(): string

Defined in: utils/days.ts:503

Return the uppercase name of the weekday (e.g. "MONDAY").

This is primarily useful for debugging and logging.

Returns

string

until()

until(day?): number

Defined in: utils/days.ts:326

Number of days until the next occurrence of a given weekday.

If day is omitted the current weekday is used. The returned value is in the range 1..7 (returning 7 if the target is the same as this).

Parameters

day?

target weekday (see class description).

DayInput | Weekday | null

Returns

number

days until next target.

Example

Weekday.WEDNESDAY.until(Weekday.FRIDAY); // 2
Weekday.MONDAY.until(Weekday.MONDAY); // 7

from()

static from(value?): Weekday

Defined in: utils/days.ts:163

Create a Weekday instance from a variety of inputs.

A static factory wrapper that provides a more descriptive name than a direct constructor call and centralizes conversion logic.

Parameters

value?

optional weekday input (see class description); undefined or null yields the current day.

DayInput | Weekday | null

Returns

Weekday

the corresponding singleton Weekday.

Throws

TypeError if value is not convertible.

Example

Weekday.from("monday");
Weekday.from(5); // Saturday

get_date()

static get_date(from?): Date

Defined in: utils/days.ts:196

Normalize a DayInput into a native Date object.

The argument may be a timestamp (number), an ISO date string, or a Date instance; null/undefined returns new Date() (today). This helper is shared by the weekday/date methods below.

Parameters

from?

input value to coerce.

DayInput | null

Returns

Date

the corresponding Date.

Throws

TypeError if the argument is of an unsupported type.

Throws

RangeError if a string is not a valid ISO date.

Example

Weekday.get_date("2024-01-01");
Weekday.get_date(1672531200); // seconds since epoch

get_day()

static get_day(value?): Weekday

Defined in: utils/days.ts:174

Identical to from; included as an alternate name for clarity, matching other public APIs.

Parameters

value?

see from

DayInput | Weekday | null

Returns

Weekday

the corresponding Weekday.

today()

static today(): Weekday

Defined in: utils/days.ts:226

Return the current weekday using the system clock.

Returns

Weekday

the Weekday corresponding to new Date().getDay().