Refactoring and cleanup

Author: AyronK

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

@@ -10,6 +10,9 @@ import {
   CacheHandlerParametersRevalidateTag,
   CacheHandlerParametersSet,
   CacheHandlerParametersGet,
+  Handler,
+  OnCreationHook,
+  Revalidate,
 } from "./cache-handler.types";
 import { PrerenderManifest } from "next/dist/build";
 import type {
@@ -19,228 +22,8 @@ import type {
   GetIncrementalFetchCacheContext,
 } from "next/dist/server/response-cache/types";
 
-export type Revalidate = false | number;
 const PRERENDER_MANIFEST_VERSION = 4;
 
-/**
- * Represents an internal Next.js metadata for a `get` method.
- * This metadata is available in the `get` method of the cache handler.
- */
-type HandlerGetMeta = {
-  /**
-   * An array of tags that are implicitly associated with the cache entry.
-   */
-  implicitTags: string[];
-};
-
-/**
- * Represents a cache Handler.
- */
-export type Handler = {
-  /**
-   * A descriptive name for the cache Handler.
-   */
-  name: string;
-  /**
-   * Retrieves the value associated with the given key from the cache.
-   *
-   * @param key - The unique string identifier for the cache entry.
-   *
-   * @param meta - The metadata object for the `get` method. See {@link HandlerGetMeta}.
-   *
-   * @returns A Promise that resolves to the cached value (if found), `null` or `undefined` if the entry is not found.
-   *
-   * @example
-   * ### With auto expiration
-   *
-   * If your cache store supports time based key eviction, the `get` method is straightforward.
-   *
-   * ```js
-   *  const handler = {
-   *    async get(key) {
-   *      const cacheValue = await cacheStore.get(key);
-   *
-   *      if (!cacheValue) {
-   *          return null;
-   *      }
-   *
-   *      return cacheValue;
-   *   }
-   * }
-   * ```
-   *
-   * ### Without auto expiration
-   *
-   * If your cache store does not support time based key eviction,
-   * you can implement the `delete` method to remove the cache entry when it becomes expired.
-   *
-   * ```js
-   *  const handler = {
-   *    async get(key) {
-   *      const cacheValue = await cacheStore.get(key);
-   *
-   *      if (!cacheValue) {
-   *          return null;
-   *      }
-   *
-   *      return cacheValue;
-   *    },
-   *    async delete(key) {
-   *      await cacheStore.delete(key);
-   *    }
-   * }
-   * ```
-   *
-   
-   */
-  get: (
-    key: string,
-    meta: HandlerGetMeta,
-  ) => Promise<CacheHandlerValue | null | undefined>;
-  /**
-   * Sets or updates a value in the cache store.
-   *
-   * @param key - The unique string identifier for the cache entry.
-   *
-   * @param value - The value to be stored in the cache. See {@link CacheHandlerValue}.
-   *
-   * @returns A Promise that resolves when the value has been successfully set in the cache.
-   *
-   * @remarks
-   *
-   * Read more about the `lifespan` parameter: {@link LifespanParameters}.
-   *
-   * ### LifespanParameters
-   * If no `revalidate` option or `revalidate: false` is set in your [`getStaticProps` ↗](https://nextjs.org/docs/pages/api-reference/functions/get-static-props#revalidate)
-   * the `lifespan` parameter will be `null` and you should consider the cache entry as always fresh and never stale.
-   *
-   * Use the absolute time (`expireAt`) to set and expiration time for the cache entry in your cache store to be in sync with the file system cache.
-   *
-   
-   */
-  set: (key: string, value: CacheHandlerValue) => Promise<void>;
-  /**
-   * Deletes all cache entries that are associated with the specified tag.
-   * See [fetch `options.next.tags` and `revalidateTag` ↗](https://nextjs.org/docs/app/building-your-application/caching#fetch-optionsnexttags-and-revalidatetag)
-   *
-   * @param tag - A string representing the cache tag associated with the data you want to revalidate.
-   * Must be less than or equal to 256 characters. This value is case-sensitive.
-   *
-   
-   */
-  revalidateTag: (tag: string) => Promise<void>;
-  /**
-   * Deletes the cache entry associated with the given key from the cache store.
-   * This method is optional and supposed to be used only when the cache store does not support time based key eviction.
-   * This method will be automatically called by the `CacheHandler` class when the retrieved cache entry is stale.
-   *
-   * @param key - The unique string identifier for the cache entry with prefix if present.
-   *
-   * @returns A Promise that resolves when the cache entry has been successfully deleted.
-   */
-  delete?: (key: string) => Promise<void>;
-};
-
-/**
- * Represents the parameters for Time-to-Live (TTL) configuration.
- */
-export type TTLParameters = {
-  /**
-   * The time in seconds for when the cache entry becomes stale.
-   *
-   * @default 31536000 // 1 year
-   */
-  defaultStaleAge: number;
-  /**
-   * Estimates the expiration age based on the stale age.
-   *
-   * @param staleAge - The stale age in seconds.
-   * After the stale age, the cache entry is considered stale, can be served from the cache, and should be revalidated.
-   * Revalidation is handled by the `CacheHandler` class.
-   *
-   * @default (staleAge) => staleAge * 1.5
-   *
-   * @returns The expiration age in seconds.
-   */
-  estimateExpireAge(staleAge: number): number;
-};
-
-/**
- * Configuration options for the {@link CacheHandler}.
- */
-export type CacheHandlerConfig = {
-  /**
-   * An array of cache instances that conform to the Handler interface.
-   * Multiple caches can be used to implement various caching strategies or layers.
-   */
-  handlers: (Handler | undefined | null)[];
-  /**
-   * Time-to-live (TTL) options for the cache entries.
-   */
-  ttl?: Partial<TTLParameters>;
-};
-
-/**
- * Contextual information provided during cache creation, including server directory paths and environment mode.
- */
-export type CacheCreationContext = {
-  /**
-   * The absolute path to the Next.js server directory.
-   */
-  serverDistDir: string;
-  /**
-   * Indicates if the Next.js application is running in development mode.
-   * When in development mode, caching behavior might differ.
-   */
-  dev?: boolean;
-  /**
-   * The unique identifier for the current build of the Next.js application.
-   * This build ID is generated during the `next build` process and is used
-   * to ensure consistency across multiple instances of the application,
-   * especially when running in containerized environments. It helps in
-   * identifying which version of the application is being served.
-   *
-   * https://nextjs.org/docs/pages/building-your-application/deploying#build-cache
-   *
-   * @example
-   * ```js
-   * // cache-handler.mjs
-   * CacheHandler.onCreation(async ({ buildId }) => {
-   *   let redisHandler;
-   *
-   *   if (buildId) {
-   *     await client.connect();
-   *
-   *     redisHandler = await createRedisHandler({
-   *       client,
-   *       keyPrefix: `${buildId}:`,
-   *     });
-   *   }
-   *
-   *   const localHandler = createLruHandler();
-   *
-   *   return {
-   *     handlers: [redisHandler, localHandler],
-   *   };
-   * });
-   * ```
-   */
-  buildId?: string;
-};
-
-/**
- * Represents a hook function that is called during the build and on start of the application.
- *
- * @param context - The {@link CacheCreationContext} object, providing contextual information about the cache creation environment,
- * such as server directory paths and whether the application is running in development mode.
- *
- * @returns Either a {@link CacheHandlerConfig} object or a Promise that resolves to a {@link CacheHandlerConfig},
- * specifying how the cache should be configured.
- */
-export type OnCreationHook = (
-  context: CacheCreationContext,
-) => Promise<CacheHandlerConfig> | CacheHandlerConfig;
-
 /**
  * Deletes an entry from all handlers.
  *

packages/nextjs-cache-handler/src/handlers/cache-handler.types.ts

@@ -4,6 +4,7 @@ import type {
 } from "next/dist/server/lib/incremental-cache";
 
 import type FileSystemCache from "next/dist/server/lib/incremental-cache/file-system-cache";
+
 /**
  * A set of time periods and timestamps for controlling cache behavior.
  */
@@ -49,7 +50,7 @@ export type CacheHandlerParametersGetWithTags = [
  * Represents an internal Next.js metadata for a `get` method.
  * This metadata is available in the `get` method of the cache handler.
  */
-type HandlerGetMeta = {
+export type HandlerGetMeta = {
   /**
    * An array of tags that are implicitly associated with the cache entry.
    */
@@ -58,7 +59,7 @@ type HandlerGetMeta = {
 /**
  * Represents a cache Handler.
  */
-type Handler = {
+export type Handler = {
   /**
    * A descriptive name for the cache Handler.
    */
@@ -159,7 +160,7 @@ type Handler = {
 /**
  * Represents the parameters for Time-to-Live (TTL) configuration.
  */
-type TTLParameters = {
+export type TTLParameters = {
   /**
    * The time in seconds for when the cache entry becomes stale.
    *
@@ -182,7 +183,7 @@ type TTLParameters = {
 /**
  * Configuration options for the {@link CacheHandler}.
  */
-type CacheHandlerConfig = {
+export type CacheHandlerConfig = {
   /**
    * An array of cache instances that conform to the Handler interface.
    * Multiple caches can be used to implement various caching strategies or layers.
@@ -196,7 +197,7 @@ type CacheHandlerConfig = {
 /**
  * Contextual information provided during cache creation, including server directory paths and environment mode.
  */
-type CacheCreationContext = {
+export type CacheCreationContext = {
   /**
    * The absolute path to the Next.js server directory.
    */
@@ -249,7 +250,7 @@ type CacheCreationContext = {
  * @returns Either a {@link CacheHandlerConfig} object or a Promise that resolves to a {@link CacheHandlerConfig},
  * specifying how the cache should be configured.
  */
-type OnCreationHook = (
+export type OnCreationHook = (
   context: CacheCreationContext,
 ) => Promise<CacheHandlerConfig> | CacheHandlerConfig;
 declare class CacheHandler implements NextCacheHandler {
@@ -345,12 +346,3 @@ export type CacheHandlerValue = NextCacheHandlerValue & {
    */
   lifespan: LifespanParameters | null;
 };
-
-export {
-  type CacheCreationContext,
-  CacheHandler,
-  type CacheHandlerConfig,
-  type Handler,
-  type OnCreationHook,
-  type TTLParameters,
-};

packages/nextjs-cache-handler/src/handlers/composite.ts

@@ -1,19 +1,5 @@
-import { CacheHandlerValue, Handler } from "./cache-handler.types";
-
-export type CreateCompositeHandlerOptions = {
-  /**
-   * A collection of handlers to manage the cache.
-   */
-  handlers: Handler[];
-
-  /**
-   * Strategy to determine which handler to use for the set operation.
-   * Defaults to the first handler if not provided.
-   * @param data - The data to be saved in one of the handlers. See {@link CacheHandlerValue}.
-   * @returns The index of the handler for the set operation.
-   */
-  setStrategy: (data: CacheHandlerValue) => number;
-};
+import { Handler } from "./cache-handler.types";
+import { CreateCompositeHandlerOptions } from "./composite.types";
 
 /**
  * Creates a composite Handler for managing cache operations using multiple handlers.

packages/nextjs-cache-handler/src/handlers/composite.types.ts

@@ -0,0 +1,16 @@
+import { Handler, CacheHandlerValue } from "./cache-handler.types";
+
+export type CreateCompositeHandlerOptions = {
+  /**
+   * A collection of handlers to manage the cache.
+   */
+  handlers: Handler[];
+
+  /**
+   * Strategy to determine which handler to use for the set operation.
+   * Defaults to the first handler if not provided.
+   * @param data - The data to be saved in one of the handlers. See {@link CacheHandlerValue}.
+   * @returns The index of the handler for the set operation.
+   */
+  setStrategy: (data: CacheHandlerValue) => number;
+};

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

@@ -1,6 +1,7 @@
 import { LRUCache } from "lru-cache";
 import { CacheHandlerValue, Handler } from "./cache-handler.types";
 import { NEXT_CACHE_IMPLICIT_TAG_ID } from "../helpers/const";
+import { LruCacheOptions } from "./local-lru.types";
 
 const MAX_ITEMS_NUMBER = 1000;
 const MAX_ITEM_SIZE_BYTES = 100 * 1024 * 1024;
@@ -33,28 +34,6 @@ export function createConfiguredCache<CacheValueType extends object | string>(
   });
 }
 
-/**
- * Configuration options for the LRU cache.
- */
-export type LruCacheOptions = {
-  /**
-   * Optional. Maximum number of items the cache can hold.
-   *
-   * @default 1000
-   */
-  maxItemsNumber?: number;
-  /**
-   * Optional. Maximum size in bytes for each item in the cache.
-   *
-   * @default 104857600 // 100 Mb
-   */
-  maxItemSizeBytes?: number;
-};
-/**
- * @deprecated Use {@link LruCacheOptions} instead.
- */
-export type LruCacheHandlerOptions = LruCacheOptions;
-
 /**
  * Creates an LRU (Least Recently Used) cache Handler.
  *
@@ -77,8 +56,6 @@ export type LruCacheHandlerOptions = LruCacheOptions;
  *
  * @remarks
  * - Use this Handler as a fallback for any remote store Handler.
- *
- * @since 1.0.0
  */
 export default function createHandler({
   ...lruOptions