postcss-merge-rules 5.0.6 → 5.1.0

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "postcss-merge-rules",
-  "version": "5.0.6",
+  "version": "5.1.0",
   "description": "Merge CSS rules with PostCSS.",
+  "types": "types/index.d.ts",
   "main": "src/index.js",
   "files": [
     "LICENSE-MIT",
-    "src"
+    "src",
+    "types"
   ],
   "keywords": [
     "css",
@@ -24,7 +26,7 @@
   "dependencies": {
     "browserslist": "^4.16.6",
     "caniuse-api": "^3.0.0",
-    "cssnano-utils": "^3.0.2",
+    "cssnano-utils": "^3.1.0",
     "postcss-selector-parser": "^6.0.5"
   },
   "bugs": {
@@ -34,8 +36,9 @@
     "node": "^10 || ^12 || >=14.0"
   },
   "devDependencies": {
+    "@types/caniuse-api": "^3.0.2",
     "postcss": "^8.2.15",
-    "postcss-discard-comments": "^5.0.3"
+    "postcss-discard-comments": "^5.1.0"
   },
   "peerDependencies": {
     "postcss": "^8.2.15"

package/src/index.js

@@ -8,8 +8,8 @@ const {
 } = require('./lib/ensureCompatibility');
 
 /**
- * @param {postcss.Declaration} a
- * @param {postcss.Declaration} b
+ * @param {import('postcss').Declaration} a
+ * @param {import('postcss').Declaration} b
  * @return {boolean}
  */
 function declarationIsEqual(a, b) {
@@ -19,8 +19,8 @@ function declarationIsEqual(a, b) {
 }
 
 /**
- * @param {postcss.Declaration[]} array
- * @param {postcss.Declaration} decl
+ * @param {import('postcss').Declaration[]} array
+ * @param {import('postcss').Declaration} decl
  * @return {number}
  */
 function indexOfDeclaration(array, decl) {
@@ -29,10 +29,10 @@ function indexOfDeclaration(array, decl) {
 
 /**
  * Returns filtered array of matched or unmatched declarations
- * @param {postcss.Declaration[]} a
- * @param {postcss.Declaration[]} b
+ * @param {import('postcss').Declaration[]} a
+ * @param {import('postcss').Declaration[]} b
  * @param {boolean} [not=false]
- * @return {postcss.Declaration[]}
+ * @return {import('postcss').Declaration[]}
  */
 function intersect(a, b, not) {
   return a.filter((c) => {
@@ -42,8 +42,8 @@ function intersect(a, b, not) {
 }
 
 /**
- * @param {postcss.Declaration[]} a
- * @param {postcss.Declaration[]} b
+ * @param {import('postcss').Declaration[]} a
+ * @param {import('postcss').Declaration[]} b
  * @return {boolean}
  */
 function sameDeclarationsAndOrder(a, b) {
@@ -54,8 +54,8 @@ function sameDeclarationsAndOrder(a, b) {
 }
 
 /**
- * @param {postcss.Rule} ruleA
- * @param {postcss.Rule} ruleB
+ * @param {import('postcss').Rule} ruleA
+ * @param {import('postcss').Rule} ruleB
  * @param {string[]=} browsers
  * @param {Map<string, boolean>=} compatibilityCache
  * @return {boolean}
@@ -70,8 +70,11 @@ function canMerge(ruleA, ruleB, browsers, compatibilityCache) {
     return false;
   }
 
-  const parent = sameParent(ruleA, ruleB);
-  const { name } = ruleA.parent;
+  const parent = sameParent(
+    /** @type {any} */ (ruleA),
+    /** @type {any} */ (ruleB)
+  );
+  const { name } = /** @type {any} */ (ruleA).parent;
   if (parent && name && name.includes('keyframes')) {
     return false;
   }
@@ -79,22 +82,29 @@ function canMerge(ruleA, ruleB, browsers, compatibilityCache) {
 }
 
 /**
- * @param {postcss.Rule} rule
- * @return {postcss.Declaration[]}
+ * @param {import('postcss').Rule} rule
+ * @return {import('postcss').Declaration[]}
  */
 function getDecls(rule) {
-  return rule.nodes.filter((node) => node.type === 'decl');
+  return /** @type {import('postcss').Declaration[]} */ (
+    rule.nodes.filter((node) => node.type === 'decl')
+  );
 }
 
+/** @type {(...rules: import('postcss').Rule[]) => string} */
 const joinSelectors = (...rules) => rules.map((s) => s.selector).join();
 
+/**
+ * @param {...import('postcss').Rule} rules
+ * @return {number}
+ */
 function ruleLength(...rules) {
   return rules.map((r) => (r.nodes.length ? String(r) : '')).join('').length;
 }
 
 /**
  * @param {string} prop
- * @return {{prefix: string, base:string, rest:string[]}}
+ * @return {{prefix: string?, base:string?, rest:string[]}}
  */
 function splitProp(prop) {
   // Treat vendor prefixed properties as if they were unprefixed;
@@ -155,8 +165,8 @@ function isConflictingProp(propA, propB) {
 }
 
 /**
- * @param {postcss.Rule} first
- * @param {postcss.Rule} second
+ * @param {import('postcss').Rule} first
+ * @param {import('postcss').Rule} second
  * @return {boolean} merged
  */
 function mergeParents(first, second) {
@@ -178,9 +188,9 @@ function mergeParents(first, second) {
 }
 
 /**
- * @param {postcss.Rule} first
- * @param {postcss.Rule} second
- * @return {postcss.Rule} mergedRule
+ * @param {import('postcss').Rule} first
+ * @param {import('postcss').Rule} second
+ * @return {import('postcss').Rule} mergedRule
  */
 function partialMerge(first, second) {
   let intersection = intersect(getDecls(first), getDecls(second));
@@ -190,7 +200,11 @@ function partialMerge(first, second) {
   let nextRule = second.next();
   if (!nextRule) {
     // Grab next cousin
-    const parentSibling = second.parent.next();
+    /** @type {any} */
+    const parentSibling =
+      /** @type {import('postcss').Container<import('postcss').ChildNode>} */ (
+        second.parent
+      ).next();
     nextRule = parentSibling && parentSibling.nodes && parentSibling.nodes[0];
   }
   if (nextRule && nextRule.type === 'rule' && canMerge(second, nextRule)) {
@@ -262,14 +276,17 @@ function partialMerge(first, second) {
   receivingBlock.selector = joinSelectors(first, second);
   receivingBlock.nodes = [];
 
-  second.parent.insertBefore(second, receivingBlock);
+  /** @type {import('postcss').Container<import('postcss').ChildNode>} */ (
+    second.parent
+  ).insertBefore(second, receivingBlock);
 
   const firstClone = first.clone();
   const secondClone = second.clone();
 
   /**
-   * @param {function(postcss.Declaration):void} callback
-   * @return {function(postcss.Declaration)}
+   * @param {function(import('postcss').Declaration):void} callback
+   * @this {import('postcss').Rule}
+   * @return {function(import('postcss').Declaration)}
    */
   function moveDecl(callback) {
     return (decl) => {
@@ -308,10 +325,10 @@ function partialMerge(first, second) {
 /**
  * @param {string[]} browsers
  * @param {Map<string, boolean>} compatibilityCache
- * @return {function(postcss.Rule)}
+ * @return {function(import('postcss').Rule)}
  */
 function selectorMerger(browsers, compatibilityCache) {
-  /** @type {postcss.Rule} */
+  /** @type {import('postcss').Rule | null} */
   let cache = null;
   return function (rule) {
     // Prime the cache with the first rule, or alternately ensure that it is
@@ -343,10 +360,16 @@ function selectorMerger(browsers, compatibilityCache) {
     if (cache.selector === rule.selector) {
       const cached = getDecls(cache);
       rule.walk((decl) => {
-        if (~indexOfDeclaration(cached, decl)) {
-          return decl.remove();
+        if (
+          ~indexOfDeclaration(
+            cached,
+            /** @type {import('postcss').Declaration} */ (decl)
+          )
+        ) {
+          decl.remove();
+          return;
         }
-        cache.append(decl);
+        /** @type {import('postcss').Rule} */ (cache).append(decl);
       });
       rule.remove();
       return;
@@ -356,12 +379,16 @@ function selectorMerger(browsers, compatibilityCache) {
     cache = partialMerge(cache, rule);
   };
 }
-
+/**
+ * @type {import('postcss').PluginCreator<void>}
+ * @return {import('postcss').Plugin}
+ */
 function pluginCreator() {
   return {
     postcssPlugin: 'postcss-merge-rules',
 
     prepare(result) {
+      /** @type {typeof result.opts & browserslist.Options} */
       const resultOpts = result.opts || {};
       const browsers = browserslist(null, {
         stats: resultOpts.stats,

package/src/lib/ensureCompatibility.js

@@ -15,21 +15,35 @@ const formValidation = 'form-validation';
 const vendorPrefix =
   /-(ah|apple|atsc|epub|hp|khtml|moz|ms|o|rim|ro|tc|wap|webkit|xv)-/;
 
+const level2Sel = new Set(['=', '~=', '|=']);
+const level3Sel = new Set(['^=', '$=', '*=']);
+
 /**
  * @param {string} selector
- * @return {string[]}
+ * @return {RegExpMatchArray | null}
  */
 function filterPrefixes(selector) {
   return selector.match(vendorPrefix);
 }
 
-// Internet Explorer use :-ms-input-placeholder.
-// Microsoft Edge use ::-ms-input-placeholder.
+/**
+ * Internet Explorer use :-ms-input-placeholder.
+ * Microsoft Edge use ::-ms-input-placeholder.
+ *
+ * @type {(selector: string) => number}
+ */
 const findMsInputPlaceholder = (selector) =>
   ~selector.search(/-ms-input-placeholder/i);
 
+/**
+ * @param {string[]} selectorsA
+ * @param {string[]} selectorsB
+ * @return {boolean}
+ */
 function sameVendor(selectorsA, selectorsB) {
+  /** @type {(selectors: string[]) => string} */
   let same = (selectors) => selectors.map(filterPrefixes).join();
+  /** @type {(selectors: string[]) => string | undefined} */
   let findMsVendor = (selectors) => selectors.find(findMsInputPlaceholder);
   return (
     same(selectorsA) === same(selectorsB) &&
@@ -99,10 +113,18 @@ const pseudoElements = {
   ':visited': cssSel2,
 };
 
+/**
+ * @param {string} selector
+ * @return {boolean}
+ */
 function isCssMixin(selector) {
   return selector[selector.length - 1] === ':';
 }
 
+/**
+ * @param {string} selector
+ * @return {boolean}
+ */
 function isHostPseudoClass(selector) {
   return selector.includes(':host');
 }
@@ -110,18 +132,28 @@ function isHostPseudoClass(selector) {
 const isSupportedCache = new Map();
 
 // Move to util in future
+/**
+ * @param {string} feature
+ * @param {string[] | undefined} browsers
+ */
 function isSupportedCached(feature, browsers) {
   const key = JSON.stringify({ feature, browsers });
   let result = isSupportedCache.get(key);
 
   if (!result) {
-    result = isSupported(feature, browsers);
+    result = isSupported(feature, /** @type {string[]} */ (browsers));
     isSupportedCache.set(key, result);
   }
 
   return result;
 }
 
+/**
+ * @param {string[]} selectors
+ * @param{string[]=} browsers
+ * @param{Map<string,boolean>=} compatibilityCache
+ * @return {boolean}
+ */
 function ensureCompatibility(selectors, browsers, compatibilityCache) {
   // Should not merge mixins
   if (selectors.some(isCssMixin)) {
@@ -144,7 +176,8 @@ function ensureCompatibility(selectors, browsers, compatibilityCache) {
       ast.walk((node) => {
         const { type, value } = node;
         if (type === 'pseudo') {
-          const entry = pseudoElements[value];
+          const entry =
+            pseudoElements[/** @type {keyof pseudoElements} */ (value)];
           if (!entry && noVendor(value)) {
             compatible = false;
           }
@@ -165,14 +198,13 @@ function ensureCompatibility(selectors, browsers, compatibilityCache) {
           if (!node.operator) {
             compatible = isSupportedCached(cssSel2, browsers);
           }
-
           if (value) {
             // [foo="bar"], [foo~="bar"], [foo|="bar"]
-            if (['=', '~=', '|='].includes(node.operator)) {
+            if (level2Sel.has(/** @type {string} */ (node.operator))) {
               compatible = isSupportedCached(cssSel2, browsers);
             }
             // [foo^="bar"], [foo$="bar"], [foo*="bar"]
-            if (['^=', '$=', '*='].includes(node.operator)) {
+            if (level3Sel.has(/** @type {string} */ (node.operator))) {
               compatible = isSupportedCached(cssSel3, browsers);
             }
           }

package/types/index.d.ts

@@ -0,0 +1,9 @@
+export = pluginCreator;
+/**
+ * @type {import('postcss').PluginCreator<void>}
+ * @return {import('postcss').Plugin}
+ */
+declare function pluginCreator(): import('postcss').Plugin;
+declare namespace pluginCreator {
+    const postcss: true;
+}

package/types/lib/ensureCompatibility.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @param {string[]} selectorsA
+ * @param {string[]} selectorsB
+ * @return {boolean}
+ */
+export function sameVendor(selectorsA: string[], selectorsB: string[]): boolean;
+/**
+ * @param {string} selector
+ * @return {boolean}
+ */
+export function noVendor(selector: string): boolean;
+export const pseudoElements: {
+    ':active': string;
+    ':after': string;
+    ':any-link': string;
+    ':before': string;
+    ':checked': string;
+    ':default': string;
+    ':dir': string;
+    ':disabled': string;
+    ':empty': string;
+    ':enabled': string;
+    ':first-child': string;
+    ':first-letter': string;
+    ':first-line': string;
+    ':first-of-type': string;
+    ':focus': string;
+    ':focus-within': string;
+    ':focus-visible': string;
+    ':has': string;
+    ':hover': string;
+    ':in-range': string;
+    ':indeterminate': string;
+    ':invalid': string;
+    ':is': string;
+    ':lang': string;
+    ':last-child': string;
+    ':last-of-type': string;
+    ':link': string;
+    ':matches': string;
+    ':not': string;
+    ':nth-child': string;
+    ':nth-last-child': string;
+    ':nth-last-of-type': string;
+    ':nth-of-type': string;
+    ':only-child': string;
+    ':only-of-type': string;
+    ':optional': string;
+    ':out-of-range': string;
+    ':placeholder-shown': string;
+    ':required': string;
+    ':root': string;
+    ':target': string;
+    '::after': string;
+    '::backdrop': string;
+    '::before': string;
+    '::first-letter': string;
+    '::first-line': string;
+    '::marker': string;
+    '::placeholder': string;
+    '::selection': string;
+    ':valid': string;
+    ':visited': string;
+};
+/**
+ * @param {string[]} selectors
+ * @param{string[]=} browsers
+ * @param{Map<string,boolean>=} compatibilityCache
+ * @return {boolean}
+ */
+export function ensureCompatibility(selectors: string[], browsers?: string[] | undefined, compatibilityCache?: Map<string, boolean> | undefined): boolean;