@boredland/node-ts-cache 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: test and release
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22.x, 24.x]
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # tag=v5.5.0
+        with:
+          token: ${{ github.token }}
+          fetch-depth: 0
+      - name: setup node ${{ matrix.node-version }}
+        uses: actions/setup-node@dda4788290998366da86b6a4f497909644397bb2 # tag=v6.6.0
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      - run: npm i --prefer-offline
+      - run: npm run build
+      - run: npm run test

package/LICENSE.md

@@ -0,0 +1,23 @@
+# MIT License
+
+Copyright (c) 2022 ioki GmbH
+Copyright (c) 2022 Jonas Strassel
+Copyright (c) 2017 Himmet Avsar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# @boredland/node-ts-cache
+
+[![CI](https://github.com/boredland/node-ts-cache/actions/workflows/ci.yml/badge.svg)](https://github.com/boredland/node-ts-cache/actions/workflows/ci.yml)
+[![The MIT License](https://img.shields.io/npm/l/node-ts-cache.svg)](http://opensource.org/licenses/MIT)
+
+Simple and extensible caching module supporting decorators and multiple caching strategies.
+
+## Install
+
+```bash
+npm i @boredland/node-ts-cache
+```
+
+## Usage
+
+### Wrap your function calls with `withCacheFactory`
+
+Function wrapper factory for arbitrary functions. The cache key is calculated based on the parameters passed to the function.
+
+```ts
+import {
+  withCacheFactory,
+  CacheContainer,
+  LRUStorage,
+} from "@boredland/node-ts-cache";
+
+const doThingsCache = new CacheContainer(new LRUStorage());
+
+const someFn = (input: { a: string; b: number }) => Promise.resolve("result");
+
+const wrappedFn = withCacheFactory(doThingsCache)(someFn, {
+  prefix: "my-function",
+  strategy: "eager", // or "lazy" or "swr"
+});
+
+const result = await wrappedFn({ a: "lala", b: 123 });
+```
+
+### Caching Strategies
+
+The `withCache` wrapper supports three different caching strategies:
+
+#### Eager (Default)
+
+```ts
+const wrappedFn = withCacheFactory(cacheContainer)(someFn, {
+  strategy: "eager",
+});
+```
+
+- Cache is populated before returning the result
+- Expired items are removed and the function is called again
+
+#### Lazy
+
+```ts
+const wrappedFn = withCacheFactory(cacheContainer)(someFn, {
+  strategy: "lazy",
+});
+```
+
+- Cache is populated in the background after returning the result
+- Expired items are invalidated on touch (when accessed)
+
+#### Stale-While-Revalidate (SWR)
+
+```ts
+const wrappedFn = withCacheFactory(cacheContainer)(someFn, {
+  strategy: "swr",
+});
+```
+
+- Returns expired cache immediately while revalidating in the background
+- Revalidation is queued with configurable concurrency
+- Perfect for scenarios where stale data is acceptable
+- Only one concurrent revalidation is enqueued per cache-key
+
+### Advanced Options
+
+```ts
+const wrappedFn = withCacheFactory(cacheContainer)(someFn, {
+  prefix: "my-function", // Cache key prefix
+  strategy: "swr", // Caching strategy
+  ttl: 60000, // Time-to-live in milliseconds (null = forever)
+  revalidationConcurrency: 5, // Max concurrent background revalidations (default: 1)
+  calculateKey: (params) => {
+    // Custom key calculation
+    return `${params[0]}-${params[1]}`;
+  },
+  shouldStore: (result) => {
+    // Conditional caching
+    return result && result.success;
+  },
+});
+```
+
+### Using `getItem` and `setItem` directly
+
+```ts
+import { CacheContainer, LRUStorage } from "@boredland/node-ts-cache";
+
+const myCache = new CacheContainer(new LRUStorage({ max: 1000 }));
+
+class MyService {
+  public async getUsers(): Promise<string[]> {
+    const cachedUsers = await myCache.getItem<string[]>("users");
+
+    if (cachedUsers) {
+      return cachedUsers.content;
+    }
+
+    const newUsers = ["Max", "User"];
+
+    await myCache.setItem("users", newUsers, { ttl: 60000 });
+
+    return newUsers;
+  }
+}
+```
+
+### LRUStorage
+
+The `LRUStorage` adapter uses an in-memory LRU (Least Recently Used) cache with configurable capacity:
+
+```ts
+import { LRUStorage } from "@boredland/node-ts-cache";
+
+// Create an LRU cache with max 10,000 items
+const storage = new LRUStorage({ max: 10000 });
+
+const container = new CacheContainer(storage);
+```
+
+**Features:**
+
+- In-memory caching with automatic eviction
+- LRU eviction policy when capacity is reached
+- Configurable maximum size
+- Perfect for testing and single-process applications
+
+## Logging
+
+This project uses `debug` to log useful information.
+Set environment variable **DEBUG=node-ts-cache** to enable logging.
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Example Test Usage
+
+For a complete example of how to test with `LRUStorage`, see the [comprehensive test suite](./src/lruStorage.test.ts):
+
+## LICENSE
+
+Distributed under the MIT License. See LICENSE.md for more information.
+
+## Development & Testing
+
+### Setup
+
+```bash
+cd node-ts-cache
+npm i
+npm run build
+npm test
+npm run lint
+```
+
+### Commands
+
+- `npm test` - Run test suite with Vitest
+- `npm run lint` - Run TypeScript and Biome linting
+- `npm run build` - Build the project
+
+## Credits
+
+As this is a fork of the original [node-ts-cache](https://github.com/havsar/node-ts-cache), all credit goes to the upstream project by [havsar](https://github.com/havsar).
+
+Structural changes have been made by [boredland](https://github.com/boredland) in order to align more with their use-case.
+
+Project Link: [https://github.com/boredland/node-ts-cache](https://github.com/boredland/node-ts-cache)

package/biome.json

@@ -0,0 +1,50 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.3.4/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"files": {
+		"ignoreUnknown": false
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab"
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"correctness": {
+				"useImportExtensions": "error",
+				"noUnsafeOptionalChaining": "error"
+			},
+			"suspicious": {
+				"noConsole": "error"
+			},
+			"nursery": {
+				"noFloatingPromises": "error",
+				"noMisusedPromises": "error"
+			},
+			"style": {
+				"noUnusedTemplateLiteral": "error",
+				"noProcessEnv": "error",
+				"useThrowNewError": "error"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "double"
+		}
+	},
+	"assist": {
+		"enabled": true,
+		"actions": {
+			"source": {
+				"organizeImports": "on"
+			}
+		}
+	}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@boredland/node-ts-cache",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boredland/node-ts-cache.git"
+  },
+  "license": "ISC",
+  "private": false,
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest",
+    "lint": "tsc && biome check --fix --no-errors-on-unmatched",
+    "prepublishOnly": "npm run build && npm run test -- --run"
+  },
+  "devDependencies": {
+    "lru-cache": "^11.2.2",
+    "node-object-hash": "^3.1.1",
+    "p-queue": "^9.0.0",
+    "vitest": "^4.0.8",
+    "@biomejs/biome": "2.3.4",
+    "@types/node": "^24.10.0",
+    "tsdown": "^0.16.0",
+    "typescript": "^5.9.3"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "module": "./dist/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./*": "./*"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/renovate.json

@@ -0,0 +1,37 @@
+{
+	"automerge": true,
+	"enabled": true,
+	"extends": [
+		":pinDependencies",
+		":dependencyDashboard",
+		":semanticPrefixFixDepsChoreOthers",
+		":semanticCommits",
+		"group:monorepos",
+		"group:recommended",
+		"workarounds:all",
+		"helpers:pinGitHubActionDigests"
+	],
+	"labels": ["dependency"],
+	"lockFileMaintenance": {
+		"automerge": true,
+		"enabled": true
+	},
+	"major": {
+		"dependencyDashboardApproval": true
+	},
+	"npm": {
+		"enabled": true
+	},
+	"github-actions": {
+		"enabled": true
+	},
+	"packageRules": [
+		{
+			"automerge": true,
+			"automergeStrategy": "squash",
+			"matchUpdateTypes": ["digest", "minor", "patch", "pin"]
+		}
+	],
+	"prConcurrentLimit": 1,
+	"semanticCommits": "enabled"
+}

package/src/cacheContainer.ts

@@ -0,0 +1,90 @@
+import { debug } from "./debug.ts";
+import type { Storage } from "./storage.ts";
+
+export type CachedItem<T = unknown> = {
+	content: T;
+	meta: {
+		createdAt: number;
+		ttl: number | null;
+		isLazy: boolean;
+	};
+};
+
+export type CachingOptions = {
+	/** Number of milliseconds to expire the cachte item - defaults to forever */
+	ttl: number | null;
+	/** (Default: true) If true, expired cache entries will be deleted on touch and returned anyway. If false, entries will be deleted after the given ttl. */
+	isLazy: boolean;
+	/** (Default: JSON.stringify combination of className, methodName and call args) */
+	calculateKey: (data: {
+		/** The class name for the method being decorated */
+		className: string;
+		/** The method name being decorated */
+		methodName: string;
+		/** The arguments passed to the method when called */
+		args: unknown[];
+	}) => string;
+};
+
+export class CacheContainer {
+	constructor(private storage: Storage) {}
+
+	public async getItem<T>(
+		key: string,
+	): Promise<
+		{ content: T; meta: { expired: boolean; createdAt: number } } | undefined
+	> {
+		const item = await this.storage.getItem(key);
+
+		if (!item) return;
+
+		const result = {
+			content: item.content as T,
+			meta: {
+				createdAt: item.meta.createdAt,
+				expired: this.isItemExpired(item),
+			},
+		};
+
+		if (result.meta.expired) await this.unsetKey(key);
+
+		if (result.meta.expired && !item.meta.isLazy) return undefined;
+
+		return result;
+	}
+
+	public async setItem(
+		key: string,
+		content: unknown,
+		options?: Partial<CachingOptions>,
+	): Promise<void> {
+		const finalOptions = {
+			ttl: null,
+			isLazy: true,
+			...options,
+		};
+
+		const meta: CachedItem<typeof content>["meta"] = {
+			createdAt: Date.now(),
+			isLazy: finalOptions.isLazy,
+			ttl: finalOptions.ttl,
+		};
+
+		await this.storage.setItem(key, { meta, content });
+	}
+
+	public async clear(): Promise<void> {
+		await this.storage.clear();
+
+		debug("Cleared cache");
+	}
+
+	private isItemExpired(item: CachedItem): boolean {
+		if (item.meta.ttl === null) return false;
+		return Date.now() > item.meta.createdAt + item.meta.ttl;
+	}
+
+	public async unsetKey(key: string): Promise<void> {
+		await this.storage.removeItem(key);
+	}
+}

package/src/debug.ts

@@ -0,0 +1,3 @@
+import { debug as _debug } from "node:util";
+
+export const debug = _debug("node-ts-cache");

package/src/hash.ts

@@ -0,0 +1,15 @@
+import { hasher } from "node-object-hash";
+
+/**
+ * Hash function for creating consistent, deterministic hashes from JavaScript objects.
+ * Used primarily for generating cache keys and ensuring object equality checks.
+ *
+ * @param obj - Any JavaScript object to hash
+ * @returns String hash of the object
+ */
+const { hash } = hasher({
+	sort: true, // Ensures consistent order for object properties
+	coerce: true, // Converts values to a consistent type (e.g., numbers to strings)
+});
+
+export default hash;

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./cacheContainer.ts";
+export * from "./lruStorage.ts";
+export * from "./storage.ts";
+export * from "./withCache.ts";

package/src/lruStorage.test.ts

@@ -0,0 +1,613 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { CacheContainer } from "./cacheContainer.ts";
+import { LRUStorage } from "./lruStorage.ts";
+import { withCacheFactory } from "./withCache.ts";
+
+describe("LRUStorage with withCache", () => {
+  let storage: LRUStorage;
+  let container: CacheContainer;
+  let withCache: ReturnType<typeof withCacheFactory>;
+
+  beforeEach(() => {
+    storage = new LRUStorage({ max: 10 });
+    container = new CacheContainer(storage);
+    withCache = withCacheFactory(container);
+  });
+
+  describe("Basic caching functionality", () => {
+    it("should cache function results", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn);
+
+      const result1 = await cachedFn(5);
+      const result2 = await cachedFn(5);
+
+      expect(result1).toBe(10);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+
+    it("should differentiate between different parameters", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn);
+
+      const result1 = await cachedFn(5);
+      const result2 = await cachedFn(10);
+
+      expect(result1).toBe(10);
+      expect(result2).toBe(20);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+
+    it("should use custom calculateKey function", async () => {
+      const mockFn = vi.fn(async (x: number, y: number) => x + y);
+      const cachedFn = withCache(mockFn, {
+        calculateKey: ([x, y]) => `${x}-${y}`,
+      });
+
+      const result1 = await cachedFn(1, 2);
+      const result2 = await cachedFn(1, 2);
+
+      expect(result1).toBe(3);
+      expect(result2).toBe(3);
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+
+    it("should support prefix option", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn1 = withCache(mockFn, { prefix: "version1" });
+      const cachedFn2 = withCache(mockFn, { prefix: "version2" });
+
+      const result1 = await cachedFn1(5);
+      const result2 = await cachedFn2(5);
+
+      expect(result1).toBe(10);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+
+    it("should work with multiple parameters", async () => {
+      const mockFn = vi.fn(async (a: number, b: string) => `${a}-${b}`);
+      const cachedFn = withCache(mockFn);
+
+      const result1 = await cachedFn(1, "a");
+      const result2 = await cachedFn(1, "a");
+
+      expect(result1).toBe("1-a");
+      expect(result2).toBe("1-a");
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+  });
+
+  describe("TTL and expiration", () => {
+    it("should cache items with TTL in eager mode", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn, { ttl: 100, strategy: "eager" });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Item should still be cached before expiration
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Wait for expiration
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // After expiration, item is removed and function is called again
+      const result3 = await cachedFn(5);
+      expect(result3).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+
+    it("should use lazy strategy to invalidate cache on touch", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn, { ttl: 100, strategy: "lazy" });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Item should be cached for one subsequent call
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Wait for expiration
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // After expiration, the cached item is stale, but should be returned
+      const result3 = await cachedFn(5);
+      expect(result3).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Next call should have invalidated the cache and call the function again
+      const result4 = await cachedFn(5);
+      expect(result4).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+
+    it("should use swr strategy to return stale cache and revalidate in background", async () => {
+      const mockFn = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 2;
+      });
+      const cachedFn = withCache(mockFn, { ttl: 100, strategy: "swr" });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Item should be cached
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Wait for expiration
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // With swr strategy, expired items are returned immediately
+      const result3 = await cachedFn(5);
+      expect(result3).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+      // The stale cache is returned, but revalidation is queued in background
+      // Wait a bit for background revalidation to complete
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+  });
+
+  describe("shouldStore option", () => {
+    it("should not cache when shouldStore returns false", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn, {
+        shouldStore: (result: unknown) => (result as number) > 15,
+      });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+
+    it("should cache when shouldStore returns true", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn, {
+        shouldStore: (result: unknown) => (result as number) > 5,
+      });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+
+    it("should evaluate shouldStore on complex results", async () => {
+      const mockFn = vi.fn(async (x: number) => ({
+        value: x * 2,
+        success: x > 0,
+      }));
+      const cachedFn = withCache(mockFn, {
+        shouldStore: (result: unknown) =>
+          (result as { success: boolean }).success,
+      });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toEqual({ value: 10, success: true });
+
+      const result2 = await cachedFn(5);
+      expect(result2).toEqual({ value: 10, success: true });
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+  });
+
+  describe("LRU eviction", () => {
+    it("should evict least recently used items when max capacity is reached", async () => {
+      // Create storage with small capacity
+      const smallStorage = new LRUStorage({ max: 3 });
+      const smallContainer = new CacheContainer(smallStorage);
+      const smallWithCache = withCacheFactory(smallContainer);
+
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = smallWithCache(mockFn);
+
+      // Fill cache to capacity
+      await cachedFn(1); // key1
+      await cachedFn(2); // key2
+      await cachedFn(3); // key3
+
+      expect(mockFn).toHaveResolvedTimes(3);
+
+      // Access all three to verify they're cached
+      await cachedFn(1);
+      await cachedFn(2);
+      await cachedFn(3);
+      expect(mockFn).toHaveResolvedTimes(3);
+
+      // Add a new item, which should evict the least recently used
+      await cachedFn(4); // This should evict key1 (least recently used)
+
+      expect(mockFn).toHaveResolvedTimes(4);
+
+      // key1 should be evicted and function should be called again
+      await cachedFn(1);
+      expect(mockFn).toHaveResolvedTimes(5);
+    });
+
+    it("should keep recently accessed items in cache", async () => {
+      const smallStorage = new LRUStorage({ max: 2 });
+      const smallContainer = new CacheContainer(smallStorage);
+      const smallWithCache = withCacheFactory(smallContainer);
+
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = smallWithCache(mockFn);
+
+      await cachedFn(1);
+      await cachedFn(2);
+      expect(mockFn).toHaveResolvedTimes(2);
+
+      // Access 1 again to make it recently used
+      await cachedFn(1);
+      expect(mockFn).toHaveResolvedTimes(2);
+
+      // Add 3, should evict 2 (not 1)
+      await cachedFn(3);
+      expect(mockFn).toHaveResolvedTimes(3);
+
+      // 1 should still be cached
+      await cachedFn(1);
+      expect(mockFn).toHaveResolvedTimes(3);
+
+      // 2 should have been evicted
+      await cachedFn(2);
+      expect(mockFn).toHaveResolvedTimes(4);
+    });
+  });
+
+  describe("Clear and removal", () => {
+    it("should clear all cache entries", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn);
+
+      await cachedFn(1);
+      await cachedFn(2);
+      expect(mockFn).toHaveResolvedTimes(2);
+
+      // Clear cache
+      await container.clear();
+
+      // Should call function again
+      await cachedFn(1);
+      await cachedFn(2);
+      expect(mockFn).toHaveResolvedTimes(4);
+    });
+
+    it("should remove individual cache entries", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      // Create a named function so we know the function name
+      const namedAsyncFn = Object.defineProperty(mockFn, "name", {
+        value: "testFn",
+      }) as unknown as (x: number) => Promise<number>;
+
+      const cachedFn = withCache(namedAsyncFn, {
+        calculateKey: ([x]) => `custom-key-${x}`,
+      });
+
+      await cachedFn(5);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Manually remove the key - must include the function name and prefix
+      // The key format is: ${operation.name}:${prefix}:${calculateKeyResult}
+      const fullKey = "testFn:default:custom-key-5";
+      await container.unsetKey(fullKey);
+
+      // Should call function again
+      await cachedFn(5);
+      expect(mockFn).toHaveResolvedTimes(2);
+    });
+  });
+
+  describe("Complex scenarios", () => {
+    it("should handle multiple concurrent calls", async () => {
+      const mockFn = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 2;
+      });
+      const cachedFn = withCache(mockFn);
+
+      const results = await Promise.all([
+        cachedFn(5),
+        cachedFn(5),
+        cachedFn(5),
+      ]);
+
+      expect(results).toEqual([10, 10, 10]);
+      expect(mockFn).toHaveResolvedTimes(3);
+    });
+
+    it("should handle different data types", async () => {
+      const mockFn = vi.fn(async (data: Record<string, string>) => ({
+        received: data,
+        timestamp: Date.now(),
+      }));
+      const cachedFn = withCache(mockFn);
+
+      const result1 = await cachedFn({ name: "test" });
+      const result2 = await cachedFn({ name: "test" });
+
+      // Verify both results are the same object (cached)
+      expect(result1).toBe(result2);
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+
+    it("should combine multiple cache options", async () => {
+      const mockFn = vi.fn(async (x: number) => x * 2);
+      const cachedFn = withCache(mockFn, {
+        prefix: "combined",
+        ttl: 100,
+        strategy: "lazy",
+        shouldStore: (result: unknown) => (result as number) > 5,
+      });
+
+      const result1 = await cachedFn(5);
+      expect(result1).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      const result2 = await cachedFn(5);
+      expect(result2).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      const result3 = await cachedFn(5);
+      expect(result3).toBe(10);
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+  });
+
+  describe("Storage operations", () => {
+    it("should correctly store and retrieve items", async () => {
+      const key = "test-key";
+      const content = { value: "test", number: 123 };
+
+      await storage.setItem(key, {
+        content,
+        meta: {
+          createdAt: Date.now(),
+          ttl: null,
+          isLazy: true,
+        },
+      });
+
+      const retrieved = await storage.getItem(key);
+      expect(retrieved?.content).toEqual(content);
+    });
+
+    it("should remove items from storage", async () => {
+      const key = "test-key";
+      const content = { value: "test" };
+
+      await storage.setItem(key, {
+        content,
+        meta: {
+          createdAt: Date.now(),
+          ttl: null,
+          isLazy: true,
+        },
+      });
+
+      await storage.removeItem(key);
+
+      const retrieved = await storage.getItem(key);
+      expect(retrieved).toBeUndefined();
+    });
+
+    it("should clear all storage items", async () => {
+      const key1 = "key1";
+      const key2 = "key2";
+
+      await storage.setItem(key1, {
+        content: "value1",
+        meta: {
+          createdAt: Date.now(),
+          ttl: null,
+          isLazy: true,
+        },
+      });
+
+      await storage.setItem(key2, {
+        content: "value2",
+        meta: {
+          createdAt: Date.now(),
+          ttl: null,
+          isLazy: true,
+        },
+      });
+
+      await storage.clear();
+
+      const result1 = await storage.getItem(key1);
+      const result2 = await storage.getItem(key2);
+
+      expect(result1).toBeUndefined();
+      expect(result2).toBeUndefined();
+    });
+  });
+
+  describe("Error handling", () => {
+    it("should not cache errors", async () => {
+      const mockFn = vi.fn(async (x: number) => {
+        if (x < 0) throw new Error("Negative number");
+        return x * 2;
+      });
+      const cachedFn = withCache(mockFn);
+
+      const result = await cachedFn(5);
+      expect(result).toBe(10);
+
+      await expect(cachedFn(-5)).rejects.toThrow("Negative number");
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("Concurrency limiting in revalidation queue", () => {
+    it("should limit concurrent revalidations to revalidationConcurrency in swr mode", async () => {
+      const mockFn = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 2;
+      });
+
+      const cachedFn = withCache(mockFn, {
+        ttl: 100,
+        strategy: "swr",
+        revalidationConcurrency: 1,
+      });
+
+      // Prime the cache
+      await cachedFn(5);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Wait for expiration so cache is stale
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Track concurrent execution count
+      let maxConcurrent = 0;
+      let currentConcurrent = 0;
+      const originalImpl = mockFn.getMockImplementation();
+
+      mockFn.mockImplementation(async (x: number) => {
+        currentConcurrent++;
+        maxConcurrent = Math.max(maxConcurrent, currentConcurrent);
+        // biome-ignore lint/style/noNonNullAssertion: we're sure it is here
+        const result = await originalImpl!(x);
+        currentConcurrent--;
+        return result;
+      });
+
+      // Trigger multiple revalidations
+      const results = await Promise.all([
+        cachedFn(5),
+        cachedFn(5),
+        cachedFn(5),
+      ]);
+
+      // wait until all would have been called
+      await new Promise((resolve) => setTimeout(resolve, 450));
+
+      expect(results).toEqual([10, 10, 10]);
+      // With concurrency: 1, should never have more than 1 concurrent revalidation
+      expect(maxConcurrent).toBe(1);
+      expect(mockFn).toHaveBeenCalledTimes(2);
+    });
+
+    it("should only queue revalidations in swr strategy when cache is expired", async () => {
+      const mockFn = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 2;
+      });
+
+      const cachedFn = withCache(mockFn, {
+        ttl: 100,
+        strategy: "swr",
+        revalidationConcurrency: 1,
+      });
+
+      // Prime the cache
+      await cachedFn(5);
+      expect(mockFn).toHaveResolvedTimes(1);
+
+      // Track concurrent execution count
+      let maxConcurrent = 0;
+      let currentConcurrent = 0;
+      const originalImpl = mockFn.getMockImplementation();
+
+      mockFn.mockImplementation(async (x: number) => {
+        currentConcurrent++;
+        maxConcurrent = Math.max(maxConcurrent, currentConcurrent);
+        // biome-ignore lint/style/noNonNullAssertion: we're sure it is here
+        const result = await originalImpl!(x);
+        currentConcurrent--;
+        return result;
+      });
+
+      // Call while cache is still valid - should NOT queue revalidation
+      const results = await Promise.all([
+        cachedFn(5),
+        cachedFn(5),
+        cachedFn(5),
+      ]);
+
+      expect(results).toEqual([10, 10, 10]);
+      // Since cache is not expired, no revalidation should be queued
+      // Function should only be called once (initial call)
+      expect(mockFn).toHaveResolvedTimes(1);
+    });
+
+    it("should use concurrency limit per unique cache key", async () => {
+      const mockFn1 = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 2;
+      });
+
+      const mockFn2 = vi.fn(async (x: number) => {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return x * 3;
+      });
+
+      const cachedFn1 = withCache(mockFn1, {
+        ttl: 100,
+        strategy: "swr",
+        revalidationConcurrency: 1,
+        prefix: "fn1",
+      });
+
+      const cachedFn2 = withCache(mockFn2, {
+        ttl: 100,
+        strategy: "swr",
+        revalidationConcurrency: 1,
+        prefix: "fn2",
+      });
+
+      // Prime both caches
+      await cachedFn1(5);
+      await cachedFn2(5);
+      expect(mockFn1).toHaveResolvedTimes(1);
+      expect(mockFn2).toHaveResolvedTimes(1);
+
+      // Wait for expiration
+      await new Promise((resolve) => setTimeout(resolve, 150));
+
+      // Track concurrent execution for each
+      let maxConcurrent1 = 0;
+      let currentConcurrent1 = 0;
+      const originalImpl1 = mockFn1.getMockImplementation();
+
+      mockFn1.mockImplementation(async (x: number) => {
+        currentConcurrent1++;
+        maxConcurrent1 = Math.max(maxConcurrent1, currentConcurrent1);
+        // biome-ignore lint/style/noNonNullAssertion: we're sure it is here
+        const result = await originalImpl1!(x);
+        currentConcurrent1--;
+        return result;
+      });
+
+      // Trigger revalidations for both functions concurrently
+      const results = await Promise.all([
+        cachedFn1(5),
+        cachedFn1(5),
+        cachedFn2(5),
+        cachedFn2(5),
+      ]);
+
+      expect(results).toEqual([10, 10, 15, 15]);
+      // Each function's queue should limit its own concurrency
+      expect(maxConcurrent1).toBe(1);
+    });
+  });
+});

package/src/lruStorage.ts

@@ -0,0 +1,32 @@
+import { LRUCache } from "lru-cache";
+import type { CachedItem } from "./cacheContainer.ts";
+import type { Storage } from "./storage.ts";
+
+export class LRUStorage implements Storage {
+	private cache: LRUCache<string, CachedItem, unknown>;
+
+	constructor({
+		max = 10_000,
+	}: Partial<LRUCache<string, CachedItem, unknown>> = {}) {
+		this.cache = new LRUCache<string, CachedItem, unknown>({
+			max,
+		});
+	}
+
+	async clear(): Promise<void> {
+		this.cache.clear();
+	}
+
+	async getItem(key: string) {
+		const item = this.cache.get(key);
+		return item;
+	}
+
+	async setItem(key: string, content: CachedItem) {
+		this.cache.set(key, content);
+	}
+
+	async removeItem(key: string) {
+		this.cache.delete(key);
+	}
+}

package/src/storage.ts

@@ -0,0 +1,27 @@
+import type { CachedItem } from "./cacheContainer.ts";
+
+export interface Storage {
+	/**
+	 * returns a cached item from the storage layer
+	 * @param key - key to look up
+	 */
+	getItem(key: string): Promise<CachedItem | undefined>;
+
+	/**
+	 * sets a cached item on the storage layer
+	 * @param key - key to store
+	 * @param content - content to store, including some meta data
+	 */
+	setItem(key: string, content: CachedItem): Promise<void>;
+
+	/**
+	 * removes item from the storage layer
+	 * @param key - key to remove
+	 */
+	removeItem(key: string): Promise<void>;
+
+	/**
+	 * remove all keys from the storage layer
+	 */
+	clear(): Promise<void>;
+}

package/src/withCache.ts

@@ -0,0 +1,110 @@
+import PQueue from "p-queue";
+import type { CacheContainer, CachingOptions } from "./cacheContainer.ts";
+import hash from "./hash.ts";
+
+const revalidationQueues: Record<string, PQueue> = {};
+
+type WithCacheOptions<Parameters, Result> = Partial<
+  Omit<CachingOptions, "calculateKey" | "isLazy">
+> & {
+  /** an optional prefix to prepend to the key */
+  prefix?: string;
+  /** an optional function to calculate a key based on the parameters of the wrapped function */
+  calculateKey?: (input: Parameters) => string;
+  /** an optional function that is called just before the result is stored to the storage */
+  shouldStore?: (result: Awaited<Result>) => boolean;
+  /**
+   * caching strategy to use
+   * - "lazy": cache is populated in the background after returning the result
+   * - "swr": stale-while-revalidate, cache is returned if present and updated in the background
+   * - "eager": cache is populated before returning the result
+   * @default "eager"
+   */
+  strategy?: "lazy" | "swr" | "eager";
+  /**
+   * Concurrency for revalidation queue
+   * @default 1
+   */
+  revalidationConcurrency?: number;
+};
+
+/**
+ * wrapped function factory
+ * @param container - cache container to create the fn for
+ * @returns wrapping function
+ */
+export const withCacheFactory = (container: CacheContainer) => {
+  /**
+   * function wrapper
+   * @param operation - the function to be wrapped
+   * @param options - caching options
+   * @returns wrapped operation
+   */
+  const withCache = <
+    Parameters extends Array<unknown>,
+    Result extends Promise<unknown>,
+  >(
+    operation: (...parameters: Parameters) => Result,
+    options: WithCacheOptions<Parameters, Result> = {},
+  ) => {
+    return async (...parameters: Parameters): Promise<Result> => {
+      const {
+        calculateKey,
+        strategy = "eager",
+        revalidationConcurrency: concurrency = 1,
+        ...rest
+      } = options;
+      const prefix = options.prefix ?? "default";
+      const key = `${operation.name}:${prefix}:${
+        calculateKey ? calculateKey(parameters) : hash(parameters)
+      }` as const;
+
+      const queueName = `${operation.name}:${prefix}` as const;
+
+      revalidationQueues[queueName] =
+        revalidationQueues[queueName] ??
+        new PQueue({
+          concurrency,
+        });
+      revalidationQueues[queueName].concurrency = concurrency;
+
+      const cachedResponse = await container.getItem<Awaited<Result>>(key);
+
+      const refreshedItem = async () => {
+        const result = await operation(...parameters);
+        if (!options.shouldStore || options.shouldStore(result)) {
+          await container.setItem(key, result, {
+            ...rest,
+            isLazy: strategy === "lazy" || strategy === "swr",
+          });
+        }
+        return result;
+      };
+
+      /**
+       * Stale-While-Revalidate strategy
+       * If the cached response is expired, we return it immediately and
+       * revalidate in the background
+       */
+      if (strategy === "swr" && cachedResponse?.meta.expired) {
+        if (
+          !revalidationQueues[queueName].runningTasks.some(
+            (t) => t.id === key && t.startTime,
+          )
+        ) {
+          revalidationQueues[queueName].add(refreshedItem, {
+            id: key,
+          });
+        }
+      }
+
+      if (cachedResponse) {
+        return cachedResponse.content;
+      }
+
+      const result = await refreshedItem();
+      return result;
+    };
+  };
+  return withCache;
+};

package/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    "noEmit": true,
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "target": "ES2022",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+
+    "allowImportingTsExtensions": true
+  }
+}

package/tsdown.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  exports: {
+    all: true,
+  },
+  minify: true,
+  platform: "node",
+});