As John already teased in his blog post about the JavaScript API changes in APEX 21.2, there is a new apex.date namespace coming.

Main purpose of it is to have an out-of-the-box replacement for Moment.js which is part of APEX since we introduced our Calendar region with FullCalendar version 3. In APEX 21.1 this region was updated to use the newer version 5 of the underlying FullCalendar library, and this particular version doesn't come with Moment.js anymore and changed many other things, especially from an API point of view. If you're interested in these changes in more detail, we created a blog posting back when 21.1 was released to help developers to get started with this new version.

Additionally even Moment.js itself states, that you shouldn't use this library anymore:

So we thought it would be really helpful for all APEX developers to have an integrated API which can do most of the things Moment.js did + things that make sense in an APEX or database environment.

There are 4 main categories in which you will find functions to use in apex.date:

• Date Manipulation

• Date Formatting & Parsing

• Date Comparison

• Miscellaneous Functions

Before starting with the description of the actual categories and showing some code examples, it is worth to mention that apex.date operates with native JavaScript date objects and doesn't introduce new custom objects like Moment.js did.

var date = new Date();

Date Manipulation

This category contains functions to manipulate JavaScript date objects, like adding or subtracting given amounts to or from a date.

So lets add something to a given date:

var date = new Date();

// add 2 years
apex.date.add( date, 2, apex.date.UNIT.YEAR );

// add 5 days
apex.date.add( date, 5, apex.date.UNIT.DAY );

// add 45 minutes
apex.date.add( date, 45, apex.date.UNIT.MINUTE );

console.log( date );

And now lets subtract something from a date:

var date = new Date();

// subtract 2 months
apex.date.subtract( date, 2, apex.date.UNIT.MONTH );

// subtract 30 seconds
apex.date.subtract( date, 30, apex.date.UNIT.SECOND );

// subtract 4 weeks
apex.date.subtract( date, 4, apex.date.UNIT.WEEK );

console.log( date );

As you can see, we used the apex.date.UNIT object in both examples, this has constants for all units used by apex.date

Date Formatting & Parsing

In this category there's everything related to date formatting & parsing. The most important part to mention is that apex.date handles it formatting & parsing logic using Oracle Database compatible format masks, which makes it easy for APEX developers to re-use their DB logic also on the client, without investigating too much brain power in thinking in 2 separate format mask flavors.

Date formatting:

var date = new Date(),
    dateString = "";

dateString = apex.date.format( date, "YYYY-MM-DD HH24:MI:SS" );
// output: 2021-10-11 22:15:45

dateString = apex.date.format( date, "YYYY/MM/DD" );
// output: 2021/10/11

dateString = apex.date.format( date, "YYYY, IW" );
// output: 2021, 41

dateString = apex.date.format( date, "Day, DD Month YYYY" );
// output: Monday, 11 October 2021

dateString = apex.date.format( date, "DL" );
// output: Monday, October 11, 2021

dateString = apex.date.format( date, "DL", "de" );
// output: Montag, 11. Oktober 2021

dateString = apex.date.format( date, "DL", "es" );
// output: lunes, 11 de octubre de 2021

// relative date / time as words
dateString = apex.date.since( date );
// output: "10 months from now" or "2 months ago"

dateString = apex.date.since( date, true );
// output: "in 10mo" or "2mo"

Date parsing:

var date;

date = apex.date.parse( "2021-10-11 22:15", "YYYY-MM-DD HH24:MI");
date = apex.date.parse( "2021/10/11", "YYYY/MM/DD");
date = apex.date.parse( "2021-OCT-11 22:15:45", "YYYY-MON-DD HH24:MI:SS");

If no format or language is specified, apex.date automatically uses the format and language defined in your application. You can also get this information using:

apex.locale.getDateFormat();
apex.locale.getLanguage();

Date Comparison

This category contains functions useful to compare 2 or more JavaScript date objects with each other.

var date1 = apex.date.parse( "2021/10/01", "YYYY/MM/DD"),
    date2 = apex.date.parse( "2021/10/15", "YYYY/MM/DD"),
    date3 = apex.date.parse( "2021/10/31", "YYYY/MM/DD");

// is date 1 < date 2
apex.date.isBefore( date1, date2, apex.date.UNIT.DAY );
// output: true

// is date 1 > date 2
apex.date.isAfter( date1, date2, apex.date.UNIT.DAY );
// output: false

// is date 1 = date 2
apex.date.isSame( date1, date2, apex.date.UNIT.DAY );
// output: false

// is date 1 <= date 2
apex.date.isSameOrBefore( date1, date2, apex.date.UNIT.DAY );
// output: true

// is date 1 >= date 2
apex.date.isSameOrAfter( date1, date2, apex.date.UNIT.DAY );
// output: false

// is date 1 between date 2 and date 3
apex.date.isBetween( date1, date2, date3, apex.date.UNIT.DAY );
// output: false

// get the minimum date of given date arguments
var minDate = apex.date.min( date1, date2, date3 );
// output: date1 as date object

// get the maximum date of given date arguments
var maxDate = apex.date.max( date1, date2, date3 );
// output: date3 as date object

Most compare functions are also utilizing apex.date.UNIT constants. This enables developers to precisely compare dates from milliseconds up to years.

Miscellaneous

Beside the other categorized functionality, apex.date also has more generic functions or useful helper functions on board, which I won't describe here in full length, but to just get an idea, here are a few of them:

var date = new Date();

// get ISO week number
var week = apex.date.ISOWeek( date );

// get total days of month
var days = apex.date.daysInMonth( date );

// get first of month as date object
var first = apex.date.firstOfMonth( date );

// get last of month as date object
var last = apex.date.lastOfMonth( date );

// get months between 2 dates
var months = apex.date.monthsBetween( now, date );

// check if it's a leap year
var isLeapYear = apex.date.isLeapYear( date );

The whole apex.date API documentation is part of our official JavaScript API documentation, which when APEX 21.2 is ready will be available here. I also plan to publish a demo app show casing everything in this post live in an APEX app. This app will be released as soon as 21.2 is available on apex.oracle.com.

Edit 18/11/2021: As promised, and now that APEX 21.2 pre-production release is available at apex.oracle.com, you can find the demo app here.

Happy APEXing! 🚀