org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/node_modules/retry/Readme.md

   1 # retry
   2
   3 Abstraction for exponential and custom retry strategies for failed operations.
   4
   5 ## Installation
   6
   7     npm install retry
   8
   9 ## Current Status
  10
  11 This module has been tested and is ready to be used.
  12
  13 ## Tutorial
  14
  15 The example below will retry a potentially failing `dns.resolve` operation
  16 `10` times using an exponential backoff strategy. With the default settings, this
  17 means the last attempt is made after `17 minutes and 3 seconds`.
  18
  19 ``` javascript
  20 var dns = require('dns');
  21 var retry = require('retry');
  22
  23 function faultTolerantResolve(address, cb) {
  24   var operation = retry.operation();
  25
  26   operation.attempt(function(currentAttempt) {
  27     dns.resolve(address, function(err, addresses) {
  28       if (operation.retry(err)) {
  29         return;
  30       }
  31
  32       cb(err ? operation.mainError() : null, addresses);
  33     });
  34   });
  35 }
  36
  37 faultTolerantResolve('nodejs.org', function(err, addresses) {
  38   console.log(err, addresses);
  39 });
  40 ```
  41
  42 Of course you can also configure the factors that go into the exponential
  43 backoff. See the API documentation below for all available settings.
  44 currentAttempt is an int representing the number of attempts so far.
  45
  46 ``` javascript
  47 var operation = retry.operation({
  48   retries: 5,
  49   factor: 3,
  50   minTimeout: 1 * 1000,
  51   maxTimeout: 60 * 1000,
  52   randomize: true,
  53 });
  54 ```
  55
  56 ## API
  57
  58 ### retry.operation([options])
  59
  60 Creates a new `RetryOperation` object. `options` is the same as `retry.timeouts()`'s `options`, with two additions:
  61
  62 * `forever`: Whether to retry forever, defaults to `false`.
  63 * `unref`: Wether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's, defaults to `false`.
  64
  65 ### retry.timeouts([options])
  66
  67 Returns an array of timeouts. All time `options` and return values are in
  68 milliseconds. If `options` is an array, a copy of that array is returned.
  69
  70 `options` is a JS object that can contain any of the following keys:
  71
  72 * `retries`: The maximum amount of times to retry the operation. Default is `10`.
  73 * `factor`: The exponential factor to use. Default is `2`.
  74 * `minTimeout`: The number of milliseconds before starting the first retry. Default is `1000`.
  75 * `maxTimeout`: The maximum number of milliseconds between two retries. Default is `Infinity`.
  76 * `randomize`: Randomizes the timeouts by multiplying with a factor between `1` to `2`. Default is `false`.
  77
  78 The formula used to calculate the individual timeouts is:
  79
  80 ```
  81 Math.min(random * minTimeout * Math.pow(factor, attempt), maxTimeout)
  82 ```
  83
  84 Have a look at [this article][article] for a better explanation of approach.
  85
  86 If you want to tune your `factor` / `times` settings to attempt the last retry
  87 after a certain amount of time, you can use wolfram alpha. For example in order
  88 to tune for `10` attempts in `5 minutes`, you can use this equation:
  89
  90 ![screenshot](https://github.com/tim-kos/node-retry/raw/master/equation.gif)
  91
  92 Explaining the various values from left to right:
  93
  94 * `k = 0 ... 9`:  The `retries` value (10)
  95 * `1000`: The `minTimeout` value in ms (1000)
  96 * `x^k`: No need to change this, `x` will be your resulting factor
  97 * `5 * 60 * 1000`: The desired total amount of time for retrying in ms (5 minutes)
  98
  99 To make this a little easier for you, use wolfram alpha to do the calculations:
 100
 101 <http://www.wolframalpha.com/input/?i=Sum%5B1000*x^k%2C+{k%2C+0%2C+9}%5D+%3D+5+*+60+*+1000>
 102
 103 [article]: http://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html
 104
 105 ### retry.createTimeout(attempt, opts)
 106
 107 Returns a new `timeout` (integer in milliseconds) based on the given parameters.
 108
 109 `attempt` is an integer representing for which retry the timeout should be calculated. If your retry operation was executed 4 times you had one attempt and 3 retries. If you then want to calculate a new timeout, you should set `attempt` to 4 (attempts are zero-indexed).
 110
 111 `opts` can include `factor`, `minTimeout`, `randomize` (boolean) and `maxTimeout`. They are documented above.
 112
 113 `retry.createTimeout()` is used internally by `retry.timeouts()` and is public for you to be able to create your own timeouts for reinserting an item, see [issue #13](https://github.com/tim-kos/node-retry/issues/13).
 114
 115 ### retry.wrap(obj, [options], [methodNames])
 116
 117 Wrap all functions of the `obj` with retry. Optionally you can pass operation options and
 118 an array of method names which need to be wrapped.
 119
 120 ```
 121 retry.wrap(obj)
 122
 123 retry.wrap(obj, ['method1', 'method2'])
 124
 125 retry.wrap(obj, {retries: 3})
 126
 127 retry.wrap(obj, {retries: 3}, ['method1', 'method2'])
 128 ```
 129 The `options` object can take any options that the usual call to `retry.operation` can take.
 130
 131 ### new RetryOperation(timeouts, [options])
 132
 133 Creates a new `RetryOperation` where `timeouts` is an array where each value is
 134 a timeout given in milliseconds.
 135
 136 Available options:
 137 * `forever`: Whether to retry forever, defaults to `false`.
 138 * `unref`: Wether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's, defaults to `false`.
 139
 140 If `forever` is true, the following changes happen:
 141 * `RetryOperation.errors()` will only output an array of one item: the last error.
 142 * `RetryOperation` will repeatedly use the `timeouts` array. Once all of its timeouts have been used up, it restarts with the first timeout, then uses the second and so on.
 143
 144 #### retryOperation.errors()
 145
 146 Returns an array of all errors that have been passed to
 147 `retryOperation.retry()` so far.
 148
 149 #### retryOperation.mainError()
 150
 151 A reference to the error object that occured most frequently. Errors are
 152 compared using the `error.message` property.
 153
 154 If multiple error messages occured the same amount of time, the last error
 155 object with that message is returned.
 156
 157 If no errors occured so far, the value is `null`.
 158
 159 #### retryOperation.attempt(fn, timeoutOps)
 160
 161 Defines the function `fn` that is to be retried and executes it for the first
 162 time right away. The `fn` function can receive an optional `currentAttempt` callback that represents the number of attempts to execute `fn` so far.
 163
 164 Optionally defines `timeoutOps` which is an object having a property `timeout` in miliseconds and a property `cb` callback function.
 165 Whenever your retry operation takes longer than `timeout` to execute, the timeout callback function `cb` is called.
 166
 167
 168 #### retryOperation.try(fn)
 169
 170 This is an alias for `retryOperation.attempt(fn)`. This is deprecated. Please use `retryOperation.attempt(fn)` instead.
 171
 172 #### retryOperation.start(fn)
 173
 174 This is an alias for `retryOperation.attempt(fn)`. This is deprecated. Please use `retryOperation.attempt(fn)` instead.
 175
 176 #### retryOperation.retry(error)
 177
 178 Returns `false` when no `error` value is given, or the maximum amount of retries
 179 has been reached.
 180
 181 Otherwise it returns `true`, and retries the operation after the timeout for
 182 the current attempt number.
 183
 184 #### retryOperation.stop()
 185
 186 Allows you to stop the operation being retried. Useful for aborting the operation on a fatal error etc.
 187
 188 #### retryOperation.attempts()
 189
 190 Returns an int representing the number of attempts it took to call `fn` before it was successful.
 191
 192 ## License
 193
 194 retry is licensed under the MIT license.
 195
 196
 197 # Changelog
 198
 199 0.10.0 Adding `stop` functionality, thanks to @maxnachlinger.
 200
 201 0.9.0 Adding `unref` functionality, thanks to @satazor.
 202
 203 0.8.0 Implementing retry.wrap.
 204
 205 0.7.0 Some bug fixes and made retry.createTimeout() public. Fixed issues [#10](https://github.com/tim-kos/node-retry/issues/10), [#12](https://github.com/tim-kos/node-retry/issues/12), and [#13](https://github.com/tim-kos/node-retry/issues/13).
 206
 207 0.6.0 Introduced optional timeOps parameter for the attempt() function which is an object having a property timeout in milliseconds and a property cb callback function. Whenever your retry operation takes longer than timeout to execute, the timeout callback function cb is called.
 208
 209 0.5.0 Some minor refactoring.
 210
 211 0.4.0 Changed retryOperation.try() to retryOperation.attempt(). Deprecated the aliases start() and try() for it.
 212
 213 0.3.0 Added retryOperation.start() which is an alias for retryOperation.try().
 214
 215 0.2.0 Added attempts() function and parameter to retryOperation.try() representing the number of attempts it took to call fn().