async-throttle

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

• Features
• Installation
• Usage
• Configuration
• API Reference
• Error Handling
• Best Practices
• Examples
• TypeScript Support
• Browser Compatibility
• Contributing
• Changelog
• License

Features

• 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

Installation

You can install the package using npm:

npm install @mareers/async-throttle

Usage

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`;
    },
};
asyncThrottle.addToQueue(task);

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

console.log(asyncThrottle.currentStatus);

To clear the queue, use the clearQueue method:

asyncThrottle.clearQueue();

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

asyncThrottle.stop();

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.stop();
});
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}`));

Configuration

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

AsyncThrottle

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

Types

• 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 {
    asyncThrottle.addToQueue(task);
} 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.

Examples

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(`https://api.example.com/users/${userId}`);
    return response.data;
};

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

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');
    apiThrottle.stop();
});

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.

Contributing

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.

Changelog

See CHANGELOG.md for details on version history and updates.

License

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 () => {
        someDbOperation(connection);
    },
};

// 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.