@decocms/blocks 7.14.0 → 7.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.14.0",
+  "version": "7.15.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/sdk/cachedLoader.ts

@@ -19,6 +19,7 @@ import {
 } from "../middleware/observability";
 import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
 import { withInflightTimeout } from "./inflightTimeout";
+import { RequestContext } from "./requestContext";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
 
@@ -32,12 +33,26 @@ export interface CachedLoaderOptions {
   keyFn?: (props: unknown) => string;
 }
 
+/**
+ * The `@decocms/apps` loader/action module shape: a `default` loader plus the
+ * optional `cache` / `cacheKey` exports Fresh loaders ship with.
+ *
+ *   export const cache = "stale-while-revalidate";
+ *   export const cacheKey = (props, req) => `${new URL(req.url).pathname}...`;
+ *
+ * `cache` is the OPT-IN: absent (or `"no-store"`) means the loader runs on every
+ * invocation, matching `@decocms/apps`' default. Any other value opts the loader
+ * into single-flight dedup (concurrent identical calls in one render collapse to
+ * one upstream call — the #339 N+1 fix). `cacheKey` computes the dedup identity
+ * from `(props, req)`; returning `null` means "do not dedup, run fresh".
+ */
 export interface LoaderModule<TProps = any, TResult = any> {
-  default: (props: TProps) => Promise<TResult>;
+  default: (props: TProps, req?: Request) => Promise<TResult>;
   cache?: CachePolicy | { maxAge: number };
-  cacheKey?: (props: TProps) => string | null;
+  cacheKey?: (props: TProps, req?: Request) => string | null;
 }
 
+
 interface CacheEntry<T = unknown> {
   value: T;
   createdAt: number;
@@ -307,43 +322,105 @@ export function createCachedLoader<TProps, TResult>(
   };
 }
 
+
+// ---------------------------------------------------------------------------
+// Module loader dedup (the `@decocms/apps` cache/cacheKey convention)
+//
+// Distinct from `createCachedLoader` above (VTEX's byte-capped SWR cache): the
+// module path is DEDUP-ONLY. A loader that opts in via `export const cache`
+// gets single-flight — concurrent identical invocations in one render (N
+// sections referencing the same loader) share one upstream call — but nothing
+// is retained past settlement, so there is zero cross-request staleness. This
+// is the deliberately-conservative fix for the #339 N+1 (2–3× product GraphQL
+// per PDP render) without the SWR machinery's stale-serving semantics.
+// ---------------------------------------------------------------------------
+
+const moduleInflight = new Map<string, Promise<unknown>>();
+
 /**
- * Create a cached loader from a module that exports `cache` and/or `cacheKey`.
- * Falls back to the provided defaults if the module doesn't declare them.
+ * Wrap an `@decocms/apps`-shaped loader module so its `cache`/`cacheKey` exports
+ * drive single-flight dedup. Loaders without a `cache` export (or `"no-store"`)
+ * are returned unwrapped — they run on every call, matching apps' default.
+ *
+ * The dedup key is `${name}::${cacheKey(props, req)}`; `req` comes from the
+ * caller or, on the CMS-resolution path (which passes only props), from
+ * `RequestContext.current` — both execute inside the same AsyncLocalStorage
+ * scope. `cacheKey` returning `null`, or `req` being unavailable when `cacheKey`
+ * needs it, falls back to running fresh / keying on `JSON.stringify(props)`.
  */
 export function createCachedLoaderFromModule<TProps, TResult>(
   name: string,
   mod: LoaderModule<TProps, TResult>,
-  defaults?: Partial<CachedLoaderOptions>,
-): (props: TProps) => Promise<TResult> {
-  const moduleCache = mod.cache;
-  let policy: CachePolicy;
-  let maxAge: number | undefined;
-
-  if (typeof moduleCache === "string") {
-    policy = moduleCache;
-  } else if (moduleCache && typeof moduleCache === "object") {
-    policy = "stale-while-revalidate";
-    maxAge = moduleCache.maxAge;
-  } else {
-    policy = defaults?.policy ?? "stale-while-revalidate";
-  }
+): (props: TProps, req?: Request) => Promise<TResult> {
+  const policy: CachePolicy = typeof mod.cache === "string"
+    ? mod.cache
+    : mod.cache && typeof mod.cache === "object"
+      ? "stale-while-revalidate"
+      : "no-store";
+
+  // Only `stale-while-revalidate` (or `{ maxAge }`) opts into dedup — matching
+  // `@decocms/apps`/deco, where `no-store` (the default) and `no-cache` both
+  // bypass single-flight and run on every call. Return unwrapped otherwise.
+  if (policy !== "stale-while-revalidate") return mod.default;
+
+  const cacheKeyFn = mod.cacheKey;
+
+  return (props: TProps, req?: Request): Promise<TResult> => {
+    const request = req ?? RequestContext.current?.request ?? undefined;
+
+    let keyPart: string | null;
+    if (cacheKeyFn) {
+      // A cacheKey that dereferences `req` (e.g. `new URL(req.url)`) would throw
+      // when the request is unavailable — fall back to props-hash dedup instead.
+      keyPart = request ? cacheKeyFn(props, request) : JSON.stringify(props);
+    } else {
+      keyPart = JSON.stringify(props);
+    }
 
-  maxAge = maxAge ?? defaults?.maxAge;
+    // Explicit null → the loader declared this call uncacheable: run fresh.
+    if (keyPart === null) return mod.default(props, req);
 
-  const keyFn = mod.cacheKey
-    ? (props: unknown) => {
-        const key = mod.cacheKey!(props as TProps);
-        return key ?? JSON.stringify(props);
-      }
-    : defaults?.keyFn;
-
-  return createCachedLoader(name, mod.default, {
-    policy,
-    maxAge,
-    staleIfError: defaults?.staleIfError,
-    keyFn,
-  });
+    const key = `${name}::${keyPart}`;
+    const existing = moduleInflight.get(key) as Promise<TResult> | undefined;
+    if (existing) return existing;
+
+    const promise = Promise.resolve(mod.default(props, req)).finally(() => {
+      moduleInflight.delete(key);
+    });
+    moduleInflight.set(key, promise);
+    return promise;
+  };
+}
+
+/**
+ * Registry entry factory for generated loader maps (`.deco/loaders.gen.ts`).
+ * Lazily imports the loader module on first call, then delegates to a memoized
+ * `createCachedLoaderFromModule` wrapper so `cache`/`cacheKey` exports take
+ * effect. Keeps generated code a one-liner while the dedup logic stays here,
+ * unit-tested, in the framework.
+ */
+export function createLoaderEntry<TProps = any, TResult = any>(
+  name: string,
+  importFn: () => Promise<LoaderModule<TProps, TResult>>,
+): (props: TProps, req?: Request) => Promise<TResult> {
+  // Memoize the import+build PROMISE (not the resolved wrapper) so concurrent
+  // first-calls — exactly the N-sections-per-render case — share one import
+  // instead of racing into N. Reset on failure so a transient import error can
+  // retry rather than poisoning the entry forever.
+  let wrappedPromise:
+    | Promise<(props: TProps, req?: Request) => Promise<TResult>>
+    | undefined;
+  return (props: TProps, req?: Request): Promise<TResult> => {
+    if (!wrappedPromise) {
+      wrappedPromise = importFn()
+        .then((mod) => createCachedLoaderFromModule(name, mod))
+        .catch((err) => {
+          wrappedPromise = undefined;
+          throw err;
+        });
+    }
+    return wrappedPromise.then((wrapped) => wrapped(props, req));
+  };
 }
 
 /** Clear all cached entries. Useful for decofile hot-reload. */
@@ -351,6 +428,7 @@ export function clearLoaderCache() {
   cache.clear();
   cacheBytes = 0;
   inflightRequests.clear();
+  moduleInflight.clear();
 }
 
 /** Get cache stats for diagnostics. */

package/src/sdk/cachedLoaderModule.test.ts

@@ -0,0 +1,209 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  clearLoaderCache,
+  createCachedLoaderFromModule,
+  createLoaderEntry,
+  type LoaderModule,
+} from "./cachedLoader";
+import { RequestContext } from "./requestContext";
+
+/** A loader whose `default` we can count calls on and control resolution of. */
+function makeLoader<T>(result: T) {
+  let resolve!: (v: T) => void;
+  const gate = new Promise<T>((r) => (resolve = r));
+  const fn = vi.fn(async (_props: unknown, _req?: Request) => {
+    await gate;
+    return result;
+  });
+  return { fn, release: () => resolve(result) };
+}
+
+afterEach(() => {
+  clearLoaderCache();
+  vi.restoreAllMocks();
+});
+
+describe("createCachedLoaderFromModule — dedup-only (no SWR)", () => {
+  it("runs on every call when the module has no `cache` export (apps no-store default)", async () => {
+    const { fn, release } = makeLoader("x");
+    release();
+    const mod: LoaderModule = { default: fn };
+    const loader = createCachedLoaderFromModule("site/loaders/plain", mod);
+
+    // No wrap at all → returns the original function identity.
+    expect(loader).toBe(fn);
+
+    await loader({ a: 1 });
+    await loader({ a: 1 });
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("runs on every call for `no-cache` (only stale-while-revalidate opts into dedup)", async () => {
+    const { fn, release } = makeLoader("x");
+    const mod: LoaderModule = { default: fn, cache: "no-cache" };
+    const loader = createCachedLoaderFromModule("site/loaders/nocache", mod);
+
+    expect(loader).toBe(fn);
+    const p1 = loader({ a: 1 });
+    const p2 = loader({ a: 1 });
+    release();
+    await Promise.all([p1, p2]);
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("collapses concurrent identical calls into ONE upstream call when `cache` opts in", async () => {
+    const { fn, release } = makeLoader("shelf");
+    const mod: LoaderModule = { default: fn, cache: "stale-while-revalidate" };
+    const loader = createCachedLoaderFromModule("site/loaders/related", mod);
+
+    // Three sections on one render invoke the same loader concurrently.
+    const p1 = loader({ slug: "abc" });
+    const p2 = loader({ slug: "abc" });
+    const p3 = loader({ slug: "abc" });
+    release();
+    const [r1, r2, r3] = await Promise.all([p1, p2, p3]);
+
+    expect(r1).toBe("shelf");
+    expect(r2).toBe("shelf");
+    expect(r3).toBe("shelf");
+    // The #339 N+1 fix: 3 concurrent references → 1 upstream call.
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does NOT retain results across settlement (no cross-request staleness)", async () => {
+    const { fn, release } = makeLoader("v");
+    release();
+    const mod: LoaderModule = { default: fn, cache: "stale-while-revalidate" };
+    const loader = createCachedLoaderFromModule("site/loaders/nostale", mod);
+
+    await loader({ slug: "abc" });
+    // Sequential (non-concurrent) call after the first settled → re-runs.
+    await loader({ slug: "abc" });
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("dedups by the module's custom cacheKey(props, req), not raw props", async () => {
+    const { fn, release } = makeLoader("p");
+    const mod: LoaderModule = {
+      default: fn,
+      cache: "stale-while-revalidate",
+      // Key only on pathname — ignores tracking params on the URL.
+      cacheKey: (_props, req) => new URL(req!.url).pathname,
+    };
+    const loader = createCachedLoaderFromModule("site/loaders/pdp", mod);
+
+    const reqA = new Request("https://x.test/produto?utm_source=a");
+    const reqB = new Request("https://x.test/produto?utm_source=b");
+    const p1 = loader({ id: 1 }, reqA);
+    const p2 = loader({ id: 2 }, reqB); // different props + url, same pathname
+    release();
+    await Promise.all([p1, p2]);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs fresh (no dedup) when cacheKey returns null", async () => {
+    const { fn, release } = makeLoader("p");
+    const mod: LoaderModule = {
+      default: fn,
+      cache: "stale-while-revalidate",
+      cacheKey: () => null,
+    };
+    const loader = createCachedLoaderFromModule("site/loaders/personalized", mod);
+
+    const req = new Request("https://x.test/");
+    const p1 = loader({ id: 1 }, req);
+    const p2 = loader({ id: 1 }, req);
+    release();
+    await Promise.all([p1, p2]);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it("sources req from RequestContext when the caller passes none (CMS-resolution path)", async () => {
+    const { fn, release } = makeLoader("p");
+    const seen: string[] = [];
+    const mod: LoaderModule = {
+      default: fn,
+      cache: "stale-while-revalidate",
+      cacheKey: (_props, req) => {
+        seen.push(new URL(req!.url).pathname);
+        return new URL(req!.url).pathname;
+      },
+    };
+    const loader = createCachedLoaderFromModule("site/loaders/ctx", mod);
+
+    const req = new Request("https://x.test/categoria");
+    await RequestContext.run(req, async () => {
+      // Called with ONLY props, mirroring resolve.ts internalResolve.
+      const p1 = loader({ a: 1 });
+      const p2 = loader({ a: 1 });
+      release();
+      await Promise.all([p1, p2]);
+    });
+
+    expect(seen).toContain("/categoria");
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to props-hash dedup when cacheKey needs req but none is available", async () => {
+    const { fn, release } = makeLoader("p");
+    const mod: LoaderModule = {
+      default: fn,
+      cache: "stale-while-revalidate",
+      // Would throw on undefined req — the wrapper must not call it without one.
+      cacheKey: (_props, req) => new URL(req!.url).pathname,
+    };
+    const loader = createCachedLoaderFromModule("site/loaders/noreq", mod);
+
+    // No req arg, no RequestContext scope.
+    const p1 = loader({ a: 1 });
+    const p2 = loader({ a: 1 });
+    release();
+    await expect(Promise.all([p1, p2])).resolves.toEqual(["p", "p"]);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("propagates loader errors and clears the in-flight entry", async () => {
+    const err = new Error("upstream down");
+    const fn = vi.fn(async () => {
+      throw err;
+    });
+    const mod: LoaderModule = { default: fn, cache: "stale-while-revalidate" };
+    const loader = createCachedLoaderFromModule("site/loaders/boom", mod);
+
+    await expect(loader({ a: 1 })).rejects.toThrow("upstream down");
+    // A retry after failure is not blocked by a stuck in-flight entry.
+    await expect(loader({ a: 1 })).rejects.toThrow("upstream down");
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createLoaderEntry — lazy import + wrap", () => {
+  it("imports the module once and dedups concurrent calls", async () => {
+    const { fn, release } = makeLoader("lazy");
+    const importFn = vi.fn(async () => ({
+      default: fn,
+      cache: "stale-while-revalidate" as const,
+    }));
+    const entry = createLoaderEntry("site/loaders/lazy", importFn);
+
+    const p1 = entry({ a: 1 });
+    const p2 = entry({ a: 1 });
+    release();
+    await Promise.all([p1, p2]);
+
+    expect(importFn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes non-opted-in loaders straight through", async () => {
+    const { fn, release } = makeLoader("plain");
+    release();
+    const entry = createLoaderEntry("site/loaders/plain", async () => ({ default: fn }));
+
+    await entry({ a: 1 });
+    await entry({ a: 1 });
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+});