refactor note processing functions

app/notes/[slug]/opengraph-image.tsx

@@ -3,7 +3,7 @@ import { notFound } from "next/navigation";
 import { join } from "path";
 import { existsSync } from "fs";
 import { readFile } from "fs/promises";
-import { getPostSlugs, getFrontMatter } from "../../../lib/helpers/posts";
+import { getSlugs, getFrontMatter } from "../../../lib/helpers/posts";
 import { POSTS_DIR, AVATAR_PATH } from "../../../lib/config/constants";
 
 export const contentType = "image/png";
@@ -18,7 +18,7 @@ export const dynamic = "force-static";
 export const dynamicParams = false;
 
 export const generateStaticParams = async () => {
-  const slugs = await getPostSlugs();
+  const slugs = await getSlugs();
 
   // map slugs into a static paths object required by next.js
   return slugs.map((slug) => ({

app/notes/[slug]/page.tsx

@@ -7,7 +7,7 @@ import Time from "../../../components/Time";
 import Comments from "../../../components/Comments";
 import Loading from "../../../components/Loading";
 import HitCounter from "./counter";
-import { getPostSlugs, getFrontMatter } from "../../../lib/helpers/posts";
+import { getSlugs, getFrontMatter } from "../../../lib/helpers/posts";
 import { addMetadata } from "../../../lib/helpers/metadata";
 import * as config from "../../../lib/config";
 import { BASE_URL } from "../../../lib/config/constants";
@@ -24,7 +24,7 @@ export const dynamicParams = false;
 export const experimental_ppr = true;
 
 export const generateStaticParams = async () => {
-  const slugs = await getPostSlugs();
+  const slugs = await getSlugs();
 
   // map slugs into a static paths object required by next.js
   return slugs.map((slug) => ({

app/notes/page.tsx

@@ -1,6 +1,6 @@
 import Link from "../../components/Link";
 import Time from "../../components/Time";
-import { getAllPosts } from "../../lib/helpers/posts";
+import { getFrontMatter } from "../../lib/helpers/posts";
 import { addMetadata } from "../../lib/helpers/metadata";
 import * as config from "../../lib/config";
 import type { ReactElement } from "react";
@@ -19,7 +19,7 @@ export const metadata = addMetadata({
 
 const Page = async () => {
   // parse the year of each note and group them together
-  const notes = await getAllPosts();
+  const notes = await getFrontMatter();
   const notesByYear: {
     [year: string]: FrontMatter[];
   } = {};

app/sitemap.ts

@@ -1,6 +1,6 @@
 import path from "path";
 import glob from "fast-glob";
-import { getAllPosts } from "../lib/helpers/posts";
+import { getFrontMatter } from "../lib/helpers/posts";
 import { BASE_URL } from "../lib/config/constants";
 import type { MetadataRoute } from "next";
 
@@ -36,7 +36,7 @@ const sitemap = async (): Promise<MetadataRoute.Sitemap> => {
     });
   });
 
-  (await getAllPosts()).forEach((post) => {
+  (await getFrontMatter()).forEach((post) => {
     routes.push({
       url: post.permalink,
       // pull lastModified from front matter date

lib/helpers/build-feed.ts

@@ -1,13 +1,16 @@
 import { cache } from "react";
 import { Feed } from "feed";
-import { getAllPosts, getPostContent } from "./posts";
+import { getFrontMatter, getContent } from "./posts";
 import * as config from "../config";
 import { BASE_URL } from "../config/constants";
 
 import ogImage from "../../app/opengraph-image.jpg";
 
+/**
+ * Returns a `Feed` object, which can then be processed with `feed.rss2()`, `feed.atom1()`, or `feed.json1()`.
+ * @see https://github.com/jpmonette/feed#example
+ */
 export const buildFeed = cache(async (): Promise<Feed> => {
-  // https://github.com/jpmonette/feed#example
   const feed = new Feed({
     id: BASE_URL,
     link: BASE_URL,
@@ -28,8 +31,8 @@ export const buildFeed = cache(async (): Promise<Feed> => {
   });
 
   // add posts separately using their frontmatter
-  const posts = await getAllPosts();
-  for (const post of posts.reverse()) {
+  const posts = await getFrontMatter();
+  for (const post of posts) {
     feed.addItem({
       guid: post.permalink,
       link: post.permalink,
@@ -42,7 +45,10 @@ export const buildFeed = cache(async (): Promise<Feed> => {
         },
       ],
       date: new Date(post.date),
-      content: `${await getPostContent(post.slug)}\n\n<p><a href="${post.permalink}"><strong>Continue reading...</strong></a></p>`,
+      content: `
+        ${await getContent(post.slug)}
+        <p><a href="${post.permalink}"><strong>Continue reading...</strong></a></p>
+      `.trim(),
     });
   }
 

lib/helpers/metadata.ts

@@ -1,7 +1,10 @@
 import defaultMetadata from "../config/metadata";
 import type { Metadata } from "next";
 
-// helper function to deep merge a page's metadata into the default site metadata
+/**
+ * Helper function to deep merge a page's metadata into the default site metadata
+ * @see https://nextjs.org/docs/app/api-reference/functions/generate-metadata
+ */
 export const addMetadata = (metadata: Metadata): Metadata => {
   return {
     ...defaultMetadata,

lib/helpers/posts.ts

@@ -19,8 +19,34 @@ export type FrontMatter = {
   noComments?: boolean;
 };
 
-// returns front matter and the **raw & uncompiled** markdown of a given slug
-export const getFrontMatter = cache(async (slug: string): Promise<FrontMatter | undefined> => {
+/** Use filesystem to get a simple list of all post slugs */
+export const getSlugs = cache(async (): Promise<string[]> => {
+  // list all .mdx files in POSTS_DIR
+  const mdxFiles = await glob("*/index.mdx", {
+    cwd: path.join(process.cwd(), POSTS_DIR),
+    dot: false,
+  });
+
+  // strip the .mdx extensions from filenames
+  const slugs = mdxFiles.map((fileName) => fileName.replace(/\/index\.mdx$/, ""));
+
+  return slugs;
+});
+
+// overloaded to return either the front matter of a single post or ALL posts
+export const getFrontMatter: {
+  /**
+   * Parses and returns the front matter of ALL posts, sorted reverse chronologically
+   */
+  (): Promise<FrontMatter[]>;
+  /**
+   * Parses and returns the front matter of a given slug, or undefined if the slug does not exist
+   */
+  (slug: string): Promise<FrontMatter | undefined>;
+} = cache(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async (slug?: any): Promise<any> => {
+    if (typeof slug === "string") {
       try {
         const { frontmatter } = await import(`../../${POSTS_DIR}/${slug}/index.mdx`);
 
@@ -48,33 +74,35 @@ export const getFrontMatter = cache(async (slug: string): Promise<FrontMatter |
           // stylized title with limited html tags:
           htmlTitle,
           slug,
-      date: new Date(frontmatter.date).toISOString(), // validate/normalize the date string provided from front matter
+          // validate/normalize the date string provided from front matter
+          date: new Date(frontmatter.date).toISOString(),
           permalink: `${BASE_URL}/${POSTS_DIR}/${slug}`,
-    };
+        } as FrontMatter;
       } catch (error) {
         console.error(`Failed to load front matter for post with slug "${slug}":`, error);
         return undefined;
       }
-});
+    }
 
-// use filesystem to get a simple list of all post slugs
-export const getPostSlugs = cache(async (): Promise<string[]> => {
-  // list all .mdx files in POSTS_DIR
-  const mdxFiles = await glob("*/index.mdx", {
-    cwd: path.join(process.cwd(), POSTS_DIR),
-    dot: false,
-  });
+    if (!slug) {
+      // concurrently fetch the front matter of each post
+      const slugs = await getSlugs();
+      const posts = await Promise.all(slugs.map(getFrontMatter));
 
-  // strip the .mdx extensions from filenames
-  const slugs = mdxFiles.map((fileName) => fileName.replace(/\/index\.mdx$/, ""));
+      // sort the results reverse chronologically and return
+      return posts.sort(
+        (post1, post2) => new Date(post2!.date).getTime() - new Date(post1!.date).getTime()
+      ) as FrontMatter[];
+    }
 
-  return slugs;
-});
+    throw new Error(`getFrontMatter() called with invalid argument.`);
+  }
+);
 
-// returns the content of a post with very limited processing to include in RSS feeds
-// TODO: also remove MDX-related syntax (e.g. import/export statements)
-export const getPostContent = cache(async (slug: string): Promise<string | undefined> => {
+/** Returns the content of a post with very limited processing to include in RSS feeds */
+export const getContent = cache(async (slug: string): Promise<string | undefined> => {
   try {
+    // TODO: also remove MDX-related syntax (e.g. import/export statements)
     const content = await unified()
       .use(remarkParse)
       .use(remarkFrontmatter)
@@ -104,20 +132,10 @@ export const getPostContent = cache(async (slug: string): Promise<string | undef
       })
       .process(await read(path.resolve(process.cwd(), `${POSTS_DIR}/${slug}/index.mdx`)));
 
-    // convert the parsed content to a string
-    return content.toString().trim();
+    // convert the parsed content to a string with "safe" HTML
+    return content.toString().replaceAll("<p></p>", "").trim();
   } catch (error) {
     console.error(`Failed to load/parse content for post with slug "${slug}":`, error);
     return undefined;
   }
 });
-
-// returns the parsed front matter of ALL posts, sorted reverse chronologically
-export const getAllPosts = cache(async (): Promise<FrontMatter[]> => {
-  // concurrently fetch the front matter of each post
-  const slugs = await getPostSlugs();
-  const posts = (await Promise.all(slugs.map(getFrontMatter))) as FrontMatter[];
-
-  // sort the results reverse chronologically and return
-  return posts.sort((post1, post2) => new Date(post1.date).getTime() - new Date(post2.date).getTime());
-});