refactor(docs): internal command signatures (#615)

* refactor: slight readDoc signature change

* chore: remove unnecessary comment

* chore: rename variable

* refactor: return content and data, rather than matter object

Author: kanadgupta

src/lib/pushDoc.ts

@@ -1,5 +1,3 @@
-import crypto from 'crypto';
-
 import chalk from 'chalk';
 import config from 'config';
 import { Headers } from 'node-fetch';
@@ -29,28 +27,27 @@ export default async function pushDoc(
   filepath: string,
   type: CommandCategories
 ) {
-  const { content, matter, slug } = readDoc(filepath);
-  const hash = crypto.createHash('sha1').update(content).digest('hex');
+  const { content, data, hash, slug } = readDoc(filepath);
 
-  let data: {
+  let payload: {
     body?: string;
     html?: string;
     htmlmode?: boolean;
     lastUpdatedHash: string;
-  } = { body: matter.content, ...matter.data, lastUpdatedHash: hash };
+  } = { body: content, ...data, lastUpdatedHash: hash };
 
   if (type === CommandCategories.CUSTOM_PAGES) {
     if (filepath.endsWith('.html')) {
-      data = { html: matter.content, htmlmode: true, ...matter.data, lastUpdatedHash: hash };
+      payload = { html: content, htmlmode: true, ...data, lastUpdatedHash: hash };
     } else {
-      data = { body: matter.content, htmlmode: false, ...matter.data, lastUpdatedHash: hash };
+      payload = { body: content, htmlmode: false, ...data, lastUpdatedHash: hash };
     }
   }
 
   function createDoc() {
     if (dryRun) {
       return `🎭 dry run! This will create '${slug}' with contents from ${filepath} with the following metadata: ${JSON.stringify(
-        matter.data
+        data
       )}`;
     }
 
@@ -65,14 +62,14 @@ export default async function pushDoc(
       ),
       body: JSON.stringify({
         slug,
-        ...data,
+        ...payload,
       }),
     })
       .then(res => handleRes(res))
       .then(res => `🌱 successfully created '${res.slug}' (ID: ${res.id}) with contents from ${filepath}`);
   }
 
-  function updateDoc(existingDoc: typeof data) {
+  function updateDoc(existingDoc: typeof payload) {
     if (hash === existingDoc.lastUpdatedHash) {
       return `${dryRun ? '🎭 dry run! ' : ''}\`${slug}\` ${
         dryRun ? 'will not be' : 'was not'
@@ -81,7 +78,7 @@ export default async function pushDoc(
 
     if (dryRun) {
       return `🎭 dry run! This will update '${slug}' with contents from ${filepath} with the following metadata: ${JSON.stringify(
-        matter.data
+        data
       )}`;
     }
 
@@ -96,7 +93,7 @@ export default async function pushDoc(
       ),
       body: JSON.stringify(
         Object.assign(existingDoc, {
-          ...data,
+          ...payload,
         })
       ),
     })

src/lib/readDoc.ts

@@ -1,15 +1,22 @@
-import type matter from 'gray-matter';
-
+import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
 
 import grayMatter from 'gray-matter';
 
 import { debug } from './logger';
 
-type DocMetadata = {
+type ReadDocMetadata = {
+  /** The contents of the file below the YAML front matter */
   content: string;
-  matter: matter.GrayMatterFile<string>;
+  /** A JSON object with the YAML front matter */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  data: Record<string, any>;
+  /**
+   * A hash of the file contents (including the front matter)
+   */
+  hash: string;
+  /** The page slug */
   slug: string;
 };
 
@@ -18,15 +25,17 @@ type DocMetadata = {
  *
  * @param {String} filepath path to the HTML/Markdown file
  *  (file extension must end in `.html`, `.md`., or `.markdown`)
- * @returns {DocMetadata} an object containing the file's content, matter, and slug
  */
-export default function readDoc(filepath: string): DocMetadata {
+export default function readDoc(filepath: string): ReadDocMetadata {
   debug(`reading file ${filepath}`);
-  const content = fs.readFileSync(filepath, 'utf8');
-  const matter = grayMatter(content);
-  debug(`frontmatter for ${filepath}: ${JSON.stringify(matter)}`);
+  const rawFileContents = fs.readFileSync(filepath, 'utf8');
+  const matter = grayMatter(rawFileContents);
+  const { content, data } = matter;
+  debug(`front matter for ${filepath}: ${JSON.stringify(matter)}`);
 
   // Stripping the subdirectories and markdown extension from the filename and lowercasing to get the default slug.
   const slug = matter.data.slug || path.basename(filepath).replace(path.extname(filepath), '').toLowerCase();
-  return { content, matter, slug };
+
+  const hash = crypto.createHash('sha1').update(rawFileContents).digest('hex');
+  return { content, data, hash, slug };
 }