refactor: url and import option (#1299)

Author: cap-Bernardito

README.md

@@ -109,16 +109,16 @@ module.exports = {
 
 |                 Name                  |            Type             |      Default       | Description                                                            |
 | :-----------------------------------: | :-------------------------: | :----------------: | :--------------------------------------------------------------------- |
-|           **[`url`](#url)**           |    `{Boolean\|Function}`    |       `true`       | Enables/Disables `url`/`image-set` functions handling                  |
-|        **[`import`](#import)**        |    `{Boolean\|Function}`    |       `true`       | Enables/Disables `@import` at-rules handling                           |
+|           **[`url`](#url)**           |     `{Boolean\|Object}`     |       `true`       | Enables/Disables `url`/`image-set` functions handling                  |
+|        **[`import`](#import)**        |     `{Boolean\|Object}`     |       `true`       | Enables/Disables `@import` at-rules handling                           |
 |       **[`modules`](#modules)**       | `{Boolean\|String\|Object}` |   `{auto: true}`   | Enables/Disables CSS Modules and their configuration                   |
 |     **[`sourceMap`](#sourcemap)**     |         `{Boolean}`         | `compiler.devtool` | Enables/Disables generation of source maps                             |
 | **[`importLoaders`](#importloaders)** |         `{Number}`          |        `0`         | Enables/Disables or setups number of loaders applied before CSS loader |
 |      **[`esModule`](#esmodule)**      |         `{Boolean}`         |       `true`       | Use ES modules syntax                                                  |
 
 ### `url`
 
-Type: `Boolean|Function`
+Type: `Boolean|Object`
 Default: `true`
 
 Enables/Disables handling the CSS functions `url` and `image-set`. If set to `false`, `css-loader` will not parse any paths specified in `url` or `image-set`. A function can also be passed to control this behavior dynamically based on the path to the asset. Starting with version [4.0.0](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md#400-2020-07-25), absolute paths are parsed based on the server root.
@@ -164,7 +164,7 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `Object`
 
 Allow to filter `url()`. All filtered `url()` will not be resolved (left in the code as they were written).
 
@@ -178,15 +178,17 @@ module.exports = {
         test: /\.css$/i,
         loader: "css-loader",
         options: {
-          url: (url, resourcePath) => {
-            // resourcePath - path to css file
+          url: {
+            filter: (url, resourcePath) => {
+              // resourcePath - path to css file
 
-            // Don't handle `img.png` urls
-            if (url.includes("img.png")) {
-              return false;
-            }
+              // Don't handle `img.png` urls
+              if (url.includes("img.png")) {
+                return false;
+              }
 
-            return true;
+              return true;
+            },
           },
         },
       },
@@ -197,7 +199,7 @@ module.exports = {
 
 ### `import`
 
-Type: `Boolean|Function`
+Type: `Boolean|Object`
 Default: `true`
 
 Enables/Disables `@import` at-rules handling.
@@ -245,7 +247,7 @@ module.exports = {
 };
 ```
 
-#### `Function`
+#### `Object`
 
 Allow to filter `@import`. All filtered `@import` will not be resolved (left in the code as they were written).
 
@@ -259,15 +261,17 @@ module.exports = {
         test: /\.css$/i,
         loader: "css-loader",
         options: {
-          import: (url, media, resourcePath) => {
-            // resourcePath - path to css file
+          import: {
+            filter: (url, media, resourcePath) => {
+              // resourcePath - path to css file
 
-            // Don't handle `style.css` import
-            if (url.includes("style.css")) {
-              return false;
-            }
+              // Don't handle `style.css` import
+              if (url.includes("style.css")) {
+                return false;
+              }
 
-            return true;
+              return true;
+            },
           },
         },
       },

src/index.js

@@ -67,7 +67,7 @@ export default async function loader(content, map, meta) {
         api: importPluginApi,
         context: this.context,
         rootContext: this.rootContext,
-        filter: getFilter(options.import, this.resourcePath),
+        filter: getFilter(options.import.filter, this.resourcePath),
         resolver,
         urlHandler: (url) =>
           stringifyRequest(
@@ -94,7 +94,7 @@ export default async function loader(content, map, meta) {
         replacements,
         context: this.context,
         rootContext: this.rootContext,
-        filter: getFilter(options.url, this.resourcePath),
+        filter: getFilter(options.url.filter, this.resourcePath),
         resolver: urlResolver,
         urlHandler: (url) => stringifyRequest(this, url),
       })

src/options.json

@@ -9,7 +9,13 @@
           "type": "boolean"
         },
         {
-          "instanceof": "Function"
+          "type": "object",
+          "properties": {
+            "filter": {
+              "instanceof": "Function"
+            }
+          },
+          "additionalProperties": false
         }
       ]
     },
@@ -20,7 +26,13 @@
           "type": "boolean"
         },
         {
-          "instanceof": "Function"
+          "type": "object",
+          "properties": {
+            "filter": {
+              "instanceof": "Function"
+            }
+          },
+          "additionalProperties": false
         }
       ]
     },

test/__snapshots__/import-option.test.js.snap

@@ -6,14 +6,48 @@ exports[`validate options should throw an error on the "esModule" option with "t
    -> Use the ES modules syntax (https://github.com/webpack-contrib/css-loader#esmodule)."
 `;
 
+exports[`validate options should throw an error on the "import" option with "() => {}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.import should be one of these:
+   boolean | object { filter? }
+   -> Enables/Disables '@import' at-rules handling (https://github.com/webpack-contrib/css-loader#import).
+   Details:
+    * options.import should be a boolean.
+    * options.import should be an object:
+      object { filter? }"
+`;
+
+exports[`validate options should throw an error on the "import" option with "[]" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.import should be one of these:
+   boolean | object { filter? }
+   -> Enables/Disables '@import' at-rules handling (https://github.com/webpack-contrib/css-loader#import).
+   Details:
+    * options.import should be a boolean.
+    * options.import should be an object:
+      object { filter? }"
+`;
+
+exports[`validate options should throw an error on the "import" option with "{"filter":true}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.import.filter should be an instance of function."
+`;
+
+exports[`validate options should throw an error on the "import" option with "{}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.import has an unknown property 'unknown'. These properties are valid:
+   object { filter? }"
+`;
+
 exports[`validate options should throw an error on the "import" option with "true" value 1`] = `
 "Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
  - options.import should be one of these:
-   boolean | function
+   boolean | object { filter? }
    -> Enables/Disables '@import' at-rules handling (https://github.com/webpack-contrib/css-loader#import).
    Details:
     * options.import should be a boolean.
-    * options.import should be an instance of function."
+    * options.import should be an object:
+      object { filter? }"
 `;
 
 exports[`validate options should throw an error on the "importLoaders" option with "2.5" value 1`] = `
@@ -278,12 +312,46 @@ exports[`validate options should throw an error on the "unknown" option with "tr
    object { url?, import?, modules?, sourceMap?, importLoaders?, esModule? }"
 `;
 
+exports[`validate options should throw an error on the "url" option with "() => {}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.url should be one of these:
+   boolean | object { filter? }
+   -> Enables/Disables 'url'/'image-set' functions handling (https://github.com/webpack-contrib/css-loader#url).
+   Details:
+    * options.url should be a boolean.
+    * options.url should be an object:
+      object { filter? }"
+`;
+
+exports[`validate options should throw an error on the "url" option with "[]" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.url should be one of these:
+   boolean | object { filter? }
+   -> Enables/Disables 'url'/'image-set' functions handling (https://github.com/webpack-contrib/css-loader#url).
+   Details:
+    * options.url should be a boolean.
+    * options.url should be an object:
+      object { filter? }"
+`;
+
+exports[`validate options should throw an error on the "url" option with "{"filter":true}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.url.filter should be an instance of function."
+`;
+
+exports[`validate options should throw an error on the "url" option with "{}" value 1`] = `
+"Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
+ - options.url has an unknown property 'unknown'. These properties are valid:
+   object { filter? }"
+`;
+
 exports[`validate options should throw an error on the "url" option with "true" value 1`] = `
 "Invalid options object. CSS Loader has been initialized using an options object that does not match the API schema.
  - options.url should be one of these:
-   boolean | function
+   boolean | object { filter? }
    -> Enables/Disables 'url'/'image-set' functions handling (https://github.com/webpack-contrib/css-loader#url).
    Details:
     * options.url should be a boolean.
-    * options.url should be an instance of function."
+    * options.url should be an object:
+      object { filter? }"
 `;

test/__snapshots__/url-option.test.js.snap

@@ -53,23 +53,25 @@ describe('"import" option', () => {
     expect(getErrors(stats)).toMatchSnapshot("errors");
   });
 
-  it('should work when "Function"', async () => {
+  it("should work with import.filter", async () => {
     const compiler = getCompiler("./import/import.js", {
-      import: (url, media, resourcePath) => {
-        expect(url).toBeDefined();
+      import: {
+        filter: (url, media, resourcePath) => {
+          expect(url).toBeDefined();
 
-        if (url === "test-nested-media.css") {
-          expect(media).toBeDefined();
-        }
+          if (url === "test-nested-media.css") {
+            expect(media).toBeDefined();
+          }
 
-        expect(resourcePath).toBeDefined();
+          expect(resourcePath).toBeDefined();
 
-        // Don't handle `test.css`
-        if (url.includes("test.css")) {
-          return false;
-        }
+          // Don't handle `test.css`
+          if (url.includes("test.css")) {
+            return false;
+          }
 
-        return true;
+          return true;
+        },
       },
     });
     const stats = await compile(compiler);

test/__snapshots__/validate-options.test.js.snap

@@ -50,21 +50,23 @@ describe('"url" option', () => {
     expect(getErrors(stats)).toMatchSnapshot("errors");
   });
 
-  it('should work with a value equal to "Function"', async () => {
+  it("should work with url.filter", async () => {
     const compiler = getCompiler("./url/url.js", {
-      url: (url, resourcePath) => {
-        expect(typeof resourcePath === "string").toBe(true);
+      url: {
+        filter: (url, resourcePath) => {
+          expect(typeof resourcePath === "string").toBe(true);
 
-        if (url.startsWith("/guide/img")) {
-          return false;
-        }
+          if (url.startsWith("/guide/img")) {
+            return false;
+          }
 
-        // Don't handle `img.png`
-        if (url.includes("img.png")) {
-          return false;
-        }
+          // Don't handle `img.png`
+          if (url.includes("img.png")) {
+            return false;
+          }
 
-        return true;
+          return true;
+        },
       },
     });
     const stats = await compile(compiler);

test/import-option.test.js

@@ -3,12 +3,12 @@ import { getCompiler, compile } from "./helpers/index";
 describe("validate options", () => {
   const tests = {
     url: {
-      success: [true, false, () => {}],
-      failure: ["true"],
+      success: [true, false, { filter: () => true }],
+      failure: ["true", [], () => {}, { filter: true }, { unknown: () => {} }],
     },
     import: {
-      success: [true, false, () => {}],
-      failure: ["true"],
+      success: [true, false, { filter: () => true }],
+      failure: ["true", [], () => {}, { filter: true }, { unknown: () => {} }],
     },
     modules: {
       success: [