@decocms/blocks 7.81.5 → 7.83.0
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.
- package/package.json +1 -1
- package/src/hooks/Stats.test.ts +29 -23
- package/src/hooks/Stats.tsx +23 -18
- package/src/sdk/cachedLoader.test.ts +39 -0
- package/src/sdk/cachedLoader.ts +17 -1
package/package.json
CHANGED
package/src/hooks/Stats.test.ts
CHANGED
|
@@ -25,36 +25,42 @@ async function render(props: Record<string, unknown> = {}) {
|
|
|
25
25
|
}
|
|
26
26
|
|
|
27
27
|
describe("Stats", () => {
|
|
28
|
-
it("is mounted by the framework, so rendering it
|
|
29
|
-
// DecoRootLayout renders <Stats /> for every site
|
|
30
|
-
//
|
|
31
|
-
|
|
32
|
-
delete process.env.DECO_ANALYTICS_ENABLED;
|
|
28
|
+
it("is mounted by the framework, so rendering it with no key must be inert", async () => {
|
|
29
|
+
// DecoRootLayout renders <Stats /> for every site. On the collector's origin only a key
|
|
30
|
+
// identifies the site, so without one there is no tag, no preconnect and no request.
|
|
31
|
+
delete process.env.DECO_ANALYTICS_SITE_KEY;
|
|
33
32
|
expect(await render()).toBe("");
|
|
34
33
|
});
|
|
35
34
|
|
|
36
|
-
it("
|
|
37
|
-
|
|
38
|
-
|
|
35
|
+
it("loads from the collector's origin with a key, and preconnects to it", async () => {
|
|
36
|
+
process.env.DECO_ANALYTICS_SITE_KEY = "dq_abc123";
|
|
37
|
+
const html = await render();
|
|
38
|
+
expect(html).toContain('src="https://analytics.decocdn.com/_dq/a.js?k=dq_abc123"');
|
|
39
|
+
expect(html).toContain("preconnect");
|
|
40
|
+
});
|
|
39
41
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
process.env.DECO_ANALYTICS_ENABLED = "1";
|
|
45
|
-
vi.resetModules();
|
|
42
|
+
it("renders nothing when explicitly disabled, even with a key or first-party", async () => {
|
|
43
|
+
process.env.DECO_ANALYTICS_ENABLED = "false";
|
|
44
|
+
process.env.DECO_ANALYTICS_SITE_KEY = "dq_abc123";
|
|
45
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
|
|
46
46
|
expect(await render()).toBe("");
|
|
47
47
|
});
|
|
48
48
|
|
|
49
|
-
it("
|
|
50
|
-
process.env.
|
|
51
|
-
const
|
|
52
|
-
expect(
|
|
49
|
+
it("is first-party only when opted in: same origin, no key needed, no preconnect", async () => {
|
|
50
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
|
|
51
|
+
const html = await render();
|
|
52
|
+
expect(html).toContain('src="/_dq/a.js"');
|
|
53
53
|
// A preconnect to the page's own origin is a wasted hint, and on some browsers a
|
|
54
54
|
// second connection opened for nothing.
|
|
55
|
-
expect(
|
|
55
|
+
expect(html).not.toContain("preconnect");
|
|
56
56
|
|
|
57
|
+
// Only the exact string opts in.
|
|
57
58
|
vi.resetModules();
|
|
59
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "1";
|
|
60
|
+
expect(await render()).toBe("");
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
it("uses a custom origin as given, with or without a key", async () => {
|
|
58
64
|
process.env.DECO_ANALYTICS_ORIGIN = "https://analytics.example.com";
|
|
59
65
|
const cross = await render();
|
|
60
66
|
expect(cross).toContain('src="https://analytics.example.com/_dq/a.js"');
|
|
@@ -62,7 +68,7 @@ describe("Stats", () => {
|
|
|
62
68
|
});
|
|
63
69
|
|
|
64
70
|
it("carries dev and debug as attributes, and omits them when off", async () => {
|
|
65
|
-
process.env.
|
|
71
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
|
|
66
72
|
// The whole reason these are attributes: TanStack hoists `<script async>` into `<head>`
|
|
67
73
|
// above any inline config block, so a global set alongside the tag loses the race and the
|
|
68
74
|
// collector boots into silence with no error.
|
|
@@ -79,8 +85,8 @@ describe("Stats", () => {
|
|
|
79
85
|
});
|
|
80
86
|
|
|
81
87
|
it("puts the site key in the URL, because that is where the collector reads it", async () => {
|
|
82
|
-
process.env.
|
|
83
|
-
//
|
|
88
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
|
|
89
|
+
// First-party sites are identified by the Host header, which a visitor cannot forge.
|
|
84
90
|
// Emitting an empty key would put a `tag`-sourced identity on a site that has a
|
|
85
91
|
// trustworthy one, and `tag` is the source that must never reach an invoice.
|
|
86
92
|
const none = await render();
|
|
@@ -99,7 +105,7 @@ describe("Stats", () => {
|
|
|
99
105
|
});
|
|
100
106
|
|
|
101
107
|
it("uses defer only when asked, async otherwise", async () => {
|
|
102
|
-
process.env.
|
|
108
|
+
process.env.DECO_ANALYTICS_FIRST_PARTY = "true";
|
|
103
109
|
// Nothing visual may depend on this script. `async` is what keeps a slow or failed
|
|
104
110
|
// collector from becoming a slow or broken page.
|
|
105
111
|
expect(await render()).toContain("async");
|
package/src/hooks/Stats.tsx
CHANGED
|
@@ -46,28 +46,31 @@
|
|
|
46
46
|
* development host, skip, and say nothing. Attributes cannot lose that race because
|
|
47
47
|
* they are on the element that is executing.
|
|
48
48
|
*
|
|
49
|
-
* ##
|
|
49
|
+
* ## Third-party by default
|
|
50
50
|
*
|
|
51
|
-
*
|
|
52
|
-
*
|
|
53
|
-
* the
|
|
54
|
-
*
|
|
55
|
-
*
|
|
51
|
+
* The tag loads from the collector's origin and `DECO_ANALYTICS_SITE_KEY` identifies
|
|
52
|
+
* the site. Without a key it renders nothing: on that origin nothing else identifies
|
|
53
|
+
* the site, so its events would be dropped. `DECO_ANALYTICS_FIRST_PARTY=true` opts
|
|
54
|
+
* into the site's own host, which must route `/_dq/*` to the collector.
|
|
55
|
+
*
|
|
56
|
+
* `DECO_ANALYTICS_ENABLED=false` turns it off. That gate and `ONEDOLLAR_ENABLED` are
|
|
57
|
+
* independent, so a site can run both during a shadow comparison and neither can turn
|
|
58
|
+
* the other off.
|
|
56
59
|
*/
|
|
57
60
|
|
|
58
61
|
export interface Props {
|
|
59
62
|
/**
|
|
60
|
-
* Where the collector is published. Empty means same-origin
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
+
* Where the collector is published. Empty means same-origin: the script and the
|
|
64
|
+
* beacon are served from the site's own hostname, which must route `/_dq/*` to the
|
|
65
|
+
* collector.
|
|
63
66
|
*/
|
|
64
67
|
origin?: string;
|
|
65
68
|
/**
|
|
66
|
-
* The site's public key,
|
|
69
|
+
* The site's public key, which identifies it on the collector's origin.
|
|
67
70
|
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
+
* First-party sites are identified by the `Host` header, which a visitor cannot
|
|
72
|
+
* forge; those must leave this unset. A key travels in the page source where anyone
|
|
73
|
+
* can read and reuse it, so a key-identified site is recorded with
|
|
71
74
|
* `site_id_source = tag` and is never billed from.
|
|
72
75
|
*/
|
|
73
76
|
siteKey?: string;
|
|
@@ -82,21 +85,23 @@ export interface Props {
|
|
|
82
85
|
debug?: boolean;
|
|
83
86
|
}
|
|
84
87
|
|
|
85
|
-
/**
|
|
86
|
-
export const DEFAULT_ORIGIN = "";
|
|
88
|
+
/** The collector's own origin. See {@link Props.origin}. */
|
|
89
|
+
export const DEFAULT_ORIGIN = "https://analytics.decocdn.com";
|
|
87
90
|
|
|
88
91
|
/**
|
|
89
|
-
*
|
|
92
|
+
* On unless "false", and independent of `ONEDOLLAR_ENABLED` so both can run at once.
|
|
90
93
|
*/
|
|
91
|
-
const DECO_ANALYTICS_ENABLED = process.env.DECO_ANALYTICS_ENABLED
|
|
94
|
+
const DECO_ANALYTICS_ENABLED = process.env.DECO_ANALYTICS_ENABLED !== "false";
|
|
95
|
+
const DECO_ANALYTICS_FIRST_PARTY = process.env.DECO_ANALYTICS_FIRST_PARTY === "true";
|
|
92
96
|
const DECO_ANALYTICS_ORIGIN = process.env.DECO_ANALYTICS_ORIGIN;
|
|
93
97
|
const DECO_ANALYTICS_SITE_KEY = process.env.DECO_ANALYTICS_SITE_KEY;
|
|
94
98
|
|
|
95
99
|
function Stats({ origin, siteKey, defer, dev, debug }: Props) {
|
|
96
100
|
if (!DECO_ANALYTICS_ENABLED) return null;
|
|
97
101
|
|
|
98
|
-
const base = origin ?? DECO_ANALYTICS_ORIGIN ?? DEFAULT_ORIGIN;
|
|
102
|
+
const base = origin ?? DECO_ANALYTICS_ORIGIN ?? (DECO_ANALYTICS_FIRST_PARTY ? "" : DEFAULT_ORIGIN);
|
|
99
103
|
const key = siteKey ?? DECO_ANALYTICS_SITE_KEY;
|
|
104
|
+
if (base === DEFAULT_ORIGIN && !key) return null;
|
|
100
105
|
|
|
101
106
|
return (
|
|
102
107
|
<>
|
|
@@ -119,4 +119,43 @@ describe("createCachedLoader", () => {
|
|
|
119
119
|
expect(loaderFn).toHaveBeenCalledTimes(2);
|
|
120
120
|
expect(getLoaderCacheStats().entries).toBe(0);
|
|
121
121
|
});
|
|
122
|
+
|
|
123
|
+
it("shouldCache=false returns the result without storing it", async () => {
|
|
124
|
+
const loaderFn = vi.fn(async () => ({ products: [] as number[] }));
|
|
125
|
+
const cached = createCachedLoader("t/should-cache-miss", loaderFn, {
|
|
126
|
+
policy: "stale-while-revalidate",
|
|
127
|
+
maxAge: 60_000,
|
|
128
|
+
shouldCache: (r) => (r as { products: number[] }).products.length > 0,
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
expect(await cached({})).toEqual({ products: [] });
|
|
132
|
+
await cached({}); // not stored: goes to origin again
|
|
133
|
+
|
|
134
|
+
expect(loaderFn).toHaveBeenCalledTimes(2);
|
|
135
|
+
expect(getLoaderCacheStats().entries).toBe(0);
|
|
136
|
+
});
|
|
137
|
+
|
|
138
|
+
it("an uncacheable SWR refresh keeps the stale entry and retries on the next hit", async () => {
|
|
139
|
+
vi.useFakeTimers();
|
|
140
|
+
vi.setSystemTime(new Date("2026-05-18T16:00:00.000Z"));
|
|
141
|
+
const results = [[1], [], [2]];
|
|
142
|
+
const loaderFn = vi.fn(async () => ({ products: results.shift() ?? [] }));
|
|
143
|
+
const cached = createCachedLoader("t/should-cache-swr", loaderFn, {
|
|
144
|
+
policy: "stale-while-revalidate",
|
|
145
|
+
maxAge: 1_000,
|
|
146
|
+
shouldCache: (r) => (r as { products: number[] }).products.length > 0,
|
|
147
|
+
});
|
|
148
|
+
|
|
149
|
+
await cached({}); // MISS -> stores [1]
|
|
150
|
+
vi.setSystemTime(new Date("2026-05-18T16:00:05.000Z")); // now stale
|
|
151
|
+
expect(await cached({})).toEqual({ products: [1] }); // refresh returns [] -> not stored
|
|
152
|
+
await vi.runAllTimersAsync();
|
|
153
|
+
expect(await cached({})).toEqual({ products: [1] }); // still stale [1]; refresh runs again
|
|
154
|
+
await vi.runAllTimersAsync();
|
|
155
|
+
|
|
156
|
+
expect(loaderFn).toHaveBeenCalledTimes(3);
|
|
157
|
+
vi.setSystemTime(new Date("2026-05-18T16:00:05.500Z")); // within maxAge of the [2] write
|
|
158
|
+
expect(await cached({})).toEqual({ products: [2] });
|
|
159
|
+
vi.useRealTimers();
|
|
160
|
+
});
|
|
122
161
|
});
|
package/src/sdk/cachedLoader.ts
CHANGED
|
@@ -55,6 +55,15 @@ export interface CachedLoaderOptions {
|
|
|
55
55
|
staleWhileRevalidate?: number;
|
|
56
56
|
/** Key function to generate a cache key from loader props. Default: JSON.stringify. */
|
|
57
57
|
keyFn?: (props: unknown) => string;
|
|
58
|
+
/**
|
|
59
|
+
* Whether a resolved result is stored. Returning `false` hands the value to
|
|
60
|
+
* the caller without writing it — e.g. an empty search that may just be the
|
|
61
|
+
* index rebuilding, which would otherwise be served as "not found" for the
|
|
62
|
+
* whole window. On a background SWR refresh the stale entry is kept. Use this
|
|
63
|
+
* instead of throwing to skip the write: a throw is counted as a loader error.
|
|
64
|
+
* Default: every resolved result is stored.
|
|
65
|
+
*/
|
|
66
|
+
shouldCache?: (result: unknown) => boolean;
|
|
58
67
|
}
|
|
59
68
|
|
|
60
69
|
/**
|
|
@@ -270,6 +279,7 @@ export function createCachedLoader<TProps, TResult>(
|
|
|
270
279
|
staleIfError = 0,
|
|
271
280
|
staleWhileRevalidate = 300_000,
|
|
272
281
|
keyFn = JSON.stringify,
|
|
282
|
+
shouldCache,
|
|
273
283
|
} = resolved;
|
|
274
284
|
|
|
275
285
|
const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
|
|
@@ -381,6 +391,11 @@ export function createCachedLoader<TProps, TResult>(
|
|
|
381
391
|
// Skip the write if a purge cleared the cache mid-refresh — otherwise
|
|
382
392
|
// we'd re-insert pre-purge data the purge was meant to drop.
|
|
383
393
|
if (gen !== cacheGeneration) return;
|
|
394
|
+
// Uncacheable result: keep serving the stale entry, retry on the next hit.
|
|
395
|
+
if (shouldCache && !shouldCache(result)) {
|
|
396
|
+
entry.refreshing = false;
|
|
397
|
+
return;
|
|
398
|
+
}
|
|
384
399
|
setCacheEntry(
|
|
385
400
|
cacheKey,
|
|
386
401
|
{
|
|
@@ -429,7 +444,8 @@ export function createCachedLoader<TProps, TResult>(
|
|
|
429
444
|
recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
|
|
430
445
|
// Skip caching if a purge landed while this loader was in flight — still
|
|
431
446
|
// return the fresh value to the caller, just don't persist a raced entry.
|
|
432
|
-
|
|
447
|
+
// Same for a result the caller marked uncacheable.
|
|
448
|
+
if (gen === cacheGeneration && (!shouldCache || shouldCache(result))) {
|
|
433
449
|
setCacheEntry(
|
|
434
450
|
cacheKey,
|
|
435
451
|
{
|