Allow hooks for watch events

Search Terms

• hooks
• events
• watch

Suggestion

Allow a ts file to react to actions performed by tsc while it is running in --watch mode. This can be done by having that file export specific members of specific known types that tsc will execute at the appropriate time.

Use Cases

I would like to automatically regenerate an index.ts file before letting tsc proceed with its normal compilation that would include the now altered index.ts.

In one of my projects, I would also want to restart a server after compilation. Others may want to do other build related tasks, such as re-running a subset of tests after build for example.

Examples

Given a command line
tsc --build --watch --watchHook ./watcher.ts

and the following watcher.ts file:

/*
 "tsc-watch" is a tentative name for a lib that would define the "TS*"
 types used below.
 */
/// <reference lib="tsc-watch" />

interface TSChangeSet {
  [key: string]: {
    files: string[];
    buildInfo: TSBuildInfo;
  };
}

const hooks: TSWatcherHooks = {
  /**
   * Executes before an initial build.
   *
   * This should also be executed once for each referenced project.
   *
   * @param tsconfigPath An absolute path to the tsconfig being built.
   *     This is most useful to distinguish between projects in references.
   * @param buildInfo undefined if there was no prior buildInfo file.
   *     Else, it's an object representation of its contents before compilation.
   *
   * @return If the returned value is a promise, it will be awaited before
   *     proceeding. If it is anything else, tsc will resume immediately.
   *     If the promise is rejected or this handler throws, the compilation
   *     should be considered to have failed.
   */
  onBeforeBuild: (
    tsconfigPath: string,
    buildInfo?: TSBuildInfo
  ): unknown | Promise<unknown> => {
    return;
  },
  /**
   * Executes after an initial build.
   *
   * This should also be executed once for each referenced project.
   *
   * @param tsconfigPath An absolute path to the tsconfig being built.
   *     This is most useful to distinguish between projects in references.
   * @param buildInfo undefined if not an incremental build.
   *     Else, it's an object representation of its contents after compilation.
   *
   * @return If the returned value is a promise, it will be awaited before
   *     proceeding. If it is anything else, tsc will resume immediately.
   *     If the promise is rejected or this handler throws, tsc should exit
   *     with an error code.
   */
  onAfterBuild: (
    tsconfigPath: string,
    buildInfo?: TSBuildInfo
  ): unknown | Promise<unknown> => {
    return;
  },
  /**
   * Executes before a rebuild.
   *
   * This should be executed once regardless of whether the change is in just
   * one project or multiple.
   *
   * If there are additional changes after this handler (e.g. a file is
   * edited as a result of this call), then compilation should NOT proceed,
   * and yet this handler should be executed a second time with the newly
   * changed files.
   *
   * @param changedFiles A set of objects changed since last build.
   *     Each key in the set is a path to a tsconfig file.
   *     Each value is an object with the build info as one member,
   *     and an array of changed files as the other.
   *
   * @return If the returned value is a promise, it will be awaited before
   *     proceeding. If it is anything else, tsc will resume immediately.
   *     If the promise is rejected or this handler throws, the recompilation
   *     should be considered to have failed.
   */
  onBeforeRebuild: (changedFiles: TSChangeSet): unknown | Promise<unknown> => {
    // Do stuff before recompilation, e.g. (re)generate index files
    return;
  },
  /**
   * Executes after a rebuild.
   *
   * This should be executed once regardless of whether the change is in just
   * one project or multiple.
   *
   * @param changedFiles A set of objects changed since last build.
   *     Each key in the set is a path to a tsconfig file.
   *     Each value is an object with the build info as one member,
   *     and an array of changed files as the other.
   *
   *     All changes from before handlers are also merged into this set.
   *
   * @return If the returned value is a promise, it will be awaited before
   *     proceeding. If it is anything else, tsc will resume immediately.
   *     If the promise is rejected or this handler throws, tsc should exit
   *     with an error code.
   */
  onAfterRebuild: (changedFiles: TSChangeSet): unknown | Promise<unknown> => {
    // Do stuff after recompilation, e.g. run test subset, restart app, etc.
    return;
  }
};
export default hooks;

I would like tsc to behave as described in the watcher.ts file. As with most TS settings, there should be an analog in the tsconfig.json file, where the path to the hooks file is relative to the tsconfig.json file.

Currently, in order to do these sorts of things, one has to use a separate builder like gulp, which is somewhat complex to use for projects that use project references.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start at the tsc --build --watch entry point and trace the project-reference watch flow. Review the proposed watcher.ts hooks and the analogous tsconfig.json setting, then verify that before/after build and rebuild handlers, including async failures and changed-file reporting, behave as described.