Allow hooks for watch events

[boenrobot]

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:

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

[orta]

Relates to https://github.com/microsoft/TypeScript/issues/16607

[sdrsdr]

This is something very important to me also. Being able to "hook" code to different life cycle events of the typescript compiler especially in watch mode will make the compiler much-much flexible tool. I fancy a "pre-compile", "post-compile" hooks probably "change-detected" hook. In pre-compile I might opt to "git pull" some submodules, and in "post-compile" I might copy some additional files around .. all this out of the compiler scope but totally in-scope for my build/test/deploy cycles. To make everything efficient a "plugins" should be "loaded" in the tsc node runtime as compilation in watch mode will have huge penalties starting new external nodejs env just to run some simple tasks .. also waiting for this tasks to finish will be too much work compared to await-ing a call to "plugin" exported function. The perceived slowdown of the build process is something I'm willing to pay for the immense convenience this will bring to my workflow

[sdrsdr]

Also as for "who will use this feature": take a look at tsc-watch a tool that solves the discussed problem with nearly 200K weekly downloads. And only god knows how many people a efficiently solving the problem with other tools. Think of the miens popularity of Maven and its plugins