0
# Text Processing & Formatting
1

2
Functions for extracting, formatting, and normalizing text content from Notion's rich text structures, date formats, and title normalization for URLs.
3

4
## Capabilities
5

6
### Extract Text Content
7

8
Extracts plain text from Notion's rich text decoration arrays.
9

10
```typescript { .api }
11
/**
12
 * Gets the raw, unformatted text content of a block's content value
13
 * @param text - Array of text decorations from block properties
14
 * @returns Plain text string without formatting
15
 */
16
function getTextContent(text?: Decoration[]): string;
17

18
type Decoration = [string] | [string, string[][]] | [string, string[][], string];
19
```
20

21
**Usage Example:**
22

23
```typescript
24
import { getTextContent } from "notion-utils";
25

26
// Extract text from rich text decorations
27
const decorations: Decoration[] = [
28
  ["Hello "],
29
  ["world", [["b"]]],  // Bold "world"
30
  ["!"]
31
];
32

33
const plainText = getTextContent(decorations);
34
// Returns: "Hello world!"
35
```
36

37
### Normalize Titles
38

39
Normalizes titles for use in URLs and slugs, supporting international characters.
40

41
```typescript { .api }
42
/**
43
 * Normalizes a title for use in URLs/slugs
44
 * @param title - Title string to normalize
45
 * @returns URL-safe normalized title
46
 */
47
function normalizeTitle(title?: string | null): string;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { normalizeTitle } from "notion-utils";
54

55
// Basic normalization
56
const slug1 = normalizeTitle("My Page Title");
57
// Returns: "my-page-title"
58

59
// Handle special characters
60
const slug2 = normalizeTitle("Hello, World! @#$%");
61
// Returns: "hello-world"
62

63
// Support international characters
64
const slug3 = normalizeTitle("こんにちは世界 Hello");
65
// Returns: "こんにちは世界-hello"
66

67
// Handle edge cases
68
const slug4 = normalizeTitle("   Multiple   Spaces   ");
69
// Returns: "multiple-spaces"
70
```
71

72
### Date Formatting
73

74
Functions for formatting dates and Notion datetime objects.
75

76
```typescript { .api }
77
/**
78
 * Formats a date string or timestamp into a readable format
79
 * @param input - Date string or timestamp
80
 * @param options - Formatting options
81
 * @returns Formatted date string (e.g., "Jan 15, 2023")
82
 */
83
function formatDate(input: string | number, options?: { month?: 'long' | 'short' }): string;
84

85
/**
86
 * Formats a Notion datetime object into a readable string
87
 * @param datetime - Notion datetime object
88
 * @returns Formatted datetime string
89
 */
90
function formatNotionDateTime(datetime: NotionDateTime): string;
91

92
interface NotionDateTime {
93
  type: 'datetime';
94
  start_date: string;
95
  start_time?: string;
96
  time_zone?: string;
97
}
98
```
99

100
**Usage Examples:**
101

102
```typescript
103
import { formatDate, formatNotionDateTime } from "notion-utils";
104

105
// Format regular dates
106
const date1 = formatDate("2023-01-15");
107
// Returns: "Jan 15, 2023"
108

109
const date2 = formatDate("2023-01-15", { month: 'long' });
110
// Returns: "January 15, 2023"
111

112
const date3 = formatDate(1673740800000); // timestamp
113
// Returns: "Jan 15, 2023"
114

115
// Format Notion datetime objects
116
const notionDate: NotionDateTime = {
117
  type: 'datetime',
118
  start_date: '2023-01-15',
119
  start_time: '10:30',
120
  time_zone: 'America/New_York'
121
};
122

123
const formatted = formatNotionDateTime(notionDate);
124
// Returns: "Jan 15, 2023" with UTC timezone handling
125
```
126

127
### Date Value Extraction
128

129
Extracts date values from Notion property arrays.
130

131
```typescript { .api }
132
/**
133
 * Attempts to find a valid date from a given property array
134
 * @param prop - Property array that may contain date values
135
 * @returns FormattedDate object or null if no date found
136
 */
137
function getDateValue(prop: any[]): FormattedDate | null;
138

139
interface FormattedDate {
140
  type: 'date' | 'datetime';
141
  start_date: string;
142
  end_date?: string;
143
  start_time?: string;
144
  end_time?: string;
145
  time_zone?: string;
146
}
147
```
148

149
**Usage Example:**
150

151
```typescript
152
import { getDateValue } from "notion-utils";
153

154
// Extract date from property array
155
const propertyArray = [
156
  ["‣"],
157
  [
158
    [
159
      "d",
160
      {
161
        type: "date",
162
        start_date: "2023-01-15",
163
        start_time: "10:30"
164
      }
165
    ]
166
  ]
167
];
168

169
const dateValue = getDateValue(propertyArray);
170
// Returns: { type: 'date', start_date: '2023-01-15', start_time: '10:30' }
171
```
172

173
## Types
174

175
```typescript { .api }
176
// Text decoration types
177
type Decoration = [string] | [string, string[][]] | [string, string[][], string];
178

179
// Date and time types
180
interface NotionDateTime {
181
  type: 'datetime';
182
  start_date: string;
183
  start_time?: string;
184
  time_zone?: string;
185
}
186

187
interface FormattedDate {
188
  type: 'date' | 'datetime';
189
  start_date: string;
190
  end_date?: string;
191
  start_time?: string;
192
  end_time?: string;
193
  time_zone?: string;
194
}
195
```