feat - Allow advanced merging through mergeWithRules

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 5.2.0 / 2020-10-07
+
+- Feature - Support advanced merging cases through `mergeWithRules` #146 #149
+
 ## 5.1.4 / 2020-09-09
 
 - Fix - Expose `CustomizeRule` for TypeScript users #147
@@ -102,17 +106,17 @@ merge.smart(
     loaders: [
       {
         test: /\.js$/,
-        loaders: ["babel"],
-      },
-    ],
+        loaders: ["babel"]
+      }
+    ]
   },
   {
     loaders: [
       {
         test: /\.js$/,
-        loaders: ["react-hot", "babel"],
-      },
-    ],
+        loaders: ["react-hot", "babel"]
+      }
+    ]
   }
 );
 // will become
@@ -121,8 +125,8 @@ merge.smart(
     {
       test: /\.js$/,
       // order of second argument is respected
-      loaders: ["react-hot", "babel"],
-    },
+      loaders: ["react-hot", "babel"]
+    }
   ];
 }
 ```
@@ -183,10 +187,10 @@ const output = merge.smartStrategy(
 
 ```javascript
 const a = {
-  entry: ["foo"],
+  entry: ["foo"]
 };
 const b = {
-  entry: [],
+  entry: []
 };
 
 merge(a, b); // Yields a result, not b like before.

README.md

@@ -157,21 +157,90 @@ const output = mergeWithCustomize({
   customizeArray: unique(
     "plugins",
     ["HotModuleReplacementPlugin"],
-    (plugin) => plugin.constructor && plugin.constructor.name
-  ),
+    plugin => plugin.constructor && plugin.constructor.name
+  )
 })(
   {
-    plugins: [new webpack.HotModuleReplacementPlugin()],
+    plugins: [new webpack.HotModuleReplacementPlugin()]
   },
   {
-    plugins: [new webpack.HotModuleReplacementPlugin()],
+    plugins: [new webpack.HotModuleReplacementPlugin()]
   }
 );
 
 // Output contains only single HotModuleReplacementPlugin now and it's
 // going to be the last plugin instance.
 ```
 
+## **`mergeWithRules`**
+
+To support advanced merging needs (i.e. merging within loaders), `mergeWithRules` includes additional syntax that allows you to match fields and apply strategies to match. Consider the full example below:
+
+```javascript
+const a = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: [{ loader: "style-loader" }, { loader: "sass-loader" }]
+      }
+    ]
+  }
+};
+const b = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: [
+          {
+            loader: "style-loader",
+            options: {
+              modules: true
+            }
+          }
+        ]
+      }
+    ]
+  }
+};
+const result = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: [
+          {
+            loader: "style-loader",
+            options: {
+              modules: true
+            }
+          },
+          { loader: "sass-loader" }
+        ]
+      }
+    ]
+  }
+};
+
+assert.deepStrictEqual(
+  mergeWithRules({
+    module: {
+      rules: {
+        test: "match",
+        use: {
+          loader: "match",
+          options: "replace"
+        }
+      }
+    }
+  })(a, b),
+  result
+);
+```
+
+The way it works is that you should annotate fields to match using `match` (or `CustomizeRule.Match` if you are using TypeScript) matching your configuration structure and then use specific strategies to define how particular fields should be transformed.
+
 ## Development
 
 1. `nvm use`