Type SortableSet

Author: mohsen1

.eslintrc.js

@@ -41,7 +41,8 @@ module.exports = {
 			"preferType": {
 				"*": "any"
 			},
-			"requireReturnType": true
+			"requireReturnType": true,
+			requireReturnDescription: false
 		}],
 		"node/no-unsupported-features": "error",
 		"node/no-deprecated-api": "error",

lib/Chunk.js

@@ -18,21 +18,22 @@ const ERR_CHUNK_INITIAL =
 /** @typedef {import("./ModuleReason.js")} ModuleReason */
 /** @typedef {import("webpack-sources").Source} Source */
 
+/** @typedef {(a: Module, b: Module) => -1|0|1} ModuleSortPredicate */
+/** @typedef {(m: Module) => boolean} ModuleFilterPredicate */
+/** @typedef {(c: Chunk) => boolean} ChunkFilterPredicate */
+
 /**
  *  @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
+ *  @property {string | number} 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 */
-
 /**
+ * Compare two objects based on their ids for sorting
  * @param {WithId} a object that contains an ID property
  * @param {WithId} b object that contains an ID property
  * @returns {-1|0|1} sort value
@@ -44,9 +45,9 @@ const sortById = (a, b) => {
 };
 
 /**
- *
- * @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) => {
@@ -108,11 +109,9 @@ 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 */
+		/** @private @type {SortableSet<ChunkGroup | WithId>} */
 		this._groups = new SortableSet(undefined, sortById);
 		/** @type {Source[]} */
 		this.files = [];

lib/ChunkGroup.js

@@ -26,8 +26,8 @@ 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/util/SortableSet.js

@@ -1,19 +1,32 @@
 "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 {
+	// eslint-disable-next-line valid-jsdoc
+	/**
+	 * Create a new sortable set
+	 * @param {Array<T>=} initialIterable The initial iterable value
+	 * @param {SortFunction=} defaultSort Default sorting function
+	 * @typedef {(a: T, b: T) => number} SortFunction
+	 */
 	constructor(initialIterable, defaultSort) {
 		super(initialIterable);
+		/** @private @type {(a: T, b: T) => number}} */
 		this._sortFn = defaultSort;
+		/** @private @type {(a: T, b: T) => number} | null} */
 		this._lastActiveSortFn = null;
+		/** @private @type {Map<Function, T> | undefined} */
 		this._cache = undefined;
+		/** @private @type {Map<Function, T> | 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 +36,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 +75,14 @@ class SortableSet extends Set {
 		this._invalidateCache();
 	}
 
-	/**
-	 * @returns {void}
-	 */
 	sort() {
 		this.sortWith(this._sortFn);
 	}
 
+	// eslint-disable-next-line valid-jsdoc
 	/**
-	 * @param {Function} fn - function to calculate value
-	 * @returns {TODO} - returns result of fn(this), cached until set changes
+	 * @param {(instance: SortableSet<T>) => TODO} fn function to calculate value
+	 * @returns {TODO} returns result of fn(this), cached until set changes
 	 */
 	getFromCache(fn) {
 		if (this._cache === undefined) {
@@ -76,8 +99,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} fn function to calculate value
+	 * @returns {any} returns result of fn(this), cached until set changes
 	 */
 	getFromUnorderedCache(fn) {
 		if (this._cacheOrderIndependent === undefined) {
@@ -93,12 +116,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

@@ -70,7 +70,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

@@ -5984,9 +5984,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"