date

Collection of time durations in milliseconds

Adds an amount to a date: days, hours, minutes, seconds

d = new Date('2024-12-26 6:00:00');
d30 = utils.date.add(d, { minutes: 30 }); // Date('2024-12-26 6:00:00')

Creates an array of dates, starting with the startDate, and adding in the options count number of times.

const startDate = new Date('2025-02-02');
utils.date.arrange(startDate, 6, { days: 1 });
//   ['2025-02-02 00:00:00')
//   ['2025-02-03 00:00:00')
//   ['2025-02-04 00:00:00')
//   ['2025-02-05 00:00:00')
//   ['2025-02-06 00:00:00')
//   ['2025-02-07 00:00:00')
//   ['2025-02-08 00:00:00')
//   ['2025-02-09 00:00:00')
// ]

Clones a date.

(Doesn't seem needed currently)

(NOTE: the timezone information is lost)

This helps you correct a "local date" from another timezone.

For example, if you got '2:15 PM' from a machine that is in eastern.

Combination of date.correctForTimezone and date.epochShift

For example, say you got a timezone string like this: 2024-12-27 13:30:00

You know the timezone of the source is in us/eastern, but you are in us/central.

If you just use Date.parse(dateString), it assumes 1:30 Central- not1:30 Eastern`

We can correct it like this:

dateStr = '2024-12-27 13:30:00';
d = new Date(Date.parse(dateStr));

//-- the source was from 'us/eastern' timezone (-0500)
sourceTimezone = 'us/eastern';

//-- we are currently in 'us/central' timezone (-0600)
//-- this matters because of the Date.parse() done before
localTimezone = 'us/central'; // (change if yours is different)

utils.date.correctForOtherTimezone( d, sourceTimezone, localTimezone);

//-- correctly converted it to the correct local time
// 2024-12-28T18:30:00.000Z

CorrectForTimezone is the opposite of date.epochShift. (This subtracts the timezone offset to a date, where the other adds the offset)

Use this when a date string is read by javascript, BUT the timezone is not sent or passed.

For example, something VERY IMPORTANT happened at '2/1/2025, 2:15:41 PM EST', ISO '2025-02-01T20:15:41.000Z', epoch: 1738440941000.

But the dates from the database don't include the timezone. (Note that Z is conceptually equivalent of +0000)

If I create a date in javaScript WITHOUT the timezone, it assumes my local timezone.

dTest = new Date('2025-02-01T20:15:41.000'); // -- DID NOT INCLUDE Timezone, so it assumes local timezone
({ epoch: dTest2.getTime(), iso: dTest.toISOString(), local: dTest.toLocaleString() });

//-- time is INCORRECT, what should be the ISO time, is the local time.
//  local: '2/1/2025, 8:15:41 PM', iso: '2025-02-02T02:15:41.000Z', epoch: 1738440941000

It assumed that the local time was 8pm instead of that as the ISO / GMT time.

To correct this, I just call epoch shift

dTest = new Date('2025-02-01T20:15:41.000'); // -- DID NOT INCLUDE Timezone, so it assumes local timezone
dTest2 = utils.date.epochShift(dTest, 'us/central');  //-- correct for my local timezone
({ epoch: dTest2.getTime(), iso: dTest.toISOString(), local: dTest.toLocaleString() });

//-- time is CORRECT
// local: '2/1/2025, 2:15:41 PM', iso: '2025-02-01T20:15:41.000Z', epoch: 1738440941000

See the list of TZ database time zones for the full list of timezone options.

Prints the duration in ISO format: D:HH:MM:SS.MMM

start = new Date(Date.ISO(2024, 12, 26, 12, 0, 0));
end = new Date(Date.ISO(2024, 12, 26, 13, 0, 0));

duration = end.getTime() - start.getTime();

utils.date.durationLong(duration); // '0 days, 1 hours, 0 minutes, 0.00 seconds'

Prints the duration in long format: D days, H hours, M minutes, S.MMM seconds

start = new Date(Date.ISO(2024, 12, 26, 12, 0, 0));
end = new Date(Date.ISO(2024, 12, 27, 13, 0, 0));

duration = end.getTime() - start.getTime();

utils.date.durationLong(duration); // '1 days, 1 hours, 0 minutes, 0.00 seconds'

Creates a new date that is at the end of the day (in UTC)

d = new Date('2024-12-26 6:00:00');
dEnd = utils.date.endOfDay(d); // Date('2024-12-26 23:59:59.9999')

EpochShift is the opposite of date.correctForTimezone. (This adds the timezone offset, where the other subtracts the offset)

Use this if you somehow have a date that needs to be shifted by the timezone offset.

For example, if you have a time that is already in GMT, and want the date shifted by a timezone.

This is used internally for date.correctForOtherTimezone if local dates are provided - but for a different timezone you yourself are not in.

Epoch shift changes the internals of a JavaScript date, so the utcDate is no longer correct, but many other functions behave closer to expected.

Once you epoch shift the date, then time stored in the date is incorrect (because it always points to GMT)

For example, using .toIsoString() or anything with Intl.DateTimeFormat etc - will all give you incorrect results.

See here why this might not be what you want

• date.correctForTimezone or
• date.correctForTimezones.

Creates an array of dates, beginning at startDate, and adding time until EndDate is reached.

const startDate = new Date('2025-02-02');
const endDate = new Date('2025-02-09 23:59:59.000');
// alternative
// endDate = utils.date.endOfDay(utils.date.add(startDate, { days; 7 }));

utils.date.arrange(startDate, endDate, { days: 1 });
//   ['2025-02-02 00:00:00.000'],
//   ['2025-02-03 00:00:00.000'],
//   ['2025-02-04 00:00:00.000'],
//   ['2025-02-05 00:00:00.000'],
//   ['2025-02-06 00:00:00.000'],
//   ['2025-02-07 00:00:00.000'],
//   ['2025-02-08 00:00:00.000'],
//   ['2025-02-09 00:00:00.000'],
//   ['2025-02-09 23:59:59.9999']
// ]

Determines the number of milliseconds difference between a given timezone and UTC.

(Note: these values are cached, and optimized for repeated use on the same value)

See the list of TZ database time zones for the full list of options.

Determines the weekday of a date

Simple check on whether the a JavaScript Date object is - or is not - an 'Invalid Date' instance.

d = new Date('2024-12-1');
utils.date.isValid(d); // true

d = new Date('2024-12-1T');
utils.date.isValid(d); // false

d = new Date('some string');
utils.date.isValid(d); // false

If repeatedly asking for a local time, use this method instead.

myDate = new Date('2025-01-15T06:00:00.000Z');
centralFormatter = utils.date.localISOFormatter('us/central');
centralFormatter(myDate); // '2025-01-15T00:00:00.000Z'

as opposed to

myDate = new Date('2025-01-15T06:00:00.000Z');
utils.date.toLocalISO(myDate, 'us/central'); // '2025-01-15T00:00:00.000Z'

Overwrite the internal time for a date object.

const targetDate = new Date('2025-01-01');
utils.date.overwrite(targetDate, new Date('2025-02-01'));

targetDate.toISOString(); // 2025-02-01T00:00:00.000Z

Harshly parses a JavaScript Date.

If the testValue is null, undefined then the same value is returned.

if the testValue is a valid Date - then the parsed Date object is returned.

If the testValue is not a valid Date, then throws an Error.

d = utils.date.parse('2024-12-01'); // returns Date object
d = utils.date.parse(0); // returns Date object

d = utils.date.parse(null); // returns null

Creates a new date that is at the start of the day (in UTC)

d = new Date('2024-12-26 6:00:00');
dEnd = utils.date.startOfDay(d); // Date('2024-12-26 0:00:00.0000')

Print a date that has been epoch shifted.

Dates in JavaScript are always stored in GMT, although you can format it to different times with Intl.DateTimeFormat.

Once you epoch shift the date, then time stored in the date is incorrect (because it always points to GMT)

For example, using .toIsoString() or anything with Intl.DateTimeFormat etc - will all give you incorrect results.

If you want an ISO format for an epoch shifted date, you'll need something like this.

Prints a date in 8601 format to a timezone (with +H:MM offset) using Intl.DateTimeFormat.

The date accepted here is assumed to already have the internal clock set to GMT.

If you do epochShift, then use date.toEpochShiftedISO and pass the timezone the timezone the date is epoch shifted to.

d = Date.parse('2024-12-27 13:30:00');

utils.date.toLocalISO(d, 'america/Chicago'); // '2024-12-27T07:30:00.000-06:00'
utils.date.toLocalISO(d, 'europe/paris'); //    '2024-12-27T14:30:00.000+01:00'

Sometimes it is helpful to have the weekday to make sense of things

utils.date.toLocalISO(d, 'america/Chicago', true); // '2024-12-27T07:30:00.000-06:00 FRI' 
utils.date.toLocalISO(d, 'europe/paris', true); //    '2024-12-27T14:30:00.000+01:00 FRI'

Function that is passed a date for formatting