timrwood/moment — pull request #265 by rockymeza (2012-04-07 16:30:05+00:00)
Title: Feature/durations

This is a new feature based on the discussion in #236.

I created a new object called Duration that can be `add`ed and `subtract`ed. It can be instantiated using the `moment.duration` function. There are three ways to instantiate a Duration object: Object, key/value, and millisecond. The following five invocations result in essentially the same Duration object.

```javascript
moment.duration({seconds: 45});
moment.duration({s: 45});
moment.duration(45, 'seconds');
moment.duration(45, 's');
moment.duration(45000);
```

I exposed the `Duration.prototype` on `moment.duration.fn`. On it currently there are two methods: `toValue` and `humanize`. `toValue` returns the milliseconds of all the options added together. `humanize` contains the functionality that `moment.humanizeDuration` used to contain.

I deprecated `moment.humanizeDuration`, but I left it and the tests in place. It now relies on `Duration.prototype.humanize`. `moment.fn.from` also relies on the `Duration.prototype.humanize` now instead of `humanizeDuration`.

## Things that it doesn't do (yet)

- There is no `isDuration` function to type-check Duration objects.
- When `add`ing using a duration, it basically clones the duration object by calling `moment.duration` on it. So, there is no special handling of Durations versus normal Objects in adding and subtracting.
- If you create a Duration of 7 days and check the `weeks` property, it will still be zero.

## Don't merge this in yet.

I am opening this pull request so that we can continue the conversation and also start developing this feature.

cc @nilakanta