No matter what language you use, working with date values is often a cumbersome process. JavaScript may be more difficult than most — think about that time you had to calculate duration. The Moment.js JavaScript library saves the day, as it simplifies parsing, validating, manipulating, and formatting date values. (Both date and time values are implied when stating it handles data values; I want to make sure that is clear, because during a recent conversation with some junior developers, I realized that was not clear.) Here’s a quick tour of this wonderful JavaScript library.

Getting Moment.js

As developers, do we expect anything less than free these days? It makes me wonder how anybody makes money these days, but then I remember it takes skill to actually make these tools do something useful.

The Moment.js library is freely available under the terms of the MIT license — the current version is 2.0. The Moment.js site’s home page provides links to the full version (moment.js) which is around 44 kb, and to a minified version (moment.min.js), which has a miniscule 5.5 kb footprint.

If you are interested in contributing to the project or are just curious, the project is available on GitHub. With the library downloaded, include it in your page or other JavaScript, and you are up and running. Also, you can run it within node.js. With a few mouse clicks, you are ready to go.

Using Moment.js

The crux of working with the Moment.js library is the moment object — it is used for everything. You simply create an instance of the moment object, and you are in business. The moment object constructor is overloaded, so there are numerous ways to create instances of it. The simplest way is to use no parameters, which creates an instance of the object using the current date and time. The following code snippet does just this.

var currentDateTime = new moment();

Additionally, you can initialize the object with specific date and time values. The following code creates an instance of moment using a specified date and time.

var specificDate = new moment("April 15, 1969");

Once you have moment objects with values, the Moment.js library provides numerous ways to manipulate and format the date and time values. As an example, the isValid property is one I love, since it allows me to quickly determine if a date value is legal (according to ISO-8601 formats outlined in the documentation). The following code executes the block of code in the if statement if the moment object has a valid date value.

if (moment("some value").isValid()) {
<p>// do something inside the if statement block</p>
}

The moment object has a lot of overloaded get and set methods. The get method is used when no value is passed to the method, whereas the set approach is used when an actual parameter value is used with the method. The following code includes examples of using these methods.

var currentDateTime = new moment();
<p>// The next line displays the minutes property in a window</p>
<p>alert(currentDateTime.minutes());</p>
<p>// The next line sets the hour value to 3 AM</p>
currentDateTime.hours(3);

In addition to setting and getting values, you can manipulate values contained in moment object instances.

var sd = new moment("April 15, 2000");
<p>// The next line adds years to bring it to the current year.</p>
<p>sd.add('years', 13);</p>
<p>// The next line adds months to bring to current month</p>
<p>sd.add('m', 3);</p>
<p>// The next line subtraces days to make it the first of the month</p>
<p>sd.subtract('days',14);</p>
<p>// The next line changes it to the start of the year - January 1</p>
sd.startOf('year');

The number of get and set methods is overwhelming, so please refer to the documentation for more details.

The final aspect of the Moment.js library I will cover is formatting, because properly displaying date values is a critical aspect of many projects. The library offers a great number of formatting options so you can display values to meet any demand. The format method is a basic way to display values according to your requirements. The documentation provides the following two examples, which provide a glimpse of what is offered.

var cur = new moment();
<p>// The following displays day of week following by date and time as specified</p>
<p>cur.format("dddd, MMMM Do YYYY, h:mm:ss a");</p>
// The following displays shorthand for day of week and hour like Fri, 6PM
moment().format("ddd, hA");

You can test and play with moment.js via jsFiddle. You must import the library into the page within jsFiddle — a good resource for this is the CloudFlare site, which provides a CDN for a wide range of JavaScript libraries. The following HTML can be used to use moment.js in your jsFiddle environment.

<script src="http://cdnjs.cloudflare.com/ajax/libs/moment.js/1.7.2/moment.min.js"></script>

No more fear of working with dates

One of the things that really stands out with regards to moment.js is the high quality of everything related to it. The documentation is first rate, which is somewhat shocking for a free tool. When you combine this with the quality of the code, unit tests, and timely information via Twitter, and you”ll be up and running with it in no time.

I fell in love with this nifty library the first time I took it for a ride. It’s a great addition to any JavaScript developer’s toolkit.

Keep your engineering skills up to date by signing up for TechRepublic’s free Software Engineer newsletter, delivered each Tuesday.