API methods

API methods

• consume
• get
• set
• penalty
• reward
• block
• delete
• deleteInMemoryBlockedAll
• getKey

Note, limiter doesn't store any data for key, until you call consume, set, penalty, reward or any other method supposed to change amount of points.

rateLimiter.consume(key, points = 1, options = {})

Points can be consumed by IP address, user ID, authorisation token, API route or any other string.

Returns Promise, which:

• resolved with RateLimiterRes when point(s) is consumed, so action can be done
• rejected only for store and database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object
• rejected when there is no points to be consumed, where reject reason rejRes is RateLimiterRes object
• rejected when key is blocked (if block strategy is set up), where reject reason rejRes is RateLimiterRes object

Alternatively, penalty method can be used to withdraw points. It doesn't throw exceptions when there are not enough points, but resolves with RateLimiterRes instead.

Arguments:

• key is usually IP address or some unique string

• points integer number of points consumed. default: 1

• options is object with additional settings:

  • customDuration set custom duration for specific key. customDuration works only for new consume calls in the time window. It can not overwrite already existing keys. If limiter's duration is 5 seconds and key user1 had a call in the beginning of time window without customDuration the second consume call won't overwrite it until key user1 expires in 5 seconds.

rateLimiter.get(key)

Get RateLimiterRes in current duration. It always returns RateLimiterRes.isFirstInDuration=false.

Returns Promise, which:

• resolved with RateLimiterRes if key is set
• resolved with null if key is NOT set or expired
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

Arguments:

• key is usually IP address or some unique string

rateLimiter.set(key, points, secDuration)

Set the integer number of consumed points by key for secDuration seconds.

Store it forever, if secDuration is 0.

Returns Promise, which:

• resolved with RateLimiterRes
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

rateLimiter.penalty(key, points = 1)

Fine key by points integer number of points for one duration.

Note: Depending on time penalty may go to next durations

Returns Promise, which:

• resolved with RateLimiterRes
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

rateLimiter.reward(key, points = 1)

Reward key by points integer number of points for one duration.

Note: Depending on time reward may go to next durations

Returns Promise, which:

• resolved with RateLimiterRes
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

rateLimiter.block(key, secDuration)

Block key by setting consumed points to points + 1 for secDuration seconds.

It force updates expire, if there is already key.

Blocked key never expires, if secDuration is 0. Note, that calling consume function for the blocked key overwrites duration, so it will expire.

Returns Promise, which:

• resolved with RateLimiterRes
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

rateLimiter.delete(key)

Delete all data related to key.

For example, previously blocked key is not blocked after delete as there is no data anymore.

Returns Promise, which:

• resolved with boolean, true if data is removed by key, false if there is no such key.
• rejected only for database limiters if insuranceLimiter isn't setup: when some error happened, where reject reason rejRes is Error object
• rejected only for RateLimiterCluster if insuranceLimiter isn't setup: when timeoutMs exceeded, where reject reason rejRes is Error object

rateLimiter.deleteInMemoryBlockedAll()

Delete all in memory blocked keys. A key may be blocked in memory to avoid extra requests to a store. See in memory block options here

rateLimiter.getKey(key)

Returns internal key prefixed with keyPrefix option as it is saved in store.