Feat: Add typedoc

Author: ksambhi

.gitignore

@@ -46,4 +46,7 @@ Thumbs.db
 !email/mailmerge-cli/assets/template-workspace/.env
 
 # legacy code that has secrets
-legacy
+legacy
+
+# docs
+docs

README.md

@@ -34,6 +34,16 @@ You should use `build-local` when working on just the TypeScript code
 npx nx run-many -t build
 ```
 
+### Documentation
+
+You can get API documentation for everything in the repo by running:
+
+```
+npm run docs
+```
+
+This will output the documentation to `./docs/` in the repo root.
+
 ### Linting
 
 ```bash

common/util/src/logger.ts

@@ -4,7 +4,12 @@ import winston from "winston";
 const { combine, colorize, printf, timestamp } = winston.format;
 
 /**
- * Create a logger with the given module name
+ * Create a logger with the given module name.
+ *
+ * The logger is an instance of `winston.Logger` with a single `Console` transport, which logs to the console in this format:
+ * ```
+ * 2024-07-31T20:08:14.697Z my-module info Hello, world!
+ * ```
  * @param moduleName Name of the module to log
  * @returns Logger instance
  *
@@ -21,9 +26,9 @@ export default function createLogger(moduleName: string) {
                     colorize(),
                     timestamp(),
                     printf((info) => {
-                        return `${chalk.grey(info["timestamp"])} ${chalk.magenta(moduleName)} ${info.level} ${
-                            info.message
-                        }`;
+                        return `${chalk.grey(info["timestamp"])} ${chalk.magenta(moduleName)} ${
+                            info.level
+                        } ${info.message}`;
                     }),
                 ),
                 level: "debug",

common/util/src/move.ts

@@ -1,6 +1,9 @@
 import fs from "fs/promises";
 import { join, basename } from "path";
 
+/**
+ * Move a file to a directory, maintaing the same name.
+ */
 export const move = (file: string, directory: string) => {
     return fs.rename(file, join(directory, basename(file)));
 };

common/util/typedoc.json

@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.jsonc"
+    ],
+    "entryPoints": [
+        "src/index.ts"
+    ]
+}

email/mailmerge-cli/typedoc.json

@@ -0,0 +1,8 @@
+{
+    "extends": [
+        "../../typedoc.base.jsonc"
+    ],
+    "entryPoints": [
+        "src/index.ts"
+    ]
+}

email/mailmerge/src/engines/types.ts

@@ -3,6 +3,8 @@
  * @packageDocumentation
  */
 import { MappedRecord } from "../util/types";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import NunjucksMarkdownEngine from "./nunjucks-md/index.js";
 
 /**
  * Generic "any" type for template engine options: essentially a dictionary.

email/mailmerge/src/pipelines/generate.ts

@@ -23,7 +23,7 @@ export interface GenerateOptions {
      *
      * Using this you can overridee mappings of attachments from the records with a list of attachments for every email.
      *
-     * This will result in {@link GenerateOptions.mappings.keysForAttachments} being ignored.
+     * This will result in {@link GenerateOptions["mappings"].keysForAttachments} being ignored.
      *
      * As a result, every email will have the same attachments.
      */

email/mailmerge/src/pipelines/loaders/types.ts

@@ -1,4 +1,7 @@
-import { RawRecord } from "../../util";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { DEFAULT_FIELD_NAMES, RawRecord } from "../../util/index.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { CSVBackend } from "./csv.js";
 
 /**
  * Generic way of loading data in to do a data merge on.

email/mailmerge/src/pipelines/storage/sidecar.ts

@@ -17,7 +17,7 @@ import { MappedRecord } from "../../util/index.js";
 import { StorageBackend, MergeResultWithMetadata, MergeResult } from "./types";
 
 /** Metadata the JSON backend passes on {@link MergeResultWithMetadata.storageBackendMetadata} - bsically the original sidecar file with the path it came from */
-interface JSONSidecarsBackendMetadata {
+export interface JSONSidecarsBackendMetadata {
     sideCar: SidecarData & {
         /** Path to the original sidecar file */
         $originalFilepath: string;