tryer
Because everyone loves a tryer! Conditional and repeated function invocation for node and browser.
Loading the library Calling the exported function Examples
Say what?
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.
What size is it?
5.6 kb unminified with comments, 1.1 kb minified, 0.5 kb minified + gzipped.How do I install it?
Via npm:npm i tryer --save
Or if you just want the git repo:
git clone git@gitlab.com:philbooth/tryer.git
How do I use it?
Loading the library
If you are running in Node.js or another CommonJS-style environment, you canrequire
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
.Calling the exported function
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
:
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
:
action
.
Until when
returns true
(or a truthy value),
action
will not be called.
Defaults to
a function that immediately returns true
.until
:
action
.
After until
returns true
(or a truthy value),
action
will no longer be called.
Defaults to
a function that immediately returns true
.fail
:
limit
falsey values
are returned by when
or until
.
Defaults to an empty function.pass
:
until
has returned truthily.
Defaults to an empty function.limit
:
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
:
-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.Examples
// 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
});
How do I set up the dev environment?
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 in
test/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