reqoal

A lightweight and efficient JavaScript/TypeScript library for request coalescing — merge concurrent identical async calls into a single request to reduce load and improve performance.

Features

• Coalesce concurrent or repeated calls for the same function and arguments
• Supports both async and sync functions
• Caches results for a configurable TTL
• Periodically prunes expired cache entries (automatic memory management)
• Manual cache invalidation and pruning
• Custom key generator for advanced cache strategies
• Concurrency limit per instance
• ESM & CJS compatible
• TypeScript-first, with full type safety

Installation

npm install reqoal

Usage

Global Instance (Simple)

import { coalesce, isCoalesced, invalidate, clear, prune, setKeyGenerator } from 'reqoal';

// Async or sync function
async function fetchUser(id) {
	/* ... */
}
function add(a, b) {
	return a + b;
}

// Coalesce requests
const user = await coalesce(fetchUser, 123);
const sum = await coalesce(add, 1, 2); // works with sync too!

// Check if a request is in-flight or cached
const active = isCoalesced(fetchUser, 123);

// Invalidate cache for a specific call
invalidate(fetchUser, 123);

// Clear all cache and in-flight requests
clear();

// Manually prune expired cache entries (optional)
prune();

// Set a custom key generator (advanced)
setKeyGenerator((functionName, ...args) => `${functionName}:${args.join('-')}`);

Custom Instance (Advanced)

import { ReqoalInstance } from 'reqoal';

const coalescer = new ReqoalInstance(
	60000, // prune interval (ms)
	1000, // TTL (ms)
	console, // custom logger
	5, // max concurrency
);

await coalescer.coalesce(fetchUser, 123);
coalescer.setKeyGenerator((functionName, ...args) => `${functionName}:${args.join('-')}`);

API

Global Exports

• coalesce(fn, ...args) — Coalesce and cache requests
• isCoalesced(fn, ...args) — Check if a request is in-flight or cached
• invalidate(fn, ...args) — Invalidate cache for a specific call
• clear() — Clear all cache and in-flight requests
• prune() — Manually prune expired cache entries
• setKeyGenerator(fn) — Set a custom key generator

ReqoalInstance

• new ReqoalInstance(intervalMs?, ttlMs?, consoler?, maxConcurrency?)
• .coalesce(fn, ...args)
• .isCoalesced(fn, ...args)
• .invalidate(fn, ...args)
• .clear()
• .prune()
• .setKeyGenerator(fn)

ESM & CJS Compatibility

• ESM: import { coalesce } from 'reqoal'
• CJS: const { coalesce } = require('reqoal')

License

MIT

Links

• GitHub Repository
• Documentation
• Report Issues