feat: add the fixed preload filter

Author: webdiscus

CHANGELOG.md

@@ -1,8 +1,26 @@
 # Changelog
 
-## 4.14.0 (2025-01-19)
+## 4.15.0-beta.0 (2025-01-20)
+
+- feat: add the fixed preload filter:
+  ```ts
+  type PreloadFilter =
+    | RegExp
+    | Array<RegExp>
+    | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
+    | ((asset: { sourceFiles: Array<string>; outputFile: string }) => void | boolean); // <= BRAKING CHANGES compared to v4.14.0 (DEPRECATED)
+  ```
+
+## 4.14.0 (2025-01-19) DEPRECATED (filter API will be changed in next version)
 
 - feat: add the `filter` for the `preload` option
+  ```ts
+  type AdvancedFilter =
+    | RegExp
+    | Array<RegExp>
+    | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
+    | ((value: string) => void | true | false); // <= string argument DEPRECATED
+  ```
 
 ## 4.13.0 (2025-01-18)
 

README.md

@@ -2501,7 +2501,7 @@ Type:
 ```ts
 type Preload = Array<{
   test: RegExp;
-  filter?: AdvancedFilter;
+  filter?: PreloadFilter;
   as?: string;
   rel?: string;
   type?: string;
@@ -2510,11 +2510,11 @@ type Preload = Array<{
 ```
 
 ```ts
-type AdvancedFilter =
+type PreloadFilter =
   | RegExp
   | Array<RegExp>
   | { includes?: Array<RegExp>; excludes?: Array<RegExp> }
-  | ((value: string) => void | true | false);
+  | ((asset: { sourceFiles: Array<string>; outputFile: string }) => void | boolean);
 ```
 
 Default: `null`
@@ -2572,9 +2572,12 @@ For example:
 By default, all files matching the `test` option will be preloaded. 
 You can use the `filter` to preload specific files individually.
 
-The `AdvancedFilter` type provides a versatile way to define filtering logic, 
+The `PreloadFilter` type provides a versatile way to define filtering logic, 
 from simple patterns to complex inclusion and exclusion criteria. 
 
+The filter RegExp matches both the source and output files.
+If you need to match source or output files separately use the filter function, see below.
+
 Here's are supported filter formats:
 
 - `RegExp`\
@@ -2607,12 +2610,40 @@ Here's are supported filter formats:
     excludes: [/exclude-this/,],
   }
   ```
-- `(value: string) => void | false`\
+- `(asset: { sourceFiles: Array<string>; outputFile: string }) => void | boolean`\
   Custom logic provides maximum flexibility for filtering that cannot be expressed with regular expressions.\
-  A custom filter function takes an output asset file as input and decides whether it matches based on the return value:
+  A custom filter function takes the source files and the output asset file as input, and decides whether they match based on the return value:
   - Returns `void` (`undefined`) or `true` if the value passes the filter.
   - Returns `false` if the value fails the filter.
 
+> [!NOTE]
+> Only `style` type may have many files in the `sourceFiles`.\
+> If many styles are imported in one JS file, then all extracted CSS will be squashed into single CSS file with the name of a JS parent file. 
+> In this case the `sourceFiles` will have many files.
+> 
+> Usage for `style` type:
+> ```js
+> {
+>   test: /\.(s?css|less)$/,
+>   filter: ({ sourceFiles, outputFile }) => {
+>     return !sourceFiles.some((sourceFile) => /noPreload/.test(sourceFile));
+>   },
+>   as: 'style',
+> },
+> ```
+> 
+> All other types have only one file in the `sourceFiles` array.
+> You can use the argument destructor to extract only first source file.
+> 
+> Usage for all other types:
+> ```js
+> {
+>   test: /\.(js|ts)$/,
+>   filter: ({ sourceFiles: [sourceFile], outputFile }) => !/noPreload/.test(outputFile),
+>   as: 'script',
+> },
+> ```
+
 For example, preload all JS files except dynamically imported (async chunks).
 
 There is the _app.js_:
@@ -2634,6 +2665,7 @@ preload: [
   {
     test: /\.(js|ts)$/,
     filter: {
+      // matches source and output files
       excludes: [/asyncChunk/],
     },
     as: 'script',
@@ -2646,7 +2678,7 @@ The same effect using the `filter` function:
 preload: [
   {
     test: /\.(js|ts)$/,
-    filter: (assetFile) => !/asyncChunk/.test(assetFile),
+    filter: ({ sourceFiles: [sourceFile], outputFile }) => !/asyncChunk/.test(sourceFile)),
     as: 'script',
   },
 ],

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-bundler-webpack-plugin",
-  "version": "4.14.0",
+  "version": "4.15.0-beta.0",
   "description": "Generates complete single-page or multi-page website from source assets. Build-in support for Markdown, Eta, EJS, Handlebars, Nunjucks, Pug. Alternative to html-webpack-plugin.",
   "keywords": [
     "html",

src/Plugin/Collection.js

@@ -341,25 +341,25 @@ class Collection {
             injectedChunks.add(chunkFile);
           }
 
-          const assetFile = this.pluginOption.getAssetOutputFile(chunkFile, entryFile);
           const inline = this.pluginOption.isInlineJs(resource, chunkFile);
+          const assetFile = this.pluginOption.getAssetOutputFile(chunkFile, entryFile);
 
           splitChunkFiles.add(chunkFile);
           data.chunks.push({ inline, chunkFile, assetFile });
         }
 
         // dynamic imported chunks
-        for (let chunkFile of childrenFiles) {
+        for (let { sourceFile, outputFile: chunkFile } of childrenFiles) {
           if (hasChunks) {
             if (injectedChunks.has(chunkFile)) continue;
             injectedChunks.add(chunkFile);
           }
 
-          const assetFile = this.pluginOption.getAssetOutputFile(chunkFile, entryFile);
           const inline = this.pluginOption.isInlineJs(resource, chunkFile);
+          const assetFile = this.pluginOption.getAssetOutputFile(chunkFile, entryFile);
 
           splitChunkFiles.add(chunkFile);
-          data.children.push({ inline, chunkFile, assetFile });
+          data.children.push({ inline, chunkFile, assetFile, sourceFile });
         }
 
         const entryData = this.data.get(entryFile);
@@ -390,14 +390,24 @@ class Collection {
 
   /**
    * @param {Entrypoint} entrypoint
-   * @return {Array<string>}
+   * @return {Array<{sourceFile: string, outputFile: string}>}
    */
   #getChildrenFiles(entrypoint) {
     let files = [];
     const children = entrypoint.getChildren();
 
     for (const chunkGroup of children) {
-      let chunkFiles = chunkGroup.getFiles();
+      // Note: there is no legal way to get the source file of the asyncChunk
+      // except using the private property `_modulePreOrderIndices`.
+      const [firsModule] = chunkGroup._modulePreOrderIndices.entries().next().value;
+
+      // The first module in the modulePreOrderIndices is the self module of the imported asyncChunk,
+      // other modules are dependencies imported in the first module.
+      // This is very strange structure, but other not exists.
+      const sourceFile = firsModule.resource;
+
+      let chunkFiles = chunkGroup.getFiles().map((value) => ({ sourceFile, outputFile: value }));
+
       if (chunkFiles) {
         files.push(...chunkFiles);
       }

src/Plugin/Option.js

@@ -759,7 +759,7 @@ class Option {
    * Normalize the filter option defined by user and create inner structure of one.
    *
    * @param {RegExp} test
-   * @param {AdvancedFilter} filter
+   * @param {PreloadFilter} filter
    * @return {{includes: RegExp[], excludes: RegExp[], fn: function}}
    */
   normalizeAdvancedFiler(test, filter) {
@@ -795,7 +795,7 @@ class Option {
   /**
    * Apply the advanced filter to a value.
    *
-   * @param {string} value
+   * @param {string | {sourceFiles: Array<string>, outputFile: string}} value
    * @param {NormalizedAdvancedFilter} filter
    * @return {boolean}
    */
@@ -804,9 +804,17 @@ class Option {
 
     const hasIncludes = includes.length > 0;
     const hasExcludes = excludes.length > 0;
+    const values = [];
 
-    const isIncluded = !hasIncludes || includes.some((regex) => regex.test(value));
-    const isExcluded = hasExcludes && excludes.some((regex) => regex.test(value));
+    if (typeof filter === 'string') {
+      values.push(value);
+    } else {
+      if ('sourceFiles' in value) values.push(...value.sourceFiles);
+      if ('outputFile' in value) values.push(value.outputFile);
+    }
+
+    const isIncluded = !hasIncludes || includes.some((regex) => values.some((value) => regex.test(value)));
+    const isExcluded = hasExcludes && excludes.some((regex) => values.some((value) => regex.test(value)));
 
     return isIncluded && !isExcluded && fn(value) !== false;
   }

src/Plugin/Preload.js

@@ -151,21 +151,34 @@ class Preload {
         if (Array.isArray(item.chunks)) {
           // js
           for (let { chunkFile, assetFile } of item.chunks) {
-            if (this.pluginOption.applyAdvancedFiler(assetFile, conf._opts.filter)) {
+            // sourceFiles contain only one file
+            let sourceFiles = [item.resource];
+            let outputFile = assetFile;
+
+            if (this.pluginOption.applyAdvancedFiler({ sourceFiles, outputFile }, conf._opts.filter)) {
               preloadAssets.set(assetFile, conf._opts);
             }
           }
         } else {
           // css, images, fonts, etc
-          if (this.pluginOption.applyAdvancedFiler(item.assetFile, conf._opts.filter)) {
+          // sourceFiles may contain many file, when many style files are imported in a JS file,
+          // then all generated CSS contents will be squashed into one CSS file
+          let sourceFiles = Array.isArray(item.resource) ? item.resource : [item.resource];
+          let outputFile = item.assetFile;
+
+          if (this.pluginOption.applyAdvancedFiler({ sourceFiles, outputFile }, conf._opts.filter)) {
             preloadAssets.set(item.assetFile, conf._opts);
           }
         }
 
         // dynamic imported modules, asyncChunks
         if (Array.isArray(item.children)) {
-          for (let { chunkFile, assetFile } of item.children) {
-            if (this.pluginOption.applyAdvancedFiler(assetFile, conf._opts.filter)) {
+          for (let { chunkFile, assetFile, sourceFile } of item.children) {
+            // sourceFiles contain only one file
+            let sourceFiles = [sourceFile];
+            let outputFile = assetFile;
+
+            if (this.pluginOption.applyAdvancedFiler({ sourceFiles, outputFile }, conf._opts.filter)) {
               preloadAssets.set(assetFile, conf._opts);
             }
           }
@@ -180,12 +193,14 @@ class Preload {
           const conf = options.find(({ test }) => test.test(assetItem.resource));
           if (!conf) continue;
 
-          let preloadFile = assetItem.issuer
+          // sourceFiles contain only one file
+          let sourceFiles = [assetItem.resource];
+          let outputFile = assetItem.issuer
             ? this.getPreloadFile(data.entry, assetItem.issuer, assetItem.assetFile)
             : assetItem.assetFile;
 
-          if (this.pluginOption.applyAdvancedFiler(preloadFile, conf._opts.filter)) {
-            preloadAssets.set(preloadFile, conf._opts);
+          if (this.pluginOption.applyAdvancedFiler({ sourceFiles, outputFile }, conf._opts.filter)) {
+            preloadAssets.set(outputFile, conf._opts);
           }
         }
       }

test/cases/option-preload-dynamic-import-filter-fn/expected/css/main.5b01e96e.css

@@ -0,0 +1,12 @@
+@font-face {
+  font-family: 'OpenSans';
+  src: url(../fonts/open-sans-regular.woff2) format('woff2');
+  font-style: normal;
+}
+
+h1 {
+  color: orangered;
+}
+.module-b {
+  color: chartreuse;
+}

test/cases/option-preload-dynamic-import-filter-fn/expected/css/style.0d25913e.css

@@ -0,0 +1,9 @@
+@font-face {
+  font-family: 'OpenSans';
+  src: url(../fonts/open-sans-regular.woff2) format('woff2');
+  font-style: normal;
+}
+
+h1 {
+  color: orangered;
+}

test/cases/option-preload-dynamic-import-filter-fn/expected/fonts/open-sans-regular.woff2

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Test</title>
+    <link rel="preload" href="../js/main.9e75183b.js" as="script">
+    <link rel="preload" href="../js/module1.chunk.js" as="script">
+    <link rel="preload" href="../css/style.0d25913e.css" as="style">
+    <link rel="preload" href="../fonts/open-sans-regular.woff2" as="font" type="font/woff2" crossorigin>
+    <link href="../css/style.0d25913e.css" rel="stylesheet">
+    <link href="../css/main.5b01e96e.css" rel="stylesheet">
+<script src="../js/main.9e75183b.js" defer="defer"></script>
+  </head>
+  <body>
+    <h1>Hello World!</h1>
+    <script src="../js/noPreload.2382a7e6.js" defer="defer"></script>
+  </body>
+</html>