pdqhash-node 1.0.0 → 1.1.0

package/README.md

@@ -8,16 +8,67 @@ A minimal Node.js wrapper around the Cargo crate [pdqhash](https://github.com/da
 ## Install
 ```
 yarn add pdqhash-node
-yarn build
 ```
 
 ## Usage
 
 ```js
 import { readFileSync } from 'fs';
-import { pdqhash } from 'pdqhash-node';
+import { pdqhash, pdqhashBuffer } from 'pdqhash-node';
 
 const buf = readFileSync('image.jpg');
-const hashHex = pdqhash(buf); // string | null
+var hashHex = pdqhash(buf); // string | null
+// or
+var hashBuf = pdqhashBuffer(buf); // Buffer | null
 console.log(hashHex);
 ```
+
+## API
+
+- `pdqhash(input: Buffer): string | null`
+	- Hex string PDQ hash. Returns `null` if hashing fails.
+- `pdqhashBuffer(input: Buffer): Buffer | null`
+	- Raw PDQ hash bytes as a `Buffer`. Returns `null` if hashing fails.
+- `pdqhashWithQuality(input: Buffer): { hash: string; quality: number } | null`
+	- Hex string PDQ hash plus the quality score. Returns `null` if hashing fails.
+- `hammingDistance(a: Buffer, b: Buffer): number`
+	- Computes Hamming distance between two PDQ hash Buffers.
+
+### Examples
+
+Compute hash in hex and Buffer:
+
+```js
+import { readFileSync } from 'fs';
+import { pdqhash, pdqhashBuffer } from 'pdqhash-node';
+
+const buf = readFileSync('image.jpg');
+console.log(pdqhash(buf)); // hex string
+console.log(pdqhashBuffer(buf)?.toString('hex')); // same hash from Buffer
+```
+
+Get hash with quality:
+
+```js
+import { readFileSync } from 'fs';
+import { pdqhashWithQuality } from 'pdqhash-node';
+
+const buf = readFileSync('image.jpg');
+const result = pdqhashWithQuality(buf);
+if (result) {
+	console.log(result.hash, result.quality);
+}
+```
+
+Compute Hamming distance:
+
+```js
+import { readFileSync } from 'fs';
+import { pdqhashBuffer, hammingDistance } from 'pdqhash-node';
+
+const a = pdqhashBuffer(readFileSync('image1.jpg'));
+const b = pdqhashBuffer(readFileSync('image2.jpg'));
+if (a && b) {
+	console.log(hammingDistance(a, b));
+}
+```

package/index.d.ts

@@ -11,23 +11,57 @@
  *
  * @throws {TypeError}
  * Thrown if `input` is not a Buffer.
+ */
+declare function pdqhash(input: Buffer): string | null;
+
+/**
+ * Generate a PDQ perceptual hash from a binary buffer.
  *
- * @example
- * ```ts
- * import { pdqhash } from "pdqhash-node";
+ * This function accepts a {@link Buffer} and returns the raw PDQ
+ * hash as a {@link Buffer}.
  *
- * const buf = fs.readFileSync("image.jpg");
- * const hash = pdqhash(buf);
+ * @param input - A Buffer containing the binary data to hash.
+ * @returns A Buffer containing the PDQ hash, or `null` if a hash could not be generated.
  *
- * if (hash) {
- *   console.log(hash);
- * }
- * ```
+ * @throws {TypeError}
+ * Thrown if `input` is not a Buffer.
  */
-declare function pdqhash(input: Buffer): string | null;
+declare function pdqhashBuffer(input: Buffer): Buffer | null;
+
+/**
+ * Generate a PDQ hash with quality metadata from a binary buffer.
+ *
+ * Returns an object containing the PDQ hash in hex string form and
+ * the computed quality score.
+ *
+ * @param input - A Buffer containing the binary data to hash.
+ * @returns An object `{ hash: string, quality: number }`, or `null` if a hash could not be generated.
+ *
+ * @throws {TypeError}
+ * Thrown if `input` is not a Buffer.
+ */
+declare function pdqhashWithQuality(input: Buffer): { hash: string; quality: number } | null;
+
+/**
+ * Compute Hamming distance between two PDQ hashes.
+ *
+ * Accepts two PDQ hash Buffers and returns their Hamming distance
+ * as a number.
+ *
+ * @param a - First PDQ hash as a Buffer.
+ * @param b - Second PDQ hash as a Buffer.
+ * @returns The Hamming distance between `a` and `b`.
+ *
+ * @throws {TypeError}
+ * Thrown if either argument is not a Buffer.
+ */
+declare function hammingDistance(a: Buffer, b: Buffer): number;
 
 declare const _default: {
-  pdqhash: typeof pdqhash;
+	pdqhash: typeof pdqhash;
+	pdqhashBuffer: typeof pdqhashBuffer;
+	pdqhashWithQuality: typeof pdqhashWithQuality;
+	hammingDistance: typeof hammingDistance;
 };
 
 export = _default;

package/index.js

@@ -33,6 +33,111 @@ function pdqhash(input) {
   return Buffer.from(res.hash).toString('hex');
 }
 
+/**
+ * Generate a PDQ perceptual hash from a binary buffer.
+ *
+ * This function accepts a {@link Buffer} and returns the raw PDQ
+ * hash as a {@link Buffer}.
+ *
+ * @param input - A Buffer containing the binary data to hash.
+ * @returns A Buffer containing the PDQ hash, or `null` if a hash could not be generated.
+ *
+ * @throws {TypeError}
+ * Thrown if `input` is not a Buffer.
+ *
+ * @example
+ * ```ts
+ * import { pdqhashBuffer } from "pdqhash-node";
+ *
+ * const buf = fs.readFileSync("image.jpg");
+ * const hashBuf = pdqhashBuffer(buf);
+ *
+ * if (hashBuf) {
+ *   console.log(hashBuf.toString('hex'));
+ * }
+ * ```
+ */
+function pdqhashBuffer(input) {
+  if (!Buffer.isBuffer(input)) {
+    throw new TypeError('pdqhashBuffer(input): input must be a Buffer');
+  }
+  const res = addon.generatePdqFromBuffer(input);
+  if (!res) return null;
+  return Buffer.from(res.hash);
+}
+
+/**
+ * Generate a PDQ hash with quality metadata from a binary buffer.
+ *
+ * Returns an object containing the PDQ hash in hex string form and
+ * the computed quality score.
+ *
+ * @param input - A Buffer containing the binary data to hash.
+ * @returns An object `{ hash: string, quality: number }`, or `null` if a hash could not be generated.
+ *
+ * @throws {TypeError}
+ * Thrown if `input` is not a Buffer.
+ *
+ * @example
+ * ```ts
+ * import { pdqhashWithQuality } from "pdqhash-node";
+ *
+ * const buf = fs.readFileSync("image.jpg");
+ * const result = pdqhashWithQuality(buf);
+ *
+ * if (result) {
+ *   console.log(result.hash, result.quality);
+ * }
+ * ```
+ */
+function pdqhashWithQuality(input) {
+  if (!Buffer.isBuffer(input)) {
+    throw new TypeError('pdqhashWithQuality(input): input must be a Buffer');
+  }
+  const res = addon.generatePdqFromBuffer(input);
+  if (!res) return null;
+  return {
+    hash: Buffer.from(res.hash).toString('hex'),
+    quality: res.quality,
+  };
+}
+
+/**
+ * Compute Hamming distance between two PDQ hashes.
+ *
+ * Accepts two PDQ hash Buffers and returns their Hamming distance
+ * as a number.
+ *
+ * @param a - First PDQ hash as a Buffer.
+ * @param b - Second PDQ hash as a Buffer.
+ * @returns The Hamming distance between `a` and `b`.
+ *
+ * @throws {TypeError}
+ * Thrown if either argument is not a Buffer.
+ *
+ * @example
+ * ```ts
+ * import { pdqhashBuffer, hammingDistance } from "pdqhash-node";
+ *
+ * const a = pdqhashBuffer(fs.readFileSync("image1.jpg"));
+ * const b = pdqhashBuffer(fs.readFileSync("image2.jpg"));
+ *
+ * if (a && b) {
+ *   console.log(hammingDistance(a, b));
+ * }
+ * ```
+ */
+function hammingDistance(a, b) {
+  if (!Buffer.isBuffer(a) || !Buffer.isBuffer(b)) {
+    throw new TypeError('hammingDistance(a, b): arguments must be Buffers');
+  }
+  return addon.hammingDistance(a, b);
+}
+
 module.exports = {
   pdqhash,
+  pdqhashBuffer,
+  pdqhashWithQuality,
+  hammingDistance
 };
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdqhash-node",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "index.js",
   "types": "index.d.ts",
   "license": "Apache-2.0",
@@ -14,7 +14,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/dispherical/pdqhash-node.git"
+    "url": "git+https://github.com/dispherical/pdqhash-node.git"
   },
   "keywords": [
     "pdq",

package/src/lib.rs

@@ -22,3 +22,18 @@ pub fn generate_pdq_from_buffer(input: Buffer) -> Result<Option<PdqResult>> {
         None => Ok(None),
     }
 }
+
+#[napi]
+pub fn hamming_distance(a: Buffer, b: Buffer) -> Result<u32> {
+    if a.len() != b.len() {
+        return Err(Error::new(
+            Status::InvalidArg,
+            "Buffers must be the same length",
+        ));
+    }
+
+    Ok(a.iter()
+        .zip(b.iter())
+        .map(|(x, y)| (x ^ y).count_ones())
+        .sum())
+}