npm.io
0.2.11 • Published 3d ago

@notion-headless-cms/notion-orm

Licence
MIT
Version
0.2.11
Deps
3
Size
136 kB
Vulns
0
Weekly
898
SummaryDependencyVersions

@notion-headless-cms/notion-orm

内部利用向けパッケージ — npm に公開されるが、ユーザーは直接 import しない。 @notion-headless-cms/notion-source の dependencies として同梱されるため、利用側で明示インストールする必要もない。

Notion API を叩いて @notion-headless-cms/core の DataSource<T> を返す ORM 層。createNotionCollection() でページ取得・Markdown 変換を行う。

位置付け

ユーザーコード
    └─ createClient({ sources: { notion: notionSource(...) } })   ← core
         └─ notionSource({ schema, token })   ← notion-source
              └─ createNotionCollection({ token, dataSourceId, properties })   ← notion-orm
                   └─ @notionhq/client / zod / 内部 fetcher / transformer

ユーザー空間からは notionSource() (notion-source パッケージ) しか見えず、@notion-headless-cms/notion-orm を直接 import する必要はない。

公開 API (notion-source からのみ呼ばれる)

  • createNotionCollection(opts) — DataSource<T> を返す
  • defineSchema(zodSchema, mapping) — 宣言的スキーマを構築
  • defineMapping(mapping) — プロパティ名マッピング

ユーザーが直接呼ぶ公開 API

  • fetchBlockTree(client, pageId): Promise<NotionBlockTreeNode[]> — ページ配下の全ブロックを has_children を再帰展開した木として返す。@notion-headless-cms/react-renderer の <NotionRenderer blocks={...} /> の入力に使う
  • NotionBlockTreeNode — BlockObjectResponse & { children?: NotionBlockTreeNode[] }
import { Client } from "@notionhq/client";
import { fetchBlockTree } from "@notion-headless-cms/notion-orm";

const client = new Client({ auth: process.env.NOTION_TOKEN });
const blocks = await fetchBlockTree(client, pageId);

なぜ「直接 import しない」設計か

  • ユーザーが直接 ORM レイヤーを触る必要はない (CLI が隠蔽する)
  • 生成物経由に揃えることで Notion API の差分を吸収しやすい
  • 将来 googledocs-orm 等を追加する際に抽象を変更しやすい

npm には公開されるので、別リポジトリから pnpm add @notion-headless-cms/notion-orm でインストールできる (インストール後、import は CLI 生成物経由で行う)。

関連

Keywords

notionnotion-apiheadless-cmscmsdatasourceormtypescript