Because everyone loves a trier! Conditional and repeated function invocation for node and browser.
Sometimes, you want to defer calling a function until a certain pre-requisite condition is met. Other times, you want to call a function repeatedly until some post-requisite condition is satisfied. Occasionally, you might even want to do both for the same function.
To save you writing explicit conditions and loops on each of those occasions, trier.js implements a predicate-based approach that hides the cruft behind a simple, functional interface.
Additionally, it allows you to easily specify retry intervals and limits, so that your code doesn't hog the CPU. It also supports exponential incrementation of retry intervals, which can be useful when handling indefinite error states such as network failure.
You can install trier.js
with one of
the package managers:
NPM;
Jam;
Bower;
or Component.
The package name
for the first three
is trier
and for Component
it's philbooth/trier.js
:
npm install trier
jam install trier
bower install trier
component install philbooth/trier.js
Alternatively, you can just clone the git repository from GitHub:
git clone git@github.com:philbooth/trier.js.git
If you are running in
Node.js,
Browserify
or another CommonJS-style
environment,
you can require
trier.js like so:
var trier = require('trier');
It also the supports the AMD-style format preferred by Require.js:
require.config({
paths: {
trier: 'trier.js/src/trier'
}
});
require([ 'trier' ], function (trier) {
});
If you are
including trier.js
with an HTML <script>
tag,
or neither of the above environments
are detected,
trier.js will just export its interface globally
as trier
.
trier.js
has no dependencies
and exports
a single public function,
attempt
,
which enables you to
conditionally
and repeatedly
call functions
without writing
explicit if
statements
or loops.
trier.attempt
takes one argument,
an options object
that supports
the following properties:
when
: A callback function used to test the pre-condition for function invocation. Untilwhen
returns true (or a truthy value), theaction
function will not be called. If undefined, it defaults to a function defined asfunction () { return true; }
.until
: A callback function used to test the post-condition for terminating function invocation. Afteruntil
returns true (or a truthy value), theaction
function will no longer be called. If undefined, it defaults to a function defined asfunction () { return true; }
.action
: The invocation target. A function that will be called according to the values returned bywhen
anduntil
. If undefined, it defaults to a function defined asfunction () {}
. If your implementation ofaction
expects any arguments, it will be treated as asynchronous and passed an additional function parameter,done
. You must calldone
when the action is finished.fail
: The error handler. A function that will be called iflimit
falsey values are returned bywhen
oruntil
. If undefined, it defaults to a function defined asfunction () {}
.pass
: Success handler. A function that will be called afteruntil
has returned truthily. If undefined, it defaults to a function defined asfunction () {}
.limit
: Failure limit, representing the number of times thatwhen
anduntil
may return a falsey value, before the invocation is deemed to have failed and attempts to callaction
will cease. A negative number indicates that the attempt should never fail, instead continuing indefinitely untilwhen
anduntil
have returned truthy values. Defaults to -1.interval
: A number representing the retry interval, in milliseconds. Use a negative number to indicate that each subsequent retry should wait for twice the interval from the preceding iteration (i.e. exponential incrementation). The default value is -1000, signifying that the initial retry interval should be one second and that each subsequent retry should double the previous interval.context
: The context object (i.e.this
) on which to invoke the functionswhen
,until
,action
,fail
andpass
. Defaults to an empty object.args
: The arguments array that will be provided to the functionswhen
,action
,fail
andpass
. Defaults to an empty array.
Examples:
// Attempt to insert a database record, waiting until a
// connection is available before doing so. The retry
// interval is 1 second on each occasion and the call
// will fail after 10 attempts.
trier.attempt({
when: function () {
return db.isConnected;
},
action: function () {
db.insert(record);
},
fail: function () {
log.error('No database connection, terminating.');
process.exit(1);
},
interval: 1000,
limit: 10
});
// Attempt to send an email message, optionally retrying with
// exponentially increasing intervals starting at 1 second.
// Continue to make attempts until the call succeeds.
var sent = false
trier.attempt({
until: function () {
return sent;
},
action: function (done) {
smtp.send(email, function (error) {
if (!error) {
sent = true;
}
done();
});
},
interval: -1000,
limit: -1
});
The build environment relies on
Node.js,
NPM,
JSHint,
CoffeeScript,
Mocha,
Chai,
spooks.js and
UglifyJS.
Assuming that you already have
Node.js
and NPM
installed,
you just need to run
npm install
to set up all of the dependencies
as listed in package.json
.
The unit tests are in test/trier.coffee
.
You can run them with the command npm test
.