Schedules

Schedules in Later are json objects that define a set of time periods along with the values that should be considered valid for that time period. The combination of a time period with their valid values is called a constraint. Later then takes all of the constraints that have been defined and finds dates that match all of them.

Since Later schedules are json objects, they can easily be serialized and stored in caches and databases as needed. They are also completely deterministic which means a schedule will always produce exactly the same valid occurrences. Therefore, occurrences never need to be stored as they can always be recalculated from the schedule definition.

Later includes a set of helpful parsers that makes generating valid schedules really easy. There is usually no need to manually create the schedule definition yourself, though it is useful to understand how to interpret a schedule definition.

A basic schedule is a set of time periods along with their valid values. A date is only considered valid if it meets all of the constraints within a basic schedule. A basic schedule can include as many time periods (with or without modifiers) as needed, in any order.

  // a basic schedule that is valid every day at 10:15am and 10:45am
  var basic = {h: [10], m: [15,45]};

Here we can see a schedule is made up of objects with properties that correspond to the various time periods. In this case h is the hour time period and m is the minute time period. The values to consider valid are always stored in an array as the value of the property.

Note Basic schedules are only valid as part of a complete schedule definition.

Multiple basic schedules can be combined into a single composite schedule by placing them into an array. A date is considered valid if any of the basic schedules are valid (basically an OR of all of the basic schedules). A composite schedule can contain as many basic schedules as needed.

  // a composite schedule that is valid every day at 10:15am and 10:45am
  // and every day at 5:30pm
  var composite = [
    {h: [10], m: [15,45]},
    {h: [17], m: [30]}
  ];

Note Composite schedules are only valid as part of a complete schedule definition.

An exception schedule is a basic or composite schedule that defines when a schedule should be considered invalid. A date is considered invalid if any of the basic schedules within an exception schedule are valid.

  // an exception schedule that makes any date in March as
  // well as any Monday of any month invalid
  var exception = [
    {M: [3]},
    {dw: [2]}
  ];

Note Exception schedules are only valid as part of a complete schedule definition.

A complete definition is a json object that at a minimum contains a schedules property that defines a composite schedule with at least one basic schedule. Optionally, the definition can also include an exceptions property that defines a composite exception schedule.

A valid schedule that fires every 10 minutes. The composite schedule is always placed in an object under a property named schedules. Even if you only have a basic schedule, the schedules property must be an array.

  var schedule = {
    schedules:
      [
        {m: [0,10,20,30,40,50]},
      ]
  };

A valid schedule definition that includes exceptions with modifiers. Here we see the composite exception schedule is always placed in an object under a property named exceptions. Even if you only have a basic exception schedule, the exceptions property must be an array.

  var schedule = {
    schedules:
      [
        {h: [10], m: [15,45]},
        {h: [17], m: [30]}
      ],
    exceptions:
      [
        {M_a: [3]},
        {dw: [2]}
      ]
  };

While Later has been designed to efficiently calculate occurrences for all types and complexities of schedules, there are a few things to keep in mind for applications that have particularly high performance requirements.

• Basic time periods perform the best. These include years, months, days, hours, minutes, and seconds. Calculating ISO week of year is particularly expensive.
• Schedules without exceptions perform better than those with exceptions. Defining your schedule without the need for exceptions will improve performance.
• Use the time time period instead of specifying hours and minutes seperately when possible. Reducing the number of constraints will generally improve performance.
• Using after and before modifiers to eliminate the need for specifying a lot of valid values will improve performance, especially when calculating ranges.