{"id":20019921,"url":"https://github.com/joeattardi/promise-poller","last_synced_at":"2025-04-06T11:08:28.025Z","repository":{"id":4260365,"uuid":"52056940","full_name":"joeattardi/promise-poller","owner":"joeattardi","description":"A basic poller built on top of promises","archived":false,"fork":false,"pushed_at":"2022-08-29T02:34:54.000Z","size":251,"stargazers_count":117,"open_issues_count":8,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-30T10:08:40.600Z","etag":null,"topics":["javascript","poller","polling","promise"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joeattardi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-19T02:57:25.000Z","updated_at":"2024-11-18T09:21:49.000Z","dependencies_parsed_at":"2022-08-08T06:15:10.755Z","dependency_job_id":null,"html_url":"https://github.com/joeattardi/promise-poller","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeattardi%2Fpromise-poller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeattardi%2Fpromise-poller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeattardi%2Fpromise-poller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joeattardi%2Fpromise-poller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joeattardi","download_url":"https://codeload.github.com/joeattardi/promise-poller/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247471519,"owners_count":20944158,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","poller","polling","promise"],"created_at":"2024-11-13T08:29:11.076Z","updated_at":"2025-04-06T11:08:28.003Z","avatar_url":"https://github.com/joeattardi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# promise-poller\n[![](https://travis-ci.org/joeattardi/promise-poller.svg?branch=master)](https://travis-ci.org/joeattardi/promise-poller)\n[![](https://badge.fury.io/js/promise-poller.svg)](https://www.npmjs.com/package/promise-poller)\n[![](https://david-dm.org/joeattardi/promise-poller.svg)](https://david-dm.org/joeattardi/promise-poller)\n\nA basic poller built on top of promises.\n\nSometimes, you may perform asynchronous operations that may fail. In many of those cases, you want to retry these operations one or more times before giving up. `promise-poller` handles this elegantly using promises.\n\n# Usage\n## Basic usage\nThe core of `promise-poller` is a *task function*. This is simply a function that starts your asynchronous task and returns a promise. If the task function does not return a promise, it will be wrapped in a promise. To start polling, pass your task function to the `promisePoller` function:\n\n    import promisePoller from 'promise-poller';\n\n    function myTask() {\n      // do some async stuff that returns a promise\n      return promise;\n    }\n\n    var poller = promisePoller({\n      taskFn: myTask\n    });\n\nThe `promisePoller` function will return a \"master promise\". This promise will be resolved when your task succeeds, or rejected if your task fails and no retries remain.\n\nThe master promise will be resolved with the value that your task promise is resolved with. If the poll fails, the master promise will be rejected with an array of all the rejection reasons for each poll attempt.\n\n`promise-poller` will attempt your task by calling the function and waiting on the returned promise. If the promise is rejected, `promise-poller` will wait one second and try again. It will attempt to execute your task 3 times before rejecting the master promise.\n\n### Use in non-ES2015 environments\n`promise-poller` is written using ES2015 and transpiled with Babel. The main `promisePoller` function is the default export. If you are using `promise-poller` in an ES5 environment, you will have to specify the `default` property when requiring the library in:\n\n    var promisePoller = require('promise-poller').default;\n\n## Specify polling options\nYou can specify a different polling interval or number of retries:\n\n    var poller = promisePoller({\n      taskFn: myTask,\n      interval: 500, // milliseconds\n      retries: 5\n    });\n\n## Specify timeout\nIf you want each poll attempt to reject after a certain timeout has passed, use the `timeout` option:\n\n    var poller = promisePoller({\n      taskFn: myTask,\n      interval: 500,\n      timeout: 2000\n    });\n\nIn the above example, the poll is considered failed if it isn't resolved after 2 seconds. If there are retries remaining, it will retry the poll as usual.\n\n## Specify \"master timeout\"\nInstead of timing out each poll attempt, you can set a timeout for the entire master polling operation:\n\n    var poller = promisePoller({\n      taskFn: myTask,\n      interval: 500,\n      retries: 10,\n      masterTimeout: 2000\n    });\n\nIn the above example, the entire poll operation will fail if there is not a successful poll within 2 seconds. This will reject the master promise.\n\n## Cancel polling\nYou may want to cancel the polling early. For example, if the poll fails because of an invalid password, that's not likely to change, so it would be a waste of time to continue to poll. To cancel polling early, return `false` from the task function instead of a promise.\n\nAlternatively, if your task function involves async work with promises, you can reject the promise with the `CANCEL_TOKEN` object.\n\n### Cancellation example\n\n```javascript\nimport promisePoller, { CANCEL_TOKEN } from 'promise-poller';\n\nconst taskFn = () =\u003e {\n  return new Promise((resolve, reject) =\u003e {\n    doAsyncStuff().then(resolve, error =\u003e {\n      if (error === 'invalid password') {\n        reject(CANCEL_TOKEN); // will cancel polling\n      } else {\n        reject(error); // will continue polling\n      }\n    });\n  });\n}\n```\n\n## The `shouldContinue` function\nYou can specify an optional `shouldContinue` function that takes two arguments. The first argument is a rejection reason when a poll fails, and the second argument is the resolved value when a poll succeeds. \nIf the poll attempt failed, and you want to abort further polling, return `false` from this function. On the other hand, if your poll resolved to a value but you want to keep polling, return `true` from this function.\n\n## Select polling strategy\nBy default, `promise-poller` will use a fixed interval between each poll attempt. For example, with an `interval` option of 500, the poller will poll approximately every 500 milliseconds. This is the `fixed-interval` strategy. There are two other strategies available that may better suit your use case. To select a polling strategy, specify the `strategy` option, e.g.:\n\n    promisePoller({\n      taskFn: myTask,\n      strategy: 'linear-backoff'\n    });\n\n### Linear backoff (`linear-backoff`)\nOptions:\n\n* `start` - The starting value to use for the polling interval (default = 1000)\n* `increment` - The amount to increase the interval by on each poll attempt.\n\nLinear backoff will increase the interval linearly by some constant amount for each poll attempt. For example, using the default options, the first retry will wait 1000 milliseconds. Each successive retry will wait an additional 1000 milliseconds: 1000, 2000, 3000, 4000, etc.\n\n### Exponential backoff with jitter (`exponential-backoff`)\nOptions:\n\n* `min` - The minimum interval amount to use (default = 1000)\n* `max` - The maximum interval amount to use (default = 30000)\n\nExponential backoff increases the poll interval by a power of two for each poll attempt. `promise-poller` uses exponential backoff with jitter. Jitter takes a random value between `min` and 2^*n* on the *n*th polling interval, not to exceed `max`. \n\nFor more information about exponential backoff with jitter, and its advantages, see [https://www.awsarchitectureblog.com/2015/03/backoff.html](https://www.awsarchitectureblog.com/2015/03/backoff.html).\n\n## Progress notification\nYou can also specify a progress callback function. Each time the task fails, the progress callback will be called with the number of retries remaining and the error that occurred (the value that the task promise was rejected with):\n\n    function progress(retriesRemaining, error) {\n      // log the error?\n    }\n\n    var poller = promisePoller({\n      taskFn: myTask,\n      interval: 500,\n      retries: 5,\n      progressCallback: progress\n    });\n\n## Debugging\n`promise-poller` uses the [debug](https://www.npmjs.com/package/debug) library. The debug name is `promisePoller`. To run your program with debug output for the `promise-poller`, set the `DEBUG` environment variable accordingly:\n\n`% DEBUG=promisePoller node path/to/app.js`\n\nIf you have more than one poller active at a time, and you need to differentiate between them in debug output, you can give the `promisePoller` options a `name` property:\n\n    var poller = promisePoller({\n      taskFn: myTask,\n      interval: 500,\n      retries: 5,\n      name: 'App Server Poller'\n    });\n\nWhen this poller prints debug messages, the poller name will be included:\n\n    promisePoller (App Server Poller) Poll failed. 1 retries remaining. +504ms\n\n# Contributors\n* Joe Attardi\n* /u/jcready\n* Jason Stitt\n* Emily Marigold Klassen\n\n# License\nThe MIT License (MIT)\n\nCopyright (c) 2016-2019 Joe Attardi \u003cjattardi@gmail.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeattardi%2Fpromise-poller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoeattardi%2Fpromise-poller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoeattardi%2Fpromise-poller/lists"}