refactor: simplify the way of handling page properties

- separate common page meta data (used by static site generators)
  from actual properties
- simplify db property filter logic
- remove default injection of #h1 heading on pages, this is better
  left to static site generator template engines

Author: JohannesRudolph

package.json

@@ -14,7 +14,8 @@
   "scripts": {
     "build": "tsc",
     "prepare": "tsc",
-    "test": "jest"
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
   "devDependencies": {
     "@types/jest": "^27.0.2",

src/DeferredRenderer.ts

@@ -80,14 +80,11 @@ export class DeferredRenderer {
     logger.success("sync complete");
   }
 
-  public getRenderedPages() : RenderedPage[] {
+  public getRenderedPages(): RenderedPage[] {
     return Array.from(this.renderedPages.values()).map((x) => ({
-      id: x.id,
-      category: x.category,
       file: x.file,
+      meta: x.properties.meta,
       properties: x.properties.values,
     }));
   }
 }
-
-

src/FrontmatterRenderer.ts

@@ -1,11 +1,17 @@
 import * as yaml from "js-yaml";
+import { PageProperties } from "./PageProperties";
 
 export class FrontmatterRenderer {
   constructor() {}
 
-  public renderFrontmatter(properties: Record<string, any>) {    
-    const frontmatter = `---\n${yaml.dump(properties)}---\n\n`;
+  public renderFrontmatter(props: PageProperties) {
+    const obj = {
+      ...props.meta,
+      properties: props.values,
+    };
 
-    return frontmatter
+    const frontmatter = `---\n${yaml.dump(obj)}---\n\n`;
+
+    return frontmatter;
   }
 }

src/PageProperties.ts

@@ -1,11 +1,23 @@
+export interface PageMeta {
+  id: string;
+  url: string;
+  title: string;
+  category: string;
+  order?: number;
+}
 
 export interface PageProperties {
+  meta: PageMeta;
+
   /**
    * A mapping of property object keys -> property values
    */
   values: Record<string, any>;
+  
   /**
    * A mapping of Notion API property names -> property object keys
    */
   keys: Map<string, string>;
 }
+
+export interface PagePropertiesWithMeta extends PageProperties {}

src/PageRenderer.ts

@@ -11,8 +11,6 @@ import { DatabaseConfig } from "./SyncConfig";
 import { PropertiesParser } from "./PropertiesParser";
 import { logger } from "./logger";
 
-const debug = require("debug")("page");
-
 const fs = fsc.promises;
 
 export class PageRenderer {
@@ -23,23 +21,12 @@ export class PageRenderer {
   ) {}
 
   renderPage(page: Page, config: DatabaseConfig): RenderPageTask {
-    const parsed = this.propertiesParser.parse(page.properties);
-    const props = this.propertiesParser.filter(config, parsed);
-
-    const name = props.values["name"];
-    if (!name) {
-      this.throwMissingRequiredProperty("name", page);
-    }
-
-    const category = props.values["category"];
-    if (!category) {
-      this.throwMissingRequiredProperty("category", page);
-    }
- 
-    const nameSlug = slugify(name);
-    const categorySlug = slugify(category);
+    const props = this.propertiesParser.parse(page, config);
 
+    const categorySlug = slugify(props.meta.category);
     const destDir = `${config.outDir}/${categorySlug}`;
+
+    const nameSlug = slugify(props.meta.title);
     const file = `${destDir}/${nameSlug}.md`;
 
     // Design: all the rendering performance could be greatly enhanced writing directly to output streams instead
@@ -48,20 +35,13 @@ export class PageRenderer {
 
     return {
       id: page.id,
-      category: categorySlug,
       file,
       properties: props,
       render: async () => {
         const assetWriter = new AssetWriter(destDir);
 
-        const frontmatter = this.frontmatterRenderer.renderFrontmatter(
-          props.values
-        );
-        const body = await this.bodyRenderer.renderBody(
-          page,
-          props,
-          assetWriter
-        );
+        const frontmatter = this.frontmatterRenderer.renderFrontmatter(props);
+        const body = await this.bodyRenderer.renderBody(page, assetWriter);
 
         await fs.mkdir(destDir, { recursive: true });
         await fs.writeFile(file, frontmatter + body);
@@ -70,11 +50,4 @@ export class PageRenderer {
       },
     };
   }
-
-  private throwMissingRequiredProperty(propertyName: string, page: Page) {
-    const msg = `Page ${page.url} is missing required property ${propertyName}`;
-    debug(msg + "\n%O", page);
-
-    throw new Error(msg);
-  }
 }

src/PropertiesParser.spec.ts

@@ -1,19 +1,41 @@
+import { Page } from "@notionhq/client/build/src/api-types";
 import { PropertiesParser } from "./PropertiesParser";
+import { RichTextRenderer } from "./RichTextRenderer";
 import { DatabaseConfig } from "./SyncConfig";
 
+const page: Partial<Page> = {
+  id: "123",
+  url: "http://example.com/123",
+  properties: {
+    order: { id: "a", type: "number", number: 30 },
+    Category: { id: "b", type: "select", select: { name: "Tools" } },
+    Name: {
+      id: "c",
+      type: "title",
+      title: [
+        {
+          type: "text",
+          text: { content: "Terraform" },
+          plain_text: "Terraform",
+          annotations: {
+            bold: false,
+            code: false,
+            color: "default",
+            italic: false,
+            strikethrough: false,
+            underline: false,
+          },
+        },
+      ],
+    },
+  },
+};
+
 describe("PropertiesParser", () => {
-  describe("filter", () => {
-    test("preserves all properties and adds conventional with no include filter", async () => {
-      const sut = new PropertiesParser({} as any);
+  describe("parse", () => {
 
-      const props = {
-        values: { order: 30, category: "Tools", name: "Terraform" },
-        keys: new Map([
-          ["order", "order"],
-          ["Category", "category"],
-          ["Name", "name"],
-        ]),
-      };
+    test("preserves all properties and adds conventional with no include filter", async () => {
+      const sut = new PropertiesParser(new RichTextRenderer());
 
       const config: DatabaseConfig = {
         outDir: "db/",
@@ -22,31 +44,32 @@ describe("PropertiesParser", () => {
         },
       };
 
-      const result = sut.filter(config, props);
+      const result = sut.parse(page as any, config);
+
       const expected = {
-        keys: props.keys,
+        meta: {
+          category: "Tools",
+          id: "123",
+          title: "Terraform",
+          url: "http://example.com/123",
+          order: 30
+        },
+        keys: new Map([
+          ["order", "order"],
+          ["Category", "category"],
+          ["Name", "name"],
+        ]),
         values: {
           order: 30,
           category: "Tools",
           name: "Terraform",
-          title: "Terraform",
         },
       };
-
       expect(result).toEqual(expected);
     });
 
     test("filters according to include filter", async () => {
-      const sut = new PropertiesParser({} as any);
-
-      const props = {
-        values: { order: 30, category: "Tools", name: "Terraform" },
-        keys: new Map([
-          ["order", "order"],
-          ["Category", "category"],
-          ["Name", "name"],
-        ]),
-      };
+      const sut = new PropertiesParser(new RichTextRenderer());
 
       const config: DatabaseConfig = {
         outDir: "db/",
@@ -56,19 +79,25 @@ describe("PropertiesParser", () => {
         },
       };
 
-      const result = sut.filter(config, props);
+      const result = sut.parse(page as any, config);
+
       const expected = {
+        meta: {
+          category: "Tools",
+          id: "123",
+          title: "Terraform",
+          url: "http://example.com/123",
+          order: 30
+        },
         keys: new Map([
           ["Name", "name"],
           ["Category", "category"],
         ]),
         values: {
           category: "Tools",
           name: "Terraform",
-          title: "Terraform",
         },
       };
-
       expect(result).toEqual(expected);
     });
   });