Migrate to Vitest, refactor cache-handler API names

Author: better-salmon

.vscode/settings.json

@@ -7,10 +7,6 @@
   "typescript.surveys.enabled": false,
   "typescript.tsdk": "node_modules/typescript/lib",
   "explorer.fileNesting.enabled": true,
-  "explorer.fileNesting.patterns": {
-    "*.ts": "$(capture).test.ts, $(capture).test.tsx",
-    "*.tsx": "$(capture).test.ts, $(capture).test.tsx"
-  },
   "cSpell.words": ["nextjs", "prerendered", "codestyle"],
   "editor.defaultFormatter": "biomejs.biome",
   "[jsonc]": {

apps/cache-testing/package.json

@@ -6,7 +6,6 @@
   "type": "module",
   "scripts": {
     "build": "next build && tsx create-instances.ts",
-    "check-types": "tsc --noEmit",
     "cluster:start": "pm2 start cluster.config.js --env production",
     "cluster:stop": "pm2 kill",
     "e2e": "playwright test --config=./playwright.config.ts",

apps/cache-testing/run-app-instances.ts

@@ -2,7 +2,7 @@
 
 import { scheduler } from 'node:timers/promises';
 import Fastify from 'fastify';
-// biome-ignore lint/style/noNamespaceImport: pm2 works only with Namespace import
+// biome-ignore lint/style/noNamespaceImport: pm2 works only with namespace import
 import * as pm2Default from 'pm2';
 
 const { default: pm2 } = pm2Default as unknown as {

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

@@ -18,7 +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 { isTagImplicit } from '@neshca/cache-handler/helpers';
 import { createClient, commandOptions } from 'redis';
 
 CacheHandler.onCreation(async () => {
@@ -179,7 +179,7 @@ CacheHandler.onCreation(async () => {
 
       // Check if the tag is implicit.
       // Implicit tags are not stored in the cached values.
-      if (isImplicitTag(tag)) {
+      if (isTagImplicit(tag)) {
         // Mark the tag as revalidated at the current time.
         await client.hSet(
           commandOptions({ signal: AbortSignal.timeout(timeoutMs) }),

internal/typescript-config/test.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "Test",
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2023"],
+
+    "module": "NodeNext",
+    "moduleDetection": "force",
+    "esModuleInterop": true,
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "skipLibCheck": true,
+
+    "noEmit": true
+  }
+}

packages/cache-handler/package.json

@@ -24,16 +24,16 @@
   "type": "module",
   "exports": {
     ".": "./dist/cache-handler.js",
+    "./helpers/*": "./dist/helpers/*.js",
     "./handlers/*": "./dist/handlers/*.js",
-    "./helpers": "./dist/helpers/helpers.js",
     "./instrumentation/*": "./dist/instrumentation/*.js"
   },
   "scripts": {
     "build": "tsc",
     "check-types": "tsc --noEmit",
     "dev": "tsc --watch",
-    "test": "tsx --test src/**/*.test.ts",
-    "test:watch": "tsx --watch --test src/**/*.test.ts"
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "cluster-key-slot": "^1.1.2",
@@ -44,7 +44,8 @@
     "@repo/typescript-config": "workspace:*",
     "@types/node": "22.13.9",
     "tsx": "4.19.3",
-    "typescript": "5.8.2"
+    "typescript": "5.8.2",
+    "vitest": "3.0.7"
   },
   "peerDependencies": {
     "next": ">= 15 < 16",

packages/cache-handler/src/cache-handler.ts

@@ -15,8 +15,8 @@ import type {
 } from './next-common-types.js';
 import { CachedRouteKind } from './next-common-types.js';
 
-import { createValidatedAgeEstimationFunction } from './helpers/create-validated-age-estimation-function.js';
-import { getTagsFromHeaders } from './helpers/get-tags-from-headers.js';
+import { composeAgeEstimationFn } from './utils/compose-age-estimation-fn.js';
+import { getTagsFromHeaders } from './utils/get-tags-from-headers.js';
 
 export type { CacheHandlerValue };
 
@@ -623,8 +623,7 @@ export class CacheHandler implements NextCacheHandler {
       CacheHandler.#defaultStaleAge = Math.floor(defaultStaleAge);
     }
 
-    CacheHandler.#estimateExpireAge =
-      createValidatedAgeEstimationFunction(estimateExpireAge);
+    CacheHandler.#estimateExpireAge = composeAgeEstimationFn(estimateExpireAge);
 
     CacheHandler.#serverDistDir = serverDistDir;
 

packages/cache-handler/src/handlers/experimental-redis-cluster.ts

@@ -1,11 +1,11 @@
-import calculate from 'cluster-key-slot';
-import type { createCluster } from 'redis';
 import type { CacheHandlerValue, Handler } from '../cache-handler.js';
 import type { CreateRedisStringsHandlerOptions } from '../common-types.js';
+import calculate from 'cluster-key-slot';
+import type { createCluster } from 'redis';
 
 import { REVALIDATED_TAGS_KEY } from '../constants.js';
-import { getTimeoutRedisCommandOptions } from '../helpers/get-timeout-redis-command-options.js';
-import { isImplicitTag } from '../helpers/is-implicit-tag.js';
+import { createRedisTimeoutConfig } from '../helpers/create-redis-timeout-config.js';
+import { isTagImplicit } from '../helpers/is-tag-implicit.js';
 
 type CreateRedisClusterHandlerOptions<T = ReturnType<typeof createCluster>> =
   CreateRedisStringsHandlerOptions & {
@@ -83,7 +83,7 @@ export default function createHandler({
     name: 'experimental-redis-cluster',
     async get(key, { implicitTags }) {
       const result = await cluster.get(
-        getTimeoutRedisCommandOptions(timeoutMs),
+        createRedisTimeoutConfig(timeoutMs),
         keyPrefix + key,
       );
 
@@ -104,7 +104,7 @@ export default function createHandler({
       }
 
       const revalidationTimes = await cluster.hmGet(
-        getTimeoutRedisCommandOptions(timeoutMs),
+        createRedisTimeoutConfig(timeoutMs),
         revalidatedTagsKey,
         Array.from(combinedTags),
       );
@@ -115,7 +115,7 @@ export default function createHandler({
           Number.parseInt(timeString, 10) > cacheValue.lastModified
         ) {
           await cluster.unlink(
-            getTimeoutRedisCommandOptions(timeoutMs),
+            createRedisTimeoutConfig(timeoutMs),
             keyPrefix + key,
           );
 
@@ -126,7 +126,7 @@ export default function createHandler({
       return cacheValue;
     },
     async set(key, cacheHandlerValue) {
-      const options = getTimeoutRedisCommandOptions(timeoutMs);
+      const options = createRedisTimeoutConfig(timeoutMs);
 
       let setOperation: Promise<string | null>;
 
@@ -184,9 +184,9 @@ export default function createHandler({
     async revalidateTag(tag) {
       // If the tag is an implicit tag, we need to mark it as revalidated.
       // The revalidation process is done by the CacheHandler class on the next get operation.
-      if (isImplicitTag(tag)) {
+      if (isTagImplicit(tag)) {
         await cluster.hSet(
-          getTimeoutRedisCommandOptions(timeoutMs),
+          createRedisTimeoutConfig(timeoutMs),
           revalidatedTagsKey,
           tag,
           Date.now(),
@@ -201,7 +201,7 @@ export default function createHandler({
 
       do {
         const remoteTagsPortion = await cluster.hScan(
-          getTimeoutRedisCommandOptions(timeoutMs),
+          createRedisTimeoutConfig(timeoutMs),
           keyPrefix + sharedTagsKey,
           cursor,
           hScanOptions,
@@ -242,7 +242,7 @@ export default function createHandler({
         }
 
         const unlinkPromisesForSlot = client.unlink(
-          getTimeoutRedisCommandOptions(timeoutMs),
+          createRedisTimeoutConfig(timeoutMs),
           keys,
         );
 
@@ -252,15 +252,15 @@ export default function createHandler({
       }
 
       const updateTagsOperation = cluster.hDel(
-        { isolated: true, ...getTimeoutRedisCommandOptions(timeoutMs) },
+        { isolated: true, ...createRedisTimeoutConfig(timeoutMs) },
         keyPrefix + sharedTagsKey,
         tagsToDelete,
       );
 
       await Promise.allSettled([...unlinkPromises, updateTagsOperation]);
     },
     async delete(key) {
-      await cluster.unlink(getTimeoutRedisCommandOptions(timeoutMs), key);
+      await cluster.unlink(createRedisTimeoutConfig(timeoutMs), key);
     },
   };
 }

packages/cache-handler/src/handlers/local-lru.ts

@@ -1,15 +1,108 @@
-import type { LruCacheOptions } from '../lru-cache-next-adapter/cache-types/next-cache-handler-value.js';
-import createCacheStore from '../lru-cache-next-adapter/cache-types/next-cache-handler-value.js';
-
 import type { Handler } from '../cache-handler.js';
 import { NEXT_CACHE_IMPLICIT_TAG_ID } from '../next-common-types.js';
+import {
+  type CacheHandlerValue,
+  CachedRouteKind,
+} from '../next-common-types.js';
+import { LRUCache } from 'lru-cache';
+
+function calculateObjectSize({ value }: CacheHandlerValue): number {
+  // Return default size if value is falsy
+  if (!value) {
+    return 25;
+  }
+
+  switch (value.kind) {
+    case CachedRouteKind.REDIRECT: {
+      // Calculate size based on the length of the stringified props
+      return JSON.stringify(value.props).length;
+    }
+    case CachedRouteKind.IMAGE: {
+      // Throw a specific error for image kind
+      throw new Error(
+        'Image kind should not be used for incremental-cache calculations.',
+      );
+    }
+    case CachedRouteKind.FETCH: {
+      // Calculate size based on the length of the stringified data
+      return JSON.stringify(value.data || '').length;
+    }
+    case CachedRouteKind.APP_ROUTE: {
+      // Size based on the length of the body
+      return value.body.length;
+    }
+    case CachedRouteKind.PAGES: {
+      return value.html.length + JSON.stringify(value.pageData).length;
+    }
+    case CachedRouteKind.APP_PAGE: {
+      return value.html.length + (value.rscData?.length || 0);
+    }
+    default: {
+      return 0;
+    }
+  }
+}
+
+export function createCacheStore(
+  options?: LruCacheOptions,
+): LRUCache<string, CacheHandlerValue> {
+  return createConfiguredCache(calculateObjectSize, options);
+}
 
 /**
- * @deprecated Use {@link LruCacheOptions} instead.
+ * Configuration options for the LRU cache.
+ *
+ * @since 1.0.0
  */
-export type LruCacheHandlerOptions = LruCacheOptions;
+export type LruCacheOptions = {
+  /**
+   * Optional. Maximum number of items the cache can hold.
+   *
+   * @default 1000
+   *
+   * @since 1.0.0
+   */
+  maxItemsNumber?: number;
+  /**
+   * Optional. Maximum size in bytes for each item in the cache.
+   *
+   * @default 104857600 // 100 Mb
+   *
+   * @since 1.0.0
+   */
+  maxItemSizeBytes?: number;
+};
+
+const MAX_ITEMS_NUMBER = 1000;
+const MAX_ITEM_SIZE_BYTES = 100 * 1024 * 1024;
+
+const DEFAULT_OPTIONS: LruCacheOptions = {
+  maxItemsNumber: MAX_ITEMS_NUMBER,
+  maxItemSizeBytes: MAX_ITEM_SIZE_BYTES,
+};
 
-export type { LruCacheOptions };
+/**
+ * Creates a configured LRUCache.
+ *
+ * @param calculateSizeCallback - A callback function to calculate the size of cache items.
+ *
+ * @param options - Optional configuration options for the cache.
+ *
+ * @returns A new instance of LRUCache.
+ */
+export function createConfiguredCache<CacheValueType extends object | string>(
+  calculateSizeCallback: (value: CacheValueType) => number,
+  {
+    maxItemsNumber = MAX_ITEMS_NUMBER,
+    maxItemSizeBytes = MAX_ITEM_SIZE_BYTES,
+  } = DEFAULT_OPTIONS,
+): LRUCache<string, CacheValueType> {
+  return new LRUCache<string, CacheValueType>({
+    max: maxItemsNumber,
+    maxSize: maxItemSizeBytes,
+    sizeCalculation: calculateSizeCallback,
+  });
+}
 
 /**
  * Creates an LRU (Least Recently Used) cache Handler.