Date and time handling using dateutils

The dateutils functions enable you to perform date and time operations in JavaScript, with all dates handled as ISO-8601 strings.

These are the concepts for working with these functions:

  • ISO date format: Most methods expect and return dates in ISO-8601 format. For example, 2023-12-25T14:30:00-05:00.
  • Time zones: Use a valid time zone IDs, such as UTC, America/New_York, and Europe/London.
  • Immutability: Each operation returns a new date string without modifying the original input.

The methods that you can use in dateutils functions include create, now, add, subtract, convertTimeZone, and format.

create

Use this function to construct a new ISO date string from specific components.

Syntax:

dateutils.create(year, month, day, hour, minute, second, timeZone)

This table shows the parameters you can specify when using the create function:

Type Parameter Description
Number year The full year, such as 2025.
Number month The month of the year, such as 1 for January and 12 for December.
Number day The day of the month, which is 1 to 31.
Number hour The hour of the day, which is 0-23.
Number minute The minute of the hour, which is 0-59.
Number second The second of the minute, which is 0-59.
String timeZone The time zone ID, such as America/Los_Angeles.

Example:

// Create a date for Christmas morning 2025 in New York
var xmas = dateutils.create(2025, 12, 25, 8, 0, 0, "America/New_York");

// Result: "2025-12-25T08:00:00-05:00"

now

Use this function to return the current date and time for a specific time zone. You can use the timeZone parameter for this function. This parameter is a string that defines the target time zone ID.

Syntax:

dateutils.now(timeZone)

Example:

// Get the current time in London
var currentLondonTime = dateutils.now("Europe/London");

// Result example: "2023-10-05T14:30:15+01:00"

add

Use this function to add a time interval to a date.

Syntax:

dateutils.add(isoDate, amount, unit)

This table shows the parameters you can specify when using the add function:

Type Parameter Description
String isoDate The starting date in ISO-8601 format
Number amount The amount to add
String unit The unit of time, with valid values including:
  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

Example:

var startDate = "2023-01-01T10:00:00Z";

// Add two weeks to the start date
var futureDate = dateutils.add(startDate, 2, "weeks");

// Result: "2023-01-15T10:00:00Z"

subtract

Use this function to subtract a time interval from a date.

Syntax:

dateutils.subtract(isoDate, amount, unit)

This table shows the parameters you can specify when using the subtract function:

Type Parameter Description
String isoDate The starting date in ISO-8601 format
Number amount The amount to subtract
String unit The unit of time, with valid values including:
  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds

Example:

var deadline = "2023-05-01T17:00:00Z";

// Calculate a reminder three days before the deadline
var reminderDate = dateutils.subtract(deadline, 3, "days");

// Result: "2023-04-28T17:00:00Z"

convertTimeZone

Use this function to convert an existing date to a different time zone. The instant in time remains the same, but the clock time and offset are adjusted.

Syntax:

dateutils.convertTimeZone(isoDate, targetTimeZone)

This table shows the parameters you can specify when using the convertTimeZone function:

Type Parameter Description
String isoDate The source date in ISO-8601 format
String targetTimeZone The target time zone ID for conversion

Example:

// A meeting at 3:00 PM in California
var meetingCA = "2023-12-01T15:00:00-08:00"; // Pacific Standard Time

// What time is that meeting for a colleague in Tokyo?
var meetingTokyo = dateutils.convertTimeZone(meetingCA, "Asia/Tokyo");

// Result: "2023-12-02T08:00:00+09:00" (Next day, 8 AM)

format

Use this function to format an ISO date string into a readable date format or a specific pattern.

Syntax:

dateutils.format(isoDate, pattern)

This table shows the parameters you can specify when using the format function:

Parameter Type Description
String isoDate The source date in ISO-8601 format
String pattern

A Java DateTimeFormatter pattern string

These are the common pattern symbols:
  • yyyy = Year (2023)
  • MM = Month number (09)
  • MMM = Month abbreviation (Sep)
  • MMMM = Full month name (September)
  • dd = Day of month (05)
  • EEEE = Day of week (Monday)
  • HH = Hour in 24-hour format (0-23)
  • mm = Minute (0-59)

Example:

var rawDate = "2023-12-25T14:30:00Z";

// Format for a report header
var reportDate = dateutils.format(rawDate, "EEEE, MMMM dd, yyyy");

// Result: "Monday, December 25, 2023"
Caution: If you provided invalid inputs, the script stops and throws an error. Ensure that your inputs are valid when calling these methods. These are the common errors you can receive:
  • You passed a string that isn't in valid ISO-8601 format.
  • You passed a time zone ID that doesn't exist. For example, USA/Central instead of America/Chicago.