@blazediff/core-native 5.1.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
  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).
12
12
 
13
13
  **Features:**
14
- - **PNG, JPEG & QOI support** - auto-detected by file extension
14
+ - **PNG, JPEG & QOI support** - auto-detected by file extension or encoded bytes
15
15
  - SIMD-accelerated (NEON on ARM, SSE4.1 on x86)
16
16
  - Block-based two-pass optimization
17
17
  - YIQ perceptual color difference
@@ -49,9 +49,9 @@ Pre-built binaries are included via platform-specific packages:
49
49
 
50
50
  ## API
51
51
 
52
- ### compare(basePath, comparePath, diffOutput, options?)
52
+ ### compare(base, comparison, diffOutput, options?)
53
53
 
54
- Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detected from file extension.
54
+ Compare two images from file paths or encoded `Uint8Array`/`Buffer` inputs and optionally generate a diff image. Both inputs must use the same input type. Format is auto-detected from the file extension or encoded bytes.
55
55
 
56
56
  <table>
57
57
  <tr>
@@ -60,14 +60,14 @@ Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detec
60
60
  <th width="500">Description</th>
61
61
  </tr>
62
62
  <tr>
63
- <td><code>basePath</code></td>
64
- <td>string</td>
65
- <td>Path to the base/expected image</td>
63
+ <td><code>base</code></td>
64
+ <td>string | Uint8Array</td>
65
+ <td>Base/expected image path or encoded bytes</td>
66
66
  </tr>
67
67
  <tr>
68
- <td><code>comparePath</code></td>
69
- <td>string</td>
70
- <td>Path to the comparison/actual image</td>
68
+ <td><code>comparison</code></td>
69
+ <td>string | Uint8Array</td>
70
+ <td>Comparison/actual image path or encoded bytes</td>
71
71
  </tr>
72
72
  <tr>
73
73
  <td><code>diffOutput</code></td>
@@ -83,6 +83,22 @@ Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detec
83
83
 
84
84
  <strong>Returns:</strong> `Promise<BlazeDiffResult>`
85
85
 
86
+ #### Encoded Buffer Inputs
87
+
88
+ ```typescript
89
+ import { readFile } from "node:fs/promises";
90
+ import { compare } from "@blazediff/core-native";
91
+
92
+ const [expected, actual] = await Promise.all([
93
+ readFile("expected.png"),
94
+ readFile("actual.png"),
95
+ ]);
96
+
97
+ const result = await compare(expected, actual, "diff.png");
98
+ ```
99
+
100
+ The native binding borrows the existing `Buffer` or `Uint8Array` backing memory for the synchronous call. The encoded bytes are not copied into Rust, so the same JavaScript buffers can be reused across comparisons. Decoding still allocates native RGBA pixel buffers.
101
+
86
102
  <table>
87
103
  <tr>
88
104
  <th width="500">Option</th>
@@ -108,17 +124,23 @@ Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detec
108
124
  <td>false</td>
109
125
  <td>Output only differences with transparent background</td>
110
126
  </tr>
127
+ <tr>
128
+ <td><code>diffColorAlt</code></td>
129
+ <td>[number, number, number]</td>
130
+ <td>diff color</td>
131
+ <td>Alternative RGB color for darkening differences</td>
132
+ </tr>
111
133
  <tr>
112
134
  <td><code>interpret</code></td>
113
135
  <td>boolean</td>
114
136
  <td>false</td>
115
- <td>Run structured interpretation after diff - adds <code>interpretation</code> to the result with detected change regions, classification, and a human-readable summary</td>
137
+ <td>Generate the diff image and structured interpretation in one pass, adding <code>interpretation</code> to the result</td>
116
138
  </tr>
117
139
  </table>
118
140
 
119
- ### interpret(image1Path, image2Path, options?)
141
+ ### interpret(image1, image2, options?)
120
142
 
121
- Convenience wrapper that calls `compare` with `interpret: true` and returns the `InterpretResult` directly. No diff image output - purely analytical.
143
+ Convenience wrapper that calls `compare` with `interpret: true` and returns the `InterpretResult` directly. Accepts matching path or encoded byte inputs. No diff image output - purely analytical.
122
144
 
123
145
  <table>
124
146
  <tr>
@@ -127,14 +149,14 @@ Convenience wrapper that calls `compare` with `interpret: true` and returns the
127
149
  <th width="500">Description</th>
128
150
  </tr>
129
151
  <tr>
130
- <td><code>image1Path</code></td>
131
- <td>string</td>
132
- <td>Path to the first image</td>
152
+ <td><code>image1</code></td>
153
+ <td>string | Uint8Array</td>
154
+ <td>First image path or encoded bytes</td>
133
155
  </tr>
134
156
  <tr>
135
- <td><code>image2Path</code></td>
136
- <td>string</td>
137
- <td>Path to the second image</td>
157
+ <td><code>image2</code></td>
158
+ <td>string | Uint8Array</td>
159
+ <td>Second image path or encoded bytes</td>
138
160
  </tr>
139
161
  <tr>
140
162
  <td><code>options</code></td>
@@ -272,9 +294,11 @@ Options:
272
294
  -t, --threshold <THRESHOLD> Color difference threshold (0.0-1.0) [default: 0.1]
273
295
  -a, --antialiasing Enable anti-aliasing detection
274
296
  --diff-mask Output only differences (transparent background)
297
+ --diff-color-alt <R,G,B> Alternative RGB color for darkening differences
275
298
  -c, --compression <LEVEL> PNG compression level (0-9, 0=fastest, 9=smallest) [default: 0]
276
299
  -q, --quality <QUALITY> JPEG quality (1-100) [default: 90]
277
300
  --output-format <FORMAT> Output format (json or text) [default: json]
301
+ --interpret Generate diff output and structured interpretation
278
302
  -h, --help Print help
279
303
  -V, --version Print version
280
304
  ```
package/dist/index.d.ts CHANGED
@@ -5,6 +5,8 @@ interface BlazeDiffOptions {
5
5
  antialiasing?: boolean;
6
6
  /** Output only differences with transparent background */
7
7
  diffMask?: boolean;
8
+ /** Alternative RGB color for darkening differences. Default: diff color */
9
+ diffColorAlt?: [number, number, number];
8
10
  /** PNG compression level (0-9, 0=fastest/largest, 9=slowest/smallest) */
9
11
  compression?: number;
10
12
  /** JPEG quality (1-100). Default: 90 */
@@ -12,6 +14,8 @@ interface BlazeDiffOptions {
12
14
  /** Run structured interpretation after raw pixel diff */
13
15
  interpret?: boolean;
14
16
  }
17
+ /** File path or encoded PNG, JPEG, or QOI bytes. */
18
+ type BlazeDiffInput = string | Uint8Array;
15
19
  type BlazeDiffResult = {
16
20
  match: true;
17
21
  interpretation?: InterpretResult;
@@ -88,19 +92,22 @@ interface InterpretResult {
88
92
  height: number;
89
93
  }
90
94
  /**
91
- * Compare two images (PNG or JPEG) and optionally generate a diff image.
95
+ * Compare two encoded images (PNG, JPEG, or QOI) and optionally generate a diff image.
96
+ *
97
+ * Inputs must both be file paths or both be encoded byte arrays. Node.js Buffer
98
+ * values are Uint8Array instances and can be passed directly.
92
99
  *
93
100
  * Uses native N-API bindings when available for ~10-100x better performance
94
- * on small images (no process spawn overhead). Falls back to execFile if
95
- * native bindings are unavailable.
101
+ * on small images (no process spawn overhead). Path inputs fall back to
102
+ * execFile if native bindings are unavailable.
96
103
  *
97
104
  * @example
98
105
  * ```ts
99
- * // With diff output
106
+ * // With file paths and diff output
100
107
  * const result = await compare('expected.png', 'actual.png', 'diff.png');
101
108
  *
102
- * // Without diff output (faster, just returns comparison result)
103
- * const result = await compare('expected.png', 'actual.png');
109
+ * // With encoded image buffers
110
+ * const result = await compare(expectedPngBuffer, actualPngBuffer);
104
111
  *
105
112
  * if (result.match) {
106
113
  * console.log('Images identical');
@@ -109,7 +116,7 @@ interface InterpretResult {
109
116
  * }
110
117
  * ```
111
118
  */
112
- declare function compare(basePath: string, comparePath: string, diffOutput?: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
119
+ declare function compare(base: BlazeDiffInput, comparison: BlazeDiffInput, diffOutput?: string, options?: BlazeDiffOptions): Promise<BlazeDiffResult>;
113
120
  /** Get the path to the blazediff binary for direct CLI usage. */
114
121
  declare function getBinaryPath(): string;
115
122
  /**
@@ -120,8 +127,9 @@ declare function hasNativeBinding(): boolean;
120
127
  /**
121
128
  * Interpret the diff between two images, returning structured analysis results.
122
129
  *
123
- * Uses native N-API bindings when available for better performance.
124
- * Falls back to execFile if native bindings are unavailable.
130
+ * Inputs must both be file paths or both be encoded byte arrays. Uses native
131
+ * N-API bindings when available for better performance. Path inputs fall back
132
+ * to execFile if native bindings are unavailable.
125
133
  *
126
134
  * @example
127
135
  * ```ts
@@ -132,6 +140,6 @@ declare function hasNativeBinding(): boolean;
132
140
  * }
133
141
  * ```
134
142
  */
135
- declare function interpret(image1Path: string, image2Path: string, options?: Pick<BlazeDiffOptions, "threshold" | "antialiasing">): Promise<InterpretResult>;
143
+ declare function interpret(image1: BlazeDiffInput, image2: BlazeDiffInput, options?: Pick<BlazeDiffOptions, "threshold" | "antialiasing">): Promise<InterpretResult>;
136
144
 
137
- export { type BlazeDiffOptions, type BlazeDiffResult, type BoundingBox, type ChangeRegion, type ClassificationSignals, type ColorDeltaStats, type GradientStats, type InterpretResult, type ShapeStats, compare, getBinaryPath, hasNativeBinding, interpret };
145
+ export { type BlazeDiffInput, type BlazeDiffOptions, type BlazeDiffResult, type BoundingBox, type ChangeRegion, type ClassificationSignals, type ColorDeltaStats, type GradientStats, type InterpretResult, type ShapeStats, compare, getBinaryPath, hasNativeBinding, interpret };
package/dist/index.js CHANGED
@@ -50,6 +50,17 @@ var import_node_path = __toESM(require("path"));
50
50
  var import_node_url = require("url");
51
51
  var import_node_util = require("util");
52
52
  var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
53
+ function validateRgb(color) {
54
+ if (!color) return void 0;
55
+ if (color.length !== 3 || color.some(
56
+ (channel) => !Number.isInteger(channel) || channel < 0 || channel > 255
57
+ )) {
58
+ throw new RangeError(
59
+ "diffColorAlt must contain three integer RGB channels"
60
+ );
61
+ }
62
+ return color;
63
+ }
53
64
  var PLATFORM_PACKAGES = {
54
65
  "darwin-arm64": {
55
66
  packageName: "@blazediff/core-native-darwin-arm64",
@@ -140,6 +151,7 @@ function convertToNapiOptions(options) {
140
151
  threshold: options?.threshold,
141
152
  antialiasing: options?.antialiasing,
142
153
  diffMask: options?.diffMask,
154
+ diffColorAlt: validateRgb(options?.diffColorAlt),
143
155
  compression: options?.compression,
144
156
  quality: options?.quality,
145
157
  interpret: options?.interpret
@@ -199,13 +211,12 @@ function buildArgs(diffOutput, options) {
199
211
  if (options.threshold !== void 0)
200
212
  args.push(`--threshold=${options.threshold}`);
201
213
  if (options.antialiasing) args.push("--antialiasing");
202
- if (!useInterpret) {
203
- if (options.diffMask) args.push("--diff-mask");
204
- if (options.compression !== void 0)
205
- args.push(`--compression=${options.compression}`);
206
- if (options.quality !== void 0)
207
- args.push(`--quality=${options.quality}`);
208
- }
214
+ if (options.diffMask) args.push("--diff-mask");
215
+ const diffColorAlt = validateRgb(options.diffColorAlt);
216
+ if (diffColorAlt) args.push(`--diff-color-alt=${diffColorAlt.join(",")}`);
217
+ if (options.compression !== void 0)
218
+ args.push(`--compression=${options.compression}`);
219
+ if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
209
220
  return args;
210
221
  }
211
222
  function parseJsonOutput(text) {
@@ -290,27 +301,48 @@ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath)
290
301
  );
291
302
  }
292
303
  }
293
- async function compare(basePath, comparePath, diffOutput, options) {
304
+ async function compare(base, comparison, diffOutput, options) {
305
+ const baseIsPath = typeof base === "string";
306
+ const comparisonIsPath = typeof comparison === "string";
307
+ if (baseIsPath !== comparisonIsPath) {
308
+ throw new TypeError(
309
+ "Image inputs must both be file paths or both be encoded byte arrays"
310
+ );
311
+ }
294
312
  const binding = tryLoadNativeBinding();
295
313
  if (binding) {
296
314
  try {
297
- const result = binding.compare(
298
- basePath,
299
- comparePath,
315
+ const result = baseIsPath && comparisonIsPath ? binding.compare(
316
+ base,
317
+ comparison,
318
+ diffOutput ?? null,
319
+ convertToNapiOptions(options)
320
+ ) : binding.compareBuffers(
321
+ base,
322
+ comparison,
300
323
  diffOutput ?? null,
301
324
  convertToNapiOptions(options)
302
325
  );
303
326
  return convertNapiResult(result);
304
327
  } catch (err) {
305
- const message = err instanceof Error ? err.message : String(err);
306
- const missingFile = detectMissingFile(message, basePath, comparePath);
307
- if (missingFile) {
308
- return { match: false, reason: "file-not-exists", file: missingFile };
328
+ if (baseIsPath && comparisonIsPath) {
329
+ const message = err instanceof Error ? err.message : String(err);
330
+ const missingFile = detectMissingFile(message, base, comparison);
331
+ if (missingFile) {
332
+ return {
333
+ match: false,
334
+ reason: "file-not-exists",
335
+ file: missingFile
336
+ };
337
+ }
309
338
  }
310
339
  throw err;
311
340
  }
312
341
  }
313
- return execFileCompare(basePath, comparePath, diffOutput, options);
342
+ if (!baseIsPath || !comparisonIsPath) {
343
+ throw new Error("Encoded image inputs require the native N-API binding");
344
+ }
345
+ return execFileCompare(base, comparison, diffOutput, options);
314
346
  }
315
347
  function getBinaryPath() {
316
348
  return getBinaryPathInternal();
@@ -318,15 +350,17 @@ function getBinaryPath() {
318
350
  function hasNativeBinding() {
319
351
  return tryLoadNativeBinding() !== null;
320
352
  }
321
- async function interpret(image1Path, image2Path, options) {
353
+ async function interpret(image1, image2, options) {
354
+ const image1IsPath = typeof image1 === "string";
355
+ const image2IsPath = typeof image2 === "string";
322
356
  const binding = tryLoadNativeBinding();
323
- if (binding) {
324
- return binding.interpretImages(image1Path, image2Path, {
357
+ if (binding && image1IsPath && image2IsPath) {
358
+ return binding.interpretImages(image1, image2, {
325
359
  threshold: options?.threshold,
326
360
  antialiasing: options?.antialiasing
327
361
  });
328
362
  }
329
- const result = await compare(image1Path, image2Path, void 0, {
363
+ const result = await compare(image1, image2, void 0, {
330
364
  ...options,
331
365
  interpret: true
332
366
  });
package/dist/index.mjs CHANGED
@@ -7,6 +7,17 @@ import path from "path";
7
7
  import { fileURLToPath } from "url";
8
8
  import { promisify } from "util";
9
9
  var execFileAsync = promisify(execFile);
10
+ function validateRgb(color) {
11
+ if (!color) return void 0;
12
+ if (color.length !== 3 || color.some(
13
+ (channel) => !Number.isInteger(channel) || channel < 0 || channel > 255
14
+ )) {
15
+ throw new RangeError(
16
+ "diffColorAlt must contain three integer RGB channels"
17
+ );
18
+ }
19
+ return color;
20
+ }
10
21
  var PLATFORM_PACKAGES = {
11
22
  "darwin-arm64": {
12
23
  packageName: "@blazediff/core-native-darwin-arm64",
@@ -97,6 +108,7 @@ function convertToNapiOptions(options) {
97
108
  threshold: options?.threshold,
98
109
  antialiasing: options?.antialiasing,
99
110
  diffMask: options?.diffMask,
111
+ diffColorAlt: validateRgb(options?.diffColorAlt),
100
112
  compression: options?.compression,
101
113
  quality: options?.quality,
102
114
  interpret: options?.interpret
@@ -156,13 +168,12 @@ function buildArgs(diffOutput, options) {
156
168
  if (options.threshold !== void 0)
157
169
  args.push(`--threshold=${options.threshold}`);
158
170
  if (options.antialiasing) args.push("--antialiasing");
159
- if (!useInterpret) {
160
- if (options.diffMask) args.push("--diff-mask");
161
- if (options.compression !== void 0)
162
- args.push(`--compression=${options.compression}`);
163
- if (options.quality !== void 0)
164
- args.push(`--quality=${options.quality}`);
165
- }
171
+ if (options.diffMask) args.push("--diff-mask");
172
+ const diffColorAlt = validateRgb(options.diffColorAlt);
173
+ if (diffColorAlt) args.push(`--diff-color-alt=${diffColorAlt.join(",")}`);
174
+ if (options.compression !== void 0)
175
+ args.push(`--compression=${options.compression}`);
176
+ if (options.quality !== void 0) args.push(`--quality=${options.quality}`);
166
177
  return args;
167
178
  }
168
179
  function parseJsonOutput(text) {
@@ -247,27 +258,48 @@ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath)
247
258
  );
248
259
  }
249
260
  }
250
- async function compare(basePath, comparePath, diffOutput, options) {
261
+ async function compare(base, comparison, diffOutput, options) {
262
+ const baseIsPath = typeof base === "string";
263
+ const comparisonIsPath = typeof comparison === "string";
264
+ if (baseIsPath !== comparisonIsPath) {
265
+ throw new TypeError(
266
+ "Image inputs must both be file paths or both be encoded byte arrays"
267
+ );
268
+ }
251
269
  const binding = tryLoadNativeBinding();
252
270
  if (binding) {
253
271
  try {
254
- const result = binding.compare(
255
- basePath,
256
- comparePath,
272
+ const result = baseIsPath && comparisonIsPath ? binding.compare(
273
+ base,
274
+ comparison,
275
+ diffOutput ?? null,
276
+ convertToNapiOptions(options)
277
+ ) : binding.compareBuffers(
278
+ base,
279
+ comparison,
257
280
  diffOutput ?? null,
258
281
  convertToNapiOptions(options)
259
282
  );
260
283
  return convertNapiResult(result);
261
284
  } catch (err) {
262
- const message = err instanceof Error ? err.message : String(err);
263
- const missingFile = detectMissingFile(message, basePath, comparePath);
264
- if (missingFile) {
265
- return { match: false, reason: "file-not-exists", file: missingFile };
285
+ if (baseIsPath && comparisonIsPath) {
286
+ const message = err instanceof Error ? err.message : String(err);
287
+ const missingFile = detectMissingFile(message, base, comparison);
288
+ if (missingFile) {
289
+ return {
290
+ match: false,
291
+ reason: "file-not-exists",
292
+ file: missingFile
293
+ };
294
+ }
266
295
  }
267
296
  throw err;
268
297
  }
269
298
  }
270
- return execFileCompare(basePath, comparePath, diffOutput, options);
299
+ if (!baseIsPath || !comparisonIsPath) {
300
+ throw new Error("Encoded image inputs require the native N-API binding");
301
+ }
302
+ return execFileCompare(base, comparison, diffOutput, options);
271
303
  }
272
304
  function getBinaryPath() {
273
305
  return getBinaryPathInternal();
@@ -275,15 +307,17 @@ function getBinaryPath() {
275
307
  function hasNativeBinding() {
276
308
  return tryLoadNativeBinding() !== null;
277
309
  }
278
- async function interpret(image1Path, image2Path, options) {
310
+ async function interpret(image1, image2, options) {
311
+ const image1IsPath = typeof image1 === "string";
312
+ const image2IsPath = typeof image2 === "string";
279
313
  const binding = tryLoadNativeBinding();
280
- if (binding) {
281
- return binding.interpretImages(image1Path, image2Path, {
314
+ if (binding && image1IsPath && image2IsPath) {
315
+ return binding.interpretImages(image1, image2, {
282
316
  threshold: options?.threshold,
283
317
  antialiasing: options?.antialiasing
284
318
  });
285
319
  }
286
- const result = await compare(image1Path, image2Path, void 0, {
320
+ const result = await compare(image1, image2, void 0, {
287
321
  ...options,
288
322
  interpret: true
289
323
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazediff/core-native",
3
- "version": "5.1.0",
3
+ "version": "5.3.0",
4
4
  "description": "Native Rust binaries for blazediff - the fastest image diff in the world",
5
5
  "private": false,
6
6
  "publishConfig": {
@@ -20,12 +20,12 @@
20
20
  "dist"
21
21
  ],
22
22
  "optionalDependencies": {
23
- "@blazediff/core-native-darwin-arm64": "5.1.0",
24
- "@blazediff/core-native-darwin-x64": "5.1.0",
25
- "@blazediff/core-native-linux-arm64": "5.1.0",
26
- "@blazediff/core-native-linux-x64": "5.1.0",
27
- "@blazediff/core-native-win32-arm64": "5.1.0",
28
- "@blazediff/core-native-win32-x64": "5.1.0"
23
+ "@blazediff/core-native-darwin-arm64": "5.3.0",
24
+ "@blazediff/core-native-darwin-x64": "5.3.0",
25
+ "@blazediff/core-native-linux-arm64": "5.3.0",
26
+ "@blazediff/core-native-linux-x64": "5.3.0",
27
+ "@blazediff/core-native-win32-arm64": "5.3.0",
28
+ "@blazediff/core-native-win32-x64": "5.3.0"
29
29
  },
30
30
  "keywords": [
31
31
  "image",