Creating a Store
Overview
A store tracks how many hits each client (identified via their IP address) has received and automatically reduce that hit count as time elapses.
The Store
Interface
A store must have the increment
, decrement
, and resetKey
public
methods. It may optionally have the init
, get
and resetAll
public methods
and a prefix
(string) or localKeys
(boolean) field. For backwards
compatibility with versions prior to 6.0.0
, it may also have the incr
and
decr
public methods. Finally, it may have a constructor
and any number of
private methods.
The increment
method is the primary interface between the middleware and the
store. It adds 1 to the internal count for a key and returns an object
consisting of the new internal count (totalHits
) and the time that the count
will reach 0 (resetTime
).
The decrement
method is used only to ‘uncount’ requests when one or both of
the skipSuccessfulRequests
or skipFailedRequests
options are enabled.
The init
method allows the store to set itself up using the options passed to
the middleware. The store can get the windowMs
option from this method.
The get
method takes a string
argument (the key that identifies a client)
and returns an object consisting of the internal hit count (totalHits
) and the
time that the count will reach 0 (resetTime
) for the given client. It may
return undefined
if it cannot find the key.
The resetKey
method takes a string
argument (the key that identifies a
client) and sets the internal count for that key to zero.
The resetAll
method takes no arguments and sets the internal count for all
keys to zero.
The prefix
field is used to avoid conflicts when the user creates multiple
instances of the store for multiple rate limits (e.g. 10 hits per minute and 60
hits per hour). Keys in the database should be prefixed with this value.
prefix
is generally passed as an option to the constructor. (The singleCount
validation check also takes the prefix
field into account and does not report
that a user is being double-counted if the stores have different prefixes.)
The localKeys
field is an alternative to prefix
for stores such as the
MemoryStore where two instances will automatically keep separate counts. Setting
it to true
will prevent false positives from the singleCount
validation
check.
The get
and resetKey
methods can be called from the middleware, like so:
// Create a rate limiter.
const limiter = rateLimit({
/* ... */
})
// Fetch or reset the hit count for a key.
limiter.get('1.2.3.4')
limiter.resetKey('1.2.3.4')
Dependency configuration
Add express-rate-limit
as a peer dependency, and a development dependency to
the package:
{
"peerDependencies": {
"express-rate-limit": ">= 6"
},
"devDependencies": {
"express-rate-limit": "7"
}
}
If the store supports the incr
method, replace >= 6
with >= 2.3.0
Example Typescript and Javascript Stores
Using a Custom Store
// Use `const ... = require('...')` instead if you are using CommonJS
import rateLimit from 'express-rate-limit'
import SomeStore from './some-store.js'
const limiter = rateLimit({
store: new SomeStore({ customParam: '🎉' }),
})