@notion-headless-cms/core 0.3.12 → 0.3.14

package/dist/index.d.mts

@@ -1,22 +1,31 @@
-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-CYf6NtCC.mjs";
-import { a as CacheAdapter, c as DataSource, d as PropertyDef, f as PropertyMap, i as memoryCache, l as InvalidateKind, o as DocumentCacheOps, p as WebhookConfig, s as ImageCacheOps, t as MemoryCacheOptions, u as InvalidateScope } from "./memory-Cp-dnNGC.mjs";
-import { a as Logger, i as definePlugin, n as mergeLoggers, o as CMSHooks, r as CMSPlugin, s as MaybePromise, t as mergeHooks } from "./hooks-D3omfgl4.mjs";
-import { BuiltInCMSErrorCode, CMSError, CMSErrorCode, CMSErrorContext, isCMSError, isCMSErrorInNamespace } from "./errors.mjs";
+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-D7PfY-bV.mjs";
+import { a as CacheAdapter, c as DataSource, d as PropertyDef, f as PropertyMap, i as memoryCache, l as InvalidateKind, o as DocumentCacheOps, p as WebhookConfig, s as ImageCacheOps, t as MemoryCacheOptions, u as InvalidateScope } from "./memory-BKDsuGVN.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-CC_x98vG.mjs";
+import { a as Logger, i as definePlugin, n as mergeLoggers, o as CMSHooks, r as CMSPlugin, s as MaybePromise, t as mergeHooks } from "./hooks-C4HRqHLo.mjs";
 
 //#region src/types/collection.d.ts
+/**
+ * `where` フィルタの型。各フィールドに単一値、または OR 候補の配列を指定できる。
+ * 配列を渡すと「いずれかに一致」(in-match) になる。
+ */
+type WhereClause<T extends BaseContentItem> = { [K in keyof T]?: T[K] | readonly T[K][] };
 /** 並び順指定。 */
 interface SortOption<T extends BaseContentItem = BaseContentItem> {
   /** ソートするプロパティ名。 */
   by: keyof T & string;
   /** 昇順 / 降順。デフォルト "desc"。 */
   dir?: "asc" | "desc";
+  /** カスタム comparator。指定した場合 `by` / `dir` より優先される。 */
+  compare?: (a: T, b: T) => number;
 }
 /** `list()` のオプション。ページ取得に必要な絞り込み・ソート・ページングを表現する。 */
 interface ListOptions<T extends BaseContentItem = BaseContentItem> {
-  /** ステータス絞り込み (`publishedStatuses` を上書き)。 */
-  status?: string | readonly string[];
-  /** プロパティ一致フィルタ (in-memory フィルタ)。 */
-  where?: Partial<Record<keyof T, unknown>>;
+  /** ステータス絞り込み (`publishedStatuses` を上書き)。単一値または配列で指定。 */
+  statuses?: string | readonly string[];
+  /** プロパティ一致フィルタ (in-memory フィルタ)。配列は OR 一致。 */
+  where?: WhereClause<T>;
+  /** 任意ロジックのフィルタ関数。`where` より後に適用される。 */
+  filter?: (item: T) => boolean;
   /** タグ絞り込み (schema に tags: string[] フィールドがある場合)。 */
   tag?: string;
   /** ソート。デフォルトは publishedAt の降順。 */
@@ -30,23 +39,19 @@ interface ListOptions<T extends BaseContentItem = BaseContentItem> {
 interface AdjacencyOptions<T extends BaseContentItem = BaseContentItem> {
   sort?: SortOption<T>;
 }
-/** `get()` のオプション。 */
-interface GetOptions {
+/** `find()` のオプション。 */
+interface FindOptions {
   /** true なら TTL に関わらずブロッキングで再取得し、本文 cache を破棄する。 */
-  fresh?: boolean;
+  bypassCache?: boolean;
 }
 /**
- * `get()` の戻り値。アイテム本体に `render()` が生える。
- * `render()` を呼んだ時点で初めて本文をロードする lazy 設計。
+ * `find()` の戻り値。アイテム本体に `html()` / `markdown()` / `blocks()` が生える。
+ * これらを呼んだ時点で初めて本文をロードする lazy 設計。
  */
-type ItemWithRender<T extends BaseContentItem> = T & {
-  /**
-   * 本文を文字列で返す。デフォルトは HTML。
-   * `format: "markdown"` で Markdown を返す。
-   */
-  render(opts?: {
-    format?: "html" | "markdown";
-  }): Promise<string>;
+type ItemWithContent<T extends BaseContentItem> = T & {
+  /** HTML 文字列を返す。 */html(): Promise<string>; /** Markdown 文字列を返す。 */
+  markdown(): Promise<string>; /** コンテンツ AST（ContentBlock 配列）を返す。 */
+  blocks(): Promise<ContentBlock[]>;
 };
 /** `cache.warm()` のオプション。 */
 interface WarmOptions {
@@ -55,56 +60,59 @@ interface WarmOptions {
   /** 進捗コールバック。 */
   onProgress?: (done: number, total: number) => void;
 }
+/** `cache.warm()` の戻り値。 */
+interface WarmResult {
+  ok: number;
+  failed: Array<{
+    slug: string;
+    error: unknown;
+  }>;
+}
 /** コレクションごとのキャッシュ操作 namespace。 */
 interface CollectionCacheOps<T extends BaseContentItem> {
   /**
-   * 指定 slug、または slug 省略時はコレクション全体のキャッシュを失効させる。
+   * コレクション全体のキャッシュを失効させる。
    * 次回 `get` / `list` で source から再取得される。
    */
-  invalidate(slug?: string): Promise<void>;
+  invalidate(): Promise<void>;
+  /**
+   * 指定 slug のアイテムキャッシュを失効させる。
+   * 次回 `get` で source から再取得される。
+   */
+  invalidateItem(slug: string): Promise<void>;
   /**
    * 全アイテムを並列に事前取得・レンダリングしてキャッシュに格納する。
    * SSG ビルド前のウォームアップに利用する。
    */
-  warm(opts?: WarmOptions): Promise<{
-    ok: number;
-    failed: number;
-  }>;
-  /** 前後アイテムのナビゲーション (リスト順序ベース)。 */
-  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
-    prev: T | null;
-    next: T | null;
-  }>;
+  warm(opts?: WarmOptions): Promise<WarmResult>;
 }
 /** `check()` の戻り値。差分なしか、差分ありの場合はアイテムを含む。 */
 type CheckResult<T extends BaseContentItem> = {
   stale: false;
 } | {
   stale: true;
-  item: ItemWithRender<T>;
+  item: ItemWithContent<T>;
 };
 /**
  * コレクション別の CMS クライアント。
- * `cms.posts.get(slug)` / `cms.posts.list()` のようにアクセスする。
+ * `cms.posts.find(slug)` / `cms.posts.list()` のようにアクセスする。
  */
 interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
   /**
-   * スラッグで単件取得。アイテム本体に `render()` が生える。
+   * スラッグで単件取得。アイテム本体に `html()` / `markdown()` / `blocks()` が生える。
    *
    * SWR: TTL 未設定 or 期限内ならキャッシュ即時返却 + バックグラウンド差分チェック。
-   *      TTL 期限切れ、または `opts.fresh === true` でブロッキング取得。
+   *      TTL 期限切れ、または `opts.bypassCache === true` でブロッキング取得。
    *
    * @returns キャッシュまたは source から取得したアイテム。存在しない場合は null。
    */
-  get(slug: string, opts?: GetOptions): Promise<ItemWithRender<T> | null>;
+  find(slug: string, opts?: FindOptions): Promise<ItemWithContent<T> | null>;
   /** 公開済みアイテム一覧を取得する。 */
   list(opts?: ListOptions<T>): Promise<T[]>;
-  /** SSG パラメータ生成 (Next App Router の `generateStaticParams` 互換)。 */
-  params(): Promise<{
-    slug: string;
-  }[]>;
+  /** コレクション内の全スラッグを返す。`generateStaticParams` 等の SSG パラメータ生成に利用する。 */
+  params(): Promise<string[]>;
   /**
-   * Notion から最新版を取得し、`currentVersion`（`item.updatedAt`）と比較する。
+   * Notion から最新版を取得し、`currentVersion`（`item.lastEditedTime`）と比較する。
    * 差分があればキャッシュを更新してアイテムを返す。
    * ページ表示後の1回限りのクライアント再検証エンドポイント用。
    *
@@ -112,6 +120,11 @@ interface CollectionClient<T extends BaseContentItem = BaseContentItem> {
    *          アイテムが存在しない: `null`
    */
   check(slug: string, currentVersion: string): Promise<CheckResult<T> | null>;
+  /** 前後アイテムのナビゲーション (リスト順序ベース)。 */
+  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
+    prev: T | null;
+    next: T | null;
+  }>;
   /** キャッシュ操作 namespace。 */
   cache: CollectionCacheOps<T>;
 }
@@ -145,6 +158,11 @@ interface ContentConfig {
   /** 追加する rehype プラグイン。 */
   rehypePlugins?: RendererPluginList;
 }
+/** SWR（Stale-While-Revalidate）設定。 */
+interface SWRConfig {
+  /** SWR の有効期間 (ミリ秒)。未設定時は TTL なし（失効まで stale を返す）。 */
+  ttlMs?: number;
+}
 /** レートリミット・リトライ設定。 */
 interface RateLimiterConfig {
   /** 同時実行数の上限。デフォルト: 3 */
@@ -197,22 +215,27 @@ type InferCollectionItem<C> = C extends CollectionDef<infer T> ? T : BaseContent
  *       publishedStatuses: ["公開済み"],
  *     }
  *   },
- *   cache: memoryCache({ ttlMs: 5 * 60_000 }),
+ *   cache: [memoryCache()],
+ *   swr: { ttlMs: 5 * 60_000 },
  * });
  */
 interface CreateCMSOptions<C extends CollectionsConfig = CollectionsConfig> {
   /** コレクション定義のマップ。 */
   collections: C;
   /**
-   * キャッシュアダプタ (単体または配列)。未指定時はキャッシュなし。
+   * キャッシュアダプタ (配列)。未指定時はキャッシュなし。
    * - `memoryCache()` のように doc + image 両方を担当するもの
    * - `r2Cache()` (image のみ)、`kvCache()` (doc のみ) のように片側のみ担当するもの
-   * - 配列で組み合わせると、各 adapter の `handles` で振り分けられる
+   * - 複数 adapter を配列で組み合わせると、各 adapter の `handles` で振り分けられる
+   */
+  cache?: readonly CacheAdapter[];
+  /** SWR（Stale-While-Revalidate）設定。 */
+  swr?: SWRConfig;
+  /**
+   * Markdown→HTML レンダラー。
+   * 省略時は `@notion-headless-cms/renderer` の `renderMarkdown` を動的 import で使用する。
+   * カスタム実装も `RendererFn` 型を満たせば使用可能。
    */
-  cache?: CacheAdapter | readonly CacheAdapter[];
-  /** SWR の有効期間 (ミリ秒)。未設定時は TTL なし (失効まで stale を返す)。 */
-  ttlMs?: number;
-  /** カスタムレンダラー。未指定時は `@notion-headless-cms/renderer` の `renderMarkdown` を動的 import。 */
   renderer?: RendererFn;
   /** 画像プロキシのベース URL。デフォルト `/api/images`。 */
   imageProxyBase?: string;
@@ -266,8 +289,12 @@ interface HandlerOptions {
 /** `$handler()` が内部で依存する CMS 機能の最小セット。 */
 interface HandlerAdapter {
   imageCache: ImageCacheOps;
-  /** コレクション名で DataSource を取り出し parseWebhook にフォワードする。 */
-  parseWebhook(req: Request, webhookSecret: string | undefined): Promise<InvalidateScope | null>;
+  /**
+   * 指定コレクションの DataSource.parseWebhook を呼ぶ。
+   * 未知コレクション → `webhook/unknown_collection` CMSError
+   * parseWebhook 未実装 → `webhook/not_implemented` CMSError
+   */
+  parseWebhookFor(collection: string, req: Request, webhookSecret: string | undefined): Promise<InvalidateScope>;
   revalidate(scope: InvalidateScope): Promise<void>;
 }
 /**
@@ -275,24 +302,24 @@ interface HandlerAdapter {
  * Next.js / React Router / Hono / Cloudflare Workers いずれでも使える。
  *
  * ルート:
- * - GET  `{basePath}/images/:hash` — 画像プロキシ
- * - POST `{basePath}/revalidate`   — Webhook 受信 + $revalidate()
+ * - GET  `{basePath}/images/:hash`              — 画像プロキシ
+ * - POST `{basePath}/revalidate/:collection`    — Webhook 受信 + $revalidate()
  */
 declare function createHandler(adapter: HandlerAdapter, opts?: HandlerOptions): (req: Request) => Promise<Response>;
 //#endregion
 //#region src/cms.d.ts
 /** `CMSClient<C>` — コレクション別アクセス + グローバル操作の合成型。 */
 type CMSClient<C extends CollectionsConfig> = { [K in keyof C]: CollectionClient<InferCollectionItem<C[K]>> } & CMSGlobalOps;
-/** `CMSClient` のグローバル名前空間。`$` プレフィックス。 */
+/** `CMSClient` のグローバル名前空間。 */
 interface CMSGlobalOps {
   /** 登録されているコレクション名の一覧。 */
-  readonly $collections: readonly string[];
+  readonly collections: readonly string[];
   /** 全コレクションまたは特定スコープのキャッシュを無効化する。 */
-  $invalidate(scope?: InvalidateScope): Promise<void>;
+  invalidate(scope?: InvalidateScope): Promise<void>;
   /** Web Standard なルーティングハンドラ (画像プロキシ / webhook) を生成する。 */
-  $handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
+  handler(opts?: HandlerOptions): (req: Request) => Promise<Response>;
   /** ハッシュキーでキャッシュ画像を取得する。 */
-  $getCachedImage(hash: string): Promise<StorageBinary | null>;
+  getCachedImage(hash: string): Promise<StorageBinary | null>;
 }
 /**
  * 複数の `CollectionDef` を束ねた CMS クライアントを生成する。
@@ -310,7 +337,8 @@ interface CMSGlobalOps {
  *       publishedStatuses: ["公開済み"],
  *     }
  *   },
- *   cache: memoryCache({ ttlMs: 5 * 60_000 }),
+ *   cache: [memoryCache()],
+ *   swr: { ttlMs: 5 * 60_000 },
  * });
  */
 declare function createCMS<C extends CollectionsConfig>(opts: CreateCMSOptions<C>): CMSClient<C>;
@@ -385,31 +413,33 @@ declare class CollectionClientImpl<T extends BaseContentItem> implements Collect
   private readonly ctx;
   readonly cache: CollectionCacheOps<T>;
   constructor(ctx: CollectionContext<T>);
-  get(slug: string, opts?: GetOptions): Promise<ItemWithRender<T> | null>;
+  find(slug: string, opts?: FindOptions): Promise<ItemWithContent<T> | null>;
   list(opts?: ListOptions<T>): Promise<T[]>;
-  params(): Promise<{
-    slug: string;
-  }[]>;
+  params(): Promise<string[]>;
   check(slug: string, currentVersion: string): Promise<CheckResult<T> | null>;
+  adjacent(slug: string, opts?: AdjacencyOptions<T>): Promise<{
+    prev: T | null;
+    next: T | null;
+  }>;
   private invalidateImpl;
+  private invalidateItemImpl;
   private warmImpl;
-  private adjacentImpl;
   private persistMeta;
-  private invalidateContent;
+  private invalidateContentEntry;
   /**
    * 本文キャッシュをロードする。キャッシュが無いか、メタとの整合性が取れない場合は
    * 再生成して書き戻す。
    */
   private loadOrBuildContent;
-  /** メタ既知の状態で本文だけバックグラウンド再生成する。エラーは握りつぶす。 */
+  /** メタ既知の状態で本文だけバックグラウンド再生成する。エラーは onSwrError フックに通知する。 */
   private rebuildContentBg;
   private attachLazyContent;
   private fetchList;
   private checkAndUpdateItemBg;
   private checkAndUpdateListBg;
   private fetchListRaw;
-  private findRaw;
+  private fetchRaw;
 }
 //#endregion
-export { type AdjacencyOptions, type BaseContentItem, type BuiltInCMSErrorCode, type CMSClient, CMSError, type CMSErrorCode, type CMSErrorContext, type CMSGlobalOps, type CMSHooks, type CMSPlugin, type CMSSchemaProperties, type CacheAdapter, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, CollectionClientImpl, type CollectionContext, type CollectionDef, type CollectionsConfig, type ContentBlock, type ContentConfig, type ContentResult, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type GetOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InferCollectionItem, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithRender, type ListOptions, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, type PropertyDef, type PropertyMap, type RateLimiterConfig, type RenderOptions, type RendererFn, type RendererPluginList, type RetryConfig, type SortOption, type StorageBinary, type WarmOptions, type WebhookConfig, collectionKey, createCMS, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, memoryCache, mergeHooks, mergeLoggers, 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 CacheAdapter, type CachedItemContent, type CachedItemList, type CachedItemMeta, type CheckResult, type CollectionCacheOps, type CollectionClient, CollectionClientImpl, type CollectionContext, type CollectionDef, type CollectionsConfig, type ContentBlock, type ContentConfig, type ContentResult, type CreateCMSOptions, DEFAULT_RETRY_CONFIG, type DataSource, type DocumentCacheOps, type FindOptions, type HandlerAdapter, type HandlerOptions, type ImageCacheOps, type ImageRef, type InferCollectionItem, type InlineNode, type InvalidateKind, type InvalidateScope, type ItemWithContent, type ListOptions, type LogLevel, type Logger, type MaybePromise, type MemoryCacheOptions, 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, collectionKey, createCMS, createHandler, definePlugin, isCMSError, isCMSErrorInNamespace, isStale, matchCMSError, memoryCache, mergeHooks, mergeLoggers, noopDocOps, noopImgOps, sha256Hex, withRetry };
 //# sourceMappingURL=index.d.mts.map