Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 864 Commits
.github		.github
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Repository files navigation

plugin-throttling.js

Octokit plugin for GitHub’s recommended request throttling

Implements allrecommended best practices to prevent hitting secondary rate limits.

Usage

Browsers	Load`@octokit/plugin-throttling` and`@octokit/core` (or core-compatible module) directly fromesm.sh <scripttype="module">import{Octokit}from"https://esm.sh/@octokit/core";import{throttling}from"https://esm.sh/@octokit/plugin-throttling";</script>
Node	Install with`npm install @octokit/core @octokit/plugin-throttling`. Optionally replace`@octokit/core` with a core-compatible module. import{Octokit}from"@octokit/core";import{throttling}from"@octokit/plugin-throttling";

Important

As we useconditional exports, you will need to adapt yourtsconfig.json by setting"moduleResolution": "node16", "module": "node16".

See the TypeScript docs onpackage.json "exports".
See thishelpful guide on transitioning to ESM from@sindresorhus

The code below creates a "Hello, world!" issue on every repository in a given organization. Without the throttling plugin it would send many requests in parallel and would hit rate limits very quickly. But the@octokit/plugin-throttling slows down your requests according to the official guidelines, so you don't get blocked before your quota is exhausted.

Thethrottle.onSecondaryRateLimit andthrottle.onRateLimit options are required. Returntrue to automatically retry the request afterretryAfter seconds.

constMyOctokit=Octokit.plugin(throttling);constoctokit=newMyOctokit({auth:`secret123`,throttle:{onRateLimit:(retryAfter,options,octokit,retryCount)=>{octokit.log.warn(`Request quota exhausted for request${options.method}${options.url}`,);if(retryCount<1){// only retries onceoctokit.log.info(`Retrying after${retryAfter} seconds!`);returntrue;}},onSecondaryRateLimit:(retryAfter,options,octokit)=>{// does not retry, only logs a warningoctokit.log.warn(`SecondaryRateLimit detected for request${options.method}${options.url}`,);},},});asyncfunctioncreateIssueOnAllRepos(org){constrepos=awaitoctokit.paginate(octokit.repos.listForOrg.endpoint({ org}),);returnPromise.all(repos.map(({ name})=>octokit.issues.create({        owner,repo:name,title:"Hello, world!",}),),);}

Pass{ throttle: { enabled: false } } to disable this plugin.

Clustering

Enabling Clustering support ensures that your application will not go over rate limitsacross Octokit instances and across Nodejs processes.

First install eitherredis orioredis:

# NodeRedis (https://github.com/NodeRedis/node_redis)npm install --save redis# or ioredis (https://github.com/luin/ioredis)npm install --save ioredis

Then in your application:

importBottleneckfrom"bottleneck";importRedisfrom"redis";constclient=Redis.createClient({/* options */});constconnection=newBottleneck.RedisConnection({ client});connection.on("error",err=>console.error(err));constoctokit=newMyOctokit({auth:'secret123'throttle:{onSecondaryRateLimit:(retryAfter,options,octokit)=>{/* ... */},onRateLimit:(retryAfter,options,octokit)=>{/* ... */},// The Bottleneck connection object    connection,// A "throttling ID". All octokit instances with the same ID// using the same Redis server will share the throttling.id:"my-super-app",// Otherwise the plugin uses a lighter version of Bottleneck without Redis support    Bottleneck}});// To close the connection and allow your application to exit cleanly:awaitconnection.disconnect();

To use theioredis library instead:

importRedisfrom"ioredis";constclient=newRedis({/* options */});constconnection=newBottleneck.IORedisConnection({ client});connection.on("error",(err)=>console.error(err));

Options

name	type	description
`options.retryAfterBaseValue`	`Number`	Number of milliseconds that will be used to multiply the time to wait based on `retry-after` or `x-ratelimit-reset` headers. Defaults to`1000`
`options.fallbackSecondaryRateRetryAfter`	`Number`	Number of seconds to wait until retrying a request in case a secondary rate limit is hit and no`retry-after` header was present in the response. Defaults to`60`
`options.connection`	`Bottleneck.RedisConnection`	A Bottleneck connection instance. SeeClustering above.
`options.id`	`string`	A "throttling ID". All octokit instances with the same ID using the same Redis server will share the throttling. SeeClustering above. Defaults to`no-id`.
`options.Bottleneck`	`Bottleneck`	Bottleneck constructor. SeeClustering above. Defaults to `bottleneck/light`.