{

  "name": "backoff",

  "description": "Fibonacci and exponential backoffs.",

  "version": "2.2.0",

  "author": {

    "name": "Mathieu Turcotte",

    "email": "[email protected]"

  },

  "keywords": [

    "backoff",

    "retry",

    "fibonacci",

    "exponential"

  ],

  "repository": {

    "type": "git",

    "url": "https://github.com/MathieuTurcotte/node-backoff.git"

  },

  "devDependencies": {

    "sinon": "1.5.2",

    "nodeunit": "0.7",

    "jshint": "1.1.0"

  },

  "scripts": {

    "pretest": "node_modules/jshint/bin/jshint lib/ tests/ examples/ index.js",

    "test": "node_modules/nodeunit/bin/nodeunit tests/"

  },

  "engines": {

    "node": ">= 0.6"

  },

  "readme": "# Backoff for Node.js [](http://travis-ci.org/MathieuTurcotte/node-backoff)\n\nFibonacci and exponential backoffs for Node.js.\n\n## Installation\n\n```\nnpm install backoff\n```\n\n## Unit tests\n\n```\nnpm test\n```\n\n## Usage\n\n### Object Oriented\n\nThe usual way to instantiate a new `Backoff` object is to use one predefined\nfactory method: `backoff.fibonacci([options])`, `backoff.exponential([options])`.\n\n`Backoff` inherits from `EventEmitter`. When a backoff starts, a `backoff`\nevent is emitted and, when a backoff ends, a `ready` event is emitted.\nHandlers for these two events are called with the current backoff number and\ndelay.\n\n``` js\nvar backoff = require('backoff');\n\nvar fibonacciBackoff = backoff.fibonacci({\n    randomisationFactor: 0,\n    initialDelay: 10,\n    maxDelay: 300\n});\n\nfibonacciBackoff.failAfter(10);\n\nfibonacciBackoff.on('backoff', function(number, delay) {\n    // Do something when backoff starts, e.g. show to the\n    // user the delay before next reconnection attempt.\n    console.log(number + ' ' + delay + 'ms');\n});\n\nfibonacciBackoff.on('ready', function(number, delay) {\n    // Do something when backoff ends, e.g. retry a failed\n    // operation (DNS lookup, API call, etc.). If it fails\n    // again then backoff, otherwise reset the backoff\n    // instance.\n    fibonacciBackoff.backoff();\n});\n\nfibonacciBackoff.on('fail', function() {\n    // Do something when the maximum number of backoffs is\n    // reached, e.g. ask the user to check its connection.\n    console.log('fail');\n});\n\nfibonacciBackoff.backoff();\n```\n\nThe previous example would print the following.\n\n```\n0 10ms\n1 10ms\n2 20ms\n3 30ms\n4 50ms\n5 80ms\n6 130ms\n7 210ms\n8 300ms\n9 300ms\nfail\n```\n\nNote that `Backoff` objects are meant to be instantiated once and reused\nseveral times by calling `reset` after a successful \"retry\".\n\n### Functional\n\nIt's also possible to avoid some boilerplate code when invoking an asynchronous\nfunction in a backoff loop by using `backoff.call(fn, [args, ...], callback)`.\n\nTypical usage looks like the following.\n\n``` js\nvar call = backoff.call(get, 'https://duplika.ca/', function(err, res) {\n    console.log('Retries: ' + call.getResults().length);\n\n    if (err) {\n        console.log('Error: ' + err.message);\n    } else {\n        console.log('Status: ' + res.statusCode);\n    }\n});\n\ncall.setStrategy(new backoff.ExponentialStrategy());\ncall.failAfter(10);\ncall.start();\n```\n\n## API\n\n### backoff.fibonacci([options])\n\nConstructs a Fibonacci backoff (10, 10, 20, 30, 50, etc.).\n\nSee bellow for options description.\n\n### backoff.exponential([options])\n\nConstructs an exponential backoff (10, 20, 40, 80, etc.).\n\nThe options are the following.\n\n- randomisationFactor: defaults to 0, must be between 0 and 1\n- initialDelay: defaults to 100 ms\n- maxDelay: defaults to 10000 ms\n\nWith these values, the backoff delay will increase from 100 ms to 10000 ms. The\nrandomisation factor controls the range of randomness and must be between 0\nand 1. By default, no randomisation is applied on the backoff delay.\n\n### backoff.call(fn, [args, ...], callback)\n\n- fn: function to call in a backoff handler, i.e. the wrapped function\n- args: function's arguments\n- callback: function's callback accepting an error as its first argument\n\nConstructs a `FunctionCall` instance for the given function. The wrapped\nfunction will get retried until it succeds or reaches the maximum number\nof backoffs. In both cases, the callback function will be invoked with the\nlast result returned by the wrapped function.\n\nIt is the caller's responsability to initiate the call by invoking the\n`start` method on the returned `FunctionCall` instance.\n\n### Class Backoff\n\n#### new Backoff(strategy)\n\n- strategy: the backoff strategy to use\n\nConstructs a new backoff object from a specific backoff strategy. The backoff\nstrategy must implement the `BackoffStrategy`interface defined bellow.\n\n#### backoff.failAfter(numberOfBackoffs)\n\n- numberOfBackoffs: maximum number of backoffs before the fail event gets\nemitted, must be greater than 0\n\nSets a limit on the maximum number of backoffs that can be performed before\na fail event gets emitted and the backoff instance is reset. By default, there\nis no limit on the number of backoffs that can be performed.\n\n#### backoff.backoff([err])\n\nStarts a backoff operation. If provided, the error parameter will be emitted\nas the last argument of the `backoff` and `fail` events to let the listeners\nknow why the backoff operation was attempted.\n\nAn error will be thrown an error if a backoff operation is already in progress.\n\nIn practice, this method should be called after a failed attempt to perform a\nsensitive operation (connecting to a database, downloading a resource over the\nnetwork, etc.).\n\n#### backoff.reset()\n\nResets the backoff delay to the initial backoff delay and stop any backoff\noperation in progress. After reset, a backoff instance can and should be\nreused.\n\nIn practice, this method should be called after having successfully completed\nthe sensitive operation guarded by the backoff instance or if the client code\nrequest to stop any reconnection attempt.\n\n#### Event: 'backoff'\n\n- number: number of backoffs since last reset, starting at 0\n- delay: backoff delay in milliseconds\n- err: optional error parameter passed to `backoff.backoff([err])`\n\nEmitted when a backoff operation is started. Signals to the client how long\nthe next backoff delay will be.\n\n#### Event: 'ready'\n\n- number: number of backoffs since last reset, starting at 0\n- delay: backoff delay in milliseconds\n\nEmitted when a backoff operation is done. Signals that the failing operation\nshould be retried.\n\n#### Event: 'fail'\n\n- err: optional error parameter passed to `backoff.backoff([err])`\n\nEmitted when the maximum number of backoffs is reached. This event will only\nbe emitted if the client has set a limit on the number of backoffs by calling\n`backoff.failAfter(numberOfBackoffs)`. The backoff instance is automatically\nreset after this event is emitted.\n\n### Interface BackoffStrategy\n\nA backoff strategy must provide the following methods.\n\n#### strategy.next()\n\nComputes and returns the next backoff delay.\n\n#### strategy.reset()\n\nResets the backoff delay to its initial value.\n\n### Class ExponentialStrategy\n\nExponential (10, 20, 40, 80, etc.) backoff strategy implementation.\n\n#### new ExponentialStrategy([options])\n\nThe options are the following.\n\n- randomisationFactor: defaults to 0, must be between 0 and 1\n- initialDelay: defaults to 100 ms\n- maxDelay: defaults to 10000 ms\n\n### Class FibonacciStrategy\n\nFibonnaci (10, 10, 20, 30, 50, etc.) backoff strategy implementation.\n\n#### new FibonacciStrategy([options])\n\nThe options are the following.\n\n- randomisationFactor: defaults to 0, must be between 0 and 1\n- initialDelay: defaults to 100 ms\n- maxDelay: defaults to 10000 ms\n\n### Class FunctionCall\n\nThis class manages the calling of an asynchronous function within a backoff\nloop.\n\nThis class should rarely be instantiated directly since the factory method\n`backoff.call(fn, [args, ...], callback)` offers a more convenient and safer\nway to create `FunctionCall` instances.\n\n#### new FunctionCall(fn, args, callback)\n\n- fn: asynchronous function to call\n- args: an array containing fn's args\n- callback: fn's callback\n\nConstructs a function handler for the given asynchronous function.\n\n#### call.setStrategy(strategy)\n\n- strategy: strategy instance to use, defaults to `FibonacciStrategy`.\n\nSets the backoff strategy to use. This method should be called before\n`call.call()`.\n\n#### call.failAfter(maxNumberOfBackoffs)\n\n- maxNumberOfBackoffs: maximum number of backoffs before the call is aborted\n\nSets the maximum number of backoffs before the call is aborted. By default,\nthere is no limit on the number of backoffs that can be performed.\n\nThis method should be called before `call.call()`.\n\n#### call.getResults()\n\nRetrieves all intermediary results returned by the wrapped function. This\nmethod can be called at any point in time during the call life cycle, i.e.\nbefore, during and after the wrapped function invocation.\n\nReturns an array of arrays containing the results returned by the wrapped\nfunction for each call. For example, to get the error code returned by the\nsecond call, one would do the following.\n\n``` js\nvar results = call.getResults();\nvar error = results[1][0];\n```\n\n#### call.start()\n\nInitiates the call the wrapped function. This method should only be called\nonce per function call instance.\n\n#### call.abort()\n\nAborts the call.\n\nPast results can be retrieved using `call.getResults()`. This method can be\ncalled at any point in time during the call life cycle, i.e. before, during\nand after the wrapped function invocation.\n\n#### Event: 'call'\n\n- args: wrapped function's arguments\n\nEmitted each time the wrapped function is called.\n\n#### Event: 'callback'\n\n- results: wrapped function's return values\n\nEmitted each time the wrapped function invokes its callback.\n\n#### Event: 'backoff'\n\n- number: backoff number, starts at 0\n- delay: backoff delay in milliseconds\n- err: the error that triggered the backoff operation\n\nEmitted each time a backoff operation is started.\n\n## License\n\nThis code is free to use under the terms of the [MIT license](http://mturcotte.mit-license.org/).\n",

  "readmeFilename": "README.md",

  "bugs": {

    "url": "https://github.com/MathieuTurcotte/node-backoff/issues"

  },

  "_id": "[email protected]",

  "dist": {

    "shasum": "7da9c85703a8363cd131cf529b51787f31ca1638"

  },

  "_from": "[email protected]",

  "_resolved": "https://registry.npmjs.org/backoff/-/backoff-2.2.0.tgz"

}