Merge pull request webpack#7513 from mohsen1/SortableSet-types

Add SortableSet types

Author: sokra

lib/Chunk.js

@@ -19,34 +19,38 @@ const ERR_CHUNK_INITIAL =
 /** @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 | number} id the id of the object
  */
 
 /**
- *  @typedef {Object} WithId an object who has an id property
- *  @property {string} id the id of the object
+ * Compare two Modules based on their ids for sorting
+ * @param {Module} a module
+ * @param {Module} b module
+ * @returns {-1|0|1} sort value
  */
-
-/** @typedef {(a: Module, b: Module) => -1|0|1} ModuleSortPredicate */
-/** @typedef {(m: Module) => boolean} ModuleFilterPredicate */
-/** @typedef {(c: Chunk) => boolean} ChunkFilterPredicate */
+const sortModuleById = (a, b) => {
+	if (a.id < b.id) return -1;
+	if (b.id < a.id) return 1;
+	return 0;
+};
 
 /**
- * @param {WithId} a object that contains an ID property
- * @param {WithId} b object that contains an ID property
+ * Compare two ChunkGroups based on their ids for sorting
+ * @param {ChunkGroup} a chunk group
+ * @param {ChunkGroup} b chunk group
  * @returns {-1|0|1} sort value
  */
-const sortById = (a, b) => {
+const sortChunkGroupById = (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
+ * Compare two Identifiables , based on their ids for sorting
+ * @param {Module} a first object with ident fn
+ * @param {Module} b second object with ident fn
  * @returns {-1|0|1} The order number of the sort
  */
 const sortByIdentifier = (a, b) => {
@@ -70,13 +74,13 @@ const getModulesIdent = set => {
 
 /**
  * @template T
- * @param {Set<T>} set the set to convert to array
+ * @param {SortableSet<T>} set the sortable 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
+ * @param {SortableSet<Module>} set the sortable Set to get the count/size of
  * @returns {number} the size of the modules
  */
 const getModulesSize = set => {
@@ -108,12 +112,10 @@ class Chunk {
 		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 */
+		/** @private @type {SortableSet<Module>} */
 		this._modules = new SortableSet(undefined, sortByIdentifier);
-		/** @private */
-		this._groups = new SortableSet(undefined, sortById);
+		/** @private @type {SortableSet<ChunkGroup>} */
+		this._groups = new SortableSet(undefined, sortChunkGroupById);
 		/** @type {Source[]} */
 		this.files = [];
 		/** @type {boolean} */
@@ -498,14 +500,14 @@ class Chunk {
 	}
 
 	/**
-	 * @param {ModuleSortPredicate=} sortByFn a predicate function used to sort modules
+	 * @param {function(Module, Module): -1|0|1=} sortByFn a predicate function used to sort modules
 	 * @returns {void}
 	 */
 	sortModules(sortByFn) {
-		this._modules.sortWith(sortByFn || sortById);
+		this._modules.sortWith(sortByFn || sortModuleById);
 	}
 
-	sortItems(sortChunks) {
+	sortItems() {
 		this.sortModules();
 	}
 
@@ -661,8 +663,8 @@ class Chunk {
 
 	/**
 	 *
-	 * @param {ModuleFilterPredicate} filterFn predicate function used to filter modules
-	 * @param {ChunkFilterPredicate} filterChunkFn predicate function used to filter chunks
+	 * @param {function(Module): boolean} filterFn predicate function used to filter modules
+	 * @param {function(Chunk): boolean} filterChunkFn predicate function used to filter chunks
 	 * @returns {boolean} return true if module exists in graph
 	 */
 	hasModuleInGraph(filterFn, filterChunkFn) {

lib/ChunkGroup.js

@@ -19,15 +19,15 @@ let debugId = 5000;
 
 /**
  * @template T
- * @param {Set<T>} set set to convert to array.
+ * @param {SortableSet<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
+ * @param {HasId} a first sorting comparator
+ * @param {HasId} b second sorting comparator
  * @returns {1|0|-1} a sorting index to determine order
  */
 const sortById = (a, b) => {
@@ -37,8 +37,8 @@ const sortById = (a, b) => {
 };
 
 /**
- * @param {OriginRecord} a the first comparitor in sort
- * @param {OriginRecord} b the second comparitor in sort
+ * @param {OriginRecord} a the first comparator in sort
+ * @param {OriginRecord} b the second comparator in sort
  * @returns {1|-1|0} returns sorting order as index
  */
 const sortOrigin = (a, b) => {

lib/Module.js

@@ -65,7 +65,7 @@ class Module extends DependenciesBlock {
 		// Graph (per Compilation)
 		/** @type {ModuleReason[]} */
 		this.reasons = [];
-		/** @type {SortableSet} */
+		/** @type {SortableSet<Chunk>} */
 		this._chunks = new SortableSet(undefined, sortById);
 
 		// Info from Compilation (per Compilation)

lib/ModuleTemplate.js

@@ -6,6 +6,9 @@
 
 const { Tapable, SyncWaterfallHook, SyncHook } = require("tapable");
 
+/** @typedef {import("webpack-sources").Source} Source */
+/** @typedef {import("./Module")} Module */
+
 module.exports = class ModuleTemplate extends Tapable {
 	constructor(runtimeTemplate, type) {
 		super();
@@ -40,6 +43,12 @@ module.exports = class ModuleTemplate extends Tapable {
 		};
 	}
 
+	/**
+	 * @param {Module} module the module
+	 * @param {TODO} dependencyTemplates templates for dependencies
+	 * @param {TODO} options render options
+	 * @returns {Source} the source
+	 */
 	render(module, dependencyTemplates, options) {
 		try {
 			const moduleSource = module.source(

lib/Template.js

@@ -24,11 +24,11 @@ const MATCH_PADDED_HYPHENS_REPLACE_REGEX = /^-|-$/g;
 
 /**
  * @typedef {Object} HasId
- * @property {number} id
+ * @property {number | string} id
  * */
 
 /**
- * @typedef {(m: Module, idx: number) => boolean} ModuleFilterPredicate
+ * @typedef {function(Module, number): boolean} ModuleFilterPredicate
  */
 
 /**
@@ -44,14 +44,6 @@ const stringifyIdSortPredicate = (a, b) => {
 	return 0;
 };
 
-/**
- * @param {Module} module the module to compare against
- * @returns {boolean} return true if module.id is equal to type "number"
- */
-const moduleIdIsNumber = module => {
-	return typeof module.id === "number";
-};
-
 class Template {
 	/**
 	 *
@@ -177,18 +169,20 @@ class Template {
 	}
 
 	/**
-	 *
-	 * @param {Module[]} modules a collection of modules to get array bounds for
+	 * @typedef {Object} WithId
+	 * @property {string|number} id
+	 */
+
+	/**
+	 * @param {WithId[]} modules a collection of modules to get array bounds for
 	 * @returns {[number, number] | false} returns the upper and lower array bounds
 	 * or false if not every module has a number based id
 	 */
 	static getModulesArrayBounds(modules) {
-		// Typeguards don't work for .every() with predicate functions
-		// https://github.com/Microsoft/TypeScript/issues/23799
-		if (!modules.every(moduleIdIsNumber)) return false;
 		var maxId = -Infinity;
 		var minId = Infinity;
 		for (const module of modules) {
+			if (typeof module.id !== "number") return false;
 			if (maxId < module.id) maxId = /** @type {number} */ (module.id);
 			if (minId > module.id) minId = /** @type {number} */ (module.id);
 		}

lib/util/SortableSet.js

@@ -1,19 +1,31 @@
 "use strict";
-//TODO: Make this a generic type
-//https://github.com/Microsoft/TypeScript/issues/23385
-//https://github.com/Microsoft/TypeScript/issues/23384
+
+/**
+ * A subset of Set that offers sorting functionality
+ * @template T item type in set
+ */
 class SortableSet extends Set {
+	/**
+	 * Create a new sortable set
+	 * @param {Array<T>=} initialIterable The initial iterable value
+	 * @typedef {function(T, T): number} SortFunction
+	 * @param {SortFunction=} defaultSort Default sorting function
+	 */
 	constructor(initialIterable, defaultSort) {
 		super(initialIterable);
+		/** @private @type {function(T, T): number}} */
 		this._sortFn = defaultSort;
+		/** @private @type {function(T, T): number} | null} */
 		this._lastActiveSortFn = null;
+		/** @private @type {Map<Function, T[]> | undefined} */
 		this._cache = undefined;
+		/** @private @type {Map<Function, T[]|string|number> | undefined} */
 		this._cacheOrderIndependent = undefined;
 	}
 
 	/**
-	 * @param {TODO} value - value to add to set
-	 * @returns {this} - returns itself
+	 * @param {T} value value to add to set
+	 * @returns {this} returns itself
 	 */
 	add(value) {
 		this._lastActiveSortFn = null;
@@ -23,19 +35,31 @@ class SortableSet extends Set {
 		return this;
 	}
 
+	/**
+	 * @param {T} value value to delete
+	 * @returns {boolean} true if value existed in set, false otherwise
+	 */
 	delete(value) {
 		this._invalidateCache();
 		this._invalidateOrderedCache();
 		return super.delete(value);
 	}
 
+	/**
+	 * @returns {void}
+	 */
 	clear() {
 		this._invalidateCache();
 		this._invalidateOrderedCache();
 		return super.clear();
 	}
 
-	sortWith(/** @type {(a: TODO, b: TODO) => number} */ sortFn) {
+	/**
+	 * Sort with a comparer function
+	 * @param {SortFunction} sortFn Sorting comparer function
+	 * @returns {void}
+	 */
+	sortWith(sortFn) {
 		if (this.size <= 1 || sortFn === this._lastActiveSortFn) {
 			// already sorted - nothing to do
 			return;
@@ -50,16 +74,14 @@ class SortableSet extends Set {
 		this._invalidateCache();
 	}
 
-	/**
-	 * @returns {void}
-	 */
 	sort() {
 		this.sortWith(this._sortFn);
 	}
 
 	/**
-	 * @param {Function} fn - function to calculate value
-	 * @returns {TODO} - returns result of fn(this), cached until set changes
+	 * Get data from cache
+	 * @param {function(SortableSet<T>): T[]} fn function to calculate value
+	 * @returns {T[]} returns result of fn(this), cached until set changes
 	 */
 	getFromCache(fn) {
 		if (this._cache === undefined) {
@@ -76,8 +98,8 @@ class SortableSet extends Set {
 	}
 
 	/**
-	 * @param {Function} fn - function to calculate value
-	 * @returns {TODO} - returns result of fn(this), cached until set changes
+	 * @param {function(SortableSet<T>): string|number|T[]} fn function to calculate value
+	 * @returns {any} returns result of fn(this), cached until set changes
 	 */
 	getFromUnorderedCache(fn) {
 		if (this._cacheOrderIndependent === undefined) {
@@ -93,12 +115,20 @@ class SortableSet extends Set {
 		return newData;
 	}
 
+	/**
+	 * @private
+	 * @returns {void}
+	 */
 	_invalidateCache() {
 		if (this._cache !== undefined) {
 			this._cache.clear();
 		}
 	}
 
+	/**
+	 * @private
+	 * @returns {void}
+	 */
 	_invalidateOrderedCache() {
 		if (this._cacheOrderIndependent !== undefined) {
 			this._cacheOrderIndependent.clear();

package.json

@@ -72,7 +72,7 @@
     "script-loader": "~0.7.0",
     "simple-git": "^1.65.0",
     "style-loader": "^0.19.1",
-    "typescript": "^2.9.0-dev.20180518",
+    "typescript": "^2.9.1",
     "url-loader": "^0.6.2",
     "val-loader": "^1.0.2",
     "vm-browserify": "~0.0.0",

yarn.lock

@@ -6489,9 +6489,9 @@ typedarray@^0.0.6:
   version "0.0.6"
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
 
-typescript@^2.9.0-dev.20180518:
-  version "2.9.0-dev.20180518"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.9.0-dev.20180518.tgz#7c709cb5d59e60a5e346cc5856277fd7b8ced68c"
+typescript@^2.9.1:
+  version "2.9.1"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-2.9.1.tgz#fdb19d2c67a15d11995fd15640e373e09ab09961"
 
 ua-parser-js@^0.7.9:
   version "0.7.17"