Add compiler typings

Author: ooflorent

declarations/WebpackOptions.d.ts

@@ -396,26 +396,7 @@ export interface WebpackOptions {
 	/**
 	 * Options for the watcher
 	 */
-	watchOptions?: {
-		/**
-		 * Delay the rebuilt after the first change. Value is a time in ms.
-		 */
-		aggregateTimeout?: number;
-		/**
-		 * Ignore some files from watching
-		 */
-		ignored?: {
-			[k: string]: any;
-		};
-		/**
-		 * Enable polling mode for watching
-		 */
-		poll?: boolean | number;
-		/**
-		 * Stop watching when stdin stream has ended
-		 */
-		stdin?: boolean;
-	};
+	watchOptions?: WatchOptions;
 }
 /**
  * This interface was referenced by `WebpackOptions`'s JSON-Schema
@@ -1421,3 +1402,27 @@ export interface StatsOptions {
 	 */
 	warningsFilter?: FilterTypes;
 }
+/**
+ * This interface was referenced by `WebpackOptions`'s JSON-Schema
+ * via the `definition` "WatchOptions".
+ */
+export interface WatchOptions {
+	/**
+	 * Delay the rebuilt after the first change. Value is a time in ms.
+	 */
+	aggregateTimeout?: number;
+	/**
+	 * Ignore some files from watching
+	 */
+	ignored?: {
+		[k: string]: any;
+	};
+	/**
+	 * Enable polling mode for watching
+	 */
+	poll?: boolean | number;
+	/**
+	 * Stop watching when stdin stream has ended
+	 */
+	stdin?: boolean;
+}

lib/Compilation.js

@@ -68,13 +68,32 @@ const { arrayToSetDeprecation } = require("./util/deprecation");
 /** @typedef {import("./dependencies/EntryDependency")} EntryDependency */
 /** @typedef {import("./util/createHash").Hash} Hash */
 
-// TODO use @callback
-/** @typedef {{[assetName: string]: Source}} CompilationAssets */
-/** @typedef {(err?: WebpackError|null, result?: Module) => void } ModuleCallback */
-/** @typedef {(err?: Error|null) => void} Callback */
-/** @typedef {(d: Dependency) => any} DepBlockVarDependenciesCallback */
+/**
+ * @callback Callback
+ * @param {WebpackError=} err
+ * @returns {void}
+ */
+
+/**
+ * @callback ModuleCallback
+ * @param {WebpackError=} err
+ * @param {Module=} result
+ * @returns {void}
+ */
+
+/**
+ * @callback DepBlockVarDependenciesCallback
+ * @param {Dependency} dependency
+ * @returns {any}
+ */
+
+/**
+ * @typedef {Object} Plugin
+ * @property {() => void} apply
+ */
+
 /** @typedef {new (...args: any[]) => Dependency} DepConstructor */
-/** @typedef {{apply: () => void}} Plugin */
+/** @typedef {Record<string, Source>} CompilationAssets */
 
 /**
  * @typedef {Object} ModuleFactoryCreateDataContextInfo
@@ -536,12 +555,6 @@ class Compilation {
 		return new Stats(this);
 	}
 
-	/**
-	 * @typedef {Object} AddModuleResult
-	 * @property {Module} module the added or existing module
-	 * @property {boolean} issuer was this the first request for this module
-	 */
-
 	/**
 	 * @param {Module} module module to be added that was created
 	 * @param {ModuleCallback} callback returns the module in the compilation,
@@ -631,7 +644,7 @@ class Compilation {
 	 *
 	 * @param {Module} module module to be built
 	 * @param {ModuleCallback} callback the callback
-	 * @returns {TODO} returns the callback function with results
+	 * @returns {void}
 	 */
 	_buildModule(module, callback) {
 		const currentProfile = this.profile
@@ -1116,7 +1129,7 @@ class Compilation {
 	}
 
 	/**
-	 * @param {Callback} callback signals when the seal method is finishes
+	 * @param {Callback} callback signals when the call finishes
 	 * @returns {void}
 	 */
 	seal(callback) {
@@ -2294,6 +2307,10 @@ class Compilation {
 		}
 	}
 
+	/**
+	 * @param {Callback} callback signals when the call finishes
+	 * @returns {void}
+	 */
 	createChunkAssets(callback) {
 		const outputOptions = this.outputOptions;
 		const cachedSourceMap = new WeakMap();

lib/Compiler.js

@@ -28,8 +28,13 @@ const Watching = require("./Watching");
 const { makePathsRelative } = require("./util/identifier");
 
 /** @typedef {import("../declarations/WebpackOptions").Entry} Entry */
+/** @typedef {import("../declarations/WebpackOptions").OutputOptions} OutputOptions */
+/** @typedef {import("../declarations/WebpackOptions").WatchOptions} WatchOptions */
 /** @typedef {import("../declarations/WebpackOptions").WebpackOptions} WebpackOptions */
+/** @typedef {import("../declarations/WebpackOptions").WebpackPluginInstance} WebpackPluginInstance */
+/** @typedef {import("./Chunk")} Chunk */
 /** @typedef {import("./FileSystemInfo").FileSystemInfoEntry} FileSystemInfoEntry */
+/** @typedef {import("./Stats")} Stats */
 
 /**
  * @typedef {Object} CompilationParams
@@ -38,7 +43,24 @@ const { makePathsRelative } = require("./util/identifier");
  * @property {Set<string>} compilationDependencies
  */
 
+/**
+ * @template T
+ * @callback Callback
+ * @param {Error=} err
+ * @param {T=} result
+ */
+
+/**
+ * @callback RunAsChildCallback
+ * @param {Error=} err
+ * @param {Chunk[]=} entries
+ * @param {Compilation=} compilation
+ */
+
 class Compiler {
+	/**
+	 * @param {string} context the compilation path
+	 */
 	constructor(context) {
 		this.hooks = Object.freeze({
 			/** @type {SyncBailHook<Compilation>} */
@@ -142,16 +164,29 @@ class Compiler {
 		this.watchMode = false;
 	}
 
+	/**
+	 * @param {WatchOptions} watchOptions the watcher's options
+	 * @param {Callback<Stats>} handler signals when the call finishes
+	 * @returns {Watching} a compiler watcher
+	 */
 	watch(watchOptions, handler) {
-		if (this.running) return handler(new ConcurrentCompilationError());
+		if (this.running) {
+			return handler(new ConcurrentCompilationError());
+		}
 
 		this.running = true;
 		this.watchMode = true;
 		return new Watching(this, watchOptions, handler);
 	}
 
+	/**
+	 * @param {Callback<Stats>} callback signals when the call finishes
+	 * @returns {void}
+	 */
 	run(callback) {
-		if (this.running) return callback(new ConcurrentCompilationError());
+		if (this.running) {
+			return callback(new ConcurrentCompilationError());
+		}
 
 		const finalCallback = (err, stats) => {
 			this.cache.beginIdle();
@@ -231,6 +266,10 @@ class Compiler {
 		});
 	}
 
+	/**
+	 * @param {RunAsChildCallback} callback signals when the call finishes
+	 * @returns {void}
+	 */
 	runAsChild(callback) {
 		this.compile((err, compilation) => {
 			if (err) return callback(err);
@@ -257,6 +296,11 @@ class Compiler {
 		}
 	}
 
+	/**
+	 * @param {Compilation} compilation the compilation
+	 * @param {Callback<void>} callback signals when the assets are emitted
+	 * @returns {void}
+	 */
 	emitAssets(compilation, callback) {
 		let outputPath;
 
@@ -322,6 +366,10 @@ class Compiler {
 		});
 	}
 
+	/**
+	 * @param {Callback<void>} callback signals when the call finishes
+	 * @returns {void}
+	 */
 	emitRecords(callback) {
 		if (!this.recordsOutputPath) return callback();
 		const idx1 = this.recordsOutputPath.lastIndexOf("/");
@@ -350,6 +398,10 @@ class Compiler {
 		});
 	}
 
+	/**
+	 * @param {Callback<void>} callback signals when the call finishes
+	 * @returns {void}
+	 */
 	readRecords(callback) {
 		if (!this.recordsInputPath) {
 			this.records = {};
@@ -375,6 +427,14 @@ class Compiler {
 		});
 	}
 
+	/**
+	 * @param {Compilation} compilation the compilation
+	 * @param {string} compilerName the compiler's name
+	 * @param {number} compilerIndex the compiler's index
+	 * @param {OutputOptions} outputOptions the output options
+	 * @param {WebpackPluginInstance[]} plugins the plugins to apply
+	 * @returns {Compiler} a child compiler
+	 */
 	createChildCompiler(
 		compilation,
 		compilerName,
@@ -454,6 +514,10 @@ class Compiler {
 		return new Compilation(this);
 	}
 
+	/**
+	 * @param {CompilationParams} params the compilation parameters
+	 * @returns {Compilation} the created compilation
+	 */
 	newCompilation(params) {
 		const compilation = this.createCompilation();
 		compilation.name = this.name;
@@ -489,6 +553,10 @@ class Compiler {
 		return params;
 	}
 
+	/**
+	 * @param {Callback<Compilation>} callback signals when the compilation finishes
+	 * @returns {void}
+	 */
 	compile(callback) {
 		const params = this.newCompilationParams();
 		this.hooks.beforeCompile.callAsync(params, err => {
@@ -516,6 +584,10 @@ class Compiler {
 		});
 	}
 
+	/**
+	 * @param {Callback<void>} callback signals when the compiler closes
+	 * @returns {void}
+	 */
 	close(callback) {
 		this.cache.shutdown(callback);
 	}