Merge pull request #7178 from webpack/feature/types-chunkgroup

Feature/types chunkgroup

lib/ChunkGroup.js

@@ -7,16 +7,40 @@
 const SortableSet = require("./util/SortableSet");
 const compareLocations = require("./compareLocations");
 
+/** @typedef {import("./Chunk")} Chunk */
+/** @typedef {import("./Module")} Module */
+/** @typedef {import("./ModuleReason")} ModuleReason */
+
+/** @typedef {{id: number}} HasId */
+/** @typedef {{module: Module, loc: any, request: string}} OriginRecord */
+/** @typedef {string|{name: string}} ChunkGroupOptions */
+
 let debugId = 5000;
 
+/**
+ * @template {T}
+ * @param {Set<T>} set set to convert to array.
+ * @returns {T[]} the array format of existing set
+ */
 const getArray = set => Array.from(set);
 
+/**
+ * A convenience method used to sort chunks based on their id's
+ * @param {HasId} a first sorting comparitor
+ * @param {HasId} b second sorting comparitor
+ * @returns {1|0|-1} a sorting index to determine order
+ */
 const sortById = (a, b) => {
 	if (a.id < b.id) return -1;
 	if (b.id < a.id) return 1;
 	return 0;
 };
 
+/**
+ * @param {OriginRecord} a the first comparitor in sort
+ * @param {OriginRecord} b the second comparitor in sort
+ * @returns {1|-1|0} returns sorting order as index
+ */
 const sortOrigin = (a, b) => {
 	const aIdent = a.module ? a.module.identifier() : "";
 	const bIdent = b.module ? b.module.identifier() : "";
@@ -26,21 +50,33 @@ const sortOrigin = (a, b) => {
 };
 
 class ChunkGroup {
+	/**
+	 * Creates an instance of ChunkGroup.
+	 * @param {ChunkGroupOptions=} options chunk group options passed to chunkGroup
+	 */
 	constructor(options) {
 		if (typeof options === "string") {
 			options = { name: options };
 		} else if (!options) {
 			options = { name: undefined };
 		}
+		/** @type {number} */
 		this.groupDebugId = debugId++;
 		this.options = options;
 		this._children = new SortableSet(undefined, sortById);
 		this._parents = new SortableSet(undefined, sortById);
 		this._blocks = new SortableSet();
+		/** @type {Chunk[]} */
 		this.chunks = [];
+		/** @type {OriginRecord[]} */
 		this.origins = [];
 	}
 
+	/**
+	 * when a new chunk is added to a chunkGroup, addingOptions will occur.
+	 * @param {ChunkGroupOptions} options the chunkGroup options passed to addOptions
+	 * @returns {void}
+	 */
 	addOptions(options) {
 		for (const key of Object.keys(options)) {
 			if (this.options[key] === undefined) {
@@ -57,23 +93,46 @@ class ChunkGroup {
 		}
 	}
 
+	/**
+	 * returns the name of current ChunkGroup
+	 * @returns {string|undefined} returns the ChunkGroup name
+	 */
 	get name() {
 		return this.options.name;
 	}
 
+	/**
+	 * sets a new name for current ChunkGroup
+	 * @param {string} value the new name for ChunkGroup
+	 * @returns {void}
+	 */
 	set name(value) {
 		this.options.name = value;
 	}
 
-	/* istanbul ignore next */
+	/**
+	 * get a uniqueId for ChunkGroup, made up of its member Chunk debugId's
+	 * @readonly
+	 * @returns {string} a unique concatenation of chunk debugId's
+	 */
 	get debugId() {
 		return Array.from(this.chunks, x => x.debugId).join("+");
 	}
 
+	/**
+	 * get a unique id for ChunkGroup, made up of its member Chunk id's
+	 * @readonly
+	 * @returns {string} a unique concatenation of chunk ids
+	 */
 	get id() {
 		return Array.from(this.chunks, x => x.id).join("+");
 	}
 
+	/**
+	 * Performs an unshift of a specific chunk
+	 * @param {Chunk} chunk chunk being unshifted
+	 * @returns {boolean} returns true if attempted chunk shift is accepted
+	 */
 	unshiftChunk(chunk) {
 		const oldIdx = this.chunks.indexOf(chunk);
 		if (oldIdx > 0) {
@@ -86,6 +145,12 @@ class ChunkGroup {
 		return false;
 	}
 
+	/**
+	 * inserts a chunk before another existing chunk in group
+	 * @param {Chunk} chunk Chunk being inserted
+	 * @param {Chunk} before Placeholder/target chunk marking new chunk insertion point
+	 * @returns {boolean} return true if insertion was successful
+	 */
 	insertChunk(chunk, before) {
 		const oldIdx = this.chunks.indexOf(chunk);
 		const idx = this.chunks.indexOf(before);
@@ -102,6 +167,11 @@ class ChunkGroup {
 		return false;
 	}
 
+	/**
+	 * add a chunk into ChunkGroup. Is pushed on or prepended
+	 * @param {Chunk} chunk chunk being pushed into ChunkGroupS
+	 * @returns {boolean} returns true if chunk addition was ssuccesful.
+	 */
 	pushChunk(chunk) {
 		const oldIdx = this.chunks.indexOf(chunk);
 		if (oldIdx >= 0) {
@@ -111,6 +181,12 @@ class ChunkGroup {
 		return true;
 	}
 
+	/**
+	 * @description
+	 * @param {Chunk} oldChunk chunk to be replaced
+	 * @param {Chunk} newChunk New chunkt that will be replaced
+	 * @returns {boolean} rerturns true for
+	 */
 	replaceChunk(oldChunk, newChunk) {
 		const oldIdx = this.chunks.indexOf(oldChunk);
 		if (oldIdx < 0) return false;
@@ -210,7 +286,7 @@ class ChunkGroup {
 	}
 
 	/**
-	 * @return {Array} - an array containing the blocks
+	 * @returns {Array} - an array containing the blocks
 	 */
 	getBlocks() {
 		return this._blocks.getFromCache(getArray);
@@ -263,6 +339,10 @@ class ChunkGroup {
 		return Array.from(files);
 	}
 
+	/**
+	 * @param {ModuleReason} reason reason for removing ChunkGroup
+	 * @returns {void}
+	 */
 	remove(reason) {
 		// cleanup parents
 		for (const parentChunkGroup of this._parents) {
@@ -310,6 +390,13 @@ class ChunkGroup {
 		this._children.sort();
 	}
 
+	/**
+	 * Sorting predicate which allows current ChunkGroup to be compared against another.
+	 * Sorting values are based off of number of chunks in ChunkGroup.
+	 *
+	 * @param {ChunkGroup} otherGroup the chunkGroup to compare this against
+	 * @returns {-1|0|1} sort position for comparison
+	 */
 	compareTo(otherGroup) {
 		if (this.chunks.length > otherGroup.chunks.length) return -1;
 		if (this.chunks.length < otherGroup.chunks.length) return 1;