Fork and reload for config changes

Author: pjeby

bin/typedoc

@@ -1,5 +1,16 @@
 #!/usr/bin/env node
 //@ts-check
 
-/* eslint-disable @typescript-eslint/no-var-requires */
-import("../dist/lib/cli.js");
+const { fork } = require("child_process");
+
+function main() {
+    fork(__dirname + "/../dist/lib/cli.js", process.argv.slice(2), {
+        stdio: "inherit",
+    }).on("exit", (code) => {
+        // Watch restart required? Fork a new child
+        if (code === 7) main();
+        else process.exit(code || 0);
+    });
+}
+
+main();

site/options/other.md

@@ -18,16 +18,6 @@ configuration files, files imported by `@include`/`@includeCode`, and any
 files explicitly registered by plugins as needing to be watched, as well
 as all your TypeScript source files.
 
-Note, however, that if you are defining your typedoc configuration using an ESM
-module (`.mjs`, or `.js` in a `"type": "module"` project) on Windows, typedoc
-will not be able to reload it when it changes, due to the way node's import
-caching works on Windows. (And if your configuration files import or require
-other modules, those modules won't be reloaded either, regardless of platform!)
-
-In such cases, you'll need to either switch to a .cjs file, manually restart
-the build, or use an external watcher like `onchange` to restart typedoc when
-relevant files change.
-
 ## preserveWatchOutput
 
 ```bash

src/lib/application.ts

@@ -462,11 +462,16 @@ export class Application extends AbstractComponent<
         this._watchFile?.(path, shouldRestart);
     }
 
-    public convertAndWatch(
+    /**
+     * Run a convert / watch process.
+     *
+     * @param success Callback to run after each convert, receiving the project
+     * @returns True if the watch process should be restarted due to a
+     * configuration change, false for an options error
+     */
+    public async convertAndWatch(
         success: (project: ProjectReflection) => Promise<void>,
-        /** Callback to restart watching when options or other critical files change */
-        restartWatch?: () => unknown,
-    ): void {
+    ): Promise<boolean> {
         if (
             !this.options.getValue("preserveWatchOutput") &&
             this.logger instanceof ConsoleLogger
@@ -498,7 +503,7 @@ export class Application extends AbstractComponent<
         // have reported in the first time... just error out for now. I'm not convinced anyone will actually notice.
         if (this.options.getFileNames().length === 0) {
             this.logger.error(this.i18n.solution_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         // Support for packages mode is currently unimplemented
@@ -507,7 +512,7 @@ export class Application extends AbstractComponent<
             this.entryPointStrategy !== EntryPointStrategy.Expand
         ) {
             this.logger.error(this.i18n.strategy_not_supported_in_watch_mode());
-            return;
+            return false;
         }
 
         const tsconfigFile =
@@ -575,16 +580,13 @@ export class Application extends AbstractComponent<
             );
         };
 
+        /** resolver for the returned promise  */
+        let exitWatch: (restart: boolean) => unknown;
         const restartMain = (file: string) => {
             if (restarting) return;
-            if (!restartWatch)
-                this.logger.warn(
-                    this.i18n.file_0_changed_but_cant_restart(nicePath(file)),
-                );
-            else
-                this.logger.info(
-                    this.i18n.file_0_changed_restarting(nicePath(file)),
-                );
+            this.logger.info(
+                this.i18n.file_0_changed_restarting(nicePath(file)),
+            );
             restarting = true;
             currentProgram = undefined;
             this.clearWatches();
@@ -594,7 +596,7 @@ export class Application extends AbstractComponent<
         const runSuccess = () => {
             if (restarting && successFinished) {
                 successFinished = false;
-                if (restartWatch) restartWatch();
+                exitWatch(true);
                 return;
             }
 
@@ -673,6 +675,11 @@ export class Application extends AbstractComponent<
         };
 
         const tsWatcher = ts.createWatchProgram(host);
+
+        // Don't return to caller until the watch needs to restart
+        return await new Promise((res) => {
+            exitWatch = res;
+        });
     }
 
     validate(project: ProjectReflection) {

src/lib/cli.ts

@@ -32,8 +32,8 @@ async function main() {
         if (exitCode !== ExitCodes.Watching) {
             app.logger.verbose(`Full run took ${Date.now() - start}ms`);
             logRunSummary(app.logger);
-            process.exit(exitCode);
         }
+        process.exit(exitCode);
     } catch (error) {
         console.error("TypeDoc exiting with unexpected error:");
         console.error(error);
@@ -73,11 +73,12 @@ async function run(app: td.Application) {
     }
 
     if (app.options.getValue("watch")) {
-        app.convertAndWatch(async (project) => {
+        return (await app.convertAndWatch(async (project) => {
             app.validate(project);
             await app.generateOutputs(project);
-        }, main);
-        return ExitCodes.Watching;
+        }))
+            ? ExitCodes.Watching
+            : ExitCodes.OptionError;
     }
 
     const project = await app.convert();

src/lib/internationalization/locales/en.cts

@@ -15,8 +15,6 @@ export = {
         "The provided tsconfig file looks like a solution style tsconfig, which is not supported in watch mode",
     strategy_not_supported_in_watch_mode:
         "entryPointStrategy must be set to either resolve or expand for watch mode",
-    file_0_changed_but_cant_restart:
-        "File {0} changed but no restart callback was given; please restart manually",
     file_0_changed_restarting:
         "Configuration file {0} changed: full restart required...",
     file_0_changed_rebuilding: "File {0} changed: rebuilding output...",

src/lib/utils/options/readers/typedoc.ts

@@ -12,8 +12,6 @@ import { createRequire } from "module";
 import { pathToFileURL } from "url";
 import type { TranslatedString } from "../../../internationalization/internationalization.js";
 
-const require = createRequire(import.meta.url);
-
 /**
  * Obtains option values from typedoc.json
  */
@@ -90,25 +88,10 @@ export class TypeDocReader implements OptionsReader {
             }
         } else {
             try {
-                if (process.platform === "win32") {
-                    // Node on Windows doesn't support the `?` trick for
-                    // cache-busting, so try using require()
-                    delete require.cache[require.resolve(file)];
-                    try {
-                        const mod = require(file);
-                        fileContent = mod.default ?? mod;
-                    } catch (error: any) {
-                        // Only recent node can require an ESM
-                        if (error?.code !== "ERR_REQUIRE_ESM") throw error;
-                    }
-                }
-                if (!fileContent) {
-                    const esmPath = pathToFileURL(file).toString();
-                    // Cache-bust for reload on watch
-                    fileContent = await (
-                        await import(`${esmPath}?${Date.now()}`)
-                    ).default;
-                }
+                // On Windows, we need to ensure this path is a file path.
+                // Or we'll get ERR_UNSUPPORTED_ESM_URL_SCHEME
+                const esmPath = pathToFileURL(file).toString();
+                fileContent = await (await import(esmPath)).default;
             } catch (error) {
                 logger.error(
                     logger.i18n.failed_read_options_file_0(nicePath(file)),