@decocms/blocks 7.0.0

package/src/sdk/cachedLoader.ts

@@ -0,0 +1,364 @@
+/**
+ * Server-side loader caching with stale-while-revalidate + stale-if-error.
+ *
+ * Provides an in-memory cache layer for commerce loaders during SSR.
+ * Supports:
+ * - Single-flight dedup (identical concurrent requests share one fetch)
+ * - SWR: serve stale immediately, refresh in background
+ * - SIE: on origin error, fall back to stale entry within a configurable window
+ *
+ * Can be configured with explicit options or by passing a cache profile name
+ * (e.g. "product") which derives timing from the unified profile system.
+ */
+
+import {
+  recordCacheMetric,
+  recordLoaderError,
+  recordLoaderMetric,
+  withTracing,
+} from "../middleware/observability";
+import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
+import { withInflightTimeout } from "./inflightTimeout";
+
+export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
+
+export interface CachedLoaderOptions {
+  policy: CachePolicy;
+  /** Max age in milliseconds before an entry is considered stale. Default: 60_000 (1 min). */
+  maxAge?: number;
+  /** How long to serve stale on origin error, in ms. Default: 0 (no error fallback). */
+  staleIfError?: number;
+  /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
+  keyFn?: (props: unknown) => string;
+}
+
+export interface LoaderModule<TProps = any, TResult = any> {
+  default: (props: TProps) => Promise<TResult>;
+  cache?: CachePolicy | { maxAge: number };
+  cacheKey?: (props: TProps) => string | null;
+}
+
+interface CacheEntry<T = unknown> {
+  value: T;
+  createdAt: number;
+  refreshing: boolean;
+  /** Estimated payload size in bytes (UTF-16 length of JSON.stringify). */
+  estimatedBytes: number;
+}
+
+const DEFAULT_MAX_AGE = 60_000;
+
+/**
+ * Byte-cap for the in-memory loader cache. Default 32 MB — comfortably below
+ * the Cloudflare Workers 128 MB isolate limit even when other caches (router,
+ * VTEX fetch cache, V8 heap) are also resident.
+ *
+ * Override via env: `DECO_LOADER_CACHE_MAX_BYTES=67108864` (64 MB).
+ *
+ * Switched from entry-count to byte-based eviction because PLP payloads
+ * (~0.5–2 MB each) blew past 128 MB at well under the previous 500-entry cap.
+ */
+const DEFAULT_MAX_CACHE_BYTES = 32 * 1024 * 1024;
+
+function resolveMaxBytes(): number {
+  const env = typeof globalThis.process !== "undefined"
+    ? globalThis.process.env
+    : undefined;
+  const raw = env?.DECO_LOADER_CACHE_MAX_BYTES;
+  if (!raw) return DEFAULT_MAX_CACHE_BYTES;
+  const parsed = Number.parseInt(raw, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CACHE_BYTES;
+}
+
+const MAX_CACHE_BYTES = resolveMaxBytes();
+
+const cache = new Map<string, CacheEntry>();
+let cacheBytes = 0;
+
+// Floor each entry at 512 bytes so we never accumulate unbounded zero-cost
+// entries when a loader legitimately returns `undefined` or an empty object
+// — `JSON.stringify(undefined) === undefined` and the eviction loop would
+// otherwise never reclaim them. JSON-length also under-counts V8's actual
+// retention (structured objects retain 2–5× the JSON byte size); the 32 MB
+// cap is conservative enough that this approximation is fine for an OOM
+// safety net, but real RSS at the cap can land around 64–160 MB on
+// object-heavy payloads.
+const MIN_ENTRY_BYTES = 512;
+
+function estimateBytes(value: unknown): number {
+  try {
+    // UTF-16 string length is an order-of-magnitude estimate of the bytes the
+    // object retains in V8 (V8 keeps a structured representation, not JSON).
+    // The absolute value is less important than the relative pressure signal.
+    const len = JSON.stringify(value)?.length ?? 0;
+    return Math.max(len, MIN_ENTRY_BYTES);
+  } catch {
+    // Circular refs / non-serializable values: fall back to a fixed budget so
+    // the entry still counts against the cap.
+    return 1024;
+  }
+}
+
+function setCacheEntry<T>(key: string, entry: CacheEntry<T>) {
+  const prev = cache.get(key);
+  if (prev) cacheBytes -= prev.estimatedBytes;
+  cacheBytes += entry.estimatedBytes;
+  cache.set(key, entry);
+}
+
+function deleteCacheEntry(key: string) {
+  const prev = cache.get(key);
+  if (!prev) return;
+  cacheBytes -= prev.estimatedBytes;
+  cache.delete(key);
+}
+
+function evictIfNeeded() {
+  if (cacheBytes <= MAX_CACHE_BYTES) return;
+  const oldest = [...cache.entries()].sort(
+    (a, b) => a[1].createdAt - b[1].createdAt,
+  );
+  for (const [key] of oldest) {
+    deleteCacheEntry(key);
+    if (cacheBytes <= MAX_CACHE_BYTES) break;
+  }
+}
+
+const inflightRequests = new Map<string, Promise<unknown>>();
+
+function resolveOptions(
+  optionsOrProfile: CachedLoaderOptions | CacheProfileName,
+): CachedLoaderOptions {
+  if (typeof optionsOrProfile === "string") {
+    return loaderCacheOptions(optionsOrProfile);
+  }
+  return optionsOrProfile;
+}
+
+/**
+ * Wraps a loader function with server-side caching, single-flight dedup,
+ * and stale-if-error resilience.
+ *
+ * Accepts either explicit options or a cache profile name:
+ *
+ * @example
+ * ```ts
+ * // Profile-driven (recommended):
+ * const cachedPDP = createCachedLoader("vtex/productDetailsPage", pdpLoader, "product");
+ *
+ * // Explicit options (when loader needs different timing than its profile):
+ * const cachedSuggestions = createCachedLoader("vtex/suggestions", suggestionsLoader, {
+ *   policy: "stale-while-revalidate",
+ *   maxAge: 120_000,
+ *   staleIfError: 300_000,
+ * });
+ * ```
+ */
+export function createCachedLoader<TProps, TResult>(
+  name: string,
+  loaderFn: (props: TProps) => Promise<TResult>,
+  optionsOrProfile: CachedLoaderOptions | CacheProfileName,
+): (props: TProps) => Promise<TResult> {
+  const resolved = resolveOptions(optionsOrProfile);
+  const { policy, maxAge = DEFAULT_MAX_AGE, staleIfError = 0, keyFn = JSON.stringify } = resolved;
+
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+  const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
+
+  if (policy === "no-store") return loaderFn;
+
+  return async (props: TProps): Promise<TResult> => {
+    const cacheKey = `${name}::${keyFn(props)}`;
+
+    const inflight = inflightRequests.get(cacheKey);
+    if (inflight) {
+      // Treat in-flight dedup as a cache hit — avoided the origin call.
+      recordCacheMetric(true, name, undefined, "cachedLoader");
+      const start = performance.now();
+      return inflight.then((r) => {
+        recordLoaderMetric(name, performance.now() - start, "HIT");
+        return r as TResult;
+      });
+    }
+
+    if (isDev) {
+      // Dev mode: no caching, but still useful to count attempts.
+      recordCacheMetric(false, name, undefined, "cachedLoader");
+      const devStart = performance.now();
+      const promise = withInflightTimeout(
+        withTracing(
+          "deco.cachedLoader",
+          () => loaderFn(props),
+          { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
+        ),
+        `cachedLoader:dev ${cacheKey}`,
+      )
+        .then((r) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          return r;
+        })
+        .catch((err) => {
+          recordLoaderMetric(name, performance.now() - devStart, "BYPASS");
+          recordLoaderError(name);
+          throw err;
+        })
+        .finally(() => inflightRequests.delete(cacheKey));
+      inflightRequests.set(cacheKey, promise);
+      return promise;
+    }
+
+    const entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
+    const now = Date.now();
+    const isStale = entry ? now - entry.createdAt > maxAge : true;
+
+    if (policy === "no-cache") {
+      if (entry && !isStale) {
+        recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
+        return entry.value;
+      }
+    }
+
+    if (policy === "stale-while-revalidate") {
+      if (entry && !isStale) {
+        recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
+        return entry.value;
+      }
+
+      if (entry && isStale && !entry.refreshing) {
+        // Stale-while-revalidate hit: serve stale, refresh in background.
+        recordCacheMetric(true, name, "STALE-HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-HIT");
+        entry.refreshing = true;
+        loaderFn(props)
+          .then((result) => {
+            setCacheEntry(cacheKey, {
+              value: result,
+              createdAt: Date.now(),
+              refreshing: false,
+              estimatedBytes: estimateBytes(result),
+            });
+            evictIfNeeded();
+          })
+          .catch(() => {
+            // Background refresh failed — entry stays stale.
+            // If past the SIE window, evict so we don't serve indefinitely stale data.
+            entry.refreshing = false;
+            if (staleIfError > 0 && now - entry.createdAt > maxAge + staleIfError) {
+              deleteCacheEntry(cacheKey);
+            }
+          });
+        return entry.value;
+      }
+
+      if (entry) {
+        // Past SIE window — still serve the stale value once but mark
+        // the decision as STALE-ERROR so dashboards can distinguish
+        // this from healthy SWR.
+        recordCacheMetric(true, name, "STALE-ERROR", "cachedLoader");
+        recordLoaderMetric(name, 0, "STALE-ERROR");
+        return entry.value;
+      }
+    }
+
+    // Cache miss — emit metric, then run loader inside a span so individual
+    // slow loaders are visible in traces.
+    recordCacheMetric(false, name, "MISS", "cachedLoader");
+    const loaderStart = performance.now();
+    const promise = withInflightTimeout(
+      withTracing("deco.cachedLoader", () => loaderFn(props), {
+        "deco.loader": name,
+        "deco.cache.policy": policy,
+      }),
+      `cachedLoader ${cacheKey}`,
+    )
+      .then((result) => {
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
+        setCacheEntry(cacheKey, {
+          value: result,
+          createdAt: Date.now(),
+          refreshing: false,
+          estimatedBytes: estimateBytes(result),
+        });
+        evictIfNeeded();
+        return result;
+      })
+      .catch((err) => {
+        // SIE fallback: if we have a stale entry within the error window, return it
+        if (staleIfError > 0 && entry) {
+          const age = now - entry.createdAt;
+          if (age < maxAge + staleIfError) {
+            console.warn(
+              `[cachedLoader] ${name}: origin error, serving stale entry (age=${Math.round(age / 1000)}s, sie=${Math.round(staleIfError / 1000)}s)`,
+            );
+            recordLoaderMetric(name, performance.now() - loaderStart, "STALE-ERROR");
+            return entry.value;
+          }
+        }
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
+        recordLoaderError(name);
+        throw err;
+      })
+      .finally(() => inflightRequests.delete(cacheKey));
+
+    inflightRequests.set(cacheKey, promise);
+    return promise;
+  };
+}
+
+/**
+ * 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.
+ */
+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";
+  }
+
+  maxAge = maxAge ?? defaults?.maxAge;
+
+  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,
+  });
+}
+
+/** Clear all cached entries. Useful for decofile hot-reload. */
+export function clearLoaderCache() {
+  cache.clear();
+  cacheBytes = 0;
+  inflightRequests.clear();
+}
+
+/** Get cache stats for diagnostics. */
+export function getLoaderCacheStats() {
+  return {
+    entries: cache.size,
+    inflight: inflightRequests.size,
+    estimatedBytes: cacheBytes,
+    maxBytes: MAX_CACHE_BYTES,
+  };
+}

package/src/sdk/clx.ts

@@ -0,0 +1,5 @@
+/** Filter out nullable values, join and minify class names */
+export const clx = (...args: (string | null | undefined | false)[]) =>
+  args.filter(Boolean).join(" ").replace(/\s\s+/g, " ");
+
+export default clx;

package/src/sdk/cn.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { clx, cn } from "./cn";
+
+describe("cn", () => {
+  it("joins strings", () => {
+    expect(cn("a", "b", "c")).toBe("a b c");
+  });
+
+  it("supports conditional objects", () => {
+    expect(cn("a", { b: true, c: false }, "d")).toBe("a b d");
+  });
+
+  it("filters out falsy values", () => {
+    expect(cn("a", null, undefined, false, 0 as any, "b")).toBe("a b");
+  });
+
+  it("merges conflicting Tailwind utilities (last one wins)", () => {
+    expect(cn("p-2", "p-4")).toBe("p-4");
+  });
+
+  it("merges hover variants independently from base utilities", () => {
+    expect(cn("p-2", "hover:p-4")).toBe("p-2 hover:p-4");
+  });
+});
+
+describe("clx (re-exported)", () => {
+  it("filters falsy and joins with single spaces", () => {
+    expect(clx("a", null, "b", undefined, "c")).toBe("a b c");
+  });
+
+  it("does NOT merge conflicting utilities (that's cn's job)", () => {
+    expect(clx("p-2", "p-4")).toBe("p-2 p-4");
+  });
+});

package/src/sdk/cn.ts

@@ -0,0 +1,28 @@
+/**
+ * `cn(...inputs)` — the canonical Tailwind class-name combinator
+ * (clsx + tailwind-merge). Every storefront we audited shipped a
+ * site-local copy of this; we promote it to the framework so sites
+ * can drop the duplicate.
+ *
+ * Behaviour:
+ *   - Accepts the full `clsx` input format (strings, objects, arrays,
+ *     conditionals, falsy values).
+ *   - De-duplicates conflicting Tailwind utilities via `tailwind-merge`
+ *     (e.g. `cn("p-2", "p-4")` → `"p-4"`).
+ *
+ * The simpler `clx` (no tailwind-merge, just `filter+join`) is still
+ * exported from `@decocms/start/sdk/clx` for cases where you want to
+ * keep the literal class string. Re-exported here so a single import
+ * covers both.
+ */
+
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export { clx } from "./clx";
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}
+
+export type { ClassValue };

package/src/sdk/composite.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { MeterAdapter } from "../middleware/observability";
+import { createCompositeLogger, createCompositeMeter } from "./composite";
+import type { LoggerAdapter } from "./logger";
+
+describe("createCompositeLogger", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("fans calls out to every adapter", () => {
+    const aCalls: any[][] = [];
+    const bCalls: any[][] = [];
+    const a: LoggerAdapter = { log: (...args) => void aCalls.push(args) };
+    const b: LoggerAdapter = { log: (...args) => void bCalls.push(args) };
+    const composite = createCompositeLogger([a, b]);
+
+    composite.log("info", "hello", { foo: 1 });
+
+    expect(aCalls).toEqual([["info", "hello", { foo: 1 }]]);
+    expect(bCalls).toEqual([["info", "hello", { foo: 1 }]]);
+  });
+
+  it("filters falsy entries (null/undefined/false)", () => {
+    const calls: any[] = [];
+    const a: LoggerAdapter = { log: (...args) => void calls.push(args) };
+    const composite = createCompositeLogger([null, a, undefined, false]);
+    composite.log("info", "ok");
+    // adapter receives the call with no third arg (undefined is omitted)
+    expect(calls.length).toBe(1);
+    expect(calls[0][0]).toBe("info");
+    expect(calls[0][1]).toBe("ok");
+  });
+
+  it("isolates errors so one bad adapter does not block others", () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const okCalls: any[][] = [];
+    const broken: LoggerAdapter = {
+      log() {
+        throw new Error("boom");
+      },
+    };
+    const ok: LoggerAdapter = { log: (...args) => void okCalls.push(args) };
+    const composite = createCompositeLogger([broken, ok]);
+
+    expect(() => composite.log("error", "still goes through")).not.toThrow();
+    expect(okCalls.length).toBe(1);
+    expect(okCalls[0][0]).toBe("error");
+    expect(okCalls[0][1]).toBe("still goes through");
+    expect(errSpy).toHaveBeenCalled(); // composite reports the failure
+  });
+
+  it("returns the single adapter directly when only one is provided", () => {
+    const a: LoggerAdapter = { log: () => {} };
+    expect(createCompositeLogger([a])).toBe(a);
+  });
+});
+
+describe("createCompositeMeter", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  function recorder() {
+    const counter: any[] = [];
+    const gauge: any[] = [];
+    const histo: any[] = [];
+    const meter: MeterAdapter = {
+      counterInc: (n, v, l) => void counter.push([n, v, l]),
+      gaugeSet: (n, v, l) => void gauge.push([n, v, l]),
+      histogramRecord: (n, v, l) => void histo.push([n, v, l]),
+    };
+    return { meter, counter, gauge, histo };
+  }
+
+  it("fans counter/gauge/histogram across meters", () => {
+    const a = recorder();
+    const b = recorder();
+    const composite = createCompositeMeter([a.meter, b.meter]);
+
+    composite.counterInc("c", 1, { p: "/" });
+    composite.gaugeSet?.("g", 5);
+    composite.histogramRecord?.("h", 100, { route: "/p" });
+
+    expect(a.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(a.counter[0][2]).toEqual({ p: "/" });
+    expect(b.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(a.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(b.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(a.histo[0]).toEqual(["h", 100, { route: "/p" }]);
+    expect(b.histo[0]).toEqual(["h", 100, { route: "/p" }]);
+  });
+
+  it("isolates errors per meter and per call type", () => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    const broken: MeterAdapter = {
+      counterInc: () => {
+        throw new Error("c");
+      },
+      gaugeSet: () => {
+        throw new Error("g");
+      },
+      histogramRecord: () => {
+        throw new Error("h");
+      },
+    };
+    const ok = recorder();
+    const composite = createCompositeMeter([broken, ok.meter]);
+
+    composite.counterInc("c", 1);
+    composite.gaugeSet?.("g", 5);
+    composite.histogramRecord?.("h", 100);
+
+    expect(ok.counter[0].slice(0, 2)).toEqual(["c", 1]);
+    expect(ok.gauge[0].slice(0, 2)).toEqual(["g", 5]);
+    expect(ok.histo[0].slice(0, 2)).toEqual(["h", 100]);
+  });
+
+  it("skips meters that don't implement optional ops", () => {
+    const onlyCounter: MeterAdapter = { counterInc: () => {} };
+    const composite = createCompositeMeter([onlyCounter]);
+    expect(() => composite.gaugeSet?.("g", 1)).not.toThrow();
+    expect(() => composite.histogramRecord?.("h", 1)).not.toThrow();
+  });
+});

package/src/sdk/composite.ts

@@ -0,0 +1,114 @@
+/**
+ * Composite adapters — fan out to multiple backends with try/catch isolation.
+ *
+ * Used by `instrumentWorker()` so the same logger/meter can dual-emit to
+ * (e.g.) console-JSON + OTLP, or AE + OTLP, without any one backend's
+ * failure taking down the others.
+ *
+ * The "always include console-JSON logger" guarantee in the observability
+ * plan relies on this: even if HyperDX is down, the local console adapter
+ * still records the line.
+ */
+
+import type { MeterAdapter } from "../middleware/observability";
+import type { LoggerAdapter, LogLevel } from "./logger";
+
+type Labels = Record<string, string | number | boolean>;
+
+// ---------------------------------------------------------------------------
+// Logger
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single LoggerAdapter that fans every call out to all
+ * provided adapters. Falsy entries (e.g. `otelEnabled ? otelAdapter : null`)
+ * are filtered out so call sites can write:
+ *
+ * ```ts
+ * createCompositeLogger([defaultLoggerAdapter, otelEnabled ? otelLogger : null]);
+ * ```
+ *
+ * Each downstream `.log()` call is isolated in try/catch so a thrown
+ * error in one backend cannot suppress the others.
+ */
+export function createCompositeLogger(
+  adapters: Array<LoggerAdapter | null | undefined | false>,
+): LoggerAdapter {
+  const list = adapters.filter((a): a is LoggerAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    log(level: LogLevel, msg: string, attrs?: Record<string, unknown>) {
+      for (const adapter of list) {
+        try {
+          adapter.log(level, msg, attrs);
+        } catch (error) {
+          // Use console.error directly — calling logger here would recurse.
+          try {
+            console.error("[composite-logger] adapter failed", String(error));
+          } catch {
+            /* swallow */
+          }
+        }
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Meter
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a single MeterAdapter that fans counter/gauge/histogram writes
+ * out to all provided meters. Same semantics as `createCompositeLogger`:
+ * falsy entries are dropped, each downstream call is try/catch isolated.
+ */
+export function createCompositeMeter(
+  adapters: Array<MeterAdapter | null | undefined | false>,
+): MeterAdapter {
+  const list = adapters.filter((a): a is MeterAdapter => Boolean(a));
+
+  if (list.length === 1) return list[0];
+
+  return {
+    counterInc(name: string, value?: number, labels?: Labels) {
+      for (const m of list) {
+        try {
+          m.counterInc(name, value, labels);
+        } catch (error) {
+          warn("counterInc", name, error);
+        }
+      }
+    },
+    gaugeSet(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.gaugeSet) continue;
+        try {
+          m.gaugeSet(name, value, labels);
+        } catch (error) {
+          warn("gaugeSet", name, error);
+        }
+      }
+    },
+    histogramRecord(name: string, value: number, labels?: Labels) {
+      for (const m of list) {
+        if (!m.histogramRecord) continue;
+        try {
+          m.histogramRecord(name, value, labels);
+        } catch (error) {
+          warn("histogramRecord", name, error);
+        }
+      }
+    },
+  };
+}
+
+function warn(op: string, metric: string, error: unknown) {
+  try {
+    console.error(`[composite-meter] ${op}(${metric}) adapter failed`, String(error));
+  } catch {
+    /* swallow */
+  }
+}