docs(cache): invalidation using ocache (#4216)

Author: RihanArfan

docs/1.docs/7.cache.md

@@ -328,7 +328,58 @@ When `swr` is disabled and a cached value has expired:
 1. The stale entry is cleared.
 2. The client waits for the function/handler to resolve with a fresh value.
 
-## Cache keys and invalidation
+## Cache invalidation
+
+Cached entries can be invalidated programmatically at runtime (for example from a webhook when the underlying data changes) without waiting for `maxAge` to expire.
+
+### `.invalidate()` method
+
+Every function created with `defineCachedFunction` exposes an `.invalidate()` method. Arguments are passed through `getKey` to generate the cache key.
+
+```ts
+import { defineCachedFunction } from "nitro/cache";
+
+const cachedGHStars = defineCachedFunction(async (repo: string) => {
+  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());
+  return data.stargazers_count;
+}, {
+  maxAge: 60 * 60,
+  name: "ghStars",
+  getKey: (repo: string) => repo,
+});
+
+await cachedGHStars("unjs/nitro"); // populates the cache
+await cachedGHStars.invalidate("unjs/nitro"); // removes the entry
+await cachedGHStars("unjs/nitro"); // re-invokes the function
+```
+
+If no cached entry matches the given arguments, `.invalidate()` resolves without error and leaves storage unchanged.
+
+### `invalidateCache()` helper
+
+`invalidateCache` is a helper from `ocache`. It invalidates a cached entry from the cache options used to define it, so invalidation can live anywhere in your app, independent of where the cached function is defined.
+
+Pass the same `name`, `group`, `base`, and `getKey` used when defining the function, along with the `args` identifying the entry to remove:
+
+```ts
+import { invalidateCache } from "ocache";
+
+await invalidateCache({
+  options: {
+    name: "ghStars",
+    group: "nitro/functions",
+    getKey: (repo: string) => repo,
+  },
+  args: ["unjs/nitro"],
+});
+```
+
+::important
+The `name`, `group`, `base`, and `getKey` passed to `invalidateCache` must match the ones used when the cached function was defined. Mismatched options resolve to a different storage key and will not invalidate the intended entry. :br :br
+Nitro defaults to `group: 'nitro/functions'` for cached functions and `group: 'nitro/handlers'` for cached handlers (or `'nitro/route-rules'` when using [route rules](#using-route-rules)).
+::
+
+## Cache keys
 
 When using the `defineCachedFunction` or `defineCachedHandler` functions, the cache key is generated using the following pattern:
 
@@ -356,13 +407,6 @@ Will generate the following cache key:
 cache:nitro/functions:getAccessToken:default.json
 ```
 
-You can invalidate the cached function entry with:
-
-```ts
-import { useStorage } from "nitro/storage";
-
-await useStorage('cache').removeItem('nitro/functions:getAccessToken:default.json')
-```
 
 ::note
 For cached handlers, the cache key includes a hash of the URL path and, when using the [`varies`](#handler-only-options) option, hashes of the specified header values appended to the key.