Refactor package.json and tsconfig.json generation into their own files

Author: hlxid

src/generate/extension.ts

@@ -2,7 +2,7 @@ import CodeBlockWriter from "code-block-writer";
 import { getServiceClientName } from "../nodecgIOVersions";
 import { ProductionInstallation } from "../utils/installation";
 import { CodeLanguage, GenerationOptions } from "./prompt";
-import { write } from "./index";
+import { writeBundleFile } from "./utils";
 
 interface ServiceNames {
     name: string;
@@ -70,7 +70,7 @@ export async function genExtension(opts: GenerationOptions, install: ProductionI
     });
 
     const fileExtension = opts.language === "typescript" ? "ts" : "js";
-    await write(writer.toString(), opts.bundlePath, "extension", `index.${fileExtension}`);
+    await writeBundleFile(writer.toString(), opts.bundlePath, "extension", `index.${fileExtension}`);
 }
 
 function genImport(writer: CodeBlockWriter, symbolToImport: string, packageName: string, lang: CodeLanguage) {

src/generate/index.ts

@@ -1,38 +1,17 @@
 import { CommandModule } from "yargs";
-import * as chalk from "chalk";
-import * as path from "path";
 import * as fs from "fs";
 import { logger } from "../utils/log";
 import { directoryExists } from "../utils/fs";
 import { Installation, ProductionInstallation, readInstallInfo } from "../utils/installation";
 import { corePackages } from "../nodecgIOVersions";
 import { GenerationOptions, promptGenerationOpts } from "./prompt";
-import { getLatestPackageVersion, runNpmBuild, runNpmInstall } from "../utils/npm";
+import { runNpmBuild, runNpmInstall } from "../utils/npm";
 import { genExtension } from "./extension";
-import { findNodeCGDirectory, getNodeCGIODirectory, getNodeCGVersion } from "../utils/nodecgInstallation";
-import { SemVer } from "semver";
-import { genDashboard, genGraphic, genNodeCGDashboardConfig, genNodeCGGraphicConfig } from "./panel";
-
-const defaultTsConfigJson = {
-    compilerOptions: {
-        target: "es2019",
-        sourceMap: true,
-        lib: ["es2019"],
-        alwaysStrict: true,
-        forceConsistentCasingInFileNames: true,
-        noFallthroughCasesInSwitch: true,
-        noImplicitAny: true,
-        noImplicitReturns: true,
-        noImplicitThis: true,
-        strictNullChecks: true,
-        skipLibCheck: true,
-        module: "CommonJS",
-        types: ["node"],
-    },
-};
-
-export const yellowInstallCommand = chalk.yellow("nodecg-io install");
-const yellowGenerateCommand = chalk.yellow("nodecg-io generate");
+import { findNodeCGDirectory, getNodeCGIODirectory } from "../utils/nodecgInstallation";
+import { genDashboard, genGraphic } from "./panel";
+import { genTsConfig } from "./tsConfig";
+import { writeBundleFile, yellowGenerateCommand, yellowInstallCommand } from "./utils";
+import { genPackageJson } from "./packageJson";
 
 export const generateModule: CommandModule = {
     command: "generate",
@@ -123,85 +102,9 @@ export async function generateBundle(
     }
 }
 
-async function genPackageJson(nodecgDir: string, opts: GenerationOptions): Promise<void> {
-    const serviceDeps: [string, string][] = opts.servicePackages.map((pkg) => [pkg.name, addSemverCaret(pkg.version)]);
-
-    const dependencies: [string, string][] = [["nodecg-io-core", addSemverCaret(opts.corePackage.version)]];
-
-    // When we use JS we only need core for requireService etc. and if we TS we also need nodecg, ts, types for node and
-    // each service for typings.
-    if (opts.language === "typescript") {
-        dependencies.push(...serviceDeps);
-
-        logger.debug("Fetching latest typescript and @types/node versions...");
-        const [nodecgVersion, latestNodeTypes, latestTypeScript] = await Promise.all([
-            getNodeCGVersion(nodecgDir),
-            getLatestPackageVersion("@types/node"),
-            getLatestPackageVersion("typescript"),
-        ]);
-
-        dependencies.push(
-            ["nodecg", addSemverCaret(nodecgVersion)],
-            ["@types/node", addSemverCaret(latestNodeTypes)],
-            ["typescript", addSemverCaret(latestTypeScript)],
-        );
-        dependencies.sort();
-    }
-
-    const content = {
-        name: opts.bundleName,
-        version: opts.version.version,
-        private: true,
-        nodecg: {
-            compatibleRange: addSemverCaret("1.4.0"),
-            bundleDependencies: Object.fromEntries(serviceDeps),
-            graphics: genNodeCGGraphicConfig(opts),
-            dashboardPanels: genNodeCGDashboardConfig(opts),
-        },
-        // These scripts are for compiling TS and thus are only needed when generating a TS bundle
-        scripts:
-            opts.language === "typescript"
-                ? {
-                      build: "tsc -b",
-                      watch: "tsc -b -w",
-                      clean: "tsc -b --clean",
-                  }
-                : undefined,
-        dependencies: Object.fromEntries(dependencies),
-    };
-
-    await write(content, opts.bundlePath, "package.json");
-}
-
-function addSemverCaret(version: string | SemVer): string {
-    return `^${version}`;
-}
-
-async function genTsConfig(opts: GenerationOptions): Promise<void> {
-    // Only TS needs its tsconfig.json compiler configuration
-    if (opts.language === "typescript") {
-        await write(defaultTsConfigJson, opts.bundlePath, "tsconfig.json");
-    }
-}
-
 async function genGitIgnore(opts: GenerationOptions): Promise<void> {
     const languageIgnoredFiles = opts.language === "typescript" ? ["/extension/*.js", "/extension/*.js.map"] : [];
     const ignoreEntries = ["/node_modules/", "/.vscode/", "/.idea/", ...languageIgnoredFiles];
     const content = ignoreEntries.join("\n");
-    await write(content, opts.bundlePath, ".gitignore");
-}
-
-export async function write(content: string | Record<string, unknown>, ...paths: string[]): Promise<void> {
-    const finalPath = path.join(...paths);
-
-    logger.debug(`Writing file at ${finalPath}`);
-
-    // Create directory if missing
-    const parent = path.dirname(finalPath);
-    if (!(await directoryExists(parent))) {
-        await fs.promises.mkdir(parent);
-    }
-
-    const str = typeof content === "string" ? content : JSON.stringify(content, null, 4);
-    await fs.promises.writeFile(finalPath, str);
+    await writeBundleFile(content, opts.bundlePath, ".gitignore");
 }

src/generate/packageJson.ts

@@ -0,0 +1,109 @@
+import { GenerationOptions } from "./prompt";
+import { logger } from "../utils/log";
+import { getNodeCGVersion } from "../utils/nodecgInstallation";
+import { getLatestPackageVersion } from "../utils/npm";
+import { genNodeCGDashboardConfig, genNodeCGGraphicConfig } from "./panel";
+import { SemVer } from "semver";
+import { writeBundleFile } from "./utils";
+
+/**
+ * A dependency on a npm package. First field is the package name and the second field is the version.
+ */
+type Dependency = [string, string];
+
+/**
+ * Generates the whole package.json file for the bundle.
+ *
+ * @param nodecgDir the directory in which nodecg is installed
+ * @param opts the options that the user chose for the bundle.
+ */
+export async function genPackageJson(nodecgDir: string, opts: GenerationOptions): Promise<void> {
+    const serviceDeps: Dependency[] = opts.servicePackages.map((pkg) => [pkg.name, addSemverCaret(pkg.version)]);
+
+    const content = {
+        name: opts.bundleName,
+        version: opts.version.version,
+        private: true,
+        nodecg: {
+            compatibleRange: addSemverCaret("1.4.0"),
+            bundleDependencies: Object.fromEntries(serviceDeps),
+            graphics: genNodeCGGraphicConfig(opts),
+            dashboardPanels: genNodeCGDashboardConfig(opts),
+        },
+        // These scripts are for compiling TS and thus are only needed when generating a TS bundle
+        scripts: genScripts(opts),
+        dependencies: Object.fromEntries(await genDependencies(opts, serviceDeps, nodecgDir)),
+    };
+
+    await writeBundleFile(content, opts.bundlePath, "package.json");
+}
+
+/**
+ * Generates the dependency field for a package.json of a bundle.
+ *
+ * @param opts the selected options for bundle generation
+ * @param serviceDeps the dependencies on service packages
+ * @param nodecgDir the directory in which nodecg is installed
+ * @return the dependencies for a bundle with the given options.
+ */
+async function genDependencies(opts: GenerationOptions, serviceDeps: Dependency[], nodecgDir: string) {
+    const core = [opts.corePackage.name, addSemverCaret(opts.corePackage.version)];
+
+    if (opts.language === "typescript") {
+        // For typescript we need core, all services (for typings) and special packages like ts itself or node typings.
+        const deps = [core, ...serviceDeps, ...(await genTypeScriptDependencies(nodecgDir))];
+        deps.sort();
+        return deps;
+    } else {
+        // For JS we only need the core for e.g. the requireService function.
+        return [core];
+    }
+}
+
+/**
+ * Generates all extra dependencies that are needed when having a bundle in TS. Meaning typescript itself, nodecg for typings
+ * and types for node.
+ * @param nodecgDir the directory in which nodecg is installed. Used to get nodecg version which will be used by nodecg dependency.
+ */
+async function genTypeScriptDependencies(nodecgDir: string): Promise<Dependency[]> {
+    logger.debug("Fetching latest typescript and @types/node versions...");
+    const [nodecgVersion, latestNodeTypes, latestTypeScript] = await Promise.all([
+        getNodeCGVersion(nodecgDir),
+        getLatestPackageVersion("@types/node"),
+        getLatestPackageVersion("typescript"),
+    ]);
+
+    return [
+        ["nodecg", addSemverCaret(nodecgVersion)],
+        ["@types/node", addSemverCaret(latestNodeTypes)],
+        ["typescript", addSemverCaret(latestTypeScript)],
+    ];
+}
+
+/**
+ * Generates the script field of the package.json.
+ * Contains build scripts for TypeScript if it was chosen as a bundle language.
+ * Will be empty for JavaScript because it doesn't need to be built.
+ */
+function genScripts(opts: GenerationOptions) {
+    if (opts.language !== "typescript") {
+        return undefined;
+    }
+
+    // Is TypeScript, thus we need the build scripts that invoke tsc
+    return {
+        build: "tsc -b",
+        watch: "tsc -b -w",
+        clean: "tsc -b --clean",
+    };
+}
+
+/**
+ * Adds the semver caret operator to a given version to allow or minor and patch updates by npm.
+ *
+ * @param version the base version
+ * @return the version with the semver caret operator in front.
+ */
+function addSemverCaret(version: string | SemVer): string {
+    return `^${version}`;
+}

src/generate/panel.ts

@@ -1,5 +1,5 @@
 import { GenerationOptions } from "./prompt";
-import { write } from "./index";
+import { writeBundleFile } from "./utils";
 
 type PanelType = "graphic" | "dashboard";
 
@@ -42,13 +42,13 @@ function genPanel(type: PanelType, opts: GenerationOptions): string {
 
 export async function genGraphic(opts: GenerationOptions): Promise<void> {
     if (opts.graphic) {
-        await write(genPanel("graphic", opts), opts.bundlePath, "graphics", graphicFileName);
+        await writeBundleFile(genPanel("graphic", opts), opts.bundlePath, "graphics", graphicFileName);
     }
 }
 
 export async function genDashboard(opts: GenerationOptions): Promise<void> {
     if (opts.dashboard) {
-        await write(genPanel("dashboard", opts), opts.bundlePath, "dashboard", dashboardFile);
+        await writeBundleFile(genPanel("dashboard", opts), opts.bundlePath, "dashboard", dashboardFile);
     }
 }
 

src/generate/prompt.ts

@@ -4,7 +4,7 @@ import * as path from "path";
 import { directoryExists } from "../utils/fs";
 import { ProductionInstallation } from "../utils/installation";
 import { getServicesFromInstall } from "../install/prompt";
-import { yellowInstallCommand } from ".";
+import { yellowInstallCommand } from "./utils";
 import { NpmPackage } from "../utils/npm";
 import { corePackage } from "../nodecgIOVersions";
 
@@ -101,6 +101,8 @@ export async function promptGenerationOpts(
     return computeGenOptsFields(opts, install);
 }
 
+// region prompt validation
+
 function validateBundleName(str: string): true | string {
     if (str.length === 0) {
         return "You must provide a bundle name.";
@@ -136,6 +138,16 @@ function validateServiceSelection(services: string[]): true | string {
     }
 }
 
+// endregion
+
+/**
+ * Converts a {@link PromptedGenerationOptions} to a {@link GenerationOptions} by computing the fields
+ * that {@link GenerationOptions} has using the passed installation.
+ *
+ * @param opts the prompted generation options
+ * @param install the current nodecg-io installation. Used to get installed packages/exact versions.
+ * @return opts including computed fields.
+ */
 export function computeGenOptsFields(
     opts: PromptedGenerationOptions,
     install: ProductionInstallation,

src/generate/tsConfig.ts

@@ -0,0 +1,30 @@
+import { GenerationOptions } from "./prompt";
+import { writeBundleFile } from "./utils";
+
+const defaultTsConfigJson = {
+    compilerOptions: {
+        target: "es2019",
+        sourceMap: true,
+        lib: ["es2019"],
+        alwaysStrict: true,
+        forceConsistentCasingInFileNames: true,
+        noFallthroughCasesInSwitch: true,
+        noImplicitAny: true,
+        noImplicitReturns: true,
+        noImplicitThis: true,
+        strictNullChecks: true,
+        skipLibCheck: true,
+        module: "CommonJS",
+        types: ["node"],
+    },
+};
+
+/**
+ * Generates a tsconfig.json for a bundle if the language was set to typescript.
+ */
+export async function genTsConfig(opts: GenerationOptions): Promise<void> {
+    // Only TS needs its tsconfig.json compiler configuration
+    if (opts.language === "typescript") {
+        await writeBundleFile(defaultTsConfigJson, opts.bundlePath, "tsconfig.json");
+    }
+}

src/generate/utils.ts

@@ -0,0 +1,29 @@
+import * as path from "path";
+import { logger } from "../utils/log";
+import { directoryExists } from "../utils/fs";
+import * as fs from "fs";
+import * as chalk from "chalk";
+
+// Colored commands for logging purposes.
+export const yellowInstallCommand = chalk.yellow("nodecg-io install");
+export const yellowGenerateCommand = chalk.yellow("nodecg-io generate");
+
+/**
+ * Writes a file for a bundle.
+ * @param content the file content. A object will automatically be converted to a string and pretty printed.
+ * @param paths the path to the file. You should probably start with the bundle path and add directories/filenames.
+ */
+export async function writeBundleFile(content: string | Record<string, unknown>, ...paths: string[]): Promise<void> {
+    const finalPath = path.join(...paths);
+
+    logger.debug(`Writing file at ${finalPath}`);
+
+    // Create directory if missing
+    const parent = path.dirname(finalPath);
+    if (!(await directoryExists(parent))) {
+        await fs.promises.mkdir(parent);
+    }
+
+    const str = typeof content === "string" ? content : JSON.stringify(content, null, 4);
+    await fs.promises.writeFile(finalPath, str);
+}