@decocms/blocks 8.0.0 → 8.1.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/bin/deco.js +13 -0
  2. package/package.json +32 -82
  3. package/src/index.ts +35 -8
  4. package/src/protocol/assets.ts +124 -0
  5. package/src/protocol/canonical.ts +7 -0
  6. package/src/protocol/ciphertext.ts +6 -0
  7. package/src/protocol/client.ts +170 -0
  8. package/src/protocol/conformance/cases/assets.ts +81 -0
  9. package/src/protocol/conformance/cases/guards.ts +314 -0
  10. package/src/protocol/conformance/cases/reads.ts +168 -0
  11. package/src/protocol/conformance/cases/types.ts +9 -0
  12. package/src/protocol/conformance/cases/wire.ts +138 -0
  13. package/src/protocol/conformance/cases/writes.ts +345 -0
  14. package/src/protocol/conformance/contentHashFixtures.ts +79 -0
  15. package/src/protocol/conformance/context.ts +222 -0
  16. package/src/protocol/conformance/index.ts +140 -0
  17. package/src/protocol/errors.ts +142 -0
  18. package/src/protocol/index.ts +39 -0
  19. package/src/protocol/keys.ts +279 -0
  20. package/src/protocol/params.ts +67 -0
  21. package/src/protocol/secrets.ts +231 -0
  22. package/src/protocol/server/assets.ts +119 -0
  23. package/src/protocol/server/auth.ts +49 -0
  24. package/src/protocol/server/bodyCache.ts +84 -0
  25. package/src/protocol/server/content.ts +175 -0
  26. package/src/protocol/server/core.ts +112 -0
  27. package/src/protocol/server/handler.ts +102 -0
  28. package/src/protocol/server/http.ts +139 -0
  29. package/src/protocol/server/index.ts +11 -0
  30. package/src/protocol/server/methods/apply.ts +341 -0
  31. package/src/protocol/server/methods/read.ts +156 -0
  32. package/src/protocol/server/rpc.ts +136 -0
  33. package/src/protocol/storage/fs/hash.ts +21 -0
  34. package/src/protocol/storage/fs/index.ts +338 -0
  35. package/src/protocol/storage/fs/lock.ts +68 -0
  36. package/src/protocol/storage/fs/transaction.ts +183 -0
  37. package/src/protocol/storage/fs/unsupported.ts +15 -0
  38. package/src/protocol/storage/memory.ts +238 -0
  39. package/src/protocol/storage.ts +182 -0
  40. package/src/protocol/types.ts +172 -0
  41. package/src/v8/analytics.ts +50 -0
  42. package/src/v8/background.ts +107 -0
  43. package/src/v8/builtins/data.ts +23 -0
  44. package/src/v8/builtins/index.ts +26 -0
  45. package/src/v8/builtins/lazy.ts +23 -0
  46. package/src/v8/builtins/legacy.ts +65 -0
  47. package/src/v8/builtins/matchers.ts +31 -0
  48. package/src/v8/builtins/multivariate.ts +25 -0
  49. package/src/v8/builtins/secret.ts +82 -0
  50. package/src/v8/canonical.ts +117 -0
  51. package/src/v8/ciphertext.ts +158 -0
  52. package/src/v8/cli/builtins.ts +20 -0
  53. package/src/v8/cli/check/index.ts +774 -0
  54. package/src/v8/cli/check/messages.ts +168 -0
  55. package/src/v8/cli/content.ts +287 -0
  56. package/src/v8/cli/index.ts +17 -0
  57. package/src/v8/cli/log.ts +18 -0
  58. package/src/v8/cli/main.ts +12 -0
  59. package/src/v8/cli/root.ts +66 -0
  60. package/src/v8/cli/run.ts +236 -0
  61. package/src/v8/cli/schema/builtinSchemas.ts +236 -0
  62. package/src/v8/cli/schema/generate.ts +507 -0
  63. package/src/v8/cli/schema/index.ts +63 -0
  64. package/src/v8/cli/schema/tsProgram.ts +497 -0
  65. package/src/v8/cli/schema/typeToSchema.ts +689 -0
  66. package/src/v8/cli/serve/server.ts +303 -0
  67. package/src/v8/cli/watch.ts +86 -0
  68. package/src/v8/client.ts +147 -0
  69. package/src/v8/cms.ts +237 -0
  70. package/src/v8/content.ts +195 -0
  71. package/src/v8/draft.ts +136 -0
  72. package/src/v8/errors.ts +59 -0
  73. package/src/v8/fetch.ts +133 -0
  74. package/src/v8/identity.ts +65 -0
  75. package/src/v8/index.ts +39 -0
  76. package/src/v8/json.ts +74 -0
  77. package/src/v8/matchRoute.ts +204 -0
  78. package/src/v8/remoteLoader.ts +282 -0
  79. package/src/v8/resolver.ts +278 -0
  80. package/src/v8/secrets.ts +17 -0
  81. package/src/v8/telemetry.ts +533 -0
  82. package/src/v8/types.ts +240 -0
  83. package/src/cms/applySectionConventions.ts +0 -124
  84. package/src/cms/blockSource.test.ts +0 -76
  85. package/src/cms/blockSource.ts +0 -191
  86. package/src/cms/client.browserBundle.test.ts +0 -44
  87. package/src/cms/client.ts +0 -80
  88. package/src/cms/draftSource.test.ts +0 -343
  89. package/src/cms/draftSource.ts +0 -362
  90. package/src/cms/index.ts +0 -151
  91. package/src/cms/layoutCacheRace.test.ts +0 -181
  92. package/src/cms/loadDecofileDirectory.test.ts +0 -109
  93. package/src/cms/loadDecofileDirectory.ts +0 -89
  94. package/src/cms/loader.test.ts +0 -200
  95. package/src/cms/loader.ts +0 -304
  96. package/src/cms/registry.test.ts +0 -110
  97. package/src/cms/registry.ts +0 -242
  98. package/src/cms/resolve.test.ts +0 -980
  99. package/src/cms/resolve.ts +0 -2282
  100. package/src/cms/schema.test.ts +0 -356
  101. package/src/cms/schema.ts +0 -1215
  102. package/src/cms/sectionLoaderContext.test.ts +0 -111
  103. package/src/cms/sectionLoaderContext.ts +0 -113
  104. package/src/cms/sectionLoaders.test.ts +0 -533
  105. package/src/cms/sectionLoaders.ts +0 -636
  106. package/src/cms/sectionMixins.test.ts +0 -167
  107. package/src/cms/sectionMixins.ts +0 -153
  108. package/src/cms/stickyFlags.test.ts +0 -117
  109. package/src/flags/audience.ts +0 -56
  110. package/src/flags/everyone.ts +0 -29
  111. package/src/flags/flag.ts +0 -15
  112. package/src/flags/flags.test.ts +0 -148
  113. package/src/flags/multivariate/image.ts +0 -11
  114. package/src/flags/multivariate/message.ts +0 -11
  115. package/src/flags/multivariate/page.ts +0 -16
  116. package/src/flags/multivariate/section.ts +0 -16
  117. package/src/flags/multivariate.ts +0 -1
  118. package/src/flags/types.ts +0 -59
  119. package/src/flags/utils/multivariate.ts +0 -20
  120. package/src/hooks/Image.test.ts +0 -100
  121. package/src/hooks/Image.tsx +0 -250
  122. package/src/hooks/JsonLd.tsx +0 -353
  123. package/src/hooks/LazySection.tsx +0 -121
  124. package/src/hooks/LiveControls.tsx +0 -122
  125. package/src/hooks/Picture.tsx +0 -127
  126. package/src/hooks/RenderSection.test.tsx +0 -81
  127. package/src/hooks/RenderSection.tsx +0 -91
  128. package/src/hooks/SectionErrorFallback.tsx +0 -97
  129. package/src/hooks/index.ts +0 -30
  130. package/src/matchers/builtins.test.ts +0 -318
  131. package/src/matchers/builtins.ts +0 -459
  132. package/src/matchers/countryNames.ts +0 -104
  133. package/src/matchers/override.test.ts +0 -205
  134. package/src/matchers/override.ts +0 -136
  135. package/src/matchers/posthog.ts +0 -154
  136. package/src/middleware/decoState.ts +0 -55
  137. package/src/middleware/healthMetrics.ts +0 -133
  138. package/src/middleware/hydrationContext.test.ts +0 -61
  139. package/src/middleware/hydrationContext.ts +0 -79
  140. package/src/middleware/index.ts +0 -88
  141. package/src/middleware/liveness.ts +0 -21
  142. package/src/middleware/observability.test.ts +0 -242
  143. package/src/middleware/observability.ts +0 -643
  144. package/src/middleware/validateSection.test.ts +0 -147
  145. package/src/middleware/validateSection.ts +0 -100
  146. package/src/sdk/abTesting.test.ts +0 -326
  147. package/src/sdk/abTesting.ts +0 -499
  148. package/src/sdk/analytics.ts +0 -77
  149. package/src/sdk/cacheHeaders.test.ts +0 -115
  150. package/src/sdk/cacheHeaders.ts +0 -433
  151. package/src/sdk/cachedLoader.test.ts +0 -122
  152. package/src/sdk/cachedLoader.ts +0 -503
  153. package/src/sdk/cachedLoaderModule.test.ts +0 -209
  154. package/src/sdk/clx.ts +0 -5
  155. package/src/sdk/cn.test.ts +0 -34
  156. package/src/sdk/cn.ts +0 -28
  157. package/src/sdk/composite.test.ts +0 -121
  158. package/src/sdk/composite.ts +0 -114
  159. package/src/sdk/cookie.test.ts +0 -108
  160. package/src/sdk/cookie.ts +0 -129
  161. package/src/sdk/crypto.ts +0 -185
  162. package/src/sdk/csp.ts +0 -59
  163. package/src/sdk/detectDevice.ts +0 -45
  164. package/src/sdk/djb2.ts +0 -20
  165. package/src/sdk/encoding.test.ts +0 -71
  166. package/src/sdk/encoding.ts +0 -47
  167. package/src/sdk/env.test.ts +0 -33
  168. package/src/sdk/env.ts +0 -54
  169. package/src/sdk/flags.test.ts +0 -91
  170. package/src/sdk/flags.ts +0 -108
  171. package/src/sdk/http.test.ts +0 -71
  172. package/src/sdk/http.ts +0 -124
  173. package/src/sdk/index.ts +0 -90
  174. package/src/sdk/inflightTimeout.test.ts +0 -35
  175. package/src/sdk/inflightTimeout.ts +0 -53
  176. package/src/sdk/instrumentedFetch.test.ts +0 -559
  177. package/src/sdk/instrumentedFetch.ts +0 -339
  178. package/src/sdk/invoke.test.ts +0 -115
  179. package/src/sdk/invoke.ts +0 -298
  180. package/src/sdk/logger.test.ts +0 -432
  181. package/src/sdk/logger.ts +0 -304
  182. package/src/sdk/mergeCacheControl.ts +0 -150
  183. package/src/sdk/normalizeUrls.ts +0 -91
  184. package/src/sdk/observability.ts +0 -109
  185. package/src/sdk/otel.test.ts +0 -526
  186. package/src/sdk/otel.ts +0 -1012
  187. package/src/sdk/otelAdapters/clickhouseCollector.ts +0 -65
  188. package/src/sdk/otelAdapters.test.ts +0 -89
  189. package/src/sdk/otelAdapters.ts +0 -144
  190. package/src/sdk/otelHttpLog.test.ts +0 -457
  191. package/src/sdk/otelHttpLog.ts +0 -419
  192. package/src/sdk/otelHttpMeter.test.ts +0 -292
  193. package/src/sdk/otelHttpMeter.ts +0 -506
  194. package/src/sdk/otelHttpTracer.test.ts +0 -474
  195. package/src/sdk/otelHttpTracer.ts +0 -543
  196. package/src/sdk/redirects.ts +0 -228
  197. package/src/sdk/requestContext.ts +0 -281
  198. package/src/sdk/requestContextStorage.browser.test.ts +0 -29
  199. package/src/sdk/requestContextStorage.browser.ts +0 -43
  200. package/src/sdk/requestContextStorage.ts +0 -35
  201. package/src/sdk/retry.ts +0 -45
  202. package/src/sdk/serverTimings.ts +0 -68
  203. package/src/sdk/signal.ts +0 -42
  204. package/src/sdk/sitemap.ts +0 -160
  205. package/src/sdk/urlRedaction.test.ts +0 -73
  206. package/src/sdk/urlRedaction.ts +0 -82
  207. package/src/sdk/urlUtils.ts +0 -134
  208. package/src/sdk/useDevice.test.ts +0 -130
  209. package/src/sdk/useDevice.ts +0 -89
  210. package/src/sdk/useDeviceContext.tsx +0 -108
  211. package/src/sdk/useId.ts +0 -7
  212. package/src/sdk/useScript.test.ts +0 -128
  213. package/src/sdk/useScript.ts +0 -210
  214. package/src/sdk/useSuggestions.test.ts +0 -230
  215. package/src/sdk/useSuggestions.ts +0 -188
  216. package/src/sdk/wrapCaughtErrors.ts +0 -107
  217. package/src/setup.ts +0 -120
  218. package/src/types/index.ts +0 -53
  219. package/src/types/widgets.ts +0 -14
  220. package/tsconfig.json +0 -7
@@ -1,503 +0,0 @@
1
- /**
2
- * Server-side loader caching with stale-while-revalidate + stale-if-error.
3
- *
4
- * Provides an in-memory cache layer for commerce loaders during SSR.
5
- * Supports:
6
- * - Single-flight dedup (identical concurrent requests share one fetch)
7
- * - SWR: serve stale immediately, refresh in background
8
- * - SIE: on origin error, fall back to stale entry within a configurable window
9
- *
10
- * Can be configured with explicit options or by passing a cache profile name
11
- * (e.g. "product") which derives timing from the unified profile system.
12
- */
13
-
14
- import {
15
- recordCacheMetric,
16
- recordLoaderError,
17
- recordLoaderMetric,
18
- withTracing,
19
- } from "../middleware/observability";
20
- import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
21
- import { withInflightTimeout } from "./inflightTimeout";
22
- import { RequestContext } from "./requestContext";
23
-
24
- // Build-time constant injected by `decoVitePlugin()` (see @decocms/tanstack's
25
- // vite plugin) — the same commit-SHA/deploy token the edge Cache API uses as
26
- // its `__v` cache-key version. Declared here with a `typeof` guard so it's
27
- // inert where the define is not applied (Node tests, non-plugin builds). Same
28
- // pattern already used in `../cms/blockSource.ts`.
29
- declare const __DECO_BUILD_HASH__: string | undefined;
30
-
31
- // Prefixes every in-memory loader cache key with the build hash, mirroring the
32
- // edge cache's `__v`. This is defense-in-depth, NOT the primary invalidation
33
- // lever: the cache Map is per-isolate, so a fresh isolate spun for a new deploy
34
- // already starts empty, and a warm isolate keeps running its old bundle (hence
35
- // its old BUILD) until it is recycled — the prefix cannot flush that. It only
36
- // matters if this store ever becomes shared across builds. Gated on truthiness
37
- // (empty string ⇒ unversioned) to match getBuildHash()/getDeploymentId() in
38
- // workerEntry.ts / blockSource.ts.
39
- const BUILD =
40
- typeof __DECO_BUILD_HASH__ !== "undefined" && __DECO_BUILD_HASH__ ? __DECO_BUILD_HASH__ : "";
41
-
42
- /**
43
- * `maxAge` above this (10 min) is almost always a mistake for a commerce loader:
44
- * upstream (catalog/price/stock) changes then take that long to propagate and a
45
- * redeploy is the only fast lever. Warned once per loader name.
46
- */
47
- const LONG_MAXAGE_WARN = 600_000;
48
- const warnedLongMaxAge = new Set<string>();
49
-
50
- export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
51
-
52
- export interface CachedLoaderOptions {
53
- policy: CachePolicy;
54
- /** Max age in milliseconds before an entry is considered stale. Default: 60_000 (1 min). */
55
- maxAge?: number;
56
- /** How long to serve stale on origin error, in ms. Default: 0 (no error fallback). */
57
- staleIfError?: number;
58
- /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
59
- keyFn?: (props: unknown) => string;
60
- }
61
-
62
- /**
63
- * The `@decocms/apps` loader/action module shape: a `default` loader plus the
64
- * optional `cache` / `cacheKey` exports Fresh loaders ship with.
65
- *
66
- * export const cache = "stale-while-revalidate";
67
- * export const cacheKey = (props, req) => `${new URL(req.url).pathname}...`;
68
- *
69
- * `cache` is the OPT-IN: absent (or `"no-store"`) means the loader runs on every
70
- * invocation, matching `@decocms/apps`' default. Any other value opts the loader
71
- * into single-flight dedup (concurrent identical calls in one render collapse to
72
- * one upstream call — the #339 N+1 fix). `cacheKey` computes the dedup identity
73
- * from `(props, req)`; returning `null` means "do not dedup, run fresh".
74
- */
75
- export interface LoaderModule<TProps = any, TResult = any> {
76
- default: (props: TProps, req?: Request) => Promise<TResult>;
77
- cache?: CachePolicy | { maxAge: number };
78
- cacheKey?: (props: TProps, req?: Request) => string | null;
79
- }
80
-
81
-
82
- interface CacheEntry<T = unknown> {
83
- value: T;
84
- createdAt: number;
85
- refreshing: boolean;
86
- /** Estimated payload size in bytes (UTF-16 length of JSON.stringify). */
87
- estimatedBytes: number;
88
- }
89
-
90
- const DEFAULT_MAX_AGE = 60_000;
91
-
92
- /**
93
- * Byte-cap for the in-memory loader cache. Default 32 MB — comfortably below
94
- * the Cloudflare Workers 128 MB isolate limit even when other caches (router,
95
- * VTEX fetch cache, V8 heap) are also resident.
96
- *
97
- * Override via env: `DECO_LOADER_CACHE_MAX_BYTES=67108864` (64 MB).
98
- *
99
- * Switched from entry-count to byte-based eviction because PLP payloads
100
- * (~0.5–2 MB each) blew past 128 MB at well under the previous 500-entry cap.
101
- */
102
- const DEFAULT_MAX_CACHE_BYTES = 32 * 1024 * 1024;
103
-
104
- function resolveMaxBytes(): number {
105
- const env = typeof globalThis.process !== "undefined"
106
- ? globalThis.process.env
107
- : undefined;
108
- const raw = env?.DECO_LOADER_CACHE_MAX_BYTES;
109
- if (!raw) return DEFAULT_MAX_CACHE_BYTES;
110
- const parsed = Number.parseInt(raw, 10);
111
- return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CACHE_BYTES;
112
- }
113
-
114
- const MAX_CACHE_BYTES = resolveMaxBytes();
115
-
116
- const cache = new Map<string, CacheEntry>();
117
- let cacheBytes = 0;
118
-
119
- // Bumped by clearLoaderCache(). A loader invocation captures this at entry and
120
- // only writes its result back if the generation is unchanged when it settles —
121
- // so a purge (e.g. POST /_cache/purge-loaders) that lands while a loader is
122
- // in flight can't be silently undone by that in-flight loader repopulating a
123
- // just-cleared entry with pre-purge data.
124
- let cacheGeneration = 0;
125
-
126
- // Floor each entry at 512 bytes so we never accumulate unbounded zero-cost
127
- // entries when a loader legitimately returns `undefined` or an empty object
128
- // — `JSON.stringify(undefined) === undefined` and the eviction loop would
129
- // otherwise never reclaim them. JSON-length also under-counts V8's actual
130
- // retention (structured objects retain 2–5× the JSON byte size); the 32 MB
131
- // cap is conservative enough that this approximation is fine for an OOM
132
- // safety net, but real RSS at the cap can land around 64–160 MB on
133
- // object-heavy payloads.
134
- const MIN_ENTRY_BYTES = 512;
135
-
136
- function estimateBytes(value: unknown): number {
137
- try {
138
- // UTF-16 string length is an order-of-magnitude estimate of the bytes the
139
- // object retains in V8 (V8 keeps a structured representation, not JSON).
140
- // The absolute value is less important than the relative pressure signal.
141
- const len = JSON.stringify(value)?.length ?? 0;
142
- return Math.max(len, MIN_ENTRY_BYTES);
143
- } catch {
144
- // Circular refs / non-serializable values: fall back to a fixed budget so
145
- // the entry still counts against the cap.
146
- return 1024;
147
- }
148
- }
149
-
150
- function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
151
- const prev = cache.get(key);
152
- if (prev) cacheBytes -= prev.estimatedBytes;
153
- cacheBytes += entry.estimatedBytes;
154
- cache.set(key, entry);
155
- }
156
-
157
- function deleteCacheEntry(key: string) {
158
- const prev = cache.get(key);
159
- if (!prev) return;
160
- cacheBytes -= prev.estimatedBytes;
161
- cache.delete(key);
162
- }
163
-
164
- function evictIfNeeded() {
165
- if (cacheBytes <= MAX_CACHE_BYTES) return;
166
- const oldest = [...cache.entries()].sort(
167
- (a, b) => a[1].createdAt - b[1].createdAt,
168
- );
169
- for (const [key] of oldest) {
170
- deleteCacheEntry(key);
171
- if (cacheBytes <= MAX_CACHE_BYTES) break;
172
- }
173
- }
174
-
175
- const inflightRequests = new Map<string, Promise<unknown>>();
176
-
177
- function resolveOptions(
178
- optionsOrProfile: CachedLoaderOptions | CacheProfileName,
179
- ): CachedLoaderOptions {
180
- if (typeof optionsOrProfile === "string") {
181
- return loaderCacheOptions(optionsOrProfile);
182
- }
183
- return optionsOrProfile;
184
- }
185
-
186
- /**
187
- * Wraps a loader function with server-side caching, single-flight dedup,
188
- * and stale-if-error resilience.
189
- *
190
- * Accepts either explicit options or a cache profile name:
191
- *
192
- * @example
193
- * ```ts
194
- * // Profile-driven (recommended):
195
- * const cachedPDP = createCachedLoader("vtex/productDetailsPage", pdpLoader, "product");
196
- *
197
- * // Explicit options (when loader needs different timing than its profile):
198
- * const cachedSuggestions = createCachedLoader("vtex/suggestions", suggestionsLoader, {
199
- * policy: "stale-while-revalidate",
200
- * maxAge: 120_000,
201
- * staleIfError: 300_000,
202
- * });
203
- * ```
204
- */
205
- export function createCachedLoader<TProps, TResult>(
206
- name: string,
207
- loaderFn: (props: TProps) => Promise<TResult>,
208
- optionsOrProfile: CachedLoaderOptions | CacheProfileName,
209
- ): (props: TProps) => Promise<TResult> {
210
- const resolved = resolveOptions(optionsOrProfile);
211
- const { policy, maxAge = DEFAULT_MAX_AGE, staleIfError = 0, keyFn = JSON.stringify } = resolved;
212
-
213
- const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
214
- const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
215
-
216
- if (policy !== "no-store" && maxAge > LONG_MAXAGE_WARN && !warnedLongMaxAge.has(name)) {
217
- warnedLongMaxAge.add(name);
218
- console.warn(
219
- `[cachedLoader] ${name}: maxAge=${Math.round(maxAge / 1000)}s is very long — ` +
220
- `upstream changes take that long to propagate. Prefer a short window and use ` +
221
- `POST /_cache/purge-loaders (or a redeploy) for immediate invalidation.`,
222
- );
223
- }
224
-
225
- if (policy === "no-store") return loaderFn;
226
-
227
- return async (props: TProps): Promise<TResult> => {
228
- const cacheKey = `${BUILD}::${name}::${keyFn(props)}`;
229
- // Snapshot the cache generation; a purge during this invocation bumps it,
230
- // and the deferred writes below skip repopulating a just-cleared entry.
231
- const gen = cacheGeneration;
232
-
233
- const inflight = inflightRequests.get(cacheKey);
234
- if (inflight) {
235
- // Treat in-flight dedup as a cache hit — avoided the origin call.
236
- recordCacheMetric(true, name, undefined, "cachedLoader");
237
- const start = performance.now();
238
- return inflight.then((r) => {
239
- recordLoaderMetric(name, performance.now() - start, "HIT");
240
- return r as TResult;
241
- });
242
- }
243
-
244
- if (isDev) {
245
- // Dev mode: no caching, but still useful to count attempts.
246
- recordCacheMetric(false, name, undefined, "cachedLoader");
247
- const devStart = performance.now();
248
- const promise = withInflightTimeout(
249
- withTracing(
250
- "deco.cachedLoader",
251
- () => loaderFn(props),
252
- { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
253
- ),
254
- `cachedLoader:dev ${cacheKey}`,
255
- )
256
- .then((r) => {
257
- recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
258
- return r;
259
- })
260
- .catch((err) => {
261
- recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
262
- recordLoaderError(name);
263
- throw err;
264
- })
265
- .finally(() => inflightRequests.delete(cacheKey));
266
- inflightRequests.set(cacheKey, promise);
267
- return promise;
268
- }
269
-
270
- const entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
271
- const now = Date.now();
272
- const isStale = entry ? now - entry.createdAt > maxAge : true;
273
-
274
- if (policy === "no-cache") {
275
- if (entry && !isStale) {
276
- recordCacheMetric(true, name, "HIT", "cachedLoader");
277
- recordLoaderMetric(name, 0, "HIT");
278
- return entry.value;
279
- }
280
- }
281
-
282
- if (policy === "stale-while-revalidate") {
283
- if (entry && !isStale) {
284
- recordCacheMetric(true, name, "HIT", "cachedLoader");
285
- recordLoaderMetric(name, 0, "HIT");
286
- return entry.value;
287
- }
288
-
289
- if (entry && isStale && !entry.refreshing) {
290
- // Stale-while-revalidate hit: serve stale, refresh in background.
291
- recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
292
- recordLoaderMetric(name, 0, "STALE-HIT");
293
- entry.refreshing = true;
294
- loaderFn(props)
295
- .then((result) => {
296
- // Skip the write if a purge cleared the cache mid-refresh — otherwise
297
- // we'd re-insert pre-purge data the purge was meant to drop.
298
- if (gen !== cacheGeneration) return;
299
- setCacheEntry(cacheKey, {
300
- value: result,
301
- createdAt: Date.now(),
302
- refreshing: false,
303
- estimatedBytes: estimateBytes(result),
304
- });
305
- evictIfNeeded();
306
- })
307
- .catch(() => {
308
- // Background refresh failed — entry stays stale.
309
- // If past the SIE window, evict so we don't serve indefinitely stale data.
310
- entry.refreshing = false;
311
- if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
312
- deleteCacheEntry(cacheKey);
313
- }
314
- });
315
- return entry.value;
316
- }
317
-
318
- if (entry) {
319
- // Past SIE window — still serve the stale value once but mark
320
- // the decision as STALE-ERROR so dashboards can distinguish
321
- // this from healthy SWR.
322
- recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
323
- recordLoaderMetric(name, 0, "STALE-ERROR");
324
- return entry.value;
325
- }
326
- }
327
-
328
- // Cache miss — emit metric, then run loader inside a span so individual
329
- // slow loaders are visible in traces.
330
- recordCacheMetric(false, name, "MISS", "cachedLoader");
331
- const loaderStart = performance.now();
332
- const promise = withInflightTimeout(
333
- withTracing("deco.cachedLoader", () => loaderFn(props), {
334
- "deco.loader": name,
335
- "deco.cache.policy": policy,
336
- }),
337
- `cachedLoader ${cacheKey}`,
338
- )
339
- .then((result) => {
340
- recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
341
- // Skip caching if a purge landed while this loader was in flight — still
342
- // return the fresh value to the caller, just don't persist a raced entry.
343
- if (gen === cacheGeneration) {
344
- setCacheEntry(cacheKey, {
345
- value: result,
346
- createdAt: Date.now(),
347
- refreshing: false,
348
- estimatedBytes: estimateBytes(result),
349
- });
350
- evictIfNeeded();
351
- }
352
- return result;
353
- })
354
- .catch((err) => {
355
- // SIE fallback: if we have a stale entry within the error window, return it
356
- if (staleIfError > 0 && entry) {
357
- const age = now - entry.createdAt;
358
- if (age < maxAge + staleIfError) {
359
- console.warn(
360
- `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
361
- );
362
- recordLoaderMetric(name, performance.now() - loaderStart, "STALE-ERROR");
363
- return entry.value;
364
- }
365
- }
366
- recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
367
- recordLoaderError(name);
368
- throw err;
369
- })
370
- .finally(() => inflightRequests.delete(cacheKey));
371
-
372
- inflightRequests.set(cacheKey, promise);
373
- return promise;
374
- };
375
- }
376
-
377
-
378
- // ---------------------------------------------------------------------------
379
- // Module loader dedup (the `@decocms/apps` cache/cacheKey convention)
380
- //
381
- // Distinct from `createCachedLoader` above (VTEX's byte-capped SWR cache): the
382
- // module path is DEDUP-ONLY. A loader that opts in via `export const cache`
383
- // gets single-flight — concurrent identical invocations in one render (N
384
- // sections referencing the same loader) share one upstream call — but nothing
385
- // is retained past settlement, so there is zero cross-request staleness. This
386
- // is the deliberately-conservative fix for the #339 N+1 (2–3× product GraphQL
387
- // per PDP render) without the SWR machinery's stale-serving semantics.
388
- // ---------------------------------------------------------------------------
389
-
390
- const moduleInflight = new Map<string, Promise<unknown>>();
391
-
392
- /**
393
- * Wrap an `@decocms/apps`-shaped loader module so its `cache`/`cacheKey` exports
394
- * drive single-flight dedup. Loaders without a `cache` export (or `"no-store"`)
395
- * are returned unwrapped — they run on every call, matching apps' default.
396
- *
397
- * The dedup key is `${name}::${cacheKey(props, req)}`; `req` comes from the
398
- * caller or, on the CMS-resolution path (which passes only props), from
399
- * `RequestContext.current` — both execute inside the same AsyncLocalStorage
400
- * scope. `cacheKey` returning `null`, or `req` being unavailable when `cacheKey`
401
- * needs it, falls back to running fresh / keying on `JSON.stringify(props)`.
402
- */
403
- export function createCachedLoaderFromModule<TProps, TResult>(
404
- name: string,
405
- mod: LoaderModule<TProps, TResult>,
406
- ): (props: TProps, req?: Request) => Promise<TResult> {
407
- const policy: CachePolicy = typeof mod.cache === "string"
408
- ? mod.cache
409
- : mod.cache && typeof mod.cache === "object"
410
- ? "stale-while-revalidate"
411
- : "no-store";
412
-
413
- // Only `stale-while-revalidate` (or `{ maxAge }`) opts into dedup — matching
414
- // `@decocms/apps`/deco, where `no-store` (the default) and `no-cache` both
415
- // bypass single-flight and run on every call. Return unwrapped otherwise.
416
- if (policy !== "stale-while-revalidate") return mod.default;
417
-
418
- const cacheKeyFn = mod.cacheKey;
419
-
420
- return (props: TProps, req?: Request): Promise<TResult> => {
421
- const request = req ?? RequestContext.current?.request ?? undefined;
422
-
423
- let keyPart: string | null;
424
- if (cacheKeyFn) {
425
- // A cacheKey that dereferences `req` (e.g. `new URL(req.url)`) would throw
426
- // when the request is unavailable — fall back to props-hash dedup instead.
427
- keyPart = request ? cacheKeyFn(props, request) : JSON.stringify(props);
428
- } else {
429
- keyPart = JSON.stringify(props);
430
- }
431
-
432
- // Explicit null → the loader declared this call uncacheable: run fresh.
433
- if (keyPart === null) return mod.default(props, req);
434
-
435
- const key = `${BUILD}::${name}::${keyPart}`;
436
- const existing = moduleInflight.get(key) as Promise<TResult> | undefined;
437
- if (existing) return existing;
438
-
439
- const promise = Promise.resolve(mod.default(props, req)).finally(() => {
440
- moduleInflight.delete(key);
441
- });
442
- moduleInflight.set(key, promise);
443
- return promise;
444
- };
445
- }
446
-
447
- /**
448
- * Registry entry factory for generated loader maps (`.deco/loaders.gen.ts`).
449
- * Lazily imports the loader module on first call, then delegates to a memoized
450
- * `createCachedLoaderFromModule` wrapper so `cache`/`cacheKey` exports take
451
- * effect. Keeps generated code a one-liner while the dedup logic stays here,
452
- * unit-tested, in the framework.
453
- */
454
- export function createLoaderEntry<TProps = any, TResult = any>(
455
- name: string,
456
- importFn: () => Promise<LoaderModule<TProps, TResult>>,
457
- ): (props: TProps, req?: Request) => Promise<TResult> {
458
- // Memoize the import+build PROMISE (not the resolved wrapper) so concurrent
459
- // first-calls — exactly the N-sections-per-render case — share one import
460
- // instead of racing into N. Reset on failure so a transient import error can
461
- // retry rather than poisoning the entry forever.
462
- let wrappedPromise:
463
- | Promise<(props: TProps, req?: Request) => Promise<TResult>>
464
- | undefined;
465
- return (props: TProps, req?: Request): Promise<TResult> => {
466
- if (!wrappedPromise) {
467
- wrappedPromise = importFn()
468
- .then((mod) => createCachedLoaderFromModule(name, mod))
469
- .catch((err) => {
470
- wrappedPromise = undefined;
471
- throw err;
472
- });
473
- }
474
- return wrappedPromise.then((wrapped) => wrapped(props, req));
475
- };
476
- }
477
-
478
- /**
479
- * Clear all cached entries in THIS isolate. Used both by decofile hot-reload
480
- * (`@decocms/blocks-admin`) and by the `POST /_cache/purge-loaders` route — an
481
- * escape hatch to invalidate immediately (e.g. after an out-of-band Magento/
482
- * catalog sync) without waiting out the TTL. Per-isolate: the route must be hit
483
- * for every isolate; a redeploy replaces isolates wholesale. Bumps the cache
484
- * generation so any loader in flight at purge time won't repopulate a cleared
485
- * entry with pre-purge data.
486
- */
487
- export function clearLoaderCache() {
488
- cache.clear();
489
- cacheBytes = 0;
490
- inflightRequests.clear();
491
- moduleInflight.clear();
492
- cacheGeneration++;
493
- }
494
-
495
- /** Get cache stats for diagnostics. */
496
- export function getLoaderCacheStats() {
497
- return {
498
- entries: cache.size,
499
- inflight: inflightRequests.size,
500
- estimatedBytes: cacheBytes,
501
- maxBytes: MAX_CACHE_BYTES,
502
- };
503
- }