Version bump and readme update

Author: AyronK

README.md

@@ -44,15 +44,23 @@ Read more about this in Handlers section below.
 
 Instead of:
 
-```
+```js
 const { CacheHandler } = require("@neshca/cache-handler");
 module.exports = CacheHandler;
 ```
 
 Use this:
 
-```
-const { Next15CacheHandler } = require("@fortedigital/next-15-cache-handler");
+```js
+const { CacheHandler } = require("@neshca/cache-handler");
+const {
+  Next15CacheHandler,
+} = require("@fortedigital/nextjs-cache-handler/next-15-cache-handler");
+
+CacheHandler.onCreation(() => {
+  // your usual setup
+});
+
 module.exports = new Next15CacheHandler();
 ```
 
@@ -108,6 +116,132 @@ Next 15 decided to change type of data.value.body property from String to Buffer
 
 It is recommended to use this handler with `redis-strings` in Next 15.
 
+## Full example
+
+```js
+// @neshca/cache-handler dependencies
+const { CacheHandler } = require("@neshca/cache-handler");
+const createLruHandler = require("@neshca/cache-handler/local-lru").default;
+
+// Next/Redis dependencies
+const { createClient } = require("redis");
+const { PHASE_PRODUCTION_BUILD } = require("next/constants");
+
+// @fortedigital/nextjs-cache-handler dependencies
+const createCompositeHandler =
+  require("@fortedigital/nextjs-cache-handler/composite").default;
+const createRedisHandler =
+  require("@fortedigital/nextjs-cache-handler/redis-strings").default;
+const createBufferStringHandler =
+  require("@fortedigital/nextjs-cache-handler/buffer-string-decorator").default;
+const {
+  Next15CacheHandler,
+} = require("@fortedigital/nextjs-cache-handler/next-15-cache-handler");
+
+// Usual onCreation from @neshca/cache-handler
+CacheHandler.onCreation(() => {
+  // Important - It's recommended to use global scope to ensure only one Redis connection is made
+  // This ensures only one instance get created
+  if (global.cacheHandlerConfig) {
+    return global.cacheHandlerConfig;
+  }
+
+  // Important - It's recommended to use global scope to ensure only one Redis connection is made
+  // This ensures new instances are not created in a race condition
+  if (global.cacheHandlerConfigPromise) {
+    return global.cacheHandlerConfigPromise;
+  }
+
+  // You may need to ignore Redis locally, remove this block otherwise
+  if (process.env.NODE_ENV === "development") {
+    const lruCache = createLruHandler();
+    return { handlers: [lruCache] };
+  }
+
+  // Main promise initializing the handler
+  global.cacheHandlerConfigPromise = (async () => {
+    /** @type {import("redis").RedisClientType | null} */
+    let redisClient = null;
+    if (PHASE_PRODUCTION_BUILD !== process.env.NEXT_PHASE) {
+      const settings = {
+        url: process.env.REDIS_URL, // Make sure you configure this variable
+        pingInterval: 10000,
+      };
+
+      // This is optional and needed only if you use access keys
+      if (process.env.REDIS_ACCESS_KEY) {
+        settings.password = process.env.REDIS_ACCESS_KEY;
+      }
+
+      try {
+        redisClient = createClient(settings);
+        redisClient.on("error", (e) => {
+          if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== "undefined") {
+            console.warn("Redis error", e);
+          }
+          global.cacheHandlerConfig = null;
+          global.cacheHandlerConfigPromise = null;
+        });
+      } catch (error) {
+        console.warn("Failed to create Redis client:", error);
+      }
+    }
+
+    if (redisClient) {
+      try {
+        console.info("Connecting Redis client...");
+        await redisClient.connect();
+        console.info("Redis client connected.");
+      } catch (error) {
+        console.warn("Failed to connect Redis client:", error);
+        await redisClient
+          .disconnect()
+          .catch(() =>
+            console.warn(
+              "Failed to quit the Redis client after failing to connect."
+            )
+          );
+      }
+    }
+    const lruCache = createLruHandler();
+
+    if (!redisClient?.isReady) {
+      console.error("Failed to initialize caching layer.");
+      global.cacheHandlerConfigPromise = null;
+      global.cacheHandlerConfig = { handlers: [lruCache] };
+      return global.cacheHandlerConfig;
+    }
+
+    const redisCacheHandler = createRedisHandler({
+      client: redisClient,
+      keyPrefix: "nextjs:",
+    });
+
+    global.cacheHandlerConfigPromise = null;
+
+    // This example uses composite handler to switch from Redis to LRU cache if tags contains `memory-cache` tag.
+    // You can skip composite and use Redis or LRU only.
+    global.cacheHandlerConfig = {
+      handlers: [
+        createCompositeHandler({
+          handlers: [
+            lruCache,
+            createBufferStringHandler(redisCacheHandler), // Use `createBufferStringHandler` in Next15 and ignore it in Next14 or below
+          ],
+          setStrategy: (ctx) => (ctx?.tags.includes("memory-cache") ? 0 : 1), // You can adjust strategy for deciding which cache should the composite use
+        }),
+      ],
+    };
+
+    return global.cacheHandlerConfig;
+  })();
+
+  return global.cacheHandlerConfigPromise;
+});
+
+module.exports = new Next15CacheHandler();
+```
+
 ## Reference to Original Package
 
 This package builds upon the core functionality provided by [`@neshca/cache-handler`](https://www.npmjs.com/package/@neshca/cache-handler). You can find more information about the core library, including usage examples and API documentation, at the [official documentation page](https://caching-tools.github.io/next-shared-cache).

packages/nextjs-cache-handler/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/fortedigital/nextjs-cache-handler.git"
   },
-  "version": "1.1.3",
+  "version": "1.1.4",
   "type": "module",
   "license": "MIT",
   "description": "Next.js cache handlers",