{"id":17247019,"url":"https://github.com/jmperez/promise-throttle","last_synced_at":"2025-04-04T23:09:04.711Z","repository":{"id":27407487,"uuid":"30884335","full_name":"JMPerez/promise-throttle","owner":"JMPerez","description":"A small library to throttle promises. Useful to avoid rate limiting when using REST APIs.","archived":false,"fork":false,"pushed_at":"2023-11-22T09:28:10.000Z","size":1062,"stargazers_count":151,"open_issues_count":11,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T22:13:55.090Z","etag":null,"topics":["promise","rate-limit","rest-api","throttle-promises","throttling"],"latest_commit_sha":null,"homepage":"https://doxdox.org/jmperez/promise-throttle","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/JMPerez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["JMPerez"],"custom":["https://www.buymeacoffee.com/jmp"]}},"created_at":"2015-02-16T19:29:45.000Z","updated_at":"2025-03-05T17:09:25.000Z","dependencies_parsed_at":"2024-06-18T13:47:55.181Z","dependency_job_id":"b9cbb0b7-1cd6-4d11-8174-127fbbee7bf3","html_url":"https://github.com/JMPerez/promise-throttle","commit_stats":{"total_commits":101,"total_committers":13,"mean_commits":7.769230769230769,"dds":0.6732673267326732,"last_synced_commit":"391382a4e2592c3f6b7a1ae5b69b852210d3a84d"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fpromise-throttle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fpromise-throttle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fpromise-throttle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JMPerez%2Fpromise-throttle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JMPerez","download_url":"https://codeload.github.com/JMPerez/promise-throttle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247261612,"owners_count":20910108,"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":["promise","rate-limit","rest-api","throttle-promises","throttling"],"created_at":"2024-10-15T06:35:44.441Z","updated_at":"2025-04-04T23:09:04.680Z","avatar_url":"https://github.com/JMPerez.png","language":"JavaScript","funding_links":["https://github.com/sponsors/JMPerez","https://www.buymeacoffee.com/jmp"],"categories":[],"sub_categories":[],"readme":"Promise Throttle \u0026nbsp; [![Build Status](https://api.travis-ci.org/JMPerez/promise-throttle.svg)](https://travis-ci.org/JMPerez/promise-throttle/) [![Coverage Status](https://coveralls.io/repos/github/JMPerez/promise-throttle/badge.svg?branch=master)](https://coveralls.io/r/JMPerez/promise-throttle?branch=master) [![Greenkeeper badge](https://badges.greenkeeper.io/JMPerez/promise-throttle.svg)](https://greenkeeper.io/)\n==================\n\n\nThis small ([~530B minified and compressed](https://cost-of-modules.herokuapp.com/result?p=promise-throttle)) dependency-free library limits promises run per unit of time. Useful for Rest API consumption, which is normally rate-limited to a certain number of requests in a set amount of time.\n\nOn Node.js, pass the Promise library you are using to the constructor.\n\nTo use, simply add functions to the `PromiseThrottle` that, once called, return a `Promise`.\n\n## Use\n\nThe library can be used either server-side or in the browser.\n\n```javascript\n  var PromiseThrottle = require('promise-throttle');\n  /**\n   * A function that once called returns a promise\n   * @return Promise\n   */\n  var myFunction = function(i) {\n    return new Promise(function(resolve, reject) {\n      // here we simulate that the promise runs some code\n      // asynchronously\n      setTimeout(function() {\n        console.log(i + \": \" + Math.random());\n        resolve(i);\n      }, 10);\n    });\n  };\n\n  var promiseThrottle = new PromiseThrottle({\n    requestsPerSecond: 1,           // up to 1 request per second\n    promiseImplementation: Promise  // the Promise library you are using\n  });\n\n  var amountOfPromises = 10;\n  while (amountOfPromises-- \u003e 0) {\n    promiseThrottle.add(myFunction.bind(this, amountOfPromises))\n      .then(function(i) {\n        console.log(\"Promise \" + i + \" done\");\n      });\n  }\n\n  // example using Promise.all\n  var one = promiseThrottle.add(myFunction.bind(this, 1));\n  var two = promiseThrottle.add(myFunction.bind(this, 2));\n  var three = promiseThrottle.add(myFunction.bind(this, 3));\n\n  Promise.all([one, two, three])\n    .then(function(r) {\n        console.log(\"Promises \" + r.join(\", \") + \" done\");\n    });\n```\n\n### Options\n\n#### weight\nYou can specify `weight` option for each promise to dynamically adjust throttling depending on\naction \"heaviness\". For example, action with `weight = 2` will be throttled as two regular actions. By default weight of all actions is 1.\n\n```javascript\n  var regularAction = promiseThrottle.add(performRegularCall);\n  var heavyAction = promiseThrottle.add(performHeavyCall, {weight: 2});\n```\n\n#### signal\nYou can cancel queued promises using an [AbortSignal](https://developer.mozilla.org/docs/Web/API/AbortController). For this, pass a `signal` option obtained from an `AbortController`. Once it is aborted, the promises queued using the signal will be rejected.\n\nIf the environment where you are running the code doesn't support AbortController, you can use [a polyfill](https://github.com/mo/abortcontroller-polyfill).\n\n```js\n  var controller = new AbortController();\n  var signal = controller.signal;\n  var pt = createPromiseThrottle(10);\n  pt.addAll([\n    function() {\n      return fetch('example.com/a');\n    },\n    function() {\n      return fetch('example.com/b');\n    },\n    function() {\n      ...\n    }\n  ], {signal: signal});\n  ...\n\n  // let's abort the promises\n  controller.abort();\n```\n\nYou can decide to make only specific promises abortable:\n\n```js\n  var controller = new AbortController();\n  var signal = controller.signal;\n  var pt = createPromiseThrottle(10);\n  pt.add(function() { return fetch('example.com/a') });\n  pt.add(function() { return fetch('example.com/b') }, {signal: signal});\n  pt.add(function() { return fetch('example.com/c') });\n  ...\n\n  // let's abort the second one\n  controller.abort();\n```\n\nWhen aborting, the promise returned by `add` or `addAll` is rejected with a specific error:\n\n```js\n  var controller = new AbortController();\n  var signal = controller.signal;\n  var pt = createPromiseThrottle(10);\n  pt.addAll([\n    function() {\n      return fetch('example.com/a');\n    },\n    function() {\n      return fetch('example.com/b');\n    },\n    function() {\n      ...\n    }\n  ], {signal: signal}).catch(function(e) {\n    if (e.name === 'AbortError') {\n      console.log('Promises aborted');\n    }\n  });\n  ...\n\n  // let's abort the promises\n  controller.abort();\n```\n\n\n\n## Installation\n\nFor node.js, install the module with: `npm i promise-throttle`\n\nIf you are using it in a browser, you can use bower: `bower install promise-throttle`\n\n## Development\n\nInstall the dependencies using `npm install`.\nRun `npm start` to lint, test and browserify promise-thottle.\n\n## Projects using it\n\nSee how some projects are using it:\n\n- [ivasilov/promised-twitter](https://github.com/ivasilov/promised-twitter)\n- [JMPerez/spotify-dedup](https://github.com/JMPerez/spotify-dedup)\n- [johannesss/randify](https://github.com/johannesss/randify)\n- [JoseBarrios/mturk-api](https://github.com/JoseBarrios/mturk-api)\n- [zackiles/lucy-bot](https://github.com/zackiles/lucy-bot)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmperez%2Fpromise-throttle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmperez%2Fpromise-throttle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmperez%2Fpromise-throttle/lists"}