@blazediff/core-native 5.2.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>
@@ -122,9 +138,9 @@ Compare two images (PNG or JPEG) and generate a diff image. Format is auto-detec
122
138
  </tr>
123
139
  </table>
124
140
 
125
- ### interpret(image1Path, image2Path, options?)
141
+ ### interpret(image1, image2, options?)
126
142
 
127
- 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.
128
144
 
129
145
  <table>
130
146
  <tr>
@@ -133,14 +149,14 @@ Convenience wrapper that calls `compare` with `interpret: true` and returns the
133
149
  <th width="500">Description</th>
134
150
  </tr>
135
151
  <tr>
136
- <td><code>image1Path</code></td>
137
- <td>string</td>
138
- <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>
139
155
  </tr>
140
156
  <tr>
141
- <td><code>image2Path</code></td>
142
- <td>string</td>
143
- <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>
144
160
  </tr>
145
161
  <tr>
146
162
  <td><code>options</code></td>
package/dist/index.d.ts CHANGED
@@ -14,6 +14,8 @@ interface BlazeDiffOptions {
14
14
  /** Run structured interpretation after raw pixel diff */
15
15
  interpret?: boolean;
16
16
  }
17
+ /** File path or encoded PNG, JPEG, or QOI bytes. */
18
+ type BlazeDiffInput = string | Uint8Array;
17
19
  type BlazeDiffResult = {
18
20
  match: true;
19
21
  interpretation?: InterpretResult;
@@ -90,19 +92,22 @@ interface InterpretResult {
90
92
  height: number;
91
93
  }
92
94
  /**
93
- * 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.
94
99
  *
95
100
  * Uses native N-API bindings when available for ~10-100x better performance
96
- * on small images (no process spawn overhead). Falls back to execFile if
97
- * native bindings are unavailable.
101
+ * on small images (no process spawn overhead). Path inputs fall back to
102
+ * execFile if native bindings are unavailable.
98
103
  *
99
104
  * @example
100
105
  * ```ts
101
- * // With diff output
106
+ * // With file paths and diff output
102
107
  * const result = await compare('expected.png', 'actual.png', 'diff.png');
103
108
  *
104
- * // Without diff output (faster, just returns comparison result)
105
- * const result = await compare('expected.png', 'actual.png');
109
+ * // With encoded image buffers
110
+ * const result = await compare(expectedPngBuffer, actualPngBuffer);
106
111
  *
107
112
  * if (result.match) {
108
113
  * console.log('Images identical');
@@ -111,7 +116,7 @@ interface InterpretResult {
111
116
  * }
112
117
  * ```
113
118
  */
114
- 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>;
115
120
  /** Get the path to the blazediff binary for direct CLI usage. */
116
121
  declare function getBinaryPath(): string;
117
122
  /**
@@ -122,8 +127,9 @@ declare function hasNativeBinding(): boolean;
122
127
  /**
123
128
  * Interpret the diff between two images, returning structured analysis results.
124
129
  *
125
- * Uses native N-API bindings when available for better performance.
126
- * 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.
127
133
  *
128
134
  * @example
129
135
  * ```ts
@@ -134,6 +140,6 @@ declare function hasNativeBinding(): boolean;
134
140
  * }
135
141
  * ```
136
142
  */
137
- 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>;
138
144
 
139
- 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
@@ -301,27 +301,48 @@ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath)
301
301
  );
302
302
  }
303
303
  }
304
- 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
+ }
305
312
  const binding = tryLoadNativeBinding();
306
313
  if (binding) {
307
314
  try {
308
- const result = binding.compare(
309
- basePath,
310
- 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,
311
323
  diffOutput ?? null,
312
324
  convertToNapiOptions(options)
313
325
  );
314
326
  return convertNapiResult(result);
315
327
  } catch (err) {
316
- const message = err instanceof Error ? err.message : String(err);
317
- const missingFile = detectMissingFile(message, basePath, comparePath);
318
- if (missingFile) {
319
- 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
+ }
320
338
  }
321
339
  throw err;
322
340
  }
323
341
  }
324
- 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);
325
346
  }
326
347
  function getBinaryPath() {
327
348
  return getBinaryPathInternal();
@@ -329,15 +350,17 @@ function getBinaryPath() {
329
350
  function hasNativeBinding() {
330
351
  return tryLoadNativeBinding() !== null;
331
352
  }
332
- 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";
333
356
  const binding = tryLoadNativeBinding();
334
- if (binding) {
335
- return binding.interpretImages(image1Path, image2Path, {
357
+ if (binding && image1IsPath && image2IsPath) {
358
+ return binding.interpretImages(image1, image2, {
336
359
  threshold: options?.threshold,
337
360
  antialiasing: options?.antialiasing
338
361
  });
339
362
  }
340
- const result = await compare(image1Path, image2Path, void 0, {
363
+ const result = await compare(image1, image2, void 0, {
341
364
  ...options,
342
365
  interpret: true
343
366
  });
package/dist/index.mjs CHANGED
@@ -258,27 +258,48 @@ async function execFileInterpretCompare(binaryPath, args, basePath, comparePath)
258
258
  );
259
259
  }
260
260
  }
261
- 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
+ }
262
269
  const binding = tryLoadNativeBinding();
263
270
  if (binding) {
264
271
  try {
265
- const result = binding.compare(
266
- basePath,
267
- 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,
268
280
  diffOutput ?? null,
269
281
  convertToNapiOptions(options)
270
282
  );
271
283
  return convertNapiResult(result);
272
284
  } catch (err) {
273
- const message = err instanceof Error ? err.message : String(err);
274
- const missingFile = detectMissingFile(message, basePath, comparePath);
275
- if (missingFile) {
276
- 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
+ }
277
295
  }
278
296
  throw err;
279
297
  }
280
298
  }
281
- 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);
282
303
  }
283
304
  function getBinaryPath() {
284
305
  return getBinaryPathInternal();
@@ -286,15 +307,17 @@ function getBinaryPath() {
286
307
  function hasNativeBinding() {
287
308
  return tryLoadNativeBinding() !== null;
288
309
  }
289
- 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";
290
313
  const binding = tryLoadNativeBinding();
291
- if (binding) {
292
- return binding.interpretImages(image1Path, image2Path, {
314
+ if (binding && image1IsPath && image2IsPath) {
315
+ return binding.interpretImages(image1, image2, {
293
316
  threshold: options?.threshold,
294
317
  antialiasing: options?.antialiasing
295
318
  });
296
319
  }
297
- const result = await compare(image1Path, image2Path, void 0, {
320
+ const result = await compare(image1, image2, void 0, {
298
321
  ...options,
299
322
  interpret: true
300
323
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blazediff/core-native",
3
- "version": "5.2.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.2.0",
24
- "@blazediff/core-native-darwin-x64": "5.2.0",
25
- "@blazediff/core-native-linux-arm64": "5.2.0",
26
- "@blazediff/core-native-linux-x64": "5.2.0",
27
- "@blazediff/core-native-win32-arm64": "5.2.0",
28
- "@blazediff/core-native-win32-x64": "5.2.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",