cldn-ratelimit
v1.2.3
Published
Simple ratelimiter for Node.js
Downloads
33
Readme
Rate limiting utility
{{shield:tests}} {{shield:coverage}} {{shield:build}}
A relatively simple utility for abstract rate limiting. This library uses memory storage (i.e. does not rely on external database or writing data on your file system). Rate limits are reset if the process is restarted.
Get started
Install package from npm
npm i cldn-ratelimit
Import in your project
Here is a very simple demo demonstrating very basic limiting of login attempts.
import {RateLimit} from 'cldn-ratelimit';
const rateLimit = new RateLimit("login-attempts", 3, 60); // max 3 requests per 60 seconds
const attemptLogin = (username, password) => {
if (!rateLimit.attempt(username).allow) return "rate-limited";
if (username === "john.doe" && password === "password123") return "success";
return "wrong-password";
}
attemptLogin("john.doe", "wrongpass"); //-> "wrong-password"
attemptLogin("john.doe", "wrongpass2"); //-> "wrong-password"
attemptLogin("john.doe", "wrongpass"); //-> "wrong-password"
attemptLogin("john.doe", "password123"); //-> "rate-limited"
// wait 60 seconds
attemptLogin("john.doe", "password123"); //-> "success"
If you want to reset the rate limit after a successful login, call rateLimit.reset(username)
.
Documentation
- Class:
RateLimit
- Static method:
RateLimit.attempt(name, source, [attempts], [callback])
- Static method:
RateLimit.check(name, source, [callback])
- Static method:
RateLimit.clear(name)
- Static method:
RateLimit.create(name, limit, timeWindow)
- Static method:
RateLimit.delete(name)
- Static method:
RateLimit.get(name)
- Static method:
RateLimit.reset(name, source)
- Static method:
RateLimit.setRemaining(name, source, remaining)
new RateLimit(name, limit, timeWindow)
rateLimit.attempt(source, [attempts], [callback])
rateLimit.check(source, [callback])
rateLimit.clear()
rateLimit.delete()
rateLimit.limit
rateLimit.name
rateLimit.reset(source)
rateLimit.setRemaining(source, remaining)
rateLimit.timeWindow
- Static method:
- Interface:
AttemptResult
Class: RateLimit
Rate limit
Static method: RateLimit.attempt(name, source, [attempts], [callback])
Make an attempt with a source ID
name
string
The name of the rate limitsource
string
Unique source identifier (e.g. username, IP, etc.)attempts
number
The number of attempts to make. Default:1
callback
function
Callback function. Default:undefined
result
AttemptResult
The result of the attempt- Returns:
void
- Returns:
AttemptResult
- Throws:
Error
If the rate limit does not exist
Static method: RateLimit.check(name, source, [callback])
Check the attempt state for a source ID without decrementing the remaining attempts
name
string
The name of the rate limitsource
string
Unique source identifier (e.g. username, IP, etc.)callback
function
Callback function. Default:undefined
result
AttemptResult
The result of the attempt- Returns:
void
- Returns:
AttemptResult
- Throws:
Error
If the rate limit does not exist
Static method: RateLimit.clear(name)
Clear rate limit attempts storage. This is equivalent to resetting all rate limits.
Static method: RateLimit.create(name, limit, timeWindow)
Create a new rate limit
name
string
The name of the rate limitlimit
number
The number of attempts allowed per time window (e.g. 60)timeWindow
number
The time window in seconds (e.g. 60)- Returns:
RateLimit
Static method: RateLimit.delete(name)
Delete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.
Static method: RateLimit.get(name)
Get a rate limit instance
Static method: RateLimit.reset(name, source)
Reset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.
name
string
The name of the rate limitsource
string
Unique source identifier (e.g. username, IP, etc.)- Returns:
void
- Throws:
Error
If the rate limit does not exist
Static method: RateLimit.setRemaining(name, source, remaining)
Set the remaining attempts for a source ID.
Warning: This is not recommended as the remaining attempts depend on the limit of the instance.
name
string
The name of the rate limitsource
string
Unique source identifier (e.g. username, IP, etc.)remaining
number
The number of remaining attempts- Returns:
void
- Throws:
Error
If the rate limit does not exist
new RateLimit(name, limit, timeWindow)
Create a new rate limit
name
string
The name of the rate limitlimit
number
The number of attempts allowed per time window (e.g. 60)timeWindow
number
The time window in seconds (e.g. 60)- Throws:
Error
If the rate limit already exists
rateLimit.attempt(source, [attempts], [callback])
Make an attempt with a source ID
source
string
Unique source identifier (e.g. username, IP, etc.)attempts
number
The number of attempts to make. Default:1
callback
function
Callback functionresult
AttemptResult
The result of the attempt- Returns:
void
- Returns:
AttemptResult
rateLimit.check(source, [callback])
Check the attempt state for a source ID without decrementing the remaining attempts
source
string
Unique source identifier (e.g. username, IP, etc.)callback
function
Callback functionresult
AttemptResult
The result of the attempt- Returns:
void
- Returns:
AttemptResult
rateLimit.clear()
Clear rate limit attempts storage. This is equivalent to resetting all rate limits.
- Returns:
void
rateLimit.delete()
Delete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.
- Returns:
void
rateLimit.limit
The number of requests allowed per time window
- Type:
number
rateLimit.name
Get rate limit name
- Type:
string
- Readonly
rateLimit.reset(source)
Reset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.
rateLimit.setRemaining(source, remaining)
Set the remaining attempts for a source ID.
Warning: This is not recommended as the remaining attempts depend on the limit of the instance.
source
string
Unique source identifier (e.g. username, IP, etc.)remaining
number
The number of remaining attempts- Returns:
void
rateLimit.timeWindow
The time window in seconds (e.g. 60)
- Type:
number
Interface: AttemptResult
The result from a rate limit attempt
attemptResult.limit
The number of requests this rate limit allows per time window
- Type:
number
- Readonly
attemptResult.remaining
The number of requests remaining in the current time window
- Type:
number
- Readonly
attemptResult.reset
The number of seconds until the current time window resets
- Type:
number
- Readonly
attemptResult.rateLimit
The rate limit that this attempt was made on
- Type:
RateLimit
- Readonly
attemptResult.allow
Whether this attempt should be allowed to proceed. If false, the attempt is rate limited.
- Type:
boolean
- Readonly