moment-recur-ts

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>moment-recur-ts</title> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">moment-recur-ts</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-externals" checked /> <label class="tsd-widget" for="tsd-filter-externals">Externals</label> <input type="checkbox" id="tsd-filter-only-exported" /> <label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <ul class="tsd-breadcrumb"> <li> <a href="globals.html">Globals</a> </li> </ul> <h1> moment-recur-ts</h1> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <h1 id="moment-recur-ts">moment-recur-ts</h1> This is a fork and conversion of the moment-recur library into TypeScript. <a href="https://jefbarn.github.io/moment-recur-ts/">Online documentation</a> <a href="https://badge.fury.io/js/moment-recur-ts"><img src="https://badge.fury.io/js/moment-recur-ts.svg" alt="npm version"></a> <a href="https://travis-ci.org/jefbarn/moment-recur-ts"><img src="https://travis-ci.org/jefbarn/moment-recur-ts.svg?branch=master" alt="Build Status"></a> <a href="https://coveralls.io/github/jefbarn/moment-recur-ts?branch=master"><img src="https://coveralls.io/repos/github/jefbarn/moment-recur-ts/badge.svg?branch=master" alt="Coverage Status"></a> <a href="https://greenkeeper.io/"><img src="https://badges.greenkeeper.io/jefbarn/moment-recur-ts.svg" alt="Greenkeeper badge"></a> Original work is <a href="https://github.com/c-trimm/moment-recur">c-trimm/moment-recur</a> moment-recur-ts is a recurring date plugin for <a href="http://momentjs.com/">momentjs</a>. This plugin handles dates only; time information is discarded. The rule matching concept is borrowed from the excellent <a href="https://github.com/appsattic/node-date-recur">node-date-recur</a> library created by Andrew Chilton. <pre><code class="lang-js">let interval = moment( "01/01/2014" ).recur().every(2).days(); interval.matches( "01/03/2014" ); // true let calendar = moment.recur().every(10).dayOfMonth(); calendar.matches( "05/10/2014" ); // true </code></pre> <h2 id="getting-started">Getting Started</h2> moment-recur-ts can be included in your project a few different ways. <h3 id="node-js">node.js</h3> moment-recur-ts can be installed with npm and required into a script. <pre><code>npm install moment-recur-ts or yarn add moment-recur-ts </code></pre><pre><code class="lang-js">let moment = require('moment'); require('moment-recur-ts'); </code></pre> <h3 id="webpack-es6-typescript">Webpack + ES6/TypeScript</h3> <pre><code class="lang-js">import * as moment from 'moment' import 'moment-recur-ts' </code></pre> <h3 id="browser">Browser</h3> Simply include the momentjs script, then the moment-recur-ts script. <pre><code class="lang-html"><script src="moment.min.js"></script> <script src="moment-recur-ts.min.js"></script> </code></pre> <h3 id="polyfills">Polyfills</h3> moment-recur-ts uses newer Javascript ES6 features and may require a polyfill library for older browsers or node.js < 7. <pre><code class="lang-html"><script src="https://unpkg.com/moment/min/moment.min.js"></script> <script src="https://unpkg.com/moment-recur-ts/dist/moment-recur-ts.min.js"></script> <script src="https://unpkg.com/core-js/client/core.min.js"></script> </code></pre> <pre><code class="lang-js">require('core-js'); let moment = require('moment'); require('moment-recur-ts'); </code></pre> <h2 id="creating-a-recurring-date">Creating a Recurring Date</h2> You can create a recurrence from an instance of moment or from the constructor a few different ways. From an instance: <pre><code class="lang-js">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" }); </code></pre> From the constructor: <pre><code class="lang-js">let recurrence; // 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" }); </code></pre> <h2 id="creating-rules">Creating Rules</h2> 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. <h3 id="the-every-function">The every() Function</h3> The <code>every()</code> function allows you to set the units and, optionally, the measurment type of the recurring date. It returns the recur object to allow chaining. <pre><code class="lang-js">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"); </code></pre> <code>every()</code> will override the last "every" if a measurement was not provided. The following line will create a recurrence for every 5 days. <pre><code class="lang-js">recurrence = myDate.recur().every(1).every(5).days(); </code></pre> If you need to specify multiple units, pass an array to <code>every()</code>. You may also pass the units directly to the interval functions (listed below) instead of using <code>every()</code>. <pre><code class="lang-js">let recurrence = moment.recur().monthOfYear("January"); </code></pre> <h3 id="length-intervals">Length Intervals</h3> moment-recur-ts supports intervals for days, weeks, months, and years. Measurements may be singular or plural (ex: <code>day()</code> vs <code>days()</code>). Length Intervals must have a start date defined. Possible Length Intervals Include: <ul> <li>day / days</li> <li>week / weeks</li> <li>month / months</li> <li>year / years</li> </ul> <h4 id="examples">Examples</h4> <pre><code class="lang-js">let myDate, interval; // Create a date to start from myDate = moment("01/01/2014"); // A daily interval - will match every day. interval = myDate.recur().every(1).day(); // A bi-weekly interval - will match any date that is exactly 2 weeks from myDate. interval = myDate.recur().every(2).weeks(); // A quarterly interval - will match any date that is exactly 3 months from myDate. interval = myDate.recur().every(3).months(); // A yearly interval - will match any date that is exactly 1 year from myDate. interval = myDate.recur().every(1).years(); // It is possible to match multiple units of a single measure using an array. interval = myDate.recur().every([3, 5]).days(); // It is NOT possible to create compound intervals. The following will never match. interval = myDate.recur().every(3).days().every(2).months(); // Won't work </code></pre> <h3 id="calendar-intervals">Calendar Intervals</h3> 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: <code>dayOfMonth()</code> vs <code>daysOfMonth()</code>). Possible Calendar Intervals Include: <ul> <li>dayOfWeek / daysOfWeek</li> <li>dayOfMonth / daysOfMonth</li> <li>weekOfMonth / weeksOfMonth</li> <li>weekOfYear / weeksOfYear</li> <li>monthOfYear / monthsOfYear</li> </ul> <h4 id="examples">Examples</h4> <pre><code class="lang-js">let cal; // Will match any date that is on Sunday or Monday. cal = moment.recur().every(["Sunday", 1]).daysOfWeek(); // Will match any date that is the first or tenth day of any month. cal = moment.recur().every([1, 10]).daysOfMonth(); // Will match any date that is in the first or third week of any month. cal = moment.recur().every([1, 3]).weeksOfMonth(); // Will match any date that is in the 20th week of any year. cal = moment.recur().every(20).weekOfYear(); // Will match any date that is in January of any year. cal = moment.recur().every("January").monthsOfYear(); // You can also combine these rules to match specific dates. // For instance, this will match only on Valentines day let valentines = moment.recur().every(14).daysOfMonth() .every("Februray").monthsOfYear(); // 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(); </code></pre> <h2 id="using-the-rules">Using the Rules</h2> <h3 id="matching">Matching</h3> The <code>matches()</code> function will test a date to check if all of the recurrence rules match. It returns <code>true</code> if the date matches, <code>false</code> otherwise. <pre><code class="lang-js">let interval = moment("01/01/2014").recur().every(2).days(); interval.matches("01/02/2014"); // false interval.matches("01/03/2014"); // true </code></pre> You may also see if a date matches before the start date or after the end date by passing <code>true</code> as the second argument to <code>matches()</code>. <pre><code class="lang-js">let interval = moment("01/01/2014").recur().every(2).days(); interval.matches("12/30/2013"); // false interval.matches("12/30/2013", true); // true </code></pre> <h3 id="exceptions">Exceptions</h3> To prevent a date from matching that would normally match, use the <code>except()</code> function. <pre><code class="lang-js">let recurrence = moment("01/01/2014").recur().every(1).day().except("01/02/2014"); recurrence.matches("01/02/2014"); // false </code></pre> <h3 id="overriding-and-forgetting">Overriding and Forgetting</h3> If a rule is created with the same measurement of a previous rule, it will override the previous rule. Rules can also be removed from a recurrence. <pre><code class="lang-js">// Create a recurrence that matches every day, with an exception let recurrence = moment("01/01/2014").recur().every(1).day().except("01/03/2014"); // This will override the previous rule and match every 2 days instead. recurrence.every(2).days(); // Exceptions can also 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"); </code></pre> <h3 id="generating-dates">Generating Dates</h3> It is also possible to generate dates from the rules. These functions require a starting date. <pre><code class="lang-js">let recurrence, nextDates; // Create a recurrence recurrence = moment("01/01/2014").recur().every(2).days(); // 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"); // Generate previous three dates, formatted in local format // Outputs: ["12/30/2013", "12/28/2013", "12/26/2013"] nextDates = recurrence.previous(3, "L"); </code></pre> If your recurrence does not have a start date set, or if it does but you want to start at a different date, use the <code>fromDate()</code> method first. <pre><code class="lang-js">let recurrence = moment("01/01/2014").recur().every(2).days(); recurrence.fromDate("02/05/2014"); // Outputs: ["02/06/2014", "02/08/2014", "02/10/2014"] nextDates = recurrence.next(3, "L"); </code></pre> 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). <pre><code class="lang-js">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"); </code></pre> Important Note: These functions may be very inefficient/slow. They work by attempting to match every date from the start of a range until the desired number of dates have been generated. So if you attempt to get 10 dates for a rule that matches once a year, it will run the match function for ~3650 days. <h2 id="options-and-other-methods">Options and Other Methods</h2> moment-recur-ts provides a few methods for getting/setting options, as well as two utility methods. It also creates two additional momentjs functions. <h3 id="options">Options</h3> Options can be set when creating a recurrence or using the getter/setter methods listed below. Set options upon creation. Note that the units for rules are converted to objects, so it is not recommended to set rules this way. They can be set in the options so that they can be imported. <pre><code class="lang-js">moment().recur({ start: "01/01/2014", end: "12/31/2014", rules: [ { units: [2], measure: "days" } ], exceptions: ["01/05/2014"] }); </code></pre> Get/Set the Start Date <pre><code class="lang-js">recurrence.startDate(); // Get recurrence.startDate("01/01/2014"); // Set </code></pre> Get/Set the End Date <pre><code class="lang-js">recurrence.endDate(); // Get recurrence.endDate("01/01/2014"); // Set </code></pre> Get/Set a temporary "From Date" for use with generating dates <pre><code class="lang-js">recurrence.fromDate(); // Get recurrence.fromDate("01/01/2014"); // Set </code></pre> <h3 id="utility-methods">Utility Methods</h3> Use <code>repeats()</code> to check if a recurrence has rules set. <pre><code class="lang-js">recurrence.repeats(); // true/false </code></pre> Use <code>save()</code> 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. <pre><code class="lang-js">recurrence.save(); </code></pre> <h3 id="momentjs-functions">momentjs Functions</h3> The <code>monthWeek()</code> method can be used to determine the week of the month a date is in. <pre><code class="lang-js">moment("01/01/2014").monthWeek(); // 0 </code></pre> The <code>dateOnly()</code> method can be used to remove any time information from a moment. <pre><code class="lang-js">moment("2014-01-01 09:30:26").dateOnly(); // 01/01/2014 12:00:00 AM </code></pre> <h2 id="license">License</h2> MIT License See LICENSE file for details. </div> </div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class="globals "> <a href="globals.html">Globals</a> </li> <li class=" tsd-kind-module tsd-is-not-exported"> <a href="modules/_moment_.html">"moment"</a> </li> <li class=" tsd-kind-module"> <a href="modules/rule.html">Rule</a> </li> </ul> </nav> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> <li class=" tsd-kind-class"> <a href="classes/recur.html" class="tsd-kind-icon">Recur</a> </li> </ul> </nav> </div> </div> </div> <footer class="with-border-bottom"> <div class="container"> <h2>Legend</h2> <div class="tsd-legend-group"> <ul class="tsd-legend"> <li class="tsd-kind-module">Module</li> <li class="tsd-kind-object-literal">Object literal</li> <li class="tsd-kind-variable">Variable</li> <li class="tsd-kind-function">Function</li> <li class="tsd-kind-function tsd-has-type-parameter">Function with type parameter</li> <li class="tsd-kind-index-signature">Index signature</li> <li class="tsd-kind-type-alias">Type alias</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-enum">Enumeration</li> <li class="tsd-kind-enum-member">Enumeration member</li> <li class="tsd-kind-property tsd-parent-kind-enum">Property</li> <li class="tsd-kind-method tsd-parent-kind-enum">Method</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-interface">Interface</li> <li class="tsd-kind-interface tsd-has-type-parameter">Interface with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-interface">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-interface">Property</li> <li class="tsd-kind-method tsd-parent-kind-interface">Method</li> <li class="tsd-kind-index-signature tsd-parent-kind-interface">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-class">Class</li> <li class="tsd-kind-class tsd-has-type-parameter">Class with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-class">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-class">Property</li> <li class="tsd-kind-method tsd-parent-kind-class">Method</li> <li class="tsd-kind-accessor tsd-parent-kind-class">Accessor</li> <li class="tsd-kind-index-signature tsd-parent-kind-class">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited">Inherited constructor</li> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited">Inherited property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited">Inherited method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited">Inherited accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected">Protected property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected">Protected method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected">Protected accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-private">Private property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-private">Private method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private">Private accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-static">Static property</li> <li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static">Static method</li> </ul> </div> </div> </footer> <div class="container tsd-generator"> Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a> </div> <div class="overlay"></div> <script src="assets/js/main.js"></script> <script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script> </body> </html>