Scheduler API

is a fast, light algorithm that transforms data (a list of schedules) into metadata (availability groups and conflicts).

Previously, I drafted a course scheduling platform that took in a list of courses, figured out the right combinations of sections, and return all the possible combinations of schedules possible. However, all my code for making REST requests and figuring out the schedules was jumbled together. In "Scheduler API" I hope to define a standard metadata transformation protocol to make not only course scheduling possible, but also a host of other possible projects relating to schedule-conflict matching, such as a more sophisticated When-is-Good-type application.

How to use

This API only transforms data, so it will pass through like a function. There are multiple options depending on how you want to handle your data. You can process the data synchronously and receive a return value, or you can use an asynchronous function that's basically the synchronous function wrapped in a promise, or you can process every item asynchronously as it comes via a callback...

var scheduler = require('scheduler-api');
var corpus = {...}; // see section "Data models"

// synchronous:
var transformed = scheduler.combinations.sync(corpus);

// thenable:
scheduler.combinations.async(corpus, function (piece) {
  console.log(piece);
}).then(function (transformed) {
  console.log(transformed);
});

Data models

The input-output data models are going to be very complex. They are designed with a course scheduling algorithm in mind. I'll try to explain them as simply as possible:

Input

Overall, we say that there are multiple independent entities, e.g. courses or persons. Within an entity, we have a list of every possible parallel universe, which we refer to as scenarios. Situations like course scheduling will require multiple scenarios, but situations like WhenIsGood should only need 1 scenario. Within each scenario, we have a list of blocks in the schedule. Each block is assigned with a startTime, an endTime, and a day. The times are assigned from 0 to 1440, which represent the minutes in a 24-hour period (60*24=1440). The day doesn't have to be a date, it just has to be a unique identifier, such as the day of the week.

var entities = {
  entityid1: {
    scenarioid1: {
      blockid1: [{start: '10:30', end: '13:30', day ['M', 'W']}],
      blockid2: [{...}],
      ...
    },
    scenarioid2: {},
    ...
  },
  entityid2: {
    ...
  },
  ...
};

Take a hard look at how this JSON tree is organized and nested. Entities and blocks are allowed to have metadata, but scenarios don't. Scenario ID's are not important; they only have to be unique within the group (incremented). Entities and blocks all have unique identifiers.

Output

There are two types of outputs: combinations and conflicts. In the case of course scheduling, we are more interested in combinations of scenarios that work for as many entities as possible. However for WhenIsGood, we are actually looking for intersections of availabilities. So, our solution will transform both types of data.

var combinations = [
  {
    entityid1: scenarioid1,
    entityid2: scenarioid2,
    ...
  },
  {
    entityid1: scenarioid2,
    entityid2: scenarioid3,
    ...
  },
  ...
];

var conflict = {
  // coming soon...
};

Conclusion

Thanks for taking a look at this light javascript scheduling API!

Authored by Andrew Jiang.