Fix typings here and there (#310)

Author: bartveneman

src/context-collection.js

@@ -3,7 +3,7 @@ import { CountableCollection } from './countable-collection.js'
 class ContextCollection {
   constructor() {
     this._list = new CountableCollection()
-    /** @type {[index; string]: CountableCollection} */
+    /** @type {Map<string, CountableCollection>} */
     this._contexts = new Map()
   }
 
@@ -23,6 +23,14 @@ class ContextCollection {
   }
 
   count() {
+    /**
+     * @type {Map<string, {
+     * total: number,
+     * totalUnique: number,
+     * unique: {[string]: number},
+     * uniquenessRatio: number
+     * }>}
+     */
     const itemsPerContext = new Map()
 
     for (let [context, value] of this._contexts.entries()) {

src/countable-collection.js

@@ -1,11 +1,9 @@
 class CountableCollection {
-  /**
-   * @param {string[]} initial
-   */
+
+  /** @param {string[]?} initial */
   constructor(initial) {
-    /** @type [index: string]: string */
+    /** @type {Map<string, number>} */
     this._items = new Map()
-    /** @type number */
     this._total = 0
 
     if (initial) {
@@ -15,11 +13,7 @@ class CountableCollection {
     }
   }
 
-  /**
-   * Push an item to the end of this collection
-   * @param {string} item
-   * @returns {void}
-   */
+  /** @param {string} item */
   push(item) {
     this._total++
 
@@ -31,17 +25,10 @@ class CountableCollection {
     this._items.set(item, 1)
   }
 
-  /**
-   * Get the size of this collection
-   * @returns {number} the size of this collection
-   */
   size() {
     return this._total
   }
 
-  /**
-   * Get the counts of this collection, like total, uniques, etc.
-   */
   count() {
     return {
       total: this._total,

src/index.js

@@ -17,6 +17,8 @@ import { isCustom, isHack, isProperty } from './properties/property-utils.js'
 import { getEmbedType } from './stylesheet/stylesheet.js'
 import { isIe9Hack } from './values/browserhacks.js'
 
+/** @typedef {[number, number, number]} Specificity */
+
 function ratio(part, total) {
   if (total === 0) return 0
   return part / total
@@ -49,12 +51,12 @@ const analyze = (css) => {
   let embedSize = 0
   const embedTypes = {
     total: 0,
+    /** @type {Map<string, {size: number, count: number}>} */
     unique: new Map()
   }
 
   const startParse = Date.now()
 
-  /** @type import('css-tree').CssNode */
   const ast = parse(css, {
     parseCustomProperty: true, // To find font-families, colors, etc.
     positions: true, // So we can use stringifyNode()
@@ -70,7 +72,7 @@ const analyze = (css) => {
 
   // Atrules
   let totalAtRules = 0
-  /** @type {string}[]} */
+  /** @type {{[property: string]: string}[]} */
   const fontfaces = []
   const layers = new CountableCollection()
   const imports = new CountableCollection()
@@ -94,16 +96,16 @@ const analyze = (css) => {
   const keyframeSelectors = new CountableCollection()
   const uniqueSelectors = new Set()
   const prefixedSelectors = new CountableCollection()
-  /** @type [number,number,number] */
+  /** @type {Specificity} */
   let maxSpecificity
-  /** @type [number,number,number] */
+  /** @type {Specificity} */
   let minSpecificity
   const specificityA = new AggregateCollection()
   const specificityB = new AggregateCollection()
   const specificityC = new AggregateCollection()
   const uniqueSpecificities = new CountableCollection()
   const selectorComplexities = new AggregateCollection()
-  /** @type [number,number,number][] */
+  /** @type {Specificity[]} */
   const specificities = []
   const ids = new CountableCollection()
   const a11y = new CountableCollection()
@@ -144,7 +146,6 @@ const analyze = (css) => {
         const atRuleName = node.name
 
         if (atRuleName === 'font-face') {
-          /** @type {[index: string]: string} */
           const descriptors = {}
 
           node.block.children.forEach(descriptor => {
@@ -226,6 +227,7 @@ const analyze = (css) => {
         }
 
         const [{ value: specificityObj }] = calculate(node)
+        /** @type {Specificity} */
         const specificity = [specificityObj.a, specificityObj.b, specificityObj.c]
 
         if (specificity[0] > 0) {
@@ -601,17 +603,17 @@ const analyze = (css) => {
       totalUnique: totalUniqueSelectors,
       uniquenessRatio: ratio(totalUniqueSelectors, totalSelectors),
       specificity: {
-        /** @type [number, number, number] */
+        /** @type Specificity */
         min: minSpecificity === undefined ? [0, 0, 0] : minSpecificity,
-        /** @type [number, number, number] */
+        /** @type Specificity */
         max: maxSpecificity === undefined ? [0, 0, 0] : maxSpecificity,
-        /** @type [number, number, number] */
+        /** @type Specificity */
         sum: [specificitiesA.sum, specificitiesB.sum, specificitiesC.sum],
-        /** @type [number, number, number] */
+        /** @type Specificity */
         mean: [specificitiesA.mean, specificitiesB.mean, specificitiesC.mean],
-        /** @type [number, number, number] */
+        /** @type Specificity */
         mode: [specificitiesA.mode, specificitiesB.mode, specificitiesC.mode],
-        /** @type [number, number, number] */
+        /** @type Specificity */
         median: [specificitiesA.median, specificitiesB.median, specificitiesC.median],
         items: specificities,
         unique: uniqueSpecificitiesCount.unique,

src/selectors/utils.js

@@ -51,6 +51,7 @@ function isPseudoFunction(name) {
   )
 }
 
+/** @param {import('css-tree').Selector} selector */
 export function isAccessibility(selector) {
   let isA11y = false
 
@@ -82,7 +83,7 @@ export function isAccessibility(selector) {
 /**
  * Get the Complexity for the AST of a Selector Node
  * @param {import('css-tree').Selector} ast - AST Node for a Selector
- * @return {number} - The numeric complexity of the Selector
+ * @return {[number, boolean]} - The numeric complexity of the Selector and whether it's prefixed or not
  */
 export function getComplexity(selector) {
   let complexity = 0

src/string-utils.js

@@ -34,7 +34,7 @@ export function strEquals(base, test) {
 /**
  * Case-insensitive testing whether a string ends with a given substring
  * @param {string} base e.g. '-webkit-transform'
- * @param {string} cmp e.g. 'transform'
+ * @param {string} test e.g. 'transform'
  * @returns {boolean} true if `test` ends with `base`, false otherwise
  */
 export function endsWith(base, test) {

src/stylesheet/stylesheet.js

@@ -1,4 +1,5 @@
-export function getEmbedType(/** @type string */embed) {
+/** @param {string} embed */
+export function getEmbedType(embed) {
 	// data:image/gif;base64,R0lG
 	let start = 5 // `data:`.length
 	let semicolon = embed.indexOf(';')