moment-wrange
Fancier date ranges for Moment.js.
About
This is a fork of moment-range. We forked because there were major changes that our team needed completed in a very quick manor, and we needed to get off of tracking a git repo and use a full on NPM package.
Primary Differences from moment-range v3.0.3 (forked release)
- codebase converted from ES6 to ES5
- broke out functions into individual files
- tests default to server-side testing (browser testing maintained)
- better follows the conventions used by moment.js for function signatures
- new functions have dropped the exclusive option for the inclusivity string that moment introduced in version 2.13.0
- new functions include access to the units of time for additional granularity
- Methods Added:
- add() allows both adjacent and overlapping inputs
- invertRanges() returns inverse of given ranges for all time
- isRange() determines whether an object is typeof MomentWrange
- mergeRanges() collapses an array of ranges into a minimal set
- many little cleanup items included
Installation
moment-wrange works in both the browser and node.js.
Node / NPM
Install via npm:
npm install --save moment-wrange
ES6:
;;const moment = ;
CommonJS:
const extendMoment = ;const moment = ;
Browser
window'moment-wrange';
Examples
Create
Create a date range:
const start = 2012 0 15;const end = 2012 4 23;const range = moment;
You can also create a date range with moment objects:
const start = ;const end = ;const range = moment;
Arrays work too:
const dates = ;const range = moment;
You can also create a range from an ISO 8601 time interval string:
const timeInterval = '2015-01-17T09:50:04+00:00/2015-04-17T08:29:55+00:00';const range = moment;
You can also create a range from the start until the end of a named interval:
const date = ;const range = date;
You can also create open-ended ranges which go to the earliest or latest possible date:
const rangeUntil = moment;const rangeFrom = moment;const rangeAllTime = moment;
Note: Dates and moment objects both use a timestamp of 00:00:000 if none is
provided. To ensure your range includes any timestamp for the given end date,
use .setHours(23,59,59,999)
when constructing a Date object, or
.endOf('day')
when constructing a moment object.
Attributes
You can access the start and end moments of the range easily enough:
const start = 2012 0 15;const end = 2012 4 23;const range = moment;rangestart // momentrangeend // moment
Querying
Adjacent
Check if two ranges are touching but not overlapping:
const a = ;const b = ;const c = ;const d = ;const range1 = moment;const range2 = moment;range1 // true
Center
Calculate the center of a range:
const start = 2011 2 5;const end = 2011 3 5;const dr = moment;dr; // 1300622400000
Contains
Check to see if your range contains a date/moment:
const start = 2012 4 1;const end = 2012 4 23;const lol = 2012 4 15;const wat = 2012 4 27;const range = moment;const range2 = moment;range; // truerange; // false
The exclusive
options is used to indicate if the end of the range should be
excluded when testing for inclusion:
range // truerange // truerange // false
Intersect
What are the intersecting ranges?
range; // [moment.range(lol, end)]
IsRange
Is this a MomentWrange object?
moment; // true
Overlaps
Does it overlap another range?
range; // true
Include adjacent ranges:
const a = ;const b = ;const c = ;const d = ;const range1 = moment;const range2 = moment;range1 // falserange1 // falserange1 // true
Within
Find out if your moment falls within a date range:
const start = 2012 4 1;const end = 2012 4 23;const when = ;const range = moment;when; // true
Manipulation
Add
Add/combine/merge adjacent or overlapping ranges.
range; // [moment.range(start, d)]const range3 = moment
Clone
Deep clone a range
const start = 2011 2 5;const end = 2011 3 5;const dr = moment;const dr2 = dr;dr2start;dr2start === drstart // false
Invert
The inverse ranges for all time.
; // [moment.range(null, c), moment.range(d, null)]
Merge
Collapses an array of ranges into the minimal set of non-overlapping and non-adjacent ranges.
const r1 = moment;const r2 = moment;const r3 = moment;const r4 = moment;; // [moment.range('2000-01-01', '2000-12-01'), moment.range('2001-01-01', '2001-07-01')]
Subtract
Subtracting one range from another.
range; // [moment.range(c, d)]
Iteration
Each of the iteration methods return an Iterable, providing a convenient and performant interface to iterating over your ranges by a given period.
by
Iterate over your range by a given period. Any of the units accepted by
moment.js' add
method may be used. E.g.: 'years' | 'quarters' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds'
const range = moment;for let month of rangemonth;const years = Array;yearslength == 5 // trueyears // ['2010', '2011', '2012', '2013', '2014', '2015']
Iteration also supports excluding the end value of the range by setting the
exclusive
option to true
.
const start = 2012 2 1;const end = 2012 2 5;const range1 = moment;const acc = Array;acclength == 4 // true
Additionally it's possible to iterate by a given step that defaults to 1
:
const start = 2012 2 2;const end = 2012 2 6;const range1 = moment;let acc = Array;acc // ['02', '04', '06']acc = Array;acc // ['02', '04']
byRange
const start = 2012 2 1;const two = 2012 2 2;const end = 2012 2 5;const range1 = moment;const range2 = moment; // One day
Iterate by another range:
const acc = Array;acclength == 5 // true
Exclude the end value:
const acc = Array;acclength == 4 // true
By step:
let acc = Array;acc // ['01', '03', '05']acc = Array;acc // ['01', '03']
reverseBy
Iterate over a range in reverse:
const range = moment;const acc = Array;acc // ['2015', '2014', '2013', '2012']
Exclude the end value:
const range = moment;const acc = Array;acc // ['2015', '2014', '2013']
By step:
const start = 2012 2 2;const end = 2012 2 6;const range1 = moment;let acc = Array;acc // ['06', '04', '02']acc = Array;acc // ['06', '04']
reverseByRange
const start = 2012 2 1;const two = 2012 2 2;const end = 2012 2 5;const range1 = moment;const range2 = moment; // One day
Iterate by another range in reverse:
const acc = Array;acclength == 5 // trueacc // ['05', '04', '03', '02', '01']
Exclude the end value:
const acc = Array;acclength == 4 // trueacc // ['05', '04', '03', '02']
By step:
let acc = Array;acc // ['05', '03', '01']acc = Array;acc // ['05', '03']
Compare
Compare range lengths or add them together with simple math:
const range1 = moment;const range2 = moment;range2 > range1 // truerange1 + range2 // duration of both ranges in millisecondsMath; // difference of ranges in milliseconds
Equality
Check if two ranges are the same, i.e. their starts and ends are the same:
const range1 = moment;const range2 = moment;const range3 = moment;range1; // truerange2; // falserange1; // truerange2; // false
Difference
The difference of the entire range given various units.
Any of the units accepted by moment.js' add
method may be used.
const start = 2011 2 5;const end = 2011 5 5;const dr = moment;dr; // 3dr; // 92dr; // 7945200000
Optionally you may specify if the difference should be rounded, by default it mimics moment-js' behaviour and rounds the values:
const d1 = Date;const d2 = Date;const range = moment;dr // 4dr // 4dr // 4.5
#duration
is an alias for #diff
and they may be used interchangeably.
Conversion
toDate
Converts the DateRange
to an Array
of the start and end Date
objects.
const start = 2011 2 5;const end = 2011 5 5;const dr = moment;dr; // [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:
const start = '2015-01-17T09:50:04+00:00';const end = '2015-04-17T08:29:55+00:00';const range = moment;range // '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.
const start = 2011 2 5;const end = 2011 5 5;const range = moment;range; // 7945200000
Running Tests
Clone:
git clone https://git@github.com/theroller/moment-wrange.git
Install the dependencies:
npm install
Do all the things!
npm run testnpm run test:browsernpm run lint
Contributors
- Adam Biggs (http://lightmaker.com)
- Mats Julian Olsen
- Matt Patterson (http://reprocessed.org/)
- Wilgert Velinga (http://neocles.io)
- Tomasz Bak (http://twitter.com/tomaszbak)
- Stuart Kelly
- Jeremy Forsythe
- Александр Гренишин
- @scotthovestadt
- Thomas van Lankveld
- nebel
- Kevin Ross (http://www.alienfast.com)
- Thomas Walpole
- Jonathan Kim (http://jkimbo.co.uk)
- Tymon Tobolski (http://teamon.eu)
- Aristide Niyungeko
- Bradley Ayers
- Ross Hadden (http://rosshadden.github.com/resume)
- Victoria French
- Jochen Diekenbrock
License
moment-wrange uses the MIT License.