povtor
Version:
Repeat function call depending on the previous call result and specified conditions.
346 lines (342 loc) • 23.5 kB
HTML
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>povtor</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="index.html" class="title">povtor</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-externals" checked />
<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="globals.html">Globals</a>
</li>
</ul>
<h1>povtor</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<a href="#povtor-a-namestarta" id="povtor-a-namestarta" style="color: inherit; text-decoration: none;">
<h1>povtor <a name="start"></a></h1>
</a>
<p>Repeat function call depending on the previous call result and specified conditions.</p>
<pre><code class="language-js">retry({
<span class="hljs-attr">action</span>: axios,
<span class="hljs-attr">actionParams</span>: [{<span class="hljs-attr">url</span>: <span class="hljs-string">'/api/some/endpoint'</span>}],
<span class="hljs-attr">retryAttempts</span>: [<span class="hljs-number">2000</span>, <span class="hljs-number">5000</span>],
<span class="hljs-attr">retryTest</span>: <span class="hljs-function">(<span class="hljs-params">response</span>) =></span> response.data.error,
<span class="hljs-attr">retryOnError</span>: <span class="hljs-literal">true</span>
})
.promise.then(<span class="hljs-function">(<span class="hljs-params">response</span>) =></span> <span class="hljs-built_in">console</span>.log(response.data));</code></pre>
<a href="#features" id="features" style="color: inherit; text-decoration: none;">
<h3>Features</h3>
</a>
<ul>
<li>Repeats calling of any function whether it returns a promise or a usual value (<code>action</code> setting).</li>
<li>Use returned promise to get function's last result or last error when retry process is finished.</li>
<li>Specify context (<code>actionContext</code> setting) and parameters (<code>actionParams</code> setting) for function call.</li>
<li>Retry function call when it throws or returns rejected promise (use <code>retryOnError</code> setting) and/or
when it returns normal value or fulfilled promise (use <code>retryTest</code> setting).</li>
<li>Use a function as value for <code>retryOnError</code>/<code>retryTest</code> setting to specify condition when to retry action call.</li>
<li>Specify quantity and timeouts of retry attempts (use <code>retryAttempts</code>, <code>retryQty</code> and/or <code>retryTimeout</code> settings).</li>
<li>Limit overall time of process of retry by <code>timeLimit</code> setting.</li>
<li>Control the process of calls repeating and stop it when it is necessary.</li>
<li>Access values and errors that are produced by function during the process.</li>
<li>Does not have dependencies except for <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise">ES 2015 Promise API</a>.</li>
<li>Small size.</li>
</ul>
<p><a href="http://badge.fury.io/js/povtor"><img src="https://badge.fury.io/js/povtor.png" alt="NPM version"></a></p>
<a href="#table-of-contents" id="table-of-contents" style="color: inherit; text-decoration: none;">
<h2>Table of contents</h2>
</a>
<ul>
<li><a href="#install">Installation</a></li>
<li><a href="#usage">Usage</a></li>
<li><a href="#examples">Examples</a></li>
<li><a href="#api">API</a></li>
<li><a href="#related">Related projects</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<a href="#installation-a-nameinstalla-a-hrefstartx2191a" id="installation-a-nameinstalla-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>Installation <a name="install"></a> <a href="#start">↑</a></h2>
</a>
<a href="#node" id="node" style="color: inherit; text-decoration: none;">
<h3>Node</h3>
</a>
<pre><code>npm <span class="hljs-keyword">install</span> povtor</code></pre>
<a href="#a-hrefhttpsboweriobowera" id="a-hrefhttpsboweriobowera" style="color: inherit; text-decoration: none;">
<h3><a href="https://bower.io">Bower</a></h3>
</a>
<pre><code><span class="hljs-keyword">bower </span><span class="hljs-keyword">install </span>povtor</code></pre>
<a href="#amdumd-ltscriptgt" id="amdumd-ltscriptgt" style="color: inherit; text-decoration: none;">
<h3>AMD/UMD, <script></h3>
</a>
<p>Use <code>dist/povtor.umd.js</code> (minified version).</p>
<a href="#usage-a-nameusagea-a-hrefstartx2191a" id="usage-a-nameusagea-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>Usage <a name="usage"></a> <a href="#start">↑</a></h2>
</a>
<a href="#ecmascript-6" id="ecmascript-6" style="color: inherit; text-decoration: none;">
<h3>ECMAScript 6+</h3>
</a>
<pre><code class="language-js"><span class="hljs-keyword">import</span> {retry, getPromiseField} <span class="hljs-keyword">from</span> <span class="hljs-string">'povtor'</span>;</code></pre>
<a href="#node-1" id="node-1" style="color: inherit; text-decoration: none;">
<h3>Node</h3>
</a>
<pre><code class="language-js"><span class="hljs-keyword">const</span> retry = <span class="hljs-built_in">require</span>(<span class="hljs-string">'povtor'</span>).retry;
<span class="hljs-keyword">const</span> getPromiseField = <span class="hljs-built_in">require</span>(<span class="hljs-string">'povtor'</span>).getPromiseField;</code></pre>
<a href="#amdumd" id="amdumd" style="color: inherit; text-decoration: none;">
<h3>AMD/UMD</h3>
</a>
<pre><code class="language-js">define([<span class="hljs-string">'path/to/dist/povtor.umd.js'</span>], <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params">povtor</span>) </span>{
<span class="hljs-keyword">const</span> retry = povtor.retry;
<span class="hljs-keyword">const</span> getPromiseField = povtor.getPromiseField;
});</code></pre>
<a href="#bower-ltscriptgt" id="bower-ltscriptgt" style="color: inherit; text-decoration: none;">
<h3>Bower, <script></h3>
</a>
<pre><code class="language-html"><span class="hljs-comment"><!-- Use bower_components/povtor/dist/povtor.umd.js if the library was installed by Bower --></span>
<span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"text/javascript"</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"path/to/dist/povtor.umd.js"</span>></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
<span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"text/javascript"</span>></span><span class="actionscript">
<span class="hljs-comment">// povtor is available via povtor field of window object</span>
<span class="hljs-keyword">const</span> retry = povtor.retry;
<span class="hljs-keyword">const</span> getPromiseField = povtor.getPromiseField;
</span><span class="hljs-tag"></<span class="hljs-name">script</span>></span></code></pre>
<a href="#examples-a-nameexamplesa-a-hrefstartx2191a" id="examples-a-nameexamplesa-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h3>Examples <a name="examples"></a> <a href="#start">↑</a></h3>
</a>
<pre><code class="language-js"><span class="hljs-comment">// Request data from API endpoint and repeat request after 3, then 5, then 7 seconds</span>
<span class="hljs-comment">// when request is not successful, response data has error flag or value of state field is not 3.</span>
<span class="hljs-keyword">let</span> control = retry({
<span class="hljs-attr">action</span>: axios,
<span class="hljs-attr">actionParams</span>: [{<span class="hljs-attr">url</span>: <span class="hljs-string">'/api/some/endpoint'</span>}],
<span class="hljs-attr">retryAttempts</span>: [<span class="hljs-number">3000</span>, <span class="hljs-number">5000</span>, <span class="hljs-number">7000</span>],
<span class="hljs-attr">retryTest</span>: <span class="hljs-function">(<span class="hljs-params">response</span>) =></span> response.data.error || response.data.state !== <span class="hljs-number">3</span>,
<span class="hljs-attr">retryOnError</span>: <span class="hljs-literal">true</span>
});
<span class="hljs-comment">// control.promise will be resolved when a request is completed successfully and retryTest returns false</span>
<span class="hljs-comment">// or when all repeats will be made.</span>
control.promise.then(<span class="hljs-function">(<span class="hljs-params">response</span>) =></span> <span class="hljs-built_in">console</span>.log(response.data));
getPromiseField(control); <span class="hljs-comment">// Get value of control.promise</span>
<span class="hljs-comment">// Read file contents every second until it contains specific value.</span>
control = retry({
<span class="hljs-attr">action</span>: jsonfile.readFileSync,
<span class="hljs-attr">actionParams</span>: [<span class="hljs-string">'/path/to/data.json'</span>, {<span class="hljs-string">'throws'</span>: <span class="hljs-literal">false</span>}],
<span class="hljs-attr">retryTimeout</span>: <span class="hljs-number">1000</span>,
<span class="hljs-attr">retryTest</span>: <span class="hljs-function">(<span class="hljs-params">data</span>) =></span> ! data || ! data.result
});
<span class="hljs-comment">// control.promise will be resolved when the file contains specified value.</span>
control.promise.then(<span class="hljs-function">(<span class="hljs-params">data</span>) =></span> <span class="hljs-built_in">console</span>.log(data.result));
...
control.stop(); <span class="hljs-comment">// Stop repeating of action</span></code></pre>
<p>See tests for additional examples.</p>
<a href="#api-a-nameapia-a-hrefstartx2191a" id="api-a-nameapia-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>API <a name="api"></a> <a href="#start">↑</a></h2>
</a>
<a href="#retrysettings-retrysettings-retryresult" id="retrysettings-retrysettings-retryresult" style="color: inherit; text-decoration: none;">
<h4>retry(settings: RetrySettings): RetryResult</h4>
</a>
<p>Call specified function and repeat calls depending on settings.</p>
<p><strong><code>settings: RetrySettings</code></strong> - an object that can contain the following fields:</p>
<ul>
<li><code>action</code> - a function that should be called. Can return a promise or a value.</li>
<li><code>actionContext</code> - an object that should be used as <code>this</code> when calling the action function.</li>
<li><code>actionParams</code> - an array of parameters that should be passed into the action function.</li>
<li><code>delay</code> - an amount of milliseconds before first call of the action function.
When the value is not specified or is negative, the action function will be called immediately first time.</li>
<li><code>retryAttempts</code> - an array specifying amount and timeouts between repeated calls of the action function.
Each item can be a number or a function (see <code>retryTimeout</code> setting for details).
Has priority over <code>retryQty</code> and <code>retryTimeout</code> settings.</li>
<li><code>retryQty</code> - maximum number of repeated calls of the action function. A negative value means no restriction.
Default value is <code>-1</code>.</li>
<li><code>retryTimeout</code> - a timeout between repeated calls of the action function, or a function that returns such timeout.
A negative or non-number value means the repeat call will be made without delay (this is applied by default).
If specified function returns <code>false</code> then retry process will be finished and result promise
will be fulfilled or rejected depending on result of the last action's call.</li>
<li><code>retryOnError</code> - a boolean value or a function returning boolean value that specifies whether the action function
should be called again when the action function throws an error or returned promise is rejected.
When not specified the call of the action function will not be repeated on an error.</li>
<li><code>retryTest</code> - a boolean value or a function returning boolean value that specifies whether the action function
should be called again after a made call. When not specified the action call will not be repeated.</li>
<li><code>timeLimit</code> - time in milliseconds specifying how long retry process can last starting from call of <code>retry</code> function.</li>
</ul>
<p>The only required field is <code>action</code>.</p>
<p><code>retry</code> function returns <code>RetryResult</code> - an object that can be used to observe and control the process of calls repeating.
<strong><code>RetryResult</code></strong> contains the following fields:</p>
<ul>
<li><code>promise</code> - promise that can be used to observe the process and to get the final value of the action function
or the last error.</li>
<li><code>attempt</code> - number of calls of the action function that have already made.</li>
<li><code>error</code> - last error or value of promise rejection.</li>
<li><code>isError</code> - whether the last call of the action function is ended with error.</li>
<li><code>result</code> - contains result of each call of the action function.</li>
<li><code>settings</code> - settings that were passed to <code>retry</code> function.</li>
<li><code>startTime</code> - time in milliseconds when <code>retry</code> function was called.</li>
<li><code>stop</code> - function that can be used to stop the process of calls repeating. Returns value of <code>promise</code> field.</li>
<li><code>stopped</code> - a boolean value that indicates whether the process of calls repeating is stopped.</li>
<li><code>value</code> - a value of last successfull call of the action function. When the action function returns a promise,
the value will be result of the promise fulfillment.</li>
<li><code>valueWait</code> - a boolean value that indicates whether the action function is producing a result.
Useful only when the action function returns a promise. Is set to <code>true</code> when the promise is pending.</li>
<li><code>wait</code> - a boolean value that indicates waiting of the next call of the action function.
Is set to <code>true</code> during a timeout between calls.</li>
</ul>
<a href="#getpromisefieldobj" id="getpromisefieldobj" style="color: inherit; text-decoration: none;">
<h4>getPromiseField(obj)</h4>
</a>
<p>Return value of <code>promise</code> field of the passed object.</p>
<p>See <code>doc</code> folder for details.</p>
<a href="#related-projects-a-namerelateda-a-hrefstartx2191a" id="related-projects-a-namerelateda-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>Related projects <a name="related"></a> <a href="#start">↑</a></h2>
</a>
<ul>
<li><a href="https://github.com/gamtiq/eva">eva</a></li>
<li><a href="https://github.com/gamtiq/wrapme">wrapme</a></li>
</ul>
<a href="#contributing-a-namecontributinga-a-hrefstartx2191a" id="contributing-a-namecontributinga-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>Contributing <a name="contributing"></a> <a href="#start">↑</a></h2>
</a>
<p>In lieu of a formal styleguide, take care to maintain the existing coding style.
Add unit tests for any new or changed functionality.
Lint and test your code.</p>
<a href="#license-a-namelicensea-a-hrefstartx2191a" id="license-a-namelicensea-a-hrefstartx2191a" style="color: inherit; text-decoration: none;">
<h2>License <a name="license"></a> <a href="#start">↑</a></h2>
</a>
<p>Copyright (c) 2018-2020 Denis Sikuler
Licensed under the MIT license.</p>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="globals ">
<a href="globals.html"><em>Globals</em></a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_index_.html">"index"</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
<li class="tsd-kind-type-alias tsd-has-type-parameter"><span class="tsd-kind-icon">Type alias with type parameter</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>