Notion Plus

Notion Plus is an Object-Relational Mapping (ORM) library for TypeScript that provides a simple and intuitive way to interact with Notion databases. With Notion Plus, you can define database schemas using TypeScript interfaces, and perform CRUD operations on those databases using a fluent API.

Features

• Retrieve a database from Notion using the database ID
• Query a page and retrieve its properties and metadata
• Create a new page in the database with specified properties
• Update an existing page in the database with new properties
• Archive an existing page in the database

Installation

# Using npm
npm install notion-plus

# Using yarn
yarn add notion-plus

Usage

import { NotionPlus, Schema } from 'notion-plus'

const notionPlus = NotionPlus.getInstance(process.env.NOTION_TOKEN)
const databaseId = process.env.DB_ID

interface User {
  'First Name': string
  'Last Name': string
  Email: string
  'Company Name': string
}

const userSchema = new Schema<User>({
  'First Name': 'title',
  'Last Name': 'rich_text',
  Email: 'email',
  'Company Name': 'rich_text',
})

const userModel = notionPlus.getModel<User>(databaseId, userSchema)

// new Model<User>(notion, databaseId, userSchema)

const main = async () => {
  const users = await userModel.find({
    pageSize: 1,
    sorts: [
      {
        property: 'First Name',
        direction: 'ascending',
      },
    ],
    filter: {
      property: 'First Name',
      title: {
        contains: 'John',
      },
    },
    // metadata: true,
  })
  console.log(users)
}
main()

The EnumPropertyTypes enum (Supported Types)

The following property types are supported:

Type	Description
title	A title for a page or database item.
rich_text	Formatted text with inline styling.
checkbox	A boolean checkbox.
select	A single-select dropdown.
multi_select	A multi-select dropdown.
number	A number value.
date	A date or date-time value.
string	A plain text string.
boolean	A boolean value.
files	A file url.
email	An email address.
url	A URL.
phone_number	A phone number.
created_by	The user who created the page or database item.
created_time	The time the page or database item was created.
status	The status of a page or database item.
unique_id	A unique id for database.

---

The NotionPlus Class

The NotionPlus class is the main class in the notion-plus library. It provides a wrapper around the Notion API and exposes various methods to interact with Notion databases and pages.

Creating a new NotionPlus instance

import { NotionPlus } from 'notion-plus';

const notionPlus = NotionPlus.getInstance(process.env.NOTION_TOKEN);

Constructor

Creates a new instance of the NotionPlus class.

Name	Type	Description
notionToken	string	The API key for your Notion integration.

Since the NotionPlus class is a singleton, you should use the getInstance() method to create a new instance.

Methods

getModel<T>(databaseId: string, schema: Schema<T>): Model<T>

Returns a Model<T> instance for the specified database ID and schema. If a Model<T> instance for the specified database ID and schema has already been created, it returns the existing instance.

Name	Type	Description
databaseId	string	The ID of the Notion database.
schema	Schema	The schema of the Notion database.

getNotionClient(): Client

Returns the Client instance used by the NotionPlus class.

getDatabases(databaseId: string, filter?: QueryDatabaseParameters['filter'], pageSize?: number, sorts: QueryDatabaseParameters['sorts'] = []): Promise<QueryDatabaseResponse>

Queries a Notion database for its properties and returns the results.

Name	Type	Description
databaseId	string	The ID of the Notion database to query.
filter	QueryDatabaseParameters['filter'] (optional)	The filter to apply to the query.
pageSize	number (optional)	The number of items to return per page.
sorts	QueryDatabaseParameters['sorts'] (optional, default: [])	The sorting criteria for the query.

getPageProps(pageId: string, propertyId: string): Promise<GetPagePropertyResponse>

Retrieves the specified property value for a Notion page.

Name	Type	Description
pageId	string	The ID of the Notion page.
propertyId	string	The ID of the property to retrieve.

updateNotionPage(pageId: string, properties: UpdatePageParameters['properties']): Promise<UpdatePageResponse>

Updates the properties of a Notion page.

Name	Type	Description
pageId	string	The ID of the Notion page.
properties	UpdatePageParameters['properties']	An object containing the updated page properties.

createNotionPage(databaseId: string, properties: CreatePageParameters['properties']): Promise<CreatePageResponse>

Creates a new Notion page in the specified database.

Name	Type	Description
databaseId	string	The ID of the Notion database.
properties	CreatePageParameters['properties'] (must include all required properties)	An object containing the page properties.

archiveNotionPage(pageId: string): Promise<ArchivePageResponse>

Archives a Notion page.

Name	Type	Description
pageId	string	The ID of the page.

---

The Schema Class

Name	Description
notionSchema: NotionSchema<T & NotionRecord>	The notion schema for the Notion database.
constructor(notionSchema: NotionSchema<T>)	Creates a new Schema instance with the specified notionSchema.

The Schema class is a simple class with a single property notionSchema of type NotionSchema<T & NotionRecord>, and a constructor that initializes this property. The NotionSchema type is a mapped type that maps the keys of T to EnumPropertyTypes.

The Schema class is used in the NotionPlus class to define the schema for a Notion database

Creating a new Schema instance

import { Schema } from 'notion-plus';

interface User {
  'First Name': string;
  'Last Name': string;
  Email: string;
}

const userSchema = new Schema<User>({
  'First Name': 'title',
  'Last Name': 'rich_text',
  Email: 'email',
});

---

The Model<T> Class

A class representing a Notion database model with typed properties.

Constructor

Parameter	Type	Description
notionPlus	NotionPlus	An instance of NotionPlus class used to communicate with Notion API.
databaseId	string	The ID of the Notion database.
schema	Schema<T>	An instance of Schema class representing the typed schema of the Notion database.

Methods

Method	Parameters	Return value	Description
find	{ filter?, pageSize?, sorts?, metadata? }	Promise<FilterResponse<T>>	Finds and returns a filtered list of database items.
create	item: Partial<T>, metaData = false	Promise<T & NotionRecord>	Creates a new item in the database.
update	id: string, data: Partial<T>, metaData = false	Promise<T & NotionRecord>	Updates an existing item in the database.
archive	id: string, metaData = false	Promise<T & NotionRecord>	Archives an existing item in the database.

archive(id: string, metaData?: boolean): Promise<T | Record<string, unknown>>

Developer: