zcompress-vite-plugin 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# zcompress Vite Plugin
+
+High-performance multi-threaded asset compression for Vite production builds, powered by [zcompress](https://github.com/luochuan2008/zcompress) (Zig).
+
+## Features
+
+- 🧵 **Multi-threaded** — all CPU cores, not just one
+- ⚡ **5-10x faster** than Node.js compression plugins
+- 📦 **gzip**, **zstd**, **brotli** — all three algorithms
+- 💾 **Incremental cache** — skip unchanged files
+
+## Quick Start
+
+```bash
+npm install zcompress-vite-plugin --save-dev
+```
+
+```js
+// vite.config.js
+import zcompress from 'zcompress-vite-plugin';
+
+export default {
+  plugins: [
+    zcompress({
+      algo: 'gzip',    // 'gzip' | 'zstd' | 'brotli'
+      level: 6,        // 1-9
+      threads: 4,      // 0 = auto
+      cache: true,     // skip unchanged files
+    })
+  ]
+};
+```
+
+After `vite build`, you'll get a `dist-compressed/` folder with `.gz` (or `.zst`/`.br`) files.
+
+## How It Works
+
+The plugin ships a JS wrapper. On `npm install`, it downloads the prebuilt Zig binary for your platform from GitHub Releases. If the download fails (air-gapped, unsupported arch), it falls back to looking for `zcompress` in your PATH.
+
+```bash
+# Manual install (if auto-download fails)
+brew install zcompress           # macOS
+zig build install                # from source
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `algo` | `'gzip' \| 'zstd' \| 'brotli'` | `'gzip'` | Compression algorithm |
+| `level` | `number` | `6` | Compression level (1-9) |
+| `threads` | `number` | `0` | Thread count (0 = auto) |
+| `verbose` | `boolean` | `false` | Verbose output |
+| `cache` | `boolean` | `false` | Skip unchanged files |
+| `include` | `string[]` | `[]` | Extra extensions to compress |
+| `exclude` | `string[]` | `[]` | Extensions to skip |
+| `binaryPath` | `string` | auto | Override binary path |
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,25 @@
+declare module 'zcompress-vite-plugin' {
+  interface ZCompressOptions {
+    /** Compression algorithm: 'gzip' | 'zstd' | 'brotli' (default: 'gzip') */
+    algo?: 'gzip' | 'zstd' | 'brotli';
+    /** Compression level: 1-9 (default: 6) */
+    level?: number;
+    /** Thread count, 0 = auto (default: 0) */
+    threads?: number;
+    /** Verbose output (default: false) */
+    verbose?: boolean;
+    /** Enable incremental cache (default: false) */
+    cache?: boolean;
+    /** Extra file extensions to include (e.g. ['.ts', '.tsx']) */
+    include?: string[];
+    /** File extensions to exclude (e.g. ['.map']) */
+    exclude?: string[];
+    /** Override path to zcompress binary */
+    binaryPath?: string;
+  }
+
+  import type { Plugin } from 'vite';
+
+  function zcompressPlugin(options?: ZCompressOptions): Plugin;
+  export default zcompressPlugin;
+}

package/index.js

@@ -0,0 +1,203 @@
+/**
+ * zcompress Vite Plugin
+ *
+ * A Vite plugin that compresses build output using the zcompress CLI.
+ * Provides multi-threaded gzip/zstd compression for production builds.
+ *
+ * @example
+ * // vite.config.js
+ * import zcompress from 'zcompress-vite-plugin';
+ *
+ * export default {
+ *   plugins: [
+ *     zcompress({ algo: 'gzip', level: 6, threads: 4 })
+ *   ]
+ * };
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * @typedef {Object} ZCompressOptions
+ * @property {string} [algo='gzip'] - Compression algorithm: gzip, zstd, brotli
+ * @property {number} [level=6] - Compression level: 1-9
+ * @property {number} [threads=0] - Thread count (0 = auto)
+ * @property {boolean} [verbose=false] - Verbose output
+ * @property {boolean} [cache=false] - Enable incremental caching
+ * @property {string[]} [include] - Extra file extensions to include
+ * @property {string[]} [exclude] - File extensions to exclude
+ * @property {string} [binaryPath] - Path to zcompress binary
+ */
+
+/** @type {ZCompressOptions} */
+const DEFAULT_OPTIONS = {
+  algo: 'gzip',
+  level: 6,
+  threads: 0,
+  verbose: false,
+  cache: false,
+  include: [],
+  exclude: [],
+};
+
+/**
+ * Find the zcompress binary.
+ * Order: 1) downloaded by postinstall  2) PATH  3) local zig build
+ */
+function findBinary() {
+  // 1. Check for postinstall-downloaded binary
+  const binDir = join(__dirname, 'bin');
+  const localBin = join(binDir, process.platform === 'win32' ? 'zcompress.exe' : 'zcompress');
+  if (existsSync(localBin)) return localBin;
+
+  // 2. Check local zig build
+  const zigPaths = [
+    join(process.cwd(), 'zig-out', 'bin', 'zcompress'),
+    join(process.cwd(), 'zig-out', 'bin', 'zcompress.exe'),
+  ];
+  for (const p of zigPaths) {
+    if (existsSync(p)) return p;
+  }
+
+  // 3. Fall back to PATH
+  return 'zcompress';
+}
+
+/**
+ * Create the zcompress Vite plugin.
+ *
+ * @param {ZCompressOptions} userOptions
+ * @returns {import('vite').Plugin}
+ */
+export default function zcompressPlugin(userOptions = {}) {
+  const options = { ...DEFAULT_OPTIONS, ...userOptions };
+
+  return {
+    name: 'zcompress',
+    apply: 'build',
+    enforce: 'post',
+
+    configResolved(config) {
+      // Only run in production build mode
+      this.active = config.command === 'build';
+    },
+
+    closeBundle() {
+      if (!this.active) return;
+
+      const outDir = this.outDir || 'dist';
+      const compressedDir = `${outDir}-compressed`;
+
+      if (!existsSync(outDir)) {
+        console.warn(`[zcompress] Output directory "${outDir}" not found. Skipping.`);
+        return;
+      }
+
+      const binary = options.binaryPath || findBinary();
+      const args = [
+        '-i', outDir,
+        '-o', compressedDir,
+        '-a', options.algo,
+        '-l', String(options.level),
+      ];
+
+      if (options.threads > 0) {
+        args.push('-t', String(options.threads));
+      }
+      if (options.verbose) args.push('--verbose');
+      if (options.cache) args.push('--cache');
+
+      for (const ext of options.include) {
+        args.push(`--include=${ext}`);
+      }
+      for (const ext of options.exclude) {
+        args.push(`--exclude=${ext}`);
+      }
+
+      const cmd = `${binary} ${args.join(' ')}`;
+
+      if (options.verbose) {
+        console.log(`[zcompress] Running: ${cmd}`);
+      }
+
+      const startTime = Date.now();
+
+      try {
+        execSync(cmd, { stdio: 'inherit' });
+        const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+        // Calculate size stats
+        const srcSize = getDirSize(outDir);
+        const destSize = getDirSize(compressedDir);
+        const savedPct = srcSize > 0
+          ? ((1 - destSize / srcSize) * 100).toFixed(1)
+          : '0.0';
+
+        console.log(`[zcompress] ✅ Compressed ${formatSize(srcSize)} → ${formatSize(destSize)} (saved ${savedPct}%) in ${elapsed}s`);
+      } catch (err) {
+        console.error(`[zcompress] ❌ Compression failed: ${err.message}`);
+        console.error('[zcompress] Make sure zcompress is installed: zig build install');
+      }
+    },
+  };
+}
+
+/**
+ * Calculate total directory size in bytes.
+ *
+ * @param {string} dirPath
+ * @returns {number}
+ */
+function getDirSize(dirPath) {
+  if (!existsSync(dirPath)) return 0;
+  // Simple approximation — list files and sum their sizes
+  let total = 0;
+  try {
+    const { readdirSync } = require('node:fs');
+    const { join } = require('node:path');
+    walkDir(dirPath, (filePath) => {
+      try {
+        total += statSync(filePath).size;
+      } catch (_) { /* ignore */ }
+    });
+  } catch (_) { /* ignore */ }
+  return total;
+}
+
+/**
+ * Recursively walk a directory.
+ *
+ * @param {string} dir
+ * @param {(path: string) => void} fn
+ */
+function walkDir(dir, fn) {
+  const { readdirSync } = require('node:fs');
+  const { join } = require('node:path');
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkDir(full, fn);
+      } else {
+        fn(full);
+      }
+    }
+  } catch (_) { /* ignore */ }
+}
+
+/**
+ * Format bytes into human-readable string.
+ *
+ * @param {number} bytes
+ * @returns {string}
+ */
+function formatSize(bytes) {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const size = (bytes / Math.pow(1024, i)).toFixed(1);
+  return `${size} ${units[Math.min(i, units.length - 1)]}`;
+}

package/install.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script — downloads the prebuilt zcompress binary from GitHub Releases.
+ * Falls back gracefully if the binary can't be downloaded (e.g. air-gapped, unsupported platform).
+ */
+
+import { execSync } from 'node:child_process';
+import { createWriteStream, existsSync, chmodSync, mkdirSync, unlinkSync } from 'node:fs';
+import { get } from 'node:https';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pipeline } from 'node:stream/promises';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BIN_DIR = join(__dirname, 'bin');
+const VERSION = '0.1.0'; // Update on each release
+const REPO = 'luochuan2008/zcompress'; // Change to your GitHub username/repo
+
+const PLATFORM_MAP = {
+  'darwin-arm64':  'zcompress-macos-arm64',
+  'darwin-x64':    'zcompress-macos-x64',
+  'linux-x64':     'zcompress-linux-x64',
+  'win32-x64':     'zcompress-windows-x64.exe',
+};
+
+function getPlatformKey() {
+  const os = process.platform;
+  const arch = process.arch === 'x64' ? 'x64' : process.arch === 'arm64' ? 'arm64' : process.arch;
+  return `${os}-${arch}`;
+}
+
+function getBinaryName() {
+  const key = getPlatformKey();
+  return PLATFORM_MAP[key] || null;
+}
+
+async function downloadBinary() {
+  const binaryName = getBinaryName();
+  if (!binaryName) {
+    console.log(`[zcompress] ⚠ Unsupported platform: ${getPlatformKey()}. Build from source: zig build install`);
+    return false;
+  }
+
+  const destPath = join(BIN_DIR, process.platform === 'win32' ? 'zcompress.exe' : 'zcompress');
+
+  // Skip if already downloaded
+  if (existsSync(destPath)) {
+    console.log(`[zcompress] ✓ Binary already installed: ${destPath}`);
+    return true;
+  }
+
+  const url = `https://github.com/${REPO}/releases/download/v${VERSION}/${binaryName}`;
+  console.log(`[zcompress] ↓ Downloading ${url} ...`);
+
+  try {
+    mkdirSync(BIN_DIR, { recursive: true });
+
+    await new Promise((resolve, reject) => {
+      const file = createWriteStream(destPath);
+      get(url, (response) => {
+        // Follow redirects
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          get(response.headers.location, (redirectRes) => {
+            pipeline(redirectRes, file).then(resolve).catch(reject);
+          }).on('error', reject);
+          return;
+        }
+        if (response.statusCode !== 200) {
+          file.close();
+          unlinkSync(destPath);
+          reject(new Error(`HTTP ${response.statusCode}`));
+          return;
+        }
+        pipeline(response, file).then(resolve).catch(reject);
+      }).on('error', reject);
+    });
+
+    // Make executable on Unix
+    if (process.platform !== 'win32') {
+      chmodSync(destPath, 0o755);
+    }
+
+    console.log(`[zcompress] ✓ Binary installed: ${destPath}`);
+    return true;
+  } catch (err) {
+    console.log(`[zcompress] ⚠ Could not download binary (${err.message}). Build from source: cd zcompress && zig build install`);
+    // Clean up partial download
+    try { unlinkSync(destPath); } catch (_) { /* ignore */ }
+    return false;
+  }
+}
+
+// Run download, but don't fail install if it doesn't work
+downloadBinary().catch(() => {
+  console.log('[zcompress] ℹ Binary download skipped. The plugin requires the zcompress CLI.');
+  console.log('[zcompress] ℹ Install it via: brew install zcompress  OR  zig build install');
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "zcompress-vite-plugin",
+  "version": "0.1.0",
+  "description": "High-performance multi-threaded asset compression for Vite — powered by Zig",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "install.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node install.js",
+    "test": "node test.js"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "compression",
+    "gzip",
+    "zstd",
+    "brotli",
+    "assets",
+    "zig",
+    "performance",
+    "multi-threaded"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luochuan2008/zcompress"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}