@decocms/start 6.2.1 → 6.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "6.2.1",
+  "version": "6.3.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/middleware/observability.ts

@@ -253,6 +253,22 @@ export const MetricNames = {
    * `MIGRATION_TOOLING_PLAN.md` for the rationale.
    */
   COMMERCE_REQUEST_DURATION_MS: "commerce_request_duration_ms",
+  /**
+   * Per-loader execution duration. Emitted by `cachedLoader` for every
+   * loader call — cached or not. The `cache_status` label lets dashboards
+   * separate origin latency from in-memory hit latency without needing
+   * to join on traces.
+   *
+   * Canonical labels: `loader`, `cache_status`.
+   */
+  LOADER_DURATION_MS: "loader_duration_ms",
+  /**
+   * Counter incremented when a loader throws. Complements
+   * `loader_duration_ms` for error-rate dashboards.
+   *
+   * Canonical labels: `loader`.
+   */
+  LOADER_ERRORS_TOTAL: "loader_errors_total",
 } as const;
 
 /**
@@ -455,6 +471,35 @@ export function recordCommerceMetric(
   m.histogramRecord?.(MetricNames.COMMERCE_REQUEST_DURATION_MS, durationMs, merged);
 }
 
+/**
+ * Record a loader execution sample. Call from `cachedLoader` after the
+ * loader resolves or rejects. `cache_status` mirrors `CacheDecision` so
+ * dashboards can distinguish HIT (fresh) from STALE-HIT (SWR), STALE-ERROR
+ * (SIE fallback), MISS (origin fetch), and BYPASS (dev / no-store).
+ */
+export function recordLoaderMetric(
+  name: string,
+  durationMs: number,
+  cacheStatus: CacheDecision | "BYPASS",
+) {
+  const m = getState().meter;
+  if (!m) return;
+  m.histogramRecord?.(MetricNames.LOADER_DURATION_MS, durationMs, {
+    loader: name,
+    cache_status: cacheStatus,
+  });
+}
+
+/**
+ * Increment the loader error counter. Call when a loader throws and the
+ * error is not swallowed by a SIE fallback.
+ */
+export function recordLoaderError(name: string) {
+  const m = getState().meter;
+  if (!m) return;
+  m.counterInc(MetricNames.LOADER_ERRORS_TOTAL, 1, { loader: name });
+}
+
 function normalizePath(path: string): string {
   // Collapse dynamic segments to reduce cardinality
   return path

package/src/sdk/cachedLoader.ts

@@ -11,7 +11,12 @@
  * (e.g. "product") which derives timing from the unified profile system.
  */
 
-import { recordCacheMetric, withTracing } from "../middleware/observability";
+import {
+  recordCacheMetric,
+  recordLoaderError,
+  recordLoaderMetric,
+  withTracing,
+} from "../middleware/observability";
 import { type CacheProfileName, loaderCacheOptions } from "./cacheHeaders";
 
 export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
@@ -100,17 +105,32 @@ export function createCachedLoader<TProps, TResult>(
     if (inflight) {
       // Treat in-flight dedup as a cache hit — avoided the origin call.
       recordCacheMetric(true, name, undefined, "cachedLoader");
-      return inflight as Promise<TResult>;
+      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 = withTracing(
         "deco.cachedLoader",
-        () => loaderFn(props).finally(() => inflightRequests.delete(cacheKey)),
+        () => loaderFn(props),
         { "deco.loader": name, "deco.cache.policy": "no-cache-dev" },
-      );
+      )
+        .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;
     }
@@ -122,6 +142,7 @@ export function createCachedLoader<TProps, TResult>(
     if (policy === "no-cache") {
       if (entry && !isStale) {
         recordCacheMetric(true, name, "HIT", "cachedLoader");
+        recordLoaderMetric(name, 0, "HIT");
         return entry.value;
       }
     }
@@ -129,12 +150,14 @@ export function createCachedLoader<TProps, TResult>(
     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) => {
@@ -160,6 +183,7 @@ export function createCachedLoader<TProps, TResult>(
         // 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;
       }
     }
@@ -167,11 +191,13 @@ export function createCachedLoader<TProps, TResult>(
     // 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 = withTracing("deco.cachedLoader", () => loaderFn(props), {
       "deco.loader": name,
       "deco.cache.policy": policy,
     })
       .then((result) => {
+        recordLoaderMetric(name, performance.now() - loaderStart, "MISS");
         cache.set(cacheKey, {
           value: result,
           createdAt: Date.now(),
@@ -190,9 +216,12 @@ export function createCachedLoader<TProps, TResult>(
             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;
       });
 

package/src/sdk/observability.ts

@@ -65,6 +65,8 @@ export {
   MetricNames,
   recordCacheMetric,
   recordCommerceMetric,
+  recordLoaderError,
+  recordLoaderMetric,
   recordRequestMetric,
   type RequestMetricLabels,
   type RequestStore,