The simplest way to work with recurring schedules.

Easily define complex schedules then quickly calculate future or previous schedule occurrences. Works in Node and in the browser.

View on GitHub Get Started

Use the chainable recur api to build up complex schedules

  // fires every 2 hours on the first day of every month
  // and 8:00am and 8:00pm on the last day of every month
  // except in December
  var sched = later.parse.recur()
                .every(2).hour().first().dayOfMonth()
              .and()
                .on(8,20).hour().last().dayOfMonth()
              .except()
                .on(12).month();

  // get the next 10 valid occurrences
  later.schedule(sched).next(10);

...or use any valid Cron expression

  // fires at 10:15am every day
  var cron = '15 10 * * ? *';
  var s = later.parse.cron(cron);

  later.schedule(s).next(10);

...or a simple text expression

  // fires every 5 minutes
  var text = 'every 5 mins';
  var s = later.parse.text(text);

  later.schedule(s).prev(10);

No dependencies

Later has exactly zero dependencies which, along with its compact size (about 8kb compressed), makes incorporating it into your application a piece of cake.

Serializable

Schedules are simple json objects that are fully serializable. Easy and efficient to store in databases and in caches.

Large library of time periods

Schedules can be produced with all common time periods (seconds, minutes, etc) as well as ISO weeks, day of year, nth week of month, and others.

Unit tests included

Supported by a test suite of over 41,500 unit and scenario tests, additional tests for new scenarios always welcome.

Deterministic

All schedules are completely deterministic, meaning that they always produce the same set of valid occurrences regardless of when you calculate them.

Fully extensible

Create your own time periods that can then be used in any schedule. Write modifiers to add additional functionality to existing time periods.

Need to calculate start and end times for tasks, meetings or events? Check out Schedule.js. Built on Later, Schedule lets you easily schedule anything with full support for dependencies, resource reservations, and flexible ways to define availability (i.e. specify working hours including a lunch break).

Quick start

Step 1: Install

Later is available through both npm and bower. After installing, Later is available in the later namespace.

Using npm and Node.js:

  $ npm install @breejs/later

  var later = require('@breejs/later');

  <script src="later.min.js" type="text/javascript"></script>
  <script type="text/javascript">
    // later namespace is available
  </script>

More information on building, running tests, and running benchmarks.

Step 2: Define a schedule

The first step is to create a new schedule definition. There are a bunch of different ways to define a schedule, but at the end of the day they are just simple json objects that can easily be serialized and stored.

  // define a new schedule
  var textSched = later.parse.text('at 10:15am every weekday');
  var cronSched = later.parse.cron('0 0/5 14,18 * * ?');
  var recurSched = later.parse.recur().last().dayOfMonth();
  var manualSched = {schedules: [{M: 3, D: 21}]};

Schedules can also get as complicated as you need:

  // this schedule will fire on the closest weekday to the 15th
  // every month at 2:00 am except in March
  var complexSched = later.parse.recur()
                  .on(15).dayOfMonth().onWeekday().on(2).hour()
                .and()
                  .on(14).dayOfMonth().on(6).dayOfWeek().on(2).hour()
                .and()
                  .on(16).dayOfMonth().on(2).dayOfWeek().on(2).hour()
                .except()
                  .on(3).month();

More information on supported time periods, creating schedules, and using parsers.

Step 3: Configure timezone

All schedule definitions are completely timezone agnostic. When you need to calculate occurrences, you can decide to perform the calculation using local time or UTC.

  // set later to use UTC (the default)
  later.date.UTC();

  // set later to use local time
  later.date.localTime();

Step 4: Calculate occurrences

Once a schedule has been defined, calculating future (or past) occurrences is very straightforward. You can calculate as many occurrences as you need in either a forward or backward direction. You can even calculate ranges with start and end dates which allows scheduling of appointments or events.

  // calculate the next 10 occurrences of a recur schedule
  var recurSched = later.parse.recur().last().dayOfMonth();
      next = later.schedule(recurSched).next(10);

  // calculate the previous occurrence starting from March 21, 2013
  var cronSched = later.parse.cron('0 0/5 14,18 * * ?'),
      next = later.schedule(cronSched).prev(1, new Date(2013, 2, 21));

More information on calculating individual instances and ranges.

Step 5: Execute code using a Later schedule

Later includes implementations of setTimeout() and setInterval() that work with Later schedules instead of milliseconds. This makes it extremely easy to execute code based on a schedule definition.


  // will fire every 5 minutes
  var textSched = later.parse.text('every 5 min');

  // execute logTime one time on the next occurrence of the text schedule
  var timer = later.setTimeout(logTime, textSched);

  // execute logTime for each successive occurrence of the text schedule
  var timer2 = later.setInterval(logTime, textSched);

  // function to execute
  function logTime() {
    console.log(new Date());
  }

  // clear the interval timer when you are done
  timer2.clear();

More information on setTimeout and setInterval.

View full documentation

Later.js