The database for limitd.
Branch: master
Clone or download
Pull request Compare This branch is 78 commits ahead, 10 commits behind limitd:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Build Status

limitd-redis is client for limits on top of redis using Token Buckets. It's a fork from LimitDB.


npm i limitd-redis


Create an instance of limitd-redis as follows:

const Limitd = require('limitd-redis');

const limitd = new Limitd({
  uri: 'localhost',
  nodes: [{
    port: 7000,
    host: 'localhost'
  buckets: {
    ip: {
      size: 10,
      per_second: 5
  prefix: 'test:'

Options available:

  • uri (string): Redis Connection String.
  • nodes (array): Redis Cluster Configuration.
  • buckets (object): Setup your bucket types.
  • prefix (string): Prefix keys in Redis.


  • size is the maximun content of the bucket. This is the maximun burst you allow.
  • per_interval is the amount of tokens that the bucket receive on every interval.
  • interval defines the inverval in milliseconds.

You can also define your rates using per_second, per_minute, per_hour, per_day. So per_second: 1 is equivalent to per_interval: 1, interval: 1000.

If you omit size, limitdb assumes that size is the value of per_interval. So size: 10, per_second: 10 is the same than per_second: 10.

If you don't specify a filling rate with per_interval or any other per_x, the bucket is fixed and you have to manually reset it using PUT.

You can also define overrides inside your type definitions as follows:

buckets = {
  ip: {
    size: 10,
    per_second: 5,
    overrides: {
      '': {
        size: 100,
        per_second: 50

In this case the specific bucket for of type ip will have a greater limit.

It is also possible to define overrides by regex:

overrides: {
  'local-ips': {
    match:      /192\.168\./
    size:       100,
    per_second: 50

It's possible to configure expiration of overrides:

overrides: {
  '': {
    size:       100,
    per_second: 50,
    until:      new Date(2016, 4, 1)

Breaking changes from Limitdb

  • The status method is not supported by this client.
  • Elements will have a default TTL of a week unless specified otherwise.


limitd.take({ type: 'ip', key: '' }, (err, result) => {

limitd.take takes as argument an object with:

  • type: the bucket type.
  • key: the identifier of the bucket.
  • count: the amount of tokens you need. This is optional and the default is 1.

The result object has:

  • conformant (boolean): true if the requested amount is conformant to the limit.
  • remaining (int): the amount of remaining tokens in the bucket.
  • reset (int / unix timestamp): unix timestamp of the date when the bucket will be full again.
  • limit (int): the size of the bucket.


You can manually reset a fill a bucket using PUT:

limitd.put({ type: 'ip', key: '' }, err => {});

limitd.put takes as argument an object with:

  • type: the bucket type.
  • key: the identifier of the bucket.
  • count: the amount of tokens you want to put in the bucket. This is optional and the default is the size of the bucket.




This project is licensed under the MIT license. See the LICENSE file for more info.