@medicomind/rolldown-compression 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @medicomind/rolldown-compression
+
+## 0.2.0
+
+### Minor Changes
+
+- [`8c73f0c`](https://github.com/Medico-Mind/rolldown-compression/commit/8c73f0c725501fcf69ebbe3ea9a2d5264437d089) Thanks [@Mnwa](https://github.com/Mnwa)! - Update dependencies: TypeScript 7 toolchain, @types/node 26, zlib-rs 0.6.6.
+
+### Patch Changes
+
+- [`798219c`](https://github.com/Medico-Mind/rolldown-compression/commit/798219c059dc6c514912bbaea3844e3c0d09b447) Thanks [@Mnwa](https://github.com/Mnwa)! - Elide lifetimes
+
+- [`996537c`](https://github.com/Medico-Mind/rolldown-compression/commit/996537c2948681e323aa0d67fdc077e5e2887df2) Thanks [@Mnwa](https://github.com/Mnwa)! - rollback ts to 7
+
+## 0.1.0
+
+### Minor Changes
+
+- [`5307247`](https://github.com/Medico-Mind/rolldown-compression/commit/5307247e332a479672b6f91bfa76953922bd695e) Thanks [@Mnwa](https://github.com/Mnwa)! - Initial release.
+
+  - Rolldown plugin compressing emitted assets with gzip, brotli and zstd.
+  - Native Rust compression core (napi-rs v3 + rayon): one batched FFI call per
+    build, parallel across files and algorithms, cost-aware scheduling,
+    off-main-thread execution.
+  - `compression()` / `defineAlgorithm()` API mirroring vite-plugin-compression2:
+    include/exclude filters, threshold, filename patterns, deleteOriginalAssets,
+    skipIfLargerOrEqual, concurrency, logLevel.
+  - Eager option validation, re-compression guard, watch-mode no-op with
+    `enableInWatchMode` opt-in.
+  - Prebuilt binaries for darwin-arm64/x64, linux-x64/arm64-gnu, linux-x64-musl,
+    win32-x64-msvc.
+
+- [`66182be`](https://github.com/Medico-Mind/rolldown-compression/commit/66182be208983bbbcac805cf0bb1d2671f86fcd2) Thanks [@Mnwa](https://github.com/Mnwa)! - First release
+
+### Patch Changes
+
+- [`0fdd849`](https://github.com/Medico-Mind/rolldown-compression/commit/0fdd849328e71701b1aedadb677a82e6e75640a8) Thanks [@Mnwa](https://github.com/Mnwa)! - Set repo
+
+Release notes are generated by [changesets](https://github.com/changesets/changesets); new sections are added here automatically when a release PR is merged.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 medicomind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @medicomind/rolldown-compression
+
+[![CI](https://github.com/Medico-Mind/rolldown-compression/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Medico-Mind/rolldown-compression/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40medicomind%2Frolldown-compression?logo=npm)](https://www.npmjs.com/package/@medicomind/rolldown-compression)
+[![npm downloads](https://img.shields.io/npm/dm/%40medicomind%2Frolldown-compression)](https://www.npmjs.com/package/@medicomind/rolldown-compression)
+[![node](https://img.shields.io/node/v/%40medicomind%2Frolldown-compression)](https://www.npmjs.com/package/@medicomind/rolldown-compression)
+[![license](https://img.shields.io/npm/l/%40medicomind%2Frolldown-compression)](./LICENSE)
+
+Fast, native compression plugin for [Rolldown](https://rolldown.rs): compresses emitted assets with **gzip**, **brotli** and **zstd** at build time. The compression core is written in Rust (napi-rs + rayon) — one batched FFI call per build, fanned out across all CPU cores, without ever blocking the JS event loop.
+
+API ergonomics mirror [`vite-plugin-compression2`](https://github.com/nonzzz/vite-plugin-compression); see [differences](#differences-from-vite-plugin-compression2).
+
+## Install
+
+```sh
+npm install -D @medicomind/rolldown-compression
+```
+
+Prebuilt binaries are installed automatically — no Rust toolchain needed (see [platform support](#platform-support)).
+
+## Quick start
+
+```ts
+// rolldown.config.ts
+import { defineConfig } from 'rolldown'
+import { compression } from '@medicomind/rolldown-compression'
+
+export default defineConfig({
+  input: 'src/main.ts',
+  plugins: [
+    // gzip + brotli with defaults
+    compression(),
+  ],
+})
+```
+
+Full configuration:
+
+```ts
+import { compression, defineAlgorithm } from '@medicomind/rolldown-compression'
+
+compression({
+  include: [/\.(js|mjs|css|html|svg|json|wasm)$/],
+  exclude: [/\.(png|jpe?g|webp|woff2?)$/],
+  threshold: 1024,
+  algorithms: [
+    'gzip', // string shorthand with default level
+    defineAlgorithm('brotli', { quality: 11 }),
+    defineAlgorithm('zstd', { level: 19 }),
+  ],
+  filename: '[path][base].gz', // or (fileName, algorithm) => string
+  deleteOriginalAssets: false,
+  skipIfLargerOrEqual: true,
+  concurrency: 0, // 0 = number of logical CPUs
+  logLevel: 'info',
+})
+```
+
+## Options
+
+| option | type | default | description |
+| --- | --- | --- | --- |
+| `include` | `string \| RegExp \| Array<string \| RegExp>` | `/\.(html\|xml\|css\|json\|js\|mjs\|svg\|yaml\|yml\|toml\|txt\|wasm)$/` | Files to compress. Strings are [picomatch](https://github.com/micromatch/picomatch) globs, matched against bundle-relative file names ([`@rollup/pluginutils` `createFilter`](https://github.com/rollup/plugins/tree/master/packages/pluginutils#createfilter) semantics). |
+| `exclude` | `string \| RegExp \| Array<string \| RegExp>` | — | Files to skip. **Wins over `include`.** |
+| `threshold` | `number` | `0` | Minimum original size in bytes for a file to be compressed. |
+| `algorithms` | `Array<AlgorithmName \| DefineAlgorithmResult>` | `['gzip', 'brotli']` | Algorithms to run. Aliases `gz`, `br`, `brotliCompress`, `zstandard` normalize to `gzip` / `brotli` / `zstd`. |
+| `filename` | `string \| (fileName, algorithm) => string` | `'[path][base]' + ext` | Name of the emitted artifact. Tokens: `[path]` (directory incl. trailing `/`), `[base]`, `[name]`, `[ext]` (with dot), `[hash]` (8-char sha256 of the content). Default extensions: `.gz`, `.br`, `.zst`. |
+| `deleteOriginalAssets` | `boolean` | `false` | Remove the original from the bundle after all algorithms processed it. Errors if `filename` resolves to the source name. |
+| `skipIfLargerOrEqual` | `boolean` | `true` | Don't emit artifacts whose compressed size is `>=` the original. |
+| `concurrency` | `number` | `0` | Native worker threads. `0` = number of logical CPUs. |
+| `logLevel` | `'silent' \| 'error' \| 'warn' \| 'info'` | `'info'` | Plugin log verbosity; `info` prints a per-algorithm summary at build end. |
+| `enableInWatchMode` | `boolean` | `false` | The plugin is a no-op in watch/dev mode unless enabled (see [watch mode](#watch--dev-mode)). |
+
+All options are validated when `compression()` is called — invalid levels (e.g. brotli quality 12), unknown algorithm names or malformed filters throw immediately, not mid-build.
+
+### Per-algorithm options
+
+| algorithm | option | range | default |
+| --- | --- | --- | --- |
+| `gzip` | `level` | 0–9 | 6 |
+| `brotli` | `quality` | 0–11 | 11 |
+| `brotli` | `windowBits` | 10–24 | 22 |
+| `zstd` | `level` | 1–22 | 19 |
+
+```ts
+defineAlgorithm('gzip', { level: 9 })
+defineAlgorithm('brotli', { quality: 7, windowBits: 22 })
+defineAlgorithm('zstd', { level: 12 })
+```
+
+## How it works
+
+- The plugin hooks **`generateBundle`**, while all chunks and assets are still in memory — no filesystem round-trip. Eligible files (filter + threshold) are sent to the native module as **one batched FFI call per build**; results are emitted with `emitFile`.
+- Compression runs on a rayon thread pool inside the native module (`AsyncTask`), parallel across files *and* algorithms, scheduled most-expensive-first so one large brotli file can't stretch the batch tail. The JS event loop keeps ticking throughout (covered by a test).
+- Buffers cross the FFI boundary without base64/string round-trips, and the compression working set lives in native memory — a 500 MB asset does not pressure the JS heap.
+- A failing task never aborts the batch: per-task errors are aggregated and fail the build with one message.
+- Already-compressed artifacts (`.gz`, `.br`, `.zst` — ours or pre-existing) are never re-compressed, so chaining plugin instances can't produce `app.js.gz.br`.
+
+Limitation: assets written to disk by other plugins in `writeBundle`/`closeBundle` (i.e. after `generateBundle`) are not seen by this plugin. This matches how `vite-plugin-compression2` handles the in-bundle pass; a `writeBundle` fallback was deliberately left out to keep the pipeline zero-copy and single-pass. File an issue if you have a concrete case.
+
+### Watch / dev mode
+
+The plugin declares `apply: 'build'` (honored by Vite-style hosts such as `rolldown-vite`) **and** checks `this.meta.watchMode` at `generateBundle` time, making it a no-op under `rolldown --watch`. Set `enableInWatchMode: true` to compress in watch builds anyway.
+
+## Serving pre-compressed assets
+
+nginx ([gzip_static](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html) / [brotli_static](https://github.com/google/ngx_brotli) / [zstd_static](https://github.com/tokers/zstd-nginx-module)):
+
+```nginx
+location / {
+  gzip_static on;     # serves foo.js.gz when the client accepts gzip
+  brotli_static on;   # requires ngx_brotli
+  zstd_static on;     # requires zstd-nginx-module
+}
+```
+
+Caddy:
+
+```caddyfile
+example.com {
+  root * /srv/dist
+  file_server {
+    precompressed zstd br gzip
+  }
+}
+```
+
+## Benchmark
+
+`npm run bench` (or `node benchmark/index.mjs --quick`) generates a dist-shaped fixture set — 200 files / ~48 MB with a long-tail size distribution — and compresses it with the native core vs `node:zlib` driven at full parallelism via `Promise.all` (the reference plugin's best case). Both sides always use the same levels.
+
+Results on an Apple M1 Pro (10 cores), Node 26, default `UV_THREADPOOL_SIZE`:
+
+| scenario | output | native (rust) | node:zlib | speedup |
+| --- | --- | --- | --- | --- |
+| gzip+brotli (ref. defaults: 9/11) | 8.71 MB | 8.82s | 15.19s | **1.72x** |
+| gzip (level 9) | 5.51 MB | 0.10s | 0.33s | **3.48x** |
+| gzip (level 6) | 5.64 MB | 0.07s | 0.16s | **2.38x** |
+| brotli (quality 11) | 3.21 MB | 8.16s | 14.96s | **1.83x** |
+| zstd (level 19) | 3.28 MB | 2.19s | 6.91s | **3.15x** |
+
+Reading these numbers honestly:
+
+- **gzip** and **zstd** beat the ≥3x target: the Rust encoders ([zlib-rs](https://github.com/trifectatechfoundation/zlib-rs), ~2.4x faster per core than node's bundled zlib in our measurements; libzstd) are faster per core *and* use every core, while `node:zlib` is capped at `UV_THREADPOOL_SIZE` (default 4) threads.
+- **brotli at quality 11** is the bound on the combined number: the Rust `brotli` crate is at per-core parity with node's C brotli (we measured a 1.01 single-thread ratio), so the achievable speedup is roughly `cores / UV_THREADPOOL_SIZE` — ~2x on 8 equal cores, more on bigger machines. No implementation can honestly do better without changing the algorithm or its level.
+- The speedup grows with core count and shrinks if you raise `UV_THREADPOOL_SIZE` for the JS side — the benchmark prints both so runs are comparable.
+
+## Platform support
+
+Prebuilt binaries are published for:
+
+| platform | triple |
+| --- | --- |
+| macOS arm64 | `aarch64-apple-darwin` |
+| macOS x64 | `x86_64-apple-darwin` |
+| Linux x64 (glibc) | `x86_64-unknown-linux-gnu` |
+| Linux arm64 (glibc) | `aarch64-unknown-linux-gnu` |
+| Linux x64 (musl) | `x86_64-unknown-linux-musl` |
+| Windows x64 | `x86_64-pc-windows-msvc` |
+
+Node.js >= 18.
+
+## Differences from vite-plugin-compression2
+
+- **Native speed**: compression runs in Rust on all cores, one FFI batch per build, instead of `node:zlib` calls through the libuv thread pool.
+- **No custom JS algorithms**: `algorithms` accepts only the built-in `gzip` / `brotli` / `zstd` (function-form algorithms can't cross the FFI boundary). `defineAlgorithm` returns an opaque object, not a `[name, options]` tuple — treat it as such.
+- **No tarball plugin**: out of scope.
+- **gzip default level is 6** (zlib default), not 9 — measurably faster for a ~1% size difference. Pass `defineAlgorithm('gzip', { level: 9 })` to match the reference.
+- **zstd everywhere**: zstd is compiled in, with no dependency on the Node runtime's zstd support (node >= 22.15).
+- Extra options: `concurrency` (native thread cap) and `enableInWatchMode`.
+
+## Implementation decisions
+
+- **Rolldown target**: developed and tested against `rolldown@1.1.x` (peer range `^1.0.0`), using the Rollup-compatible `generateBundle`/`emitFile` plugin API.
+- **gzip backend**: `flate2` with the pure-Rust `zlib-rs` backend — as fast as or faster than zlib-ng in our runs, with no cmake/C toolchain requirement for contributors.
+- **Publishing**: public npm (`--access public`), versioned with [changesets](https://github.com/changesets/changesets). PRs include a changeset (`npx changeset`); the Version workflow keeps a `chore: release` PR up to date, and merging it tags the release and runs the full napi build matrix before `napi prepublish` + `npm publish`. Run the Release workflow via `workflow_dispatch` for a dry-run that builds all platform artifacts without publishing.
+
+## Development
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide (setup, tests, changesets, PR workflow).
+
+```sh
+npm install          # install JS deps
+npm run build        # release native build + TS bundle
+npm test             # vitest (unit + integration)
+cargo test           # Rust core tests
+npm run bench        # benchmark vs node:zlib
+COMPRESSION_TEST_LARGE=1 npx vitest run __tests__/integration/large-file.test.ts  # 150 MB asset test
+npx changeset        # add a changeset describing your change (required for releases)
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,309 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let node_crypto = require("node:crypto");
+let node_path = require("node:path");
+node_path = __toESM(node_path);
+let _rollup_pluginutils = require("@rollup/pluginutils");
+let node_module = require("node:module");
+//#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: (0, _rollup_pluginutils.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 = node_path.default.posix.dirname(fileName);
+	const base = node_path.default.posix.basename(fileName);
+	const ext = node_path.default.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]", () => (0, node_crypto.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 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../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
+exports.compression = compression;
+exports.defineAlgorithm = defineAlgorithm;

package/dist/index.d.cts

@@ -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 };