@codernex/nexpress 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borhan Uddin
+
+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/dist/image-processor.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parentPort, workerData } from "node:worker_threads";
+import sharp from "sharp";
+const { input, output, fileName, quality } = workerData;
+// 2. Fix: Correctly parse quality (The original RegExp was invalid)
+const parsedQuality = parseInt(quality, 10);
+const qualityArg = !isNaN(parsedQuality) && parsedQuality > 0 && parsedQuality <= 100
+    ? parsedQuality
+    : 80;
+async function ensureDirectory(dirPath) {
+    // 3. Optimization: mkdir with recursive is idempotent; no need to check access first
+    await fs.mkdir(dirPath, { recursive: true });
+}
+async function compressImage() {
+    try {
+        await ensureDirectory(output);
+        // Validate input file exists
+        try {
+            await fs.access(input);
+        }
+        catch {
+            throw new Error(`Input file not found: ${input}`);
+        }
+        const { name } = path.parse(fileName);
+        const outputFileName = `${name}.webp`;
+        const outputFilePath = path.join(output, outputFileName);
+        // 4. Fix: Sharp Configuration
+        // Removed 'lossless: true' because it conflicts with 'quality'.
+        // If a user sets quality=50, they want lossy compression to save space.
+        const result = await sharp(input)
+            .webp({
+            quality: qualityArg,
+            effort: 4, // Trade-off between compression speed and size (0-6)
+        })
+            .toFile(outputFilePath);
+        const originalStats = await fs.stat(input);
+        const savedBytes = originalStats.size - result.size;
+        // Convert bytes to Megabytes (1 MB = 1024 * 1024 bytes)
+        const savedMB = (savedBytes / (1024 * 1024)).toFixed(2);
+        const originalSize = (originalStats.size / (1024 * 1024)).toFixed(2);
+        const currentSize = (result.size / (1024 * 1024)).toFixed(2);
+        parentPort?.postMessage({
+            status: "completed",
+            data: {
+                size: result.size,
+                width: result.width,
+                height: result.height,
+                inputFile: fileName,
+                outputFile: outputFileName,
+                originalSize,
+                currentSize,
+                savedMB: `${savedMB} MB`,
+            },
+        });
+    }
+    catch (err) {
+        const error = err;
+        parentPort?.postMessage({
+            status: "error",
+            err: {
+                message: error.message,
+                stack: error.stack,
+                fileName,
+                type: error.constructor.name,
+            },
+        });
+    }
+}
+parentPort?.on("message", (message) => {
+    if (message.type === "compress") {
+        compressImage();
+    }
+});
+// Global error handlers
+process.on("uncaughtException", (err) => {
+    parentPort?.postMessage({
+        status: "error",
+        err: {
+            message: `Uncaught exception: ${err.message}`,
+            stack: err.stack,
+            fileName,
+        },
+    });
+    process.exit(1);
+});
+process.on("unhandledRejection", (reason) => {
+    parentPort?.postMessage({
+        status: "error",
+        err: {
+            message: `Unhandled rejection: ${String(reason)}`,
+            fileName,
+        },
+    });
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,147 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Worker } from "node:worker_threads";
+import { v4 as uuidV4 } from "uuid";
+/**
+ * Constants
+ */
+const MAX_WORKERS = Math.max(1, os.cpus().length - 2);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const homeDir = os.homedir();
+const acceptableArgs = ["--input", "--output", "--quality", "--help"];
+const args = process.argv.slice(2); // Use slice instead of splice
+const filteredArgs = args.filter((p) => {
+    const [key] = p.split("=");
+    return acceptableArgs.includes(key);
+});
+if (filteredArgs.length === 1) {
+    console.log(`
+    Usage: compressts [options]
+
+Description:
+  A multi-threaded image batch processor. Reads images from a source directory 
+  (relative to user home), processes them using worker threads, and saves 
+  them to an output directory.
+
+Options:
+  --input=<path>     (Required) Name of the folder containing source images. 
+                     NOTE: This path is relative to your Home Directory.
+                     Supported formats: .jpg, .jpeg, .png, .webp
+
+  --output=<path>    (Required) Destination path for processed images. 
+                     Can be an absolute path or relative to your Home Directory.
+
+  --quality=<number> (Optional) The quality of the output image (0-100).
+                     Default: defined by processor if omitted.
+
+  --help             Show this help message.
+
+Examples:
+  # Process images from MyImages to MyImages/Compressed
+  node image-processor.js --input=MyImages --output=MyImages/Compressed
+
+  # Process with specific quality
+  node image-processor.js --input=RawPhotos --output=/tmp/Processed --quality=80
+
+  # Relative path to users like /home/users/Desktop pass Desktop otherwise pass /tmp/Processed
+    `);
+    process.exit(0);
+}
+if (filteredArgs.length < 2) {
+    throw new Error("Both --input and --output paths are required");
+}
+const workers = new Map();
+const keyValues = filteredArgs.map((arg) => {
+    const [key, value] = arg.split("=");
+    return { key, value };
+});
+const input = keyValues.find((k) => k.key === "--input")?.value;
+const output = keyValues.find((k) => k.key === "--output")?.value;
+const quality = keyValues.find((k) => k.key === "--quality")?.value ?? "";
+if (!input || !output)
+    throw new Error("Input or Output is missing");
+if (quality && Number.isNaN(quality))
+    throw new Error("Quality Must be number");
+const inputPath = input.startsWith("/") ? input : path.join(homeDir, input);
+const outputPath = output.startsWith("/") ? output : path.join(homeDir, output);
+// Ensure output directory exists
+const allImages = fs.readdirSync(inputPath).filter((file) => {
+    const ext = path.extname(file);
+    return ext && [".jpg", ".jpeg", ".png", ".webp"].includes(ext.toLowerCase());
+});
+// Create workers
+allImages.forEach((fileName) => {
+    console.log("Processing:", fileName);
+    const workerId = uuidV4();
+    const worker = new Worker(path.join(__dirname, "image-processor.ts"), {
+        // Use .js file
+        workerData: {
+            input: path.join(inputPath, fileName),
+            output: outputPath,
+            fileName,
+            quality,
+        },
+    });
+    workers.set(workerId, {
+        status: "pending",
+        worker,
+        workerId,
+    });
+    // Register event listeners immediately
+    worker.on("message", (value) => {
+        if (value.status === "error") {
+            console.error(`Error processing ${fileName}:`, value.err);
+        }
+        if (value.status === "completed") {
+            console.log("============================\n");
+            console.log(`Image processing completed: ${fileName}`, `WorkerId: ${workerId}`, `ThreadId: ${worker.threadId}`);
+            console.log("Result: ", value.data);
+            console.log("============================\n\n");
+            workers.get(workerId).status = "completed";
+        }
+        worker.terminate();
+        workers.delete(workerId);
+    });
+    worker.on("error", (err) => {
+        console.error(`Worker error for ${fileName}:`, err);
+        worker.terminate();
+        workers.delete(workerId);
+    });
+    worker.on("exit", (code) => {
+        if (code !== 0) {
+            console.error(`Worker stopped with exit code ${code} for ${fileName}`);
+        }
+    });
+});
+const workerQueue = Array.from(workers.values()).filter((c) => c.status === "pending");
+let active = 0;
+function runNext() {
+    while (workerQueue.length > 0 && active < MAX_WORKERS) {
+        active++;
+        const job = workerQueue.shift();
+        if (job) {
+            runWorker(job.worker).finally(() => {
+                active--;
+                runNext();
+            });
+        }
+    }
+}
+async function runWorker(worker) {
+    worker.postMessage({
+        type: "compress",
+    });
+}
+// Start processing
+runNext();
+// Graceful shutdown
+process.on("SIGINT", () => {
+    console.log("\nShutting down workers...");
+    workers.forEach(({ worker }) => {
+        worker.terminate();
+    });
+    process.exit(0);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@codernex/nexpress",
+  "version": "1.0.0",
+  "description": "Multi-threaded image batch processor CLI",
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "nexpress": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --watch --loader ts-node/esm src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "image-processing",
+    "cli",
+    "sharp",
+    "worker-threads"
+  ],
+  "author": "@codernex",
+  "license": "ISC",
+  "dependencies": {
+    "axios": "^1.13.2",
+    "cheerio": "^1.1.2",
+    "sharp": "^0.34.5",
+    "typescript": "^5.9.3",
+    "uuid": "^11.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@types/uuid": "^10.0.0",
+    "ts-node": "^10.9.2"
+  }
+}

package/readme.md

@@ -0,0 +1,146 @@
+# NexPress - TypeScript Image Batch Processor CLI
+
+A high-performance, multi-threaded command-line tool built with Node.js and TypeScript. It converts and compresses batches of images into efficient **WebP** format using worker threads for maximum speed.
+
+## 🚀 Features
+
+- **Multi-threaded Processing:** Uses Node.js `worker_threads` to process images in parallel, utilizing all available CPU cores.
+- **Format Conversion:** Automatically converts `.jpg`, `.jpeg`, and `.png` files to optimized `.webp`.
+- **Smart Path Handling:** Supports both absolute system paths and paths relative to your home directory.
+- **Space Savings:** Calculates and displays the amount of disk space saved per image in MB.
+- **Custom Quality:** User-definable compression quality (1-100).
+- **Robust Error Handling:** Graceful shutdowns and detailed error logging.
+
+## 📦 Installation
+
+You can use NexPress in three ways:
+
+### 1. Global Installation (Recommended)
+
+This installs the `nexpress` command system-wide.
+
+```bash
+npm install -g nexpress
+
+```
+
+### 2. Run Once with npx
+
+Use it immediately without installing.
+
+```bash
+npx nexpress --input=Desktop/photos --output=Desktop/compressed
+
+```
+
+### 3. Local Development / Building from Source
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd nexpress
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link globally for testing
+npm link
+
+```
+
+## 🛠 Usage
+
+If installed globally or linked, simply run `nexpress`:
+
+```bash
+nexpress --input=<path> --output=<path> [options]
+
+```
+
+### 📂 Path Flexibility
+
+NexPress is smart about file paths. You can provide:
+
+1. **Relative Paths (from User Home):**
+   If you type `Desktop/images`, the tool looks in `~/Desktop/images` (Linux/Mac) or `C:\Users\You\Desktop\images` (Windows).
+
+```bash
+nexpress --input=Desktop/raw --output=Desktop/processed
+
+```
+
+2. **Absolute Paths:**
+   You can also provide the full system path.
+
+```bash
+nexpress --input=/home/user/Downloads/pics --output=/var/www/html/assets
+
+```
+
+### Options
+
+| Option      | Required | Description                                        | Default |
+| ----------- | -------- | -------------------------------------------------- | ------- |
+| `--input`   | ✅       | Source folder path (Absolute or relative to Home). | N/A     |
+| `--output`  | ✅       | Destination folder path.                           | N/A     |
+| `--quality` | ❌       | Compression quality (1-100).                       | `80`    |
+| `--help`    | ❌       | Displays the help menu.                            | N/A     |
+
+### Examples
+
+**Standard Compression (Default Quality: 80)**
+
+```bash
+nexpress --input=Photos --output=CompressedPhotos
+
+```
+
+**High Compression (Maximum Space Saving)**
+
+```bash
+nexpress --input=Desktop/Wallpapers --output=Desktop/WebP_Small --quality=50
+
+```
+
+**High Quality (Near Lossless)**
+
+```bash
+nexpress --input=/mnt/data/raw --output=/mnt/data/optimized --quality=95
+
+```
+
+## 💻 Development
+
+If you want to contribute or modify the code:
+
+1. **Clone and Install:**
+
+```bash
+git clone <your-repo-url>
+npm install
+
+```
+
+2. **Run in Development Mode:**
+   You can run the script directly using `ts-node`.
+
+```bash
+# Run directly without building
+npx ts-node src/index.ts --input=TestIn --output=TestOut
+
+```
+
+## 🏗 Architecture
+
+The tool uses a **Main Thread** -> **Worker Pool** architecture:
+
+1. **Main Thread:** Scans the input directory and creates a queue of image processing jobs.
+2. **Worker Threads:** Each CPU core gets a worker. The main thread distributes jobs to workers dynamically.
+3. **Sharp:** Inside the worker, the `sharp` library handles the actual image buffer manipulation and WebP conversion.
+
+## 📝 License
+
+This project is licensed under the MIT License.