From an instance of moment:
let recurrence;
// Create a recurrence using today as the start date.
recurrence = moment().recur();
// Create a recurrence while passing the start and end dates to the recur function.
// Note: passing an end date requires you to also pass a start date.
recurrence = moment().recur( start, end );
// You may pass a start date to the moment, or use an existing moment, to set the start date.
// In this case, passing a date to the recur function sets and end date.
recurrence = moment(start).recur( end );
// Finally, you can create a recurrence and pass in an entire set of options.
recurrence = moment().recur({
start: "01/01/2014",
end: "01/01/2015"
});
From static moment:
// Create recurrence without a start date. Note: this will not work with intervals.
recurrence = moment.recur();
// Create a recurrence, passing just the start, or the start and end dates.
recurrence = moment.recur( start, end );
// Create a recurrence, passing set of options.
recurrence = moment.recur({
start: "01/01/2014",
end: "01/01/2015"
});
Iterate over moments matched by rules
Note if there is no end date, results are unbounded (you must manually terminate the iterator).
Also note, this exapmle intentionally ignores some complicated leap year math.
let recurrence = moment('2012-01').recur('2032-01').every(4).years()
let leapYears = [...recurrence].map(m => m.year())
// leapYears = [ 2012, 2016, 2020, 2024, 2028, 2032 ]
Or, this is a bit faster...
let recurrence = moment('2012-01').recur('2032-01').every(4).years()
let leapYears = []
for (let date of recurrence) {
leapYears.push(date.year())
}
// leapYears = [ 2012, 2016, 2020, 2024, 2028, 2032 ]
With both a start date and an end date set, you can generate all dates within that range that match the pattern (including the start/end dates).
let recurrence = moment().recur("01/01/2014", "01/07/2014").every(2).days();
// Outputs: ["01/01/2014", "01/03/2014", "01/05/2014", "01/07/2014"]
allDates = recurrence.all("L");
Get/Set the End Date
recurrence.endDate(); // Get
recurrence.endDate("01/01/2014"); // Set
The every() function allows you to set the units and, optionally, the measurment type
of the recurring date. It returns the recur object to allow chaining.
let myDate, recurrence;
// Create a date to start from
myDate = moment("01/01/2014");
// You can pass the units to recur on, and the measurement type.
recurrence = myDate.recur().every(1, "days");
// You can also chain the measurement type instead of passing it to every.
recurrence = myDate.recur().every(1).day();
// It is also possible to pass an array of units.
recurrence = myDate.recur().every([3, 5]).days();
// When using the dayOfWeek measurement, you can pass days names.
recurrence = myDate.recur().every(["Monday", "wed"]).daysOfWeek();
// Month names also work when using monthOfYear.
recurrence = myDate.recur().every(["Jan", "february"], "monthsOfYear");
every() will override the last "every" if a measurement was not provided.
The following line will create a recurrence for every 5 days.
recurrence = myDate.recur().every(1).every(5).days();
If you need to specify multiple units, pass an array to every().
You may also pass the units directly to the interval functions (listed below)
instead of using every().
let recurrence = moment.recur().monthOfYear("January");
To prevent a date from matching that would normally match, use the except() function.
let recurrence = moment("01/01/2014").recur().every(1).day().except("01/02/2014");
recurrence.matches("01/02/2014"); // false
Forgets rules (by passing measure) and exceptions (by passing date)
// Exceptions can be removed by passing a date to the forget() function.
recurrence.forget("01/03/2014");
// Rules can be removed by passing the measurement to the forget() function.
recurrence.forget("days");
Get/Set a temporary "From Date" for use with generating dates
recurrence.fromDate(); // Get
recurrence.fromDate("01/01/2014"); // Set
Checks if a rule has been set on the chain
The matches() function will test a date to check if all of the recurrence rules match.
It returns true if the date matches, false otherwise.
let interval = moment("01/01/2014").recur().every(2).days();
interval.matches("01/02/2014"); // false
interval.matches("01/03/2014"); // true
You may also see if a date matches before the start date or after the end date by
passing true as the second argument to matches().
let interval = moment("01/01/2014").recur().every(2).days();
interval.matches("12/30/2013"); // false
interval.matches("12/30/2013", true); // true
Interval calculations will use a default of 1000 year limit when determining unbounded rules. Use this function to query or change the maximum limit.
// Will match any date that is in January of any year.
cal = moment.recur().every("January").monthsOfYear();
Get next N occurrences
// Generate the next three dates as moments
// Outputs: [moment("01/03/2014"), moment("01/05/2014"), moment("01/07/2014")]
nextDates = recurrence.next(3);
// Generate the next three dates, formatted in local format
// Outputs: ["01/03/2014", "01/05/2014", "01/07/2014"]
nextDates = recurrence.next(3, "L");
Get previous N occurrences
// Generate previous three dates, formatted in local format
// Outputs: ["12/30/2013", "12/28/2013", "12/26/2013"]
nextDates = recurrence.previous(3, "L");
Use repeats() to check if a recurrence has rules set.
recurrence.repeats(); // true/false
Reverse iterator direction
Note since there is no end date, results are unbounded (you must manually terminate the iterator).
let mondays = []
for (let monday of moment().recur().every('Monday').dayOfWeek().reverse()) {
lastThreeMondays.push(monday)
if (mondays.length > 10) break
}
Use save() to export all options, rules, and exceptions as an object.
This can be used to store recurrences in a database.
Note: This does not export the "From Date" which is considered a temporary option.
recurrence.save();
Get/Set the Start Date
recurrence.startDate(); // Get
recurrence.startDate("01/01/2014"); // Set
A weekOfMonthByDay interval is available for combining with the daysOfWeek to achieve "nth weekday of month" recurrences. The following matches every 1st and 3rd Thursday of the month.
(Note this cannot be combined at the moment with every(x).months() expression)
cal = moment.recur()
.every("Thursday").daysOfWeek()
.every([0, 2]).weeksOfMonthByDay();
cal = moment.recur()
.every(moment("01/01/2014").day()).daysOfWeek()
.every(moment("01/01/2014").monthWeekByDay()).weeksOfMonthByDay();
Generated using TypeDoc
The main Recur object to provide an interface for settings, rules, and matching
Creating Rules
moment-recur-ts uses rules to define when a date should recur. You can then generate future or past recurrences based on these rules, or see if a specific date matches the rules. Rules can also be overridden or removed.
Length Intervals
moment-recur-ts supports intervals for days, weeks, months, and years. Measurements may be singular or plural (ex:
day()vsdays()). Length Intervals must have a start date defined.Possible Length Intervals Include:
Calendar Intervals
Calendar Intervals do not depend on a start date. They define a unit of another unit. For instance, a day of a month, or a month of a year. Measurements may be singular or plural (ex:
dayOfMonth()vsdaysOfMonth()).Possible Calendar Intervals Include: