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')

JavaScript always stores dates in UTC, but the data you imported may have lost the timezone information.

Use this to correct the timezone to the correct time UTC.

For Example:

// the date we originally pulled from the database
// but thetimezone of the database was america/Toronto but not in UTC
dateStr = '2024-12-06 18:00';

// we may have done this:
myDate = new Date(dateStr);

// but now calling toISOString() is incorrect
myDate.toISOString(); // '2024-12-06T18:00:00.0000' 

// it should be:
correctedDate = utils.date.correctForTimezone('america/Toronto');
correctedDate.toISOString(); // '2024-12-06T13:00:00.00.000' -- the correct time UTC

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')

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

See here why this might not be what you want

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.

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

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')

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

Consider this as an alternative to epochShifting.

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'