feat: make the API async

BREAKING CHANGE: API is now returning a promise

Author: gregberge

README.md

@@ -69,7 +69,7 @@ import { fingerprintDiff } from 'mask-fingerprint'
 
 const png = fs.readFileSync('diff.png')
 
-const fingerprint = fingerprintDiff(png, {
+const fingerprint = await fingerprintDiff(png, {
   gridSize: 16,
   dilateRadius: 1,
   padToSquare: true,
@@ -92,6 +92,8 @@ The returned value is designed to be stored in a database, indexed, and compared
 
 ### `fingerprintDiff(buffer, options?)`
 
+Returns a `Promise<string>`.
+
 #### Parameters
 
 **buffer**

__test__/index.spec.ts

@@ -5,32 +5,32 @@ import { describe, expect, it } from 'vitest'
 import { fingerprintDiff } from '../index'
 
 describe('diff fingerprint', () => {
-  it('generates a same fingerprint for similar diffs', () => {
+  it('generates a same fingerprint for similar diffs', async () => {
     const fixturesDir = path.join(__dirname, './__fixtures__')
 
-    const generateFingerprintFromFilename = (name: string) => {
+    const generateFingerprintFromFilename = async (name: string) => {
       const diffPath = path.join(fixturesDir, name)
       const buffer = fs.readFileSync(diffPath)
       console.time(name)
-      const res = fingerprintDiff(buffer)
+      const res = await fingerprintDiff(buffer)
       console.timeEnd(name)
       return res
     }
 
-    const generateFingerprintFromPath = (name: string) => {
+    const generateFingerprintFromPath = async (name: string) => {
       const diffPath = path.join(fixturesDir, name)
       console.time(`${name}-path`)
-      const res = fingerprintDiff(diffPath)
+      const res = await fingerprintDiff(diffPath)
       console.timeEnd(`${name}-path`)
       return res
     }
 
-    const fA1 = generateFingerprintFromFilename('diff-A1.png')
-    const fA1Path = generateFingerprintFromPath('diff-A1.png')
-    const fA2 = generateFingerprintFromFilename('diff-A2.png')
-    const fA3 = generateFingerprintFromFilename('diff-A3.png')
-    const fB1 = generateFingerprintFromFilename('diff-B1.png')
-    const fLong = generateFingerprintFromFilename('long-diff.png')
+    const fA1 = await generateFingerprintFromFilename('diff-A1.png')
+    const fA1Path = await generateFingerprintFromPath('diff-A1.png')
+    const fA2 = await generateFingerprintFromFilename('diff-A2.png')
+    const fA3 = await generateFingerprintFromFilename('diff-A3.png')
+    const fB1 = await generateFingerprintFromFilename('diff-B1.png')
+    const fLong = await generateFingerprintFromFilename('long-diff.png')
 
     expect(fA1).toBe('v1:g16:d1:t0.002,0.02,0.08:202566ca9533046b')
     expect(fA1).toBe(fA2)

index.d.ts

@@ -1,6 +1,6 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
-export declare function fingerprintDiff(pngInput: string | Buffer, options?: JsEqualityFingerprintOptions | undefined | null): string
+export declare function fingerprintDiff(pngInput: string | Buffer, options?: JsEqualityFingerprintOptions | undefined | null): Promise<unknown>
 
 export interface JsEqualityFingerprintOptions {
   redThreshold?: JsRedThreshold

src/lib.rs

@@ -1,6 +1,7 @@
 #![deny(clippy::all)]
 
-use napi::bindgen_prelude::{Buffer, Either};
+use napi::{Env, Task};
+use napi::bindgen_prelude::{AsyncTask, Buffer, Either};
 use napi_derive::napi;
 use std::io::{BufReader, Cursor};
 
@@ -141,33 +142,54 @@ fn clamp_u32_to_u8(v: u32) -> u8 {
 
 /* ---------------------------------- NAPI ---------------------------------- */
 
+enum InputBytes {
+  Path(String),
+  Bytes(Vec<u8>),
+}
+
+pub struct FingerprintDiffTask {
+  input: InputBytes,
+  options: Option<JsEqualityFingerprintOptions>,
+}
+
+impl Task for FingerprintDiffTask {
+  type Output = String;
+  type JsValue = String;
+
+  fn compute(&mut self) -> napi::Result<Self::Output> {
+    let opts = build_options(self.options.take())?;
+
+    match &self.input {
+      InputBytes::Path(path) => {
+        let png_bytes = std::fs::read(path).map_err(|e| {
+          napi::Error::from_reason(format!("Failed to read PNG file '{path}': {e}"))
+        })?;
+        let (rgba, width, height) = decode_png_to_rgba(&png_bytes)?;
+        Ok(fingerprint_rgba_for_equality(&rgba, width, height, &opts))
+      }
+      InputBytes::Bytes(png_bytes) => {
+        let (rgba, width, height) = decode_png_to_rgba(png_bytes)?;
+        Ok(fingerprint_rgba_for_equality(&rgba, width, height, &opts))
+      }
+    }
+  }
+
+  fn resolve(&mut self, _env: Env, output: Self::Output) -> napi::Result<Self::JsValue> {
+    Ok(output)
+  }
+}
+
 #[napi]
 pub fn fingerprint_diff(
   png_input: Either<String, Buffer>,
   options: Option<JsEqualityFingerprintOptions>,
-) -> napi::Result<String> {
-  enum InputBytes {
-    File(Vec<u8>),
-    Buffer(Buffer),
-  }
-
+) -> napi::Result<AsyncTask<FingerprintDiffTask>> {
   let input = match png_input {
-    Either::A(path) => {
-      let bytes = std::fs::read(&path)
-        .map_err(|e| napi::Error::from_reason(format!("Failed to read PNG file '{path}': {e}")))?;
-      InputBytes::File(bytes)
-    }
-    Either::B(buffer) => InputBytes::Buffer(buffer),
-  };
-
-  let png_bytes: &[u8] = match &input {
-    InputBytes::File(bytes) => bytes.as_slice(),
-    InputBytes::Buffer(buffer) => buffer.as_ref(),
+    Either::A(path) => InputBytes::Path(path),
+    Either::B(buffer) => InputBytes::Bytes(buffer.to_vec()),
   };
 
-  let (rgba, width, height) = decode_png_to_rgba(png_bytes)?;
-  let opts = build_options(options)?;
-  Ok(fingerprint_rgba_for_equality(&rgba, width, height, &opts))
+  Ok(AsyncTask::new(FingerprintDiffTask { input, options }))
 }
 
 /* -------------------------------- PNG decode -------------------------------- */