Merge pull request #110 from alexdln/nic-107

nic-107 add layers support in widget and tools

Author: alexdln

examples/redis-cache/cache-handler.js

@@ -2,4 +2,6 @@
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const { CacheHandler } = require("@nimpl/cache-redis/cache-handler");
 
-module.exports = new CacheHandler({ redisOptions: { connectionStrategy: "wait-exit" } });
+global.cacheHandler ||= new CacheHandler({ redisOptions: { connectionStrategy: "wait-exit" } });
+
+module.exports = global.cacheHandler;

examples/redis-cache/src/app/page.tsx

@@ -4,7 +4,7 @@ import { ClientTime } from "./client-time";
 
 export default async function Home() {
     "use cache";
-    cacheLife({ stale: 5, revalidate: 10, expire: 10000 });
+    cacheLife({ stale: 30, revalidate: 60, expire: 300 });
 
     const revalidateStateDate = new Date();
     await new Promise((resolve) => setTimeout(resolve, 5000));

packages/cache-redis/README.md

@@ -130,9 +130,11 @@ You can initialize the cache handler with custom configuration in an independent
 // cache-handlers/redis.js
 import { CacheHandler } from "@nimpl/cache-redis/cache-handler";
 
-module.exports = new CacheHandler(/* Options */);
+global.cacheHandler ||= new CacheHandler(/* Options */);
 ```
 
+> **Note**: It is recommended to write to `global`, as otherwise the instance will be created differently for Next.js and for your independent use (for example, for cache-widget or your internal utilities). As a result, in-memory entries will be different, and will also be duplicated
+
 ```ts
 import { type NextConfig } from "next/types";
 
@@ -206,6 +208,17 @@ Currently in Next.js background revalidation doesn't work correctly with dynamic
 
 In serverless environments, the `CacheHandler` is initialized on each request, which makes the in-memory LRU cache layer less usable since it's reset between invocations. The cache handler will still function correctly but will primarily rely on Redis for caching in these environments.
 
+## Examples
+
+- **[Base Example](https://github.com/alexdln/nimpl-cache/tree/main/examples/redis-cache)**
+  - Minimal Next.js example demonstrating redis cache handler and widget setup
+
+- **[React Router Example](https://router-bsky.contection.dev/)** - [View source code](https://github.com/alexdln/contection/tree/main/examples/react-router-bsky)
+  - Demonstrates cache widget integration with React Router 7 and redis cache handler
+
+- **[Next.js Example](https://bsky.contection.dev/)** - [View source code](https://github.com/alexdln/contection/tree/main/examples/nextjs-bsky)
+  - Shows cache widget usage in a Next.js cacheComponents application and redis cache handler
+
 ## License
 
 [MIT](https://github.com/alexdln/nimpl-cache/blob/main/LICENSE)

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

@@ -1,18 +1,19 @@
-import { type Durations, type Logger, type Entry, type LogData, type Options } from "./types";
+import { type Durations, type Logger, type Entry, type LogData, type Options, type CacheEntry } from "./types";
 import { logger as defaultLogger } from "./lib/logger";
 import { RedisLayer } from "./layers/redis-layer";
 import { LruLayer } from "./layers/lru-layer";
 import { PendingsLayer } from "./layers/pendings-layer";
 import { CacheError } from "./lib/error";
+import { calculateStreamSize } from "./lib/stream";
 
 export class CacheHandler {
     ephemeralLayer: LruLayer;
 
     persistentLayer: RedisLayer;
 
-    private pendingGetsLayer = new PendingsLayer<Entry | undefined | null>();
+    private pendingGetsLayer = new PendingsLayer<CacheEntry | undefined | null>();
 
-    private pendingSetsLayer = new PendingsLayer<Entry | undefined | null>();
+    private pendingSetsLayer = new PendingsLayer<CacheEntry | undefined | null>();
 
     private logger: Logger;
 
@@ -34,24 +35,24 @@ export class CacheHandler {
         this.logger({ type, status, source, key, message });
     }
 
-    async get(key: string) {
+    async getEntry(key: string): Promise<CacheEntry | undefined | null> {
         const pendingSet = await this.pendingSetsLayer.get(key);
         if (pendingSet === null) return undefined;
         if (pendingSet) {
             this.logOperation("GET", "REVALIDATED", "NEW", key);
-            const [cacheStream, responseStream] = pendingSet.value.tee();
-            pendingSet.value = cacheStream;
-            return { ...pendingSet, value: responseStream };
+            const [cacheStream, responseStream] = pendingSet.entry.value.tee();
+            pendingSet.entry.value = cacheStream;
+            return { entry: { ...pendingSet.entry, value: responseStream }, size: pendingSet.size, status: "valid" };
         }
 
-        const ephemeralCache = await this.ephemeralLayer.get(key);
+        const ephemeralCache = await this.ephemeralLayer.getEntry(key);
         if (ephemeralCache) {
             if (ephemeralCache.status === "revalidate") {
                 this.logOperation("GET", "REVALIDATING", "MEMORY", key);
                 return undefined;
             }
             this.logOperation("GET", "HIT", "MEMORY", key);
-            return ephemeralCache.entry;
+            return ephemeralCache;
         }
 
         const pendingGet = await this.pendingGetsLayer.get(key);
@@ -61,15 +62,15 @@ export class CacheHandler {
         }
         if (pendingGet) {
             this.logOperation("GET", "HIT", "REDIS", key);
-            const [cacheStream, responseStream] = pendingGet.value.tee();
-            pendingGet.value = cacheStream;
-            return { ...pendingGet, value: responseStream };
+            const [cacheStream, responseStream] = pendingGet.entry.value.tee();
+            pendingGet.entry.value = cacheStream;
+            return { entry: { ...pendingGet.entry, value: responseStream }, size: pendingGet.size, status: "valid" };
         }
 
         const resolvePending = this.pendingGetsLayer.set(key);
 
         try {
-            const persistentCache = await this.persistentLayer.get(key);
+            const persistentCache = await this.persistentLayer.getEntry(key);
 
             if (persistentCache === null) {
                 await this.persistentLayer.delete(key);
@@ -87,7 +88,7 @@ export class CacheHandler {
                 return undefined;
             }
 
-            const { entry, status } = persistentCache;
+            const { entry, size, status } = persistentCache;
             const [cacheStream, responseStream] = entry.value.tee();
             entry.value = cacheStream;
 
@@ -99,9 +100,9 @@ export class CacheHandler {
                 resolvePending(undefined);
                 return undefined;
             }
-            resolvePending(responseEntry);
+            resolvePending({ entry: responseEntry, size, status: "valid" });
             this.logOperation("GET", "HIT", "REDIS", key);
-            return responseEntry;
+            return { entry: responseEntry, size, status: "valid" };
         } catch (error) {
             this.logOperation("GET", "ERROR", "REDIS", key, error instanceof Error ? error.message : undefined);
             resolvePending(null);
@@ -110,6 +111,11 @@ export class CacheHandler {
         }
     }
 
+    async get(key: string): Promise<Entry | undefined | null> {
+        const cacheEntry = await this.getEntry(key);
+        return cacheEntry ? cacheEntry.entry : undefined;
+    }
+
     async set(key: string, pendingEntry: Promise<Entry>) {
         const resolvePending = this.pendingSetsLayer.set(key);
 
@@ -123,7 +129,10 @@ export class CacheHandler {
         try {
             await this.persistentLayer.set(key, { ...entry, value: cacheStreamPersistent });
 
-            resolvePending(entry);
+            const [responseStreamSize, responseStreamMain] = responseStream.tee();
+            entry.value = responseStreamMain;
+            const size = await calculateStreamSize(responseStreamSize);
+            resolvePending({ entry, size, status: "valid" });
             this.logOperation("SET", "REVALIDATED", "NEW", key);
         } catch (error) {
             resolvePending(undefined);
@@ -173,11 +182,11 @@ export class CacheHandler {
         return ephemeralReady && persistentReady;
     }
 
-    async keys(): Promise<{ ephemeralKeys: string[]; persistentKeys: string[] }> {
+    async keys(): Promise<string[]> {
         const [ephemeralKeys, persistentKeys] = await Promise.all([
             this.ephemeralLayer.keys(),
             this.persistentLayer.keys(),
         ]);
-        return { ephemeralKeys, persistentKeys };
+        return Array.from(new Set([...ephemeralKeys, ...persistentKeys]));
     }
 }

packages/cache-redis/src/layers/lru-layer.ts

@@ -3,6 +3,7 @@ import { LRUCache } from "lru-cache";
 import { type Options, type Logger, type Durations, type Entry, type CacheEntry } from "../types";
 import { DEFAULT_LRU_MAX_SIZE, DEFAULT_LRU_TTL } from "../lib/constants";
 import { getCacheStatus, getUpdatedMetadata } from "../lib/helpers";
+import { calculateStreamSize } from "../lib/stream";
 
 export class LruLayer {
     private lruClient: LRUCache<string, CacheEntry, unknown>;
@@ -12,27 +13,32 @@ export class LruLayer {
     private lruTtl: number | "auto";
 
     constructor(options: Options["lruOptions"], logger: Logger) {
-        const { ttl, ...lruOptions } = options || {};
-        this.lruTtl = (ttl ?? (process.env.LRU_TTL && parseInt(process.env.LRU_TTL)) ?? DEFAULT_LRU_TTL) || 0;
+        const { ttl, maxSize, ...lruOptions } = options || {};
+        const lruTtl = ttl ?? (process.env.LRU_TTL && parseInt(process.env.LRU_TTL)) ?? DEFAULT_LRU_TTL;
+        if (typeof lruTtl === "number") {
+            this.lruTtl = lruTtl;
+        } else {
+            this.lruTtl = "auto";
+        }
+
         this.logger = logger;
 
         this.lruClient = new LRUCache<string, CacheEntry, unknown>({
             maxSize:
-                options?.maxSize ||
-                (process.env.LRU_MAX_SIZE && parseInt(process.env.LRU_MAX_SIZE)) ||
-                DEFAULT_LRU_MAX_SIZE,
+                maxSize || (process.env.LRU_MAX_SIZE && parseInt(process.env.LRU_MAX_SIZE)) || DEFAULT_LRU_MAX_SIZE,
             sizeCalculation: (entry) => entry.size,
             ttlAutopurge: true,
-            ...(lruOptions || {}),
+            ...lruOptions,
         });
     }
 
     private calculateLruTtl(expire: number): number {
         return this.lruTtl === "auto" ? expire * 1000 : this.lruTtl * 1000;
     }
 
-    async get(key: string): Promise<CacheEntry | undefined | null> {
+    async getEntry(key: string): Promise<CacheEntry | undefined | null> {
         const memoryEntry = this.lruClient.get(key);
+
         if (!memoryEntry) return undefined;
 
         const { entry, size } = memoryEntry;
@@ -52,14 +58,16 @@ export class LruLayer {
         };
     }
 
+    async get(key: string): Promise<Entry | undefined | null> {
+        const cacheEntry = await this.getEntry(key);
+        return cacheEntry && cacheEntry.status === "valid" ? cacheEntry.entry : undefined;
+    }
+
     async set(key: string, pendingEntry: Promise<Entry> | Entry) {
         const entry = await pendingEntry;
         const [cacheStream, responseStream] = entry.value.tee();
         entry.value = responseStream;
-        let size = 0;
-        for await (const chunk of cacheStream) {
-            size += Buffer.byteLength(chunk);
-        }
+        const size = await calculateStreamSize(cacheStream);
         this.lruClient.set(
             key,
             { entry, size: size || 1, status: "valid" },
@@ -87,10 +95,6 @@ export class LruLayer {
     }
 
     async keys(): Promise<string[]> {
-        const keys: string[] = [];
-        this.lruClient.forEach((_, key) => {
-            keys.push(key);
-        });
-        return keys;
+        return Array.from(this.lruClient.keys());
     }
 }

packages/cache-redis/src/layers/redis-layer.ts

@@ -11,7 +11,7 @@ import {
 } from "../types";
 import { PREFIX_META } from "../lib/constants";
 import { getCacheKeys, getCacheStatus, getUpdatedMetadata } from "../lib/helpers";
-import { bufferToStream } from "../lib/stream";
+import { bufferToStream, streamToBuffer } from "../lib/stream";
 import { PendingsLayer } from "./pendings-layer";
 import { CacheConnectionError, CacheError } from "../lib/error";
 
@@ -147,7 +147,7 @@ export class RedisLayer {
         return isConnected;
     }
 
-    async get(key: string): Promise<CacheEntry | undefined | null> {
+    async getEntry(key: string): Promise<CacheEntry | undefined | null> {
         const connected = await this.connect();
         if (!connected) return undefined;
 
@@ -192,20 +192,20 @@ export class RedisLayer {
         return cacheEntry;
     }
 
+    async get(key: string): Promise<Entry | undefined | null> {
+        const cacheEntry = await this.getEntry(key);
+        return cacheEntry && cacheEntry.status === "valid" ? cacheEntry.entry : undefined;
+    }
+
     async set(key: string, pendingEntry: Promise<Entry> | Entry) {
         const connected = await this.connect();
         if (!connected) return;
 
         const entry = await pendingEntry;
         const { cacheKey, metaKey } = getCacheKeys(key, this.keyPrefix);
         const pipeline = this.redisClient.pipeline();
-        const chunks: Uint8Array[] = [];
-
-        for await (const chunk of entry.value) {
-            chunks.push(chunk);
-        }
 
-        pipeline.set(cacheKey, Buffer.concat(chunks), "EX", entry.expire);
+        pipeline.set(cacheKey, await streamToBuffer(entry.value), "EX", entry.expire);
         pipeline.set(
             metaKey,
             JSON.stringify({

packages/cache-redis/src/lib/stream.ts

@@ -22,3 +22,13 @@ export const bufferToStream = (buffer: Buffer): ReadableStream => {
         },
     });
 };
+
+export const calculateStreamSize = async (
+    stream: ReadableStream<Uint8Array> | WebReadableStream<Uint8Array>,
+): Promise<number> => {
+    let size = 0;
+    for await (const chunk of stream) {
+        size += chunk.byteLength;
+    }
+    return size;
+};

packages/cache-tools/README.md

@@ -57,8 +57,9 @@ Call `getCachedFeed` instead of the raw fetcher to reuse cached payloads across
 // app/api/cache-widget/route.ts (React Router)
 import { getCacheData } from "@/cache-handler";
 
-export const loader = async ({ params }: { params: { id?: string } }) => {
-  const data = await getCacheData(params.id ? [params.id] : undefined);
+export const loader = async ({ params }: { params: { "*"?: string } }) => {
+  const segments = params["*"]?.split("/").filter(Boolean) ?? [];
+  const data = await getCacheData(segments);
 
   if (!data) return new Response("", { status: 404 });
 
@@ -88,6 +89,17 @@ export const GET = async (
 
 Use `getCacheData` as the single entry point for the [widget](https://www.npmjs.com/package/@nimpl/cache-widget).
 
+## Examples
+
+- **[Base Example](https://github.com/alexdln/nimpl-cache/tree/main/examples/redis-cache)**
+  - Minimal Next.js example demonstrating redis cache handler and widget setup
+
+- **[React Router Example](https://router-bsky.contection.dev/)** - [View source code](https://github.com/alexdln/contection/tree/main/examples/react-router-bsky)
+  - Demonstrates cache widget integration with React Router 7 and redis cache handler
+
+- **[Next.js Example](https://bsky.contection.dev/)** - [View source code](https://github.com/alexdln/contection/tree/main/examples/nextjs-bsky)
+  - Shows cache widget usage in a Next.js cacheComponents application and redis cache handler
+
 ## License
 
 MIT