chore(Chunk): add type annotations for Chunk

lib/Chunk.js

@@ -1,6 +1,6 @@
 /*
-	MIT License http://www.opensource.org/licenses/mit-license.php
+MIT License http://www.opensource.org/licenses/mit-license.php
-	Author Tobias Koppers @sokra
+Author Tobias Koppers @sokra
 */
 "use strict";
 
@@ -13,18 +13,52 @@ const ERR_CHUNK_ENTRY = "Chunk.entry was removed. Use hasRuntime()";
 const ERR_CHUNK_INITIAL =
 	"Chunk.initial was removed. Use canBeInitial/isOnlyInitial()";
 
+/** @typedef {import("./Module.js")} Module */
+/** @typedef {import("./ChunkGroup")} ChunkGroup */
+/** @typedef {import("./ModuleReason.js")} ModuleReason */
+/** @typedef {import("webpack-sources").Source} Source */
+
+/**
+ *  @typedef {Object} Identifiable an object who contains an identifier function property
+ *  @property {() => string} identifier the resource or unique identifier of something
+ */
+
+/**
+ *  @typedef {Object} WithId an object who has an id property
+ *  @property {string} id the id of the object
+ */
+
+/** @typedef {(a: Module, b: Module) => -1|0|1} ModuleSortPredicate */
+/** @typedef {(m: Module) => boolean} ModuleFilterPredicate */
+/** @typedef {(c: Chunk) => boolean} ChunkFilterPredicate */
+
+/**
+ * @param {WithId} a object that contains an ID property
+ * @param {WithId} b object that contains an ID property
+ * @returns {-1|0|1} sort value
+ */
 const sortById = (a, b) => {
 	if (a.id < b.id) return -1;
 	if (b.id < a.id) return 1;
 	return 0;
 };
 
+/**
+ *
+ * @param {Identifiable} a first object with ident fn
+ * @param {Identifiable} b second object with ident fn
+ * @returns {-1|0|1} The order number of the sort
+ */
 const sortByIdentifier = (a, b) => {
 	if (a.identifier() > b.identifier()) return 1;
 	if (a.identifier() < b.identifier()) return -1;
 	return 0;
 };
 
+/**
+ * @returns {string} a concatenation of module identifiers sorted
+ * @param {SortableSet} set to pull module identifiers from
+ */
 const getModulesIdent = set => {
 	set.sort();
 	let str = "";
@@ -34,51 +68,105 @@ const getModulesIdent = set => {
 	return str;
 };
 
+/**
+ * @template {T}
+ * @param {Set<T>} set the set to convert to array
+ * @returns {Array<T>} the array returned from Array.from(set)
+ */
 const getArray = set => Array.from(set);
 
+/**
+ * @param {Set<Module>} set the Set to get the count/size of
+ * @returns {number} the size of the modules
+ */
 const getModulesSize = set => {
-	let count = 0;
+	let size = 0;
 	for (const module of set) {
-		count += module.size();
+		size += module.size();
 	}
-	return count;
+	return size;
 };
 
+/**
+ * A Chunk is a unit of encapsulation for Modules.
+ * Chunks are "rendered" into bundles that get emitted when the build completes.
+ */
 class Chunk {
+	/**
+	 * @param {string=} name of chunk being created, is optional (for subclasses)
+	 */
 	constructor(name) {
+		/** @type {number | null} */
 		this.id = null;
+		/** @type {number[] | null} */
 		this.ids = null;
+		/** @type {number} */
 		this.debugId = debugId++;
+		/** @type {string} */
 		this.name = name;
+		/** @type {boolean} */
 		this.preventIntegration = false;
+		/** @type {Module=} */
 		this.entryModule = undefined;
+		//TODO make these typed generics for Module[] and ChunkGroup[] and their sort being (T, T): => 1,-1,0
+		//See https://github.com/webpack/webpack/pull/7046
+		/** @private */
 		this._modules = new SortableSet(undefined, sortByIdentifier);
+		/** @private */
 		this._groups = new SortableSet(undefined, sortById);
+		/** @type {Source[]} */
 		this.files = [];
+		/** @type {boolean} */
 		this.rendered = false;
+		/** @type {string=} */
 		this.hash = undefined;
+		/** @type {Object} */
 		this.contentHash = Object.create(null);
+		/** @type {string=} */
 		this.renderedHash = undefined;
+		/** @type {string=} */
 		this.chunkReason = undefined;
+		/** @type {boolean} */
 		this.extraAsync = false;
 	}
 
+	/**
+	 * @deprecated Chunk.entry has been deprecated. Please use .hasRuntime() instead
+	 * @returns {never} Throws an error trying to access this property
+	 */
 	get entry() {
 		throw new Error(ERR_CHUNK_ENTRY);
 	}
 
+	/**
+	 * @deprecated .entry has been deprecated. Please use .hasRuntime() instead
+	 * @param {never} data The data that was attempting to be set
+	 * @returns {never} Throws an error trying to access this property
+	 */
 	set entry(data) {
 		throw new Error(ERR_CHUNK_ENTRY);
 	}
 
+	/**
+	 * @deprecated Chunk.initial was removed. Use canBeInitial/isOnlyInitial()
+	 * @returns {never} Throws an error trying to access this property
+	 */
 	get initial() {
 		throw new Error(ERR_CHUNK_INITIAL);
 	}
 
+	/**
+	 * @deprecated Chunk.initial was removed. Use canBeInitial/isOnlyInitial()
+	 * @param {never} data The data attempting to be set
+	 * @returns {never} Throws an error trying to access this property
+	 */
 	set initial(data) {
 		throw new Error(ERR_CHUNK_INITIAL);
 	}
 
+	/**
+	 * @returns {boolean} whether or not the Chunk will have a runtime
+	 */
 	hasRuntime() {
 		for (const chunkGroup of this._groups) {
 			// We only need to check the first one
@@ -87,6 +175,9 @@ class Chunk {
 		return false;
 	}
 
+	/**
+	 * @returns {boolean} whether or not this chunk can be an initial chunk
+	 */
 	canBeInitial() {
 		for (const chunkGroup of this._groups) {
 			if (chunkGroup.isInitial()) return true;
@@ -94,6 +185,9 @@ class Chunk {
 		return false;
 	}
 
+	/**
+	 * @returns {boolean} whether this chunk can only be an initial chunk
+	 */
 	isOnlyInitial() {
 		if (this._groups.size <= 0) return false;
 		for (const chunkGroup of this._groups) {
@@ -102,10 +196,17 @@ class Chunk {
 		return true;
 	}
 
+	/**
+	 * @returns {boolean} if this chunk contains the entry module
+	 */
 	hasEntryModule() {
 		return !!this.entryModule;
 	}
 
+	/**
+	 * @param {Module} module the module that will be added to this chunk.
+	 * @returns {boolean} returns true if the chunk doesn't have the module and it was added
+	 */
 	addModule(module) {
 		if (!this._modules.has(module)) {
 			this._modules.add(module);
@@ -114,6 +215,10 @@ class Chunk {
 		return false;
 	}
 
+	/**
+	 * @param {Module} module the module that will be removed from this chunk
+	 * @returns {boolean} returns true if chunk exists and is successfully deleted
+	 */
 	removeModule(module) {
 		if (this._modules.delete(module)) {
 			module.removeChunk(this);
@@ -122,42 +227,74 @@ class Chunk {
 		return false;
 	}
 
+	/**
+	 * @param {Module[]} modules the new modules to be set
+	 * @returns {void} set new modules to this chunk and return nothing
+	 */
 	setModules(modules) {
 		this._modules = new SortableSet(modules, sortByIdentifier);
 	}
 
+	/**
+	 * @returns {number} the amount of modules in chunk
+	 */
 	getNumberOfModules() {
 		return this._modules.size;
 	}
 
+	/**
+	 * @returns {SortableSet} return the modules SortableSet for this chunk
+	 */
 	get modulesIterable() {
 		return this._modules;
 	}
 
+	/**
+	 * @param {ChunkGroup} chunkGroup the chunkGroup the chunk is being added
+	 * @returns {boolean} returns true if chunk is not apart of chunkGroup and is added successfully
+	 */
 	addGroup(chunkGroup) {
 		if (this._groups.has(chunkGroup)) return false;
 		this._groups.add(chunkGroup);
 		return true;
 	}
 
+	/**
+	 * @param {ChunkGroup} chunkGroup the chunkGroup the chunk is being removed from
+	 * @returns {boolean} returns true if chunk does exist in chunkGroup and is removed
+	 */
 	removeGroup(chunkGroup) {
 		if (!this._groups.has(chunkGroup)) return false;
 		this._groups.delete(chunkGroup);
 		return true;
 	}
 
+	/**
+	 * @param {ChunkGroup} chunkGroup the chunkGroup to check
+	 * @returns {boolean} returns true if chunk has chunkGroup reference and exists in chunkGroup
+	 */
 	isInGroup(chunkGroup) {
 		return this._groups.has(chunkGroup);
 	}
 
+	/**
+	 * @returns {number} the amount of groups said chunk is in
+	 */
 	getNumberOfGroups() {
 		return this._groups.size;
 	}
 
+	/**
+	 * @returns {SortableSet} the chunkGroups that said chunk is referenced in
+	 */
 	get groupsIterable() {
 		return this._groups;
 	}
 
+	/**
+	 * @param {Chunk} otherChunk the chunk to compare itself with
+	 * @returns {-1|0|1} this is a comparitor function like sort and returns -1, 0, or 1 based on sort order
+	 */
 	compareTo(otherChunk) {
 		this._modules.sort();
 		otherChunk._modules.sort();
@@ -177,6 +314,10 @@ class Chunk {
 		}
 	}
 
+	/**
+	 * @param {Module} module Module to check
+	 * @returns {boolean} returns true if module does exist in this chunk
+	 */
 	containsModule(module) {
 		return this._modules.has(module);
 	}
@@ -189,7 +330,7 @@ class Chunk {
 		return this._modules.getFromUnorderedCache(getModulesIdent);
 	}
 
-	remove(reason) {
+	remove() {
 		// cleanup modules
 		// Array.from is used here to create a clone, because removeChunk modifies this._modules
 		for (const module of Array.from(this._modules)) {
@@ -200,12 +341,24 @@ class Chunk {
 		}
 	}
 
+	/**
+	 *
+	 * @param {Module} module module to move
+	 * @param {Chunk} otherChunk other chunk to move it to
+	 * @returns {void}
+	 */
 	moveModule(module, otherChunk) {
 		GraphHelpers.disconnectChunkAndModule(this, module);
 		GraphHelpers.connectChunkAndModule(otherChunk, module);
 		module.rewriteChunkInReasons(this, [otherChunk]);
 	}
 
+	/**
+	 *
+	 * @param {Chunk} otherChunk the chunk to integrate with
+	 * @param {ModuleReason} reason reason why the module is being integrated
+	 * @returns {boolean} returns true or false if integration succeeds or fails
+	 */
 	integrate(otherChunk, reason) {
 		if (!this.canBeIntegrated(otherChunk)) {
 			return false;
@@ -236,6 +389,10 @@ class Chunk {
 		return true;
 	}
 
+	/**
+	 * @param {Chunk} newChunk the new chunk that will be split out of, and then chunk raphi twil=
+	 * @returns {void}
+	 */
 	split(newChunk) {
 		for (const chunkGroup of this._groups) {
 			chunkGroup.insertChunk(newChunk, this);
@@ -282,6 +439,12 @@ class Chunk {
 		return true;
 	}
 
+	/**
+	 *
+	 * @param {number} size the size
+	 * @param {Object} options the options passed in
+	 * @returns {number} the multiplier returned
+	 */
 	addMultiplierAndOverhead(size, options) {
 		const overhead =
 			typeof options.chunkOverhead === "number" ? options.chunkOverhead : 10000;
@@ -292,10 +455,17 @@ class Chunk {
 		return size * multiplicator + overhead;
 	}
 
+	/**
+	 * @returns {number} the size of all modules
+	 */
 	modulesSize() {
 		return this._modules.getFromUnorderedCache(getModulesSize);
 	}
 
+	/**
+	 * @param {Object} options the size display options
+	 * @returns {number} the chunk size
+	 */
 	size(options) {
 		return this.addMultiplierAndOverhead(this.modulesSize(), options);
 	}
@@ -317,6 +487,10 @@ class Chunk {
 		return this.addMultiplierAndOverhead(integratedModulesSize, options);
 	}
 
+	/**
+	 * @param {ModuleSortPredicate=} sortByFn a predicate function used to sort modules
+	 * @returns {void}
+	 */
 	sortModules(sortByFn) {
 		this._modules.sortWith(sortByFn || sortById);
 	}
@@ -452,6 +626,12 @@ class Chunk {
 		};
 	}
 
+	/**
+	 *
+	 * @param {ModuleFilterPredicate} filterFn predicate function used to filter modules
+	 * @param {ChunkFilterPredicate} filterChunkFn predicate function used to filter chunks
+	 * @returns {boolean} return true if module exists in graph
+	 */
 	hasModuleInGraph(filterFn, filterChunkFn) {
 		const queue = new Set(this.groupsIterable);
 		const chunksProcessed = new Set();

lib/util/SortableSet.js

@@ -1,5 +1,7 @@
 "use strict";
-
+//TODO: Make this a generic type
+//https://github.com/Microsoft/TypeScript/issues/23385
+//https://github.com/Microsoft/TypeScript/issues/23384
 class SortableSet extends Set {
 	constructor(initialIterable, defaultSort) {
 		super(initialIterable);