Skip to content

Options

Jump to bottom
Roman edited this page Sep 5, 2025 · 54 revisions

You can change any option in runtime, e.g. rateLimiter.points = 50 will change number of allowed points. rateLimiter.duration = 5 won't change already created keys, but it will affect all new keys.

Specific:

Mongo

Nodejs Cluster

Redis

PostgreSQL

DynamoDB

Drizzle

Options

  • keyPrefix

    Default: 'rlflx'

    It is required when you need to create two or more limiters with different options so keys don't interfere with different limiters.

    Set to empty string '', if keys should be stored without prefix.

    Note: for some limiters it should correspond to Storage requirements for tables or collections name, as keyPrefix may be used as their name.

  • points

    Default: 4

    Maximum number of points can be consumed over duration. Limiter compares this number with number of consumed points by key to reject or resolve an action.

    points value can be updated anytime, e.g. rateLimiter.points = 3. Take a look at this test case.

  • duration

    Default: 1

    Number of seconds before consumed points are reset, starting from the time of the first consumed point on a key. Points will be reset every second if the duration is set to 1 second.

    Points never expire, if duration is 0.

  • blockDuration

    Default: 0

    If blockDuration is a positive number and more points are consumed than available, the limiter prolongs points lifetime for blockDuration seconds. It rejects further consume calls for that key during this blockDuration time.

    This feature can be used to stop malicious activities for an extended period.

  • storeClient

    Required for Redis, Memcached, MongoDB, MySQL, PostgreSQL, etc

    Have to be redis, ioredis, memcached, mongodb, pg, mysql2, mysql or any other related pool or connection.

  • inMemoryBlockOnConsumed

    Default: 0

    For Redis, Memcached, MongoDB, MySQL, PostgreSQL, etc.

    Can be used against DDoS attacks. In-memory blocking works in current process memory and for consume method only.

    It blocks a key in memory for msBeforeNext milliseconds from the last consume result, if inMemoryBlockDuration is not set. This helps to avoid extra requests. inMemoryBlockOnConsumed value is supposed to be equal or more than points option. Sometimes it is not necessary to increment counter on store, if all points are consumed already.

  • inMemoryBlockDuration

    Default: 0

    Block key for inMemoryBlockDuration seconds, if inMemoryBlockOnConsumed or more points are consumed. Set it the same as blockDuration option for distributed application to have consistent result on all processes.

  • insuranceLimiter

    Default: undefined

    Instance of RateLimiterAbstract extended object to store limits, when database comes up with any error.

    All data from insuranceLimiter is NOT copied to parent limiter, when error gone

    Note: insuranceLimiter automatically setup blockDuration and execEvenly to same values as in parent to avoid unexpected behaviour

Specific options

  • storeType

    For MySQL and PostgreSQL it is required only for Knex and have to be set to 'knex'.

    For SQLite limiter it should be set if you use 'better-sqlite3' or 'knex' packages, defaulting to 'sqlite3'.

  • dbName

    Default for MySQL: 'rtlmtrflx'

    Default for MongoDB: 'node-rate-limiter-flexible'

    Database where limits are stored. It is created during creating a limiter. Doesn't work with Mongoose, as mongoose connection is established to exact database.

  • tableName

    Default: equals to 'keyPrefix' option

    For MongoDB, MySQL, PostgreSQL, SQLite.

    By default, limiter creates a table for each unique keyPrefix. tableName option sets table/collection name where values should be stored.

  • tableCreated

    Default: false For MySQL, PostgreSQL, SQLite, and DynamoDB.

    Do not create a table for rate limiter, if tableCreated=true. ready callback in construct can be safely omitted if table already created.

  • clearExpiredByTimeout

    Default: true For MySQL, SQLite, and PostgreSQL.

    Rate limiter deletes data expired more than 1 hour ago every 5 minutes.

    Note, call rateLimiter.clearExpired(Date.now() - 3600000) manually to remove expired rows in AWS Lambda or GCP function.

  • execEvenly

    Default: false

    Delay action to be executed evenly over duration. First action in duration is executed without delay. All next allowed actions in current duration are delayed by formula msBeforeDurationEnd / (remainingPoints + 2) with minimum delay of duration * 1000 / points. It allows to cut off load peaks similar way to Leaky Bucket. Read about it more in this article.

    Note: it isn't recommended to use it for long duration and few points, as it may delay action for too long with default execEvenlyMinDelayMs.

  • execEvenlyMinDelayMs

    Default: duration * 1000 / points

    Sets minimum delay in milliseconds, when action is delayed with execEvenly

Options specific to Mongo

  • indexKeyPrefix

    Default: {}

    Object which is used to create combined index by {...indexKeyPrefix, key: 1} attributes.

  • disableIndexesCreation

    Default: false

    Disable indexes creation that are created by default on limiter creation. Call async createIndexes manually. Note, without indexes no limiter would work properly.

    const limiter = new RateLimiterMongo({
    storeClient: mongoClient,
    disableIndexesCreation: true
});
await limiter.createIndexes();

Options specific to Cluster

  • timeoutMs

    Default: 5000

    Timeout for communication between worker and master over IPC. If master doesn't response in time, promise is rejected with Error

Redis specific options

  • rejectIfRedisNotReady

    Default: false

    If set to true RateLimiterRedis rejects requests immediately when Redis client status is not ready. Useful for high traffic applications or / and in combination with insuranceLimiter.

  • customIncrTtlLuaScript

    Use custom Lua script to make increments. See this rejected when consume more than maximum points and multiply delay test for example.

  • useRedisPackage

    By default it identifies redis package correctly, but they changed so much, so you can set useRedisPackage option to true explicitly if this doesn't work out of the box. If set to true storeClient should be created with redis package of version 4+.

  • useRedis3AndLowerPackage

    Default: false Danger! It isn't fully supported. Test it carefully or just upgrade your redis package to version 4 or later. If set to true storeClient should be created with redis package of version 3 or lower.

PostgreSQL options

  • schemaName

    By default it connects to public or your default schema. Use schemaName option to store data in different schema.

DynamoDB options

  • dynamoTableOpts

    By default it is set to:

    {
    readCapacityUnits: 25,
    writeCapacityUnits: 25,
}

  • ttlSet

    Default: false

    By default RateLimiterDynamo requests DynamoDB to check TTL settings. You can set ttlSet option to true to skip TTL requests during limiter instantiation. This could be useful in a serverless environment.

Drizzle options

  • schema

    Required.

    Example:

const rateLimiterFlexible = pgTable('RateLimiterFlexible', {
  key: text('key').primaryKey(),
  points: integer('points').notNull(),
  expire: timestamp('expire'),
})

Get started

Middlewares and plugins

Migration from other packages

Limiters:

Wrappers:

Knowledge base:

Clone this wiki locally