tessl/npm-notion-utils

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Text Processing & Formatting

Name: tessl/npm-notion-utils
Author: tessl

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

Capabilities

Extract Text Content

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

/**
 * Gets the raw, unformatted text content of a block's content value
 * @param text - Array of text decorations from block properties
 * @returns Plain text string without formatting
 */
function getTextContent(text?: Decoration[]): string;

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

Usage Example:

import { getTextContent } from "notion-utils";

// Extract text from rich text decorations
const decorations: Decoration[] = [
  ["Hello "],
  ["world", [["b"]]],  // Bold "world"
  ["!"]
];

const plainText = getTextContent(decorations);
// Returns: "Hello world!"

Normalize Titles

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

/**
 * Normalizes a title for use in URLs/slugs
 * @param title - Title string to normalize
 * @returns URL-safe normalized title
 */
function normalizeTitle(title?: string | null): string;

Usage Examples:

import { normalizeTitle } from "notion-utils";

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

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

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

// Handle edge cases
const slug4 = normalizeTitle("   Multiple   Spaces   ");
// Returns: "multiple-spaces"

Date Formatting

Functions for formatting dates and Notion datetime objects.

/**
 * Formats a date string or timestamp into a readable format
 * @param input - Date string or timestamp
 * @param options - Formatting options
 * @returns Formatted date string (e.g., "Jan 15, 2023")
 */
function formatDate(input: string | number, options?: { month?: 'long' | 'short' }): string;

/**
 * Formats a Notion datetime object into a readable string
 * @param datetime - Notion datetime object
 * @returns Formatted datetime string
 */
function formatNotionDateTime(datetime: NotionDateTime): string;

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

Usage Examples:

import { formatDate, formatNotionDateTime } from "notion-utils";

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

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

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

// Format Notion datetime objects
const notionDate: NotionDateTime = {
  type: 'datetime',
  start_date: '2023-01-15',
  start_time: '10:30',
  time_zone: 'America/New_York'
};

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

Date Value Extraction

Extracts date values from Notion property arrays.

/**
 * Attempts to find a valid date from a given property array
 * @param prop - Property array that may contain date values
 * @returns FormattedDate object or null if no date found
 */
function getDateValue(prop: any[]): FormattedDate | null;

interface FormattedDate {
  type: 'date' | 'datetime';
  start_date: string;
  end_date?: string;
  start_time?: string;
  end_time?: string;
  time_zone?: string;
}

Usage Example:

import { getDateValue } from "notion-utils";

// Extract date from property array
const propertyArray = [
  ["‣"],
  [
    [
      "d",
      {
        type: "date",
        start_date: "2023-01-15",
        start_time: "10:30"
      }
    ]
  ]
];

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

Types

// Text decoration types
type Decoration = [string] | [string, string[][]] | [string, string[][], string];

// Date and time types
interface NotionDateTime {
  type: 'datetime';
  start_date: string;
  start_time?: string;
  time_zone?: string;
}

interface FormattedDate {
  type: 'date' | 'datetime';
  start_date: string;
  end_date?: string;
  start_time?: string;
  end_time?: string;
  time_zone?: string;
}

Install with Tessl CLI