@medicomind/rolldown-compression 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,112 @@
+import { Plugin } from "rolldown";
+//#region ts/options.d.ts
+/** Accepted algorithm names, including aliases. */
+type AlgorithmName = 'gzip' | 'gz' | 'brotli' | 'br' | 'brotliCompress' | 'zstd' | 'zstandard';
+/** Canonical algorithm names after alias normalization. */
+type CanonicalAlgorithm = 'gzip' | 'brotli' | 'zstd';
+/** Gzip options. `level`: 0-9, default 6. */
+interface GzipOptions {
+  level?: number;
+}
+/** Brotli options. `quality`: 0-11, default 11. `windowBits`: 10-24, default 22. */
+interface BrotliOptions {
+  quality?: number;
+  windowBits?: number;
+}
+/** Zstandard options. `level`: 1-22, default 19. */
+interface ZstdOptions {
+  level?: number;
+}
+/** A normalized `(algorithm, options)` pair produced by {@link defineAlgorithm}. */
+interface DefineAlgorithmResult {
+  readonly algorithm: CanonicalAlgorithm;
+  readonly options: GzipOptions | BrotliOptions | ZstdOptions;
+}
+/** Pattern or callback used to derive compressed artifact names. */
+type FilenameOption = string | ((fileName: string, algorithm: CanonicalAlgorithm) => string);
+type LogLevel = 'silent' | 'error' | 'warn' | 'info';
+/** Options accepted by {@link compression}. */
+interface CompressionOptions {
+  /**
+   * Files to compress. Strings are picomatch globs, RegExps are tested
+   * against the output file name.
+   * @default /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|txt|wasm)$/
+   */
+  include?: string | RegExp | Array<string | RegExp>;
+  /** Files to exclude. Takes precedence over `include`. */
+  exclude?: string | RegExp | Array<string | RegExp>;
+  /**
+   * Minimum size of the original asset, in bytes, for it to be compressed.
+   * @default 0
+   */
+  threshold?: number;
+  /**
+   * Algorithms to run, as names or {@link defineAlgorithm} results.
+   * @default ['gzip', 'brotli']
+   */
+  algorithms?: Array<AlgorithmName | DefineAlgorithmResult>;
+  /**
+   * Name of the emitted artifact. Tokens: `[path]` (directory, with trailing
+   * slash), `[base]` (file name with extension), `[name]`, `[ext]` (with
+   * leading dot), `[hash]` (8-char content hash). Function form receives the
+   * original file name and the canonical algorithm name.
+   * @default '[path][base]' + per-algorithm extension (.gz / .br / .zst)
+   */
+  filename?: FilenameOption;
+  /**
+   * Remove the original asset from the bundle once all algorithms have
+   * processed it.
+   * @default false
+   */
+  deleteOriginalAssets?: boolean;
+  /**
+   * Do not emit artifacts whose compressed size is >= the original size.
+   * @default true
+   */
+  skipIfLargerOrEqual?: boolean;
+  /**
+   * Native worker threads used for compression. `0` = number of logical CPUs.
+   * @default 0
+   */
+  concurrency?: number;
+  /** @default 'info' */
+  logLevel?: LogLevel;
+  /**
+   * The plugin is a no-op in watch/dev mode unless this is set to `true`.
+   * @default false
+   */
+  enableInWatchMode?: boolean;
+}
+/**
+ * Pair an algorithm with its options, validating both eagerly.
+ *
+ * @example
+ * compression({ algorithms: [defineAlgorithm('brotli', { quality: 9 })] })
+ */
+declare function defineAlgorithm(name: 'gzip' | 'gz', options?: GzipOptions): DefineAlgorithmResult;
+declare function defineAlgorithm(name: 'brotli' | 'br' | 'brotliCompress', options?: BrotliOptions): DefineAlgorithmResult;
+declare function defineAlgorithm(name: 'zstd' | 'zstandard', options?: ZstdOptions): DefineAlgorithmResult;
+//#endregion
+//#region ts/index.d.ts
+/**
+ * Create the compression plugin.
+ *
+ * Options are validated eagerly: invalid levels, algorithm names, thresholds
+ * etc. throw here rather than during the build.
+ *
+ * @example
+ * import { defineConfig } from 'rolldown'
+ * import { compression, defineAlgorithm } from '@medicomind/rolldown-compression'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     compression({
+ *       threshold: 1024,
+ *       algorithms: ['gzip', defineAlgorithm('brotli', { quality: 11 })],
+ *     }),
+ *   ],
+ * })
+ */
+declare function compression(options?: CompressionOptions): Plugin;
+//#endregion
+export { type AlgorithmName, type BrotliOptions, type CanonicalAlgorithm, type CompressionOptions, type DefineAlgorithmResult, type FilenameOption, type GzipOptions, type LogLevel, type ZstdOptions, compression, defineAlgorithm };

package/dist/index.mjs

@@ -0,0 +1,284 @@
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { createFilter } from "@rollup/pluginutils";
+//#region ts/options.ts
+/**
+* Option types, normalization and validation for the public API.
+*
+* Everything here is validated eagerly at `compression()` call time so that
+* misconfiguration fails when the config is evaluated, not mid-build.
+*/
+const DEFAULT_INCLUDE = /\.(html|xml|css|json|js|mjs|svg|yaml|yml|toml|txt|wasm)$/;
+const ALIASES = {
+	gzip: "gzip",
+	gz: "gzip",
+	brotli: "brotli",
+	br: "brotli",
+	brotliCompress: "brotli",
+	zstd: "zstd",
+	zstandard: "zstd"
+};
+const EXTENSIONS = {
+	gzip: ".gz",
+	brotli: ".br",
+	zstd: ".zst"
+};
+const DEFAULT_LEVELS = {
+	gzip: 6,
+	brotli: 11,
+	zstd: 19
+};
+const LEVEL_RANGES = {
+	gzip: [0, 9],
+	brotli: [0, 11],
+	zstd: [1, 22]
+};
+const LOG_LEVELS = [
+	"silent",
+	"error",
+	"warn",
+	"info"
+];
+/** File extensions produced by this plugin; used by the re-compression guard. */
+const COMPRESSED_EXTENSION_RE = /\.(gz|br|zst)$/i;
+var OptionValidationError = class extends Error {
+	constructor(message) {
+		super(`[rolldown-compression] ${message}`);
+		this.name = "OptionValidationError";
+	}
+};
+function assertIntegerInRange(value, [min, max], label) {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) throw new OptionValidationError(`invalid ${label}: expected an integer between ${min} and ${max}, got ${JSON.stringify(value)}`);
+}
+/** Normalize an algorithm name, throwing on unknown input. */
+function normalizeAlgorithmName(name) {
+	const canonical = ALIASES[name];
+	if (canonical === void 0) throw new OptionValidationError(`unknown algorithm ${JSON.stringify(name)}: expected one of ${Object.keys(ALIASES).join(", ")}`);
+	return canonical;
+}
+function defineAlgorithm(name, options = {}) {
+	const algorithm = normalizeAlgorithmName(name);
+	validateAlgorithmOptions(algorithm, options);
+	return Object.freeze({
+		algorithm,
+		options: Object.freeze({ ...options })
+	});
+}
+function validateAlgorithmOptions(algorithm, options) {
+	if (algorithm === "brotli") {
+		const { quality, windowBits } = options;
+		if (quality !== void 0) assertIntegerInRange(quality, LEVEL_RANGES.brotli, "brotli quality");
+		if (windowBits !== void 0) assertIntegerInRange(windowBits, [10, 24], "brotli windowBits");
+		return;
+	}
+	const { level } = options;
+	if (level !== void 0) assertIntegerInRange(level, LEVEL_RANGES[algorithm], `${algorithm} level`);
+}
+function resolveAlgorithm(entry) {
+	const { algorithm, options } = typeof entry === "string" ? {
+		algorithm: normalizeAlgorithmName(entry),
+		options: {}
+	} : validateDefined(entry);
+	const resolved = {
+		algorithm,
+		level: algorithm === "brotli" ? options.quality ?? DEFAULT_LEVELS.brotli : options.level ?? DEFAULT_LEVELS[algorithm],
+		extension: EXTENSIONS[algorithm]
+	};
+	if (algorithm === "brotli") {
+		const { windowBits } = options;
+		if (windowBits !== void 0) resolved.windowBits = windowBits;
+	}
+	return resolved;
+}
+function validateDefined(entry) {
+	if (entry === null || typeof entry !== "object" || typeof entry.algorithm !== "string" || entry.options === null || typeof entry.options !== "object") throw new OptionValidationError(`invalid algorithms entry ${JSON.stringify(entry)}: expected an algorithm name or a defineAlgorithm() result`);
+	const algorithm = normalizeAlgorithmName(entry.algorithm);
+	validateAlgorithmOptions(algorithm, entry.options);
+	return {
+		algorithm,
+		options: entry.options
+	};
+}
+/** Validate and normalize user options. Throws at `compression()` call time. */
+function resolveOptions(options = {}) {
+	if (options === null || typeof options !== "object") throw new OptionValidationError("options must be an object");
+	const { include = DEFAULT_INCLUDE, exclude, threshold = 0, algorithms = ["gzip", "brotli"], filename, deleteOriginalAssets = false, skipIfLargerOrEqual = true, concurrency = 0, logLevel = "info", enableInWatchMode = false } = options;
+	if (typeof threshold !== "number" || Number.isNaN(threshold) || threshold < 0) throw new OptionValidationError(`invalid threshold: expected a non-negative number, got ${JSON.stringify(threshold)}`);
+	if (!Number.isInteger(concurrency) || concurrency < 0) throw new OptionValidationError(`invalid concurrency: expected a non-negative integer, got ${JSON.stringify(concurrency)}`);
+	if (!LOG_LEVELS.includes(logLevel)) throw new OptionValidationError(`invalid logLevel ${JSON.stringify(logLevel)}: expected one of ${LOG_LEVELS.join(", ")}`);
+	if (filename !== void 0 && typeof filename !== "string" && typeof filename !== "function") throw new OptionValidationError("invalid filename: expected a string pattern or a function");
+	if (!Array.isArray(algorithms) || algorithms.length === 0) throw new OptionValidationError("invalid algorithms: expected a non-empty array");
+	return {
+		filter: createFilter(include, exclude, { resolve: false }),
+		threshold,
+		algorithms: algorithms.map(resolveAlgorithm),
+		filename,
+		deleteOriginalAssets: Boolean(deleteOriginalAssets),
+		skipIfLargerOrEqual: Boolean(skipIfLargerOrEqual),
+		concurrency,
+		logLevel,
+		enableInWatchMode: Boolean(enableInWatchMode)
+	};
+}
+/**
+* Resolve the emitted file name for a compressed artifact.
+*
+* Supported tokens: `[path]`, `[base]`, `[name]`, `[ext]`, `[hash]`.
+*/
+function resolveOutputFileName(filename, fileName, algorithm, source) {
+	if (typeof filename === "function") return filename(fileName, algorithm.algorithm);
+	const pattern = filename ?? `[path][base]${algorithm.extension}`;
+	const dir = path.posix.dirname(fileName);
+	const base = path.posix.basename(fileName);
+	const ext = path.posix.extname(fileName);
+	return pattern.replaceAll("[path]", dir === "." ? "" : `${dir}/`).replaceAll("[base]", base).replaceAll("[name]", base.slice(0, base.length - ext.length)).replaceAll("[ext]", ext).replaceAll("[hash]", () => createHash("sha256").update(source).digest("hex").slice(0, 8));
+}
+/**
+* Compress a batch of buffers in the native rayon thread pool, off the JS
+* main thread. `tasks[i]` describes how to compress `buffers[i]`.
+*/
+const compressBuffers = createRequire(import.meta.url)("../index.js").compressBuffers;
+//#endregion
+//#region ts/plugin.ts
+const PLUGIN_NAME = "rolldown-compression";
+const LOG_PRIORITY = {
+	silent: 0,
+	error: 1,
+	warn: 2,
+	info: 3
+};
+function createLogger(level) {
+	const priority = LOG_PRIORITY[level];
+	const prefix = `[${PLUGIN_NAME}]`;
+	return {
+		info: (message) => {
+			if (priority >= LOG_PRIORITY.info) console.info(`${prefix} ${message}`);
+		},
+		warn: (message) => {
+			if (priority >= LOG_PRIORITY.warn) console.warn(`${prefix} ${message}`);
+		},
+		error: (message) => {
+			if (priority >= LOG_PRIORITY.error) console.error(`${prefix} ${message}`);
+		}
+	};
+}
+function toBuffer(source) {
+	return typeof source === "string" ? Buffer.from(source, "utf8") : Buffer.from(source);
+}
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} kB`;
+	return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+function createCompressionPlugin(options) {
+	const logger = createLogger(options.logLevel);
+	const emittedNames = /* @__PURE__ */ new Set();
+	return Object.assign({
+		name: PLUGIN_NAME,
+		async generateBundle(_outputOptions, bundle) {
+			if (this.meta?.watchMode && !options.enableInWatchMode) {
+				logger.info("watch mode detected, skipping compression (set enableInWatchMode to opt in)");
+				return;
+			}
+			const startedAt = performance.now();
+			const pending = [];
+			const processedSources = /* @__PURE__ */ new Set();
+			for (const [fileName, output] of Object.entries(bundle)) {
+				if (!options.filter(fileName)) continue;
+				if (COMPRESSED_EXTENSION_RE.test(fileName) || emittedNames.has(fileName)) continue;
+				const buffer = toBuffer(output.type === "chunk" ? output.code : output.source);
+				if (buffer.byteLength < options.threshold) continue;
+				for (const algorithm of options.algorithms) {
+					const outputFileName = resolveOutputFileName(options.filename, fileName, algorithm, buffer);
+					if (outputFileName === fileName) this.error(/* @__PURE__ */ new Error(`[${PLUGIN_NAME}] the filename option resolved "${fileName}" (${algorithm.algorithm}) to the same name as the source asset; refusing to overwrite it`));
+					pending.push({
+						task: {
+							fileName,
+							algorithm: algorithm.algorithm,
+							level: algorithm.level,
+							windowBits: algorithm.windowBits
+						},
+						buffer,
+						sourceFileName: fileName,
+						outputFileName
+					});
+				}
+				processedSources.add(fileName);
+			}
+			if (pending.length === 0) return;
+			const results = await compressBuffers(pending.map((artifact) => artifact.task), pending.map((artifact) => artifact.buffer), {
+				concurrency: options.concurrency,
+				skipIfLargerOrEqual: options.skipIfLargerOrEqual
+			});
+			const failures = [];
+			const emittedBySource = /* @__PURE__ */ new Map();
+			const stats = /* @__PURE__ */ new Map();
+			for (const [index, result] of results.entries()) {
+				const artifact = pending[index];
+				if (artifact === void 0) continue;
+				if (result.error !== void 0 && result.error !== null) {
+					failures.push(`${result.fileName} (${result.algorithm}): ${result.error}`);
+					continue;
+				}
+				if (result.skipped) {
+					logger.info(`skipped ${artifact.outputFileName}: ${result.algorithm} output would not be smaller than the original`);
+					continue;
+				}
+				this.emitFile({
+					type: "asset",
+					fileName: artifact.outputFileName,
+					source: result.data
+				});
+				emittedNames.add(artifact.outputFileName);
+				emittedBySource.set(artifact.sourceFileName, (emittedBySource.get(artifact.sourceFileName) ?? 0) + 1);
+				const stat = stats.get(result.algorithm) ?? {
+					count: 0,
+					originalBytes: 0,
+					outputBytes: 0
+				};
+				stat.count += 1;
+				stat.originalBytes += result.originalSize;
+				stat.outputBytes += result.compressedSize;
+				stats.set(result.algorithm, stat);
+			}
+			if (failures.length > 0) this.error(/* @__PURE__ */ new Error(`[${PLUGIN_NAME}] ${failures.length} compression task(s) failed:\n${failures.join("\n")}`));
+			if (options.deleteOriginalAssets) for (const fileName of processedSources) {
+				if ((emittedBySource.get(fileName) ?? 0) === 0) logger.warn(`deleteOriginalAssets removed "${fileName}" even though no compressed variant was emitted for it`);
+				delete bundle[fileName];
+			}
+			const elapsedMs = performance.now() - startedAt;
+			const summary = [...stats.entries()].map(([algorithm, stat]) => `${algorithm}: ${stat.count} file(s), ${formatBytes(stat.originalBytes)} -> ${formatBytes(stat.outputBytes)}`).join("; ");
+			if (summary.length > 0) {
+				const totalSaved = [...stats.values()].reduce((sum, stat) => sum + (stat.originalBytes - stat.outputBytes), 0);
+				logger.info(`${summary}; saved ${formatBytes(totalSaved)} in ${(elapsedMs / 1e3).toFixed(2)}s`);
+			}
+		}
+	}, { apply: "build" });
+}
+//#endregion
+//#region ts/index.ts
+/**
+* Create the compression plugin.
+*
+* Options are validated eagerly: invalid levels, algorithm names, thresholds
+* etc. throw here rather than during the build.
+*
+* @example
+* import { defineConfig } from 'rolldown'
+* import { compression, defineAlgorithm } from '@medicomind/rolldown-compression'
+*
+* export default defineConfig({
+*   plugins: [
+*     compression({
+*       threshold: 1024,
+*       algorithms: ['gzip', defineAlgorithm('brotli', { quality: 11 })],
+*     }),
+*   ],
+* })
+*/
+function compression(options) {
+	return createCompressionPlugin(resolveOptions(options));
+}
+//#endregion
+export { compression, defineAlgorithm };

package/index.d.ts

@@ -0,0 +1,56 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Batch-wide options for [`compress_buffers`]. */
+export interface BatchOptions {
+  /** Worker threads; 0 or omitted = number of logical CPUs. */
+  concurrency?: number
+  /**
+   * Mark results whose compressed size >= original as skipped and
+   * return no data for them. Default: false.
+   */
+  skipIfLargerOrEqual?: boolean
+}
+
+/**
+ * Compress a batch of buffers off the JS main thread.
+ *
+ * `tasks[i]` describes how to compress `buffers[i]`. Algorithm names and
+ * levels are validated synchronously so misconfiguration fails fast;
+ * I/O-shaped failures during compression are reported per task via
+ * [`CompressResult::error`].
+ */
+export declare function compressBuffers(tasks: Array<CompressTask>, buffers: Array<Buffer>, options?: BatchOptions | undefined | null): Promise<Array<CompressResult>>
+
+/** Outcome of a single task within a batch. */
+export interface CompressResult {
+  fileName: string
+  algorithm: string
+  /** Compressed bytes. Empty when `skipped` is true or `error` is set. */
+  data: Buffer
+  originalSize: number
+  compressedSize: number
+  /**
+   * True when compression would not shrink the input and
+   * `skipIfLargerOrEqual` was requested.
+   */
+  skipped: boolean
+  /** Per-task failure. A failed task never aborts the rest of the batch. */
+  error?: string
+}
+
+/**
+ * One compression task: pairs with the buffer at the same index in the
+ * `buffers` argument of [`compress_buffers`].
+ */
+export interface CompressTask {
+  fileName: string
+  /** Canonical algorithm name: "gzip" | "brotli" | "zstd". */
+  algorithm: string
+  /**
+   * Compression level; algorithm default when omitted
+   * (gzip 6, brotli 11, zstd 19).
+   */
+  level?: number
+  /** Brotli only: log2 window size (10-24, default 22). */
+  windowBits?: number
+}