feat: a generator names its file with a function too, and minify is typed as written

The public type said one function where the schema has taken a list or a descriptor since 5.10, and a filename function is what webpack's own getPath takes.

Author: alexander-akait

.changeset/generator-compression-options.md

@@ -2,4 +2,4 @@
 "minimizer-webpack-plugin": minor
 ---
 
-Add `threshold`, `minRatio` and `relatedName` to an `asset` generator, let `deleteOriginalAssets` be a function and take the original file alone, and read `minify: []` as nothing to minify rather than `false`.
+Add `threshold`, `minRatio` and `relatedName` to an `asset` generator, let `deleteOriginalAssets` be a function and take the original file alone, take a `filename` function, read `minify: []` as nothing to minify rather than `false`, and type what `minify` has long accepted.

README.md

@@ -340,6 +340,7 @@ interface minimizer {
 }
 
 type minify = minifyFn | (minifyFn | minimizer)[] | minimizer;
+// An empty array is nothing to minify.
 ```
 
 Default: `MinimizerPlugin.terserMinify`
@@ -712,7 +713,7 @@ interface generator {
   implementation: generateFn;
   options?: Record<string, any>;
   type?: "import" | "asset";
-  filename?: string;
+  filename?: string | ((pathData: any) => string);
   filter?: (name: string) => boolean;
   deleteOriginalAssets?: boolean | ((name: string) => boolean);
   threshold?: number;
@@ -818,8 +819,9 @@ new MinimizerPlugin({
       implementation: MinimizerPlugin.sharpGenerate,
       options: { encodeOptions: { webp: {} } },
       type: "asset",
-      // Optional. Without it the generator's own name for the result is used,
-      // which for `sharpGenerate` is the original with its extension replaced.
+      // Optional, a template or a function answering with one. Without it the
+      // generator's own name for the result is used, which for `sharpGenerate`
+      // is the original with its extension replaced.
       filename: "[path][name].webp",
       // Optional. Narrows what this generator reads, on top of `test`.
       filter: (name) => !name.includes("icons/"),

src/index.js

@@ -211,7 +211,7 @@ const {
  * @property {MinimizerImplementation<EXPECTED_ANY>} implementation the generator itself
  * @property {MinimizerOptions<EXPECTED_ANY>=} options options for this generator, preferred over the deprecated `generatorOptions`
  * @property {("import" | "asset")=} type `import` re-encodes a module as it is built, so the import that asked for it is renamed with it; `asset` writes a new file beside one already emitted
- * @property {string=} filename name for the generated asset, as a webpack filename template. `asset` generators only
+ * @property {(string | ((pathData: EXPECTED_ANY) => string))=} filename name for the generated asset, as a webpack filename template or a function answering with one. `asset` generators only
  * @property {((name: string) => boolean)=} filter decides per asset whether to generate from it, on top of `test`/`include`/`exclude`
  * @property {(boolean | ((name: string) => boolean))=} deleteOriginalAssets removes the asset generated from, its own file alone — whatever its `related` names stays. Written as a function it is asked per asset. `asset` generators only
  * @property {number=} threshold generate only from assets larger than this, in bytes. `asset` generators only
@@ -237,8 +237,24 @@ const {
  */
 
 /**
+ * One minimizer, written as an object stating how to run it.
  * @template T
- * @typedef {T extends import("terser").MinifyOptions ? { minify?: MinimizerImplementation<T> | undefined, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined } : { minify: MinimizerImplementation<T>, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined }} DefinedDefaultMinimizerAndOptions
+ * @typedef {object} MinimizerDescriptor
+ * @property {MinimizerImplementation<T>} implementation the minimizer itself
+ * @property {MinimizerOptions<T>=} options options for this minimizer, preferred over the deprecated `minimizerOptions`
+ * @property {((name: string, info: AssetInfo) => boolean | undefined)=} filter which assets this minimizer is offered, overriding a `filter` on the function itself
+ */
+
+/**
+ * What `minify` may be written as: one minimizer, a list of them — empty for
+ * nothing to minify — or a descriptor.
+ * @template T
+ * @typedef {MinimizerImplementation<T> | (MinimizerImplementation<T> | MinimizerDescriptor<T>)[] | MinimizerDescriptor<T>} Minify
+ */
+
+/**
+ * @template T
+ * @typedef {T extends import("terser").MinifyOptions ? { minify?: Minify<T> | undefined, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined } : { minify: Minify<T>, minimizerOptions?: MinimizerOptions<T> | undefined, terserOptions?: MinimizerOptions<T> | undefined }} DefinedDefaultMinimizerAndOptions
  */
 
 /**
@@ -1355,7 +1371,7 @@ class MinimizerPlugin {
    * @param {string | undefined} name the preset it is written under, where it has one
    * @param {EXPECTED_ANY} entry what was written there
    * @param {EXPECTED_ANY} declared what `generatorOptions` says for it
-   * @returns {{ name: string | undefined, implementation: EXPECTED_ANY, options: EXPECTED_ANY, type: string | undefined, filename: string | undefined, filter: ((name: string) => boolean) | undefined, deleteOriginalAssets: boolean | ((name: string) => boolean) | undefined, threshold: number | undefined, minRatio: number | undefined, relatedName: string | false | undefined }} the generator
+   * @returns {{ name: string | undefined, implementation: EXPECTED_ANY, options: EXPECTED_ANY, type: string | undefined, filename: string | ((pathData: EXPECTED_ANY) => string) | undefined, filter: ((name: string) => boolean) | undefined, deleteOriginalAssets: boolean | ((name: string) => boolean) | undefined, threshold: number | undefined, minRatio: number | undefined, relatedName: string | false | undefined }} the generator
    */
   describeGenerator(name, entry, declared) {
     const descriptor = isDescriptor(entry) ? entry : undefined;
@@ -2168,7 +2184,9 @@ class MinimizerPlugin {
     const written = Array.isArray(minify) ? minify : [minify];
 
     for (const [index, one] of written.entries()) {
-      const own = isDescriptor(one) ? one.options : undefined;
+      const own = isDescriptor(one)
+        ? /** @type {MinimizerDescriptor<EXPECTED_ANY>} */ (one).options
+        : undefined;
       const twice = Array.isArray(minify)
         ? getMinimizerOptionsAt(declared, index)
         : declared;

src/options.json

@@ -276,9 +276,11 @@
               "enum": ["import", "asset"]
             },
             "filename": {
-              "description": "Name for the generated asset, as a webpack filename template. `asset` generators only; by default the generator's own name for it is used.",
-              "type": "string",
-              "minLength": 1
+              "description": "Name for the generated asset, as a webpack filename template, or a function answering with one. `asset` generators only; by default the generator's own name for it is used.",
+              "anyOf": [
+                { "type": "string", "minLength": 1 },
+                { "instanceof": "Function" }
+              ]
             },
             "filter": {
               "description": "Decides per asset whether to generate from it, on top of `test`/`include`/`exclude`.",
@@ -346,9 +348,11 @@
                     "enum": ["import", "asset"]
                   },
                   "filename": {
-                    "description": "Name for the generated asset, as a webpack filename template. `asset` generators only; by default the generator's own name for it is used.",
-                    "type": "string",
-                    "minLength": 1
+                    "description": "Name for the generated asset, as a webpack filename template, or a function answering with one. `asset` generators only; by default the generator's own name for it is used.",
+                    "anyOf": [
+                      { "type": "string", "minLength": 1 },
+                      { "instanceof": "Function" }
+                    ]
                   },
                   "filter": {
                     "description": "Decides per asset whether to generate from it, on top of `test`/`include`/`exclude`.",

test/generate-option.test.js

@@ -2533,6 +2533,31 @@ describe("deleting the asset a file was written beside", () => {
     ]);
   });
 
+  it("should take a `filename` function for the name it writes", async () => {
+    const compiler = getCompiler({
+      entry: { one: path.resolve(__dirname, "./fixtures/entry.js") },
+    });
+
+    new MinimizerPlugin({
+      parallel: false,
+      test: /\.js$/i,
+      minify: [],
+      generate: {
+        implementation: (input) => ({ code: Object.values(input)[0] }),
+        type: "asset",
+        filename: (pathData) => `${pathData.filename}.gz`,
+      },
+    }).apply(compiler);
+
+    const stats = await compile(compiler);
+
+    expect(getErrors(stats)).toEqual([]);
+    expect(Object.keys(stats.compilation.assets).sort()).toEqual([
+      "one.js",
+      "one.js.gz",
+    ]);
+  });
+
   it("should not point a file written under the original's name at itself", async () => {
     const compiler = getCompiler({
       entry: { one: path.resolve(__dirname, "./fixtures/entry.js") },

types/index.d.ts

@@ -96,7 +96,7 @@ declare class MinimizerPlugin<T = import("terser").MinifyOptions> {
    * @param {string | undefined} name the preset it is written under, where it has one
    * @param {EXPECTED_ANY} entry what was written there
    * @param {EXPECTED_ANY} declared what `generatorOptions` says for it
-   * @returns {{ name: string | undefined, implementation: EXPECTED_ANY, options: EXPECTED_ANY, type: string | undefined, filename: string | undefined, filter: ((name: string) => boolean) | undefined, deleteOriginalAssets: boolean | ((name: string) => boolean) | undefined, threshold: number | undefined, minRatio: number | undefined, relatedName: string | false | undefined }} the generator
+   * @returns {{ name: string | undefined, implementation: EXPECTED_ANY, options: EXPECTED_ANY, type: string | undefined, filename: string | ((pathData: EXPECTED_ANY) => string) | undefined, filter: ((name: string) => boolean) | undefined, deleteOriginalAssets: boolean | ((name: string) => boolean) | undefined, threshold: number | undefined, minRatio: number | undefined, relatedName: string | false | undefined }} the generator
    */
   private describeGenerator;
   /**
@@ -315,6 +315,8 @@ declare namespace MinimizerPlugin {
     GeneratorDescriptor,
     Generate,
     BasePluginOptions,
+    MinimizerDescriptor,
+    Minify,
     DefinedDefaultMinimizerAndOptions,
     InternalPluginOptions,
   };
@@ -656,9 +658,9 @@ type GeneratorDescriptor = {
    */
   type?: ("import" | "asset") | undefined;
   /**
-   * name for the generated asset, as a webpack filename template. `asset` generators only
+   * name for the generated asset, as a webpack filename template or a function answering with one. `asset` generators only
    */
-  filename?: string | undefined;
+  filename?: (string | ((pathData: EXPECTED_ANY) => string)) | undefined;
   /**
    * decides per asset whether to generate from it, on top of `test`/`include`/`exclude`
    */
@@ -724,15 +726,40 @@ type BasePluginOptions = {
    */
   generatorOptions?: MinimizerOptions<EXPECTED_ANY> | undefined;
 };
+/**
+ * One minimizer, written as an object stating how to run it.
+ */
+type MinimizerDescriptor<T> = {
+  /**
+   * the minimizer itself
+   */
+  implementation: MinimizerImplementation<T>;
+  /**
+   * options for this minimizer, preferred over the deprecated `minimizerOptions`
+   */
+  options?: MinimizerOptions<T> | undefined;
+  /**
+   * which assets this minimizer is offered, overriding a `filter` on the function itself
+   */
+  filter?: ((name: string, info: AssetInfo) => boolean | undefined) | undefined;
+};
+/**
+ * What `minify` may be written as: one minimizer, a list of them — empty for
+ * nothing to minify — or a descriptor.
+ */
+type Minify<T> =
+  | MinimizerImplementation<T>
+  | (MinimizerImplementation<T> | MinimizerDescriptor<T>)[]
+  | MinimizerDescriptor<T>;
 type DefinedDefaultMinimizerAndOptions<T> =
   T extends import("terser").MinifyOptions
     ? {
-        minify?: MinimizerImplementation<T> | undefined;
+        minify?: Minify<T> | undefined;
         minimizerOptions?: MinimizerOptions<T> | undefined;
         terserOptions?: MinimizerOptions<T> | undefined;
       }
     : {
-        minify: MinimizerImplementation<T>;
+        minify: Minify<T>;
         minimizerOptions?: MinimizerOptions<T> | undefined;
         terserOptions?: MinimizerOptions<T> | undefined;
       };