feat: add shouldInvalidateCache option to cache utils

docs/content/1.guide/1.introduction/5.cache.md

@@ -11,13 +11,13 @@ const cachedFn = cachedEventHandler(fn, options)
 
 ### Options
 
-- `name`: Handler name. It will be guessed from function name if not provided and fallback to `_` otherwise.
-- `group`: Part of cache name. Useful to organize cache storage.
-- `getKey`: A function that accepts same arguments of normal function and should generate cache key. If not provided, a built-in hash function will be used.
-- `integrity`: A value that changing it, will invalidate all caches for function. By default will be computed from **function code**.
-- `maxAge`: Maximum age that cache is valid in seconds. Default is `1` second.
-- `swr`: Enable Stale-While-Revalidate behavior. Enabled by default.
-
+* `name`: Handler name. It will be guessed from function name if not provided and fallback to `_` otherwise.
+* `group`: Part of cache name. Useful to organize cache storage.
+* `getKey`: A function that accepts same arguments of normal function and should generate cache key. If not provided, a built-in hash function will be used.
+* `integrity`: A value that changing it, will invalidate all caches for function. By default will be computed from **function code**.
+* `maxAge`: Maximum age that cache is valid in seconds. Default is `1` second.
+* `swr`: Enable Stale-While-Revalidate behavior. Enabled by default.
+* `shouldInvalidateCache`: A function that returns a boolean to invalidate the current cache and create a new one.
 
 ## Examples
 
@@ -26,31 +26,38 @@ const cachedFn = cachedEventHandler(fn, options)
 ```js
 // routes/cached.ts
 const myFn = cachedEventHandler(async () => {
-  new Promise(resolve => setTimeout(resolve, 1000))
-  return `Response generated at ${new Date().toISOString()}`
-}, { swr: true })
+    new Promise(resolve => setTimeout(resolve, 1000))
+    return `Response generated at ${new Date().toISOString()}`
+}, {
+    swr: true
+})
 ```
 
 **Example:** Cache a utility function
 
 ```js
 // utils/index.ts
 const myFn = cachedFunction(async () => {
-  new Promise(resolve => setTimeout(resolve, 1000))
-  return Math.random()
-}, { swr: true })
+    new Promise(resolve => setTimeout(resolve, 1000))
+    return Math.random()
+}, {
+    swr: true
+})
 ```
 
-
 **Example:** Enable Cache on a group of routes (**🧪 Experimental!**)
 
 ```js
 // nitro.config.ts
-import { defineNitroConfig } from 'nitropack'
+import {
+    defineNitroConfig
+} from 'nitropack'
 
 export default defineNitroConfig({
-  routeRules: {
-    '/blog/**': { swr: true }
-  }
+    routeRules: {
+        '/blog/**': {
+            swr: true
+        }
+    }
 })
 ```

src/runtime/cache.ts

@@ -21,6 +21,7 @@ export interface CacheOptions<T = any> {
   getKey?: (...args: any[]) => string;
   transform?: (entry: CacheEntry<T>, ...args: any[]) => any;
   validate?: (entry: CacheEntry<T>) => boolean;
+  shouldInvalidateCache?: (...args: any[]) => boolean;
   group?: string;
   integrity?: any;
   maxAge?: number;
@@ -53,7 +54,8 @@ export function defineCachedFunction<T = any>(
 
   async function get(
     key: string,
-    resolver: () => T | Promise<T>
+    resolver: () => T | Promise<T>,
+    shouldInvalidateCache?: boolean
   ): Promise<CacheEntry<T>> {
     // Use extension for key to avoid conflicting with parent namespace (foo/bar and foo/bar/baz)
     const cacheKey = [opts.base, group, name, key + ".json"]
@@ -69,6 +71,7 @@ export function defineCachedFunction<T = any>(
     }
 
     const expired =
+      shouldInvalidateCache ||
       entry.integrity !== integrity ||
       (ttl && Date.now() - (entry.mtime || 0) > ttl) ||
       !validate(entry);
@@ -107,7 +110,8 @@ export function defineCachedFunction<T = any>(
 
   return async (...args) => {
     const key = (opts.getKey || getKey)(...args);
-    const entry = await get(key, () => fn(...args));
+    const shouldInvalidateCache = opts.shouldInvalidateCache?.(...args);
+    const entry = await get(key, () => fn(...args), shouldInvalidateCache);
     let value = entry.value;
     if (opts.transform) {
       value = (await opts.transform(entry, ...args)) || value;
@@ -130,6 +134,7 @@ export interface ResponseCacheEntry<T = any> {
 
 export interface CachedEventHandlerOptions<T = any>
   extends Omit<CacheOptions<ResponseCacheEntry<T>>, "transform" | "validate"> {
+  shouldInvalidateCache?: (event: H3Event) => boolean;
   getKey?: (event: H3Event) => string;
   headersOnly?: boolean;
 }