Simple ratelimiter for express
Last updated 5 months ago by mmpro .
Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ac-ratelimiter 
SYNC missed versions from official npm registry.


This tool provides rate-limiter based on Redis and ExpressJs.


const acrl = require('ac-ratelimiter')

const init = {
  routes: [
    { route: 'user/find', throttleLimit: 1, limit: 2, expires: 3, delay: 250 },
  logger: winston.log INSTANCE


// req.rateLimitCounter should have already the current count
acrl.ratelimiter(req, {}, err => {
  // err.status === 900 => throttling is active
  // err.status === 429 => limiter is active
  return res.json({ status: _.get(err, 'status') })



The ac-ratelimiter uses Redis as storage for the rate-limiter keys. You can also write your own, memory-based, backend. See the test for an example.

Additionally, for logging purposes, we use Winston. But you can also use any other logger that provides logging for "warn" and "error".

Last but not least, provide an array of objects with rate limiter instructions. Each object has the following properties:

Property Type Example Remarks
route string user/find A combination of controller and action (express) or any other identifier you can provide
throttleLimit integer 20 Number of calls before throttling starts
delay integer 250 Number of milliseconds a throttle request is delayed (on purpose)
limit integer 100 Number of calls before the limiter kicks in
expires integer 3 Number of seconds before the rate-limiter resets

The init function can take additional parameters like

  • environment
  • debugMode


The actual rateLimiter function takes two arguments, the Express request object (req) and an options object with the following optional properties:

Property Type Example Remarks
knownIP Object { name: 'AdmiralCloud' } Display known IPs with their name when limiter is active
link String myLink Display and locks the limiter to a given link (as identifier)
token String myToken Locks the limiter to a given token/user session
name String myName Identifier for the route - falls back to controller/action
redisKey String myKey Optional RedisKey to use for rate limiter
fallbackRoute String fbroute Optional fallback route identifier
expires Integer 3 Expire time for rate limiter - see above
throttleLimit Integer 20 Throttle limit for rate limiter - see above
delay Integer 250 Delay for throttled calls for rate limiter - see above

Good practice

It is recommended to put the determined IP to the request object as req.determinedIP.

Additionally, you can put the rateLimitCounter to the request object as req.rateLimitCounter. This way, the rate limiter does not have to fetch that value.

Both values might be retrieved prior to the rate limiter so there is no need to retrieve it once again here.


Run tests

Call yarn run test


MIT License Copyright © 2009-present, AdmiralCloud, Mark Poepping

Current Tags

  • 1.0.1                                ...           latest (5 months ago)

3 Versions

  • 1.0.1                                ...           5 months ago
  • 1.0.0                                ...           5 months ago
  • 0.0.1                                ...           5 months ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (3)
Dev Dependencies (8)
Dependents (0)

Copyright 2014 - 2016 © |