Relation Hydration Utility

Build a utility that fetches a Notion page and recursively hydrates any pages referenced through relation properties. The result should include the merged record map for the base page plus all fetched relation pages, using the dependency's built-in hydration features rather than custom HTTP calls.

Capabilities

Recursive relation hydration

• Given a page ID and default options, returns a record map containing the base page and all relation-linked pages discovered transitively, fetching each related page at most once and returning the list of fetched relation page IDs. @test
• When missing child blocks are requested, the returned record map includes the child blocks for every fetched relation page; when the option is false, relation pages remain without additional block content. @test

Depth limits

• With maxDepth set to 1, only first-level relation pages are fetched; deeper relation links are left unresolved in the resulting record map. @test

Opt-out toggle

• When relation hydration is disabled, the utility returns only the base page’s record map and an empty list of fetched relation page IDs. @test

Implementation

@generates

API

export interface HydrationOptions {
  maxDepth?: number; // defaults to 2
  includeMissingBlocks?: boolean; // fetch child blocks for fetched relation pages
  hydrateRelations?: boolean; // defaults to true
  signal?: AbortSignal;
}

export interface RecordMap {
  block: Record<string, any>;
  collection?: Record<string, any>;
  collection_view?: Record<string, any>;
  collection_query?: Record<string, any>;
  notion_user?: Record<string, any>;
  signed_urls?: Record<string, string>;
}

export interface HydratedPage {
  recordMap: RecordMap;
  fetchedRelationPageIds: string[];
}

export async function hydratePageWithRelations(
  pageId: string,
  options?: HydrationOptions
): Promise<HydratedPage>;

Dependencies { .dependencies }

notion-client { .dependency }

Used to retrieve pages, recursively hydrate relation-linked records, and optionally fetch missing child blocks through its relation-aware page fetching features.