feat: added types (#269)

Author: alexander-akait

package-lock.json

@@ -19,11 +19,14 @@
     "start": "npm run build -- -w",
     "clean": "del-cli dist",
     "prebuild": "npm run clean",
-    "build": "cross-env NODE_ENV=production babel src -d dist --copy-files",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir types && prettier \"types/**/*.ts\" --write && prettier types --write",
+    "build:code": "cross-env NODE_ENV=production babel src -d dist --copy-files",
+    "build": "npm-run-all -p \"build:**\"",
     "commitlint": "commitlint --from=master",
     "security": "npm audit --production",
     "lint:prettier": "prettier --list-different .",
     "lint:js": "eslint --cache .",
+    "lint:types": "tsc --pretty --noEmit",
     "lint": "npm-run-all -l -p \"lint:**\"",
     "test:only": "cross-env NODE_ENV=test jest",
     "test:watch": "npm run test:only -- --watch",
@@ -34,7 +37,8 @@
     "release": "standard-version"
   },
   "files": [
-    "dist"
+    "dist",
+    "types"
   ],
   "peerDependencies": {
     "webpack": "^5.1.0"
@@ -50,6 +54,7 @@
     "@commitlint/cli": "^15.0.0",
     "@commitlint/config-conventional": "^15.0.0",
     "@gfx/zopfli": "^1.0.15",
+    "@types/serialize-javascript": "^5.0.1",
     "@webpack-contrib/eslint-config-webpack": "^3.0.0",
     "babel-jest": "^27.0.6",
     "cross-env": "^7.0.3",
@@ -66,6 +71,7 @@
     "npm-run-all": "^4.1.5",
     "prettier": "^2.3.2",
     "standard-version": "^9.3.0",
+    "typescript": "^4.5.2",
     "webpack": "^5.51.0",
     "webpack-stats-plugin": "^1.0.3",
     "workbox-webpack-plugin": "^6.2.4"

package.json

@@ -11,9 +11,83 @@ import serialize from "serialize-javascript";
 
 import schema from "./options.json";
 
+/** @typedef {import("schema-utils/declarations/validate").Schema} Schema */
+/** @typedef {import("webpack").Compiler} Compiler */
+/** @typedef {import("webpack").Compilation} Compilation */
+/** @typedef {import("webpack").sources.Source} Source */
+/** @typedef {import("webpack").Asset} Asset */
+/** @typedef {import("webpack").WebpackError} WebpackError */
+
+/** @typedef {RegExp | string} Rule */
+
+/** @typedef {Rule[] | Rule} Rules */
+
+/**
+ * @typedef {{ [key: string]: any }} CustomOptions
+ */
+
+/**
+ * @template T
+ * @typedef {T extends infer U ? U : CustomOptions} InferDefaultType
+ */
+
+/**
+ * @template T
+ * @typedef {InferDefaultType<T>} CompressionOptions
+ */
+
+/**
+ * @template T
+ * @callback AlgorithmFunction
+ * @param {Buffer} input
+ * @param {CompressionOptions<T>} options
+ * @param {(error: Error, result: string | Buffer) => void} callback
+ */
+
+/**
+ * @typedef {{[key: string]: any}} PathData
+ */
+
+/**
+ * @typedef {string | ((fileData: PathData) => string)} Filename
+ */
+
+/**
+ * @typedef {boolean | "keep-source-map"} DeleteOriginalAssets
+ */
+
+/**
+ * @template T
+ * @typedef {Object} BasePluginOptions
+ * @property {Rules} [test]
+ * @property {Rules} [include]
+ * @property {Rules} [exclude]
+ * @property {string | AlgorithmFunction<T>} [algorithm]
+ * @property {CompressionOptions<T>} [compressionOptions]
+ * @property {number} [threshold]
+ * @property {number} [minRatio]
+ * @property {DeleteOriginalAssets} [deleteOriginalAssets]
+ * @property {Filename} [filename]
+ */
+
+/**
+ * @template T
+ * @typedef {BasePluginOptions<T> & { compressionOptions: CompressionOptions<T>, threshold: number, minRatio: number, deleteOriginalAssets: DeleteOriginalAssets, filename: Filename }} InternalPluginOptions
+ */
+
+/**
+ * @typedef {import("zlib").ZlibOptions} ZlibOptions
+ */
+
+/**
+ * @template [T=ZlibOptions]
+ */
 class CompressionPlugin {
+  /**
+   * @param {BasePluginOptions<T>} [options]
+   */
   constructor(options = {}) {
-    validate(schema, options, {
+    validate(/** @type {Schema} */ (schema), options, {
       name: "Compression Plugin",
       baseDataPath: "options",
     });
@@ -23,13 +97,17 @@ class CompressionPlugin {
       include,
       exclude,
       algorithm = "gzip",
-      compressionOptions = {},
+      compressionOptions = /** @type {CompressionOptions<T>} */ ({}),
       filename = "[path][base].gz",
       threshold = 0,
       minRatio = 0.8,
       deleteOriginalAssets = false,
     } = options;
 
+    /**
+     * @private
+     * @type {InternalPluginOptions<T>}
+     */
     this.options = {
       test,
       include,
@@ -42,12 +120,25 @@ class CompressionPlugin {
       deleteOriginalAssets,
     };
 
-    this.algorithm = this.options.algorithm;
+    /**
+     * @private
+     * @type {AlgorithmFunction<T>}
+     */
+    this.algorithm =
+      /** @type {AlgorithmFunction<T>} */
+      (this.options.algorithm);
 
     if (typeof this.algorithm === "string") {
+      /**
+       * @type {typeof import("zlib")}
+       */
       // eslint-disable-next-line global-require
       const zlib = require("zlib");
 
+      /**
+       * @private
+       * @type {AlgorithmFunction<T>}
+       */
       this.algorithm = zlib[this.algorithm];
 
       if (!this.algorithm) {
@@ -73,42 +164,62 @@ class CompressionPlugin {
                 zlib.constants.BROTLI_MAX_QUALITY,
             },
           },
-        }[algorithm] || {};
-
-      this.options.compressionOptions = {
-        ...defaultCompressionOptions,
-        ...this.options.compressionOptions,
-      };
+        }[/** @type {string} */ (algorithm)] || {};
+
+      this.options.compressionOptions =
+        /**
+         * @type {CompressionOptions<T>}
+         */
+        ({
+          .../** @type {object} */ (defaultCompressionOptions),
+          .../** @type {object} */ (this.options.compressionOptions),
+        });
     }
   }
 
+  /**
+   * @private
+   * @param {Buffer} input
+   * @returns {Promise<Buffer>}
+   */
   runCompressionAlgorithm(input) {
     return new Promise((resolve, reject) => {
       this.algorithm(
         input,
         this.options.compressionOptions,
         (error, result) => {
           if (error) {
-            return reject(error);
+            reject(error);
+
+            return;
           }
 
           if (!Buffer.isBuffer(result)) {
             // eslint-disable-next-line no-param-reassign
             result = Buffer.from(result);
           }
 
-          return resolve(result);
+          resolve(result);
         }
       );
     });
   }
 
+  /**
+   * @private
+   * @param {Compiler} compiler
+   * @param {Compilation} compilation
+   * @param {Record<string, Source>} assets
+   * @returns {Promise<void>}
+   */
   async compress(compiler, compilation, assets) {
     const cache = compilation.getCache("CompressionWebpackPlugin");
     const assetsForMinify = (
       await Promise.all(
         Object.keys(assets).map(async (name) => {
-          const { info, source } = compilation.getAsset(name);
+          const { info, source } = /** @type {Asset} */ (
+            compilation.getAsset(name)
+          );
 
           if (info.compressed) {
             return false;
@@ -124,6 +235,9 @@ class CompressionPlugin {
             return false;
           }
 
+          /**
+           * @type {string | undefined}
+           */
           let relatedName;
 
           if (typeof this.options.algorithm === "function") {
@@ -133,6 +247,9 @@ class CompressionPlugin {
                 .update(serialize(this.options.filename))
                 .digest("hex")}`;
             } else {
+              /**
+               * @type {string}
+               */
               let filenameForRelatedName = this.options.filename;
 
               const index = filenameForRelatedName.indexOf("?");
@@ -202,6 +319,7 @@ class CompressionPlugin {
     for (const asset of assetsForMinify) {
       scheduledTasks.push(
         (async () => {
+          // @ts-ignore
           const { name, source, buffer, output, cacheItem, info, relatedName } =
             asset;
 
@@ -210,7 +328,7 @@ class CompressionPlugin {
               try {
                 output.compressed = await this.runCompressionAlgorithm(buffer);
               } catch (error) {
-                compilation.errors.push(error);
+                compilation.errors.push(/** @type {WebpackError} */ (error));
 
                 return;
               }
@@ -235,16 +353,21 @@ class CompressionPlugin {
           });
           const newInfo = { compressed: true };
 
+          // TODO: possible problem when developer uses custom function, ideally we need to get parts of filname (i.e. name/base/ext/etc) in info
+          // otherwise we can't detect an asset as immutable
           if (
             info.immutable &&
+            typeof this.options.filename === "string" &&
             /(\[name]|\[base]|\[file])/.test(this.options.filename)
           ) {
+            // @ts-ignore
             newInfo.immutable = true;
           }
 
           if (this.options.deleteOriginalAssets) {
             if (this.options.deleteOriginalAssets === "keep-source-map") {
               compilation.updateAsset(name, source, {
+                // @ts-ignore
                 related: { sourceMap: null },
               });
             }
@@ -261,9 +384,13 @@ class CompressionPlugin {
       );
     }
 
-    return Promise.all(scheduledTasks);
+    await Promise.all(scheduledTasks);
   }
 
+  /**
+   * @param {Compiler} compiler
+   * @returns {void}
+   */
   apply(compiler) {
     const pluginName = this.constructor.name;
 
@@ -284,8 +411,11 @@ class CompressionPlugin {
           .tap(
             "compression-webpack-plugin",
             (compressed, { green, formatFlag }) =>
-              // eslint-disable-next-line no-undefined
-              compressed ? green(formatFlag("compressed")) : undefined
+              compressed
+                ? /** @type {Function} */ (green)(
+                    /** @type {Function} */ (formatFlag)("compressed")
+                  )
+                : ""
           );
       });
     });

src/index.js

@@ -1,4 +1,5 @@
 {
+  "type": "object",
   "additionalProperties": false,
   "definitions": {
     "Rule": {
@@ -114,6 +115,5 @@
         }
       ]
     }
-  },
-  "type": "object"
+  }
 }