{"id":13738699,"url":"https://github.com/andrewvo89/notiondb","last_synced_at":"2025-08-19T23:05:42.664Z","repository":{"id":65464359,"uuid":"388609400","full_name":"andrewvo89/notiondb","owner":"andrewvo89","description":"NotionDB is a object modelling tool designed to interface with Notion Databases.","archived":false,"fork":false,"pushed_at":"2022-02-16T09:57:09.000Z","size":197,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T01:23:15.752Z","etag":null,"topics":["database","nodejs","notion","notion-api","odm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrewvo89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-07-22T22:05:19.000Z","updated_at":"2024-02-02T01:40:11.000Z","dependencies_parsed_at":"2023-01-24T17:45:16.158Z","dependency_job_id":null,"html_url":"https://github.com/andrewvo89/notiondb","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/andrewvo89/notiondb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fnotiondb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fnotiondb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fnotiondb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fnotiondb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrewvo89","download_url":"https://codeload.github.com/andrewvo89/notiondb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrewvo89%2Fnotiondb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271236280,"owners_count":24723978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","nodejs","notion","notion-api","odm"],"created_at":"2024-08-03T03:02:33.657Z","updated_at":"2025-08-19T23:05:42.635Z","avatar_url":"https://github.com/andrewvo89.png","language":"TypeScript","funding_links":["https://www.buymeacoffee.com/andrewvo"],"categories":["TypeScript"],"sub_categories":[],"readme":"# NotionDB\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n[![Status](https://img.shields.io/badge/status-active-success.svg)](https://github.com/andrewvo89/notiondb)\r\n[![GitHub Issues](https://img.shields.io/github/issues/andrewvo89/notiondb)](https://github.com/andrewvo89/notiondb/issues)\r\n[![GitHub Stars](https://img.shields.io/github/stars/andrewvo89/notiondb)](https://github.com/andrewvo89/notiondb/stargazers)\r\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/andrewvo89/notiondb/blob/main/LICENSE)\r\n\r\n\u003c/div\u003e\r\n\r\n## 📝 Table of Contents\r\n\r\n- [🧐 About](#-about)\r\n- [⭐️ Features](#-features)\r\n- [🏁 Getting Started](#-getting-started)\r\n- [🎈 Usage](#-usage)\r\n- [⛏️ Built Using](#️-built-using)\r\n- [✍️ Authors](#️-authors)\r\n- [🎉 Acknowledgments](#-acknowledgements)\r\n\r\n## 🧐 About\r\n\r\nNotionDB is an object modelling tool designed to interface with [Notion](https://www.notion.so/). It is a tool to allow developers to easily spin up a cloud based database using [Notion Databases](https://www.notion.so/Intro-to-databases-fd8cd2d212f74c50954c11086d85997e). Notion Databases consist of a series of Notion Pages (database rows) with various Properties (database columns).\r\n\r\nNotionDB leverages off the official [Notion API](https://developers.notion.com/) and provides developers with easy to use classes and helper functions to easily retrieve, write, update and delete data.\r\n\r\n**Why use Notion as a Database?**\r\n\r\n- On top of the standard primitive types, Notion provides advanced types such as Dates with Time (start and end), People, URLs, Emails, Phone Numbers, Formulas, Relations, Rollups and more.\r\n- Notion provides great facilities for Filtering (compound and/or filtering and nested filtering) and multi level Sorting. This makes querying and sorting through data seamless for developers.\r\n- To visualize the data, the Notion user interface can display the database data in various views such as Table, Board, Timeline, Calendar, List and Gallery views.\r\n- Being able to access and write data to a Notion Database from a server side environment opens up endless opportunities to interface Notion with other databases, services and APIs.\r\n\r\nFor any enquiries, email hello@andrewvo.co.\r\n\r\nIf you would like to donate to the project, you can buy me a coffee.\r\n\r\n\u003ca href=\"https://www.buymeacoffee.com/andrewvo\" target=\"_blank\"\u003e\u003cimg src=\"https://firebasestorage.googleapis.com/v0/b/tempnote-io.appspot.com/o/assets%2Fbmc-button.png?alt=media\u0026token=284ab195-54bd-4d4f-b1ab-27e968c579fa\" alt=\"Buy Me A Coffee\" width=200px\u003e\u003c/a\u003e\r\n\r\n## ⭐️ Features\r\n\r\n### Databases\r\n\r\n- Get all Databases associated with an integration key.\r\n- Get a single Database by Database ID or Database Notion URL.\r\n- Create a Database using a Schema of Properties (column definitions).\r\n\r\n### Pages\r\n\r\n- Get all Pages from a Database.\r\n- Get a single Page by Page ID or Page Notion URL.\r\n- Filter down and Sort Pages from a Database using Notion's powerful Filter and Sort tools.\r\n- Create a Page (a database row) inside a Database.\r\n- Delete a Page from a Database.\r\n- Restore a deleted Page from a Database.\r\n\r\n### Blocks\r\n\r\n- Get all supported children Blocks from a Page.\r\n\r\n### Users\r\n\r\n- Get all Users from a Database.\r\n- Get a single User by User ID.\r\n\r\n## 🏁 Getting Started\r\n\r\n### Prerequisites\r\n\r\n1. A Notion account. A free personal account will give you access to unlimited pages.\r\n2. Create an integration key through My intgerations: https://www.notion.so/my-integrations.\r\n\r\n\u003cp align=\"center\"\u003e\r\n\u003cimg src=\"https://firebasestorage.googleapis.com/v0/b/andrewvo-co.appspot.com/o/notiondb%2F2ec137d-093ad49-create-integration.gif?alt=media\u0026token=f950f2ba-0672-49d7-93b2-3bedbe7a5afa\" alt=\"Integration Key\"\u003e\r\n\u003c/p\u003e\r\n\r\n3. Share a Databae with your integration.\r\n\r\n\u003cp align=\"center\"\u003e\r\n\u003cimg src=\"https://firebasestorage.googleapis.com/v0/b/andrewvo-co.appspot.com/o/notiondb%2F0a267dd-share-database-with-integration.gif?alt=media\u0026token=7336cf03-de4e-4e7d-b38f-c9a5d75201cc\" alt=\"Integration Key\"\u003e\r\n\u003c/p\u003e\r\n\r\nFor more information on integrations, visit: https://developers.notion.com/docs.\r\n\r\n### Installing\r\n\r\nInstall the package using npm:\r\n\r\n```\r\nnpm install notiondb\r\n```\r\n\r\nOr with yarn:\r\n\r\n```\r\nyarn add notiondb\r\n```\r\n\r\n## 🎈 Usage\r\n\r\n### Initialization\r\n\r\n```javascript\r\nconst { NotionDB } = require('notiondb');\r\n\r\nconst integrationKey = process.env.NOTION_INTEGRATION_KEY;\r\nconst notionDB = new NotionDB(integrationKey);\r\n```\r\n\r\n### Databases\r\n\r\n#### Get all Database references available from the integration.\r\n\r\n```javascript\r\nconst databases = await notionDB.databases.getAll();\r\nconsole.log(databases.map((d) =\u003e d.object));\r\n```\r\n\r\n#### Get a single Database reference using a Database ID or Database URL.\r\n\r\n```javascript\r\nconst { NotionUrl, NotionUrlTypes, NotionId } = require('notiondb/models');\r\n\r\n// Method 1 of Database lookup\r\nconst url = new NotionUrl(\r\n  'https://www.notion.so/notion-user/9dbfa923a10242b8bdcb3158fa2fc54b?v=3caf278e48064aea87b9e0c849a5a6d9',\r\n  NotionUrlTypes.DATABASE,\r\n);\r\nconst database = await notionDB.databases.get(url);\r\nconsole.log(database.object);\r\n\r\n// Method 2 of Database lookup\r\nconst id = new NotionId('9dbfa923a10242b8bdcb3158fa2fc54b');\r\nconst database = await notionDB.databases.get(id);\r\nconsole.log(database.object);\r\n```\r\n\r\n#### Create a new Database using a Schema. Databases must be created inside a Parent Page.\r\n\r\n```javascript\r\nconst { PropertySchema, SchemaObject } = require('notiondb/schema');\r\nconst { NotionId } = require('notiondb/models');\r\n\r\nconst parentPageId = new NotionId('6dbfa957f10282b8cdcb3458fa2c54f');\r\nconst title = 'Orders';\r\nconst schemaObjects = [\r\n  new SchemaObject('Order ID', 'title'),\r\n  new SchemaObject('Date', 'date'),\r\n  new SchemaObject('Product', 'select'),\r\n  new SchemaObject('Price', 'number'),\r\n  new SchemaObject('Quantity', 'select'),\r\n];\r\n// A schema takes an array of schema objects\r\nconst schema = new PropertySchema(schemaObjects);\r\nconst database = await notionDB.databases.create(parentPageId, title, schema);\r\nconsole.log(database.object);\r\n```\r\n\r\n### Pages\r\n\r\n#### Get all Pages from a Database.\r\n\r\n```javascript\r\n// Get an existing Database reference first\r\nconst pages = await database.pages.getAll();\r\nconsole.log(pages.map((p) =\u003e p.object));\r\n```\r\n\r\n#### Get many Pages using Filters and Sorts from a Database.\r\n\r\n```javascript\r\nconst {\r\n  CompoundFilter,\r\n  NumberFilter,\r\n  SelectFilter,\r\n} = require('notiondb/models/filter');\r\nconst { PropertySort, TimestampSort } = require('notiondb/models/sort');\r\nconst { PropertySchema, SchemaObject } = require('notiondb/schema');\r\n\r\n/**\r\n * Filter by Price \u003e 5\r\n * Sort by Price from highest to lowest\r\n */\r\nconst options = {\r\n  filter: new NumberFilter('Price', 'greater_than', 5),\r\n  sort: new PropertySort('Price', 'descending'),\r\n};\r\nconst pages = await database.pages.getMany(options);\r\nconsole.log(pages.map((p) =\u003e p.object));\r\n\r\n/**\r\n * Filter by Price \u003e 5 AND Product is Sunglasses\r\n * Sort by Last Edited Time, newest to oldest\r\n */\r\nconst priceFilter = new NumberFilter('Price', 'greater_than', 5);\r\nconst productFilter = new SelectFilter('Product', 'equals', 'Sunglasses');\r\nconst compoundFilter = new CompoundFilter([priceFilter, productFilter], 'and');\r\n\r\nconst options = {\r\n  filter: compoundFilter,\r\n  sort: new TimestampSort('last_edited_time', 'descending'),\r\n};\r\nconst pages = await database.pages.getMany(options);\r\nconsole.log(pages.map((p) =\u003e p.object));\r\n\r\n/**\r\n * Filter by Price \u003e 5 AND Product is Sunglasses\r\n * OR\r\n * Product is Reading Glasses\r\n * Sort by Last Edited Time, newest to oldest\r\n */\r\nconst priceFilter = new NumberFilter('Price', 'greater_than', 5);\r\nconst productFilter = new SelectFilter('Product', 'equals', 'Sunglasses');\r\nconst compoundFilter = new CompoundFilter([priceFilter, productFilter], 'and');\r\nconst readingGlassesFilter = new SelectFilter(\r\n  'Product',\r\n  'equals',\r\n  'Reading Glasses',\r\n);\r\nconst topLevelCompoundFilter = new CompoundFilter(\r\n  [compoundFilter, readingGlassesFilter],\r\n  'or',\r\n);\r\n\r\nconst options = {\r\n  filter: topLevelCompoundFilter,\r\n};\r\nconst pages = await database.pages.getMany(options);\r\nconsole.log(pages.map((p) =\u003e p.object));\r\n```\r\n\r\n#### Get a single Page using a Page ID or Page URL.\r\n\r\n```javascript\r\n// Method 1 of Page lookup\r\nconst { NotionId, NotionUrl, NotionUrlTypes } = require('notiondb/models');\r\n\r\nconst url = new NotionUrl(\r\n  'https://www.notion.so/notion-user/My-First-Page-ec51a30420fe800db023d48671466f29',\r\n  NotionUrlTypes.PAGE,\r\n);\r\nconst page = await database.pages.get(url);\r\nconsole.log(page.object);\r\n\r\n// Method 2 of Page lookup (with excluded properties on result)\r\nconst id = new NotionId('ec51a30420fe800db023d48671466f29');\r\nconst excludeProperties = ['Price', 'Quantity'];\r\nconst page = await database.pages.get(id, excludeProperties);\r\nconsole.log(page.object);\r\n```\r\n\r\n#### Create a new Page in an existing Database.\r\n\r\n```javascript\r\n// Get an existing Database reference first\r\nconst page = await database.pages.create({\r\n  'Order ID': uuidv4(),\r\n  Date: new Date(),\r\n  Product: '3D Glasses',\r\n  Price: 12.99,\r\n  Quantity: 15,\r\n});\r\nconsole.log(page.object);\r\n```\r\n\r\n#### Create a new Page in an existing Database with additional options for Date.\r\n\r\n```javascript\r\nconst startDate = new Date();\r\nconst endDate = new Date();\r\nendDate.setDate(startDate.getDate() + 2);\r\n\r\n// Get an existing Database reference first\r\nconst page = await database.pages.create({\r\n  'Order ID': uuidv4(),\r\n  Date: {\r\n    value: startDate,\r\n    options: {\r\n      includeTime: true,\r\n      timezone: 'Australia/Sydney',\r\n      end: endDate,\r\n    },\r\n  },\r\n  Product: '3D Glasses',\r\n  Price: 12.99,\r\n  Quantity: 15,\r\n});\r\nconsole.log(page.object);\r\n```\r\n\r\n#### Update an existing Page.\r\n\r\n```javascript\r\nconst { NotionId } = require('notiondb/models');\r\n\r\n// Update existing Page object retrieved from a previous Page get()\r\nconst updatedPage = await page.update({\r\n  Price: 9.99,\r\n  Product: 'Sunglasses',\r\n});\r\n\r\n// Use static update method to update blindly using a Notion ID or Notion URL\r\nconst id = new NotionId('ec51a30420fe800db023d48671466f29');\r\nconst updatedPage = await database.pages.update(id, {\r\n  Price: 9.99,\r\n  Product: 'Sunglasses',\r\n});\r\n```\r\n\r\n#### Delete an existing Page.\r\n\r\n```javascript\r\nconst { NotionId } = require('notiondb/models');\r\n\r\n// Delete existing Page object retrieved from a previous Page get()\r\nconst deletedPage = await page.delete();\r\n\r\n// Use static delete method to delete (archive) blindly using a Notion ID or Notion URL\r\nconst id = new NotionId('ec51a30420fe800db023d48671466f29');\r\nconst deletedPage = await database.pages.delete(id);\r\n```\r\n\r\n#### Restore a deleted Page.\r\n\r\n```javascript\r\nconst { NotionId } = require('notiondb/models');\r\n\r\n// Restore existing Page object retrieved from a previous Page get()\r\nconst restoredPage = await page.restore();\r\n\r\n// Use static restore method to restore (unarchive) blindly using a Notion ID or Notion URL\r\nconst id = new NotionId('ec51a30420fe800db023d48671466f29');\r\nconst restoredPage = await database.pages.restore(id);\r\n```\r\n\r\n### Blocks\r\n\r\n#### Get all children Blocks of a Page.\r\n\r\n```javascript\r\n// Get an existing Page reference first\r\nconst blocks = await page.blocks.getAll();\r\nconsole.log(blocks.map((b) =\u003e b.object));\r\n```\r\n\r\n### Users\r\n\r\n#### List all users from a Database.\r\n\r\n```javascript\r\n// Get an existing Database reference first\r\nconst users = await database.users.getAll();\r\nconsole.log(users.map((u) =\u003e u.object));\r\n```\r\n\r\n#### Get a single User using a User ID.\r\n\r\n```javascript\r\nconst { NotionId } = require('notiondb/models');\r\n\r\nconst id = new NotionId('193ead88-13c7-46ef-a6a2-62fa58234e7d');\r\nconst user = await database.users.get(id);\r\nconsole.log(user.object);\r\n```\r\n\r\n## ⛏️ Built Using\r\n\r\n- [Notion API](https://developers.notion.com/) - API Requests\r\n- [Node.js](https://nodejs.org/en/) - Server Environment\r\n- [TypeScript](https://www.typescriptlang.org/) - Language\r\n\r\n## ✍️ Authors\r\n\r\n- [@andrewvo89](https://github.com/andrewvo89) - Founder and creator\r\n\r\n## 🎉 Acknowledgements\r\n\r\n- [Notion](https://www.notion.so/) for their amazing product.\r\n- [Mongoose](https://mongoosejs.com/) for concept inspiration.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvo89%2Fnotiondb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrewvo89%2Fnotiondb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrewvo89%2Fnotiondb/lists"}