feat(lru-cache): support options and fetchMethod

docs/2.drivers/lru-cache.md

@@ -24,3 +24,26 @@ const storage = createStorage({
   driver: lruCacheDriver(),
 });
 ```
+
+## Stale while revalidate
+
+LRU cache allows you to easily create a `stale-while-revalidate` storage.
+
+```ts
+const staleWhileRevalidateStorage = createStorage({
+  driver: driver({
+    max: 100,
+    ttl: 1000 * 60 * 15, // 15 minutes
+    allowStale: true,
+    fetchMethod: async (key, value, options) => {
+      const data = await fetch("https://your.api.com/endpoint?query${key}");
+      return data;
+    },
+  }),
+});
+
+const data = await staleWhileRevalidateStorage.get("my-search-result");
+```
+
+That approach will invoke API call maximum once per 15 minutes and will return cached values. Additionally after 15 minutes it will return stale value and will trigger API call in the background to update the cache.
+It allows you for great performance and user experience when the accuracy of the returned data is not critical.

src/drivers/lru-cache.ts

@@ -15,7 +15,7 @@ export default defineDriver((opts: LRUDriverOptions = {}) => {
     max: 1000,
     sizeCalculation:
       opts.maxSize || opts.maxEntrySize
-        ? (value, key: string) => {
+        ? (value: unknown, key: string) => {
             return key.length + byteLength(value);
           }
         : undefined,
@@ -29,11 +29,13 @@ export default defineDriver((opts: LRUDriverOptions = {}) => {
     hasItem(key) {
       return cache.has(key);
     },
-    getItem(key) {
-      return cache.get(key) ?? null;
+    async getItem(key, options) {
+      const storageResult = await cache.fetch(key, options);
+      return storageResult ?? null;
     },
-    getItemRaw(key) {
-      return cache.get(key) ?? null;
+    async getItemRaw(key, options) {
+      const storageResult = await cache.fetch(key, options);
+      return storageResult ?? null;
     },
     setItem(key, value) {
       cache.set(key, value);

test/drivers/lru-cache.test.ts

@@ -1,6 +1,7 @@
-import { it, describe, expect } from "vitest";
+import { it, describe, expect, vi, beforeEach, afterEach } from "vitest";
 import driver from "../../src/drivers/lru-cache";
 import { testDriver } from "./utils";
+import { createStorage } from "../../src";
 
 describe("drivers: lru-cache", () => {
   testDriver({
@@ -27,3 +28,62 @@
     },
   });
 });
+
+describe("drivers: lru-cache with TTL and stale-while-revalidate cache", () => {
+  it("should get the value from the fetchMethod and then from cache", async () => {
+    const fetchMethodTestSpy = vi.fn();
+    const storage = createStorage({
+      driver: driver({
+        max: 10,
+        ttl: 50,
+        allowStale: true,
+        fetchMethod: async (key, value, options) => {
+          fetchMethodTestSpy(key, value);
+          return "ourTestValue";
+        },
+      }),
+    });
+
+    const value = await storage.getItem("test");
+    expect(value).toBe("ourTestValue");
+    const secondCheck = await storage.getItem("test");
+    expect(secondCheck).toBe("ourTestValue");
+
+    expect(fetchMethodTestSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("[stale-while-revalidate] should return cached value while refreshing for the new value", async () => {
+    const fetchMethodTestSpy = vi.fn();
+    const storage = createStorage({
+      driver: driver({
+        max: 10,
+        ttl: 50,
+        allowStale: true,
+        fetchMethod: async (key, value, options) => {
+          fetchMethodTestSpy(key, value);
+          // first time when there is no cached value we return the first string
+          if (!value) {
+            return "stale-test-value";
+          }
+          return "stale-test-value-after-revalidate";
+        },
+      }),
+    });
+
+    // first time we're invoking the fetchMethod and get value from it
+    const firstRead = await storage.getItem("stale-test-key");
+    expect(firstRead).toBe("stale-test-value");
+
+    // when TTL expired we're still getting the value from the cache and it's refreshed under the hood
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const secondRead = await storage.getItem("stale-test-key");
+    expect(secondRead).toBe("stale-test-value");
+
+    // the next read after that should return refreshed value
+    const thirdRead = await storage.getItem("stale-test-key");
+    expect(thirdRead).toBe("stale-test-value-after-revalidate");
+
+    // fetchMethod should be called only twice - once on init and once after TTL expired
+    expect(fetchMethodTestSpy).toHaveBeenCalledTimes(2);
+  });
+});