Merge pull request #7299 from webpack/feature/type-compiler-compilati…

…on-save

chore(types): Add JSDoc To Compiler, Compilation, and Connected Classes Types

.eslintrc.js

@@ -32,8 +32,10 @@ module.exports = {
 		"valid-jsdoc": ["error", {
 			"prefer": {
 				"return": "returns",
+				"prop": "property",
 				"memberof": "DONTUSE",
 				"class": "DONTUSE",
+				"extends": "DONTUSE",
 				"inheritdoc": "DONTUSE",
 				"description": "DONTUSE",
 				"readonly": "DONTUSE"

.github/ISSUE_TEMPLATE/Bug_report.md

@@ -1,39 +1,39 @@
----
-name: Bug report
-about: Create a report to help us improve
----
-
-<!-- Please don't delete this template because we'll close your issue -->
-<!-- Before creating an issue please make sure you are using the latest version of webpack. -->
-
-# Bug report
-
-<!-- Please ask questions on StackOverflow or the webpack Gitter. -->
-<!-- https://stackoverflow.com/questions/ask?tags=webpack -->
-<!-- https://gitter.im/webpack/webpack -->
-<!-- Issues which contain questions or support requests will be closed. -->
-
-**What is the current behavior?**
-
-
-**If the current behavior is a bug, please provide the steps to reproduce.**
-
-
-<!-- A great way to do this is to provide your configuration via a GitHub repository -->
-<!-- The most helpful is a minimal reproduction with instructions on how to reproduce -->
-<!-- Repositories with too many files or large `webpack.config.js` files are not suitable -->
-<!-- Please only add small code snippets directly into this issue -->
-<!-- https://gist.github.com is a good place for longer code snippets -->
-<!-- If your issue is caused by a plugin or loader, please create an issue on the loader/plugin repository instead -->
-
-**What is the expected behavior?**
-
-
-<!-- "It should work" is not a helpful explanation -->
-<!-- Explain exactly how it should behave -->
-
-**Other relevant information:**
-webpack version:  
-Node.js version: 
-Operating System: 
-Additional tools:
+---
+name: Bug report
+about: Create a report to help us improve
+---
+
+<!-- Please don't delete this template because we'll close your issue -->
+<!-- Before creating an issue please make sure you are using the latest version of webpack. -->
+
+# Bug report
+
+<!-- Please ask questions on StackOverflow or the webpack Gitter. -->
+<!-- https://stackoverflow.com/questions/ask?tags=webpack -->
+<!-- https://gitter.im/webpack/webpack -->
+<!-- Issues which contain questions or support requests will be closed. -->
+
+**What is the current behavior?**
+
+
+**If the current behavior is a bug, please provide the steps to reproduce.**
+
+
+<!-- A great way to do this is to provide your configuration via a GitHub repository -->
+<!-- The most helpful is a minimal reproduction with instructions on how to reproduce -->
+<!-- Repositories with too many files or large `webpack.config.js` files are not suitable -->
+<!-- Please only add small code snippets directly into this issue -->
+<!-- https://gist.github.com is a good place for longer code snippets -->
+<!-- If your issue is caused by a plugin or loader, please create an issue on the loader/plugin repository instead -->
+
+**What is the expected behavior?**
+
+
+<!-- "It should work" is not a helpful explanation -->
+<!-- Explain exactly how it should behave -->
+
+**Other relevant information:**
+webpack version:  
+Node.js version: 
+Operating System: 
+Additional tools:

.github/ISSUE_TEMPLATE/Feature_request.md

@@ -1,27 +1,27 @@
----
-name: Feature request
-about: Suggest an idea for this project
-
----
-
-<!-- Please don't delete this template or we'll close your issue -->
-
-## Feature request
-
-<!-- Issues which contain questions or support requests will be closed. -->
-<!-- Before creating an issue please make sure you are using the latest version of webpack. -->
-<!-- Check if this feature need to be implemented in a plugin or loader instead -->
-<!-- If yes: file the issue on the plugin/loader repo -->
-<!-- Features related to the development server should be filed on this repo instead -->
-
-**What is the expected behavior?**
-
-
-**What is motivation or use case for adding/changing the behavior?**
-
-
-**How should this be implemented in your opinion?**
-
-
-**Are you willing to work on this yourself?**
-yes
+---
+name: Feature request
+about: Suggest an idea for this project
+
+---
+
+<!-- Please don't delete this template or we'll close your issue -->
+
+## Feature request
+
+<!-- Issues which contain questions or support requests will be closed. -->
+<!-- Before creating an issue please make sure you are using the latest version of webpack. -->
+<!-- Check if this feature need to be implemented in a plugin or loader instead -->
+<!-- If yes: file the issue on the plugin/loader repo -->
+<!-- Features related to the development server should be filed on this repo instead -->
+
+**What is the expected behavior?**
+
+
+**What is motivation or use case for adding/changing the behavior?**
+
+
+**How should this be implemented in your opinion?**
+
+
+**Are you willing to work on this yourself?**
+yes

.github/ISSUE_TEMPLATE/Other.md

@@ -1,9 +1,9 @@
----
-name: Other
-about: Something else
-
----
-
-<!-- Bug reports and Feature requests must use other templates, or will be closed -->
-<!-- Please ask questions on StackOverflow or the webpack Gitter (https://gitter.im/webpack/webpack). -->
-<!-- Issues which contain questions or support requests will be closed. -->
+---
+name: Other
+about: Something else
+
+---
+
+<!-- Bug reports and Feature requests must use other templates, or will be closed -->
+<!-- Please ask questions on StackOverflow or the webpack Gitter (https://gitter.im/webpack/webpack). -->
+<!-- Issues which contain questions or support requests will be closed. -->

.prettierignore

@@ -13,3 +13,4 @@
 !examples/**/webpack.config.js
 !schemas/**/*.js
 !declarations.d.ts
+!tsconfig.json

declarations.d.ts

@@ -7,6 +7,100 @@ declare namespace NodeJS {
 	}
 }
 
+
+declare module "neo-async" {
+	export interface Dictionary<T> {
+		[key: string]: T;
+	}
+	export type IterableCollection<T> = T[] | IterableIterator<T> | Dictionary<T>;
+
+	export interface ErrorCallback<T> {
+		(err?: T): void;
+	}
+	export interface AsyncBooleanResultCallback<E> {
+		(err?: E, truthValue?: boolean): void;
+	}
+	export interface AsyncResultCallback<T, E> {
+		(err?: E, result?: T): void;
+	}
+	export interface AsyncResultArrayCallback<T, E> {
+		(err?: E, results?: Array<T | undefined>): void;
+	}
+	export interface AsyncResultObjectCallback<T, E> {
+		(err: E | undefined, results: Dictionary<T | undefined>): void;
+	}
+
+	export interface AsyncFunction<T, E> {
+		(callback: (err?: E, result?: T) => void): void;
+	}
+	export interface AsyncFunctionEx<T, E> {
+		(callback: (err?: E, ...results: T[]) => void): void;
+	}
+	export interface AsyncIterator<T, E> {
+		(item: T, callback: ErrorCallback<E>): void;
+	}
+	export interface AsyncForEachOfIterator<T, E> {
+		(item: T, key: number | string, callback: ErrorCallback<E>): void;
+	}
+	export interface AsyncResultIterator<T, R, E> {
+		(item: T, callback: AsyncResultCallback<R, E>): void;
+	}
+	export interface AsyncMemoIterator<T, R, E> {
+		(memo: R | undefined, item: T, callback: AsyncResultCallback<R, E>): void;
+	}
+	export interface AsyncBooleanIterator<T, E> {
+		(item: T, callback: AsyncBooleanResultCallback<E>): void;
+	}
+
+	export interface AsyncWorker<T, E> {
+		(task: T, callback: ErrorCallback<E>): void;
+	}
+	export interface AsyncVoidFunction<E> {
+		(callback: ErrorCallback<E>): void;
+	}
+
+	export type AsyncAutoTasks<R extends Dictionary<any>, E> = {
+		[K in keyof R]: AsyncAutoTask<R[K], R, E>
+	};
+	export type AsyncAutoTask<R1, R extends Dictionary<any>, E> =
+		| AsyncAutoTaskFunctionWithoutDependencies<R1, E>
+		| (keyof R | AsyncAutoTaskFunction<R1, R, E>)[];
+	export interface AsyncAutoTaskFunctionWithoutDependencies<R1, E> {
+		(cb: AsyncResultCallback<R1, E> | ErrorCallback<E>): void;
+	}
+	export interface AsyncAutoTaskFunction<R1, R extends Dictionary<any>, E> {
+		(results: R, cb: AsyncResultCallback<R1, E> | ErrorCallback<E>): void;
+	}
+
+	export function each<T, E>(
+		arr: IterableCollection<T>,
+		iterator: AsyncIterator<T, E>,
+		callback?: ErrorCallback<E>
+	): void;
+
+	export function map<T, R, E>(
+		arr: T[] | IterableIterator<T>,
+		iterator: AsyncResultIterator<T, R, E>,
+		callback?: AsyncResultArrayCallback<R, E>
+	): void;
+	export function map<T, R, E>(
+		arr: Dictionary<T>,
+		iterator: AsyncResultIterator<T, R, E>,
+		callback?: AsyncResultArrayCallback<R, E>
+	): void;
+
+	export function parallel<T, E>(
+		tasks: Array<AsyncFunction<T, E>>,
+		callback?: AsyncResultArrayCallback<T, E>
+	): void;
+	export function parallel<T, E>(
+		tasks: Dictionary<AsyncFunction<T, E>>,
+		callback?: AsyncResultObjectCallback<T, E>
+	): void;
+
+	export const forEach: typeof each;
+}
+
 // There are no typings for @webassemblyjs/ast
 declare module "@webassemblyjs/ast" {
 	export function traverse(

lib/AsyncDependenciesBlock.js

@@ -3,9 +3,22 @@
 	Author Tobias Koppers @sokra
 */
 "use strict";
+
 const DependenciesBlock = require("./DependenciesBlock");
 
+/** @typedef {import("./ChunkGroup")} ChunkGroup */
+/** @typedef {import("./Module")} Module */
+/** @typedef {import("./Dependency").DependencyLocation} DependencyLocation */
+/** @typedef {import("./util/createHash").Hash} Hash */
+/** @typedef {TODO} GroupOptions */
+
 module.exports = class AsyncDependenciesBlock extends DependenciesBlock {
+	/**
+	 * @param {GroupOptions} groupOptions options for the group
+	 * @param {Module} module the Module object
+	 * @param {DependencyLocation=} loc the line of code
+	 * @param {TODO=} request the request
+	 */
 	constructor(groupOptions, module, loc, request) {
 		super();
 		if (typeof groupOptions === "string") {
@@ -14,28 +27,50 @@ module.exports = class AsyncDependenciesBlock extends DependenciesBlock {
 			groupOptions = { name: undefined };
 		}
 		this.groupOptions = groupOptions;
+		/** @type {ChunkGroup=} */
 		this.chunkGroup = undefined;
 		this.module = module;
 		this.loc = loc;
 		this.request = request;
+		/** @type {DependenciesBlock} */
+		this.parent = undefined;
 	}
 
+	/**
+	 * @returns {string} The name of the chunk
+	 */
 	get chunkName() {
 		return this.groupOptions.name;
 	}
 
+	/**
+	 * @param {string} value The new chunk name
+	 * @returns {void}
+	 */
 	set chunkName(value) {
 		this.groupOptions.name = value;
 	}
 
+	/**
+	 * @returns {never} this throws and should never be called
+	 */
 	get chunks() {
 		throw new Error("Moved to AsyncDependenciesBlock.chunkGroup");
 	}
 
+	/**
+	 * @param {never} value setter value
+	 * @returns {never} this is going to throw therefore we should throw type
+	 * assertions by returning never
+	 */
 	set chunks(value) {
 		throw new Error("Moved to AsyncDependenciesBlock.chunkGroup");
 	}
 
+	/**
+	 * @param {Hash} hash the hash used to track block changes, from "crypto" module
+	 * @returns {void}
+	 */
 	updateHash(hash) {
 		hash.update(JSON.stringify(this.groupOptions));
 		hash.update(
@@ -50,16 +85,25 @@ module.exports = class AsyncDependenciesBlock extends DependenciesBlock {
 		super.updateHash(hash);
 	}
 
+	/**
+	 * @returns {void}
+	 */
 	disconnect() {
 		this.chunkGroup = undefined;
 		super.disconnect();
 	}
 
+	/**
+	 * @returns {void}
+	 */
 	unseal() {
 		this.chunkGroup = undefined;
 		super.unseal();
 	}
 
+	/**
+	 * @returns {void}
+	 */
 	sortItems() {
 		super.sortItems();
 	}

lib/AutomaticPrefetchPlugin.js

@@ -30,7 +30,7 @@ class AutomaticPrefetchPlugin {
 		compiler.hooks.afterCompile.tap("AutomaticPrefetchPlugin", compilation => {
 			lastModules = compilation.modules
 				.filter(m => m instanceof NormalModule)
-				.map(m => ({
+				.map((/** @type {NormalModule} */ m) => ({
 					context: m.context,
 					request: m.request
 				}));