Nyuma

Description

Nyuma means "back" in Swahili. It is an async retry implementation with fibonacci or exponential strategy.

Motivation

All the backoff implementation I came accross where missing on key feature: a maximum overall time option.

Installation

$ npm install @webinmove/nyuma

Usage

Basic real life

const{ fibonacci }=require('@webinmove/nyuma');constfetch=require('node-fetch');constmain=async()=>{constnyuma=fibonacci({initialDelay: 100,maxTime: 60000});try{// Here we'll only retry on real network errorconstresponse=awaitnyuma.start(()=>fetch('https://api.github.com/repos/webinmove/nyuma'));console.log(awaitresponse.json());}catch(err){// Couldn't get the response in less than a minute...console.error(err);}};main();

With another strategy and more options

const{ exponential }=require('@webinmove/nyuma');constfetch=require('node-fetch');constmain=async()=>{constnyuma=exponential({initialDelay: 100,maxDelay: 10000,maxRetries: 3,maxTime: 60000,maxTimeError: 'First fetch was too long',factor: 3});try{constbody=awaitnyuma.retryHook(({ error, retryCount, lastDelay, duration })=>console.log('Retry with:',{ error, retryCount, lastDelay, duration })).failHook(({ reason, retryCount, lastDelay, duration })=>console.log('Failed with:',{ reason, retryCount, lastDelay, duration })).start(async()=>{constresponse=awaitfetch('https://api.github.com/repos/webinmove/nyuma');if(response.status>=400){thrownewError(`Call responded with status ${response.status}`);}returnresponse.json();});console.log(body);}catch(err){// Couldn't get the response in less than a minute or 5 retries...console.error(err);}};main();

Using base classes

const{ Nyuma, ExponentialStrategy }=require('@webinmove/nyuma');constfetch=require('node-fetch');constmain=async()=>{conststrategy=newExponentialStrategy({factor: 3});constnyuma=newNyuma({
strategy,initialDelay: 100,maxDelay: 10000,maxRetries: 3,maxTime: 60000});nyuma.failHook(({ reason, retryCount, lastDelay, duration })=>console.log({ reason, retryCount, lastDelay, duration }));try{constbody=awaitnyuma.start(async()=>{constresponse=awaitfetch('https://api.github.com/repos/webinmove/nyuma');if(response.status>=400){thrownewError(`Call responded with status ${response.status}`);}returnresponse.json();});console.log(body);}catch(err){// Couldn't get the response in less than a minute or 5 retries...console.error(err);}};main();

API

fibonacci(params)

Returns a Nyuma instance initialized with the fibonacci strategy and the params.

params

• initialDelay: delay in ms for the first retry (required)
• maxDelay: maximum delay can reach before a retry (optional, default Infinity)
• maxRetries: maximum retries before throwing the last error encounter (optional, default Infinity)
• maxTime: maximum time for the first try and all retries before throwing the last error encounter or a specific error if the first try was too long (optional, default Infinity)
• maxTimeError: error message in case the first try was too long (optional, dafault "First try reached max time")

Note: you should specify at least a maxRetries or a maxTime

exponential(params)

Returns a Nyuma instance initialized with the exponential strategy and the params.

params

• factor: exponential factor used to compute the delays (optional, default 2)
• initialDelay: delay in ms for the first retry (required)
• maxDelay: maximum delay can reach before a retry (optional, default Infinity)
• maxRetries: maximum retries before throwing the last error encounter (optional, default Infinity)
• maxTime: maximum time for the first try and all retries before throwing the last error encounter or a specific error if the first try was too long (optional, default Infinity)
• maxTimeError: error message in case the first try was too long (optional, dafault "First try reached max time")

Note: you should specify at least a maxRetries or a maxTime

Class Nyuma

constructor(params)

Returns a Nyuma instance initialized with the params.

params

• strategy: a strategy instance (optional, default exponentialStrategy)
• initialDelay: delay in ms for the first retry (required)
• maxDelay: maximum delay can reach before a retry (optional, default Infinity)
• maxRetries: maximum retries before throwing the last error encounter (optional, default Infinity)
• maxTime: maximum time for the first try and all retries before throwing the last error encounter or a specific error if the first try was too long (optional, default Infinity)
• maxTimeError: error message in case the first try was too long (optional, dafault "First try reached max time")

Note: you should specify at least a maxRetries or a maxTime

start(fn)

Start the retry process retruning a promise of the fn result.

• fn: a function that will be retry until sucess or a maximum reached (required)

When called this function will have 2 arguments:

• retryCount: number of retry already done
• lastDelay: delay between the previous retry and the current

exemple:

const{ Nyuma, FibonacciStrategy }=require('@webinmove/nyuma');constmain=async()=>{conststrategy=newFibonacciStrategy();constnyuma=newNyuma({ strategy,initialDelay: 10,maxRetries: 10});awaitnyuma.start(async(retryCount,lastDelay)=>{console.log(`${retryCount}${lastDelay} ms`);thrownewError('Try again!');});};main();

will output:

0 0 ms
1 10 ms
2 10 ms
3 20 ms
4 30 ms
5 50 ms
6 80 ms
7 130 ms
8 210 ms
9 340 ms
10 550 ms
(node:51869) UnhandledPromiseRejectionWarning: Error: Try again!

failHook(fn)

Set a function on fail hook function.

• fn: a function that will be called on fail.

When called this function will have 1 argument:

• params: object containing
  • reason: string with the fail reason (e.g. "Maximum retry reached" or "Maximum time reached")
  • retryCount: number of retry done until fail
  • lastDelay: last retry delay in ms
  • duration: overall duration before fail in ms

Class ExponentialStrategy

constructor(params)

Returns a ExponentialStrategy instance initialized with the params.

params

• factor: the multiplicator factor, should be >= 1 (optional, default 2)

next()

Retruns the next iteration of the exponential sequence (e.g.: 1, 2, 4, 8, ...).

Class FibonacciStrategy

constructor()

Returns a FibonacciStrategy instance initialized with the params.

next()

Retruns the next iteration of the fibonacci sequence (e.g.: 1, 1, 2, 3, 5, 8, ...).

Npm scripts

Running code formating

$ npm run format

Running tests

$ npm run test:spec

Running lint tests

$ npm run test:lint

Running coverage tests

$ npm run test:cover

This will create a coverage folder with all the report in coverage/index.html

Running all tests

$ npm test

Note: that's the one you want to use most of the time

Reporting bugs and contributing

If you want to report a bug or request a feature, please open an issue. If want to help us improve nyuma, fork and make a pull request. Please use commit format as described here. And don't forget to run npm run format before pushing commit.