Smart-batcher NPM

# smart-batcher

`smart-batcher` is a lightweight and powerful TypeScript utility for efficiently managing batched requests with integrated, configurable in-memory caching. It optimizes request handling by:

1.  **Batching:** Grouping multiple requests for the same resource type and processing them together, reducing redundant operations (like database queries).
2.  **Caching:** Storing results in a configurable in-memory cache to avoid repeated calls to your batch function for the same keys.
3.  **Events:** Emitting events when actions are executing.

It's ideal for scenarios like fetching data from a database or an external API where you want to minimize the number of requests.

## Installation

```bash
npm install smart-batcher

Usage

import SmartBatcher from "smart-batcher";

// 1. Define your batch function.  This function takes an array of
//    STRING keys and returns a Promise that resolves to an array of results.
//    The results array MUST be the same length as the keys array, and the
//    results MUST be in the same order as the keys.  If a key cannot be
//    found, return null at the corresponding index.  If an error occurs,
//    return an Error object at the corresponding index.
const batchFunction = async (ids: string[]): Promise<(string | Error | null)[]> => {
    console.log("batchFunction called with ids:", ids);
    // Simulate fetching data from a database or API.
    const results = ids.map(id => {
        if (id === "error") {
            return new Error("Simulated batch function error");
        }
        if (id === "missing") {
          return null; // Simulate a missing item
        }
        return `Data for ${id}`;
    });
    return results;
};

// 2. Create a SmartBatcher instance.
const batcher = new SmartBatcher(batchFunction, {
    delay: 50,         // Optional: Wait 50ms before executing the batch (default: 0 - setImmediate)
    memoryLimitMB: 10,  // Optional: Cache size limit in MB (default: 1024)
    expirationTime: 0, // Optional: Cache expiration time in ms (default: 0 - no expiration)
});

// 3. Use the batcher to load data.
async function fetchData() {
    const promise1 = batcher.load("id1");
    const promise2 = batcher.load("id2");
    const promise3 = batcher.load("id3");

    // Fetch same data: Will get in cache.
    const promise4 = batcher.load("id1");

    // Example with error
    const promise5 = batcher.load("error");
    // Example with missing
    const promise6 = batcher.load("missing");


    console.log(await promise1); // Output: Data for id1
    console.log(await promise2); // Output: Data for id2
    console.log(await promise3); // Output: Data for id3
    console.log(await promise4); // Output: Data for id1 (from cache!)
    await promise5.catch(err => console.error(err));  //Output Error: Simulated batch function error
    await promise6.catch(err => console.error(err)) // Output Error: Not found: missing

    // Using loadMany
    const results = await batcher.loadMany(["id4", "id5", "id1", "error"]);
    console.log(results); // Output: ['Data for id4', 'Data for id5', 'Data for id1', Error: Simulated batch function error]
    const results2 = await batcher.loadMany(["id4", "id5", "id1", "error"]); //Output: [ 'Data for id4', 'Data for id5', 'Data for id1', Error: Simulated batch function error] (id4 and id5 from cache)
}

fetchData();

// Clear the cache
async function clear() {
  await batcher.clearCache();
  console.log("Cache cleared");
}
//clear();

API

`new SmartBatcher<T>(batchFunction, options?)`

Creates a new SmartBatcher instance.

batchFunction: (keys: string[]) => Promise<(T | Error | null)[]> (required)
An asynchronous function that takes an array of string keys and returns a promise that resolves to an array of results. The result array must have the same length as the input keys array, and the results must be in the same order.
- If a value for a key is found, put the value at the corresponding index in the result array.
- If a value for a key is not found, put null at the corresponding index.
- If an error occurs while fetching a particular key, put an Error object at the corresponding index.
- If an error occurs that prevents any keys from being fetched (e.g., a database connection error), it's recommended to reject the promise returned by batchFunction with that error. The SmartBatcher will then reject all pending load and loadMany calls with that error.
options: { delay?: number; memoryLimitMB?: number; expirationTime?: number; } (optional)
- delay?: number: The time, in milliseconds, to wait before executing the batch function. This delay allows multiple load calls made in quick succession to be grouped into a single batch. Defaults to 0, which means the batch is executed on the next tick of the event loop using setImmediate.
- memoryLimitMB?: number: The maximum size of the in-memory cache, in megabytes. Defaults to 1024 (1GB). If adding a new value to the cache would exceed this limit, an error will be thrown, and the value will not be cached. Existing cached values are not evicted; the limit only applies to new additions.
- expirationTime?: number: The time, in milliseconds, after which a cached value is considered expired and will be removed from the cache. Defaults to 0, which means cached values do not expire.

`.load(key: string): Promise<T>`

Loads a single value by its key.

key: string (required): The key of the value to load. Keys must be strings.

Returns a promise that:

Resolves with the value if it's found (either from the cache or the batch function).
Rejects with an Error if the batch function returns an Error for that key, if the batch function throws an error, or if there is a cache error.

`.loadMany(keys: string[]): Promise<(T | Error)[]>`

Loads multiple values by their keys.

keys: string[] (required): An array of string keys.

Returns a promise that resolves to an array of results. Each element in the result array will be either:

The value associated with the corresponding key (if found).
An Error object if the batch function returned an error for that key, or the batch function throws an error.

`.clearCache(): Promise<void>`

Clears the entire in-memory cache. Returns a promise that resolves when the cache is cleared.

`.setValue(key: string, value: T): Promise<Record<string, T>>`

Sets value into cache

key (string): The key to associate with the value.
value (T): The value to be stored.
Return: Promise<Record<string, T>>

`.getValue(key: string): Promise<T | undefined>`

get value from cache.

key (string): The key to get.
Return: Promise<T | undefined>

`.deleteValue(key: string): Promise<Record<string, T>>`

Delete value.

key (string): The key to delete.
Return: Promise<Record<string, T>>

`.has(key: string): Promise<boolean>`

Check whether a key in cache.

key (string): The key to check
Return: Promise

`.restartAllValues(): Promise<Record<string, T>>`

Reset All Cache

Return: Promise<Record<string, T>>

Events

The SmartBatcher class extends EventEmitter and emits the following events:

setValue: Emitted when a value is successfully set in the cache. The event data is an object: { key: string, value: T }.
getValue: Emitted when get value in cache. The event data is an object: { key: string, value: T | undefined }.
deleteValue: Emitted when a value is deleted. The event data is an object: { key: string, deletedValue: T }.
expiredValue: Emitted when a value is expired. The event data is an object: { key: string }.
deleteAlls: Emitted when clear all cache. The event data is an object: Record<string, T>.
has: Emitted check exits key in cache. The event data is an object: {key: string, exists: boolean}.

You can listen to these events using the standard on method:

batcher.on('setValue', ({key, value}) => {
    console.log(`Cached value for key '${key}':`, value);
});

Error Handling

smart-batcher handles errors robustly:

Batch Function Errors: If the batchFunction returns an Error object for a specific key, the load or loadMany promise for that key will reject with that error.
Batch Function Throws: If the batchFunction itself throws an error, all pending load and loadMany promises will reject with that error.
Cache Errors: If an error occurs while interacting with the cache (e.g., during get or setValue), the load promise will reject with that error.
Not Array: If your batchFunction return not an array, all promises in load and loadMany will reject with an Error("batchFunction must return an array").