Moment-daterange NPM

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

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).

@infinitebrahmanuniverse/nolb-mom @everything-registry/sub-chunk-2195 @zalastax/nolb-mom

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago

9 years ago