@raketa-cloud/next 1.0.9 → 1.1.0

package/README.md

@@ -0,0 +1,144 @@
+# @raketa-cloud/next
+
+Next.js integration library for **Raketa Cloud DXP**. Provides GraphQL API clients, in-memory LRU caching, and dynamic URL redirect helpers for Next.js App Router applications.
+
+---
+
+## Installation
+
+```bash
+npm install @raketa-cloud/next
+```
+
+Peer & runtime dependencies:
+
+```json
+{
+  "dependencies": {
+    "graphql-request": "^7.1.2",
+    "lru-cache": "^11.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}
+```
+
+---
+
+## Exports
+
+```javascript
+import {
+  Cache,
+  DxpPublic,
+  DxpPrivate,
+  generateCloudPublicHelpers,
+} from "@raketa-cloud/next";
+```
+
+---
+
+## Quick Reference
+
+### 1. In-Memory Cache (`Cache`)
+
+```javascript
+import { Cache } from "@raketa-cloud/next";
+
+const cache = new Cache({
+  max: 2500, // Max entries
+  maxSize: 300 * 1024 * 1024, // 300 MB budget
+  ttl: 1000 * 60 * 5, // 5 minutes
+  debugMode: false,
+});
+
+// Fetch with cache & stale-while-revalidate fallback:
+const data = await cache.fetch("my-cache-key", async () => {
+  return await fetchFromUpstream();
+});
+```
+
+### 2. Public DXP Client (`DxpPublic`)
+
+```javascript
+import { DxpPublic } from "@raketa-cloud/next";
+import getConfig from "lib/getConfig";
+import localCache from "./localCache";
+
+const dxpPublic = new DxpPublic(getConfig, localCache);
+
+// Find a single resource (e.g. page, article, customer)
+const page = await dxpPublic.resources.find("en", "about-us", "page", {
+  withCache: true,
+});
+
+// List resources with filters & pagination
+const articles = await dxpPublic.resources.list("en", {
+  pagination: { page: 1, pageSize: 10 },
+  filters: { resourceType: "article", tagSlugs: ["news"] },
+});
+
+// Fetch website settings
+const settings = await dxpPublic.settings.find("en", { withCache: true });
+
+// Fetch a tag
+const tag = await dxpPublic.tags.find("en", "technology", { withCache: true });
+
+// Custom GraphQL query
+const queryDoc = dxpPublic.client.gql`
+  query MyQuery($input: ResourcesInput!) {
+    resources(input: $input) {
+      list { id title slug }
+    }
+  }
+`;
+const result = await dxpPublic.client.query(queryDoc, {
+  input: { locale: "en" },
+});
+```
+
+### 3. Dynamic Redirects Helper (`generateCloudPublicHelpers`)
+
+```javascript
+import { DxpPublic, generateCloudPublicHelpers } from "@raketa-cloud/next";
+import getConfig from "lib/getConfig";
+import redirectsCache from "./redirectsCache";
+
+const dxpRedirects = new DxpPublic(getConfig, redirectsCache);
+const { findRedirect } = generateCloudPublicHelpers(dxpRedirects);
+
+// In Next.js middleware:
+const redirect = await findRedirect("/old-path");
+// returns: { id, url, destination, httpResponseCode } | null
+```
+
+### 4. Private DXP Client (`DxpPrivate`)
+
+```javascript
+import { DxpPrivate } from "@raketa-cloud/next";
+import getConfig from "lib/getConfig";
+
+// Server-side (with token resolver function)
+const dxpPrivate = new DxpPrivate(getConfig, async () => {
+  return getAdminTokenFromCookies();
+});
+
+// Change preview for visual builder
+const preview = await dxpPrivate.resources.changePreview(
+  "en",
+  resourceId,
+  versionNumber,
+  "page",
+);
+
+// Mini-resources list for admin pickers
+const miniList = await dxpPrivate.resources.miniResources("en", {
+  filters: { resourceType: "page" },
+});
+```
+
+---
+
+## Documentation
+
+For a comprehensive guide with complete project structure and Next.js App Router patterns, see the [Monorepo README](../../README.md).

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@raketa-cloud/next",
-  "version": "1.0.9",
+  "version": "1.1.0",
+  "type": "module",
   "main": "src/index.js",
   "repository": {
     "type": "git",
@@ -8,15 +9,16 @@
     "directory": "packages/raketa-cloud-next"
   },
   "scripts": {
+    "test": "node --test test/**/*.test.js",
     "check-types": "tsc --noEmit",
     "format": "prettier --write src/**/*.js"
   },
   "devDependencies": {
     "@repo/typescript-config": "*",
-    "@turbo/gen": "^1.12.4",
+    "@turbo/gen": "^2.10.13",
     "@types/node": "^20.11.24",
-    "@types/react": "18.3.0",
-    "@types/react-dom": "18.3.1",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "prettier": "^3.8.3",
     "typescript": "5.5.4"
   },

package/src/Cache.js

@@ -7,7 +7,7 @@ function getApproximateMemoryUsage(obj) {
   const seen = new WeakSet();
 
   function sizeOf(value) {
-    // 1. Handle null and undefined explicitly (This fixes your error!)
+    // 1. Handle null and undefined explicitly
     if (value === null || value === undefined) return 0;
 
     // 2. Handle primitives based on JS specs
@@ -41,8 +41,6 @@ function getApproximateMemoryUsage(obj) {
 
 export default class Cache {
   constructor(opts = {}) {
-    const self = this;
-
     const cacheOptions = {
       max: opts.max || 5000, // Items count
       ttl: opts.ttl || 1000 * 60 * 5, // 5 minutes
@@ -50,18 +48,18 @@ export default class Cache {
       noDeleteOnStaleGet: true,
     };
 
-    // Conditionally use the memrory calculation since it is veery flaky and inaccurate...
+    // Conditionally use the memory calculation
     if (opts.maxSize) {
       cacheOptions.maxSize = opts.maxSize;
 
       cacheOptions.sizeCalculation = (value, key) => {
         return getApproximateMemoryUsage(key) + getApproximateMemoryUsage(value);
       };
-
     }
 
     this.debugMode = opts.debugMode || false;
     this.cacheInstance = new LRUCache(cacheOptions);
+    this.inFlight = new Map();
   }
 
   _debug(msg) {
@@ -82,31 +80,41 @@ export default class Cache {
   }
 
   _cloneObject(obj) {
-    if (obj === null || obj === undefined) {
-      return obj;
-    }
-
-    const type = typeof obj;
-
-    if (type !== "function" || type !== "obj") {
+    if (obj === null || obj === undefined || typeof obj !== "object") {
       return obj;
     }
 
-    // Ah the JS world! See the official docs https://developer.mozilla.org/en-US/docs/Glossary/Deep_copy.
-    // Important note - this works only for objects with primitive types to copy. If an object property is
-    // a function - well it will not work correctly...
     return JSON.parse(JSON.stringify(obj));
   }
 
-  _setInCache(key, value) {
+  _setInCache(key, value, opts) {
     this.cacheInstance.set(
       key,
-      value ? this._cloneObject(value) : NULL_SENTINEL
+      value !== null && value !== undefined ? this._cloneObject(value) : NULL_SENTINEL,
+      opts
     );
   }
 
   clear() {
     this.cacheInstance.clear();
+    this.inFlight.clear();
+  }
+
+  delete(key) {
+    return this.cacheInstance.delete(key);
+  }
+
+  has(key) {
+    return this.cacheInstance.has(key);
+  }
+
+  get(key) {
+    const { cachedValue } = this._fetchFromCache(key);
+    return this._cloneObject(cachedValue);
+  }
+
+  set(key, value, opts) {
+    this._setInCache(key, value, opts);
   }
 
   forEach(callback) {
@@ -125,48 +133,77 @@ export default class Cache {
     return this.cacheInstance.maxSize;
   }
 
+  get inFlightCount() {
+    return this.inFlight.size;
+  }
+
+  get inFlightKeys() {
+    return Array.from(this.inFlight.keys());
+  }
+
+  async _revalidateInBackground(cacheKey, fetcher, staleValue) {
+    if (this.inFlight.has(cacheKey)) {
+      return;
+    }
+
+    const promise = (async () => {
+      try {
+        const freshEntity = await fetcher();
+        this._setInCache(cacheKey, freshEntity);
+        return freshEntity;
+      } catch (e) {
+        if (this.debugMode) {
+          console.error(`[Cache] Background revalidation failed for "${cacheKey}":`, e);
+        }
+        // Refresh TTL for the stale value so subsequent immediate requests don't hammer the backend
+        this._setInCache(cacheKey, staleValue);
+      } finally {
+        this.inFlight.delete(cacheKey);
+      }
+    })();
+
+    this.inFlight.set(cacheKey, promise);
+  }
+
   async fetch(cacheKey, fetcher) {
     const { cachedValue, status } = this._fetchFromCache(cacheKey);
 
+    // 1. Cache HIT: Return immediately
     if (status.get === "hit") {
       this._debug(`Cache HIT: ${cacheKey}`);
       return this._cloneObject(cachedValue);
     }
 
+    // 2. Cache STALE: Return stale value immediately and revalidate in background
     if (status.get === "stale") {
-      this._debug(`Cache STALE: ${cacheKey}`);
+      this._debug(`Cache STALE (serving stale, revalidating in background): ${cacheKey}`);
+      this._revalidateInBackground(cacheKey, fetcher, cachedValue);
+      return this._cloneObject(cachedValue);
+    }
 
+    // 3. Cache MISS: Singleflight deduplication for concurrent requests
+    this._debug(`Cache MISS: ${cacheKey}`);
+    if (this.inFlight.has(cacheKey)) {
+      this._debug(`Cache MISS (joining in-flight fetch): ${cacheKey}`);
+      return this.inFlight.get(cacheKey);
+    }
+
+    const promise = (async () => {
       try {
         const freshEntity = await fetcher();
-
         this._setInCache(cacheKey, freshEntity);
-
         return this._cloneObject(freshEntity);
       } catch (e) {
-        console.error(e);
-
-        // Reset TTL
-        this._setInCache(cacheKey, cachedValue);
-
-        return this._cloneObject(cachedValue);
+        if (this.debugMode) {
+          console.error(`[Cache] Fetch failed for "${cacheKey}":`, e);
+        }
+        throw e;
+      } finally {
+        this.inFlight.delete(cacheKey);
       }
-    }
-
-    try {
-      this._debug(`Cache MISS: ${cacheKey}`);
-
-      const freshEntity = await fetcher();
+    })();
 
-      this._setInCache(cacheKey, freshEntity);
-
-      return this._cloneObject(freshEntity);
-    } catch (e) {
-      console.error(e);
-
-      // Reset TTL
-      this._setInCache(cacheKey, cachedValue);
-
-      return this._cloneObject(cachedValue);
-    }
+    this.inFlight.set(cacheKey, promise);
+    return promise;
   }
 }

package/test/Cache.test.js

@@ -0,0 +1,300 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import Cache from "../src/Cache.js";
+
+describe("Cache", () => {
+  describe("Basic Caching (Miss & Hit)", () => {
+    it("should fetch and store value on cache miss, then return from cache on hit", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      let fetchCount = 0;
+      const fetcher = async () => {
+        fetchCount++;
+        return { id: 1, title: "Homepage", metadata: { published: true } };
+      };
+
+      // 1. Cache Miss
+      const result1 = await cache.fetch("page-home", fetcher);
+      assert.deepEqual(result1, { id: 1, title: "Homepage", metadata: { published: true } });
+      assert.equal(fetchCount, 1);
+
+      // 2. Cache Hit
+      const result2 = await cache.fetch("page-home", fetcher);
+      assert.deepEqual(result2, { id: 1, title: "Homepage", metadata: { published: true } });
+      assert.equal(fetchCount, 1, "Fetcher must not be called again on cache hit");
+    });
+
+    it("should correctly handle primitive, null, and falsy values", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+
+      // Null value
+      let nullFetches = 0;
+      const nullFetcher = async () => {
+        nullFetches++;
+        return null;
+      };
+      assert.equal(await cache.fetch("null-val", nullFetcher), null);
+      assert.equal(await cache.fetch("null-val", nullFetcher), null);
+      assert.equal(nullFetches, 1);
+
+      // Boolean false
+      let boolFetches = 0;
+      const boolFetcher = async () => {
+        boolFetches++;
+        return false;
+      };
+      assert.equal(await cache.fetch("bool-val", boolFetcher), false);
+      assert.equal(await cache.fetch("bool-val", boolFetcher), false);
+      assert.equal(boolFetches, 1);
+
+      // Number 0
+      let numFetches = 0;
+      const numFetcher = async () => {
+        numFetches++;
+        return 0;
+      };
+      assert.equal(await cache.fetch("num-val", numFetcher), 0);
+      assert.equal(await cache.fetch("num-val", numFetcher), 0);
+      assert.equal(numFetches, 1);
+
+      // Empty string
+      let strFetches = 0;
+      const strFetcher = async () => {
+        strFetches++;
+        return "";
+      };
+      assert.equal(await cache.fetch("str-val", strFetcher), "");
+      assert.equal(await cache.fetch("str-val", strFetcher), "");
+      assert.equal(strFetches, 1);
+    });
+  });
+
+  describe("Singleflight / In-Flight Request Deduplication", () => {
+    it("should deduplicate concurrent requests on cache miss to a single backend call", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      let backendCalls = 0;
+      const slowFetcher = async () => {
+        backendCalls++;
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        return { data: "singleflight-result", timestamp: Date.now() };
+      };
+
+      // 10 concurrent requests for the same uncached key
+      const requests = Array.from({ length: 10 }, () =>
+        cache.fetch("concurrent-miss-key", slowFetcher)
+      );
+
+      const results = await Promise.all(requests);
+
+      // Exactly 1 backend call made
+      assert.equal(backendCalls, 1);
+      assert.equal(results.length, 10);
+
+      // All callers receive identical data
+      const firstTimestamp = results[0].timestamp;
+      for (const r of results) {
+        assert.equal(r.data, "singleflight-result");
+        assert.equal(r.timestamp, firstTimestamp);
+      }
+
+      // In-flight map should be empty after completion
+      assert.equal(cache.inFlightCount, 0);
+    });
+
+    it("should propagate errors to all waiting concurrent callers on cache miss", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      let backendCalls = 0;
+      const failingFetcher = async () => {
+        backendCalls++;
+        await new Promise((resolve) => setTimeout(resolve, 30));
+        throw new Error("Upstream Network Timeout");
+      };
+
+      // 5 concurrent requests expecting failure
+      const requests = Array.from({ length: 5 }, () =>
+        cache.fetch("failing-key", failingFetcher)
+      );
+
+      const results = await Promise.allSettled(requests);
+
+      assert.equal(backendCalls, 1);
+      for (const res of results) {
+        assert.equal(res.status, "rejected");
+        assert.equal(res.reason.message, "Upstream Network Timeout");
+      }
+
+      // In-flight map is properly cleaned up after failure
+      assert.equal(cache.inFlightCount, 0);
+
+      // Subsequent attempt can retry
+      const successFetcher = async () => ({ recovered: true });
+      const recovery = await cache.fetch("failing-key", successFetcher);
+      assert.deepEqual(recovery, { recovered: true });
+    });
+  });
+
+  describe("Stale-While-Revalidate (SWR)", () => {
+    it("should return stale value instantly without waiting for revalidation", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      let fetchCount = 0;
+      const initialFetcher = async () => {
+        fetchCount++;
+        return { version: 1, payload: "initial" };
+      };
+
+      // Initial populate
+      await cache.fetch("swr-instant-key", initialFetcher);
+      assert.equal(fetchCount, 1);
+
+      // Wait 120ms (TTL is 100ms) to become stale
+      await new Promise((resolve) => setTimeout(resolve, 120));
+
+      let backgroundRan = false;
+      const slowRevalidator = async () => {
+        backgroundRan = true;
+        fetchCount++;
+        await new Promise((resolve) => setTimeout(resolve, 80));
+        return { version: 2, payload: "fresh" };
+      };
+
+      // Fetch on stale: must return version 1 IMMEDIATELY (< 15ms), not blocking on 80ms
+      const start = Date.now();
+      const staleResult = await cache.fetch("swr-instant-key", slowRevalidator);
+      const elapsed = Date.now() - start;
+
+      assert.ok(elapsed < 20, `Stale return took ${elapsed}ms; expected < 20ms`);
+      assert.deepEqual(staleResult, { version: 1, payload: "initial" });
+
+      // Wait 100ms for background revalidation to complete
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      assert.ok(backgroundRan, "Background revalidator must have executed");
+      assert.equal(fetchCount, 2);
+
+      // Next request should now get the freshly revalidated data (version 2)
+      const freshResult = await cache.fetch("swr-instant-key", initialFetcher);
+      assert.deepEqual(freshResult, { version: 2, payload: "fresh" });
+      assert.equal(fetchCount, 2, "Fresh hit should not invoke fetcher");
+    });
+
+    it("should deduplicate multiple concurrent requests on a stale entry to 1 background revalidation", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      let revalidateCount = 0;
+      await cache.fetch("swr-concurrent-key", async () => ({ v: "v1" }));
+
+      // Wait for key to become stale
+      await new Promise((resolve) => setTimeout(resolve, 120));
+
+      const slowRevalidator = async () => {
+        revalidateCount++;
+        await new Promise((resolve) => setTimeout(resolve, 60));
+        return { v: "v2" };
+      };
+
+      // 10 concurrent requests on stale key
+      const results = await Promise.all(
+        Array.from({ length: 10 }, () =>
+          cache.fetch("swr-concurrent-key", slowRevalidator)
+        )
+      );
+
+      // All 10 requests immediately received the stale value
+      for (const res of results) {
+        assert.deepEqual(res, { v: "v1" });
+      }
+
+      // Wait for background revalidation to finish
+      await new Promise((resolve) => setTimeout(resolve, 80));
+
+      // Exactly 1 background revalidation ran
+      assert.equal(revalidateCount, 1);
+      assert.equal(cache.inFlightCount, 0);
+
+      // Cache now has fresh value
+      assert.deepEqual(cache.get("swr-concurrent-key"), { v: "v2" });
+    });
+
+    it("should retain stale value and refresh TTL when background revalidation fails (429 resilience)", async () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+      await cache.fetch("swr-429-key", async () => ({ status: "good-data" }));
+
+      // Wait to become stale
+      await new Promise((resolve) => setTimeout(resolve, 120));
+
+      // Background revalidation throws upstream 429
+      const failingRevalidator = async () => {
+        throw new Error("GraphQL Error (Code: 429): Too Many Requests");
+      };
+
+      // Caller receives stale data safely without throwing
+      const staleResult = await cache.fetch("swr-429-key", failingRevalidator);
+      assert.deepEqual(staleResult, { status: "good-data" });
+
+      // Wait for background promise to complete error handling
+      await new Promise((resolve) => setTimeout(resolve, 30));
+
+      // Cache still preserves the stale data and cleared inFlight
+      assert.deepEqual(cache.get("swr-429-key"), { status: "good-data" });
+      assert.equal(cache.inFlightCount, 0);
+      assert.ok(cache.getRemainingTTL("swr-429-key") > 0, "TTL should be refreshed for stale entry");
+    });
+  });
+
+  describe("Lifecycle & Utility Methods", () => {
+    it("should support get, set, delete, has, and clear", () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+
+      cache.set("item-1", { a: 1 });
+      assert.ok(cache.has("item-1"));
+      assert.deepEqual(cache.get("item-1"), { a: 1 });
+
+      cache.delete("item-1");
+      assert.ok(!cache.has("item-1"));
+      assert.equal(cache.get("item-1"), undefined);
+
+      cache.set("a", 1);
+      cache.set("b", 2);
+      cache.set("c", 3);
+      assert.equal(cache.has("a"), true);
+      assert.equal(cache.has("b"), true);
+
+      cache.clear();
+      assert.equal(cache.has("a"), false);
+      assert.equal(cache.has("b"), false);
+      assert.equal(cache.has("c"), false);
+      assert.equal(cache.inFlightCount, 0);
+    });
+
+    it("should support forEach iteration and TTL checking", () => {
+      const cache = new Cache({ ttl: 100, debugMode: false });
+
+      cache.set("alpha", { value: 10 });
+      cache.set("beta", { value: 20 });
+
+      const keys = [];
+      cache.forEach((_val, key) => {
+        keys.push(key);
+      });
+
+      assert.ok(keys.includes("alpha"));
+      assert.ok(keys.includes("beta"));
+
+      const ttl = cache.getRemainingTTL("alpha");
+      assert.ok(typeof ttl === "number" && ttl > 0);
+    });
+
+    it("should calculate approximate memory size when maxSize is configured", () => {
+      const sizedCache = new Cache({
+        maxSize: 10 * 1024 * 1024, // 10MB
+        ttl: 5000,
+      });
+
+      sizedCache.set("large-obj", {
+        title: "Test",
+        items: [1, 2, 3, 4, 5],
+        nested: { active: true },
+      });
+
+      assert.ok(sizedCache.calculatedSize > 0, "calculatedSize must be greater than 0");
+      assert.equal(sizedCache.maxSize, 10 * 1024 * 1024);
+    });
+  });
+});

package/tsconfig.json

@@ -1,7 +1,8 @@
 {
   "extends": "@repo/typescript-config/react-library.json",
   "compilerOptions": {
-    "outDir": "dist"
+    "outDir": "dist",
+    "allowJs": true
   },
   "include": ["src"],
   "exclude": ["node_modules", "dist"]