html-minifier-next 3.0.0 → 3.2.0

package/README.md

@@ -1,7 +1,6 @@
 # HTML Minifier Next
 
-[![npm version](https://img.shields.io/npm/v/html-minifier-next.svg)](https://www.npmjs.com/package/html-minifier-next)
-[![Build status](https://github.com/j9t/html-minifier-next/workflows/Tests/badge.svg)](https://github.com/j9t/html-minifier-next/actions)
+[![npm version](https://img.shields.io/npm/v/html-minifier-next.svg)](https://www.npmjs.com/package/html-minifier-next) [![Build status](https://github.com/j9t/html-minifier-next/workflows/Tests/badge.svg)](https://github.com/j9t/html-minifier-next/actions)
 
 HTML Minifier Next (HMN) is a highly **configurable, well-tested, JavaScript-based HTML minifier**.
 
@@ -21,35 +20,9 @@ From npm for programmatic use:
 npm i html-minifier-next
 ```
 
-## Usage
+## General usage
 
-**Note** that almost all options are disabled by default. Experiment and find what works best for you and your project.
-
-**Sample command line:**
-
-```bash
-html-minifier-next --collapse-whitespace --remove-comments --minify-js true --input-dir=. --output-dir=example
-```
-
-**Process specific file extensions:**
-
-```bash
-# Process only HTML files (CLI method)
-html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext=html
-
-# Process multiple file extensions (CLI method)
-html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext=html,htm,php
-
-# Using configuration file that sets `fileExt` (e.g., `"fileExt": "html,htm"`)
-html-minifier-next --config-file=html-minifier.json --input-dir=src --output-dir=dist
-
-# Process all files (default behavior)
-html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist
-# Note: When processing all files, non-HTML files will also be read as UTF‑8 and passed to the minifier.
-# Consider restricting with “--file-ext” to avoid touching binaries (e.g., images, archives).
-```
-
-### CLI options
+### CLI
 
 Use `html-minifier-next --help` to check all available options:
 
@@ -58,8 +31,11 @@ Use `html-minifier-next --help` to check all available options:
 | `--input-dir <dir>` | Specify an input directory | `--input-dir=src` |
 | `--output-dir <dir>` | Specify an output directory | `--output-dir=dist` |
 | `--file-ext <extensions>` | Specify file extension(s) to process (overrides config file setting) | `--file-ext=html`, `--file-ext=html,htm,php`, `--file-ext="html, htm, php"` |
-| `-o --output <file>` | Specify output file (single file mode) | `-o minified.html` |
-| `-c --config-file <file>` | Use a configuration file | `--config-file=html-minifier.json` |
+| `-o <file>`, `--output <file>` | Specify output file (reads from file arguments or STDIN) | File to file: `html-minifier-next input.html -o output.html`<br>Pipe to file: `cat input.html \| html-minifier-next -o output.html`<br>File to STDOUT: `html-minifier-next input.html` |
+| `-c <file>`, `--config-file <file>` | Use a configuration file | `--config-file=html-minifier.json` |
+| `-v`, `--verbose` | Show detailed processing information (active options, file statistics) | `html-minifier-next --input-dir=src --output-dir=dist --verbose --collapse-whitespace` |
+| `-d`, `--dry` | Dry run: Process and report statistics without writing output | `html-minifier-next input.html --dry --collapse-whitespace` |
+| `-V`, `--version` | Output the version number | `html-minifier-next --version` |
 
 ### Configuration file
 
@@ -123,7 +99,62 @@ const { minify } = require('html-minifier-next');
 
 See [the original blog post](http://perfectionkills.com/experimenting-with-html-minifier) for details of [how it works](http://perfectionkills.com/experimenting-with-html-minifier#how_it_works), [description of each option](http://perfectionkills.com/experimenting-with-html-minifier#options), [testing results](http://perfectionkills.com/experimenting-with-html-minifier#field_testing), and [conclusions](http://perfectionkills.com/experimenting-with-html-minifier#cost_and_benefits).
 
-For lint-like capabilities take a look at [HTMLLint](https://github.com/kangax/html-lint).
+For lint-like capabilities, take a look at [HTMLLint](https://github.com/kangax/html-lint).
+
+## Options quick reference
+
+Most of the options are disabled by default. Experiment and find what works best for you and your project.
+
+Options can be used in config files (camelCase) or via CLI flags (kebab-case with `--` prefix). Options that default to `true` use `--no-` prefix in CLI to disable them.
+
+| Option (config/CLI) | Description | Default |
+| --- | --- | --- |
+| `caseSensitive`<br>`--case-sensitive` | Treat attributes in case-sensitive manner (useful for custom HTML elements) | `false` |
+| `collapseBooleanAttributes`<br>`--collapse-boolean-attributes` | [Omit attribute values from boolean attributes](http://perfectionkills.com/experimenting-with-html-minifier#collapse_boolean_attributes) | `false` |
+| `collapseInlineTagWhitespace`<br>`--collapse-inline-tag-whitespace` | Don’t leave any spaces between `display: inline;` elements when collapsing—use with `collapseWhitespace=true` | `false` |
+| `collapseWhitespace`<br>`--collapse-whitespace` | [Collapse whitespace that contributes to text nodes in a document tree](http://perfectionkills.com/experimenting-with-html-minifier#collapse_whitespace) | `false` |
+| `conservativeCollapse`<br>`--conservative-collapse` | Always collapse to 1 space (never remove it entirely)—use with `collapseWhitespace=true` | `false` |
+| `continueOnParseError`<br>`--continue-on-parse-error` | [Handle parse errors](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors) instead of aborting | `false` |
+| `customAttrAssign`<br>`--custom-attr-assign` | Arrays of regexes that allow to support custom attribute assign expressions (e.g., `<div flex?="{{mode != cover}}"></div>`) | `[]` |
+| `customAttrCollapse`<br>`--custom-attr-collapse` | Regex that specifies custom attribute to strip newlines from (e.g., `/ng-class/`) | |
+| `customAttrSurround`<br>`--custom-attr-surround` | Arrays of regexes that allow to support custom attribute surround expressions (e.g., `<input {{#if value}}checked="checked"{{/if}}>`) | `[]` |
+| `customEventAttributes`<br>`--custom-event-attributes` | Arrays of regexes that allow to support custom event attributes for `minifyJS` (e.g., `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
+| `customFragmentQuantifierLimit`<br>`--custom-fragment-quantifier-limit` | Set maximum quantifier limit for custom fragments to prevent ReDoS attacks | `200` |
+| `decodeEntities`<br>`--decode-entities` | Use direct Unicode characters whenever possible | `false` |
+| `html5`<br>`--no-html5` | Parse input according to the HTML specification | `true` |
+| `ignoreCustomComments`<br>`--ignore-custom-comments` | Array of regexes that allow to ignore certain comments, when matched | `[ /^!/, /^\s*#/ ]` |
+| `ignoreCustomFragments`<br>`--ignore-custom-fragments` | Array of regexes that allow to ignore certain fragments, when matched (e.g., `<?php … ?>`, `{{ … }}`, etc.) | `[ /<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/ ]` |
+| `includeAutoGeneratedTags`<br>`--no-include-auto-generated-tags` | Insert elements generated by HTML parser | `true` |
+| `inlineCustomElements`<br>`--inline-custom-elements` | Array of names of custom elements which are inline | `[]` |
+| `keepClosingSlash`<br>`--keep-closing-slash` | Keep the trailing slash on void elements | `false` |
+| `maxInputLength`<br>`--max-input-length` | Maximum input length to prevent ReDoS attacks (disabled by default) | `undefined` |
+| `maxLineLength`<br>`--max-line-length` | Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points | |
+| `minifyCSS`<br>`--minify-css` | Minify CSS in `style` elements and `style` attributes (uses [clean-css](https://github.com/jakubpawlowicz/clean-css)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
+| `minifyJS`<br>`--minify-js` | Minify JavaScript in `script` elements and event attributes (uses [Terser](https://github.com/terser/terser)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
+| `minifyURLs`<br>`--minify-urls` | Minify URLs in various attributes (uses [relateurl](https://github.com/stevenvachon/relateurl)) | `false` (could be `String`, `Object`, `Function(text)`, `async Function(text)`) |
+| `noNewlinesBeforeTagClose`<br>`--no-newlines-before-tag-close` | Never add a newline before a tag that closes an element | `false` |
+| `preserveLineBreaks`<br>`--preserve-line-breaks` | Always collapse to 1 line break (never remove it entirely) when whitespace between tags includes a line break—use with `collapseWhitespace=true` | `false` |
+| `preventAttributesEscaping`<br>`--prevent-attributes-escaping` | Prevents the escaping of the values of attributes | `false` |
+| `processConditionalComments`<br>`--process-conditional-comments` | Process contents of conditional comments through minifier | `false` |
+| `processScripts`<br>`--process-scripts` | Array of strings corresponding to types of `script` elements to process through minifier (e.g., `text/ng-template`, `text/x-handlebars-template`, etc.) | `[]` |
+| `quoteCharacter`<br>`--quote-character` | Type of quote to use for attribute values (`'` or `"`) | |
+| `removeAttributeQuotes`<br>`--remove-attribute-quotes` | [Remove quotes around attributes when possible](http://perfectionkills.com/experimenting-with-html-minifier#remove_attribute_quotes) | `false` |
+| `removeComments`<br>`--remove-comments` | [Strip HTML comments](http://perfectionkills.com/experimenting-with-html-minifier#remove_comments) | `false` |
+| `removeEmptyAttributes`<br>`--remove-empty-attributes` | [Remove all attributes with whitespace-only values](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
+| `removeEmptyElements`<br>`--remove-empty-elements` | [Remove all elements with empty contents](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_elements) | `false` |
+| `removeOptionalTags`<br>`--remove-optional-tags` | [Remove optional tags](http://perfectionkills.com/experimenting-with-html-minifier#remove_optional_tags) | `false` |
+| `removeRedundantAttributes`<br>`--remove-redundant-attributes` | [Remove attributes when value matches default](https://meiert.com/blog/optional-html/#toc-attribute-values) | `false` |
+| `removeScriptTypeAttributes`<br>`--remove-script-type-attributes` | Remove `type="text/javascript"` from `script` elements; other `type` attribute values are left intact | `false` |
+| `removeStyleLinkTypeAttributes`<br>`--remove-style-link-type-attributes` | Remove `type="text/css"` from `style` and `link` elements; other `type` attribute values are left intact | `false` |
+| `removeTagWhitespace`<br>`--remove-tag-whitespace` | Remove space between attributes whenever possible; **note that this will result in invalid HTML** | `false` |
+| `sortAttributes`<br>`--sort-attributes` | [Sort attributes by frequency](#sorting-attributes-and-style-classes) | `false` |
+| `sortClassName`<br>`--sort-class-name` | [Sort style classes by frequency](#sorting-attributes-and-style-classes) | `false` |
+| `trimCustomFragments`<br>`--trim-custom-fragments` | Trim whitespace around `ignoreCustomFragments` | `false` |
+| `useShortDoctype`<br>`--use-short-doctype` | [Replaces the doctype with the short (HTML) doctype](http://perfectionkills.com/experimenting-with-html-minifier#use_short_doctype) | `false` |
+
+### Sorting attributes and style classes
+
+Minifier options like `sortAttributes` and `sortClassName` won’t impact the plain‑text size of the output. However, they form long, repetitive character chains that should improve the compression ratio of gzip used for HTTP.
 
 ## Minification comparison
 
@@ -151,58 +182,63 @@ How does HTML Minifier Next compare to other solutions, like [minimize](https://
 | [United Nations](https://www.un.org/en/) | 151 | **114** | 130 | 123 | 121 | 124 |
 | [W3C](https://www.w3.org/) | 50 | **36** | 41 | 39 | 39 | 39 |
 
-## Options quick reference
+## Examples
 
-Most of the options are disabled by default.
+### CLI
 
-| Option | Description | Default |
-| --- | --- | --- |
-| `caseSensitive` | Treat attributes in case-sensitive manner (useful for custom HTML elements) | `false` |
-| `collapseBooleanAttributes` | [Omit attribute values from boolean attributes](http://perfectionkills.com/experimenting-with-html-minifier#collapse_boolean_attributes) | `false` |
-| `customFragmentQuantifierLimit` | Set maximum quantifier limit for custom fragments to prevent ReDoS attacks | `200` |
-| `collapseInlineTagWhitespace` | Don’t leave any spaces between `display: inline;` elements when collapsing—use with `collapseWhitespace=true` | `false` |
-| `collapseWhitespace` | [Collapse whitespace that contributes to text nodes in a document tree](http://perfectionkills.com/experimenting-with-html-minifier#collapse_whitespace) | `false` |
-| `conservativeCollapse` | Always collapse to 1 space (never remove it entirely)—use with `collapseWhitespace=true` | `false` |
-| `continueOnParseError` | [Handle parse errors](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors) instead of aborting | `false` |
-| `customAttrAssign` | Arrays of regexes that allow to support custom attribute assign expressions (e.g., `'<div flex?="{{mode != cover}}"></div>'`) | `[]` |
-| `customAttrCollapse` | Regex that specifies custom attribute to strip newlines from (e.g., `/ng-class/`) | |
-| `customAttrSurround` | Arrays of regexes that allow to support custom attribute surround expressions (e.g., `<input {{#if value}}checked="checked"{{/if}}>`) | `[]` |
-| `customEventAttributes` | Arrays of regexes that allow to support custom event attributes for `minifyJS` (e.g., `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
-| `decodeEntities` | Use direct Unicode characters whenever possible | `false` |
-| `html5` | Parse input according to the HTML specification | `true` |
-| `ignoreCustomComments` | Array of regexes that allow to ignore certain comments, when matched | `[ /^!/, /^\s*#/ ]` |
-| `ignoreCustomFragments` | Array of regexes that allow to ignore certain fragments, when matched (e.g., `<?php … ?>`, `{{ … }}`, etc.) | `[ /<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/ ]` |
-| `includeAutoGeneratedTags` | Insert elements generated by HTML parser | `true` |
-| `inlineCustomElements` | Array of names of custom elements which are inline | `[]` |
-| `keepClosingSlash` | Keep the trailing slash on void elements | `false` |
-| `maxInputLength` | Maximum input length to prevent ReDoS attacks (disabled by default) | `undefined` |
-| `maxLineLength` | Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points | |
-| `minifyCSS` | Minify CSS in `style` elements and `style` attributes (uses [clean-css](https://github.com/jakubpawlowicz/clean-css)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
-| `minifyJS` | Minify JavaScript in `script` elements and event attributes (uses [Terser](https://github.com/terser/terser)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
-| `minifyURLs` | Minify URLs in various attributes (uses [relateurl](https://github.com/stevenvachon/relateurl)) | `false` (could be `String`, `Object`, `Function(text)`, `async Function(text)`) |
-| `noNewlinesBeforeTagClose` | Never add a newline before a tag that closes an element | `false` |
-| `preserveLineBreaks` | Always collapse to 1 line break (never remove it entirely) when whitespace between tags includes a line break—use with `collapseWhitespace=true` | `false` |
-| `preventAttributesEscaping` | Prevents the escaping of the values of attributes | `false` |
-| `processConditionalComments` | Process contents of conditional comments through minifier | `false` |
-| `processScripts` | Array of strings corresponding to types of `script` elements to process through minifier (e.g., `text/ng-template`, `text/x-handlebars-template`, etc.) | `[]` |
-| `quoteCharacter` | Type of quote to use for attribute values (`'` or `"`) | |
-| `removeAttributeQuotes` | [Remove quotes around attributes when possible](http://perfectionkills.com/experimenting-with-html-minifier#remove_attribute_quotes) | `false` |
-| `removeComments` | [Strip HTML comments](http://perfectionkills.com/experimenting-with-html-minifier#remove_comments) | `false` |
-| `removeEmptyAttributes` | [Remove all attributes with whitespace-only values](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
-| `removeEmptyElements` | [Remove all elements with empty contents](http://perfectionkills.com/experimenting-with-html-minifier#remove_empty_elements) | `false` |
-| `removeOptionalTags` | [Remove optional tags](http://perfectionkills.com/experimenting-with-html-minifier#remove_optional_tags) | `false` |
-| `removeRedundantAttributes` | [Remove attributes when value matches default](https://meiert.com/blog/optional-html/#toc-attribute-values) | `false` |
-| `removeScriptTypeAttributes` | Remove `type="text/javascript"` from `script` elements; other `type` attribute values are left intact | `false` |
-| `removeStyleLinkTypeAttributes`| Remove `type="text/css"` from `style` and `link` elements; other `type` attribute values are left intact | `false` |
-| `removeTagWhitespace` | Remove space between attributes whenever possible; **note that this will result in invalid HTML** | `false` |
-| `sortAttributes` | [Sort attributes by frequency](#sorting-attributes-and-style-classes) | `false` |
-| `sortClassName` | [Sort style classes by frequency](#sorting-attributes-and-style-classes) | `false` |
-| `trimCustomFragments` | Trim whitespace around `ignoreCustomFragments` | `false` |
-| `useShortDoctype` | [Replaces the doctype with the short (HTML) doctype](http://perfectionkills.com/experimenting-with-html-minifier#use_short_doctype) | `false` |
+**Sample command line:**
 
-### Sorting attributes and style classes
+```bash
+html-minifier-next --collapse-whitespace --remove-comments --minify-js true --input-dir=. --output-dir=example
+```
 
-Minifier options like `sortAttributes` and `sortClassName` won’t impact the plain‑text size of the output. However, they form long, repetitive character chains that should improve the compression ratio of gzip used for HTTP.
+**Process specific file extensions:**
+
+```bash
+# Process only HTML files
+html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext=html
+
+# Process multiple file extensions
+html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext=html,htm,php
+
+# Using configuration file that sets `fileExt` (e.g., `"fileExt": "html,htm"`)
+html-minifier-next --config-file=html-minifier.json --input-dir=src --output-dir=dist
+
+# Process all files (default behavior)
+html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist
+# Note: When processing all files, non-HTML files will also be read as UTF‑8 and passed to the minifier
+# Consider restricting with `--file-ext` to avoid touching binaries (e.g., images, archives)
+```
+
+**Dry run mode (preview outcome without writing files):**
+
+```bash
+# Preview with output file
+html-minifier-next input.html -o output.html --dry --collapse-whitespace
+
+# Preview directory processing with statistics per file and total
+html-minifier-next --input-dir=src --output-dir=dist --dry --collapse-whitespace
+# Output: [DRY RUN] Would process directory: src → dist
+#   index.html: 1,234 → 892 bytes (-342, 27.7%)
+#   about.html: 2,100 → 1,654 bytes (-446, 21.2%)
+# ---
+# Total: 3,334 → 2,546 bytes (-788, 23.6%)
+```
+
+**Verbose mode (show detailed processing information):**
+
+```bash
+# Show processing details while minifying
+html-minifier-next --input-dir=src --output-dir=dist --verbose --collapse-whitespace
+# Output: Options: collapseWhitespace, html5, includeAutoGeneratedTags
+#   ✓ src/index.html: 1,234 → 892 bytes (-342, 27.7%)
+#   ✓ src/about.html: 2,100 → 1,654 bytes (-446, 21.2%)
+# ---
+# Total: 3,334 → 2,546 bytes (-788, 23.6%)
+
+# Note: `--dry` automatically enables verbose output
+html-minifier-next --input-dir=src --output-dir=dist --dry --collapse-whitespace
+```
 
 ## Special cases
 
@@ -283,7 +319,9 @@ ignoreCustomFragments: [/\{\{[\s\S]{0,500}?\}\}/]
 
 **Important:** When using custom `ignoreCustomFragments`, the minifier automatically applies bounded quantifiers to prevent ReDoS attacks, but you can also write safer patterns yourself using explicit bounds.
 
-## Running benchmarks
+## Running HTML Minifier Next
+
+### Benchmarks
 
 Benchmarks for minified HTML:
 
@@ -293,7 +331,7 @@ npm install
 npm run benchmarks
 ```
 
-## Running local server
+## Local server
 
 ```shell
 npm run serve

package/cli.js

@@ -27,6 +27,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { pathToFileURL } from 'url';
 import { createRequire } from 'module';
 import { camelCase, paramCase } from 'change-case';
 import { Command } from 'commander';
@@ -44,6 +45,14 @@ function fatal(message) {
   process.exit(1);
 }
 
+// Handle broken pipe (e.g., when piping to `head`)
+process.stdout.on('error', (err) => {
+  if (err && err.code === 'EPIPE') {
+    process.exit(0);
+  }
+  fatal('STDOUT error\n' + (err && err.message ? err.message : String(err)));
+});
+
 /**
  * JSON does not support regexes, so, e.g., JSON.parse() will not create
  * a RegExp from the JSON value `[ "/matchString/" ]`, which is
@@ -60,7 +69,7 @@ function fatal(message) {
  * search string, the user would need to enclose the expression in a
  * second set of slashes:
  *
- *    --customAttrSrround "[\"//matchString//\"]"
+ *    --customAttrSurround "[\"//matchString//\"]"
  */
 function parseRegExp(value) {
   if (value) {
@@ -73,8 +82,8 @@ function parseJSON(value) {
     try {
       return JSON.parse(value);
     } catch {
-      if (/^{/.test(value)) {
-        fatal('Could not parse JSON value \'' + value + '\'');
+      if (/^\s*[{[]/.test(value)) {
+        fatal('Could not parse JSON value `' + value + '`');
       }
       return value;
     }
@@ -95,10 +104,20 @@ function parseJSONRegExpArray(value) {
 
 const parseString = value => value;
 
+const parseValidInt = (optionName) => (value) => {
+  const s = String(value).trim();
+  // Accept only non-negative whole integers
+  if (!/^\d+$/.test(s)) {
+    fatal(`Invalid number for \`--${paramCase(optionName)}: "${value}"\``);
+  }
+  const num = Number(s);
+  return num;
+};
+
 const mainOptions = {
   caseSensitive: 'Treat attributes in case-sensitive manner (useful for custom HTML elements)',
   collapseBooleanAttributes: 'Omit attribute values from boolean attributes',
-  customFragmentQuantifierLimit: ['Set maximum quantifier limit for custom fragments to prevent ReDoS attacks (default: 200)', parseInt],
+  customFragmentQuantifierLimit: ['Set maximum quantifier limit for custom fragments to prevent ReDoS attacks (default: 200)', parseValidInt('customFragmentQuantifierLimit')],
   collapseInlineTagWhitespace: 'Don’t leave any spaces between “display: inline;” elements when collapsing—use with “collapseWhitespace=true”',
   collapseWhitespace: 'Collapse whitespace that contributes to text nodes in a document tree',
   conservativeCollapse: 'Always collapse to 1 space (never remove it entirely)—use with “collapseWhitespace=true”',
@@ -114,8 +133,8 @@ const mainOptions = {
   includeAutoGeneratedTags: 'Insert elements generated by HTML parser',
   inlineCustomElements: ['Array of names of custom elements which are inline', parseJSONArray],
   keepClosingSlash: 'Keep the trailing slash on void elements',
-  maxInputLength: ['Maximum input length to prevent ReDoS attacks', parseInt],
-  maxLineLength: ['Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points', parseInt],
+  maxInputLength: ['Maximum input length to prevent ReDoS attacks', parseValidInt('maxInputLength')],
+  maxLineLength: ['Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points', parseValidInt('maxLineLength')],
   minifyCSS: ['Minify CSS in “style” elements and “style” attributes (uses clean-css)', parseJSON],
   minifyJS: ['Minify JavaScript in “script” elements and event attributes (uses Terser)', parseJSON],
   minifyURLs: ['Minify URLs in various attributes (uses relateurl)', parseJSON],
@@ -154,7 +173,9 @@ mainOptionKeys.forEach(function (key) {
     program.option('--' + paramCase(key), option);
   }
 });
-program.option('-o --output <file>', 'Specify output file (if not specified STDOUT will be used for output)');
+program.option('-o --output <file>', 'Specify output file (reads from file arguments or STDIN; outputs to STDOUT if not specified)');
+program.option('-v --verbose', 'Show detailed processing information');
+program.option('-d --dry', 'Dry run: process and report statistics without writing output');
 
 function readFile(file) {
   try {
@@ -164,179 +185,419 @@ function readFile(file) {
   }
 }
 
-let config = {};
-program.option('-c --config-file <file>', 'Use config file', function (configPath) {
+/**
+ * Load config from a file path, trying JSON, CJS, then ESM
+ * @param {string} configPath - Path to config file
+ * @returns {Promise<object>} Loaded config object
+ */
+async function loadConfigFromPath(configPath) {
   const data = readFile(configPath);
+
+  // Try JSON first
   try {
-    config = JSON.parse(data);
+    return JSON.parse(data);
   } catch (je) {
+    const abs = path.resolve(configPath);
+
+    // Try CJS require
     try {
-      config = require(path.resolve(configPath));
+      const result = require(abs);
+      // Handle ESM interop: if `require()` loads an ESM file, it may return `{__esModule: true, default: …}`
+      return (result && result.__esModule && result.default) ? result.default : result;
     } catch (ne) {
-      fatal('Cannot read the specified config file.\nAs JSON: ' + je.message + '\nAs module: ' + ne.message);
+      // Try ESM import
+      try {
+        const mod = await import(pathToFileURL(abs).href);
+        return mod.default || mod;
+      } catch (ee) {
+        fatal('Cannot read the specified config file.\nAs JSON: ' + je.message + '\nAs CJS: ' + ne.message + '\nAs ESM: ' + ee.message);
+      }
     }
   }
+}
+
+/**
+ * Normalize and validate config object by applying parsers and transforming values.
+ * @param {object} config - Raw config object
+ * @returns {object} Normalized config object
+ */
+function normalizeConfig(config) {
+  const normalized = { ...config };
+
+  // Apply parsers to main options
   mainOptionKeys.forEach(function (key) {
-    if (key in config) {
+    if (key in normalized) {
       const option = mainOptions[key];
       if (Array.isArray(option)) {
-        const value = config[key];
-        config[key] = option[1](typeof value === 'string' ? value : JSON.stringify(value));
+        const value = normalized[key];
+        normalized[key] = option[1](typeof value === 'string' ? value : JSON.stringify(value));
       }
     }
   });
 
   // Handle fileExt in config file
-  if ('fileExt' in config) {
+  if ('fileExt' in normalized) {
     // Support both string (`html,htm`) and array (`["html", "htm"]`) formats
-    if (Array.isArray(config.fileExt)) {
-      config.fileExt = config.fileExt.join(',');
+    if (Array.isArray(normalized.fileExt)) {
+      normalized.fileExt = normalized.fileExt.join(',');
     }
   }
-});
+
+  return normalized;
+}
+
+let config = {};
+program.option('-c --config-file <file>', 'Use config file');
 program.option('--input-dir <dir>', 'Specify an input directory');
 program.option('--output-dir <dir>', 'Specify an output directory');
 program.option('--file-ext <extensions>', 'Specify file extension(s) to process (comma-separated), e.g., “html” or “html,htm,php”');
 
-let content;
-program.arguments('[files...]').action(function (files) {
-  content = files.map(readFile).join('');
-}).parse(process.argv);
+(async () => {
+  let content;
+  await program.arguments('[files...]').action(function (files) {
+    content = files.map(readFile).join('');
+  }).parseAsync(process.argv);
 
-const programOptions = program.opts();
+  const programOptions = program.opts();
 
-function createOptions() {
-  const options = {};
+  // Load and normalize config if `--config-file` was specified
+  if (programOptions.configFile) {
+    config = await loadConfigFromPath(programOptions.configFile);
+    config = normalizeConfig(config);
+  }
 
-  mainOptionKeys.forEach(function (key) {
-    const param = programOptions[key === 'minifyURLs' ? 'minifyUrls' : camelCase(key)];
+  function createOptions() {
+    const options = {};
 
-    if (typeof param !== 'undefined') {
-      options[key] = param;
-    } else if (key in config) {
-      options[key] = config[key];
-    }
-  });
-  return options;
-}
+    mainOptionKeys.forEach(function (key) {
+      const param = programOptions[key === 'minifyURLs' ? 'minifyUrls' : camelCase(key)];
+
+      if (typeof param !== 'undefined') {
+        options[key] = param;
+      } else if (key in config) {
+        options[key] = config[key];
+      }
+    });
+    return options;
+  }
 
-function mkdir(outputDir, callback) {
-  fs.mkdir(outputDir, { recursive: true }, function (err) {
-    if (err) {
-      fatal('Cannot create directory ' + outputDir + '\n' + err.message);
+  function getActiveOptionsDisplay(minifierOptions) {
+    const activeOptions = Object.entries(minifierOptions)
+      .filter(([k]) => program.getOptionValueSource(k === 'minifyURLs' ? 'minifyUrls' : camelCase(k)) === 'cli')
+      .map(([k, v]) => (typeof v === 'boolean' ? (v ? k : `no-${k}`) : k));
+    if (activeOptions.length > 0) {
+      console.error('CLI options: ' + activeOptions.join(', '));
     }
-    callback();
-  });
-}
+  }
+
+  function calculateStats(original, minified) {
+    const originalSize = Buffer.byteLength(original, 'utf8');
+    const minifiedSize = Buffer.byteLength(minified, 'utf8');
+    const saved = originalSize - minifiedSize;
+    const sign = saved >= 0 ? '-' : '+';
+    const percentage = originalSize ? ((Math.abs(saved) / originalSize) * 100).toFixed(1) : '0.0';
+    return { originalSize, minifiedSize, saved, sign, percentage };
+  }
 
-function processFile(inputFile, outputFile) {
-  fs.readFile(inputFile, { encoding: 'utf8' }, async function (err, data) {
-    if (err) {
+  async function processFile(inputFile, outputFile, isDryRun = false, isVerbose = false) {
+    const data = await fs.promises.readFile(inputFile, { encoding: 'utf8' }).catch(err => {
       fatal('Cannot read ' + inputFile + '\n' + err.message);
-    }
+    });
+
     let minified;
     try {
       minified = await minify(data, createOptions());
     } catch (e) {
       fatal('Minification error on ' + inputFile + '\n' + e.message);
     }
-    fs.writeFile(outputFile, minified, { encoding: 'utf8' }, function (err) {
-      if (err) {
-        fatal('Cannot write ' + outputFile + '\n' + err.message);
-      }
+
+    const stats = calculateStats(data, minified);
+
+    // Show stats if dry run or verbose mode
+    if (isDryRun || isVerbose) {
+      console.error(`  ✓ ${path.relative(process.cwd(), inputFile)}: ${stats.originalSize.toLocaleString()} → ${stats.minifiedSize.toLocaleString()} bytes (${stats.sign}${Math.abs(stats.saved).toLocaleString()}, ${stats.percentage}%)`);
+    }
+
+    if (isDryRun) {
+      return { originalSize: stats.originalSize, minifiedSize: stats.minifiedSize, saved: stats.saved };
+    }
+
+    await fs.promises.writeFile(outputFile, minified, { encoding: 'utf8' }).catch(err => {
+      fatal('Cannot write ' + outputFile + '\n' + err.message);
     });
-  });
-}
 
-function parseFileExtensions(fileExt) {
-  if (!fileExt) return [];
-  const list = fileExt
-    .split(',')
-    .map(ext => ext.trim().replace(/^\.+/, '').toLowerCase())
-    .filter(ext => ext.length > 0);
-  return [...new Set(list)];
-}
+    return { originalSize: stats.originalSize, minifiedSize: stats.minifiedSize, saved: stats.saved };
+  }
 
-function shouldProcessFile(filename, fileExtensions) {
-  if (!fileExtensions || fileExtensions.length === 0) {
-    return true; // No extensions specified, process all files
+  function parseFileExtensions(fileExt) {
+    if (!fileExt) return [];
+    const list = fileExt
+      .split(',')
+      .map(ext => ext.trim().replace(/^\.+/, '').toLowerCase())
+      .filter(ext => ext.length > 0);
+    return [...new Set(list)];
   }
 
-  const fileExt = path.extname(filename).replace(/^\.+/, '').toLowerCase();
-  return fileExtensions.includes(fileExt);
-}
+  function shouldProcessFile(filename, fileExtensions) {
+    if (!fileExtensions || fileExtensions.length === 0) {
+      return true; // No extensions specified, process all files
+    }
 
-function processDirectory(inputDir, outputDir, extensions) {
-  // If first call provided a string, normalize once; otherwise assume pre-parsed array
-  if (typeof extensions === 'string') {
-    extensions = parseFileExtensions(extensions);
+    const fileExt = path.extname(filename).replace(/^\.+/, '').toLowerCase();
+    return fileExtensions.includes(fileExt);
   }
 
-  fs.readdir(inputDir, function (err, files) {
-    if (err) {
-      fatal('Cannot read directory ' + inputDir + '\n' + err.message);
+  async function countFiles(dir, extensions, skipRootAbs) {
+    let count = 0;
+
+    const files = await fs.promises.readdir(dir).catch(() => []);
+
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+
+      // Skip anything inside the output root
+      if (skipRootAbs) {
+        const real = await fs.promises.realpath(filePath).catch(() => undefined);
+        if (real && (real === skipRootAbs || real.startsWith(skipRootAbs + path.sep))) {
+          continue;
+        }
+      }
+
+      const lst = await fs.promises.lstat(filePath).catch(() => null);
+      if (!lst || lst.isSymbolicLink()) {
+        continue;
+      }
+
+      if (lst.isDirectory()) {
+        count += await countFiles(filePath, extensions, skipRootAbs);
+      } else if (shouldProcessFile(file, extensions)) {
+        count++;
+      }
+    }
+
+    return count;
+  }
+
+  function updateProgress(current, total) {
+    // Clear the line first, then write simple progress
+    process.stderr.write(`\r\x1b[K`);
+    if (total) {
+      const ratio = Math.min(current / total, 1);
+      const percentage = (ratio * 100).toFixed(1);
+      process.stderr.write(`Processing ${current.toLocaleString()}/${total.toLocaleString()} (${percentage}%)`);
+    } else {
+      // Indeterminate progress - no total known yet
+      process.stderr.write(`Processing ${current.toLocaleString()} files…`);
+    }
+  }
+
+  function clearProgress() {
+    process.stderr.write('\r\x1b[K'); // Clear the line
+  }
+
+  async function processDirectory(inputDir, outputDir, extensions, isDryRun = false, isVerbose = false, skipRootAbs, progress = null) {
+    // If first call provided a string, normalize once; otherwise assume pre-parsed array
+    if (typeof extensions === 'string') {
+      extensions = parseFileExtensions(extensions);
     }
 
-    files.forEach(function (file) {
+    const files = await fs.promises.readdir(inputDir).catch(err => {
+      fatal('Cannot read directory ' + inputDir + '\n' + err.message);
+    });
+
+    const allStats = [];
+
+    for (const file of files) {
       const inputFile = path.join(inputDir, file);
       const outputFile = path.join(outputDir, file);
 
-      fs.stat(inputFile, function (err, stat) {
-        if (err) {
-          fatal('Cannot read ' + inputFile + '\n' + err.message);
-        } else if (stat.isDirectory()) {
-          processDirectory(inputFile, outputFile, extensions);
-        } else if (shouldProcessFile(file, extensions)) {
-          mkdir(outputDir, function () {
-            processFile(inputFile, outputFile);
-          });
+      // Skip anything inside the output root to avoid reprocessing
+      if (skipRootAbs) {
+        const real = await fs.promises.realpath(inputFile).catch(() => undefined);
+        if (real && (real === skipRootAbs || real.startsWith(skipRootAbs + path.sep))) {
+          continue;
         }
+      }
+
+      const lst = await fs.promises.lstat(inputFile).catch(err => {
+        fatal('Cannot read ' + inputFile + '\n' + err.message);
       });
-    });
-  });
-}
 
-const writeMinify = async () => {
-  const minifierOptions = createOptions();
-  let minified;
+      if (lst.isSymbolicLink()) {
+        continue;
+      }
 
-  try {
-    minified = await minify(content, minifierOptions);
-  } catch (e) {
-    fatal('Minification error:\n' + e.message);
+      if (lst.isDirectory()) {
+        const dirStats = await processDirectory(inputFile, outputFile, extensions, isDryRun, isVerbose, skipRootAbs, progress);
+        if (dirStats) {
+          allStats.push(...dirStats);
+        }
+      } else if (shouldProcessFile(file, extensions)) {
+        if (!isDryRun) {
+          await fs.promises.mkdir(outputDir, { recursive: true }).catch(err => {
+            fatal('Cannot create directory ' + outputDir + '\n' + err.message);
+          });
+        }
+        const fileStats = await processFile(inputFile, outputFile, isDryRun, isVerbose);
+        if (fileStats) {
+          allStats.push(fileStats);
+        }
+
+        // Update progress after processing
+        if (progress) {
+          progress.current++;
+          updateProgress(progress.current, progress.total);
+        }
+      }
+    }
+
+    return allStats;
   }
 
-  let stream = process.stdout;
+  const writeMinify = async () => {
+    const minifierOptions = createOptions();
+
+    // Show config info if verbose
+    if (programOptions.verbose || programOptions.dry) {
+      getActiveOptionsDisplay(minifierOptions);
+    }
+
+    let minified;
+
+    try {
+      minified = await minify(content, minifierOptions);
+    } catch (e) {
+      fatal('Minification error:\n' + e.message);
+    }
+
+    const stats = calculateStats(content, minified);
+
+    if (programOptions.dry) {
+      const inputSource = program.args.length > 0 ? program.args.join(', ') : 'STDIN';
+      const outputDest = programOptions.output || 'STDOUT';
+
+      console.error(`[DRY RUN] Would minify: ${inputSource} → ${outputDest}`);
+      console.error(`  Original: ${stats.originalSize.toLocaleString()} bytes`);
+      console.error(`  Minified: ${stats.minifiedSize.toLocaleString()} bytes`);
+      console.error(`  Saved: ${stats.sign}${Math.abs(stats.saved).toLocaleString()} bytes (${stats.percentage}%)`);
+      return;
+    }
+
+    // Show stats if verbose
+    if (programOptions.verbose) {
+      const inputSource = program.args.length > 0 ? program.args.join(', ') : 'STDIN';
+      console.error(`  ✓ ${inputSource}: ${stats.originalSize.toLocaleString()} → ${stats.minifiedSize.toLocaleString()} bytes (${stats.sign}${Math.abs(stats.saved).toLocaleString()}, ${stats.percentage}%)`);
+    }
 
-  if (programOptions.output) {
-    stream = fs.createWriteStream(programOptions.output)
-      .on('error', (e) => {
+    if (programOptions.output) {
+      await fs.promises.mkdir(path.dirname(programOptions.output), { recursive: true }).catch((e) => {
+        fatal('Cannot create directory ' + path.dirname(programOptions.output) + '\n' + e.message);
+      });
+      await new Promise((resolve, reject) => {
+        const fileStream = fs.createWriteStream(programOptions.output)
+          .on('error', reject)
+          .on('finish', resolve);
+        fileStream.end(minified);
+        }).catch((e) => {
         fatal('Cannot write ' + programOptions.output + '\n' + e.message);
       });
-  }
+      return;
+    }
 
-  stream.write(minified);
-};
+    process.stdout.write(minified);
+  };
+
+  const { inputDir, outputDir, fileExt } = programOptions;
 
-const { inputDir, outputDir, fileExt } = programOptions;
+  // Resolve file extensions: CLI argument takes priority over config file, even if empty string
+  const hasCliFileExt = program.getOptionValueSource('fileExt') === 'cli';
+  const resolvedFileExt = hasCliFileExt ? fileExt : config.fileExt;
 
-// Resolve file extensions: CLI argument takes priority over config file, even if empty string
-const hasCliFileExt = program.getOptionValueSource('fileExt') === 'cli';
-const resolvedFileExt = hasCliFileExt ? fileExt : config.fileExt;
+  if (inputDir || outputDir) {
+    if (!inputDir) {
+      fatal('The option `output-dir` needs to be used with the option `input-dir`—if you are working with a single file, use `-o`');
+    } else if (!outputDir) {
+      fatal('You need to specify where to write the output files with the option `--output-dir`');
+    }
+
+    await (async () => {
+      // `--dry` automatically enables verbose mode
+      const isVerbose = programOptions.verbose || programOptions.dry;
+
+      // Show config info if verbose
+      if (isVerbose) {
+        const minifierOptions = createOptions();
+        getActiveOptionsDisplay(minifierOptions);
+      }
+
+      // Prevent traversing into the output directory when it is inside the input directory
+      let inputReal;
+      let outputReal;
+      inputReal = await fs.promises.realpath(inputDir).catch(() => undefined);
+      try {
+        outputReal = await fs.promises.realpath(outputDir);
+      } catch {
+        outputReal = path.resolve(outputDir);
+      }
+      let skipRootAbs;
+      if (inputReal && outputReal && (outputReal === inputReal || outputReal.startsWith(inputReal + path.sep))) {
+        // Instead of aborting, skip traversing into the output directory
+        skipRootAbs = outputReal;
+      }
+
+      if (programOptions.dry) {
+        console.error(`[DRY RUN] Would process directory: ${inputDir} → ${outputDir}`);
+      }
+
+      // Set up progress indicator (only in TTY and when not verbose/dry)
+      const showProgress = process.stderr.isTTY && !isVerbose;
+      let progress = null;
+
+      if (showProgress) {
+        // Start with indeterminate progress, count in background
+        progress = {current: 0, total: null};
+
+        // Note: `countFiles` runs asynchronously and mutates `progress.total` when complete.
+        // This shared-state mutation is safe because JavaScript is single-threaded—
+        // `updateProgress` may read `progress.total` as `null` initially,
+        // then see the updated value once `countFiles` resolves,
+        // transitioning the indicator from indeterminate to determinate progress without race conditions.
+        const extensions = typeof resolvedFileExt === 'string' ? parseFileExtensions(resolvedFileExt) : resolvedFileExt;
+        countFiles(inputDir, extensions, skipRootAbs).then(total => {
+          if (progress) {
+            progress.total = total;
+          }
+        }).catch(() => {
+          // Ignore count errors, just keep showing indeterminate progress
+        });
+      }
+
+      const stats = await processDirectory(inputDir, outputDir, resolvedFileExt, programOptions.dry, isVerbose, skipRootAbs, progress);
 
-if (inputDir || outputDir) {
-  if (!inputDir) {
-    fatal('The option output-dir needs to be used with the option input-dir. If you are working with a single file, use -o.');
-  } else if (!outputDir) {
-    fatal('You need to specify where to write the output files with the option --output-dir');
+      // Show completion message and clear progress indicator
+      if (progress) {
+        clearProgress();
+        console.error(`Processed ${progress.current.toLocaleString()} file${progress.current === 1 ? '' : 's'}`);
+      }
+
+      if (isVerbose && stats && stats.length > 0) {
+        const totalOriginal = stats.reduce((sum, s) => sum + s.originalSize, 0);
+        const totalMinified = stats.reduce((sum, s) => sum + s.minifiedSize, 0);
+        const totalSaved = totalOriginal - totalMinified;
+        const sign = totalSaved >= 0 ? '-' : '+';
+        const totalPercentage = totalOriginal ? ((Math.abs(totalSaved) / totalOriginal) * 100).toFixed(1) : '0.0';
+
+        console.error('---');
+        console.error(`Total: ${totalOriginal.toLocaleString()} → ${totalMinified.toLocaleString()} bytes (${sign}${Math.abs(totalSaved).toLocaleString()}, ${totalPercentage}%)`);
+      }
+    })();
+  } else if (content) { // Minifying one or more files specified on the CMD line
+    writeMinify();
+  } else { // Minifying input coming from STDIN
+    content = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', function (data) {
+      content += data;
+    }).on('end', writeMinify);
   }
-  processDirectory(inputDir, outputDir, resolvedFileExt);
-} else if (content) { // Minifying one or more files specified on the CMD line
-  writeMinify();
-} else { // Minifying input coming from STDIN
-  content = '';
-  process.stdin.setEncoding('utf8');
-  process.stdin.on('data', function (data) {
-    content += data;
-  }).on('end', writeMinify);
-}
+})();

package/package.json

@@ -15,15 +15,15 @@
   "description": "Highly configurable, well-tested, JavaScript-based HTML minifier",
   "devDependencies": {
     "@commitlint/cli": "^20.1.0",
-    "@eslint/js": "^9.36.0",
-    "@rollup/plugin-commonjs": "^28.0.6",
+    "@eslint/js": "^9.37.0",
+    "@rollup/plugin-commonjs": "^28.0.8",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "eslint": "^9.36.0",
+    "eslint": "^9.37.0",
     "rollup": "^4.52.4",
     "rollup-plugin-polyfill-node": "^0.13.0",
-    "vite": "^7.1.9"
+    "vite": "^7.1.12"
   },
   "exports": {
     ".": {
@@ -78,5 +78,5 @@
     "test:watch": "node --test --watch tests/*.spec.js"
   },
   "type": "module",
-  "version": "3.0.0"
+  "version": "3.2.0"
 }