whimper
v0.1.7
Published
A simple, unintrusive, task runner for node.js.
Downloads
3
Readme
whimper
A simple, unintrusive, task runner for node.js.
notes
Please note that whimper is currently in an alpha state. Tests need to be stronger, examples need to be made better, and it it needs to gain some usage so the kinks can be ironed out. It's usable, for sure, just be sure to report any issues back here.. or, better yet, submit a patch!
You can find a list of current TODOs here
overview
whimper is, in reality, just a pretty api around managing and running JavaScirpt functions. It stays out of your way and lets you do what you do best: write code. It's simple yet eloquent. Compared to other task runners out there, it really is not a bang, but a whimper.
whimper is ...
- lightweight and out of your way
- built on promises
- just JavaScirpt functions
- plugin free!
- not globally installed
built on promises
whimper is built entirely on the use of promises. Every task takes in two arguments: params
and resolver
. The params
argument is an object describing any parameteres being passed to it. The resolver
argument is a when.js resolver. It is
each task's responsibility to either return another promise or resolve/reject its resolver.
plugin free
That's right! Why create yet another plugin system when all whimper does is call JavaScript functions anyways? So long as your function returns a promise (q, when, whatever) or resolves its own promise, whimper doesn't care. Why get all fancy?
not globally installed
Global installs stink. They make things stinky and whimper is not stinky. whimper, instead, let's you chose how you want to run your tasks. If you want run your tasks from the command line, whimper gives you a way to do that. If you want to run them through code, you can do that too. You have power to decide and that's a wonderful thing.. at least we think so!
concurrency & execution
whimper does not set out to be a highly concurrent task runner. Instead it tries to provide a framework for running tasks that most developers will find comfortable. With that said, whimper does not run very many tasks concurrently. In fact, the only tasks whimper will run concurrently are tasks that have no dependencies. Any tasks that do have dependencies will be ran sequentially, ensuring all dependencies are met before running. No task will start until its dependencies have been resolved. Should a dependency fail, the task fails as well.
installation
$ npm install whimper
a simple example
// tasks.js
var whimp = require('whimper');
whimp.task('simple-task', {
run: function(params, resolver) {
doSomethingAsync(function(error) {
if ( error != null ) {
resolver.reject(error);
}
else {
resolver.resolve();
}
});
}
});
whimp.run('simple-task');
and then ...
$ node tasks
with cli support
replace whimp.run('simple-task')
with whimp.cli()
and then ...
$ node tasks simple-task
task structure
whimp.task('task-name', {
// Optional.
describe: 'A description of this task',
// Optional. Any task options. Used by CLI.
options: {
'foo': 'An optional option.',
'!bar': 'A required option.'
},
// Conditional. An array of task names this task depends on. Either this or the
// run property is required.
depends: [ 'a', 'b' ],
// Conditional. What our task actually does. Either this or the depends property
// is required.
run: function(params, resolver) {
// Resolve yourself, return a promise,
// or return any non-undefined value (sync functions only)
}
});
If your task that doesn't need any frills (options, dependencies, etc), you can just pass task
a function.
whimpe.task('task-name', function(params, resolver) { ... });
A task can also be describe as just an array of dependencies. Great for composing.
whimp.task('task-name', [ 'a', 'b', 'c' ]);
a complex example
You can find a slightly more, though not any less contrived, example at examples/complex.js. You can run this example by doing ...
$ node complex --dir test
so, another task runner?
Does the node community really need yet another task runner? I believe that yes, yes we do. Why, you may ask? It's quite simple, I think. The task runners that exist today are either far too complicated (here's looking at you, grunt), far too niche (gulp is really a build system, not a task runner), or just wheel reinvention. There were no good (subjective, I know) task runners that allowed me to just run JavaScript. Everything required configuration, plugins, global installs, and the like. I didn't want that. I wanted to run JavaScript and JavaScript alone.
Hence, whimper was born.