@blazediff/bin 3.0.0 → 3.1.1

package/README.md

@@ -10,12 +10,17 @@
 The fastest single-threaded image diff in the world. Native Rust implementation with SIMD optimization, **3-4x faster** and **3x smaller** than [odiff](https://github.com/dmtrKovalenko/odiff).
 
 **Features:**
+- **PNG & JPEG support** - auto-detected by file extension
 - SIMD-accelerated (NEON on ARM, SSE4.1 on x86)
 - Block-based two-pass optimization
 - YIQ perceptual color difference
 - Anti-aliasing detection
 - Cross-platform pre-built binaries (~700KB-900KB, no compilation required)
 
+**Vendored Libraries:**
+- [libspng](https://libspng.org/) - Fast PNG decoding/encoding with SIMD
+- [libjpeg-turbo](https://libjpeg-turbo.org/) - High-performance JPEG codec with SIMD
+
 ## Installation
 
 ```bash
@@ -34,7 +39,7 @@ Pre-built [binaries](https://github.com/teimurjan/blazediff/tree/main/packages/b
 
 ### compare(basePath, comparePath, diffOutput, options?)
 
-Compare two PNG images and generate a diff image.
+Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detected from file extension.
 
 <table>
   <tr>
@@ -133,15 +138,24 @@ if (result.match) {
 ### CLI Usage
 
 ```bash
-# Compare two images
+# Compare two PNG images
 npx blazediff expected.png actual.png diff.png
 
+# Compare two JPEG images
+npx blazediff expected.jpg actual.jpg diff.jpg
+
+# Mixed formats (PNG input, JPEG output)
+npx blazediff expected.png actual.png diff.jpg
+
 # With options
 npx blazediff expected.png actual.png diff.png --threshold 0.05 --antialiasing
 
-# With higher compression (smaller output file, slower)
+# With higher PNG compression (smaller output file, slower)
 npx blazediff expected.png actual.png diff.png -c 6
 
+# With JPEG quality setting
+npx blazediff expected.jpg actual.jpg diff.jpg -q 85
+
 # Output as JSON
 npx blazediff expected.png actual.png diff.png --output-format json
 ```
@@ -149,24 +163,34 @@ npx blazediff expected.png actual.png diff.png --output-format json
 ### CLI Options
 
 ```
-Usage: blazediff [OPTIONS] <IMAGE1> <IMAGE2> <OUTPUT>
+Usage: blazediff [OPTIONS] <IMAGE1> <IMAGE2> [OUTPUT]
 
 Arguments:
-  <IMAGE1>  First image path
-  <IMAGE2>  Second image path
-  <OUTPUT>  Output diff image path
+  <IMAGE1>  First image path (PNG or JPEG)
+  <IMAGE2>  Second image path (PNG or JPEG)
+  [OUTPUT]  Output diff image path (optional, format detected from extension)
 
 Options:
   -t, --threshold <THRESHOLD>  Color difference threshold (0.0-1.0) [default: 0.1]
   -a, --antialiasing           Enable anti-aliasing detection
       --diff-mask              Output only differences (transparent background)
       --fail-on-layout         Fail on layout (size) difference
-  -c, --compression <LEVEL>    PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) [default: 0]
+  -c, --compression <LEVEL>    PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0]
+  -q, --quality <QUALITY>      JPEG quality (1-100) [default: 90]
       --output-format <FORMAT> Output format (json or text) [default: json]
   -h, --help                   Print help
   -V, --version                Print version
 ```
 
+### Supported Formats
+
+| Format | Extensions | Notes |
+|--------|------------|-------|
+| PNG | `.png` | Lossless, supports transparency |
+| JPEG | `.jpg`, `.jpeg` | Lossy, smaller file sizes |
+
+Input images can be mixed formats (e.g., compare PNG to JPEG). Output format is determined by the output file extension.
+
 ### Exit Codes
 
 - `0` - Images are identical
@@ -175,7 +199,7 @@ Options:
 
 ## Performance
 
-Benchmarked on Apple M1 Pro with 5600x3200 4K images:
+Benchmarked on Apple M1 Pro with 5600x3200 4K PNG images:
 
 | Tool | Benchmark Time | vs blazediff |
 |------|------|--------------|

package/dist/index.d.ts

@@ -9,6 +9,8 @@ interface BlazeDiffOptions {
     failOnLayoutDiff?: boolean;
     /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
     compression?: number;
+    /** JPEG quality (1-100). Default: 90 */
+    quality?: number;
 }
 type BlazeDiffResult = {
     match: true;
@@ -26,7 +28,11 @@ type BlazeDiffResult = {
     file: string;
 };
 /**
- * Compare two PNG images and optionally generate a diff image.
+ * Compare two images (PNG or JPEG) and optionally generate a diff image.
+ *
+ * Uses native N-API bindings when available for ~10-100x better performance
+ * on small images (no process spawn overhead). Falls back to execFile if
+ * native bindings are unavailable.
  *
  * @example
  * ```ts
@@ -46,5 +52,10 @@ type BlazeDiffResult = {
 declare function compare(basePath: string, comparePath: string, diffOutput?: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
 /** Get the path to the blazediff binary for direct CLI usage. */
 declare function getBinaryPath(): string;
+/**
+ * Check if native N-API bindings are available.
+ * Returns true if the native module loaded successfully.
+ */
+declare function hasNativeBinding(): boolean;
 
-export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath };
+export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath, hasNativeBinding };

package/dist/index.js

@@ -31,7 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   compare: () => compare,
-  getBinaryPath: () => getBinaryPath
+  getBinaryPath: () => getBinaryPath,
+  hasNativeBinding: () => hasNativeBinding
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -74,6 +75,81 @@ var PLATFORM_PACKAGES = {
     packageDir: "bin-win32-x64"
   }
 };
+var nativeBinding = null;
+var nativeBindingAttempted = false;
+function tryLoadNativeBinding() {
+  if (nativeBindingAttempted) {
+    return nativeBinding;
+  }
+  nativeBindingAttempted = true;
+  const platform = import_node_os.default.platform();
+  const arch = import_node_os.default.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    return null;
+  }
+  try {
+    const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+    const binding = require2(platformInfo.packageName);
+    if (typeof binding?.compare === "function") {
+      nativeBinding = binding;
+      return binding;
+    }
+  } catch {
+  }
+  try {
+    const currentDir = import_node_path.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+    const packagesDir = import_node_path.default.resolve(currentDir, "..", "..");
+    const nodePath = import_node_path.default.join(
+      packagesDir,
+      platformInfo.packageDir,
+      "blazediff.node"
+    );
+    if ((0, import_node_fs.existsSync)(nodePath)) {
+      const require2 = (0, import_node_module.createRequire)(importMetaUrl);
+      const binding = require2(nodePath);
+      if (typeof binding?.compare === "function") {
+        nativeBinding = binding;
+        return binding;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function convertNapiResult(result) {
+  if (result.matchResult) {
+    return { match: true };
+  }
+  if (result.reason === "layout-diff") {
+    return { match: false, reason: "layout-diff" };
+  }
+  if (result.reason === "pixel-diff") {
+    return {
+      match: false,
+      reason: "pixel-diff",
+      diffCount: result.diffCount ?? 0,
+      diffPercentage: result.diffPercentage ?? 0
+    };
+  }
+  return {
+    match: false,
+    reason: "pixel-diff",
+    diffCount: result.diffCount ?? 0,
+    diffPercentage: result.diffPercentage ?? 0
+  };
+}
+function convertToNapiOptions(options) {
+  return {
+    threshold: options?.threshold,
+    antialiasing: options?.antialiasing,
+    diffMask: options?.diffMask,
+    failOnLayout: options?.failOnLayoutDiff,
+    compression: options?.compression,
+    quality: options?.quality
+  };
+}
 function resolveBinaryPath() {
   const platform = import_node_os.default.platform();
   const arch = import_node_os.default.arch();
@@ -130,6 +206,7 @@ function buildArgs(diffOutput, options) {
   if (options.failOnLayoutDiff) args.push("--fail-on-layout");
   if (options.compression !== void 0)
     args.push(`--compression=${options.compression}`);
+  if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
   return args;
 }
 function parseJsonOutput(text) {
@@ -147,7 +224,7 @@ function detectMissingFile(error, basePath, comparePath) {
   if (error.includes(comparePath)) return comparePath;
   return basePath;
 }
-async function compare(basePath, comparePath, diffOutput, options) {
+async function execFileCompare(basePath, comparePath, diffOutput, options) {
   const binaryPath = getBinaryPathInternal();
   const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
   try {
@@ -182,11 +259,37 @@ async function compare(basePath, comparePath, diffOutput, options) {
     throw new Error(output || `blazediff exited with code ${code}`);
   }
 }
+async function compare(basePath, comparePath, diffOutput, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    try {
+      const result = binding.compare(
+        basePath,
+        comparePath,
+        diffOutput ?? null,
+        convertToNapiOptions(options)
+      );
+      return convertNapiResult(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const missingFile = detectMissingFile(message, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+      throw err;
+    }
+  }
+  return execFileCompare(basePath, comparePath, diffOutput, options);
+}
 function getBinaryPath() {
   return getBinaryPathInternal();
 }
+function hasNativeBinding() {
+  return tryLoadNativeBinding() !== null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   compare,
-  getBinaryPath
+  getBinaryPath,
+  hasNativeBinding
 });

package/dist/index.mjs

@@ -33,6 +33,81 @@ var PLATFORM_PACKAGES = {
     packageDir: "bin-win32-x64"
   }
 };
+var nativeBinding = null;
+var nativeBindingAttempted = false;
+function tryLoadNativeBinding() {
+  if (nativeBindingAttempted) {
+    return nativeBinding;
+  }
+  nativeBindingAttempted = true;
+  const platform = os.platform();
+  const arch = os.arch();
+  const key = `${platform}-${arch}`;
+  const platformInfo = PLATFORM_PACKAGES[key];
+  if (!platformInfo) {
+    return null;
+  }
+  try {
+    const require2 = createRequire(import.meta.url);
+    const binding = require2(platformInfo.packageName);
+    if (typeof binding?.compare === "function") {
+      nativeBinding = binding;
+      return binding;
+    }
+  } catch {
+  }
+  try {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const packagesDir = path.resolve(currentDir, "..", "..");
+    const nodePath = path.join(
+      packagesDir,
+      platformInfo.packageDir,
+      "blazediff.node"
+    );
+    if (existsSync(nodePath)) {
+      const require2 = createRequire(import.meta.url);
+      const binding = require2(nodePath);
+      if (typeof binding?.compare === "function") {
+        nativeBinding = binding;
+        return binding;
+      }
+    }
+  } catch {
+  }
+  return null;
+}
+function convertNapiResult(result) {
+  if (result.matchResult) {
+    return { match: true };
+  }
+  if (result.reason === "layout-diff") {
+    return { match: false, reason: "layout-diff" };
+  }
+  if (result.reason === "pixel-diff") {
+    return {
+      match: false,
+      reason: "pixel-diff",
+      diffCount: result.diffCount ?? 0,
+      diffPercentage: result.diffPercentage ?? 0
+    };
+  }
+  return {
+    match: false,
+    reason: "pixel-diff",
+    diffCount: result.diffCount ?? 0,
+    diffPercentage: result.diffPercentage ?? 0
+  };
+}
+function convertToNapiOptions(options) {
+  return {
+    threshold: options?.threshold,
+    antialiasing: options?.antialiasing,
+    diffMask: options?.diffMask,
+    failOnLayout: options?.failOnLayoutDiff,
+    compression: options?.compression,
+    quality: options?.quality
+  };
+}
 function resolveBinaryPath() {
   const platform = os.platform();
   const arch = os.arch();
@@ -89,6 +164,7 @@ function buildArgs(diffOutput, options) {
   if (options.failOnLayoutDiff) args.push("--fail-on-layout");
   if (options.compression !== void 0)
     args.push(`--compression=${options.compression}`);
+  if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
   return args;
 }
 function parseJsonOutput(text) {
@@ -106,7 +182,7 @@ function detectMissingFile(error, basePath, comparePath) {
   if (error.includes(comparePath)) return comparePath;
   return basePath;
 }
-async function compare(basePath, comparePath, diffOutput, options) {
+async function execFileCompare(basePath, comparePath, diffOutput, options) {
   const binaryPath = getBinaryPathInternal();
   const args = [basePath, comparePath, ...buildArgs(diffOutput, options)];
   try {
@@ -141,10 +217,36 @@ async function compare(basePath, comparePath, diffOutput, options) {
     throw new Error(output || `blazediff exited with code ${code}`);
   }
 }
+async function compare(basePath, comparePath, diffOutput, options) {
+  const binding = tryLoadNativeBinding();
+  if (binding) {
+    try {
+      const result = binding.compare(
+        basePath,
+        comparePath,
+        diffOutput ?? null,
+        convertToNapiOptions(options)
+      );
+      return convertNapiResult(result);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const missingFile = detectMissingFile(message, basePath, comparePath);
+      if (missingFile) {
+        return { match: false, reason: "file-not-exists", file: missingFile };
+      }
+      throw err;
+    }
+  }
+  return execFileCompare(basePath, comparePath, diffOutput, options);
+}
 function getBinaryPath() {
   return getBinaryPathInternal();
 }
+function hasNativeBinding() {
+  return tryLoadNativeBinding() !== null;
+}
 export {
   compare,
-  getBinaryPath
+  getBinaryPath,
+  hasNativeBinding
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blazediff/bin",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Native Rust binaries for blazediff - the fastest image diff in the world",
   "private": false,
   "publishConfig": {
@@ -20,12 +20,12 @@
     "dist"
   ],
   "optionalDependencies": {
-    "@blazediff/bin-darwin-arm64": "3.0.0",
-    "@blazediff/bin-darwin-x64": "3.0.0",
-    "@blazediff/bin-linux-arm64": "3.0.0",
-    "@blazediff/bin-linux-x64": "3.0.0",
-    "@blazediff/bin-win32-arm64": "3.0.0",
-    "@blazediff/bin-win32-x64": "3.0.0"
+    "@blazediff/bin-darwin-arm64": "3.1.1",
+    "@blazediff/bin-darwin-x64": "3.1.1",
+    "@blazediff/bin-linux-arm64": "3.1.1",
+    "@blazediff/bin-linux-x64": "3.1.1",
+    "@blazediff/bin-win32-arm64": "3.1.1",
+    "@blazediff/bin-win32-x64": "3.1.1"
   },
   "keywords": [
     "image",
@@ -50,6 +50,7 @@
     "typescript": "5.9.2"
   },
   "scripts": {
+    "typecheck": "tsc --noEmit",
     "build": "tsup",
     "clean": "rm -rf dist"
   }

package/dist/index.d.mts

@@ -1,50 +0,0 @@
-interface BlazeDiffOptions {
-    /** Color difference threshold (0.0-1.0). Lower = more strict. Default: 0.1 */
-    threshold?: number;
-    /** Enable anti-aliasing detection to exclude AA pixels from diff count */
-    antialiasing?: boolean;
-    /** Output only differences with transparent background */
-    diffMask?: boolean;
-    /** Fail immediately if images have different dimensions */
-    failOnLayoutDiff?: boolean;
-    /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
-    compression?: number;
-}
-type BlazeDiffResult = {
-    match: true;
-} | {
-    match: false;
-    reason: "layout-diff";
-} | {
-    match: false;
-    reason: "pixel-diff";
-    diffCount: number;
-    diffPercentage: number;
-} | {
-    match: false;
-    reason: "file-not-exists";
-    file: string;
-};
-/**
- * Compare two PNG images and optionally generate a diff image.
- *
- * @example
- * ```ts
- * // With diff output
- * const result = await compare('expected.png', 'actual.png', 'diff.png');
- *
- * // Without diff output (faster, just returns comparison result)
- * const result = await compare('expected.png', 'actual.png');
- *
- * if (result.match) {
- *   console.log('Images identical');
- * } else if (result.reason === 'pixel-diff') {
- *   console.log(`${result.diffCount} pixels differ`);
- * }
- * ```
- */
-declare function compare(basePath: string, comparePath: string, diffOutput?: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
-/** Get the path to the blazediff binary for direct CLI usage. */
-declare function getBinaryPath(): string;
-
-export { type BlazeDiffOptions, type BlazeDiffResult, compare, getBinaryPath };