kaven-utils/src/KavenUtility.MinifyCss.js

Utils for Node.js.

/********************************************************************
 * @author:      Kaven
 * @email:       kaven@wuwenkai.com
 * @website:     http://blog.kaven.xyz
 * @file:        [Kaven-Utils] /src/KavenUtility.MinifyCss.ts
 * @create:      2025-10-23 11:21:26.506
 * @modify:      2025-10-23 15:09:18.405
 * @version:     6.1.1
 * @times:       5
 * @lines:       82
 * @copyright:   Copyright © 2025 Kaven. All Rights Reserved.
 * @description: [description]
 * @license:     [license]
 ********************************************************************/
import cssnano from "cssnano";
import { readFile, writeFile } from "node:fs/promises";
import { extname } from "node:path";
import postcss from "postcss";
import { EnumerateFiles } from "./KavenUtility.FileSystem.js";
/**
 * Recursively minifies CSS files starting from one or more source paths.
 *
 * This asynchronous function walks the provided source path(s) (files or directories),
 * finds files with the ".css" extension, and replaces each CSS file's contents with
 * a minified version produced by PostCSS + cssnano. Directory traversal is performed
 * iteratively and files are processed sequentially (no parallel writes).
 *
 * Behavior and important details:
 * - The `options.src` value may be a single string path or an array of string paths.
 * - If a path points to a file, it is processed only when its extension is ".css".
 * - If a path points to a directory, the directory is read and its entries are enqueued
 *   for processing. By default, directories named "node_modules" are skipped unless
 *   `options.includeNodeModules` is true.
 * - File reads and writes use UTF-8 encoding. Existing CSS files are overwritten in place.
 * - Errors obtained while calling `stat` are logged via `options.logger.Warn` and the
 *   path is skipped; other IO/processing errors are surfaced via thrown exceptions
 *   from the underlying async operations unless caught by callers.
 * - The function logs successful minification via `options.logger.Info` and warnings
 *   (e.g., ignored node_modules or stat errors) via `options.logger.Warn`.
 *
 * Parameters (I<MinifyCss>Options shape summary):
 * - options.src: string | string[] — one or more filesystem paths (files or directories)
 * - options.includeNodeModules?: boolean — when true, traverses into "node_modules" directories
 * - options.logger?: { Info?: (msg: string) => void; Warn?: (msg: string) => void; } — optional logger
 *
 * @param options - Configuration options for the minification run (see summary above).
 * @returns A Promise that resolves when all provided paths have been processed.
 * @remarks
 * - This function performs destructive updates (overwrites CSS files). Ensure you have backups
 *   or version control in place if you need to preserve original files.
 * - The function is intentionally sequential: if you require parallel processing for performance,
 *   perform concurrency control externally.
 *
 * @since 6.1.1
 * @version 2025-10-23
 */
export async function MinifyCss(options) {
    const logger = options.logger;
    for await (const file of EnumerateFiles(options.src, {
        logger: options.logger,
        ignoreDirectoryNames: options.includeNodeModules ? [] : ["node_modules"],
    })) {
        const ext = extname(file).toLowerCase();
        if (ext !== ".css") {
            continue;
        }
        const cssInput = await readFile(file, "utf8");
        const result = await postcss([cssnano()]).process(cssInput, { from: undefined });
        if (result.css) {
            await writeFile(file, result.css, "utf8");
            logger?.Info(`Minifying ${file} success.`);
        }
    }
}