diff --git a/README.md b/README.md index f8ff96c..ef79a36 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,39 @@ -# package +# batcher -A template to create new packages. +A simpler batcher for any async function + +## Installation + +```bash +npm install @edgefirst-dev/batcher +``` + +## Usage + +```typescript +import { Batcher } from "@edgefirst-dev/batcher"; + +// Configure the time window for the batcher +// The batcher will call the async function only once for the same key in this time window +let batcher = new Batcher(10); + +async function asyncFunction(): Promise { + await new Promise((resolve) => setTimeout(resolve, 1000)); + return { value: "ok" }; +} + +let [result1, result2] = await Promise.all([ + batcher.call(["my", "custom", "key"], asyncFunction), + batcher.call(["my", "custom", "key"], asyncFunction), +]); + +console.log(result1 === result2); // true +``` + +The batcher will call the async function only once for the same key, and return the same promise for all calls with the same key. This way, if the function returns an object all calls will resolve with the same object that can be compared by reference. + +> [!TIP] +> Use this batcher in Remix or React Router applications to batch async function calls in your loaders so you can avoid multiple queries or fetches for the same data. ## What to do after cloning this repository diff --git a/bun.lockb b/bun.lockb index ff2e49e..52c292b 100755 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/package.json b/package.json index 12ba188..c2137e9 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "package-name", + "name": "@edgefirst-dev/batcher", "version": "0.0.0", - "description": "A description of the package", + "description": "A simpler batcher for any async function", "license": "MIT", "funding": ["https://github.com/sponsors/sergiodxa"], "author": { @@ -11,11 +11,11 @@ }, "repository": { "type": "git", - "url": "https://github.com/sergiodxa/package" + "url": "https://github.com/edgefirst-dev/batcher" }, - "homepage": "https://sergiodxa.github.io/package", + "homepage": "https://edgefirst-dev.github.io/batcher", "bugs": { - "url": "https://github.com/sergiodxa/package/issues" + "url": "https://github.com/edgefirst-dev/batcher/issues" }, "scripts": { "build": "tsc", @@ -34,16 +34,18 @@ ".": "./build/index.js", "./package.json": "./package.json" }, - "dependencies": {}, + "dependencies": { + "type-fest": "^4.33.0" + }, "peerDependencies": {}, "devDependencies": { - "@arethetypeswrong/cli": "^0.17.2", + "@arethetypeswrong/cli": "^0.17.3", "@biomejs/biome": "^1.9.4", "@total-typescript/tsconfig": "^1.0.4", - "@types/bun": "^1.1.14", - "consola": "^3.3.3", + "@types/bun": "^1.2.1", + "consola": "^3.4.0", "typedoc": "^0.27.6", - "typedoc-plugin-mdn-links": "^4.0.6", - "typescript": "^5.7.2" + "typedoc-plugin-mdn-links": "^4.0.10", + "typescript": "^5.7.3" } } diff --git a/src/index.test.ts b/src/index.test.ts index cbd4959..a577767 100644 --- a/src/index.test.ts +++ b/src/index.test.ts @@ -1,7 +1,35 @@ -import { expect, test } from "bun:test"; +import { expect, mock, test } from "bun:test"; -import { doSomething } from "."; +import { Batcher } from "."; -test(doSomething.name, () => { - expect(() => doSomething()).toThrowError("Not implemented yet"); +test("calls the function once per key", async () => { + let fn = mock(); + let batcher = new Batcher(10); + + let times = Math.floor(Math.random() * 100) + 1; + + await Promise.all( + Array.from({ length: times }).map(() => { + return batcher.call(["key"], fn); + }), + ); + + expect(fn).toHaveBeenCalledTimes(1); +}); + +test("caches results and return the same value", async () => { + let batcher = new Batcher(10); + + let [value1, value2] = await Promise.all([ + batcher.call(["key"], async () => { + await new Promise((resolve) => setTimeout(resolve, 5)); + return { key: "value" }; + }), + batcher.call(["key"], async () => { + await new Promise((resolve) => setTimeout(resolve, 5)); + return { key: "value" }; + }), + ]); + + expect(value1).toBe(value2); }); diff --git a/src/index.ts b/src/index.ts index 45b7145..624b005 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,82 @@ -export function doSomething() { - throw new Error("Not implemented yet"); +import type { Jsonifiable } from "type-fest"; + +/** + * This is our batcher implementation. It is a class that allows us to batch + * function calls that are identical within a certain time window. This is + * useful for reducing API calls to external services, for example. + * + * The Batcher class has a cache property that stores the results of the + * function calls. It also has a timeouts property that stores the timeouts + * for each function call. The batchWindow property is the time window in + * milliseconds that we use to batch the function calls. + * + * The call method takes an array of values as key and an async function fn. + * It converts the key to a string and stores it in the cache. If the cache + * already has the key, it returns the cached value. Otherwise, it creates a + * new promise and sets a timeout for the function call. When the timeout + * expires, the function is called and the result is resolved. If an error + * occurs, the promise is rejected. Finally, the timeout is removed from the + * timeouts property. + * + * @example + * let batcher = new Batcher(10); + * let [value1, value2] = await Promise.all([ + * batcher.call(["key"], async () => { + * await new Promise((resolve) => setTimeout(resolve, 5)); + * return { key: "value" } + * }), + * batcher.call(["key"], async () => { + * await new Promise((resolve) => setTimeout(resolve, 5)); + * return { key: "value" } + * }), + * ]) + * console.log(value1 === value2); // true + */ +export class Batcher { + protected readonly cache = new Map>(); + protected readonly timeouts = new Map(); + + /** + * Creates a new instance of the Batcher. + * @param batchWindow The time window (in milliseconds) to batch function calls. + */ + constructor(protected batchWindow?: number) {} + + /** + * Calls a function with batching, ensuring multiple identical calls within a time window execute only once. + * @template TArgs The argument types. + * @template TResult The return type. + * @param fn The async function to batch. + * @param key An array of values used for deduplication. + * @returns A promise that resolves with the function result. + */ + call( + key: Key[], + fn: () => Promise, + ): Promise { + let cacheKey = JSON.stringify(key); + + if (this.cache.has(cacheKey)) { + return this.cache.get(cacheKey) as Promise; + } + + let promise = new Promise((resolve, reject) => { + let timeout = setTimeout(async () => { + try { + let result = await fn(); + resolve(result); + } catch (error) { + reject(error); + } finally { + this.timeouts.delete(cacheKey); + } + }, this.batchWindow); + + this.timeouts.set(cacheKey, timeout); + }); + + this.cache.set(cacheKey, promise); + + return promise; + } }