Because everyone loves a tryer!
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,tryer 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 backoff
of retry intervals,
which can be useful
when handling
indefinite error states
such as network failure.
5.6 kb unminified with comments, 1.1 kb minified, 0.5 kb minified + gzipped.
Via npm:
npm i tryer --save
Or if you just want the git repo:
git clone git@gitlab.com:philbooth/tryer.git
If you are running in
Node.js
or another CommonJS-style
environment,
you can require
tryer like so:
const tryer = require('tryer');
It also the supports
the AMD-style format
preferred by Require.js.
If you are
including tryer
with an HTML <script> tag,
or neither of the above environments
are detected,
it will be exported globally as tryer.
tryer is a function
that can be invoked to
call other functions
conditionally and repeatedly,
without the need for
explicit if statements
or loops in your own code.
tryer takes one argument,
an options object
that supports
the following properties:
action:
The function that you want to invoke.
If action returns a promise,
iterations will not end
until the promise is resolved or rejected.
Alternatively,
action may take a callback argument, done,
to signal that it is asynchronous.
In that case,
you are responsible
for calling done
when the action is finished.
If action is not set,
it defaults to an empty function.
when:
A predicate
that tests the pre-condition
for invoking action.
Until when returns true
(or a truthy value),
action will not be called.
Defaults to
a function that immediately returns true.
until:
A predicate
that tests the post-condition
for invoking action.
After until returns true
(or a truthy value),
action will no longer be called.
Defaults to
a function that immediately returns true.
fail:
The error handler.
A function
that will be called
if limit falsey values
are returned by when or until.
Defaults to an empty function.
pass:
Success handler.
A function
that will be called
after until has returned truthily.
Defaults to an empty function.
limit:
Failure limit,
representing the maximum number
of falsey returns from when or until
that will be permitted
before invocation is deemed to have failed.
A negative number
indicates that the attempt
should never fail,
instead continuing
for as long as when and until
have returned truthy values.
Defaults to -1.
interval:
The retry interval,
in milliseconds.
A negative number indicates
that each subsequent retry
should wait for twice the interval
from the preceding iteration
(i.e. exponential backoff).
The default value is -1000,
signifying that
the initial retry interval
should be one second
and that each subsequent attempt
should wait for double the length
of the previous interval.
// Attempt to insert a database record, waiting until `db.isConnected`
// before doing so. The retry interval is 1 second on each iteration
// and the call will fail after 10 attempts.
tryer({
action: () => db.insert(record),
when: () => db.isConnected,
interval: 1000,
limit: 10,
fail () {
log.error('No database connection, terminating.');
process.exit(1);
}
});
// Attempt to send an email message, optionally retrying with
// exponential backoff starting at 1 second. Continue to make
// attempts indefinitely until the call succeeds.
let sent = false;
tryer({
action (done) {
smtp.send(email, error => {
if (! error) {
sent = true;
}
done();
});
},
until: () => sent,
interval: -1000,
limit: -1
});
// Poll a device at 30-second intervals, continuing indefinitely.
tryer({
action: () => device.poll().then(response => handle(response)),
interval: 30000,
limit: -1
});
The dev environment relies on
Chai,
JSHint,
Mocha,
please-release-me,
spooks.js and
UglifyJS.
The source code is insrc/tryer.js
and the unit tests are intest/unit.js.
To install the dependencies:
npm i
To run the tests:
npm t
To lint the code:
npm run lint
To regenerate the minified lib:
npm run minify