moments-away

Moment.js durations made easier, ActiveSupport-style.

Wut?

Moment.js is a great JS library for manipulating dates and times in just about every way possible. If you do this kind of stuff, you should absolutely use Moment.

It provides a system of durations (e.g. “1 month”) that allow reliable offsets between dates. For instance, a month is a contextual notion: this could end up being anywhere from 28 to 31 days, not to mention the leap second thing we sometimes get at the end of the year.

However, I favor another reading style when manipulating such things, mostly because I'm used to the ActiveSupport way of doing things (in Ruby/Rails). In Moment, you'd so something like :

// The Moment way

// Based on a specific date:
var d = new Date(2013, 10, 6);
moment(d).add(3, 'months').toDate() // "3 months after d"
moment(d).subtract(1, 'year').toDate() // "1 year before d"

// Based on now:
moment().add(1, 'month').toDate()  // "1 month from now"
moment().subtract(2, 'weeks').toDate()  // "2 weeks ago"

This is functionally great, but I like how ActiveSupport reads better, so I created this little library that builds on Moment (which you should have available, then) and adds some stuff. Mirroring that exact Ruby syntax in JS is fairly convoluted and bulky memory-wise, so I went with something slightly different, but here it is.

// The Moments-Away way

// Based on a specific date:
var d = new Date(2013, 10, 6);
'3 months'.after(d)
'1 year'.before(d)

// Based on now:
'1 month'.fromNow()
'2 weeks'.ago()

// Based on Numbers instead of strings:
(3).months().after(d)
(1).year().before(d)

var om = 1, ow = 2;
om.months().fromNow()
ow.weeks().ago()

Installation

If you're using this in Node or installing through npm, just go with it:

npm install --save moments-away

Otherwise you can just pick up the library source file (only 1.7KB uncompressed).

ZOMG! :scream: You're extending native prototypes!

Yes, I am. This is necessary to achieve the level of expressiveness I was shooting for, and this does work across browsers.

If that looks too irksome for you, feel free to fork this and provide an alternative that uses, say, a global wrapper function over Strings or Numbers that returns the appropriate objects.

The API

String- or Number-based

Depending on what you're working with, it'll be smoother to use either a String- or Number-based API.

You’ll usually work with strings for one-off duration specifications. Loading the library automagically equips String with four new methods:

• before(date) returns a Date the precedes the date argument by the duration defined in the string.
• after(date) returns a Date the follows the date argument by the duration defined in the string.
• ago() returns a past Date with a distance defined in the string.
• fromNow() returns a future Date with a distance defined in the string.

The string should start with a number, followed possibly by whitespace, followed by one of the duration units recognized by moment.duration (this is every Date sub-unit from milliseconds to years, singular or plural, along with a few abbreviated forms, such as ms, s or y, for instance). Surrounding whitespace is ignored.

If you have an existing number (variable, argument, etc.) that defines your base duration, using the Number-based API will feel smoother:

function setAuthCookie(sessionId) {
  // var expiry = (AUTH_EXPIRY_MONTHS + ' months').fromNow(); // Ugh
  var expiry = AUTH_EXPIRY_MONTHS.months().fromNow();         // Better
  document.cookie = "authId=" + sessionId + "; expires=" + expiry;
}

Loading the library automagically equips Number with new methods for every duration unit supported by moment.duration, using the long forms, singular or plural:

• milliseconds(), millisecond()
• …
• years(), year()

The abbreviated forms are not used: less readable, more prone to naming conflicts.

These do not return numbers or strings, but actual Moment durations (which you could then use in regular Moment API calls), which remain contextual and will work at any later time, including on long-lived web pages.

In order to make the API homogeneous, we also extend Moment durations with the same four methods as on String: before(date), after(date), ago() and fromNow().

Contributing

You can report any issues or feature requests on GitHub.

Feel free to fork the repo, contribute and submit pull requests. These must always come with updated tests.

Licence

This work is MIT licence. Read the licence here.

To-do

• Bower wrapping (check Component, NuGet and others)
• JS Test Coverage report
• Provide GitHub pages
• Formal announcement