You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



A TypeScript library for managing and executing asynchronous functions with constraints and logging capabilities.

Version published
Weekly downloads
decreased by-25.53%
Weekly downloads




A TypeScript library for managing and executing asynchronous functions with constraints and logging capabilities. async-throttle helps you control the concurrent execution of asynchronous tasks, making it easier to manage resource usage and prevent overwhelming external services.

Table of Contents


  • Control concurrent execution of asynchronous tasks
  • Set delays between execution cycles
  • Event-based monitoring of task execution and queue status
  • TypeScript support with type definitions
  • Flexible configuration options


You can install the package using npm:

npm install @mareers/async-throttle


Import the AsyncThrottle class and the TAsyncThrottleFunction type from the package:

import { AsyncThrottle, TAsyncThrottleFunction } from '@mareers/async-throttle';

Create an instance of AsyncThrottle with the desired options:

const asyncThrottle = new AsyncThrottle({
    maxThreshold: 3,
    delayExecutions: 1000,

Add functions to the queue using the addToQueue method:

const task: TAsyncThrottleFunction<[number, number], string> = {
    args: [1, 2000],
    function: async (taskId: number, delay: number) => {
        await new Promise((resolve) => setTimeout(resolve, delay));
        return `Task ${taskId} completed`;

You can check the current status of the queue using the currentStatus getter:


To clear the queue, use the clearQueue method:


To stop the async throttle execution, call the stop method:


Async Throttle provides a bunch of events to listen to:

asyncThrottle.on('result', (res) => console.log(`RESULT: ${JSON.stringify(res)}`));
asyncThrottle.on('resultError', (res) => console.log(`RESULT_ERROR: ${JSON.stringify(res)}`));
asyncThrottle.on('empty', () => {
asyncThrottle.on('add', () => {
    // do when something is added
asyncThrottle.on('stop', () => {
    console.log(`Execution stopped`);
asyncThrottle.on('clear', () => {
    console.log(`Queue cleared`);
asyncThrottle.on('log', (message) => console.log(`LOG: ${message}`));


The AsyncThrottle constructor accepts an options object with the following properties:

  • maxThreshold (required): The maximum number of tasks that can be executed concurrently.
  • delayExecutions (required): The delay (in milliseconds) between each execution loop.

Additional configuration options:

  • logLevel (optional): Set the logging level ('debug', 'info', 'warn', 'error'). Default: 'info'.
  • retryAttempts (optional): Number of retry attempts for failed tasks. Default: 0.
  • retryDelay (optional): Delay (in milliseconds) between retry attempts. Default: 1000.

API Reference


  • constructor(options: AsyncThrottleOptions)
  • addToQueue(task: TAsyncThrottleFunction<TArgs, TResponse>): void
  • clearQueue(): void
  • stop(): void
  • on(eventName: string, callback: Function): void
  • currentStatus: AsyncThrottleStatus


  • TAsyncThrottleFunction<TArgs extends Array<any>, TResponse>
  • AsyncThrottleOptions
  • AsyncThrottleStatus

Error Handling

async-throttle provides error handling through the resultError event. You can listen to this event to catch and handle any errors that occur during task execution:

asyncThrottle.on('resultError', (error) => {
    console.error('Task execution failed:', error);
    // Implement your error handling logic here

Additionally, you can use try-catch blocks when adding tasks to the queue to handle any synchronous errors that might occur:

try {
} catch (error) {
    console.error('Failed to add task to queue:', error);

Best Practices

  1. Choose appropriate maxThreshold and delayExecutions values based on your specific use case and the resources you're working with.
  2. Use TypeScript to leverage type checking and improve code quality.
  3. Implement proper error handling by listening to the resultError event.
  4. Clear the queue and stop the AsyncThrottle instance when it's no longer needed to free up resources.
  5. Consider using a factory function to create AsyncThrottle instances with consistent configuration across your application.


Real-world use case: Rate-limited API calls

import { AsyncThrottle, TAsyncThrottleFunction } from '@mareers/async-throttle';
import axios from 'axios';

const apiThrottle = new AsyncThrottle({
    maxThreshold: 5, // Maximum 5 concurrent API calls
    delayExecutions: 1000, // 1 second delay between execution cycles

const fetchUserData = async (userId: number): Promise<any> => {
    const response = await axios.get(`${userId}`);

// Add multiple API calls to the queue
for (let i = 1; i <= 20; i++) {
    const task: TAsyncThrottleFunction<[number], any> = {
        args: [i],
        function: fetchUserData,

apiThrottle.on('result', (result) => {
    console.log('User data fetched:', result);

apiThrottle.on('resultError', (error) => {
    console.error('Failed to fetch user data:', error);

apiThrottle.on('empty', () => {
    console.log('All API calls completed');

TypeScript Support

async-throttle is written in TypeScript and provides type definitions out of the box. This ensures type safety when using the library in your TypeScript projects.

Browser Compatibility

async-throttle is primarily designed for use in Node.js environments. While it may work in modern browsers that support ES6+ features, it has not been extensively tested for browser compatibility. If you need to use async-throttle in a browser environment, consider using a bundler like webpack or rollup to ensure compatibility.


Contributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request on the GitHub repository.


See for details on version history and updates.


This package is released under the MIT License.

Note: When working with database connections or other resources that may not be available when the function gets executed, use the following pattern:

import { createConnection } from 'your-database-library';

let connection = await createConnection({
    // Connection configuration

function someDbOperation(connection) {
    // some operation that uses db connection

// Do
const task: TAsyncThrottleFunction<[], string> = {
    args: [],
    function: async () => {

// Don't
const task2: TAsyncThrottleFunction<[], string> = {
    args: [connection], // Connection might not be available
    function: someDbOperation,

This ensures that the connection is accessed at the time of execution, rather than being passed as an argument that might become stale.



Package last updated on 19 Jul 2024

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc