async-throttle-cache

async-throttle-cache

Throttle or debounce asynchronous functions and return cached result for each function calls. It can be used for rate limit.

Installation

NPM

npm install async-throttle-cache --save

import asyncThrottleCache from 'async-throttle-cache';

Browser

Direct <script> include

<script src="https://cdn.jsdelivr.net/npm/async-throttle-cache"></script>

Usage

const throttleFn = asyncThrottleCache(fn[, wait = 0[, options = {
  key: (...args) => JSON.stringify(args),
  serialize: result => Promise.resolve(result),
  deserialize: result => Promise.resolve(result),
  debounce: undefined | true | false | { leading: true },
}]]);

Creates a throttled function that only invokes fn at most once per every wait milliseconds, and returns cached result.

You can specify how to generate cache key. Different cache key will re-invoke fn to get a new result.

serialize and deserialize is for cached result, they could be asynchronous functions.

debounce is for debounce mode, if true, fn will be invoked after wait time since last call.

For example, clone result for each time throttled function execution in 1000 milliseconds. It's useful when you tend to modify the result object.

const throttleFn = asyncThrottleCache(fn, 1000, {
  serialize: async result => JSON.stringify(result),
  deserialize: async result => JSON.parse(result),
});

Examples

// define a asynchronous function, return after 100ms
function fn(arg1, arg2) {
  return new Promise((resolve) => {
    setTimeout(() => resolve({
      arg1,
      arg2
    }), 100);
  });
}

const throttleFn150ms = asyncThrottleCache(fn, 150); // longer then function execution

(async () => {
  throttleFn150ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 100ms
  throttleFn150ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 100ms
  await throttleFn150ms(2, 2); // invoke,     return { arg1: 2, arg2: 2 } at 100ms
  await throttleFn150ms(2, 2); // from cache, return { arg1: 2, arg2: 2 } at 100ms
})();

const throttleFn50ms = asyncThrottleCache(fn, 50); // shorter then function execution

(async () => {
  throttleFn50ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 100ms
  throttleFn50ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 100ms
  await throttleFn50ms(2, 2); // invoke,     return { arg1: 2, arg2: 2 } at 100ms
  await throttleFn50ms(2, 2); // invoke,     return { arg1: 2, arg2: 2 } at 200ms
})();

const throttleFn150ms = asyncThrottleCache(fn, 150, {
  key: (arg1, arg2) => JSON.stringify(arg2), // uses arg2 as key
});

(async () => {
  throttleFn150ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 100ms
  throttleFn150ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 100ms
  await throttleFn150ms(2, 2); // from cache, return { arg1: 1, arg2: 2 } at 100ms
  await throttleFn150ms(2, 2); // from cache, return { arg1: 1, arg2: 2 } at 100ms
})();

const debounceFn250ms = asyncThrottleCache(fn, 250, {
  debounce: true,
});

(async () => {
  debounceFn250ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 350ms
  debounceFn250ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 350ms
  debounceFn250ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 750ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn250ms(2, 2);       // from cache, return { arg1: 2, arg2: 2 } at 750ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn250ms(2, 2);       // from cache, return { arg1: 2, arg2: 2 } at 750ms
})();

const debounceFn50ms = asyncThrottleCache(fn, 50, {
  debounce: true,
});

(async () => {
  debounceFn50ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 150ms
  debounceFn50ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 150ms
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 150ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 350ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 550ms
})();

const debounceFn250ms = asyncThrottleCache(fn, 250, {
  debounce: {
    leading: true,
  },
});

(async () => {
  debounceFn250ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 100ms
  debounceFn250ms(1, 2);       // from cache, return { arg1: 1, arg2: 2 } at 100ms
  debounceFn250ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 100ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn250ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 750ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn250ms(2, 2);       // from cache, return { arg1: 2, arg2: 2 } at 750ms
})();

const debounceFn50ms = asyncThrottleCache(fn, 50, {
  debounce: {
    leading: true,
  },
});

(async () => {
  debounceFn50ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 100ms
  debounceFn50ms(1, 2);       // invoke,     return { arg1: 1, arg2: 2 } at 150ms
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 100ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 300ms
  await new Promise((resolve) => setTimeout(resolve, 200));
  debounceFn50ms(2, 2);       // invoke,     return { arg1: 2, arg2: 2 } at 500ms
})();