Occurrences

Once a schedule has been defined, it can be used to calculate future and past occurrences of that schedule. An occurrence is a date that meets all of the constraints imposed by the schedule.

In order to improve performance, schedules are first compiled prior to occurrences being calculated. The compiled version of the schedule can be reused to find additional occurrences as needed.

To compile a schedule, pass the schedule definition to later.schedule.

  var sched = later.schedule(schedule);

Tip All schedule definitions are 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 time (the default)
  later.date.UTC();

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

Returns true if the date passed in is a valid occurrence of the schedule, false otherwise.

  var valid = later.schedule(schedule).isValid(date);

Examples

  var sched = later.schedule(later.parse.recur().on(1,2,3).minute());

  sched.isValid(new Date('2013-03-22T10:02:00Z'));
  --> true

  sched.isValid(new Date('2013-03-22T10:22:00Z'));
  --> false

  sched.isValid(new Date('2013-03-22T10:02:05Z'));
  --> false

Instances are individual dates that meet all of the constraints that are imposed by the schedule. Instances can be calculated both forwards and backwards, in any quantity, and optionally between a start and end date. When calculating multiple instances, the minimum time between instances is based on the smallest ranged time period.

later.schedule(schedule).next(count, start, end)

Calculates the next count occurrences of schedule, optionally starting from the start date and ending before the end date.

  later.schedule({schedules: [{m: [5]}]}).next(2);

later.schedule(schedule).prev(count, start, end)

Calculates the previous count occurrences of schedule, optionally starting from the start date and ending before the end date. When using previous, the start date must be greater than the end date.

  later.schedule({schedules: [{m: [5]}]}).prev(2);

Examples

  // sched for minute equal to 1,2, or 3
  var sched = later.schedule(later.parse.recur().on(1,2,3).minute()),
      start = new Date('2013-05-22T10:22:00Z');

  // get the next instance
  sched.next(1, start);
  --> Mon, 22 May 2013 11:01:00 GMT

  // get the next 5 instances
  sched.next(5, start);
  --> [ 'Mon, 22 May 2013 11:01:00 GMT',
        'Mon, 22 May 2013 11:02:00 GMT',
        'Mon, 22 May 2013 11:03:00 GMT',
        'Mon, 22 May 2013 12:01:00 GMT',
        'Mon, 22 May 2013 12:02:00 GMT' ]

  // get the previous instance
  sched.prev(1, start);
  --> Mon, 22 May 2013 10:03:00 GMT

Ranges combine consecutively valid instances into a single start and end block of time. The start time is the first valid instance of the block of time. The end time is the first invalid time after the block.

Ranges are useful when scheduling blocks of time such as a meeting or activity. The schedule definition defines the start and end time of the activity and then ranges are used to find their occurrences.

later.schedule(schedule).nextRange(count, start, end)

Calculates the next count ranges of schedule, optionally starting from the start date and ending before the end date.

  later.schedule({schedules: [{m:[5,6,7]}]}).nextRange(2);

later.schedule(schedule).prevRange(count, start, end)

Calculates the previous count ranges of schedule, optionally starting from the start date and ending before the end date.

  later.schedule({schedules: [{m:[5,6,7]}]}).prevRange(2);

Examples

  // sched for minute equal to 1,2, or 3
  var sched = later.schedule(later.parse.recur().on(1,2,3).minute()),
      start = new Date('2013-05-22T10:22:00Z');

  // get the next range
  sched.nextRange(1, start);
  --> ['Mon, 22 May 2013 11:01:00 GMT', 'Mon, 22 May 2013 11:04:00 GMT']

  // get the next 5 ranges
  sched.nextRange(5, start);
  --> [
        ['Mon, 22 May 2013 11:01:00 GMT', 'Mon, 22 May 2013 11:04:00 GMT']
        ['Mon, 22 May 2013 12:01:00 GMT', 'Mon, 22 May 2013 12:04:00 GMT']
        ['Mon, 22 May 2013 13:01:00 GMT', 'Mon, 22 May 2013 13:04:00 GMT']
        ['Mon, 22 May 2013 14:01:00 GMT', 'Mon, 22 May 2013 14:04:00 GMT']
        ['Mon, 22 May 2013 15:01:00 GMT', 'Mon, 22 May 2013 15:04:00 GMT']
      ]

  // get the previous range
  sched.prevRange(1, start);
  --> ['Mon, 22 May 2013 10:01:00 GMT', 'Mon, 22 May 2013 10:04:00 GMT']