Yesterday (11/17 if I don’t finish this tonight), I walked through creating a somewhat friendlier wrapper around setInterval to make an API that could be used like cron. Its standard syntax is:

var cron = require('./cron'), sys = require('sys');
cron.Every((2).seconds(), function() { sys.puts('Working!'); });

While that is very expressive for the standards of code, my co-worker suggested that it was a little ugly/unfriendly for users. While there is certainly benefit to creating scheduled jobs programmatically, it’s possible that most users would just have predetermined jobs and intervals. In this installment, I’m going to try to rectify this situation.

Our starting files are at http://gist.github.com/238286. These are cleaned up a little bit from the last iteration, and github user fwg found an area where I forgot to include a ‘var’ keyword. Always run your code through jslint; a quick run I just did revealed that I left out some semicolons, and those errors can be hard to track down if your codebase gets big enough.

But I digress.

We want to establish some basic string patterns that represent time in a way that’s simple for users. If this is to be a cron replacement, it should ostensibly be easier to use. Luckily, crontab has one of the worst file formats in the universe (quick: what does * * 12 * 2 * 3 mean?). I propose recognition for the following interval patterns:

1. ‘5 weeks’, ‘5 days’, ‘5 hours’, ‘5 minutes’, ‘5 seconds’
2. the singular conjugations of #1, even if written as ‘2 second’
3. any combination of #1 interspersed with ’ and ’ or ‘&’ e.g. ‘5 weeks and 2 days’, ‘3 hours & 30 minutes’, ‘2 months and 1 week and 3 days’
4. ‘month’ ‘week’, ‘day’, ‘hour’, ‘minute’, or ‘second’, meaning once every month, week, day, hour, minute, or second respectively.

We’ll also allow these positional patterns:

1. Day of week for a weekly task (‘[Ss]aturday’ implies every Saturday)
2. ‘h?h:mm’ 24-hour clock time for a once/daily task
3. ‘h?h:mm(p|a)m?’ for 12-hour clock time for a once/daily task

Let’s start with specifying text for intervals. We’re going to create a exports.Time() function that parses these strings, and converts them to TimeInterval structures. While a pure, single regex solution might be possible, I think it’s cleaner to just divide the cases. Here’s a definition that covers the intervals we were already doing:

exports.Time = function(time) {
	if(time instanceof TimeInterval)
	{
		return time;
	}

	else if(typeof(time) == 'string')
	{
		var interval = new TimeInterval();
		if(time.match(/^(\d+) (month|week|day|hour|minute|second)s?/))
		{
			var clauses = time.split(/, | and | & |  /);
			var clauses_length = clauses.length;

			for(var i = 0; i < clauses_length; i++)
			{
				var clause_parsed = clauses[i].match(/(\d+) (month|week|day|hour|minute|second)s?/);
				if(clause_parsed != null)
				{
					var time = clause_parsed[1];
					var unit = clause_parsed[2];
					switch(unit)
					{
						case 'minute': 
							interval.addTo((+time).minutes());
							break;
						case 'hour': 
							interval.addTo((+time).hours());
							break;
						case 'second': 
							interval.addTo((+time).seconds());
							break;
						case 'day': 
							interval.addTo((+time).days());
							break;
					}
				}
			}
		}	

		else
		{
			var unit_parse = time.match(/month|week|day|hour|minute|second/);

			if(unit_parse != null)
			{
				switch(unit_parse[0])
				{
					case 'minute': 
						interval.addTo((1).minutes());
						break;
					case 'hour': 
						interval.addTo((1).hours());
						break;
					case 'second': 
						interval.addTo((1).seconds());
						break;
					case 'day': 
						interval.addTo((1).days());
						break;
				}
			}
		}
		return interval;
	}
}

This shouldn’t be too surprising if you’re used to regular expressions.This type of polymorphism might seem a little ugly to you coming from a Java or C/C++ statically typed world, but remember that in more functional languages, verbs are king. The action determines what to do with its input, not its input itself. Think of JavaScript objects as simple, flat structures.

Now, however, we get to do something cool. We get to change our definition of exports. Every to take a string input, and be completely transparent to the user and the change is even mostly transparent to us as well. Look at our new definition of exports.Every:

exports.Every = function(timeInterval, callback) {
        var parsed_time_interval = exports.Time(timeInterval);
	setInterval(callback, parsed_time_interval.seconds * 1000);
};

And here’s a basic call to it:

cron.Every('2 minutes', function() { sys.puts("It's been 2 minutes since you last saw this message"); });

All of our imaginary users’ old code works, but now we support the new, friendly syntax. Plus, since we’re exporting the time function, we’re making it easier for users to build a program on top of our library that takes input in the same format. And assuming this parsing engine ever gets reasonably sophisticated, that could add a lot of value.

I was going to include code to parse with specific offsets, (Every Saturday, Every 3:30 PM, etc.) but it appears I’ve written way too goddamn much already. So stay tuned, there will be a second subsection of this blog post.

Code available at: http://github.com/onewland/blog/tree/master/js-files/pt-2/ . Happy coding!