moment-range

What is moment-range?

The moment-range npm package extends the functionality of the Moment.js library to handle date ranges. It allows you to create, manipulate, and query ranges of dates with ease.

What are moment-range's main functionalities?

Creating Date Ranges

This feature allows you to create a date range by specifying a start and end date. The code sample demonstrates how to create a date range from January 1, 2023, to December 31, 2023.

const moment = require('moment');
const { extendMoment } = require('moment-range');
const momentRange = extendMoment(moment);

const start = moment('2023-01-01');
const end = moment('2023-12-31');
const range = momentRange.range(start, end);
console.log(range.toString());

Checking if a Date is within a Range

This feature allows you to check if a specific date falls within a given date range. The code sample checks if June 15, 2023, is within the range from January 1, 2023, to December 31, 2023.

const moment = require('moment');
const { extendMoment } = require('moment-range');
const momentRange = extendMoment(moment);

const start = moment('2023-01-01');
const end = moment('2023-12-31');
const range = momentRange.range(start, end);

const date = moment('2023-06-15');
console.log(range.contains(date)); // true

Iterating over Date Ranges

This feature allows you to iterate over each day within a date range. The code sample iterates over each day from January 1, 2023, to January 7, 2023, and prints the date.

const moment = require('moment');
const { extendMoment } = require('moment-range');
const momentRange = extendMoment(moment);

const start = moment('2023-01-01');
const end = moment('2023-01-07');
const range = momentRange.range(start, end);

for (let day of range.by('day')) {
  console.log(day.format('YYYY-MM-DD'));
}

Date Range Intersections

This feature allows you to find the intersection of two date ranges. The code sample finds the intersection of two date ranges: January 1, 2023, to June 30, 2023, and April 1, 2023, to December 31, 2023.

const moment = require('moment');
const { extendMoment } = require('moment-range');
const momentRange = extendMoment(moment);

const range1 = momentRange.range('2023-01-01', '2023-06-30');
const range2 = momentRange.range('2023-04-01', '2023-12-31');
const intersection = range1.intersect(range2);
console.log(intersection.toString()); // 2023-04-01 - 2023-06-30

Other packages similar to moment-range

date-fns

date-fns is a modern JavaScript date utility library that provides a comprehensive set of functions for manipulating dates. Unlike moment-range, date-fns is modular, allowing you to import only the functions you need. It also has a smaller footprint and better performance.

luxon

Luxon is a modern JavaScript library for working with dates and times. It is a successor to Moment.js and offers a more powerful and flexible API. Luxon supports date ranges through its Interval class, which provides similar functionality to moment-range.

dayjs

Day.js is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times. It is a lightweight alternative to Moment.js with a similar API. Day.js can be extended with plugins to support date range functionality, making it a versatile option.

README

moment-range

Fancy date ranges for Moment.js.

Examples

Create

Create a date range:

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

You can also create a date range with moment objects:

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

Contains / Within / Overlaps / Intersect / Subtract

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

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

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

Find out if your moment falls within a date range:

var start = new Date(2012, 4, 1)
  , end   = new Date(2012, 4, 23)
  , when  = moment("2012-05-10", "YYYY-MM-DD")
  , 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)]

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)
  , two   = new Date(2012, 2, 2)
  , end   = new Date(2012, 2, 5)
  , range1 = moment().range(start, end)
  , range2 = moment().range(start, two) // One day
  , 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

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))
  , 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))
  , r_2 = moment().range(new Date(2011, 2, 5), new Date(2011, 3, 15))
  , 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

Installation

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

Browser

Simply include moment-range after moment.js:

<script src="/javascripts/moment-range.js"></script>

NPM

Install via npm:

npm install moment-range

Or put it in your package.json:

{ "moment-range": "~1" }

Bower

bower install moment-range

Running Tests

Clone this bad boy:

git clone https://[e-mail]/gf3/moment-range.git

Install the dependencies:

npm install

Do all the things! (including the tests)

$ grunt

License

moment-range is UNLICENSED.