or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

block-property-utilities.mdcontent-extraction.mddata-operations.mdid-url-management.mdindex.mdnavigation-structure.mdpage-analysis.mdtext-processing.md
tile.json

tessl/npm-notion-utils

Useful utilities for working with Notion data structures and operations in both Node.js and browser environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/notion-utils@7.4.x

To install, run

npx @tessl/cli install tessl/npm-notion-utils@7.4.0

index.mddocs/

Notion Utils

Notion Utils provides a comprehensive set of utility functions for working with Notion data structures and operations. It offers isomorphic functionality that works in both Node.js and browser environments, making it ideal for building Notion-based applications, content management systems, or data processing pipelines.

Package Information

  • Package Name: notion-utils
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install notion-utils

Core Imports

import {
  getPageTitle,
  parsePageId,
  getTextContent,
  estimatePageReadTime,
  formatDate
} from "notion-utils";

For CommonJS:

const {
  getPageTitle,
  parsePageId,
  getTextContent,
  estimatePageReadTime,
  formatDate
} = require("notion-utils");

Basic Usage

import { 
  getPageTitle, 
  parsePageId, 
  getPageTableOfContents,
  estimatePageReadTime 
} from "notion-utils";
import type { ExtendedRecordMap, PageBlock } from "notion-types";

// Parse a Notion page URL to extract the page ID
const pageId = parsePageId("https://notion.so/My-Page-abc123def456");
// Returns: "abc123def456"

// Get the title of a page from a record map
const title = getPageTitle(recordMap);
// Returns: "My Page Title"

// Generate a table of contents from page headers
const toc = getPageTableOfContents(pageBlock, recordMap);
// Returns: Array of TOC entries with id, type, text, indentLevel

// Estimate reading time for a page
const readTime = estimatePageReadTime(pageBlock, recordMap);
// Returns: { numWords: 1250, numImages: 3, totalReadTimeInMinutes: 5.2, ... }

Architecture

Notion Utils is organized around several key areas:

  • Page Analysis: Functions for extracting metadata, content analysis, and structural information from Notion pages
  • ID & URL Management: Utilities for parsing, converting, and mapping Notion IDs and URLs between different formats
  • Text Processing: Functions for extracting, formatting, and normalizing text content from Notion's rich text structures
  • Navigation & Structure: Tools for building navigation elements like breadcrumbs and table of contents
  • Data Operations: Utilities for working with Notion's record maps, properties, and internal data structures
  • Content Extraction: Functions for extracting specific content types like images, tweets, and embedded media

Capabilities

Page Analysis & Metadata

Core functionality for analyzing Notion pages and extracting metadata like titles, reading time estimates, and content statistics.

function getPageTitle(recordMap: ExtendedRecordMap): string | null;

function estimatePageReadTime(
  block: Block, 
  recordMap: ExtendedRecordMap, 
  options?: EstimatePageReadTimeOptions
): PageReadTimeEstimate;

function getPageBreadcrumbs(
  recordMap: ExtendedRecordMap, 
  activePageId: string
): Array<any> | null;

Page Analysis

ID & URL Management

Utilities for parsing, converting, and mapping Notion IDs and URLs between different formats (32-char IDs, UUIDs, URLs).

function parsePageId(id?: string | null, options?: { uuid?: boolean }): string | undefined;

function idToUuid(id?: string): string;

function uuidToId(uuid: string): string;

function getCanonicalPageId(
  pageId: string, 
  recordMap: ExtendedRecordMap, 
  options?: { uuid?: boolean }
): string | null;

ID & URL Management

Text Processing & Formatting

Functions for extracting, formatting, and normalizing text content from Notion's rich text structures and data formats.

function getTextContent(text?: Decoration[]): string;

function normalizeTitle(title?: string | null): string;

function formatDate(input: string | number, options?: { month?: 'long' | 'short' }): string;

function formatNotionDateTime(datetime: NotionDateTime): string;

Text Processing

Navigation & Structure

Tools for building navigation elements and extracting structural information from Notion pages.

function getPageTableOfContents(
  page: PageBlock, 
  recordMap: ExtendedRecordMap
): Array<TableOfContentsEntry>;

function getAllPagesInSpace(
  rootPageId: string,
  rootSpaceId: string | undefined,
  getPage: (pageId: string) => Promise<ExtendedRecordMap>,
  options?: TraversalOptions
): Promise<PageMap>;

Navigation & Structure

Block & Property Utilities

Functions for working with individual blocks, extracting properties, and manipulating Notion's block-based data structures.

function getBlockTitle(block: Block, recordMap: ExtendedRecordMap): string;

function getBlockIcon(block: Block, recordMap: ExtendedRecordMap): string | null;

function getPageProperty<T>(
  propertyName: string, 
  block: Block, 
  recordMap: ExtendedRecordMap
): T;

function getBlockParentPage(
  block: Block, 
  recordMap: ExtendedRecordMap, 
  options?: { inclusive?: boolean }
): PageBlock | null;

Block & Property Utilities

Content Extraction

Functions for extracting specific types of content from Notion pages including images, tweets, and other embedded media.

function getPageImageUrls(
  recordMap: ExtendedRecordMap,
  options: { mapImageUrl: (url: string, block: Block) => string | undefined }
): string[];

function getPageTweetIds(recordMap: ExtendedRecordMap): string[];

function getPageTweetUrls(recordMap: ExtendedRecordMap): string[];

function getPageContentBlockIds(recordMap: ExtendedRecordMap, blockId?: string): string[];

Content Extraction

Data Operations

Utilities for working with Notion's record maps, data structures, and performing operations on Notion's internal data formats.

function mergeRecordMaps(recordMapA: ExtendedRecordMap, recordMapB: ExtendedRecordMap): ExtendedRecordMap;

function normalizeUrl(url?: string): string;

function isUrl(input: string): boolean;

function mapImageUrl(url: string | undefined, block: Block): string | undefined;

function mapPageUrl(rootPageId?: string): (pageId: string) => string;

Data Operations

Core Types

// From notion-types package
interface ExtendedRecordMap {
  block: Record<string, Block>;
  collection?: Record<string, Collection>;
  collection_view?: Record<string, CollectionView>;
  notion_user?: Record<string, NotionUser>;
  collection_query?: Record<string, any>;
  signed_urls?: Record<string, string>;
  preview_images?: Record<string, string>;
}

interface Block {
  id: string;
  type: BlockType;
  properties?: Record<string, any>;
  format?: Record<string, any>;
  content?: string[];
  parent_id: string;
  parent_table: string;
  alive: boolean;
  created_time: number;
  last_edited_time: number;
}

interface PageBlock extends Block {
  type: "page";
  properties?: {
    title?: Decoration[];
  };
  format?: {
    page_icon?: string;
    page_cover?: string;
    page_cover_position?: number;
    page_full_width?: boolean;
    page_small_text?: boolean;
  };
}

type Decoration = [string] | [string, string[][]] | [string, string[][], string];

// Package-specific types
interface EstimatePageReadTimeOptions {
  wordsPerMinute?: number;
  imageReadTimeInSeconds?: number;
}

interface PageReadTimeEstimate {
  numWords: number;
  numImages: number;
  totalWordsReadTimeInMinutes: number;
  totalImageReadTimeInMinutes: number;
  totalReadTimeInMinutes: number;
}

interface TableOfContentsEntry {
  id: string;
  type: BlockType;
  text: string;
  indentLevel: number;
}

interface NotionDateTime {
  type: 'datetime';
  start_date: string;
  start_time?: string;
  time_zone?: string;
}