{"id":14969149,"url":"https://github.com/fastify/fastify-throttle","last_synced_at":"2025-10-19T09:32:18.084Z","repository":{"id":181632030,"uuid":"667042956","full_name":"fastify/fastify-throttle","owner":"fastify","description":"Throttle the download speed of a request","archived":false,"fork":false,"pushed_at":"2024-10-01T21:18:47.000Z","size":368,"stargazers_count":17,"open_issues_count":1,"forks_count":5,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-04T15:11:56.065Z","etag":null,"topics":["fastify","fastify-plugin","throttle","throttling"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fastify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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":"fastify","open_collective":"fastify"}},"created_at":"2023-07-16T13:02:20.000Z","updated_at":"2024-10-01T21:18:43.000Z","dependencies_parsed_at":"2023-09-22T00:14:24.182Z","dependency_job_id":"1575349a-cf2c-41d2-93a0-bd867091f0cd","html_url":"https://github.com/fastify/fastify-throttle","commit_stats":{"total_commits":24,"total_committers":11,"mean_commits":"2.1818181818181817","dds":0.75,"last_synced_commit":"014b26a45c56508ca4a62065be57d87819bd4170"},"previous_names":["fastify/fastify-throttle"],"tags_count":4,"template":false,"template_full_name":"fastify/skeleton","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-throttle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-throttle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-throttle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fastify%2Ffastify-throttle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fastify","download_url":"https://codeload.github.com/fastify/fastify-throttle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219869824,"owners_count":16555273,"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":["fastify","fastify-plugin","throttle","throttling"],"created_at":"2024-09-24T13:41:12.721Z","updated_at":"2025-10-19T09:32:17.759Z","avatar_url":"https://github.com/fastify.png","language":"JavaScript","readme":"# @fastify/throttle\n\n![CI](https://github.com/fastify/fastify-throttle/workflows/CI/badge.svg)\n[![NPM version](https://img.shields.io/npm/v/@fastify/throttle.svg?style=flat)](https://www.npmjs.com/package/@fastify/throttle)\n[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)\n\nThrottle the download speed of a request.\n\n## Install\n```sh\nnpm i @fastify/throttle\n```\n\n## Usage\nRegister the plugin and, if necessary, pass custom options.\n\nThis plugin will add an `onSend` hook to the Fastify instance, which will throttle the download speed of the response.\n```js\nimport Fastify from 'fastify'\n\nconst fastify = Fastify()\nawait fastify.register(import('@fastify/throttle'), {\n  bytesPerSecond: 1024 * 1024, // 1MB/s\n  streamPayloads: true, // throttle the payload if it is a stream\n  bufferPayloads: true, // throttle the payload if it is a Buffer\n  stringPayloads: true // throttle the payload if it is a string\n})\n\nfastify.get('/', (request, reply) =\u003e {\n  reply.send({ hello: 'world' })\n})\n\nfastify.listen({ port: 3000 }, err =\u003e {\n  if (err) {\n    throw err\n  }\n  console.log('Server listening at http://localhost:3000')\n})\n```\n\n### Options\n\nYou can pass the following options during the plugin registration:\n```js\nawait fastify.register(import('@fastify/throttle'), {\n  bytesPerSecond: 1000, // 1000 bytes per second\n  streamPayloads: true, // throttle the payload if it is a stream\n  bufferPayloads: true, // throttle the payload if it is a Buffer\n  stringPayloads: true // throttle the payload if it is a string\n})\n```\n\nYou can define the throttling globally as plugin options or per route options.\nThe throttle options per route are the same as the plugin options.\n\n| Header | Description | Default |\n|--------|-------------|---------|\n| `bytesPerSecond` | The allowed bytes per second, number or a function | 16384 |\n| `streamPayloads` | Throttle the payload if it is a stream | true |\n| `bufferPayloads` | Throttle the payload if it is a Buffer | false |\n| `stringPayloads` | Throttle the payload if it is a string | false |\n| `async` | Set to true if bytesPerSecond is a function returning a Promise | false |\n\nExample for setting throttling globally:\n\n```js\n  const fastify = require('fastify')()\n\n  await fastify.register(import('@fastify/throttle'), {\n    bytesPerSecond: 1024 // 1KB/s\n  })\n\n  fastify.get('/', (req, reply) =\u003e {\n    reply.send(createReadStream(resolve(__dirname, __filename)))\n  })\n\n  fastify.listen({ port: 3000 })\n```\n\nExample for setting the throttling per route:\n\n```js\n  'use strict'\n\n  const fastify = require('fastify')()\n\n  await fastify.register(import('@fastify/throttle'))\n\n  fastify.get('/', {\n    config: {\n      throttle: {\n        bytesPerSecond: 1000\n      }\n    }\n  }, (req, reply) =\u003e {\n    reply.send(createReadStream(resolve(__dirname, __filename)))\n  })\n\n  fastify.listen({ port: 3000 })\n```\n\nThe `bytesPerSecond` option can be a number or a function. The function for `bytesPerSecond` has the following TypeScript definition: \n\n```typescript\ntype BytesPerSecond = (request: FastifyRequest) =\u003e ((elapsedTime: number, bytes: number) =\u003e number) | Promise\u003c((elapsedTime: number, bytes: number) =\u003e number)\u003e\n```\n\n`request` is the Fastify request object.\n\n`elapsedTime` is the time since the streaming started in seconds.\n`bytes` are the bytes already sent.\n\nYou must ensure that the return value is an integer or `Infinity`.\n\nYou could, for example, delay the output by sending 0 for the first 2 seconds by defining\nthe `bytesPerSecond` like this:\n\n```js\n  const fastify = require('fastify')()\n\n  await fastify.register(import('@fastify/throttle'))\n\n  fastify.get('/', {\n    config: {\n      throttle: {\n        bytesPerSecond: function bytesPerSecondfactory(request) {\n          // this function runs for every request\n          const client = request.headers['customer-id']\n          \n          return function (elapsedTime, bytes) {\n            return CONFIG[client] * 2 // return a number of xyz\n          }\n        }\n      }\n    }\n  }, (req, reply) =\u003e {\n    reply.send(createReadStream(resolve(__dirname, __filename)))\n  })\n\n  fastify.listen({ port: 3000 })\n```\n\nThe `bytesPerSecond` function can be a sync function or an async function. If you provide an async function then it will be detected by the plugin. If it is a sync function returning a Promise, you must set the `async` option to `true`, so that the plugin knows that it should await the Promise.\n\n```js\n  const fastify = require('fastify')()\n\n  await fastify.register(import('@fastify/throttle'))\n\n  fastify.get('/', {\n    config: {\n      throttle: {\n        async: true,\n        bytesPerSecond: function bytesPerSecondfactory(request) {\n          // this function runs for every request\n          const client = request.headers['customer-id']\n          \n          return Promise.resolve(function (elapsedTime, bytes) {\n            return CONFIG[client] * 2 // return a number of xyz\n          })\n        }\n      }\n    }\n  }, (req, reply) =\u003e {\n    reply.send(createReadStream(resolve(__dirname, __filename)))\n  })\n\n  fastify.listen({ port: 3000 })\n```\n\n\u003ca name=\"license\"\u003e\u003c/a\u003e\n## License\n**[MIT](https://github.com/fastify/fastify-throttle/blob/master/LICENSE)**\n","funding_links":["https://github.com/sponsors/fastify","https://opencollective.com/fastify"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-throttle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffastify%2Ffastify-throttle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffastify%2Ffastify-throttle/lists"}