@elumixor/notion-orm 0.1.1 → 2.0.2

package/README.md

@@ -1,267 +1,169 @@
-# Notion ORM
+# notion-orm
 
-⚠️ This package is Still in development 🏗️
-
-A library to simplify adding and querying [Notion](https://notion.so/product) databases/tables. Giving typeahead/intellisense support on columns and expected column values on user specified databases. Built on top of [Notion API](https://developers.notion.com/)
-
-Databases with the following column types are supported:
-
-- Multi-select
-- Select
-- Status
-- Date
-- Text
-- Url
-- Checkbox
-- Email
-- Phone Number
+TypeScript ORM for Notion databases. Generates fully-typed clients from your Notion schemas.
 
 ## Installation
 
-The only requirement is a Notion Developer API key ([here](https://developers.notion.com/)) and database IDs you want. Be sure to connect your [integration](https://developers.notion.com/docs/working-with-databases#adding-pages-to-a-database) (🚧 *Permissions* section) with your tables
-
 ```bash
-npm install @haustle/notion-orm --save-dev
+npm install @elumixor/notion-orm
 ```
 
-At the root of your project run the CLI to scaffold a config file (defaults to JavaScript unless a `tsconfig.json` is present):
+## Setup
+
+**1. Initialize config**
 
 ```bash
-npx notion init
-# or
-bun notion init
+notion init
 ```
 
-You can force a specific format with `--js` or `--ts`. You’ll need to pass your developer key and database IDs. How to get database IDs [here](https://developers.notion.com/docs/working-with-databases#adding-pages-to-a-database)
+Creates `notion.config.ts` in your project root:
 
-```tsx
-// notion.config.ts (generated with `notion init --ts`)
+```ts
+import type { NotionConfigType } from "@elumixor/notion-orm";
 
-// Be sure to create a .env.local file and add your NOTION_KEY
-
-// If you don't have an API key, sign up for free
-// [here](https://developers.notion.com)
-
-const auth = process.env.NOTION_KEY || "your-notion-api-key-here";
-const NotionConfig = {
-  auth,
-  databaseIds: [
-    // Add undashed database source IDs here (ex. "2a3c495da03c80bc99fe000bbf2be4bb")
-    // or use the following command to automatically update
-    // `notion add <database-source-id or URL>`
-    // If you decide to manually add database IDs, be sure to run
-    // `notion generate` to properly update the local database types
-  ],
-};
-
-export default NotionConfig;
+export default {
+  auth: process.env.NOTION_API_KEY ?? "",
+  databases: {
+    tasks: "your-notion-tasks-database-id",
+    people: "your-notion-people-database-id",
+  },
+} satisfies NotionConfigType;
 ```
 
-Execute the following command from the root project directory.
+**2. Generate types**
 
 ```bash
-npx notion generate
+notion generate
 ```
 
-**Package Size**
-Unpackaged size is 70.6KB and the installation size is 5.12MB (5.03MB from `@notionhq/client` dependency)
+Generates `generated/notion-orm/` with a typed client per database and an `index.ts` entry point.
 
-## Implementation
+**3. Use in your project**
 
-Databases can be imported via barrel file or from the individual database file. All database names will be camelCase 🐫.
+```ts
+import { NotionORM } from "../generated/notion-orm";
 
-```tsx
-// Barrel Import (access to all databases)
-import * as notion from "@haustle/notion-orm";
-notion.databaseName.add();
-notion.databaseName2.query();
-```
+const notion = new NotionORM(process.env.NOTION_API_KEY);
 
-```jsx
-// Individual Database Import
-import {
-  databaseName,
-  DatabaseSchemaType,
-  QuerySchemaType,
-} from "@haustle/notion-orm/build/db/databaseName";
-
-databaseName.add();
+// or with a config object
+const notion = new NotionORM({ auth: process.env.NOTION_API_KEY });
 ```
 
-- `DatabaseSchemaType`: Object type accepted in the database’s `add()` function
-- `QuerySchemaType`: Object type accepted in the database’s `query()` function
+## API
 
-The following examples for querying & adding are for server-side calls. If you’re looking to use this framework to execute client-side calls (ex. button click add/query X) visit the [Client (React)](https://www.notion.so/Notion-ORM-README-fdd30271bf944a3e85cb999ec8d5447d) section after reading
+All methods are fully typed based on your Notion schema.
 
-**Adding**
+### Reading
 
-Only required column required is the title.
+```ts
+// All records
+const tasks = await notion.tasks.findMany();
 
-```jsx
-notion.books.add({
-  bookName: "Raphael, Painter in Rome: a Novel", // title
-  author: "Stephanie Storey", // text
-  status: "In progress", // status
-  numberOfPages: 307, // number
-  genre: ["Historical Fiction"], // multi-select
-  rating: "⭐️⭐️⭐️⭐️", // select
-  startDate: {
-    // date
-    start: "2023-01-01",
-  },
-  phone: "0000000000", // phone
-  email: "tyrus@haustle.studio", // email
+// With filter, sort, and limit
+const tasks = await notion.tasks.findMany({
+  where: { status: { equals: "In Progress" } },
+  orderBy: { name: "asc" },
+  take: 10,
 });
-```
 
-All column types in Notion databases are mapped to a typescript type.
-
-| Column Type  | Object         |
-| ------------ | -------------- |
-| Title        | string         |
-| Text         | string         |
-| Select       | string         |
-| Multi-select | Array (string) |
-| Status       | string         |
-| Number       | number         |
-| Date         | Object         |
-| Phone number | string         |
-| Email        | string         |
+// First match or null
+const task = await notion.tasks.findFirst({
+  where: { name: { contains: "bug" } },
+});
 
-**Querying**
+// By page ID
+const task = await notion.tasks.findUnique({ where: { id: "page-id" } });
 
-For each column type you’ll be presented with the available querying filter. Find all filter conditions [here](https://developers.notion.com/reference/post-database-query-filter)
+// Page-by-page (UI pagination)
+const page1 = await notion.tasks.paginate({ take: 20 });
+const page2 = await notion.tasks.paginate({
+  take: 20,
+  after: page1.nextCursor,
+});
+// => { data, nextCursor, hasMore }
 
-While the querying functionality works, it’s **not complete and there is room for user error**. For instance, the `filter` object should contain one child. Either the column name (signifies single filter), or `and` or `or` (signify compound filters). However there is no typecheck in place to stop adding multiple children
+// Streaming all results in batches (AsyncIterable)
+for await (const task of notion.tasks.findMany({ stream: 50 })) {
+  console.log(task.name);
+}
 
-Unlike `add()` , there is no transformation after the inputted object. So the querying object you’re creating is exactly what you’d normally use to query the Notion API. Learn more about them [here](https://developers.notion.com/reference/post-database-query-filter)
+// Count
+const total = await notion.tasks.count({
+  where: { status: { equals: "Done" } },
+});
+```
 
-Example of a single filter
+### Select / omit
 
-```tsx
-notion.books.query({
-  filter: {
-    genre: {
-      contains: "Sci-Fi",
-    },
-  },
-  sort: [
-    {
-      property: "name",
-      direction: "ascending",
-    },
-    {
-      property: "Author name",
-      direction: "ascending",
-    },
-  ],
+```ts
+// Return only specific fields
+const tasks = await notion.tasks.findMany({
+  select: { name: true, status: true },
 });
-```
 
-Example of compound filters, which is signified with `and` and `or`. You can nest these are far as you want (i.e `and` filters within `or` filter). Learn more [here](https://developers.notion.com/reference/post-database-query-filter#compound-filter-object)
-
-```tsx
-await notion.books.query({
-  filter: {
-    or: [
-      {
-        genre: {
-          contains: "Sci-Fi",
-        },
-      },
-      {
-        genre: {
-          contains: "Biography",
-        },
-      },
-    ],
-  },
+// Exclude specific fields
+const tasks = await notion.tasks.findMany({
+  omit: { internalNotes: true },
 });
 ```
 
-Down below is what’s returned on a successful response. `results` being a simplified extracted version of the `rawResponse` (response from Notion API)
-
-```tsx
-{
-	rawResponse: { /* Whatever Notion API returns */},
-	results: [
-		{
-			bookName: "How to Change Your Mind",
-			genre: ["Non-fiction"],
-			numberPages: 460,
-			rating: "⭐️⭐️⭐️⭐️"
-		},
-	]
-}
-```
+### Writing
 
-## Client-side (React)
+```ts
+// Create
+const task = await notion.tasks.create({
+  data: { name: "Fix bug", status: "Todo" },
+});
 
-Notion API currently blocks calls from browser (per CORS)
+// Create many
+await notion.tasks.createMany({
+  data: [{ name: "Task A" }, { name: "Task B" }],
+});
 
-You can get around this by creating API endpoints on stack of your choice. I’ve provided examples only for **Next.js**, but the high level implementation should work with any backend.
+// Update by ID
+await notion.tasks.update({
+  where: { id: "page-id" },
+  data: { status: "Done" },
+});
 
-If you’re planning to only make server-side calls to your Notion database (from `GetStaticProps` or `GetServerSideProps`). These calls work totally fine, as these functions are executed server-side before page load. So you can ignore the proceeding steps
+// Update all matching
+await notion.tasks.updateMany({
+  where: { status: { equals: "Todo" } },
+  data: { status: "In Progress" },
+});
 
-```tsx
-export const getStaticProps: GetStaticProps = async () => {
-	const response = await NotionClient.books.query({
-		filter: {
-			genre: {
-				is_not_empty: true,
-			},
-		},
-	});
-	return {
-		props: {
-			apiResponse: response
-		}
-	}
-```
+// Upsert
+await notion.tasks.upsert({
+  where: { name: { equals: "Fix bug" } },
+  create: { name: "Fix bug", status: "Todo" },
+  update: { status: "In Progress" },
+});
 
-To execute calls client-side (ex. on button click) an API endpoint is needed to get around CORS. In this example we’re passing the databases `DatabaseSchemaType` as the body of the API call.
+// Delete by ID
+await notion.tasks.delete({ where: { id: "page-id" } });
 
-```tsx
-import { DatabaseSchemaType } from "@haustle/notion-orm/build/db/books";
+// Delete all matching
+await notion.tasks.deleteMany({
+  where: { status: { equals: "Done" } },
+});
+```
 
-async function addPageToNotionDatabase() {
-  const example: DatabaseSchemaType = {
-    bookName: "How to Change Your Mind",
-    genre: ["Non-fiction"],
-  };
+## CLI
 
-  // make sure this route reflects your API path
-  await fetch("/api/notion/books", {
-    method: "POST",
-    body: JSON.stringify(example),
-  });
-}
 ```
-
-```jsx
-<button onClick={ async() => await addPageToNotionDatabase()}>
+notion init                              Create notion.config.ts
+notion generate                          Generate types for all configured databases
+notion add <name> <database-id-or-url>   Add a database and generate its types
 ```
 
-Example API endpoint below, where we’re taking the body of type `DatabaseSchemaType` and passing it into the respected databases `add()` function to add a new page to the database. Learn more about _Next.js_ API’s and routing [here](https://nextjs.org/docs/api-routes/introduction).
-
-```tsx
-// pages/api/notion/yourDatabaseName.ts
+## Config options
 
-import type { NextApiRequest, NextApiResponse } from "next";
-import {
-  DatabaseSchemaType,
-  yourDatabaseName,
-} from "@haustle/notion-orm/build/db/yourDatabaseName";
+| Field       | Type                     | Default                  | Description                                 |
+| ----------- | ------------------------ | ------------------------ | ------------------------------------------- |
+| `auth`      | `string`                 | —                        | Notion integration token                    |
+| `databases` | `Record<string, string>` | —                        | Map of name → database ID                   |
+| `outputDir` | `string`                 | `"generated/notion-orm"` | Output directory (relative to project root) |
 
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  const { method, body } = req;
+## Environment
 
-  if (method === "POST") {
-    const bodyJSON = JSON.parse(body) as DatabaseSchemaType;
-    await yourDatabaseName.add(bodyJSON);
-  }
-}
-```
+Set `NOTION_API_KEY` in your environment or `.env` file, or pass it directly via the `auth` field in `notion.config.ts`.

package/dist/ast/constants.d.ts

@@ -1,27 +1,26 @@
 /**
  * Internal constants for AST and db-client modules.
  */
-/** Generated DB files directory — always relative to the consuming project */
-export declare const DATABASES_DIR: string;
+/** Default output directory for generated files, relative to consuming project root */
+export declare const DEFAULT_OUTPUT_DIR = "generated/notion-orm";
+/** Resolve the absolute path to the databases output directory */
+export declare function getDatabasesDir(outputDir?: string): string;
 /** File system paths for CLI output */
-export declare const AST_FS_PATHS: {
-    /** metadata.json inside generated/ */
+export declare function getFSPaths(databasesDirPath: string): {
+    /** metadata.json inside the output directory */
     readonly metadataFile: string;
-    /** src/index.ts — the dynamic barrel rewritten on every generate */
-    readonly sourceIndexTs: string;
-    /** generated/index.ts — barrel exporting all DB clients */
-    readonly generatedBarrelTs: string;
+    /** index.ts — the NotionORM class written to the output directory */
+    readonly notionORMFile: string;
 };
 export declare const AST_FS_FILENAMES: {
     readonly METADATA: "metadata.json";
     readonly INDEX_TS: "index.ts";
 };
-/** Import path strings used when generating TypeScript code */
-export declare const AST_IMPORT_PATHS: {
-    readonly DATABASE_CLIENT: "../src/db-client/DatabaseClient" | "@elumixor/notion-orm";
-    readonly QUERY_TYPES: "@elumixor/notion-orm" | "../src/db-client/queryTypes";
+/** Import path strings used when generating TypeScript code inside a given output directory */
+export declare function getImportPaths(databasesDirPath: string): {
+    readonly DATABASE_CLIENT: string;
+    readonly QUERY_TYPES: string;
     readonly ZOD: "zod";
-    readonly databaseClass: (className: string) => string;
 };
 export declare const AST_RUNTIME_CONSTANTS: {
     readonly NOTION_API_VERSION: "2025-09-03";