strapi-cache 1.8.3 → 1.8.8

package/README.md

@@ -35,9 +35,31 @@ or
 yarn add strapi-cache
 ```
 
-## ⚙️ Configuration
+## Quickstart
+
+```javascript
+// config/plugins.{js,ts}
+'strapi-cache': {
+  enabled: true,
+},
+```
+
+To use **Redis** or **Valkey** instead of memory, set `provider` and `redisConfig` (required for those providers):
+
+```javascript
+// config/plugins.{js,ts}
+'strapi-cache': {
+  enabled: true,
+  config: {
+    provider: 'redis', // or 'valkey'
+    redisConfig: env('REDIS_URL', 'redis://127.0.0.1:6379'),
+  },
+},
+```
+
+See [ioredis](https://github.com/redis/ioredis) (Redis) or [iovalkey](https://github.com/valkey-io/iovalkey) (Valkey) for advanced `redisConfig` shapes (URL string or client options object).
 
-In your Strapi project, navigate to `config/plugins.js` and add the following configuration:
+Full configuration example:
 
 ```javascript
 // config/plugins.{js,ts}
@@ -51,7 +73,7 @@ In your Strapi project, navigate to `config/plugins.js` and add the following co
     allowStale: false, // Allow stale cache items (only for memory cache)
     cacheableRoutes: ['/api/products', '/api/categories'], // Caches routes which start with these paths (if empty array, all '/api' routes are cached)
     // cacheableEntities: ['products', 'categories'], // (Optional) Specify which entities to cache. When set, only these entities will be cached (ignores cacheableRoutes). If not set (undefined), cacheableRoutes logic is used
-    excludeRoutes: ['/api/products/private'], // (NEW) Exclude routes which start with these paths from being cached (takes precedence over cacheableRoutes). **Note:** `excludeRoutes` takes precedence over `cacheableRoutes`.
+    excludeRoutes: ['/api/products/private'], // Exclude routes which start with these paths from being cached (takes precedence over cacheableRoutes). **Note:** `excludeRoutes` takes precedence over `cacheableRoutes`.
     provider: 'memory', // Cache provider ('memory', 'redis' or 'valkey')
     redisConfig: env('REDIS_URL', 'redis://localhost:6379'), // Redis/Valkey config: string or object. See https://github.com/redis/ioredis (Redis) or https://github.com/valkey-io/iovalkey (Valkey)
     redisClusterNodes: [], // If provided any cluster node (this list is not empty), initialize cluster client. Each object must have keys 'host' and 'port'
@@ -70,6 +92,36 @@ In your Strapi project, navigate to `config/plugins.js` and add the following co
 },
 ```
 
+## ⚙️ Configuration
+
+Possible configuration keys are listed below; omitted keys keep the plugin defaults.
+
+| Key                       | Description                                                                                                                   | Possible values                                                                                                               |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `debug`                   | Log cache decisions and operations to the server console                                                                      | `true` or `false` (default: `false`)                                                                                          |
+| `provider`                | Where entries are stored                                                                                                      | `'memory'`, `'redis'`, or `'valkey'` (default: `'memory'`)                                                                    |
+| `redisConfig`             | Redis/Valkey connection: URL string or client options passed to ioredis/iovalkey                                              | String or object; **required** when `provider` is `'redis'` or `'valkey'`. Default: value of `REDIS_URL` from the environment |
+| `redisClusterNodes`       | Seed nodes for Redis cluster mode; non-empty list switches to a cluster client                                                | Array of `{ host: string, port: number }` (default: `[]`)                                                                     |
+| `redisClusterOptions`     | Options for the cluster client (e.g. `scaleReads`); `redisOptions` often come from `redisConfig`                              | Object (default: `{}`)                                                                                                        |
+| `redisScanDeleteCount`    | `COUNT` hint for `SCAN` when purging keys (Redis/Valkey)                                                                      | Positive number (default: `100`)                                                                                              |
+| `max`                     | Maximum number of entries (in-memory provider only)                                                                           | Positive integer (default: `1000`)                                                                                            |
+| `ttl`                     | Time-to-live for each entry, in milliseconds                                                                                  | Non-negative number (default: `3600000`, i.e. 1 hour)                                                                         |
+| `size`                    | Approximate max total size in bytes (in-memory provider only)                                                                 | Positive integer (default: `10485760`, i.e. 10 MB)                                                                            |
+| `allowStale`              | Whether stale entries may be returned (in-memory provider only)                                                               | `true` or `false` (default: `false`)                                                                                          |
+| `cacheableRoutes`         | Only URLs starting with one of these paths are cached; if empty, every URL under the REST API prefix matches                  | Array of path prefix strings (default: `[]` meaning “all API routes”)                                                         |
+| `cacheableEntities`       | If non-empty, only these API “entity” segments are cached; **when set, this drives eligibility instead of** `cacheableRoutes` | Array of strings (e.g. collection/table names), or omit / leave empty to use `cacheableRoutes`                                |
+| `excludeRoutes`           | URLs starting with any of these prefixes are **never** cached; evaluated before `cacheableRoutes` / entities                  | Array of path prefix strings (default: `[]`)                                                                                  |
+| `cacheHeaders`            | Store and replay response headers with the body                                                                               | `true` or `false` (default: `true`)                                                                                           |
+| `cacheHeadersDenyList`    | Header names (lowercase) to strip when `cacheHeaders` is `true`                                                               | Array of strings (default: `[]`)                                                                                              |
+| `cacheHeadersAllowList`   | If non-empty, only these header names (lowercase) are stored; if empty, all headers are stored (subject to deny list)         | Array of strings (default: `[]`)                                                                                              |
+| `cacheAuthorizedRequests` | Whether to cache requests that include an `Authorization` header                                                              | `true` or `false` (default: `false`)                                                                                          |
+| `cacheGetTimeoutInMs`     | Max time to wait for a cache read before treating it as a miss                                                                | Milliseconds (default: `1000`)                                                                                                |
+| `autoPurgeCache`          | Invalidate relevant REST cache entries after content create/update/delete                                                     | `true` or `false` (default: `true`)                                                                                           |
+| `autoPurgeGraphQL`        | Invalidate GraphQL cache after content create/update/delete                                                                   | `true` or `false` (default: `false` if omitted; set `true` to enable)                                                         |
+| `autoPurgeCacheOnStart`   | Clear the cache when Strapi starts                                                                                            | `true` or `false` (default: `true`)                                                                                           |
+| `disableAdminPopups`      | Turn off admin UI notifications for cache actions                                                                             | `true` or `false` (default: `false`)                                                                                          |
+| `disableAdminButtons`     | Hide manual purge controls in the admin (list and edit views)                                                                 | `true` or `false` (default: `false`)                                                                                          |
+
 ## 🔍 Routes
 
 The plugin creates three new routes
@@ -85,7 +137,7 @@ All of these routes are protected by the policies `admin::isAuthenticatedAdmin`
 
 - **Storage**: The plugin keeps cached data in memory, Redis or Valkey, depending on the configuration.
 - **Packages**: Uses [lru-cache](https://github.com/isaacs/node-lru-cache) for in-memory cache. Uses [ioredis](https://github.com/redis/ioredis) for Redis and [iovalkey](https://github.com/valkey-io/iovalkey) for Valkey caching.
-- **Automatic Invalidation**: Cache is cleared automatically when content is updated, deleted, or created. (GraphQL cache clears on any content update.)
+- **Automatic Invalidation**: When `autoPurgeCache` is enabled (default), relevant REST cache entries are invalidated on content create, update, or delete. When `autoPurgeGraphQL` is enabled, GraphQL cache is invalidated the same way (it is off unless you set it in config).
 - **`no-cache` Header Support**: Respects the `no-cache` header, letting you skip the cache by setting `Cache-Control: no-cache` in your request.
 - **Default Cached Requests**: By default, caches all GET requests to `/api` (or whatever prefix you defined) and POST requests to `/graphql`. You can customize which routes or entities to cache using `cacheableRoutes` or `cacheableEntities` config options.
 

package/dist/server/index.js

@@ -5,7 +5,6 @@ const zlib = require("zlib");
 const rawBody = require("raw-body");
 const lruCache = require("lru-cache");
 const ioredis = require("ioredis");
-const iovalkey = require("iovalkey");
 const _interopDefault = (e) => e && e.__esModule ? e : { default: e };
 const Stream__default = /* @__PURE__ */ _interopDefault(Stream);
 const rawBody__default = /* @__PURE__ */ _interopDefault(rawBody);
@@ -274,6 +273,9 @@ const middleware$1 = async (ctx, next) => {
   if (cacheEntry && !noCache) {
     loggy.info(`HIT with key: ${key}`);
     ctx.status = 200;
+    if (cacheEntry?.body?.type === "Buffer" && Array.isArray(cacheEntry.body.data)) {
+      cacheEntry.body = Buffer.from(cacheEntry.body.data);
+    }
     ctx.body = cacheEntry.body;
     if (cacheHeaders) {
       ctx.set(cacheEntry.headers);
@@ -544,7 +546,8 @@ const config = {
     autoPurgeCache: true,
     autoPurgeCacheOnStart: true,
     disableAdminPopups: false,
-    disableAdminButtons: false
+    disableAdminButtons: false,
+    redisScanDeleteCount: 100
   }),
   validator: (config2) => {
     if (typeof config2.debug !== "boolean") {
@@ -624,6 +627,9 @@ const config = {
     if (typeof config2.disableAdminButtons !== "boolean") {
       throw new Error(`Invalid config: disableAdminButtons must be a boolean`);
     }
+    if (typeof config2.redisScanDeleteCount !== "number") {
+      throw new Error(`Invalid config: redisScanDeleteCount must be a number`);
+    }
   }
 };
 const contentTypes = {};
@@ -856,34 +862,20 @@ class RedisCacheProvider {
         this.strapi.plugin("strapi-cache").config("cacheGetTimeoutInMs")
       );
       this.keyPrefix = this.strapi.plugin("strapi-cache").config("redisConfig")?.["keyPrefix"] ?? "";
-      if (provider === "valkey") {
-        if (redisClusterNodes.length) {
-          const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions") ?? {};
-          const clusterOptions = { ...redisClusterOptions };
-          if (!clusterOptions["redisOptions"]) {
-            clusterOptions["redisOptions"] = redisConfig;
-          }
-          this.client = new iovalkey.Cluster(
-            redisClusterNodes,
-            clusterOptions
-          );
-        } else {
-          this.client = new iovalkey.Redis(redisConfig);
+      this.redisScanDeleteCount = Number(
+        this.strapi.plugin("strapi-cache").config("redisScanDeleteCount")
+      );
+      if (redisClusterNodes.length) {
+        const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions");
+        if (!redisClusterOptions["redisOptions"]) {
+          redisClusterOptions.redisOptions = redisConfig;
         }
-        loggy.info("Valkey provider initialized");
+        this.client = new ioredis.Redis.Cluster(redisClusterNodes, redisClusterOptions);
       } else {
-        if (redisClusterNodes.length) {
-          const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions");
-          if (!redisClusterOptions["redisOptions"]) {
-            redisClusterOptions.redisOptions = redisConfig;
-          }
-          this.client = new ioredis.Redis.Cluster(redisClusterNodes, redisClusterOptions);
-        } else {
-          this.client = new ioredis.Redis(redisConfig);
-        }
-        loggy.info("Redis provider initialized");
+        this.client = new ioredis.Redis(redisConfig);
       }
       this.initialized = true;
+      loggy.info(`${provider === "valkey" ? "Valkey" : "Redis"} provider initialized`);
     } catch (error) {
       loggy.error(error);
     }
@@ -931,18 +923,6 @@ class RedisCacheProvider {
       return null;
     }
   }
-  /**
-   * Deletes all given keys in Redis pipeline.
-   * @param keys to delete from cache
-   */
-  async delAll(keys) {
-    const pipeline = this.client.pipeline();
-    keys.forEach((key) => {
-      const relativeKey = key.slice(this.keyPrefix.length);
-      pipeline.del(relativeKey);
-    });
-    await pipeline.exec();
-  }
   async keys() {
     if (!this.ready) return null;
     try {
@@ -972,13 +952,37 @@ class RedisCacheProvider {
       return null;
     }
   }
+  async deleteBatch(client, batch, regExps) {
+    const toDelete = batch.filter((key) => regExps.some((re) => re.test(key)));
+    if (toDelete.length === 0) return;
+    const pipeline = client.pipeline();
+    for (const key of toDelete) {
+      const relativeKey = key.startsWith(this.keyPrefix) ? key.slice(this.keyPrefix.length) : key;
+      pipeline.del(relativeKey);
+    }
+    await pipeline.exec();
+  }
+  scanAndDelete(client, regExps) {
+    return new Promise((resolve, reject) => {
+      const stream = client.scanStream({ match: `${this.keyPrefix}*`, count: this.redisScanDeleteCount });
+      stream.on("data", (batch) => {
+        stream.pause();
+        this.deleteBatch(client, batch, regExps).then(() => stream.resume()).catch(reject);
+      });
+      stream.on("end", resolve);
+      stream.on("error", reject);
+    });
+  }
+  /**
+   * ScanStream keys and batch delete for Redis,
+   * iterates over master nodes in case of Cluster.
+   */
   async clearByRegexp(regExps) {
-    const keys = await this.keys();
-    if (!keys) {
-      return;
+    if (this.client instanceof ioredis.Redis) {
+      return this.scanAndDelete(this.client, regExps);
     }
-    const toDelete = keys.filter((key) => regExps.some((re) => re.test(key)));
-    await this.delAll(toDelete);
+    const nodes = this.client.nodes("master");
+    await Promise.all(nodes.map((node) => this.scanAndDelete(node, regExps)));
   }
 }
 const resolveCacheProvider = (strapi2) => {

package/dist/server/index.mjs

@@ -3,8 +3,7 @@ import Stream, { Readable } from "stream";
 import { createInflate, createBrotliDecompress, createGunzip } from "zlib";
 import rawBody from "raw-body";
 import { LRUCache } from "lru-cache";
-import { Redis as Redis$1 } from "ioredis";
-import { Cluster, Redis } from "iovalkey";
+import { Redis } from "ioredis";
 const loggy = {
   info: (msg) => {
     const shouldDebug = strapi.plugin("strapi-cache").config("debug") ?? false;
@@ -270,6 +269,9 @@ const middleware$1 = async (ctx, next) => {
   if (cacheEntry && !noCache) {
     loggy.info(`HIT with key: ${key}`);
     ctx.status = 200;
+    if (cacheEntry?.body?.type === "Buffer" && Array.isArray(cacheEntry.body.data)) {
+      cacheEntry.body = Buffer.from(cacheEntry.body.data);
+    }
     ctx.body = cacheEntry.body;
     if (cacheHeaders) {
       ctx.set(cacheEntry.headers);
@@ -540,7 +542,8 @@ const config = {
     autoPurgeCache: true,
     autoPurgeCacheOnStart: true,
     disableAdminPopups: false,
-    disableAdminButtons: false
+    disableAdminButtons: false,
+    redisScanDeleteCount: 100
   }),
   validator: (config2) => {
     if (typeof config2.debug !== "boolean") {
@@ -620,6 +623,9 @@ const config = {
     if (typeof config2.disableAdminButtons !== "boolean") {
       throw new Error(`Invalid config: disableAdminButtons must be a boolean`);
     }
+    if (typeof config2.redisScanDeleteCount !== "number") {
+      throw new Error(`Invalid config: redisScanDeleteCount must be a number`);
+    }
   }
 };
 const contentTypes = {};
@@ -852,34 +858,20 @@ class RedisCacheProvider {
         this.strapi.plugin("strapi-cache").config("cacheGetTimeoutInMs")
       );
       this.keyPrefix = this.strapi.plugin("strapi-cache").config("redisConfig")?.["keyPrefix"] ?? "";
-      if (provider === "valkey") {
-        if (redisClusterNodes.length) {
-          const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions") ?? {};
-          const clusterOptions = { ...redisClusterOptions };
-          if (!clusterOptions["redisOptions"]) {
-            clusterOptions["redisOptions"] = redisConfig;
-          }
-          this.client = new Cluster(
-            redisClusterNodes,
-            clusterOptions
-          );
-        } else {
-          this.client = new Redis(redisConfig);
+      this.redisScanDeleteCount = Number(
+        this.strapi.plugin("strapi-cache").config("redisScanDeleteCount")
+      );
+      if (redisClusterNodes.length) {
+        const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions");
+        if (!redisClusterOptions["redisOptions"]) {
+          redisClusterOptions.redisOptions = redisConfig;
         }
-        loggy.info("Valkey provider initialized");
+        this.client = new Redis.Cluster(redisClusterNodes, redisClusterOptions);
       } else {
-        if (redisClusterNodes.length) {
-          const redisClusterOptions = this.strapi.plugin("strapi-cache").config("redisClusterOptions");
-          if (!redisClusterOptions["redisOptions"]) {
-            redisClusterOptions.redisOptions = redisConfig;
-          }
-          this.client = new Redis$1.Cluster(redisClusterNodes, redisClusterOptions);
-        } else {
-          this.client = new Redis$1(redisConfig);
-        }
-        loggy.info("Redis provider initialized");
+        this.client = new Redis(redisConfig);
       }
       this.initialized = true;
+      loggy.info(`${provider === "valkey" ? "Valkey" : "Redis"} provider initialized`);
     } catch (error) {
       loggy.error(error);
     }
@@ -927,18 +919,6 @@ class RedisCacheProvider {
       return null;
     }
   }
-  /**
-   * Deletes all given keys in Redis pipeline.
-   * @param keys to delete from cache
-   */
-  async delAll(keys) {
-    const pipeline = this.client.pipeline();
-    keys.forEach((key) => {
-      const relativeKey = key.slice(this.keyPrefix.length);
-      pipeline.del(relativeKey);
-    });
-    await pipeline.exec();
-  }
   async keys() {
     if (!this.ready) return null;
     try {
@@ -968,13 +948,37 @@ class RedisCacheProvider {
       return null;
     }
   }
+  async deleteBatch(client, batch, regExps) {
+    const toDelete = batch.filter((key) => regExps.some((re) => re.test(key)));
+    if (toDelete.length === 0) return;
+    const pipeline = client.pipeline();
+    for (const key of toDelete) {
+      const relativeKey = key.startsWith(this.keyPrefix) ? key.slice(this.keyPrefix.length) : key;
+      pipeline.del(relativeKey);
+    }
+    await pipeline.exec();
+  }
+  scanAndDelete(client, regExps) {
+    return new Promise((resolve, reject) => {
+      const stream = client.scanStream({ match: `${this.keyPrefix}*`, count: this.redisScanDeleteCount });
+      stream.on("data", (batch) => {
+        stream.pause();
+        this.deleteBatch(client, batch, regExps).then(() => stream.resume()).catch(reject);
+      });
+      stream.on("end", resolve);
+      stream.on("error", reject);
+    });
+  }
+  /**
+   * ScanStream keys and batch delete for Redis,
+   * iterates over master nodes in case of Cluster.
+   */
   async clearByRegexp(regExps) {
-    const keys = await this.keys();
-    if (!keys) {
-      return;
+    if (this.client instanceof Redis) {
+      return this.scanAndDelete(this.client, regExps);
     }
-    const toDelete = keys.filter((key) => regExps.some((re) => re.test(key)));
-    await this.delAll(toDelete);
+    const nodes = this.client.nodes("master");
+    await Promise.all(nodes.map((node) => this.scanAndDelete(node, regExps)));
   }
 }
 const resolveCacheProvider = (strapi2) => {

package/dist/server/src/config/index.d.ts

@@ -22,6 +22,7 @@ declare const _default: {
         autoPurgeCacheOnStart: boolean;
         disableAdminPopups: boolean;
         disableAdminButtons: boolean;
+        redisScanDeleteCount: number;
     };
     validator: (config: any) => void;
 };

package/dist/server/src/index.d.ts

@@ -31,6 +31,7 @@ declare const _default: {
             autoPurgeCacheOnStart: boolean;
             disableAdminPopups: boolean;
             disableAdminButtons: boolean;
+            redisScanDeleteCount: number;
         };
         validator: (config: any) => void;
     };

package/dist/server/src/services/redis/provider.d.ts

@@ -6,18 +6,20 @@ export declare class RedisCacheProvider implements CacheProvider {
     private client;
     private cacheGetTimeoutInMs;
     private keyPrefix;
+    private redisScanDeleteCount;
     constructor(strapi: Core.Strapi);
     init(): void;
     get ready(): boolean;
     get(key: string): Promise<any | null>;
     set(key: string, val: any): Promise<any | null>;
     del(key: string): Promise<any | null>;
-    /**
-     * Deletes all given keys in Redis pipeline.
-     * @param keys to delete from cache
-     */
-    delAll(keys: string[]): Promise<void>;
     keys(): Promise<string[] | null>;
     reset(): Promise<any | null>;
+    private deleteBatch;
+    private scanAndDelete;
+    /**
+     * ScanStream keys and batch delete for Redis,
+     * iterates over master nodes in case of Cluster.
+     */
     clearByRegexp(regExps: RegExp[]): Promise<void>;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.3",
+  "version": "1.8.8",
   "keywords": [
     "strapi cache",
     "strapi rest cache",
@@ -42,7 +42,6 @@
     "@strapi/design-system": "^2.0.1",
     "@strapi/icons": "^2.0.1",
     "ioredis": "^5.6.1",
-    "iovalkey": "^0.3.3",
     "lru-cache": "^11.1.0",
     "raw-body": "^3.0.0",
     "react-intl": "^7.1.10"