feat: improve configuration of databases with union type

Author: JohannesRudolph

src/ChildDatabaseRenderer.ts

@@ -7,7 +7,7 @@ import { Database } from "./Database";
 import { DatabaseViewRenderer } from "./DatabaseViewRenderer";
 import { DeferredRenderer } from "./DeferredRenderer";
 import { RenderDatabasePageTask } from "./RenderDatabasePageTask";
-import { DatabaseConfig } from "./SyncConfig";
+import { DatabaseConfig, DatabaseConfigRenderPages, DatabaseConfigRenderTable } from "./SyncConfig";
 import { DatabaseTableRenderer } from "./DatabaseTableRenderer";
 
 export class ChildDatabaseRenderer {
@@ -26,11 +26,12 @@ export class ChildDatabaseRenderer {
     const allPages = await this.fetchPages(databaseId, dbConfig);
 
     const isCmsDb = this.config.cmsDatabaseId === databaseId;
-    const renderPages = isCmsDb || dbConfig.views;
+    const renderPages = isCmsDb || dbConfig.renderAs === "pages+views"
 
     if (renderPages) {
-      const entries = await this.queuePageRendering(allPages, dbConfig);
-      const markdown = await this.viewRenderer.renderViews(entries, dbConfig);
+      const pageConfig = dbConfig as DatabaseConfigRenderPages;
+      const entries = await this.queuePageRendering(allPages, pageConfig);
+      const markdown = await this.viewRenderer.renderViews(entries, dbConfig as DatabaseConfigRenderPages);
 
       return {
         config: dbConfig,
@@ -51,7 +52,7 @@ export class ChildDatabaseRenderer {
 
   private async queueEntryRendering(
     allPages: Page[],
-    dbConfig: DatabaseConfig
+    dbConfig: DatabaseConfigRenderTable
   ) {
     const prepareRenderEntryTasks = allPages.map((x) =>
       this.deferredRenderer.renderEntry(x, dbConfig)
@@ -63,7 +64,7 @@ export class ChildDatabaseRenderer {
 
   private async queuePageRendering(
     allPages: Page[],
-    dbConfig: DatabaseConfig
+    dbConfig: DatabaseConfigRenderPages
   ): Promise<RenderDatabasePageTask[]> {
     const prepareRenderPageTasks = allPages.map((x) =>
       this.deferredRenderer.renderPage(x, dbConfig)

src/DatabasePageRenderer.ts

@@ -1,15 +1,15 @@
-import * as fsc from 'fs';
+import * as fsc from "fs";
 
-import { Page } from '@notionhq/client/build/src/api-types';
+import { Page } from "@notionhq/client/build/src/api-types";
 
-import { AssetWriter } from './AssetWriter';
-import { FrontmatterRenderer } from './FrontmatterRenderer';
-import { logger } from './logger';
-import { PropertiesParser } from './PropertiesParser';
-import { RecursiveBodyRenderer } from './RecursiveBodyRenderer';
+import { AssetWriter } from "./AssetWriter";
+import { FrontmatterRenderer } from "./FrontmatterRenderer";
+import { logger } from "./logger";
+import { PropertiesParser } from "./PropertiesParser";
+import { RecursiveBodyRenderer } from "./RecursiveBodyRenderer";
 import { RenderDatabasePageTask as RenderDatabasePageTask } from "./RenderDatabasePageTask";
-import { slugify } from './slugify';
-import { DatabaseConfig } from './SyncConfig';
+import { slugify } from "./slugify";
+import { DatabaseConfigRenderPages } from "./SyncConfig";
 
 const fs = fsc.promises;
 
@@ -20,8 +20,11 @@ export class DatabasePageRenderer {
     readonly bodyRenderer: RecursiveBodyRenderer
   ) {}
 
-  async renderPage(page: Page, config: DatabaseConfig): Promise<RenderDatabasePageTask> {
-    if (page.archived){
+  async renderPage(
+    page: Page,
+    config: DatabaseConfigRenderPages
+  ): Promise<RenderDatabasePageTask> {
+    if (page.archived) {
       logger.warn(`rendering archived page ${page.url}`);
     }
 

src/DatabaseViewRenderer.ts

@@ -2,7 +2,7 @@ import { LinkRenderer } from "./LinkRenderer";
 import * as markdownTable from "./markdown-table";
 import { PropertiesParser } from "./PropertiesParser";
 import { RenderDatabasePageTask } from "./RenderDatabasePageTask";
-import { DatabaseConfig, DatabaseView } from "./SyncConfig";
+import { DatabaseConfigRenderPages, DatabaseView } from "./SyncConfig";
 import { DatabaseTableRenderer } from "./DatabaseTableRenderer";
 
 const debug = require("debug")("database");
@@ -11,7 +11,7 @@ const debug = require("debug")("database");
 export class DatabaseViewRenderer {
   constructor(private readonly linkRenderer: LinkRenderer) {}
 
-  public renderViews(entries: RenderDatabasePageTask[], config: DatabaseConfig): string {
+  public renderViews(entries: RenderDatabasePageTask[], config: DatabaseConfigRenderPages): string {
     const views = config.views?.map((view) => {
       const propKeys = entries[0].properties.keys;
       const propKey = propKeys.get(view.properties.groupBy);

src/DeferredRenderer.ts

@@ -7,7 +7,10 @@ import { RenderedDatabaseEntry } from "./RenderedDatabaseEntry";
 import { RenderedDatabasePage } from "./RenderedDatabasePage";
 import { RenderDatabasePageTask as RenderDatabasePageTask } from "./RenderDatabasePageTask";
 import { RenderDatabaseEntryTask } from "./RenderDatabaseEntryTask";
-import { DatabaseConfig } from "./SyncConfig";
+import {
+  DatabaseConfigRenderPages,
+  DatabaseConfigRenderTable,
+} from "./SyncConfig";
 import { Database } from "./Database";
 import { DatabaseEntryRenderer } from "./DatabaseEntryRenderer";
 
@@ -39,7 +42,7 @@ export class DeferredRenderer {
 
   public async renderPage(
     page: Page,
-    config: DatabaseConfig
+    config: DatabaseConfigRenderPages
   ): Promise<RenderDatabasePageTask> {
     // cache to avoid rendering the same page twice, e.g. when it is linked multiple times
     const cached = this.renderedPages.get(page.id);
@@ -58,7 +61,7 @@ export class DeferredRenderer {
 
   public async renderEntry(
     page: Page,
-    config: DatabaseConfig
+    config: DatabaseConfigRenderTable
   ): Promise<RenderDatabaseEntryTask> {
     const task = await this.entryRenderer.renderEntry(page, config);
 

src/MentionedPageRenderer.ts

@@ -25,6 +25,12 @@ export class MentionedPageRenderer {
 
     const dbConfig = lookupDatabaseConfig(this.config, databaseId);
 
+    if (dbConfig.renderAs !== "pages+views") {
+      throw new Error(
+        `Encountered page mention for page ${pageId}, but the mentioned page is not part of a database configured to render as 'pages+views'`
+      );
+    }
+
     return this.deferredRenderer.renderPage(page, dbConfig);
   }
 

src/PropertiesParser.ts

@@ -1,10 +1,10 @@
-import { Page, PropertyValue } from '@notionhq/client/build/src/api-types';
+import { Page, PropertyValue } from "@notionhq/client/build/src/api-types";
 
-import { logger } from './logger';
-import { PageProperties } from './PageProperties';
-import { RichTextRenderer } from './RichTextRenderer';
-import { slugify } from './slugify';
-import { DatabaseConfig } from './SyncConfig';
+import { logger } from "./logger";
+import { PageProperties } from "./PageProperties";
+import { RichTextRenderer } from "./RichTextRenderer";
+import { slugify } from "./slugify";
+import { DatabaseConfig, DatabaseConfigRenderPages } from "./SyncConfig";
 
 const debug = require("debug")("properties");
 
@@ -21,17 +21,25 @@ export class PropertiesParser {
 
   public async parsePageProperties(
     page: Page,
-    config: DatabaseConfig,
+    config: DatabaseConfigRenderPages
   ): Promise<PageProperties> {
-    const { title, category, order, properties, keys } = await this
-      .parseProperties(page, config);
+    const {
+      title,
+      category,
+      order,
+      properties,
+      keys,
+    } = await this.parseProperties(page, config);
 
     if (!title) {
       throw this.errorMissingRequiredProperty("of type 'title'", page);
     }
 
     if (!category) {
-      throw this.errorMissingRequiredProperty(config.properties.category, page);
+      throw this.errorMissingRequiredProperty(
+        config.pages.frontmatter.category.property,
+        page
+      );
     }
 
     return {
@@ -41,26 +49,35 @@ export class PropertiesParser {
         title: title, // notion API always calls it name
         category: category,
         order: order,
-        ...config.additionalPageFrontmatter,
+        ...config.pages.frontmatter.extra,
       },
       values: properties,
       keys: keys,
     };
   }
 
- public async parseProperties(page: Page, config: DatabaseConfig) {
+  public async parseProperties(page: Page, config: DatabaseConfig) {
+    /**
+     * Design: we always lookup the properties opn the page object itself.
+     * This way we only parse properties once and avoid any problems coming from
+     * e.g. category properties being filtered via include filters.
+     */
     const properties: Record<string, any> = {};
     const keys = new Map<string, string>();
 
     let title: string | null = null;
     let category: string | null = null;
     let order: number | undefined = undefined;
 
+    const categoryProperty =
+      config.renderAs === "pages+views" &&
+      config.pages.frontmatter.category.property;
+
     for (const [name, value] of Object.entries(page.properties)) {
       const parsedValue = await this.parsePropertyValue(value);
 
       if (
-        !config.properties.include ||
+        !config.properties?.include ||
         config.properties.include.indexOf(name) >= 0
       ) {
         const slug = slugify(name);
@@ -72,7 +89,7 @@ export class PropertiesParser {
         title = parsedValue;
       }
 
-      if (name === config.properties.category) {
+      if (categoryProperty && name === categoryProperty) {
         category = parsedValue;
       }
 
@@ -86,8 +103,8 @@ export class PropertiesParser {
       order,
       properties,
       keys: PropertiesParser.filterIncludedKeys(
-        config.properties.include,
-        keys,
+        config.properties?.include,
+        keys
       ),
     };
   }
@@ -137,7 +154,7 @@ export class PropertiesParser {
 
   public static filterIncludedKeys(
     includes: string[] | undefined,
-    keys: Map<string, string>,
+    keys: Map<string, string>
   ): Map<string, string> {
     if (!includes) {
       return keys;

src/SyncConfig.ts

@@ -1,4 +1,4 @@
-import { Sort } from '@notionhq/client/build/src/api-types';
+import { Sort } from "@notionhq/client/build/src/api-types";
 
 export interface SyncConfig {
   /**
@@ -33,7 +33,11 @@ export interface SyncConfig {
   databases: Record<string, DatabaseConfig>;
 }
 
-export interface DatabaseConfig {
+export type DatabaseConfig =
+  | DatabaseConfigRenderPages
+  | DatabaseConfigRenderTable;
+
+export interface DatabaseConfigBase {
   /**
    * The output directory where the sync will place pages of this database.
    *
@@ -46,49 +50,71 @@ export interface DatabaseConfig {
    */
   sorts?: Sort[];
 
-  /**
-   * Add custom data to the page frontmatter
-   */
-  additionalPageFrontmatter?: Record<string, any>;
-
   /**
    * Configuration options for Notion API page properties
    */
-  properties: {
-    /**
-     * The Notion API page property that provides an optional sub-category value to use for the markdown page category.
-     *
-     * Example: "Cluster"
-     */
-    category: string;
-
+  properties?: {
     /**
      * A whitelist of Notion API page property names to include in the markdown page properties.
      * Use this to select properties for export and control their ordering in rendered tables.
      */
     include?: string[];
   };
 
+  renderAs: "table" | "pages+views";
+}
+
+export interface DatabaseConfigRenderTable extends DatabaseConfigBase {
+  renderAs: "table";
+
+  entries: {
+    /**
+     * Controls whether to emit database entries to the index (see SyncConfig.indexPath)
+     */
+    emitToIndex: boolean;
+  };
+
+  
+}
+
+export interface DatabaseConfigRenderPages extends DatabaseConfigBase {
+  renderAs: "pages+views";
   /**
-   * Configure "views" to render on the page where the child_database is encountered. 
+   * Add custom data to the page frontmatter
+   */
+  pages: {
+    frontmatter: {
+      category: {
+        /**
+         * The Notion API page property that provides an optional sub-category value to use for the markdown page category.
+         *
+         * Example: "Cluster"
+         */
+        property: string;
+      };
+      extra?: Record<string, any>;
+    };
+  };
+
+  /**
+   * Configure "views" to render on the page where the child_database is encountered.
    * This allows to render different subsets of columns, groupings etc. to break down large tables.
    * Most useful as a "limited" replacement of more advanced database views, which are not exposed by Notion API
    * and not supported by markdown.
-   * 
-   * Note: 
-   * - When views are defined, child database pages are rendered as individual pages. 
+   *
+   * Note:
+   * - When views are defined, child database pages are rendered as individual pages.
    *   The first column of the view will link to the individual pages.
-   * - When no views are defined, child database pages are rendered as rows in a plain markdown table with all included 
+   * - When no views are defined, child database pages are rendered as rows in a plain markdown table with all included
    *   properties (see DatabaseConfig.properties.include).
-   * 
+   *
    */
-  views?: DatabaseView[]
+  views: DatabaseView[];
 }
-
 export interface DatabaseView {
   title: string;
   properties: {
     groupBy: string;
     include?: string[];
-  }
+  };
 }