{"_id":"@brugmanjoost/throttle","_rev":"1-d98c939cdef381baf40caa59cc241e1f","name":"@brugmanjoost/throttle","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@brugmanjoost/throttle","description":"A nodejs module to throttle events at a preset rate.","version":"1.0.0","author":{"name":"Joost Brugman"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/brugmanjoost/throttle.git"},"keywords":["promise","async","throttle"],"gitHead":"af827c218cd032bfb125a3da4da18f1da3876f31","bugs":{"url":"https://github.com/brugmanjoost/throttle/issues"},"homepage":"https://github.com/brugmanjoost/throttle#readme","_id":"@brugmanjoost/throttle@1.0.0","_nodeVersion":"16.13.0","_npmVersion":"8.1.0","dist":{"integrity":"sha512-vywkLJ1WqTxEl3LyW+z88g8PUJS9SP48Dj54JjCYjQKVLSR4YCcxpEk5Fl+TASB+uOH8OL5OBxjytjfgF6wIoQ==","shasum":"3001cc5d3000fd8e8eb12e1d2a20629c583afd2a","tarball":"https://registry.npmjs.org/@brugmanjoost/throttle/-/throttle-1.0.0.tgz","fileCount":9,"unpackedSize":25169,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJhk4RoCRA9TVsSAnZWagAAmskP/igbzFVYsPhU7oS4vMs4\nvrAfjU6AEQfhM6AtryAVfctr42UJ9HT6u4fpZUaBz3OJMFL3Rogv+AO+kTJH\n7T0QigfVHoeSMiIUweZGJwJTQ/IR2lntiQ1LBUrUVdLSzo55AdsLXWJWCbq6\nDlCcPwfUmReODUwgQr91Q+NWGo1YIfXIkJYwRUKkFB/cBCLk8TS8bdjbqD/O\nE6LLE1iXOiYj9GgmYXTyA+UfD6DGfoBOPRDYTdw9XMzVE0rduwxrIAgblcff\ncipWQ2acSlbqyQNN16jQKCveVwnPrJlKmmpBvUdPkY/QaWumXNbY3haLLjsD\nZ0NKRE92Ayhod9tpqWaO/BSqNftuLe2FDYg2731BEymrPoGjjCwDqUDwve7C\nqPMm85IVBI+17OFic/nu/Ia6mZJI2G0HtA9OoAyOu7JB8ofveom7YVa+Y/GL\n1P9svdONN4rSnNb1SD5QNMpiGGsTYiUdRXrLJWWHSNVYGd7EWHk7J9TctQ7L\ngphgCEHfPjdRmg4ZsfWBKfhqDLPP2YI1tjAcoCNvV8qBSpBGXmSmD7LJlMZ1\nujn0iho5kmTm8bt7B0JWqY9hKt2Ai7tZIC4M4Ima768HyBBHOHYkY6fFuidm\nayqFSJpZycJAhoBbvH8wAopT4f3r4EWkzQdCk8QB4pQtAggt9nR/qQaj34uZ\nq9j8\r\n=+UEA\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICoFJueuGXNLxqUcza+uUfhBN6xRWgfpx08Z4zg5HldJAiEAySMwo0xtAM/q9QP2l9S3XQisovrjeb7a8AYM7eKqtrk="}]},"_npmUser":{"name":"brugmanjoost","email":"joost@brugmanholding.com"},"directories":{},"maintainers":[{"name":"brugmanjoost","email":"joost@brugmanholding.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/throttle_1.0.0_1637057640507_0.2432998885368427"},"_hasShrinkwrap":false}},"time":{"created":"2021-11-16T10:14:00.451Z","1.0.0":"2021-11-16T10:14:00.634Z","modified":"2022-04-04T20:49:10.090Z"},"maintainers":[{"name":"brugmanjoost","email":"joost@brugmanholding.com"}],"description":"A nodejs module to throttle events at a preset rate.","homepage":"https://github.com/brugmanjoost/throttle#readme","keywords":["promise","async","throttle"],"repository":{"type":"git","url":"git+https://github.com/brugmanjoost/throttle.git"},"author":{"name":"Joost Brugman"},"bugs":{"url":"https://github.com/brugmanjoost/throttle/issues"},"license":"MIT","readme":"# throttle\r\nThrottle is a nodejs module used to throttle events. You can typically use it to prevent overloading external services. Throttle makes sure your code puts on the breaks in time. There are no external dependencies.\r\n\r\n1. [Installation](#install)\r\n2. [Usage](#usage)<br />\r\n2.1 [Synchronised usage](#usagesync)<br />\r\n2.2 [Async usage](#usageasync)<br />\r\n2.3 [Automatic catch up bursts](#usagecatchup)<br />\r\n2.3 [Excess bursts](#usageexcess)<br />\r\n\r\n<a name=\"install\"></a>\r\n## 1. Installation\r\n```\r\n$ npm install @brugmanjoost/throttle\r\n```\r\n<a name=\"usage\"></a>\r\n## 2. Usage\r\nYou provide a **normalRateLimit** which is the number of events that may occur in a given window and you provide **normalRateWindow** which is the duration of that window. Throttle will make sure you don't exceed that limit.\r\n\r\n<a name=\"usagesync\"></a>\r\n### 2.1 Synchronised usage\r\nYou'll likely use throttle in a larger context like a loop to process data but barebones this is how you use it:\r\n\r\n```\r\nlet throttle = new throttler.Throttle({\r\n    normalRateLimit: 5 * 60 * 60,               // 5 per second = 5 * 60 * 60 per hour\r\n    normalRateWindow: 1000 * 60 * 60,           // 1000ms * 60 * 60 is one hour\r\n});\r\n\r\nlet t = Date.now();\r\nawait throttle.next(); console.log(Date.now() - t); // Approx t+0ms\r\nawait throttle.next(); console.log(Date.now() - t); // Approx t+200ms\r\nawait throttle.next(); console.log(Date.now() - t); // Approx t+400ms\r\nawait throttle.next(); console.log(Date.now() - t); // Approx t+600ms\r\nawait throttle.next(); console.log(Date.now() - t); // Approx t+800ms\r\nconsole.log('Done', Date.now() - t);                // Approx t+800ms, shown in console last\r\n```\r\n\r\n<a name=\"usageasync\"></a>\r\n### 2.2 Async usage\r\nIf you don't use await, then throttle.next() will return immediately and the main program continues but the promises will still complete at the same rate:\r\n\r\n```\r\nlet t = Date.now();\r\nthrottle.next().then(() => console.log(Date.now() - t)); // Approx t+0ms\r\nthrottle.next().then(() => console.log(Date.now() - t)); // Approx t+200ms\r\nthrottle.next().then(() => console.log(Date.now() - t)); // Approx t+400ms\r\nthrottle.next().then(() => console.log(Date.now() - t)); // Approx t+600ms\r\nthrottle.next().then(() => console.log(Date.now() - t)); // Approx t+800ms\r\nconsole.log('Done', Date.now() - t);                     // Approx t+0ms, shown in console first\r\n```\r\n\r\n<a name=\"usagecatchup\"></a>\r\n### 2.3 Automatic catch up bursts\r\nIf your main program has some delay, e.g. fetching data, since sending the first request, then throttle will use that time to schedule the next events in burst mode to 'catch up' to the normal rate of the throttle. \r\n\r\n```\r\nlet t = Date.now();\r\nawait throttle.next(); console.log(Date.now() - t);     // Approx t+0ms\r\nawait throttle.next(); console.log(Date.now() - t);     // Approx t+200ms\r\nawait throttle.next(); console.log(Date.now() - t);     // Approx t+400ms\r\nawait throttle.next(); console.log(Date.now() - t);     // Approx t+600ms\r\nawait throttle.next(); console.log(Date.now() - t);     // Approx t+800ms\r\n\r\nsetTimeout(async () => {                                // Main program does something that takes 1 second.\r\n    console.log('Staring burst', Date.now() - t);       // Approx t+18000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+18000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+18000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+18000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+18000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+18000ms\r\n\r\n    console.log('Burst completed', Date.now() - t);     // Approx t+20000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+20000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+2200ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+24000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+26000ms\r\n    await throttle.next(); console.log(Date.now() - t); // Approx t+28000ms\r\n\r\n}, 1000);\r\n```\r\nRoom for catch up bursts is calculated based on the past events that occurred in the past window. E.g. with a rate of 3600 events over 1 hour if you generate a single event in the first second and no further events, then in the last second of that hour throttle will have accumulated room for 3599 catch up burst events yet to complete within the last second of the window. As this may exceed expectations of the service you are using it is often usefull to recalculate the rate to a smaller fraction of window that is specified by the external service.  \r\n\r\n<a name=\"usageexcess\"></a>\r\n### 2.4 Excess bursts\r\nMany services allow for brief periods of excess bursts beyond the normal service rate. In many cases your provider may consider catch up bursts as excess bursts. Please check the conditions of the service you are using.\r\n\r\nAnother aspect of excess burst is that they can usually be initiated right away.To implement that would mean that the first number of calls to next() (e.g. 10, 50, 100) would return immediately as an excess burst only to be followed by delays imposed by the normal rate. To implement this throttle would have to do more examination on the timeline of events and this is currently not implemented.\r\n","readmeFilename":"README.md"}