0
# Notion Utils
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: notion-utils
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install notion-utils`
10
11
## Core Imports
12
13
```typescript
14
import {
15
getPageTitle,
16
parsePageId,
17
getTextContent,
18
estimatePageReadTime,
19
formatDate
20
} from "notion-utils";
21
```
22
23
For CommonJS:
24
25
```javascript
26
const {
27
getPageTitle,
28
parsePageId,
29
getTextContent,
30
estimatePageReadTime,
31
formatDate
32
} = require("notion-utils");
33
```
34
35
## Basic Usage
36
37
```typescript
38
import {
39
getPageTitle,
40
parsePageId,
41
getPageTableOfContents,
42
estimatePageReadTime
43
} from "notion-utils";
44
import type { ExtendedRecordMap, PageBlock } from "notion-types";
45
46
// Parse a Notion page URL to extract the page ID
47
const pageId = parsePageId("https://notion.so/My-Page-abc123def456");
48
// Returns: "abc123def456"
49
50
// Get the title of a page from a record map
51
const title = getPageTitle(recordMap);
52
// Returns: "My Page Title"
53
54
// Generate a table of contents from page headers
55
const toc = getPageTableOfContents(pageBlock, recordMap);
56
// Returns: Array of TOC entries with id, type, text, indentLevel
57
58
// Estimate reading time for a page
59
const readTime = estimatePageReadTime(pageBlock, recordMap);
60
// Returns: { numWords: 1250, numImages: 3, totalReadTimeInMinutes: 5.2, ... }
61
```
62
63
## Architecture
64
65
Notion Utils is organized around several key areas:
66
67
- **Page Analysis**: Functions for extracting metadata, content analysis, and structural information from Notion pages
68
- **ID & URL Management**: Utilities for parsing, converting, and mapping Notion IDs and URLs between different formats
69
- **Text Processing**: Functions for extracting, formatting, and normalizing text content from Notion's rich text structures
70
- **Navigation & Structure**: Tools for building navigation elements like breadcrumbs and table of contents
71
- **Data Operations**: Utilities for working with Notion's record maps, properties, and internal data structures
72
- **Content Extraction**: Functions for extracting specific content types like images, tweets, and embedded media
73
74
## Capabilities
75
76
### Page Analysis & Metadata
77
78
Core functionality for analyzing Notion pages and extracting metadata like titles, reading time estimates, and content statistics.
79
80
```typescript { .api }
81
function getPageTitle(recordMap: ExtendedRecordMap): string | null;
82
83
function estimatePageReadTime(
84
block: Block,
85
recordMap: ExtendedRecordMap,
86
options?: EstimatePageReadTimeOptions
87
): PageReadTimeEstimate;
88
89
function getPageBreadcrumbs(
90
recordMap: ExtendedRecordMap,
91
activePageId: string
92
): Array<any> | null;
93
```
94
95
[Page Analysis](./page-analysis.md)
96
97
### ID & URL Management
98
99
Utilities for parsing, converting, and mapping Notion IDs and URLs between different formats (32-char IDs, UUIDs, URLs).
100
101
```typescript { .api }
102
function parsePageId(id?: string | null, options?: { uuid?: boolean }): string | undefined;
103
104
function idToUuid(id?: string): string;
105
106
function uuidToId(uuid: string): string;
107
108
function getCanonicalPageId(
109
pageId: string,
110
recordMap: ExtendedRecordMap,
111
options?: { uuid?: boolean }
112
): string | null;
113
```
114
115
[ID & URL Management](./id-url-management.md)
116
117
### Text Processing & Formatting
118
119
Functions for extracting, formatting, and normalizing text content from Notion's rich text structures and data formats.
120
121
```typescript { .api }
122
function getTextContent(text?: Decoration[]): string;
123
124
function normalizeTitle(title?: string | null): string;
125
126
function formatDate(input: string | number, options?: { month?: 'long' | 'short' }): string;
127
128
function formatNotionDateTime(datetime: NotionDateTime): string;
129
```
130
131
[Text Processing](./text-processing.md)
132
133
### Navigation & Structure
134
135
Tools for building navigation elements and extracting structural information from Notion pages.
136
137
```typescript { .api }
138
function getPageTableOfContents(
139
page: PageBlock,
140
recordMap: ExtendedRecordMap
141
): Array<TableOfContentsEntry>;
142
143
function getAllPagesInSpace(
144
rootPageId: string,
145
rootSpaceId: string | undefined,
146
getPage: (pageId: string) => Promise<ExtendedRecordMap>,
147
options?: TraversalOptions
148
): Promise<PageMap>;
149
```
150
151
[Navigation & Structure](./navigation-structure.md)
152
153
### Block & Property Utilities
154
155
Functions for working with individual blocks, extracting properties, and manipulating Notion's block-based data structures.
156
157
```typescript { .api }
158
function getBlockTitle(block: Block, recordMap: ExtendedRecordMap): string;
159
160
function getBlockIcon(block: Block, recordMap: ExtendedRecordMap): string | null;
161
162
function getPageProperty<T>(
163
propertyName: string,
164
block: Block,
165
recordMap: ExtendedRecordMap
166
): T;
167
168
function getBlockParentPage(
169
block: Block,
170
recordMap: ExtendedRecordMap,
171
options?: { inclusive?: boolean }
172
): PageBlock | null;
173
```
174
175
[Block & Property Utilities](./block-property-utilities.md)
176
177
### Content Extraction
178
179
Functions for extracting specific types of content from Notion pages including images, tweets, and other embedded media.
180
181
```typescript { .api }
182
function getPageImageUrls(
183
recordMap: ExtendedRecordMap,
184
options: { mapImageUrl: (url: string, block: Block) => string | undefined }
185
): string[];
186
187
function getPageTweetIds(recordMap: ExtendedRecordMap): string[];
188
189
function getPageTweetUrls(recordMap: ExtendedRecordMap): string[];
190
191
function getPageContentBlockIds(recordMap: ExtendedRecordMap, blockId?: string): string[];
192
```
193
194
[Content Extraction](./content-extraction.md)
195
196
### Data Operations
197
198
Utilities for working with Notion's record maps, data structures, and performing operations on Notion's internal data formats.
199
200
```typescript { .api }
201
function mergeRecordMaps(recordMapA: ExtendedRecordMap, recordMapB: ExtendedRecordMap): ExtendedRecordMap;
202
203
function normalizeUrl(url?: string): string;
204
205
function isUrl(input: string): boolean;
206
207
function mapImageUrl(url: string | undefined, block: Block): string | undefined;
208
209
function mapPageUrl(rootPageId?: string): (pageId: string) => string;
210
```
211
212
[Data Operations](./data-operations.md)
213
214
## Core Types
215
216
```typescript { .api }
217
// From notion-types package
218
interface ExtendedRecordMap {
219
block: Record<string, Block>;
220
collection?: Record<string, Collection>;
221
collection_view?: Record<string, CollectionView>;
222
notion_user?: Record<string, NotionUser>;
223
collection_query?: Record<string, any>;
224
signed_urls?: Record<string, string>;
225
preview_images?: Record<string, string>;
226
}
227
228
interface Block {
229
id: string;
230
type: BlockType;
231
properties?: Record<string, any>;
232
format?: Record<string, any>;
233
content?: string[];
234
parent_id: string;
235
parent_table: string;
236
alive: boolean;
237
created_time: number;
238
last_edited_time: number;
239
}
240
241
interface PageBlock extends Block {
242
type: "page";
243
properties?: {
244
title?: Decoration[];
245
};
246
format?: {
247
page_icon?: string;
248
page_cover?: string;
249
page_cover_position?: number;
250
page_full_width?: boolean;
251
page_small_text?: boolean;
252
};
253
}
254
255
type Decoration = [string] | [string, string[][]] | [string, string[][], string];
256
257
// Package-specific types
258
interface EstimatePageReadTimeOptions {
259
wordsPerMinute?: number;
260
imageReadTimeInSeconds?: number;
261
}
262
263
interface PageReadTimeEstimate {
264
numWords: number;
265
numImages: number;
266
totalWordsReadTimeInMinutes: number;
267
totalImageReadTimeInMinutes: number;
268
totalReadTimeInMinutes: number;
269
}
270
271
interface TableOfContentsEntry {
272
id: string;
273
type: BlockType;
274
text: string;
275
indentLevel: number;
276
}
277
278
interface NotionDateTime {
279
type: 'datetime';
280
start_date: string;
281
start_time?: string;
282
time_zone?: string;
283
}
284
```