tessl/npm-notion-types

TypeScript types for core Notion data structures.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Notion Types

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

Notion Types provides comprehensive TypeScript type definitions for all of Notion's core data structures. This library serves as the foundational type system for the react-notion-x ecosystem and enables type-safe development when working with Notion's API and data formats.

Package Information

Package Name: notion-types
Package Type: npm
Language: TypeScript
Installation: npm install notion-types

Core Imports

import {
  Block,
  Collection,
  CollectionView,
  RecordMap,
  ExtendedRecordMap,
  User,
  Formula,
  PropertyType,
  Color,
  Decoration
} from "notion-types";

For CommonJS:

const {
  Block,
  Collection,
  CollectionView,
  RecordMap,
  ExtendedRecordMap,
  User
} = require("notion-types");

Basic Usage

import { Block, PageBlock, TextBlock, PropertyType } from "notion-types";

// Work with block types
function processBlock(block: Block) {
  if (block.type === 'page') {
    const pageBlock = block as PageBlock;
    console.log('Page title:', pageBlock.properties?.title);
  } else if (block.type === 'text') {
    const textBlock = block as TextBlock;
    console.log('Text content:', textBlock.properties?.title);
  }
}

// Define collection property schema
const propertySchema = {
  name: PropertyType.title,
  age: PropertyType.number,
  email: PropertyType.email,
  active: PropertyType.checkbox
};

Architecture

Notion Types is organized around several core concepts:

Block System: 40+ block types representing all Notion content (pages, text, media, databases, etc.)
Collection System: Database/collection types with property schemas and views
Formula System: Complete formula language with 60+ functions and operators
Decoration System: Rich text formatting with 14 formatting types
Map System: Aggregate data structures for API responses
Core Types: Base types, colors, roles, and utility definitions

Capabilities

Block Types and Interfaces

Complete type definitions for all Notion block types including pages, text, media, and interactive content. Covers 40+ block types with full type safety.

type BlockType = 'page' | 'text' | 'header' | 'image' | 'video' | 'code' | 'table' | 'collection_view' | string;

interface BaseBlock {
  id: ID;
  type: BlockType;
  properties?: any;
  format?: any;
  content?: string[];
  parent_id: ID;
  version: number;
  created_time: number;
  last_edited_time: number;
  alive: boolean;
}

type Block = PageBlock | TextBlock | HeaderBlock | ImageBlock | VideoBlock | CodeBlock | TableBlock | CollectionViewBlock;

Block Types

Collection and Database Types

Type definitions for Notion databases (collections) including schemas, properties, and data validation. Supports all property types and collection configurations.

interface Collection {
  id: ID;
  version: number;
  name: Decoration[];
  schema: CollectionPropertySchemaMap;
  icon: string;
  parent_id: ID;
  alive: boolean;
}

interface CollectionPropertySchema {
  name: string;
  type: PropertyType;
  options?: SelectOption[];
  number_format?: NumberFormat;
  formula?: Formula;
}

type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multi_select' | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email' | 'phone_number' | 'formula' | 'relation';

Collections

Collection Views and Display

Type definitions for all Notion database view types including table, gallery, list, board, and calendar views with their configuration options.

type CollectionViewType = 'table' | 'gallery' | 'list' | 'board' | 'calendar' | 'reducer';

interface BaseCollectionView {
  id: ID;
  type: CollectionViewType;
  name: string;
  format: any;
  version: number;
  alive: boolean;
  parent_id: ID;
}

type CollectionView = TableCollectionView | GalleryCollectionView | ListCollectionView | BoardCollectionView | CalendarCollectionView;

Collection Views

Formula System

Complete type definitions for Notion's formula language including all operators, functions, and value types. Supports logic, math, text, and date operations.

type FormulaType = 'constant' | 'property' | 'operator' | 'function' | 'symbol';

interface BaseFormula {
  type: FormulaType;
  result_type: FormulaResultType;
}

type FormulaFunctionType = 'add' | 'subtract' | 'multiply' | 'divide' | 'concat' | 'if' | 'and' | 'or' | 'not' | 'date' | 'now' | 'format';

type Formula = FunctionFormula | OperatorFormula | ConstantFormula | PropertyFormula | SymbolFormula;

Formulas

API and Data Structures

Type definitions for Notion API requests, responses, search operations, and aggregate data structures including RecordMaps and ExtendedRecordMaps.

interface RecordMap {
  block: BlockMap;
  collection?: CollectionMap;
  collection_view?: CollectionViewMap;
  notion_user?: UserMap;
}

interface SearchParams {
  ancestorId: string;
  query: string;
  filters?: {
    isDeletedOnly: boolean;
    excludeTemplates: boolean;
    isNavigableOnly: boolean;
    requireEditPermissions: boolean;
  };
  limit?: number;
}

interface SearchResults {
  recordMap: RecordMap;
  results: SearchResult[];
  total: number;
}

API Types

Text Decoration and Formatting

Rich text decoration system with support for bold, italic, links, colors, mentions, and other formatting options. Includes complete type definitions for all decoration formats.

type Color = 'gray' | 'brown' | 'orange' | 'yellow' | 'teal' | 'blue' | 'purple' | 'pink' | 'red' | 'gray_background' | 'brown_background';

type SubDecoration = ['b'] | ['i'] | ['s'] | ['c'] | ['_'] | ['a', string] | ['h', Color] | ['u', string] | ['p', string];

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

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

Text Formatting

User and Permission Types

Type definitions for Notion users, roles, and permission systems. Includes user profile information and access control types.

interface User {
  id: ID;
  version: number;
  email: string;
  given_name: string;
  family_name: string;
  profile_photo: string;
  onboarding_completed: boolean;
  mobile_onboarding_completed: boolean;
}

type Role = 'editor' | 'reader' | 'none' | 'read_and_write';

Users and Permissions

Types

// Core identifier types
type ID = string;
type PropertyID = string;

// Generic map wrapper with permissions
interface NotionMap<T> {
  [key: string]: {
    role: Role;
    value: T;
  };
}

// Common map types
type BlockMap = NotionMap<Block>;
type UserMap = NotionMap<User>;
type CollectionMap = NotionMap<Collection>;
type CollectionViewMap = NotionMap<CollectionView>;

// Extended record map with convenience data
interface ExtendedRecordMap extends RecordMap {
  collection: CollectionMap;
  collection_view: CollectionViewMap;
  notion_user: UserMap;
  collection_query: {
    [collectionId: string]: {
      [collectionViewId: string]: CollectionQueryResult;
    };
  };
  signed_urls: {
    [blockId: string]: string;
  };
  preview_images?: PreviewImageMap;
}

// Core type aliases
type PropertyType = 'title' | 'text' | 'number' | 'select' | 'multi_select' | 'date' | 'person' | 'file' | 'checkbox' | 'url' | 'email' | 'phone_number' | 'formula' | 'relation' | 'rollup' | 'created_time' | 'created_by' | 'last_edited_time' | 'last_edited_by';

type Role = 'editor' | 'reader' | 'none' | 'read_and_write';

Install with Tessl CLI