Throttle

Create a throttled version of a function.

Installation

npm install --save @ambassify/throttle

Usage

Creates a throttled version of func. func will only be invoked when its result is not in the throttled function's cache or the time between the current and last invocation is larger than what's specified by delay.

If func is async, the throttled function will immediately return a value from cache (if available) while func is executing.

Returns: ThrottledFunction - The throttled version of "func"

| Param | Type | Description | | --- | --- | --- | | func | function | The function to throttle | | options | ThrottleOptions | |

Example

const throttle = require('@ambassify/throttle');

const throttled = throttle(<function-to-throttle>, <options>);

throttled('hello');
throttled.clear(<...args>);

ThrottleOptions : Object

| Name | Type | Description | | --- | --- | --- | | delay | number | How much time must have been elapsed for func to be invoked again when there's a chached result available. Defaults to Infinity. | | maxAge | number | How long are items allowed to remain in cache. Unlimited by default. | | maxSize | number | How long are items allowed to remain in cache. Unlimited by default. | | cache | Map | Specify a custom cache for throttle to use. Must provide methods that match Map's equivalent: has, get, set, delete, clear | | resolver | function | Given the same arguments used to invoke func return only what's important to build the cache key. | | onUpdated | function | Invoked with the cacheItem whenever the item is updated. | | onError | 'clear' | 'cached' | 'persist' | function | Error handler to use when "func" throws or rejects. - clear: The cache is cleared and the error is thrown - persist: The error is saved into cache and thrown - cached: If a previous value is in cache, it will be returned, if not the error will be thrown - a custom function that receives the error as first param and cacheItem as the second, when specified the throttled function won't touch the cache when an error occurs, it's up to this handler to interact with cacheItem. |

ThrottledFunction : function

The throttled function.

Properties

| Name | Type | Description | | --- | --- | --- | | clear | function | When invoked without any arguments the entire cache is cleared, when are supplied they are passed, the item for those arguments is removed from cache. |

CacheItem

CacheItems are exposed through the onUpdated callback that can be specified in the throttle options.

• cacheItem.initialized: Whether or not the item has its initial value
• cacheItem.pending: The pending promise when throttle is currently running but already has a previous value
• cacheItem.key: The key for this cache item
• cacheItem.stale: Whether or not the cache item's value is considered stale based on the last time it was updated and its "delay" option.
• cacheItem.value: Current value of the cache item. When this is set, all timers and the like for the item are also reset
• cacheItem.error: Same as "value" but used to indicate the result of throttled is an error
• cacheItem.clear(): Clear the item from throttled's cache
• cacheItem.delay(delay): Update this specific item's "delay"
• cacheItem.maxAge(maxAge): Update this specific item's "maxAge"

Example

const throttle = require('@ambassify/throttle');

let example = 0;

async function myFunction(input) {
    // Delay 500 ms to fake a slow operation
    await new Promise(resolve => setTimeout(resolve, 500));

    example += input;
    return example;
}

// Allow `myFunction` to be called once every 2 seconds for each different
//`input` and cache the value for max 5 seconds.
const throttled = throttle(myFunction, { delay: 2000, maxAge: 5000 });

throttled(1); // 1
throttled(1); // 1
throttled(1); // 1

// Wait for 2 seconds
// "myFunction" is called, but the old cached result is returned immediately

throttled(1); // 1

// Wait 500ms (the fake delay)
// "myFunction" isn't called (as delay hasn't been reached) but we do get the
// latest result

throttled(1); // 2

// Wait for 5 seconds
// "myFunction" is called but the old cached value has expired so it resolves
// with the new value once the function has run

throttled(1); // 3

const conditional = throttle(myFunction, {
    delay: 2000,
    maxAge: 5000
    onCached: function(item) {
        // Only cache results for large values of input
        if (item.key < 10)
            item.clear();
    }
}

conditional(1); // 1
conditional(1); // 2
conditional(1); // 3

conditional(20); // 23
conditional(20); // 23

Contributing

If you have some issue or code you would like to add, feel free to open a Pull Request or Issue and we will look into it as soon as we can.

License

We are releasing this under a MIT License.

About us

If you would like to know more about us, be sure to have a look at our website, or our Twitter accounts @Ambassify, Sitebase, JorgenEvens.