Proposal: generateToken's expireTime also accept a Date object

[aoberoi]

Currently the expireTime option expects a unix timestamp in seconds. This means that every user would have to understand how to convert a Date object into a unix timestamp in seconds properly. I don't see any way to get this value without first going through a Date object. That conversion can be error-prone for users (see #71). This proposal is to make the API backwards compatible and accept Number | Date types.

[aoberoi]

this is an additive change and would require bumping the minor revision number.

[aoberoi]

Here is what the change looks like, explicitly:

Before (and continues to work):

token = session.generateToken({
  expireTime : (new Date().getTime() / 1000)+(7 * 24 * 60 * 60) // in one week
});

After:

token = session.generateToken({
  expireTime : daysFromToday(7)
});

function daysFromToday(numDays) {
  var today = new Date();
  return today.setDate(today.getDate() + numDays);
}

While the number of lines in the after example is greater, the hypothesis here is that Date is better understood by JS developers than UNIX timestamps. Also, there are common libraries like moment that help JS developers juggle Dates and could be reused here.

[aoberoi]

I'm going to 👎 this proposal now. While unix timestamps are less common than Date objects, I think the latter isn't really the answer. The npm ecosystem has better reusable answers for this: modules. Here is one: https://github.com/pryv/unix-timestamp-js