moment-daterange

Fancy date ranges for Moment.js.

| Date Range | Type | |----------------|-----------------| | start | Moment | | end | Moment | | duration | Moment.duration | | Limit Range | Type | | upperLimit | Moment | | lowerLimit | Moment | | limitDuration | Moment.duration | | limitRange | Range | | Actual Range | Type | | actualStart | Moment | | actualEnd | Moment | | actualDuration | Moment.duration | | actualRange | Range |

| Date Range | Arguments | Behaviour | | |-------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--| | set(Date, [Date]) | 1. Date: Start date to set | Sets either the start date, the end date, or both. | | | | 2. Date: End date to set | null or undefined values will clear the date. | | | set(Range) | 1. Range: The range to set | | | | setStart(Date) | 1. Date: Start date to set | | | | setEnd(Date) | 1. Date: End date to set | | | | clear([Boolean], [Boolean]) | 1. Boolean: true clears start date, false does nothing | Clears the start, end, or both. | | | | 2. Boolean: true clears end date, false does nothing | Undefined parameters clear both. | |

| Limiting Time | Arguments | Behaviour | |
|-------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--| | setLimit(Date, Date) | 1. Date: Lower limit to set | Sets either the lower limit, the upper limit, or both. | | | | 2. Date: Upper limit to set | null or undefined values will clear the limit. | | | setLowerLimit(Date) | 1. Date: Lower limit to set | | | | setUpperLimit(Date) | 1. Date: Upper limit to set | | | | clearLimits([Boolean], [Boolean]) | 1. Boolean: true clears lower limit, false does nothing | Clears the upper limit, lower limit, or both. | | | | 2. Boolean: true clears upper limit, false does nothing | Undefined parameters clear both. | |

| Shifting Time | Arguments | Behaviour | | |-------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--| | shiftForward([Duration]) | 1. Duration: The duration to shift forward | Shifts the date range forward or backward. | | | shiftBackward([Duration]) | 1. Duration: The duration to shift backward | If the shifting attempts to go beyond the set limits, the date range will stop at the limit will not shift beyond it. If no limits are set the time will shift indefinitely. | | | shift(Duration) | 1. Duration: The duration to shift (+/-) | The shift method accepts positive and negative values. Omitting the optional duration will shift the duration of the date rage. | | | shiftLimitForward([Duration]) | 1. Duration: The duration to shift limit forward | Shifts the upper and lower limit forward or backward. | | | shiftLimitBackward([Duration]) | 1. Duration: The duration to shift limit backward | The shift method accepts positive and negative values. Omitting the optional duration will shift the duration of the limit. | | | shiftLimit(Duration) | 1. Duration: The duration to shift limit (+/-) | | |

• Examples
  • Create
  • Contains / Within / Overlaps / Intersect / Add / Subtract
  • Iterate
  • Compare
  • Equality
  • Difference
  • Conversion
    • toArray
    • toDate
    • toString
    • valueOf
  • Center
  • Clone
• Installation
  • Browser
  • NPM
  • Bower
• Running Tests
• License

Examples

Create

Create a date range:

var start = new Date(2012, 0, 15);
var end   = new Date(2012, 4, 23);
var range = moment.range(start, end);

You can also create a date range with moment objects:

var start = moment("2011-04-15", "YYYY-MM-DD");
var end   = moment("2011-11-27", "YYYY-MM-DD");
var range = moment.range(start, end);

Arrays work too:

var dates = [moment("2011-04-15", "YYYY-MM-DD"), moment("2011-11-27", "YYYY-MM-DD")];
var range = moment.range(dates);

You can also create a range from an ISO 8601 time interval string:

var timeInterval = "2015-01-17T09:50:04+00:00/2015-04-17T08:29:55+00:00";
var range = moment.range(timeInterval);

You can also create a range from the start until the end of a named interval:

var date = moment("2011-04-15", "YYYY-MM-DD");
var range = date.range("month");

You can also create open-ended ranges which go to the earliest or latest possible date:

var rangeUntil = moment.range(null, "2011-05-05");
var rangeFrom = moment.range("2011-03-05", null);
var rangeAllTime = moment.range(null, null);

Contains / Within / Overlaps / Intersect / Add / Subtract

Check to see if your range contains a date/moment:

var start  = new Date(2012, 4, 1);
var end    = new Date(2012, 4, 23);
var lol    = new Date(2012, 4, 15);
var wat    = new Date(2012, 4, 27);
var range  = moment.range(start, end);
var range2 = moment.range(lol, wat);

range.contains(lol); // true
range.contains(wat); // false

A optional second parameter indicates if the end of the range should be excluded when testing for inclusion

range.contains(end) // true
range.contains(end, false) // true
range.contains(end, true) // false

Find out if your moment falls within a date range:

var start = new Date(2012, 4, 1);
var end   = new Date(2012, 4, 23);
var when  = moment("2012-05-10", "YYYY-MM-DD");
var range = moment.range(start, end);

when.within(range); // true

Does it overlap another range?

range.overlaps(range2); // true

What are the intersecting ranges?

range.intersect(range2); // [moment.range(lol, end)]

Add/combine/merge overlapping ranges.

range.add(range2); // [moment.range(start, wat)]

var range3 = moment.range(new Date(2012, 3, 1), new Date(2012, 3, 15);
range.add(range3); // [null]

Subtracting one range from another.

range.subtract(range2); // [moment.range(start, lol)]

Iterate

Iterate over your date range by an amount of time or another range:

var start = new Date(2012, 2, 1);
var two   = new Date(2012, 2, 2);
var end   = new Date(2012, 2, 5);
var range1 = moment.range(start, end);
var range2 = moment.range(start, two); // One day
var acc = [];

range1.by('days', function(moment) {
  // Do something with `moment`
});

Any of the units accepted by moment.js' add method may be used.

You can also iterate by another range:

range1.by(range2, function(moment) {
  // Do something with `moment`
  acc.push(moment);
});

acc.length == 5 // true

Iteration also supports excluding the end value of the range by setting the last parameter to true.

var acc = [];

range1.by('d', function (moment) {
  acc.push(moment)
}, true);

acc.length == 4 // true

Compare

Compare range lengths or add them together with simple math:

var r_1 = moment.range(new Date(2011, 2, 5), new Date(2011, 3, 15));
var r_2 = moment.range(new Date(1995, 0, 1), new Date(1995, 12, 25));

r_2 > r_1 // true

r_1 + r_2 // duration of both ranges in milliseconds

Math.abs(r_1 - r_2); // difference of ranges in milliseconds

Equality

Check if two ranges are the same, i.e. their starts and ends are the same:

var r_1 = moment.range(new Date(2011, 2, 5), new Date(2011, 3, 15));
var r_2 = moment.range(new Date(2011, 2, 5), new Date(2011, 3, 15));
var r_3 = moment.range(new Date(2011, 3, 5), new Date(2011, 6, 15));

r_1.isSame(r_2); // true
r_2.isSame(r_3); // false

Difference

The difference of the entire range given various units.

Any of the units accepted by moment.js' add method may be used.

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 5, 5);
var dr    = moment.range(start, end);

dr.diff('months'); // 3
dr.diff('days'); // 92
dr.diff(); // 7945200000

Conversion

toArray

Converts the DateRange to an Array of Date objects.

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 5, 5);
var dr    = moment.range(start, end);

dr.toArray('days'); // [new Date(2011, 2, 5), new Date(2011, 3, 5), new Date(2011, 4, 5), new Date(2011, 5, 5)]

toDate

Converts the DateRange to an Array of the start and end Date objects.

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 5, 5);
var dr    = moment.range(start, end);

dr.toDate(); // [new Date(2011, 2, 5), new Date(2011, 5, 5)]

toString

Converting a DateRange to a String will format it as an ISO 8601 time interval:

var start = '2015-01-17T09:50:04+00:00';
var end   = '2015-04-17T08:29:55+00:00';
var range = moment.range(moment.utc(start), moment.utc(end));

range.toString() // "2015-01-17T09:50:04+00:00/2015-04-17T08:29:55+00:00"

valueOf

The difference between the end date and start date in milliseconds.

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 5, 5);
var range = moment.range(start, end);

range.valueOf(); // 7945200000

Center

Calculate the center of a range

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 3, 5);
var dr    = moment.range(start, end);

dr.center(); // 1300622400000

Clone

Deep clone a range

var start = new Date(2011, 2, 5);
var end   = new Date(2011, 3, 5);
var dr    = moment.range(start, end);

var dr2 = dr.clone();
dr2.start.add(2, 'days');

dr2.start.toDate() === dr.start.toDate() // false

Installation

moment-daterange works in both the browser and node.js.

Node / NPM

Install via npm:

npm install moment-daterange

And then require it:

var moment = require('moment');
require('moment-daterange');

Browser

Simply include moment-daterange after moment.js:

<script src="moment.js"></script>
<script src="moment.daterange.js"></script>

Running Tests

Install the dependencies:

npm install

Do all the things!

npm run-script build
npm run-script test
npm run-script jsdoc

License

moment-daterange is licensed (MIT).