Time Periods

Years, from 1970 to 2099.

Using years in a schedule:

  var sched = {schedules: [{Y: [2013, 2014, 2015]}]};

Performing years based calculations:

  var d = new Date('2013-03-22T10:02:05Z');

  later.year.name;
  --> 'year'

  later.year.range;
  --> 31556900

  later.year.val(d);
  --> 2013

  later.year.isValid(d, 2013);
  --> true

  later.year.extent();
  --> [1970, 2099]

  later.year.start(d);
  --> 'Tue, 01 Jan 2013 00:00:00 GMT'

  later.year.end(d);
  --> 'Tue, 31 Dec 2013 23:59:59 GMT'

  later.year.next(d, 2014);
  --> 'Wed, 01 Jan 2014 00:00:00 GMT'

  later.year.prev(d, 2012);
  --> 'Mon, 31 Dec 2012 23:59:59 GMT'

Later is fully extensible and it is easy to create your own custom time periods that can be used to define new schedules. To keep things simple, we'll walk through creating a new time period for indicating morning, afternoon, and evening. For our purposes, morning will be before noon and have a value of 0, afternoon will be before 6pm and have a value of 1, and evening will be before midnight and have a value of 2.

The first step is to create a name and id for the modifier and add it to the later namespace.

  later.partOfDay = later.pd = {
    // interface implementation goes here
  };

Next, we need to implement the time period interface. First we will just specify the name of this time period.

  name: 'part of day',

The range is approximately 6 hours. Though some of our periods are longer and some shorter, we'll use the shortest range which is afternoon at 6 hours.

  range: later.h.range * 6,

We then implement val to return the appropriate value based on the definition described previously.

  val: function(d) {
    return later.h.val(d) < 12 ? 0 :
           later.h.val(d) < 6 ? 1 :
           2;
  },

Then we can use our new val function to implement isValid.

  isValid: function(d, val) {
    return later.pd.val(d) === val;
  },

The extent is always going to be the same for every day so we can just return a constant array here.

  extent: function(d) { return [0, 2]; },

Next we need to implement start and end based on the current time period. This will be the start and end of each part of the day that we've defined.

  start: function(d) {
    var hour = later.pd.val(d) === 0 ? 0 :
                  later.pd.val(d) === 1 ? 12 :
                  6;

    // later.date.next is a helper function for creating the date in UTC or
    // localTime as appropriate
    return later.date.next(
      later.Y.val(d),
      later.M.val(d),
      later.D.val(d),
      hour
    );
  },

  end: function(d) {
    var hour = later.pd.val(d) === 0 ? 11 :
                  later.pd.val(d) === 1 ? 5 :
                  23;

    // later.date.prev is a helper function for creating the date in UTC or
    // localTime as appropriate, and automatically adjusts the date to be at
    // the last second of the specified time
    return later.date.prev(
      later.Y.val(d),
      later.M.val(d),
      later.D.val(d),
      hour
    );
  },

Finally, we need to implement next and prev so that you can move to different parts of the day. We need to make sure to increment and decrement the day appropriately if we've already passed the specified value.

  next: function(d, val) {
    var hour = val === 0 ? 0 : val === 1 ? 12 : 18;

    return later.date.next(
      later.Y.val(d),
      later.M.val(d),
      // increment the day if we already passed the desired time period
      later.D.val(d) + (hour < later.h.val(d) ? 1 : 0),
      hour
    );
  },

  prev: function(d, val) {
    var hour = val === 0 ? 11 : val === 1 ? 5 : 23;

    return later.date.prev(
      later.Y.val(d),
      later.M.val(d),
      // decrement the day if we already passed the desired time period
      later.D.val(d) + (hour > later.h.val(d) ? -1 : 0),
      hour
    );
  }

Full implementation

Here is the code for the completed example. To use the time period, just add this code after including Later into your project and before you use it in any schedules.

  later.partOfDay = later.pd = {

    name: 'part of day',

    range: later.h.range * 6,

    val: function(d) {
      return later.h.val(d) < 12 ? 0 :
             later.h.val(d) < 18 ? 1 :
             2;
    },

    isValid: function(d, val) {
      return later.pd.val(d) === val;
    },

    extent: function(d) { return [0, 2]; },

    start: function(d) {
      var hour = later.pd.val(d) === 0 ? 0 :
                    later.pd.val(d) === 1 ? 12 :
                    18;

      return later.date.next(
        later.Y.val(d),
        later.M.val(d),
        later.D.val(d),
        hour
      );
    },

    end: function(d) {
      var hour = later.pd.val(d) === 0 ? 11 :
                    later.pd.val(d) === 1 ? 5 :
                    23;

      return later.date.prev(
        later.Y.val(d),
        later.M.val(d),
        later.D.val(d),
        hour
      );
    },

    next: function(d, val) {
      var hour = val === 0 ? 0 : val === 1 ? 12 : 18;

      return later.date.next(
        later.Y.val(d),
        later.M.val(d),
        // increment the day if we already passed the desired time period
        later.D.val(d) + (hour < later.h.val(d) ? 1 : 0),
        hour
      );
    },

    prev: function(d, val) {
      var hour = val === 0 ? 11 : val === 1 ? 5 : 23;

      return later.date.prev(
        later.Y.val(d),
        later.M.val(d),
        // decrement the day if we already passed the desired time period
        later.D.val(d) + (hour > later.h.val(d) ? -1 : 0),
        hour
      );
    }
  };

Usage

Using the custom time period is exactly the same as using a built-in time period.

  // use our new time period to specify every 15 mins at night
  var sched = later.parse.recur().every(15).minute().on(2).customPeriod('pd'),
      next = later.schedule(sched).next(1, new Date(2013, 3, 21));

  console.log(next.toUTCString());
  --> Sun, 21 Apr 2013 18:00:00 GMT