Interface: Interval<IsValid>

An Interval object represents a half-open interval of time, where each endpoint is a DateTime. Conceptually, it is a container for those two endpoints, accompanied by methods for creating, parsing, interrogating, comparing, transforming, and formatting them.

Here is a brief overview of the most commonly used methods and getters in Interval:

Creation To create an Interval, use Interval.fromDateTimes, Interval.after, Interval.before, or Interval.fromISO.
Accessors Use Interval#start and Interval#end to get the start and end.
Interrogation To analyze the Interval, use Interval#count, Interval#length, Interval#hasSame,
Interval#contains, Interval#isAfter, or Interval#isBefore.
Transformation To create other Intervals out of this one, use Interval#set, Interval#splitAt, Interval#splitBy, Interval#divideEqually,
Interval.merge, Interval.xor, Interval#union, Interval#intersection, or Interval#difference.
Comparison To compare this Interval to another one, use Interval#equals, Interval#overlaps, Interval#abutsStart, Interval#abutsEnd, Interval#engulfs
Output To convert the Interval into other representations, see Interval#toString, Interval#toLocaleString, Interval#toISO, Interval#toISODate,
Interval#toISOTime, Interval#toFormat, and Interval#toDuration.

Type Parameters

Type Parameter	Default type
`IsValid` extends `boolean`	`DefaultValidity`

Accessors

end

Get Signature

get end(): IfValid<DateTime<true>, null, IsValid>;

Returns the end of the Interval. This is the first instant which is not part of the interval. (Interval is half-open).

Returns

IfValid<DateTime<true>, null, IsValid>

invalidExplanation

Get Signature

get invalidExplanation(): IfValid<null, string | null, IsValid>;

Returns an explanation of why this Interval became invalid, or null if the Interval is valid

Returns

IfValid<null, string | null, IsValid>

invalidReason

Get Signature

get invalidReason(): IfValid<null, string, IsValid>;

Returns an error code if this Interval is invalid, or null if the Interval is valid

Returns

IfValid<null, string, IsValid>

isValid

Get Signature

get isValid(): IfValid<true, false, IsValid>;

Returns whether this Interval's end is at least its start, meaning that the Interval isn't 'backwards'.

Returns

IfValid<true, false, IsValid>

lastDateTime

Get Signature

get lastDateTime(): IfValid<DateTime<true>, null, IsValid>;

Returns the last DateTime included in the interval (since end is not part of the interval)

Returns

IfValid<DateTime<true>, null, IsValid>

start

Get Signature

get start(): IfValid<DateTime<true>, null, IsValid>;

Returns the start of the Interval

Returns

IfValid<DateTime<true>, null, IsValid>

Methods

abutsEnd()

abutsEnd(other: Interval): IfValid<boolean, false, IsValid>;

Return whether this Interval's start is adjacent to the specified Interval's end.

Parameters

Parameter	Type
`other`	`Interval`

Returns

IfValid<boolean, false, IsValid>

abutsStart()

abutsStart(other: Interval): IfValid<boolean, false, IsValid>;

Return whether this Interval's end is adjacent to the specified Interval's start.

Parameters

Parameter	Type
`other`	`Interval`

Returns

IfValid<boolean, false, IsValid>

contains()

contains(dateTime: DateTime): IfValid<boolean, false, IsValid>;

Return whether this Interval contains the specified DateTime.

Parameters

Parameter	Type	Description
`dateTime`	`DateTime`

Returns

IfValid<boolean, false, IsValid>

count()

count(unit?: keyof DurationLikeObject, opts?: _UseLocaleWeekOption): IfValid<number, number, IsValid>;

Returns the count of minutes, hours, days, months, or years included in the Interval, even in part. Unlike Interval#length this counts sections of the calendar, not periods of time, e.g. specifying 'day' asks 'what dates are included in this interval?', not 'how many days long is this interval?'

Parameters

Parameter	Type	Description
`unit?`	keyof DurationLikeObject	the unit of time to count. Defaults to 'milliseconds'.
`opts?`	`_UseLocaleWeekOption`	-

Returns

IfValid<number, number, IsValid>

difference()

difference(...intervals: Interval<boolean>[]): (Interval<true> | Interval<false>)[];

Return Intervals representing the spans of time in this Interval that not overlap with any of the specified Intervals.

Parameters

Parameter	Type
...`intervals`	`Interval`<`boolean`>[]

Returns

(Interval<true> | Interval<false>)[]

divideEqually()

divideEqually(numberOfParts: number): IfValid<Interval<boolean>[], [], IsValid>;

Split this Interval into the specified number of smaller intervals.

Parameters

Parameter	Type	Description
`numberOfParts`	`number`	The number of Intervals to divide the Interval into.

Returns

IfValid<Interval<boolean>[], [], IsValid>

engulfs()

engulfs(other: Interval): IfValid<boolean, false, IsValid>;

Return whether this Interval engulfs the start and end of the specified Interval.

Parameters

Parameter	Type
`other`	`Interval`

Returns

IfValid<boolean, false, IsValid>

equals()

equals(other: Interval): IfValid<boolean, false, IsValid>;

Return whether this Interval has the same start and end as the specified Interval.

Parameters

Parameter	Type
`other`	`Interval`

Returns

IfValid<boolean, false, IsValid>

hasSame()

hasSame(unit: keyof DurationLikeObject): IfValid<boolean, false, IsValid>;

Returns whether this Interval's start and end are both in the same unit of time

Parameters

Parameter	Type	Description
`unit`	keyof `DurationLikeObject`	the unit of time to check sameness on

Returns

IfValid<boolean, false, IsValid>

intersection()

intersection(other: Interval): Interval<boolean> | null;

Return an Interval representing the intersection of this Interval and the specified Interval. Specifically, the resulting Interval has the maximum start time and the minimum end time of the two Intervals. Returns null if the intersection is empty, meaning the intervals do not intersect.

Parameters

Parameter	Type
`other`	`Interval`

Returns

Interval<boolean> | null

isAfter()

isAfter(dateTime: DateTime): IfValid<boolean, false, IsValid>;

Return whether this Interval's start is after the specified DateTime.

Parameters

Parameter	Type	Description
`dateTime`	`DateTime`

Returns

IfValid<boolean, false, IsValid>

isBefore()

isBefore(dateTime: DateTime): IfValid<boolean, false, IsValid>;

Return whether this Interval's end is before the specified DateTime.

Parameters

Parameter	Type	Description
`dateTime`	`DateTime`

Returns

IfValid<boolean, false, IsValid>

isEmpty()

isEmpty(): boolean;

Return whether this Interval has the same start and end DateTimes.

Returns

boolean

length()

length(unit?: keyof DurationLikeObject): IfValid<number, number, IsValid>;

Returns the length of the Interval in the specified unit.

Parameters

Parameter	Type	Description
`unit?`	keyof DurationLikeObject	the unit (such as 'hours' or 'days') to return the length in.

Returns

IfValid<number, number, IsValid>

mapEndpoints()

mapEndpoints(mapFn: (d: DateTime) => DateTime): Interval<true> | Interval<false>;

Run mapFn on the interval start and end, returning a new Interval from the resulting DateTimes

Parameters

Parameter	Type
`mapFn`	(`d`: `DateTime`) => `DateTime`

Returns

Interval<true> | Interval<false>

Examples

Interval.fromDateTimes(dt1, dt2).mapEndpoints((endpoint) => endpoint.toUTC());

Interval.fromDateTimes(dt1, dt2).mapEndpoints((endpoint) =>
  endpoint.plus({ hours: 2 }),
);

overlaps()

overlaps(other: Interval): boolean;

Return whether this Interval overlaps with the specified Interval

Parameters

Parameter	Type
`other`	`Interval`

Returns

boolean

set()

set(values?: IntervalObject): Interval<true> | Interval<false>;

"Sets" the start and/or end dates. Returns a newly-constructed Interval.

Parameters

Parameter	Type	Description
`values?`	`IntervalObject`	the values to set

Returns

Interval<true> | Interval<false>

splitAt()

splitAt(...dateTimes: DateTime<boolean>[]): IfValid<Interval<boolean>[], [], IsValid>;

Split this Interval at each of the specified DateTimes

Parameters

Parameter	Type	Description
...`dateTimes`	`DateTime`<`boolean`>[]	the unit of time to count.

Returns

IfValid<Interval<boolean>[], [], IsValid>

splitBy()

splitBy(duration: DurationLike): IfValid<Interval<boolean>[], [], IsValid>;

Split this Interval into smaller Intervals, each of the specified length. Left over time is grouped into a smaller interval

Parameters

Parameter	Type	Description
`duration`	`DurationLike`	The length of each resulting interval.

Returns

IfValid<Interval<boolean>[], [], IsValid>

toDuration()

toDuration(unit?: keyof DurationLikeObject | keyof DurationLikeObject[], opts?: DiffOptions):
  | Duration<true>
| Duration<false>;

Return a Duration representing the time spanned by this interval.

Parameters

Parameter	Type	Description
`unit?`	keyof DurationLikeObject \| keyof DurationLikeObject[]	the unit or units (such as 'hours' or 'days') to include in the duration. Defaults to ['milliseconds'].
`opts?`	`DiffOptions`	options that affect the creation of the Duration

Returns

| Duration<true> | Duration<false>

Examples

Interval.fromDateTimes(dt1, dt2).toDuration().toObject(); //=> { milliseconds: 88489257 }

Interval.fromDateTimes(dt1, dt2).toDuration("days").toObject(); //=> { days: 1.0241812152777778 }

Interval.fromDateTimes(dt1, dt2).toDuration(["hours", "minutes"]).toObject(); //=> { hours: 24, minutes: 34.82095 }

Interval.fromDateTimes(dt1, dt2)
  .toDuration(["hours", "minutes", "seconds"])
  .toObject(); //=> { hours: 24, minutes: 34, seconds: 49.257 }

Interval.fromDateTimes(dt1, dt2).toDuration("seconds").toObject(); //=> { seconds: 88489.257 }

toFormat()

toFormat(dateFormat: string, opts?: {
  separator?: string;
}): IfValid<string, "Invalid Interval", IsValid>;

Returns a string representation of this Interval formatted according to the specified format string.

Parameters

Parameter	Type	Description
`dateFormat`	`string`	the format string. This string formats the start and end time. See DateTime.toFormat for details.
`opts?`	{ `separator?`: `string`; }	options
`opts.separator?`	`string`	a separator to place between the start and end representations. Defaults to ' - '.

Returns

IfValid<string, "Invalid Interval", IsValid>

toISO()

toISO(opts?: ToISOTimeOptions): IfValid<string, "Invalid Interval", IsValid>;

Returns an ISO 8601-compliant string representation of this Interval.

Parameters

Parameter	Type	Description
`opts?`	`ToISOTimeOptions`	The same options as DateTime#toISO

Returns

IfValid<string, "Invalid Interval", IsValid>

See

https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

toISODate()

toISODate(): IfValid<string, "Invalid Interval", IsValid>;

Returns an ISO 8601-compliant string representation of the dates in this Interval. The time components are ignored.

Returns

IfValid<string, "Invalid Interval", IsValid>

See

https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

toISOTime()

toISOTime(opts?: ToISOTimeOptions): IfValid<string, "Invalid Interval", IsValid>;

Returns an ISO 8601-compliant string representation of the times in this Interval. The date components are ignored.

Parameters

Parameter	Type	Description
`opts?`	`ToISOTimeOptions`	The same options as DateTime.toISO

Returns

IfValid<string, "Invalid Interval", IsValid>

See

https://en.wikipedia.org/wiki/ISO_8601#Time_intervals

toLocaleString()

toLocaleString(formatOpts?: DateTimeFormatOptions, opts?: LocaleOptions): IfValid<string, "Invalid Interval", IsValid>;

Returns a localized string representing this Interval. Accepts the same options as the Intl.DateTimeFormat constructor and any presets defined by Luxon, such as DateTime.DATE_FULL or DateTime.TIME_SIMPLE. The exact behavior of this method is browser-specific, but in general it will return an appropriate representation of the Interval in the assigned locale. Defaults to the system's locale if no locale has been specified.

Parameters

Parameter	Type	Description
`formatOpts?`	`DateTimeFormatOptions`	Either a DateTime preset or Intl.DateTimeFormat constructor options. Defaults to DateTime.DATE_SHORT
`opts?`	`LocaleOptions`	Options to override the configuration of the start DateTime.

Returns

IfValid<string, "Invalid Interval", IsValid>

See

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat

Examples

Interval.fromISO("2022-11-07T09:00Z/2022-11-08T09:00Z").toLocaleString(); //=> 11/7/2022 – 11/8/2022

Interval.fromISO("2022-11-07T09:00Z/2022-11-08T09:00Z").toLocaleString(
  DateTime.DATE_FULL,
); //=> November 7 – 8, 2022

Interval.fromISO("2022-11-07T09:00Z/2022-11-08T09:00Z").toLocaleString(
  DateTime.DATE_FULL,
  { locale: "fr-FR" },
); //=> 7–8 novembre 2022

Interval.fromISO("2022-11-07T17:00Z/2022-11-07T19:00Z").toLocaleString(
  DateTime.TIME_SIMPLE,
); //=> 6:00 – 8:00 PM

Interval.fromISO("2022-11-07T17:00Z/2022-11-07T19:00Z").toLocaleString({
  weekday: "short",
  month: "short",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
}); //=> Mon, Nov 07, 6:00 – 8:00 p

toString()

toString(): IfValid<string, "Invalid Interval", IsValid>;

Returns a string representation of this Interval appropriate for debugging.

Returns

IfValid<string, "Invalid Interval", IsValid>

union()

union(other: Interval): Interval<true> | Interval<false>;

Return an Interval representing the union of this Interval and the specified Interval. Specifically, the resulting Interval has the minimum start time and the maximum end time of the two Intervals.

Parameters

Parameter	Type
`other`	`Interval`

Returns

Interval<true> | Interval<false>

Interface: Interval<IsValid> ​

Type Parameters ​

Accessors ​

end ​

Get Signature ​

Returns ​

invalidExplanation ​

Get Signature ​

Returns ​

invalidReason ​

Get Signature ​

Returns ​

isValid ​

Get Signature ​

Returns ​

lastDateTime ​

Get Signature ​

Returns ​

start ​

Get Signature ​

Returns ​

Methods ​

abutsEnd() ​

Parameters ​

Returns ​

abutsStart() ​

Parameters ​

Returns ​

contains() ​

Parameters ​

Returns ​

count() ​

Parameters ​

Returns ​

difference() ​

Parameters ​

Returns ​

divideEqually() ​

Parameters ​

Returns ​

engulfs() ​

Parameters ​

Returns ​

equals() ​

Parameters ​

Returns ​

hasSame() ​

Parameters ​

Returns ​

intersection() ​

Parameters ​

Returns ​

isAfter() ​

Parameters ​

Returns ​

isBefore() ​

Parameters ​

Returns ​

isEmpty() ​

Returns ​

length() ​

Parameters ​

Returns ​

mapEndpoints() ​

Parameters ​

Returns ​

Examples ​

overlaps() ​

Parameters ​

Returns ​

set() ​

Parameters ​

Returns ​

splitAt() ​

Parameters ​

Returns ​

splitBy() ​

Parameters ​

Returns ​

toDuration() ​

Interface: Interval<IsValid>

Type Parameters

Accessors

end

Get Signature

Returns

invalidExplanation

Get Signature

Returns

invalidReason

Get Signature

Returns

isValid

Get Signature

Returns

lastDateTime

Get Signature

Returns

start

Get Signature

Returns

Methods

abutsEnd()

Parameters

Returns

abutsStart()

Parameters

Returns

contains()

Parameters

Returns

count()

Parameters

Returns

difference()

Parameters

Returns

divideEqually()

Parameters

Returns

engulfs()

Parameters

Returns

equals()

Parameters

Returns

hasSame()

Parameters

Returns

intersection()

Parameters

Returns

isAfter()

Parameters

Returns

isBefore()

Parameters

Returns

isEmpty()

Returns

length()

Parameters

Returns

mapEndpoints()

Parameters

Returns

Examples

overlaps()

Parameters

Returns

set()

Parameters

Returns

splitAt()

Parameters

Returns

splitBy()

Parameters

Returns

toDuration()