refactor: types more

declarations/WebpackOptions.d.ts

@@ -184,7 +184,7 @@ export type ExternalItem =
 	| (
 			| ((
 					data: ExternalItemFunctionData,
-					callback: (err?: Error, result?: ExternalItemValue) => void
+					callback: (err?: Error | null, result?: ExternalItemValue) => void
 			  ) => void)
 			| ((data: ExternalItemFunctionData) => Promise<ExternalItemValue>)
 	  );

lib/BannerPlugin.js

@@ -11,6 +11,7 @@ const ModuleFilenameHelpers = require("./ModuleFilenameHelpers");
 const Template = require("./Template");
 const createSchemaValidation = require("./util/create-schema-validation");
 
+/** @typedef {import("../declarations/plugins/BannerPlugin").BannerFunction} BannerFunction */
 /** @typedef {import("../declarations/plugins/BannerPlugin").BannerPluginArgument} BannerPluginArgument */
 /** @typedef {import("../declarations/plugins/BannerPlugin").BannerPluginOptions} BannerPluginOptions */
 /** @typedef {import("./Compiler")} Compiler */
@@ -60,7 +61,7 @@ class BannerPlugin {
 			const getBanner = bannerOption;
 			this.banner = this.options.raw
 				? getBanner
-				: data => wrapComment(getBanner(data));
+				: /** @type {BannerFunction} */ data => wrapComment(getBanner(data));
 		} else {
 			const banner = this.options.raw
 				? bannerOption

lib/Compiler.js

@@ -208,7 +208,7 @@ class Compiler {
 		this.root = this;
 		/** @type {string} */
 		this.outputPath = "";
-		/** @type {Watching} */
+		/** @type {Watching | undefined} */
 		this.watching = undefined;
 
 		/** @type {OutputFileSystem} */
@@ -230,15 +230,15 @@ class Compiler {
 		/** @type {Set<string | RegExp>} */
 		this.immutablePaths = new Set();
 
-		/** @type {ReadonlySet<string>} */
+		/** @type {ReadonlySet<string> | undefined} */
 		this.modifiedFiles = undefined;
-		/** @type {ReadonlySet<string>} */
+		/** @type {ReadonlySet<string> | undefined} */
 		this.removedFiles = undefined;
-		/** @type {ReadonlyMap<string, FileSystemInfoEntry | "ignore" | null>} */
+		/** @type {ReadonlyMap<string, FileSystemInfoEntry | "ignore" | null> | undefined} */
 		this.fileTimestamps = undefined;
-		/** @type {ReadonlyMap<string, FileSystemInfoEntry | "ignore" | null>} */
+		/** @type {ReadonlyMap<string, FileSystemInfoEntry | "ignore" | null> | undefined} */
 		this.contextTimestamps = undefined;
-		/** @type {number} */
+		/** @type {number | undefined} */
 		this.fsStartTime = undefined;
 
 		/** @type {ResolverFactory} */

lib/ConstPlugin.js

@@ -15,7 +15,10 @@ const ConstDependency = require("./dependencies/ConstDependency");
 const { evaluateToString } = require("./javascript/JavascriptParserHelpers");
 const { parseResource } = require("./util/identifier");
 
+/** @typedef {import("estree").AssignmentProperty} AssignmentProperty */
 /** @typedef {import("estree").Expression} Expression */
+/** @typedef {import("estree").Identifier} Identifier */
+/** @typedef {import("estree").Pattern} Pattern */
 /** @typedef {import("estree").SourceLocation} SourceLocation */
 /** @typedef {import("estree").Statement} Statement */
 /** @typedef {import("estree").Super} Super */
@@ -24,10 +27,14 @@ const { parseResource } = require("./util/identifier");
 /** @typedef {import("./javascript/JavascriptParser")} JavascriptParser */
 /** @typedef {import("./javascript/JavascriptParser").Range} Range */
 
+/**
+ * @param {Set<string>} declarations set of declarations
+ * @param {Identifier | Pattern} pattern pattern to collect declarations from
+ */
 const collectDeclaration = (declarations, pattern) => {
 	const stack = [pattern];
 	while (stack.length > 0) {
-		const node = stack.pop();
+		const node = /** @type {Pattern} */ (stack.pop());
 		switch (node.type) {
 			case "Identifier":
 				declarations.add(node.name);
@@ -44,7 +51,7 @@ const collectDeclaration = (declarations, pattern) => {
 				break;
 			case "ObjectPattern":
 				for (const property of node.properties) {
-					stack.push(property.value);
+					stack.push(/** @type {AssignmentProperty} */ (property).value);
 				}
 				break;
 			case "RestElement":
@@ -54,8 +61,14 @@ const collectDeclaration = (declarations, pattern) => {
 	}
 };
 
+/**
+ * @param {Statement} branch branch to get hoisted declarations from
+ * @param {boolean} includeFunctionDeclarations whether to include function declarations
+ * @returns {Array<string>} hoisted declarations
+ */
 const getHoistedDeclarations = (branch, includeFunctionDeclarations) => {
 	const declarations = new Set();
+	/** @type {Array<TODO | null | undefined>} */
 	const stack = [branch];
 	while (stack.length > 0) {
 		const node = stack.pop();
@@ -103,7 +116,7 @@ const getHoistedDeclarations = (branch, includeFunctionDeclarations) => {
 				break;
 			case "FunctionDeclaration":
 				if (includeFunctionDeclarations) {
-					collectDeclaration(declarations, node.id);
+					collectDeclaration(declarations, /** @type {Identifier} */ (node.id));
 				}
 				break;
 			case "VariableDeclaration":

lib/DependencyTemplates.js

@@ -27,7 +27,7 @@ class DependencyTemplates {
 
 	/**
 	 * @param {DependencyConstructor} dependency Constructor of Dependency
-	 * @returns {DependencyTemplate} template for this dependency
+	 * @returns {DependencyTemplate | undefined} template for this dependency
 	 */
 	get(dependency) {
 		return this._map.get(dependency);

lib/ExportsInfo.js

@@ -1364,7 +1364,11 @@ class ExportInfo {
 			if (t === null) return undefined;
 			if (t.module !== target.module) return undefined;
 			if (!t.export !== !target.export) return undefined;
-			if (target.export && !equals(t.export, target.export)) return undefined;
+			if (
+				target.export &&
+				!equals(/** @type {ArrayLike<string>} */ (t.export), target.export)
+			)
+				return undefined;
 			result = values.next();
 		}
 		return target;

lib/FileSystemInfo.js

@@ -99,8 +99,8 @@ const INVALID = Symbol("invalid");
  * @typedef {Object} SnapshotOptimizationEntry
  * @property {Snapshot} snapshot
  * @property {number} shared
- * @property {Set<string>} snapshotContent
- * @property {Set<SnapshotOptimizationEntry>} children
+ * @property {Set<string> | undefined} snapshotContent
+ * @property {Set<SnapshotOptimizationEntry> | undefined} children
  */
 
 /**
@@ -115,6 +115,12 @@ const INVALID = Symbol("invalid");
  * @property {Set<string>} resolveDependencies.missing list of missing entries
  */
 
+/**
+ * @typedef {Object} SnapshotOptions
+ * @property {boolean=} hash should use hash to snapshot
+ * @property {boolean=} timestamp should use timestamp to snapshot
+ */
+
 const DONE_ITERATOR_RESULT = new Set().keys().next();
 
 // cspell:word tshs
@@ -137,7 +143,7 @@ class SnapshotIterable {
 		let state = 0;
 		/** @type {IterableIterator<string>} */
 		let it;
-		/** @type {(Snapshot) => (Map<string, any> | Set<string>)[]} */
+		/** @type {(snapshot: Snapshot) => (Map<string, any> | Set<string>)[]} */
 		let getMaps;
 		/** @type {(Map<string, any> | Set<string>)[]} */
 		let maps;
@@ -552,7 +558,7 @@ class SnapshotOptimization {
 			}
 		};
 
-		/** @type {SnapshotOptimizationEntry} */
+		/** @type {SnapshotOptimizationEntry | undefined} */
 		let newOptimizationEntry = undefined;
 
 		const capturedFilesSize = capturedFiles.size;
@@ -757,10 +763,9 @@ const mergeMaps = (a, b) => {
 
 /**
  * @template T
- * @template K
- * @param {Set<T, K>} a source map
- * @param {Set<T, K>} b joining map
- * @returns {Set<T, K>} joined map
+ * @param {Set<T>} a source map
+ * @param {Set<T>} b joining map
+ * @returns {Set<T>} joined map
  */
 const mergeSets = (a, b) => {
 	if (!b || b.size === 0) return a;
@@ -858,8 +863,8 @@ const getManagedItem = (managedPath, path) => {
 
 /**
  * @template {ContextFileSystemInfoEntry | ContextTimestampAndHash} T
- * @param {T} entry entry
- * @returns {T["resolved"] | undefined} the resolved entry
+ * @param {T | null} entry entry
+ * @returns {T["resolved"] | null | undefined} the resolved entry
  */
 const getResolvedTimestamp = entry => {
 	if (entry === null) return null;
@@ -868,15 +873,20 @@ const getResolvedTimestamp = entry => {
 };
 
 /**
- * @param {ContextHash} entry entry
- * @returns {string | undefined} the resolved entry
+ * @param {ContextHash | null} entry entry
+ * @returns {string | null | undefined} the resolved entry
  */
 const getResolvedHash = entry => {
 	if (entry === null) return null;
 	if (entry.resolved !== undefined) return entry.resolved;
 	return entry.symlinks === undefined ? entry.hash : undefined;
 };
 
+/**
+ * @template T
+ * @param {Set<T>} source source
+ * @param {Set<T>} target target
+ */
 const addAll = (source, target) => {
 	for (const key of source) target.add(key);
 };
@@ -1145,6 +1155,11 @@ class FileSystemInfo {
 		);
 	}
 
+	/**
+	 * @param {string} path path
+	 * @param {string} reason reason
+	 * @param {any[]} args arguments
+	 */
 	_log(path, reason, ...args) {
 		const key = path + reason;
 		if (this._loggedPaths.has(key)) return;
@@ -1258,7 +1273,7 @@ class FileSystemInfo {
 
 	/**
 	 * @param {string} path file path
-	 * @param {function((WebpackError | null)=, string=): void} callback callback function
+	 * @param {function((WebpackError | null)=, (string | null)=): void} callback callback function
 	 * @returns {void}
 	 */
 	getFileHash(path, callback) {
@@ -1289,7 +1304,7 @@ class FileSystemInfo {
 
 	/**
 	 * @param {string} path context path
-	 * @param {function((WebpackError | null)=, ContextHash=): void} callback callback function
+	 * @param {function((WebpackError | null)=, (ContextHash | null)=): void} callback callback function
 	 * @returns {void}
 	 */
 	_getUnresolvedContextHash(path, callback) {
@@ -1320,7 +1335,7 @@ class FileSystemInfo {
 
 	/**
 	 * @param {string} path context path
-	 * @param {function((WebpackError | null)=, ContextTimestampAndHash=): void} callback callback function
+	 * @param {function((WebpackError | null)=, (ContextTimestampAndHash | null)=): void} callback callback function
 	 * @returns {void}
 	 */
 	_getUnresolvedContextTsh(path, callback) {
@@ -1383,14 +1398,18 @@ class FileSystemInfo {
 		const resolveDirectories = new Set();
 		/** @type {Set<string>} */
 		const resolveMissing = new Set();
-		/** @type {Map<string, string | false>} */
+		/** @type {Map<string, string | false | undefined>} */
 		const resolveResults = new Map();
 		const invalidResolveResults = new Set();
 		const resolverContext = {
 			fileDependencies: resolveFiles,
 			contextDependencies: resolveDirectories,
 			missingDependencies: resolveMissing
 		};
+		/**
+		 * @param {string} expected expected result
+		 * @returns {string} expected result
+		 */
 		const expectedToString = expected => {
 			return expected ? ` (expected ${expected})` : "";
 		};
@@ -1610,7 +1629,7 @@ class FileSystemInfo {
 							break;
 						}
 						// Check commonjs cache for the module
-						/** @type {NodeModule} */
+						/** @type {NodeModule | undefined} */
 						const module = require.cache[path];
 						if (module && Array.isArray(module.children)) {
 							children: for (const child of module.children) {
@@ -1910,13 +1929,11 @@ class FileSystemInfo {
 
 	/**
 	 *
-	 * @param {number} startTime when processing the files has started
+	 * @param {number | null | undefined} startTime when processing the files has started
 	 * @param {Iterable<string>} files all files
 	 * @param {Iterable<string>} directories all directories
 	 * @param {Iterable<string>} missing all missing files or directories
-	 * @param {Object} options options object (for future extensions)
-	 * @param {boolean=} options.hash should use hash to snapshot
-	 * @param {boolean=} options.timestamp should use timestamp to snapshot
+	 * @param {SnapshotOptions | null | undefined} options options object (for future extensions)
 	 * @param {function((WebpackError | null)=, (Snapshot | null)=): void} callback callback function
 	 * @returns {void}
 	 */
@@ -2053,6 +2070,9 @@ class FileSystemInfo {
 			}
 			return capturedItems;
 		};
+		/**
+		 * @param {Set<string>} capturedFiles captured files
+		 */
 		const processCapturedFiles = capturedFiles => {
 			switch (mode) {
 				case 3:
@@ -2639,6 +2659,10 @@ class FileSystemInfo {
 				}
 			}
 		}
+		/**
+		 * @param {string} path file path
+		 * @param {string} hash hash
+		 */
 		const processFileHashSnapshot = (path, hash) => {
 			const cache = this._fileHashes.get(path);
 			if (cache !== undefined) {
@@ -2921,7 +2945,7 @@ class FileSystemInfo {
 
 			const hash = createHash(this._hashFunction);
 
-			hash.update(content);
+			hash.update(/** @type {string | Buffer} */ (content));
 
 			const digest = /** @type {string} */ (hash.digest("hex"));
 
@@ -2985,7 +3009,7 @@ class FileSystemInfo {
 	 * @param {function(string, IStats, function(Error=, ItemType=): void): void} options.fromFile called when context item is a file
 	 * @param {function(string, IStats, function(Error=, ItemType=): void): void} options.fromDirectory called when context item is a directory
 	 * @param {function(string[], ItemType[]): T} options.reduce called from all context items
-	 * @param {function((Error | null)=, (T)=): void} callback callback
+	 * @param {function((Error | null)=, (T | null)=): void} callback callback
 	 */
 	_readContext(
 		{
@@ -3172,6 +3196,7 @@ class FileSystemInfo {
 	 * @returns {void}
 	 */
 	_resolveContextTimestamp(entry, callback) {
+		/** @type {string[]} */
 		const hashes = [];
 		let safeTime = 0;
 		processAsyncTree(
@@ -3280,6 +3305,7 @@ class FileSystemInfo {
 	 * @returns {void}
 	 */
 	_resolveContextHash(entry, callback) {
+		/** @type {string[]} */
 		const hashes = [];
 		processAsyncTree(
 			entry.symlinks,
@@ -3436,7 +3462,9 @@ class FileSystemInfo {
 	 * @returns {void}
 	 */
 	_resolveContextTsh(entry, callback) {
+		/** @type {string[]} */
 		const hashes = [];
+		/** @type {string[]} */
 		const tsHashes = [];
 		let safeTime = 0;
 		processAsyncTree(
@@ -3554,7 +3582,7 @@ class FileSystemInfo {
 				}
 				let data;
 				try {
-					data = JSON.parse(content.toString("utf-8"));
+					data = JSON.parse(/** @type {Buffer} */ (content).toString("utf-8"));
 				} catch (e) {
 					return callback(e);
 				}