Type Guards

Runtime type checking for Notion API responses

The Notion SDK provides type guard functions to help you narrow TypeScript types at runtime and distinguish between full and partial response objects.

Block Type Guards

isFullBlock

Checks if a response is a full BlockObjectResponse (not a partial block).

function isFullBlock(
  response: ObjectResponse
): response is BlockObjectResponse

Example:

import { isFullBlock } from "@notionhq/client"

const response = await notion.blocks.retrieve({ block_id: blockId })

if (isFullBlock(response)) {
  // TypeScript knows response is BlockObjectResponse
  console.log(response.type) // "paragraph", "heading_1", etc.
  console.log(response.created_time)
}

Page Type Guards

isFullPage

Checks if a response is a full PageObjectResponse (not a partial page).

function isFullPage(
  response: ObjectResponse
): response is PageObjectResponse

Example:

import { isFullPage } from "@notionhq/client"

const response = await notion.pages.retrieve({ page_id: pageId })

if (isFullPage(response)) {
  console.log(response.url)
  console.log(response.properties)
}

isFullPageOrDataSource

Checks if a response is a full PageObjectResponse or DataSourceObjectResponse. Useful when working with search or queryDataSource results.

function isFullPageOrDataSource(
  response: ObjectResponse
): response is DataSourceObjectResponse | PageObjectResponse

Example:

import { isFullPageOrDataSource } from "@notionhq/client"

const results = await notion.search({
  query: "my page",
})

results.results.forEach(result => {
  if (isFullPageOrDataSource(result)) {
    console.log(result.id)
  }
})

Database Type Guards

isFullDatabase

Checks if a response is a full DatabaseObjectResponse (not a partial database).

function isFullDatabase(
  response: ObjectResponse
): response is DatabaseObjectResponse

Example:

import { isFullDatabase } from "@notionhq/client"

const response = await notion.databases.retrieve({ database_id: databaseId })

if (isFullDatabase(response)) {
  console.log(response.title)
  console.log(response.properties)
}

Data Source Type Guards

isFullDataSource

Checks if a response is a full DataSourceObjectResponse.

function isFullDataSource(
  response: ObjectResponse
): response is DataSourceObjectResponse

Example:

import { isFullDataSource } from "@notionhq/client"

if (isFullDataSource(response)) {
  console.log(response.object) // "data_source"
}

User Type Guards

isFullUser

Checks if a response is a full UserObjectResponse (not a partial user).

function isFullUser(
  response: UserObjectResponse | PartialUserObjectResponse
): response is UserObjectResponse

Example:

import { isFullUser } from "@notionhq/client"

const user = await notion.users.retrieve({ user_id: userId })

if (isFullUser(user)) {
  console.log(user.type) // "person" or "bot"
  console.log(user.name)
}

Comment Type Guards

isFullComment

Checks if a response is a full CommentObjectResponse (not a partial comment).

function isFullComment(
  response: CommentObjectResponse | PartialCommentObjectResponse
): response is CommentObjectResponse

Example:

import { isFullComment } from "@notionhq/client"

const comments = await notion.comments.list({ block_id: blockId })

comments.results.forEach(comment => {
  if (isFullComment(comment)) {
    console.log(comment.created_by)
    console.log(comment.rich_text)
  }
})

Rich Text Type Guards

isTextRichTextItemResponse

Checks if a rich text item is a text type.

function isTextRichTextItemResponse(
  richText: RichTextItemResponse
): richText is RichTextItemResponseCommon & TextRichTextItemResponse

Example:

import { isTextRichTextItemResponse } from "@notionhq/client"

richTextArray.forEach(item => {
  if (isTextRichTextItemResponse(item)) {
    console.log(item.text.content)
    console.log(item.text.link)
  }
})

isEquationRichTextItemResponse

Checks if a rich text item is an equation type.

function isEquationRichTextItemResponse(
  richText: RichTextItemResponse
): richText is RichTextItemResponseCommon & EquationRichTextItemResponse

Example:

import { isEquationRichTextItemResponse } from "@notionhq/client"

richTextArray.forEach(item => {
  if (isEquationRichTextItemResponse(item)) {
    console.log(item.equation.expression)
  }
})

isMentionRichTextItemResponse

Checks if a rich text item is a mention type.

function isMentionRichTextItemResponse(
  richText: RichTextItemResponse
): richText is RichTextItemResponseCommon & MentionRichTextItemResponse

Example:

import { isMentionRichTextItemResponse } from "@notionhq/client"

richTextArray.forEach(item => {
  if (isMentionRichTextItemResponse(item)) {
    console.log(item.mention.type) // "user", "page", "database", etc.
  }
})

Why Use Type Guards?

The Notion API returns different response shapes depending on the context:

• Full objects contain all properties and are returned by direct retrieve operations
• Partial objects contain only id and object properties and are returned in some contexts where full data isn’t available

Type guards help you:

1. Write type-safe code that TypeScript can verify
2. Handle partial responses gracefully
3. Access properties that only exist on full objects
4. Distinguish between different rich text types