# Easy Date Handling in JavaScript with apex.date

Working with dates and times in pure JavaScript is painful, to say the least. In Oracle APEX 21.2, the APEX team introduced the [apex.date](https://docs.oracle.com/en/database/oracle/apex/22.1/aexjs/apex.date.html) JavaScript API. The `apex.date` API provides several easy-to-use utility functions that make formatting, parsing, comparing, and performing calculations on dates in JavaScript a breeze. What I like about these functions is that many mirror SQL and PL/SQL functions and operators we know and love. In this APEX 🩳, I will demonstrate three examples.

## Example 1 - Date Calculations
The first example demonstrates a typical scenario where users must enter a start and end date. Whenever the user changes the start date, we want to default the end date to the start date plus seven days.
![Screenshot showing APEX Items for apex.date Example](https://cdn.hashnode.com/res/hashnode/image/upload/v1656975535337/o-GQZAzZW.png align="left")
In this scenario, `P70_START_DATE` is the 'Start Date', and `P70_END_DATE` is the 'End Date'. We have an 'Execute JavaScript Code' Dynamic Action on `P70_START_DATE` that triggers whenever the value changes and sets the appropriate value in `P70_END_DATE`.
![Screenshot showing Dynamic Action to Default End date using apex.date](https://cdn.hashnode.com/res/hashnode/image/upload/v1656976564065/htk-kNzqd.png align="left")

Here is the complete code for the Dynamic Action:
```javascript
/* Set dateFormat with the Date Format String for the APEX Session.
   Note: apex.date does not support all Oracle Format Strings 
     (see the documentation for details)
*/
const dateFormat   = apex.locale.getDateFormat();
// Set the number of days to add to the start date.
const addDays      = 7;
// Get the string value of the start date APEX Item.
var   startDateStr = apex.item("P70_START_DATE").getValue();
// Use apex.date.parse to convert the string date value to 
// a date value understood by apex.date
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   endDateStr   = "";
// Add 7 days to the startDate.
apex.date.add(startDate, addDays, apex.date.UNIT.DAY);
// Convert date back to a String using the date format of the session.
endDateStr = apex.date.format( startDate, dateFormat);
// Set the End Date value in the APEX Item.
apex.item( "P70_END_DATE" ).setValue(endDateStr);
```
The final parameter of `apex.date.add` identifies the unit (DAY,HOUR,YEAR, etc.). I am adding days in my example, so the unit is `DAY`. See the [documentation](https://docs.oracle.com/en/database/oracle/apex/22.1/aexjs/apex.date.html#.UNIT) for a complete list. We can also use `apex.date.subtract` to subtract date/time values.

By changing the type of Dynamic Action from 'Execute JavaScript Code' to 'Execute Server-side Code', we could have used PL/SQL to achieve the same thing.
> The benefit of the JavaScript approach is that we avoid a round trip to the database in order to do this simple calculation.

## Example 2 - Date Comparisons
In this example, we are checking to make sure the end date is greater than the start date. The javascript below uses `apex.date.isAfter` to achieve this.
```javascript
const dateFormat   = apex.locale.getDateFormat();
var   startDateStr = apex.item("P70_START_DATE").getValue();
var   endDateStr   = apex.item("P70_END_DATE").getValue();
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   endDate      = apex.date.parse(endDateStr, dateFormat);
// Clear any existing errors on the page
apex.message.clearErrors();
// apex.date.isAfter compares the two dates down to the second.
if (apex.date.isAfter( startDate, endDate, apex.date.UNIT.SECOND))
{
  
  apex.message.showErrors([
      {
          type:       "error",
          location:   ["inline" ],
          pageItem:   "P70_END_DATE",
          message:    "End Date must be after Start Date"
      }
  ]);
}
```
![Screenshot showing result of apex.date End Date Before Start date](https://cdn.hashnode.com/res/hashnode/image/upload/v1656978417517/w34l39fp6.png align="left")

There are other comparison functions available in `apex.date`, including isBefore, isBetween, isSame, isSameOrAfter, etc.

## Example 3 - Since
You may have encountered the APEX PL/SQL function `APEX_UTIL.GET_SINCE`. It returns a string describing the elapsed time between a date and time variable and the current date and time. In this example, we use `apex.date.since` to achieve the same thing as `APEX_UTIL.GET_SINCE`.

```javascript
const dateFormat   = 'MM/DD/YYYY HH:MIpm'
var   startDateStr = '07/04/2022 5:00pm';
var   startDate    = apex.date.parse(startDateStr, dateFormat);
var   sinceString = apex.date.since( startDate );
console.log('Since String: ' + sinceString);
```
Output from the above snippet: `Since String: 13 minutes ago`

## Conclusion
This blog post was just a taste of the utilities available in `apex.date`. I encourage you to explore the [documentation](https://docs.oracle.com/en/database/oracle/apex/22.1/aexjs/apex.date.html) to find out more.

## 🔗 Read More
- 🩳 [APEX Shorts](https://blog.cloudnueva.com/series/apex-shorts)
- #️⃣ [APEX Posts](https://blog.cloudnueva.com/tag/orclapex)