DateRange

date~ DateRange

Represents a Range between two timestamps.

  • Creating Date Range

    • fromList - given a list of dates, make range bins for those dates.
    • reinitialize - initialize the dateRange in-place with new start/end dates
    • shiftStart - shifts the start of the range by hours,minutes,years, etc.
    • shiftEnd - shifts the start of the range by hours,minutes,years, etc.

  • Understanding the Date Range

    • contains - if a date is within this range.
    • startDate - the starting date of the range
    • endingDate - the ending date of the range
    • startAndEndOfDay - Creates a DateRange covering the start and end of a day
    • overlaps - whether this DateRange overlaps another DateRange
    • isValid - Whether the start and end times of this range are both valid dates

  • Durations

    • duration - Epoch duration (milliseconds) between the start and end timestamps
    • durationString - creates a long duration description
    • durationISO - returns the duration as a string formatted '0:01:00:00.0000'

  • String Representation

    • toString - String conversion of the DateRange
    • toLocaleString - Creates a locale string describing the DateRange

Constructor

new DateRange(startDate, endDate, dataopt)

Parameters:
Name Type Attributes Default Description
startDate Date | String

the starting date
endDate Date | String

the ending date
data any <optional>
 null

any data to store

Members

data :any

Data attached to the DateTime

Type:
  • any

endDate :Date

The ending date

Type:
  • Date

startDate :Date

The starting date

Type:
  • Date

Methods

contains(dateToCheck) → {Boolean}

Determines if a datetime is within the range

Example
withinA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
withinB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
withinC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
withinD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));

range = new utils.DateRange(withinB, withinD);
range.contains(withinA); // false - it was before the range

range.contains(withinB); // true
range.contains(withinC); // true
range.contains(withinD); // true
Parameters:
Name Type Description
dateToCheck Date

the value to test if it is within the date range
Returns:
  • if the value is within the range (true) or not (false)
Type
Boolean

duration() → {Number}

Determines the millisecond duration between the end and start time.

durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
range = new utils.DateRange(durationA, durationB);

range.durationString(); // 1 hour in milliseconds; 1000 * 60 * 60;
Returns:
Type
Number

durationISO() → {String}

Determines the duration in days:hours:minutes:seconds.milliseconds

durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
range = new utils.DateRange(durationA, durationB);

range.durationString(); // '0:01:00:00.0000';
Returns:
Type
String

durationString() → {String}

Determines the duration in a clear and understandable string;

durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
range = new utils.DateRange(durationA, durationB);

range.durationString(); // '0 days, 1 hours, 0 minutes, 0.0 seconds';
Returns:
Type
String

isValid() → {Boolean}

Determines if both the startDate and endDate are valid dates.

Returns:
Type
Boolean

overlaps(targetDateRange) → {Boolean}

Whether this dateRange overlaps with a target dateRange.

Example
overlapA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
overlapB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
overlapC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
overlapD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));

rangeBefore = new utils.DateRange(overlapA, overlapB);
rangeAfter = new utils.DateRange(overlapC, overlapD);

rangeBefore.overlaps(rangeAfter); // false
rangeAfter.overlaps(rangeBefore); // false

rangeBefore = new utils.DateRange(overlapA, overlapC);
rangeAfter = new utils.DateRange(overlapB, overlapD);

rangeBefore.overlaps(rangeAfter); // true
rangeAfter.overlaps(rangeBefore); // true
Parameters:
Name Type Description
targetDateRange DateRange

dateRange to compare
Returns:
Type
Boolean

reinitialize(startDate, endDate, dataopt)

Reinitializes the object

(Sometimes useful for shifting times after the fact)

Parameters:
Name Type Attributes Default Description
startDate Date | String

the starting date
endDate Date | String

the ending date
data any <optional>
 null

any data to store

shiftEnd(options, inPlace) → {DateRange}

Shifts the ending time of the DateRange.

myRange = new utils.DateRange('2025-01-01', '2025-02-01');
myRange.shiftEnd({ days: 1 });
// { startDate: 2025-01-01, endDate: 2025-02-02 }

myRange.toString(); // { startDate: 2025-01-01, endDate: 2025-02-01 }

(Note that this defaults to immutable DateRanges, but passing inPlace=true will update this instance)

myRange = new utils.DateRange('2025-01-01', '2025-02-01');
myRange.shiftEnd({ days: 1 });

myRange.toString(); // { startDate: 2025-01-01, endDate: 2025-02-02 }
Parameters:
Name Type Description
options Object

options to shift the dateRange by, similar to DateUtils.add

Properties
Name Type Attributes Default Description
days Number <optional>
 0

how many days to add each check
hours Number <optional>
 0

how many days to add each check
minutes Number <optional>
 0

how many days to add each check
seconds Number <optional>
 0

how many days to add each check
years Number <optional>
 0

increments the calendar year (as opposed to adding 365.25 days)
months Number <optional>
 0

increments the calendar month (as opposed to adding in 30 days)
inPlace *
Returns:
  • this DateRange if (inPlace=true), a new instance if (inPlace=false)
Type
DateRange

shiftStart(options, inPlace) → {DateRange}

Shifts the start time of the DateRange.

myRange = new utils.DateRange('2025-01-01', '2025-02-01');
myRange.shiftStart({ days: 1 });
// { startDate: 2025-01-02, endDate: 2025-02-01 }

myRange.toString(); // { startDate: 2025-01-01, endDate: 2025-02-01 }

(Note that this defaults to immutable DateRanges, but passing inPlace=true will update this instance)

myRange = new utils.DateRange('2025-01-01', '2025-02-01');
myRange.shiftStart({ days: 1 });

myRange.toString(); // { startDate: 2025-01-02, endDate: 2025-02-01 }
Parameters:
Name Type Description
options Object

options to shift the dateRange by, similar to DateUtils.add

Properties
Name Type Attributes Default Description
days Number <optional>
 0

how many days to add each check
hours Number <optional>
 0

how many days to add each check
minutes Number <optional>
 0

how many days to add each check
seconds Number <optional>
 0

how many days to add each check
years Number <optional>
 0

increments the calendar year (as opposed to adding 365.25 days)
months Number <optional>
 0

increments the calendar month (as opposed to adding in 30 days)
inPlace *
Returns:
  • this DateRange if (inPlace=true), a new instance if (inPlace=false)
Type
DateRange

toLocaleString() → {String}

Converts the daterange to a local string value

durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
range = new utils.DateRange(durationA, durationB);

range.toLocaleString(); // '1/26/2025, 12:00:00 PM to 1/26/2025, 1:00:00 PM'
Returns:
Type
String

toString() → {String}

Converts the daterange to a string value

durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
range = new utils.DateRange(durationA, durationB);

range.toString(); // '2025-01-26T12:00:00.000Z to 2025-01-26T13:00:00.000Z';
Returns:
Type
String

(static) fromList(dateList, dataCreationFnopt) → {Array.<DateRange>}

See:

Create a list of DateRanges, from a list of dates.

dates = [new Date('2025-01-01'),
  new Date('2025-02-01'),
  new Date('2025-03-01'),
  new Date('2025-04-01')];

utils.DateRange.fromList(dates);
// [{start: 2025-01-01T00:00:00, end: 2025-02-01TT00:00:00, },
//  {start: 2025-02-01TT00:00:00, end: 2025-03-01TT00:00:00},
//  {start: 2025-03-01TT00:00:00, end: 2025-04-01TT00:00:00}]

Often though, we want to remember something about the DateRange, like which dates that it collected.

arrayGenerator = function() { return [] };
rangeList = utils.DateRange.fromList(dates, arrayGenerator);
// [{start: 2025-01-01T00:00:00, end: 2025-02-01TT00:00:00},
//  {start: 2025-02-01TT00:00:00, end: 2025-03-01TT00:00:00},
//  {start: 2025-03-01TT00:00:00, end: 2025-04-01TT00:00:00}]

dates.forEach((date) => rangeList
  .find(rl => rl.contains(date))
  .data.push(date)
);

rangeList
  .map(rl => `${rl.toString()}: has ${rl.data.length}`)
  .join('\n');

// 2025-01-01T00:00:00.000Z to 2025-02-01T00:00:00.000Z: has 2
// 2025-02-01T00:00:00.000Z to 2025-03-01T00:00:00.000Z: has 1
// 2025-03-01T00:00:00.000Z to 2025-04-01T00:00:00.000Z: has 1

(Note: you can also use date.arrange or date.generateDateSequence to come up with the list of those dates)

(If gaps are desired - ex: April to May and next one June to July, the simplest is to remove the dates from the resulting list.)

Parameters:
Name Type Attributes Description
dateList Array.<Date>

list of dates
dataCreationFn function <optional>

optional generator for data to be stored in each DataRange in the sequence
Returns:
  • list of dateList.length-1 dateRanges, where the end of the firstRange is the start of the next.
Type
Array.<DateRange>

(static) startAndEndOfDay(targetDate) → {DateRange}

Creates a DateRange based on the start and end of the day UTC.

This is very useful for determining overlapping dates.

(Alternatively, you can define a list of dates, and use DateRange.fromList to create the bins from those dates)

Parameters:
Name Type Description
targetDate Date

date to use to find the start and end UTC for
Returns:
Type
DateRange