Limit

Classes

InMemoryLimitHandle

The InMemoryLimitHandle is returned from the InMemoryLimit and acts an as interface to the actual limit object.

InMemoryLimit

An InMemoryLimit represents a per process limit implemented by using local storage to track the limiting activities. An InMemoryLimit will not be shareable between processes.

Limit

RedisLimitHandle

The LimitHandle is returned from the RedisLimit and acts an as interface to the actual limit.

RedisLimit

The RedisLimit represent a Limit object "stored" in redis. Actually, the Limit's key and its limiting timeout key are stored in redis, which means these Limit types may be shared amongst processes.

Functions

create(options)

Creates a limit of a specifed type

expand()

If config exists, attempt to extract it via json or file read, then adjust the option to look like that plus the rest.

InMemoryLimitHandle

The InMemoryLimitHandle is returned from the InMemoryLimit and acts an as interface to the actual limit object.

Kind: global class

• InMemoryLimitHandle
  • new InMemoryLimitHandle(limit, key, options)
  • .reset()
  • .isLimited() ⇒ boolean
  • .unlimit() ⇒ Promise

new InMemoryLimitHandle(limit, key, options)

Creates a handle for the specified InMemory based Limit.

Param	Type	Description
limit	InMemoryLimit	the Limit wrapped by this interface
key	string	the key to limit
options	object	the options for the limit
options.count	int	the maximum number of times that an activity may occur over a given period of time
options.period	int	the amount of time that the activity may occur before being marked as limited (milliseconds)
options.duration	int	the amount of time to keep the activity marked as limited (milliseconds)

inMemoryLimitHandle.reset()

A method for reseting the limit back to its initial state.

Kind: instance method of InMemoryLimitHandle

inMemoryLimitHandle.isLimited() ⇒ boolean

Kind: instance method of InMemoryLimitHandle
Returns: boolean - true if limiting is active, else false

inMemoryLimitHandle.unlimit() ⇒ Promise

Release the limit.

Kind: instance method of InMemoryLimitHandle
Returns: Promise - a Promise to release the limit

InMemoryLimit

An InMemoryLimit represents a per process limit implemented by using local storage to track the limiting activities. An InMemoryLimit will not be shareable between processes.

Kind: global class

• InMemoryLimit
  • new InMemoryLimit(options)
  • .limit(key, options) ⇒ InMemoryLimitHandle

new InMemoryLimit(options)

Creates a memory based limit object.

Param	Type	Description
options	object	the parameters for the limiter
options.namespace	string	the namespace used in limitNs
options.limitConfig	object	the Limit connection parameters
options.limitConfig.type	string	the type of Limit to create ('inMemory')
options.limitConfig.limitOptions.count	int	the number of times the isLimited method may be checked within the period
options.limitConfig.limitOptions.period	int	the length of time which the isLimited method may be checked before being limited (mS)
options.limitConfig.limitOptions.duration	int	the amount of time the limit will be in effect (mS)

Example

const Limit = require( '@leverege/limit' )
 const limiter = Limit.create( {
   namespace : 'example',
   limitConfig : {
     type : 'inMemory',
     limitOptions : { // default limit options
       count : 10,
       period : 30*1000,
       duration : 60*60*1000,
     },
   },
 })

 // Create a limit that will allow 25 occurances over a 5 second
 // period before imposing a 60 minute limit.
 //
 const memlim = limiter.limit( 'testKey', { count : 25,
                                           period : 5000,
                                         duration : 60*60 })

inMemoryLimit.limit(key, options) ⇒ InMemoryLimitHandle

Limits on the key. This will not auto-prefix the key with the namespace. To auto prefix the key, use limitNs( key ).

Kind: instance method of InMemoryLimit
Returns: InMemoryLimitHandle - a Promise that will resolve to an InMemoryLimitHandle.

Param	Type	Description
key	string	the key to lookup
options	object	the options for the limit
options.count	int	the maximum number of times that an activity may occur over a given period of time
options.period	int	the amount of time that the activity may occur before being marked as limited (milliseconds)
options.duration	int	the amount of time to keep the activity marked as limited (milliseconds)

Limit

Kind: global class

• Limit
  • new Limit(options)
  • instance
    • .getKey(key, namespace) ⇒ string
    • .limit(key, options) ⇒ Promise
    • .limitNs(key, options)
    • .isLimited()
    • .end()
  • static
    • .SecondsPerDay ⇒
    • .mergeDefaults()

new Limit(options)

This class provides the frame work for building rate limiting into an application. A Limit controls the number of times an operation may be performed (count) within a certain time frame (period), and once exceeded, will stay limited (squelched) for some period of time. The count, period and duration are configurable options specified when a Limit is created.

Param	Type	Description
options	object	specific settings for the derived Limit class
options.namespace	string	the namespace string to use (default='app:')

limit.getKey(key, namespace) ⇒ string

Returns the actual key to use. This will combine the namespace + ':' + key if a namespace is available.

Kind: instance method of Limit
Returns: string - the namespaced key value

Param	Type	Default	Description
key	string		a key to prefix with the namespace
namespace	string	null	if supplied, this will be used as the namespace, otherwise, the namespace provided at construction will be used

limit.limit(key, options) ⇒ Promise

Limits on the key. This will not auto-prefix the key with the namespace. To auto prefix the key, use limitNs( key ).

Kind: instance method of Limit
Returns: Promise - a Promise that will resolve with a Lock Handle

Param	Type	Description
key	string	the key to lookup
options	object	specific settings for the Limit class

limit.limitNs(key, options)

Limits on the namespace:key

Kind: instance method of Limit

Param	Type	Description
key	string	the key to lookup
options	object	specific settings for the Limit class

limit.isLimited()

This method must be overridden by the child class that extends from Limit.

Kind: instance abstract method of Limit

limit.end()

This method may be overridden by the child class that extends from Limit. It should be used to clean up any system resources, especially those that can cause unit tests to hang until everything shuts down cleanly.

Kind: instance abstract method of Limit

Limit.SecondsPerDay ⇒

Returns the number of seconds in one 24 hour period (606024)

Kind: static property of Limit
Returns: [int] a description of the return

Limit.mergeDefaults()

Returns a record containing a merging of the specified options and the default limitOptions that may be loaded from a config entry. The defaults are values of 10 hits in 30 seconds results in a 60 minute limit.

Kind: static method of Limit

RedisLimitHandle

The LimitHandle is returned from the RedisLimit and acts an as interface to the actual limit.

Kind: global class

• RedisLimitHandle
  • new RedisLimitHandle(limit, key, options)
  • .isLimited() ⇒ boolean
  • .unlimit() ⇒ Promise

new RedisLimitHandle(limit, key, options)

Creates a handle for the specified Redis based Limit.

Param	Type	Description
limit	RedisLimit	the Limit wrapped by this interface
key	string	the key to limit
options	object	the options for the limit
options.count	int	the maximum number of times that an activity may occur over a given period of time
options.period	int	the amount of time that the activity may occur before being marked as limited (milliseconds)
options.duration	int	the amount of time to keep the activity marked as limited (milliseconds)

redisLimitHandle.isLimited() ⇒ boolean

Kind: instance method of RedisLimitHandle
Returns: boolean - true if limiting is active, else false

redisLimitHandle.unlimit() ⇒ Promise

Release the limits.

Kind: instance method of RedisLimitHandle
Returns: Promise - a Promise to release the limit

RedisLimit

The RedisLimit represent a Limit object "stored" in redis. Actually, the Limit's key and its limiting timeout key are stored in redis, which means these Limit types may be shared amongst processes.

Kind: global class

• RedisLimit
  • new RedisLimit(options)
  • .limit(key, options) ⇒ RedisLimitHandle

new RedisLimit(options)

Creates a redis based limit object.

Param	Type	Description
options	object	the parameters for the limiter
options.namespace	string	the namespace used in limitNs
options.limitConfig	object	the Limit connection parameters
options.limitConfig.type	string	the type of Limit to create ('redis')
options.limitConfig.connection	object	the redis client connection settings
options.limitConfig.connection.host	string	the hostname or IP address where the redis server is running
options.limitConfig.connection.port	int	the port number that the redis server is listening on
options.limitConfig.limitOptions.count	int	the number of times the isLimited method may be checked within the period
options.limitConfig.limitOptions.period	int	the length of time which the isLimited method may be checked before being limited (mS)
options.limitConfig.limitOptions.duration	int	the amount of time the limit will be in effect (mS)

Example

const Limit = require( '@leverege/limit' )
 const limiter = Limit.create( {
   namespace : 'example',
   limitConfig : {
     type : 'redis',
     connection : {
       host : '127.0.0.1',
       port : 6379,
     },
     limitOptions : { // default limit options
       count : 10,
       period : 30*1000,
       duration : 60*60*1000,
     },
   },
 } )

 // Create a limit that will allow 25 occurances over a 5 second
 // period before imposing a 60 minute limit.
 //
 const redlim = limiter.limit( 'testKey', { count : 25,
                                               period : 5000,
                                             duration : 60*60*1000 })

redisLimit.limit(key, options) ⇒ RedisLimitHandle

Limits on the key. This will not auto-prefix the key with the namespace. To auto prefix the key, use limitNs( key ).

Kind: instance method of RedisLimit
Returns: RedisLimitHandle - a Promise that will resolve to an RedisLimitHandle.

Param	Type	Description
key	string	the key to lookup
options	object	the options for the limit
options.count	int	the maximum number of times that an activity may occur over a given period of time
options.period	int	the amount of time that the activity may occur before being marked as limited (milliseconds)
options.duration	int	the amount of time to keep the activity marked as limited (milliseconds)

create(options)

Creates a limit of a specifed type

Kind: global function

Param	Type	Description
options	object	the lock options
options.type	string	the type of lock to make. If unrecognized, this will throw an exception. Possible values: 'redis', 'inMemory'
options.namespace	string	a string that will prepended (with a ':') to all lock keys when accessing the lock using lockNS. The resulting key will be namespace:key
options.limitConfig	object	This can be an object, JSON or reference to a json/js file. If defined, it will be expanded and merged with the other options like prefix. This allows the lock type to be controlled by an environment variable or file.

expand()

If config exists, attempt to extract it via json or file read, then adjust the option to look like that plus the rest.

Kind: global function