@notion-headless-cms/core 0.3.25 → 0.4.0

package/dist/hooks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.mjs","names":[],"sources":["../src/hooks.ts"],"sourcesContent":["import type { BaseContentItem } from \"./types/content\";\nimport type { CMSHooks, MaybePromise } from \"./types/hooks\";\nimport type { Logger } from \"./types/logger\";\nimport type { CMSPlugin } from \"./types/plugin\";\n\n/**\n * プラグイン配列とダイレクトフックを合成して単一の CMSHooks を返す。\n * beforeCacheMeta / beforeCacheContent / afterRender はパイプライン（前の出力が次の入力）。\n * オブザーバー系は全員に同じ値を渡し、例外は logger に流して握りつぶす。\n */\nexport function mergeHooks<T extends BaseContentItem>(\n  plugins: CMSPlugin<T>[],\n  directHooks?: CMSHooks<T>,\n  logger?: Logger,\n): CMSHooks<T> {\n  const allHooks: CMSHooks<T>[] = [\n    ...plugins.map((p) => p.hooks ?? {}),\n    ...(directHooks ? [directHooks] : []),\n  ];\n\n  if (allHooks.length === 0) return {};\n\n  return {\n    beforeCacheMeta: buildMetaPipeline(allHooks),\n    beforeCacheContent: buildContentPipeline(allHooks),\n    afterRender: buildRenderPipeline(allHooks),\n    onCacheHit: buildObserver(allHooks, \"onCacheHit\", logger),\n    onCacheMiss: buildObserver(allHooks, \"onCacheMiss\", logger),\n    onCacheRevalidated: buildObserver(allHooks, \"onCacheRevalidated\", logger),\n    onContentRevalidated: buildObserver(\n      allHooks,\n      \"onContentRevalidated\",\n      logger,\n    ),\n    onListCacheHit: buildObserver(allHooks, \"onListCacheHit\", logger),\n    onListCacheMiss: buildObserver(allHooks, \"onListCacheMiss\", logger),\n    onListCacheRevalidated: buildObserver(\n      allHooks,\n      \"onListCacheRevalidated\",\n      logger,\n    ),\n    onError: buildObserver(allHooks, \"onError\", logger),\n    onRenderStart: buildObserver(allHooks, \"onRenderStart\", logger),\n    onRenderEnd: buildObserver(allHooks, \"onRenderEnd\", logger),\n  };\n}\n\nfunction buildMetaPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"beforeCacheMeta\"] {\n  const fns = hooks\n    .map((h) => h.beforeCacheMeta)\n    .filter(Boolean) as NonNullable<CMSHooks<T>[\"beforeCacheMeta\"]>[];\n  if (fns.length === 0) return undefined;\n  return async (meta) => {\n    let current = meta;\n    for (const fn of fns) {\n      current = await (fn(current) as MaybePromise<typeof meta>);\n    }\n    return current;\n  };\n}\n\nfunction buildContentPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"beforeCacheContent\"] {\n  const fns = hooks\n    .map((h) => h.beforeCacheContent)\n    .filter(Boolean) as NonNullable<CMSHooks<T>[\"beforeCacheContent\"]>[];\n  if (fns.length === 0) return undefined;\n  return async (content, item) => {\n    let current = content;\n    for (const fn of fns) {\n      current = await (fn(current, item) as MaybePromise<typeof content>);\n    }\n    return current;\n  };\n}\n\nfunction buildRenderPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"afterRender\"] {\n  const fns = hooks.map((h) => h.afterRender).filter(Boolean) as NonNullable<\n    CMSHooks<T>[\"afterRender\"]\n  >[];\n  if (fns.length === 0) return undefined;\n  return async (html, item) => {\n    let current = html;\n    for (const fn of fns) {\n      current = await (fn(current, item) as MaybePromise<string>);\n    }\n    return current;\n  };\n}\n\nfunction buildObserver<T extends BaseContentItem, K extends keyof CMSHooks<T>>(\n  hooks: CMSHooks<T>[],\n  key: K,\n  logger?: Logger,\n): CMSHooks<T>[K] {\n  const fns = hooks.map((h) => h[key]).filter(Boolean);\n  if (fns.length === 0) return undefined;\n  return ((...args: unknown[]) => {\n    for (const fn of fns) {\n      try {\n        (fn as (...a: unknown[]) => void)(...args);\n      } catch (err) {\n        logger?.error?.(\"観測フックで例外が発生\", {\n          hook: String(key),\n          error: err instanceof Error ? err.message : String(err),\n        });\n      }\n    }\n  }) as CMSHooks<T>[K];\n}\n\n/** プラグイン配列とダイレクトロガーを合成して単一の Logger を返す。 */\nexport function mergeLoggers(\n  plugins: Array<{ logger?: Partial<Logger> }>,\n  directLogger?: Logger,\n): Logger | undefined {\n  const loggers: Partial<Logger>[] = [\n    ...plugins.map((p) => p.logger ?? {}),\n    ...(directLogger ? [directLogger] : []),\n  ];\n  if (loggers.length === 0) return undefined;\n\n  const merged: Logger = {};\n  for (const level of [\"debug\", \"info\", \"warn\", \"error\"] as const) {\n    const fns = loggers.map((l) => l[level]).filter(Boolean) as NonNullable<\n      Logger[typeof level]\n    >[];\n    if (fns.length > 0) {\n      merged[level] = (message, context) => {\n        for (const fn of fns) fn(message, context);\n      };\n    }\n  }\n  return merged;\n}\n"],"mappings":"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"}
+{"version":3,"file":"hooks.mjs","names":[],"sources":["../src/hooks.ts"],"sourcesContent":["import type { BaseContentItem } from \"./types/content\";\nimport type { CMSHooks, MaybePromise } from \"./types/hooks\";\nimport type { Logger } from \"./types/logger\";\nimport type { CMSPlugin } from \"./types/plugin\";\n\n/**\n * プラグイン配列とダイレクトフックを合成して単一の CMSHooks を返す。\n * beforeCacheMeta / beforeCacheContent / afterRender はパイプライン（前の出力が次の入力）。\n * オブザーバー系は全員に同じ値を渡し、例外は logger に流して握りつぶす。\n */\nexport function mergeHooks<T extends BaseContentItem>(\n  plugins: CMSPlugin<T>[],\n  directHooks?: CMSHooks<T>,\n  logger?: Logger,\n): CMSHooks<T> {\n  const allHooks: CMSHooks<T>[] = [\n    ...plugins.map((p) => p.hooks ?? {}),\n    ...(directHooks ? [directHooks] : []),\n  ];\n\n  if (allHooks.length === 0) return {};\n\n  return {\n    beforeCacheMeta: buildMetaPipeline(allHooks),\n    beforeCacheContent: buildContentPipeline(allHooks),\n    afterRender: buildRenderPipeline(allHooks),\n    onCacheHit: buildObserver(allHooks, \"onCacheHit\", logger),\n    onCacheMiss: buildObserver(allHooks, \"onCacheMiss\", logger),\n    onCacheRevalidated: buildObserver(allHooks, \"onCacheRevalidated\", logger),\n    onContentRevalidated: buildObserver(\n      allHooks,\n      \"onContentRevalidated\",\n      logger,\n    ),\n    onListCacheHit: buildObserver(allHooks, \"onListCacheHit\", logger),\n    onListCacheMiss: buildObserver(allHooks, \"onListCacheMiss\", logger),\n    onListCacheRevalidated: buildObserver(\n      allHooks,\n      \"onListCacheRevalidated\",\n      logger,\n    ),\n    onError: buildObserver(allHooks, \"onError\", logger),\n    onRenderStart: buildObserver(allHooks, \"onRenderStart\", logger),\n    onRenderEnd: buildObserver(allHooks, \"onRenderEnd\", logger),\n  };\n}\n\nfunction buildMetaPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"beforeCacheMeta\"] {\n  const fns = hooks\n    .map((h) => h.beforeCacheMeta)\n    .filter(Boolean) as NonNullable<CMSHooks<T>[\"beforeCacheMeta\"]>[];\n  if (fns.length === 0) return undefined;\n  return async (meta) => {\n    let current = meta;\n    for (const fn of fns) {\n      current = await (fn(current) as MaybePromise<typeof meta>);\n    }\n    return current;\n  };\n}\n\nfunction buildContentPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"beforeCacheContent\"] {\n  const fns = hooks\n    .map((h) => h.beforeCacheContent)\n    .filter(Boolean) as NonNullable<CMSHooks<T>[\"beforeCacheContent\"]>[];\n  if (fns.length === 0) return undefined;\n  return async (content, item) => {\n    let current = content;\n    for (const fn of fns) {\n      current = await (fn(current, item) as MaybePromise<typeof content>);\n    }\n    return current;\n  };\n}\n\nfunction buildRenderPipeline<T extends BaseContentItem>(\n  hooks: CMSHooks<T>[],\n): CMSHooks<T>[\"afterRender\"] {\n  const fns = hooks.map((h) => h.afterRender).filter(Boolean) as NonNullable<\n    CMSHooks<T>[\"afterRender\"]\n  >[];\n  if (fns.length === 0) return undefined;\n  return async (html, item) => {\n    let current = html;\n    for (const fn of fns) {\n      current = await (fn(current, item) as MaybePromise<string>);\n    }\n    return current;\n  };\n}\n\nfunction buildObserver<T extends BaseContentItem, K extends keyof CMSHooks<T>>(\n  hooks: CMSHooks<T>[],\n  key: K,\n  logger?: Logger,\n): CMSHooks<T>[K] {\n  const fns = hooks.map((h) => h[key]).filter(Boolean);\n  if (fns.length === 0) return undefined;\n  return ((...args: unknown[]) => {\n    for (const fn of fns) {\n      try {\n        (fn as (...a: unknown[]) => void)(...args);\n      } catch (err) {\n        logger?.error?.(\"観測フックで例外が発生\", {\n          hook: String(key),\n          error: err instanceof Error ? err.message : String(err),\n        });\n      }\n    }\n  }) as CMSHooks<T>[K];\n}\n\n/** プラグイン配列とダイレクトロガーを合成して単一の Logger を返す。 */\nexport function mergeLoggers(\n  plugins: Array<{ logger?: Partial<Logger> }>,\n  directLogger?: Logger,\n): Logger | undefined {\n  const loggers: Partial<Logger>[] = [\n    ...plugins.map((p) => p.logger ?? {}),\n    ...(directLogger ? [directLogger] : []),\n  ];\n  if (loggers.length === 0) return undefined;\n\n  const merged: Logger = {};\n  for (const level of [\"debug\", \"info\", \"warn\", \"error\"] as const) {\n    const fns = loggers.map((l) => l[level]).filter(Boolean) as NonNullable<\n      Logger[typeof level]\n    >[];\n    if (fns.length > 0) {\n      merged[level] = (message, context) => {\n        for (const fn of fns) fn(message, context);\n      };\n    }\n  }\n  return merged;\n}\n\n/**\n * 既存 Logger をラップし、全ログコンテキストに `traceId` を自動で付与する。\n * 呼び出し側が明示的に traceId を渡した場合はその値を優先する。\n *\n * `createClient` がクライアント単位の trace ID を発行し、ネストした操作\n * (list / find / SWR 再生成 / retry) で同じ ID をログに伝搬するために使う。\n */\nexport function withTraceId(\n  logger: Logger | undefined,\n  traceId: string,\n): Logger | undefined {\n  if (!logger) return undefined;\n  const wrapped: Logger = {};\n  for (const level of [\"debug\", \"info\", \"warn\", \"error\"] as const) {\n    const fn = logger[level];\n    if (!fn) continue;\n    wrapped[level] = (message, context) => {\n      fn(message, { traceId, ...(context ?? {}) });\n    };\n  }\n  return wrapped;\n}\n"],"mappings":";;;;;;AAUA,SAAgB,WACd,SACA,aACA,QACa;CACb,MAAM,WAA0B,CAC9B,GAAG,QAAQ,KAAK,MAAM,EAAE,SAAS,CAAC,CAAC,GACnC,GAAI,cAAc,CAAC,WAAW,IAAI,CAAC,CACrC;CAEA,IAAI,SAAS,WAAW,GAAG,OAAO,CAAC;CAEnC,OAAO;EACL,iBAAiB,kBAAkB,QAAQ;EAC3C,oBAAoB,qBAAqB,QAAQ;EACjD,aAAa,oBAAoB,QAAQ;EACzC,YAAY,cAAc,UAAU,cAAc,MAAM;EACxD,aAAa,cAAc,UAAU,eAAe,MAAM;EAC1D,oBAAoB,cAAc,UAAU,sBAAsB,MAAM;EACxE,sBAAsB,cACpB,UACA,wBACA,MACF;EACA,gBAAgB,cAAc,UAAU,kBAAkB,MAAM;EAChE,iBAAiB,cAAc,UAAU,mBAAmB,MAAM;EAClE,wBAAwB,cACtB,UACA,0BACA,MACF;EACA,SAAS,cAAc,UAAU,WAAW,MAAM;EAClD,eAAe,cAAc,UAAU,iBAAiB,MAAM;EAC9D,aAAa,cAAc,UAAU,eAAe,MAAM;CAC5D;AACF;AAEA,SAAS,kBACP,OACgC;CAChC,MAAM,MAAM,MACT,KAAK,MAAM,EAAE,eAAe,EAC5B,OAAO,OAAO;CACjB,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;CAC7B,OAAO,OAAO,SAAS;EACrB,IAAI,UAAU;EACd,KAAK,MAAM,MAAM,KACf,UAAU,MAAO,GAAG,OAAO;EAE7B,OAAO;CACT;AACF;AAEA,SAAS,qBACP,OACmC;CACnC,MAAM,MAAM,MACT,KAAK,MAAM,EAAE,kBAAkB,EAC/B,OAAO,OAAO;CACjB,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;CAC7B,OAAO,OAAO,SAAS,SAAS;EAC9B,IAAI,UAAU;EACd,KAAK,MAAM,MAAM,KACf,UAAU,MAAO,GAAG,SAAS,IAAI;EAEnC,OAAO;CACT;AACF;AAEA,SAAS,oBACP,OAC4B;CAC5B,MAAM,MAAM,MAAM,KAAK,MAAM,EAAE,WAAW,EAAE,OAAO,OAAO;CAG1D,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;CAC7B,OAAO,OAAO,MAAM,SAAS;EAC3B,IAAI,UAAU;EACd,KAAK,MAAM,MAAM,KACf,UAAU,MAAO,GAAG,SAAS,IAAI;EAEnC,OAAO;CACT;AACF;AAEA,SAAS,cACP,OACA,KACA,QACgB;CAChB,MAAM,MAAM,MAAM,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,OAAO;CACnD,IAAI,IAAI,WAAW,GAAG,OAAO,KAAA;CAC7B,SAAS,GAAG,SAAoB;EAC9B,KAAK,MAAM,MAAM,KACf,IAAI;GACF,GAAkC,GAAG,IAAI;EAC3C,SAAS,KAAK;GACZ,QAAQ,QAAQ,eAAe;IAC7B,MAAM,OAAO,GAAG;IAChB,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;GACxD,CAAC;EACH;CAEJ;AACF;;AAGA,SAAgB,aACd,SACA,cACoB;CACpB,MAAM,UAA6B,CACjC,GAAG,QAAQ,KAAK,MAAM,EAAE,UAAU,CAAC,CAAC,GACpC,GAAI,eAAe,CAAC,YAAY,IAAI,CAAC,CACvC;CACA,IAAI,QAAQ,WAAW,GAAG,OAAO,KAAA;CAEjC,MAAM,SAAiB,CAAC;CACxB,KAAK,MAAM,SAAS;EAAC;EAAS;EAAQ;EAAQ;CAAO,GAAY;EAC/D,MAAM,MAAM,QAAQ,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,OAAO;EAGvD,IAAI,IAAI,SAAS,GACf,OAAO,UAAU,SAAS,YAAY;GACpC,KAAK,MAAM,MAAM,KAAK,GAAG,SAAS,OAAO;EAC3C;CAEJ;CACA,OAAO;AACT;;;;;;;;AASA,SAAgB,YACd,QACA,SACoB;CACpB,IAAI,CAAC,QAAQ,OAAO,KAAA;CACpB,MAAM,UAAkB,CAAC;CACzB,KAAK,MAAM,SAAS;EAAC;EAAS;EAAQ;EAAQ;CAAO,GAAY;EAC/D,MAAM,KAAK,OAAO;EAClB,IAAI,CAAC,IAAI;EACT,QAAQ,UAAU,SAAS,YAAY;GACrC,GAAG,SAAS;IAAE;IAAS,GAAI,WAAW,CAAC;GAAG,CAAC;EAC7C;CACF;CACA,OAAO;AACT"}

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import { a as CachedItemMeta, c as ContentResult, i as CachedItemList, l as ImageRef, n as CMSSchemaProperties, o as StorageBinary, r as CachedItemContent, s as ContentBlock, t as BaseContentItem, u as InlineNode } from "./content-DwsfWZao.mjs";
-import { a as InvalidateKind, c as PropertyMap, i as DataSource, l as WebhookConfig, n as DocumentCacheOps, o as InvalidateScope, r as ImageCacheOps, s as PropertyDef, t as CacheAdapter } from "./cache-DS81aOcC.mjs";
+import { a as ImageCacheOps, c as InvalidateScope, d as WebhookConfig, i as DocumentCacheOps, l as PropertyDef, n as CacheAdapterStats, o as DataSource, r as CacheAreaStats, s as InvalidateKind, t as CacheAdapter, u as PropertyMap } from "./cache-v9jTMnYd.mjs";
 import { a as isCMSError, i as CMSErrorContext, n as CMSError, o as isCMSErrorInNamespace, r as CMSErrorCode, s as matchCMSError, t as BuiltInCMSErrorCode } from "./errors-DcNErfYk.mjs";
-import { a as MaybePromise, i as CMSHooks, n as definePlugin, r as Logger, t as CMSPlugin } from "./plugin-Dct12kp2.mjs";
-import { a as InferCollectionItem, c as RenderOptions, d as SWRConfig, i as CreateClientOptions, l as RendererFn, m as MergeSourceCollections, n as CollectionsConfig, o as LogLevel, p as CMSSources, r as ContentConfig, s as RateLimiterConfig, u as RendererPluginList } from "./config-DYxyW3SR.mjs";
+import { a as CMSHooks, i as Logger, n as definePlugin, o as MaybePromise, r as LogContext, t as CMSPlugin } from "./plugin-BmrOz8T6.mjs";
+import { a as InferCollectionItem, c as RenderOptions, d as SWRConfig, i as CreateClientOptions, l as RendererFn, m as MergeSourceCollections, n as CollectionsConfig, o as LogLevel, p as CMSSources, r as ContentConfig, s as RateLimiterConfig, u as RendererPluginList } from "./config-DuaVFspk.mjs";
 import { MemoryCacheOptions, memoryCache } from "./cache/memory.mjs";
 import { mergeHooks, mergeLoggers } from "./hooks.mjs";
 import { NodePresetOptions, nodePreset } from "./preset/node.mjs";
@@ -204,8 +204,36 @@ declare function createHandler(adapter: HandlerAdapter, opts?: HandlerOptions):
 //#region src/cms.d.ts
 /** コレクション別アクセス + グローバル操作の合成型。 */
 type CMSClient<C extends CollectionsConfig> = { [K in keyof C]: CollectionClient<InferCollectionItem<C[K]>> } & CMSGlobalOps;
+/**
+ * `cms.stats()` が返す集約済みキャッシュ統計。
+ * 各 adapter の `stats()` 戻り値をそのまま配列で保持しつつ、ヒット率を算出する。
+ */
+interface CMSStats {
+  /** クライアント単位の trace ID (`createClient` で発行)。 */
+  traceId: string;
+  /** ドキュメントキャッシュの集計 (`handles: ["document"]` の adapter の `stats()` 戻り値)。 */
+  document?: {
+    adapter: string;
+    hits: number;
+    misses: number;
+    entries?: number;
+    sizeBytes?: number; /** 0〜1。`hits + misses === 0` のときは 0。 */
+    hitRate: number;
+  };
+  /** 画像キャッシュの集計 (`handles: ["image"]` の adapter の `stats()` 戻り値)。 */
+  image?: {
+    adapter: string;
+    hits: number;
+    misses: number;
+    entries?: number;
+    sizeBytes?: number;
+    hitRate: number;
+  };
+}
 interface CMSGlobalOps {
   readonly collections: readonly string[];
+  /** クライアント単位の trace ID (`createClient` で発行)。 */
+  readonly traceId: string;
   invalidate(scope?: InvalidateScope): Promise<void>;
   /** Web Standard な Request/Response ベースのルートハンドラ (画像プロキシ + webhook)。 */
   handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
@@ -216,6 +244,12 @@ interface CMSGlobalOps {
    */
   readonly cacheImage: ((url: string) => Promise<string>) | undefined;
   readonly imageProxyBase: string;
+  /**
+   * ドキュメント / 画像キャッシュのヒット・ミス・サイズを集約して返す。
+   * 各キャッシュアダプタの `stats()` を呼ぶだけで副作用はない。
+   * `stats()` を実装していない adapter は集計から除外される (noop など)。
+   */
+  stats(): Promise<CMSStats>;
 }
 /**
  * CMS クライアントを生成する。
@@ -241,7 +275,12 @@ interface RetryConfig {
   baseDelayMs: number;
   /** true のとき指数バックオフにランダムジッターを加える（Thundering Herd 対策）。デフォルト: true */
   jitter?: boolean;
-  onRetry?: (attempt: number, status: number) => void;
+  /**
+   * リトライ前に呼ばれるフック。`attempt` は 1 始まり、`status` はリトライ対象の HTTP ステータス、
+   * `delayMs` は次回試行までの実際の待機時間 (ジッター反映後)。
+   * 既存呼び出しは `attempt` / `status` だけで動くよう `delayMs` は省略可。
+   */
+  onRetry?: (attempt: number, status: number, delayMs?: number) => void;
 }
 declare const DEFAULT_RETRY_CONFIG: RetryConfig;
 /**
@@ -254,5 +293,5 @@ declare const DEFAULT_RETRY_CONFIG: RetryConfig;
  */
 declare function withRetry<T>(fn: () => Promise<T>, config: RetryConfig): Promise<T>;
 //#endregion
-export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CMSSources, type CacheAdapter, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, type ContentBlock, type ContentConfig, type ContentResult, type CreateClientOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type FindOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithContent, type ListOptions, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, type NodePresetOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SWRConfig, type SortOption, type StorageBinary, type WarmOptions, type WarmResult, type WebhookConfig, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, nodePreset, noopDocOps, noopImgOps, sha256Hex, withRetry };
+export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CMSSources, type CacheAdapter, type CacheAdapterStats, type CacheAreaStats, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, type ContentBlock, type ContentConfig, type ContentResult, type CreateClientOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type FindOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithContent, type ListOptions, type LogContext, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, type NodePresetOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SWRConfig, type SortOption, type StorageBinary, type WarmOptions, type WarmResult, type WebhookConfig, createClient, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, nodePreset, noopDocOps, noopImgOps, sha256Hex, withRetry };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { memoryCache } from "./cache/memory.mjs";
 import { CMSError, isCMSError, isCMSErrorInNamespace, matchCMSError } from "./errors.mjs";
-import { mergeHooks, mergeLoggers } from "./hooks.mjs";
+import { mergeHooks, mergeLoggers, withTraceId } from "./hooks.mjs";
 import { nodePreset } from "./preset/node.mjs";
 //#region src/cache.ts
 /** 文字列をSHA-256でハッシュ化し、16進数文字列として返す。画像キーの生成に使用。 */
@@ -314,9 +314,9 @@ async function withRetry(fn, config) {
 		if (status === void 0 || !config.retryOn.includes(status)) throw err;
 		lastError = err;
 		if (attempt < config.maxRetries) {
-			config.onRetry?.(attempt + 1, status);
 			const jitterFactor = config.jitter !== false ? .5 + Math.random() * .5 : 1;
 			const delay = config.baseDelayMs * 2 ** attempt * jitterFactor;
+			config.onRetry?.(attempt + 1, status, delay);
 			await new Promise((resolve) => setTimeout(resolve, delay));
 		}
 	}
@@ -683,10 +683,11 @@ var CollectionClientImpl = class {
 	async fetchListRaw() {
 		return (await withRetry(() => this.ctx.source.list({ publishedStatuses: this.ctx.publishedStatuses.length > 0 ? this.ctx.publishedStatuses : void 0 }), {
 			...this.ctx.retryConfig,
-			onRetry: (attempt, status) => {
+			onRetry: (attempt, status, delayMs) => {
 				this.ctx.logger?.warn?.("list() リトライ中", {
 					attempt,
-					status
+					status,
+					backoffMs: delayMs
 				});
 			}
 		})).filter((item) => {
@@ -698,11 +699,12 @@ var CollectionClientImpl = class {
 	async fetchRaw(slug) {
 		const retryOpts = {
 			...this.ctx.retryConfig,
-			onRetry: (attempt, status) => {
+			onRetry: (attempt, status, delayMs) => {
 				this.ctx.logger?.warn?.("find() リトライ中", {
 					attempt,
 					status,
-					slug
+					slug,
+					backoffMs: delayMs
 				});
 			}
 		};
@@ -870,35 +872,49 @@ function trimTrailingSlash(s) {
 const DEFAULT_IMAGE_PROXY_BASE = "/api/images";
 /**
 * adapter の `handles` を見て先勝ちで document / image を割り当てる。未指定は両方 noop。
+* `cms.stats()` から元 adapter の `stats()` を呼びたいので、解決元 adapter も保持する。
 */
 function resolveCache(cache) {
 	const adapters = cache ?? [];
 	let doc = noopDocOps;
 	let docName = "noop-document";
+	let docAdapter;
 	let img = noopImgOps;
 	let imgName = "noop-image";
+	let imgAdapter;
 	let docFound = false;
 	let imgFound = false;
 	for (const adapter of adapters) {
 		if (!docFound && adapter.handles.includes("document") && adapter.doc) {
 			doc = adapter.doc;
 			docName = adapter.name;
+			docAdapter = adapter;
 			docFound = true;
 		}
 		if (!imgFound && adapter.handles.includes("image") && adapter.img) {
 			img = adapter.img;
 			imgName = adapter.name;
+			imgAdapter = adapter;
 			imgFound = true;
 		}
 	}
 	return {
 		doc,
 		docName,
+		docAdapter,
 		img,
 		imgName,
+		imgAdapter,
 		hasImg: imgFound
 	};
 }
+/**
+* 衝突しにくい短い trace ID を生成する。`{epoch36}-{rand36}` の 10〜12 文字程度。
+* core はゼロ依存ルールに従い node:crypto を静的 import しないため、Math.random ベースで十分。
+*/
+function generateTraceId() {
+	return `${Date.now().toString(36)}-${Math.floor(Math.random() * 36 ** 6).toString(36).padStart(6, "0")}`;
+}
 const LOG_LEVEL_ORDER = {
 	debug: 0,
 	info: 1,
@@ -971,7 +987,9 @@ function createClient(opts) {
 	const rendererFn = opts.renderer;
 	const waitUntil = opts.waitUntil;
 	const baseLogger = mergeLoggers(opts.plugins ?? [], opts.logger);
-	const logger = opts.logLevel ? applyLogLevel(baseLogger, opts.logLevel) : baseLogger;
+	const traceId = generateTraceId();
+	const tracedLogger = withTraceId(baseLogger, traceId);
+	const logger = opts.logLevel ? applyLogLevel(tracedLogger, opts.logLevel) : tracedLogger;
 	const hooks = mergeHooks(opts.plugins ?? [], opts.hooks, logger);
 	const maxConcurrent = opts.rateLimiter?.maxConcurrent ?? 3;
 	const retryConfig = {
@@ -1020,6 +1038,45 @@ function createClient(opts) {
 		collections: collectionNames,
 		cacheImage: cacheRes.hasImg ? buildCacheImageFn(cacheRes.img, cacheRes.imgName, imageProxyBase, logger) : void 0,
 		imageProxyBase,
+		traceId,
+		async stats() {
+			const stats = { traceId };
+			const adapterCache = /* @__PURE__ */ new Map();
+			const ensure = (adapter) => {
+				if (!adapter?.stats) return void 0;
+				const cached = adapterCache.get(adapter);
+				if (cached) return cached;
+				const fresh = adapter.stats();
+				adapterCache.set(adapter, fresh);
+				return fresh;
+			};
+			const docPromise = ensure(cacheRes.docAdapter);
+			const imgPromise = ensure(cacheRes.imgAdapter);
+			const computeHitRate = (h, m) => h + m === 0 ? 0 : h / (h + m);
+			if (docPromise) {
+				const docStats = await docPromise;
+				if (docStats.doc) stats.document = {
+					adapter: docStats.name ?? cacheRes.docName,
+					hits: docStats.doc.hits,
+					misses: docStats.doc.misses,
+					entries: docStats.doc.entries,
+					sizeBytes: docStats.doc.sizeBytes,
+					hitRate: computeHitRate(docStats.doc.hits, docStats.doc.misses)
+				};
+			}
+			if (imgPromise) {
+				const imgStats = await imgPromise;
+				if (imgStats.img) stats.image = {
+					adapter: imgStats.name ?? cacheRes.imgName,
+					hits: imgStats.img.hits,
+					misses: imgStats.img.misses,
+					entries: imgStats.img.entries,
+					sizeBytes: imgStats.img.sizeBytes,
+					hitRate: computeHitRate(imgStats.img.hits, imgStats.img.misses)
+				};
+			}
+			return stats;
+		},
 		async invalidate(scope) {
 			logger?.debug?.("グローバルキャッシュを無効化", {
 				operation: "invalidate",