Implement revalidatePath functionality for the App Router (#460)

Author: better-salmon

.changeset/long-sheep-play.md

@@ -0,0 +1,29 @@
+---
+'@neshca/cache-handler': minor
+---
+
+Add `revalidatePath` functionality.
+
+#### New Features
+
+##### `@neshca/cache-handler`
+
+- add `implicitTags` parameter to the `get` method for Handlers
+- remove implicit tags filtration for the `PAGE` kind cache values
+
+##### `@neshca/cache-handle/local-lru`
+
+- implement `revalidatePath` functionality
+
+##### `@neshca/cache-handle/redis-stack`
+
+- implement `revalidatePath` functionality
+
+##### `@neshca/cache-handle/redis-strings`
+
+- implement `revalidatePath` functionality
+- refactor `revalidateTag` method to use `HSCAN` instead of `HGETALL`
+
+##### `@neshca/cache-handle/helpers`
+
+- add `isImplicitTag` and `getTimeoutRedisCommandOptions` functions

.changeset/tricky-cobras-pull.md

@@ -0,0 +1,5 @@
+---
+'@neshca/server': minor
+---
+
+Add support for the new `implicitTags` parameter.

README.md

@@ -8,8 +8,7 @@ Welcome to [**`@neshca/cache-handler`**](./packages/cache-handler/README.md), a
 
 ### Next.js Routers support
 
-- Full support for Pages Router.
-- Almost full support for App Router. The only exception is the [`revalidatePath`](https://github.com/caching-tools/next-shared-cache/issues/382) function.
+- Full support for the Pages and the App Router.
 
 ### The importance of shared cache in distributed environments
 

apps/cache-testing/tests/app.spec.ts

@@ -36,13 +36,37 @@ test.describe('On-demand revalidation', () => {
         });
     }
 
+    for (const path of paths) {
+        test(`If revalidate by path is clicked, then page should be fresh after reload ${path}`, async ({
+            page,
+            baseURL,
+        }) => {
+            const url = new URL(path, `${baseURL}:3000`);
+
+            await page.goto(url.href);
+
+            await refreshPageCache(page, 'path');
+
+            const valueFromPage = Number.parseInt((await page.getByTestId('data').innerText()).valueOf(), 10);
+
+            await refreshPageCache(page, 'path');
+
+            await expect(page.getByTestId('cache-state')).toContainText('fresh');
+
+            const valueFromPageAfterReload = Number.parseInt(
+                (await page.getByTestId('data').innerText()).valueOf(),
+                10,
+            );
+
+            expect(valueFromPageAfterReload - valueFromPage === 1).toBe(true);
+        });
+    }
+
     for (const path of paths) {
         test(`If revalidate by path is clicked on page A, then page B should be fresh on load ${path}`, async ({
             context,
             baseURL,
         }) => {
-            test.fail(true, 'This test is failing because of revalidate by path is not supported yet.');
-
             const appAUrl = new URL(path, `${baseURL}:3000`);
 
             const appA = await context.newPage();

docs/cache-handler-docs/src/pages/api-reference/handler.mdx

@@ -21,6 +21,7 @@ A descriptive name for the cache Handler. This is used to identify the cache Han
 #### Parameters
 
 - `key` - The unique string identifier for the cache entry.
+- `implicitTags` - An array of tags that are implicitly associated with the cache entry.
 
 #### Return value
 

docs/cache-handler-docs/src/pages/index.mdx

@@ -2,8 +2,7 @@ Welcome to `@neshca/cache-handler`, a specialized ISR/Data cache API crafted for
 
 ### Next.js Routers support
 
-- Full support for Pages Router.
-- Almost full support for App Router. The only exception is the [`revalidatePath`](https://github.com/caching-tools/next-shared-cache/issues/382) function.
+- Full support for the Pages and the App Router.
 
 ### The importance of shared cache in distributed environments
 

docs/cache-handler-docs/src/pages/usage/creating-a-custom-handler.mdx

@@ -18,6 +18,7 @@ Create a file called `cache-handler.mjs` next to your `next.config.js` with the
 
 ```js filename="cache-handler.mjs" copy
 import { CacheHandler } from '@neshca/cache-handler';
+import { isImplicitTag } from '@neshca/cache-handler/helpers';
 import createLruHandler from '@neshca/cache-handler/local-lru';
 import { createClient, commandOptions } from 'redis';
 
@@ -30,6 +31,8 @@ CacheHandler.onCreation(async () => {
   // Ignore Redis errors: https://github.com/redis/node-redis?tab=readme-ov-file#events.
   client.on('error', () => {});
 
+  await client.connect();
+
   // Define a timeout for Redis operations.
   const timeoutMs = 1000;
 
@@ -51,14 +54,16 @@ CacheHandler.onCreation(async () => {
     }
   }
 
+  const revalidatedTagsKey = `${keyPrefix}__revalidated_tags__`;
+
   // Create a custom Redis Handler
   const customRedisHandler = {
     // Give the handler a name.
     // It is useful for logging in debug mode.
     name: 'redis-strings-custom',
     // We do not use try/catch blocks in the Handler methods.
     // CacheHandler will handle errors and use the next available Handler.
-    async get(key) {
+    async get(key, implicitTags) {
       // Ensure that the client is ready before using it.
       // If the client is not ready, the CacheHandler will use the next available Handler.
       assertClientIsReady();
@@ -77,7 +82,43 @@ CacheHandler.onCreation(async () => {
       }
 
       // Redis stores strings, so we need to parse the JSON.
-      return JSON.parse(result);
+      const cacheValue = JSON.parse(result);
+
+      // If the cache value has no tags, return it early.
+      if (!cacheValue) {
+        return null;
+      }
+
+      // Get the set of explicit and implicit tags.
+      // implicitTags are available only on the `get` method.
+      const combinedTags = new Set([...cacheValue.tags, ...implicitTags]);
+
+      // If there are no tags, return the cache value early.
+      if (combinedTags.size === 0) {
+        return cacheValue;
+      }
+
+      // Get the revalidation times for the tags.
+      const revalidationTimes = await client.hmGet(
+        commandOptions({ signal: AbortSignal.timeout(timeoutMs) }),
+        revalidatedTagsKey,
+        Array.from(combinedTags),
+      );
+
+      // Iterate over all revalidation times.
+      for (const timeString of revalidationTimes) {
+        // If the revalidation time is greater than the last modified time of the cache value,
+        if (timeString && Number.parseInt(timeString, 10) > cacheValue.lastModified) {
+          // Delete the key from Redis.
+          await client.unlink(commandOptions({ signal: AbortSignal.timeout(timeoutMs) }), keyPrefix + key);
+
+          // Return null to indicate cache miss.
+          return null;
+        }
+      }
+
+      // Return the cache value.
+      return cacheValue;
     },
     async set(key, cacheHandlerValue) {
       // Ensure that the client is ready before using it.
@@ -99,9 +140,7 @@ CacheHandler.onCreation(async () => {
       // If the cache handler value has tags, set the tags.
       // We store them separately to save time to retrieve them in the `revalidateTag` method.
       const setTagsOperation = cacheHandlerValue.tags.length
-        ? client.hSet(options, keyPrefix + sharedTagsKey, {
-            [key]: JSON.stringify(cacheHandlerValue.tags),
-          })
+        ? client.hSet(options, keyPrefix + sharedTagsKey, key, JSON.stringify(cacheHandlerValue.tags))
         : undefined;
 
       // Wait for all operations to complete.
@@ -111,27 +150,55 @@ CacheHandler.onCreation(async () => {
       // Ensure that the client is ready before using it.
       assertClientIsReady();
 
-      // Create a new AbortSignal with a timeout for the Redis operation.
-      const getOptions = commandOptions({ signal: AbortSignal.timeout(timeoutMs) });
+      // Check if the tag is implicit.
+      // Implicit tags are not stored in the cached values.
+      if (isImplicitTag(tag)) {
+        // Mark the tag as revalidated at the current time.
+        await client.hSet(
+          commandOptions({ signal: AbortSignal.timeout(timeoutMs) }),
+          revalidatedTagsKey,
+          tag,
+          Date.now(),
+        );
+      }
+
+      // Create a map to store the tags for each key.
+      const tagsMap = new Map();
 
-      // Get all keys and their tags from Redis from the hash map we've created in the `set` method.
-      const remoteTags = await client.hGetAll(getOptions, keyPrefix + sharedTagsKey);
+      // Cursor for the hScan operation.
+      let cursor = 0;
 
-      // Create a map from the tags.
-      const tagsMap = new Map(Object.entries(remoteTags));
+      // Query size for the hScan operation.
+      const querySize = 25;
+
+      // Iterate over all keys in the shared tags.
+      while (true) {
+        // Get a portion of the keys.
+        const remoteTagsPortion = await client.hScan(keyPrefix + sharedTagsKey, cursor, { COUNT: querySize });
+
+        // Iterate over all keys in the portion.
+        for (const { field, value } of remoteTagsPortion.tuples) {
+          // Parse the tags from the value.
+          tagsMap.set(field, JSON.parse(value));
+        }
+
+        // If the cursor is 0, we have reached the end.
+        if (remoteTagsPortion.cursor === 0) {
+          break;
+        }
+
+        // Update the cursor for the next iteration.
+        cursor = remoteTagsPortion.cursor;
+      }
 
       // Create an array of keys to delete.
       const keysToDelete = [];
 
       // Create an array of tags to delete form the hash map.
       const tagsToDelete = [];
 
-      // Iterate over all keys and their tags.
-      for (const [key, tagsString] of tagsMap) {
-        // In the set method, we store tags as a stringified array.
-        // So, we need to parse it back to an array.
-        const tags = JSON.parse(tagsString);
-
+      // Iterate over all keys and tags.
+      for (const [key, tags] of tagsMap) {
         // If the tags include the specified tag, add the key to the delete list.
         if (tags.includes(tag)) {
           // Key must be prefixed because we use the key prefix in the set method.

docs/cache-handler-docs/src/pages/usage/on-demand-revalidation.mdx

@@ -6,12 +6,22 @@ Next.js provides a way to revalidate a page or a result of a `fetch` call on dem
 
 ### Pages Router
 
-The Pages Router supports only the `revalidatePath` option.
+The Pages Router supports only the `response.revalidate(path)`.
 
 See [Using On-Demand Revalidation](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration#using-on-demand-revalidation) in the Next.js documentation.
 
+#### `response.revalidate(path)` caveat
+
+Calling `response.revalidate(path)` will synchronously call `getStaticProps` and render the page with a given `path`. Then it will revalidate the cache for this page. If you want to revalidate multiple paths at once, you need to call `response.revalidate(path)` multiple times.
+
 ### App Router
 
-The App Router supports both `revalidatePath` and `revalidateTag` functions. However due to current limitations, `revalidatePath` is disabled for the App Router.
+The App Router supports both `revalidatePath` and `revalidateTag` functions. These functions will remove the cache values from the store.
 
 See [On-demand Revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation) in the Next.js documentation.
+
+#### `revalidatePath` caveat
+
+The `revalidatePath` function works differently from the `response.revalidate(path)` and `revalidateTag` functions. It does not revalidate the cached `fetch` result immediately. Instead, it marks the cache as revalidated and the next request will revalidate the cache.
+
+If you are creating a custom cache Handler, you need to manually mark the cache as revalidated in Handler's `revalidateTag` method. Later in the Handler's `get` method, you must check if the cache is revalidated and return `null` if necessary. See [Custom Redis strings example](/usage/creating-a-custom-handler#guide)

docs/cache-handler-docs/theme.config.jsx

@@ -53,10 +53,10 @@ export default {
         ),
     },
     banner: {
-        key: 'version-1.0.0',
+        key: 'version-1.1.0',
         text: (
             <a href="https://nextjs.org/blog/next-14-1">
-                🎉 1.0.0 is out! It features an improved API and TTL by default.
+                🎉 1.1.0 is out! It features Full support for the App Router!
             </a>
         ),
     },

internal/next-common/src/next-common.ts

@@ -110,3 +110,5 @@ export type TagsManifest = {
     version: 1;
     items: Record<string, { revalidatedAt: number }>;
 };
+
+export const NEXT_CACHE_IMPLICIT_TAG_ID = '_N_T_';