feat: add Node.js support

Author: ClaudiuCeia

.github/workflows/ci.yml

@@ -19,8 +19,17 @@ jobs:
         with:
           deno-version: v2.x
 
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          package-manager-cache: false
+
       - name: Check
         run: deno task check
 
       - name: Validate package
         run: deno publish --dry-run
+
+      - name: Validate npm package
+        run: deno task check:npm

.github/workflows/publish-jsr.yml .github/workflows/publish.yml.github/workflows/publish-jsr.yml renamed to .github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish to JSR
+name: Publish
 
 on:
   push:
@@ -17,7 +17,7 @@ permissions:
   id-token: write
 
 concurrency:
-  group: publish-jsr-${{ github.ref }}
+  group: publish-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
@@ -35,6 +35,13 @@ jobs:
         with:
           deno-version: v2.x
 
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          package-manager-cache: false
+          registry-url: https://registry.npmjs.org
+
       - name: Verify tag matches deno.json version
         shell: bash
         run: |
@@ -51,9 +58,20 @@ jobs:
       - name: Check
         run: deno task check
 
-      - name: Publish
+      - name: Validate npm package
+        run: deno task check:npm
+
+      - name: Publish to JSR
         run: deno publish
 
+      - name: Pack npm package
+        run: deno pack --ignore=deno.lock --output dhash.tgz
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish dhash.tgz --access public
+
       - name: Generate release notes
         shell: bash
         run: |

.gitignore

@@ -1,2 +1,3 @@
 node_modules/
 coverage/
+*.tgz

AGENTS.md

@@ -49,15 +49,19 @@ function/type, export it from `mod.ts` and add/adjust tests under `tests/`.
   - notes on permission changes or dependency changes (especially
     `npm:sharp@...`) and any `deno.lock` updates.
 
-## Publishing (JSR)
+## Publishing
 
 - Bump `version` in `deno.json`.
 - Validate locally: `deno fmt`, `deno lint`, `deno task test`.
 - Preview package contents: `deno publish --dry-run`.
-- Publish: `deno publish` (auth via token/login).
+- Preview the npm package: `deno pack --dry-run --ignore=deno.lock`.
+- Publish to JSR: `deno publish` (auth via token/login).
+- Publish to npm: `deno pack --ignore=deno.lock --output dhash.tgz` then
+  `npm publish dhash.tgz --access public`.
 - CI publish: push a semver tag matching `deno.json`’s version (e.g. `v0.2.0`).
-  GitHub Actions will run checks then publish via JSR’s tokenless GitHub Actions
-  flow (OIDC). This requires linking the package to this GitHub repo in the JSR
-  package settings.
+  GitHub Actions will run checks, publish to JSR via its tokenless GitHub
+  Actions flow (OIDC), and publish to npm using the `NPM_TOKEN` repository
+  secret. JSR publishing requires linking the package to this GitHub repo in the
+  JSR package settings.
 - CI also creates a GitHub Release for the tag using release notes generated
   from the git log since the previous `v*` tag.

README.md

@@ -1,6 +1,6 @@
 # dhash
 
-_A `dhash` implementation for Deno._
+_A `dhash` implementation for Deno and Node.js._
 
 A fast algorithm that allows checking if two images are "kind of" the same (the
 same source image, slightly modified). Examples:
@@ -31,6 +31,15 @@ deployed separately from the JSR package.
 
 ## Usage
 
+Install from JSR with Deno, or directly from npm with Node.js:
+
+```sh
+deno add jsr:@claudiu-ceia/dhash
+npm install @claudiu-ceia/dhash
+```
+
+The npm package is ESM-only.
+
 You can compare dhash values by simply computing the Hamming distance between
 them:
 
@@ -41,7 +50,7 @@ them:
   of the same base image
 
 ```ts
-import { compare, dhash } from "jsr:@claudiu-ceia/dhash";
+import { compare, dhash } from "@claudiu-ceia/dhash";
 
 const [hash1, hash2] = await Promise.all([
   dhash("./tests/dalle.png"),
@@ -71,13 +80,15 @@ preserved.
 ## Development
 
 - Run all checks: `deno task check`.
+- Build, install, and test the npm package with Node.js: `deno task check:npm`.
 - Try the experimental TypeScript 7 native checker: `deno task check:ts7`.
   Release CI continues to use Deno's stable default checker.
 - Run only tests: `deno task test` (requires
   `--allow-read --allow-write --allow-ffi --allow-env` because `sharp` uses
   native bindings, reads fixtures, and the `save()` test writes to a temporary
   directory).
 - Preview the JSR package: `deno publish --dry-run`.
+- Preview the npm package: `deno pack --dry-run --ignore=deno.lock`.
 
 ## License
 

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudiu-ceia/dhash",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "license": "MIT",
   "exports": "./mod.ts",
   "nodeModulesDir": "auto",
@@ -12,17 +12,18 @@
       "docs",
       "coverage",
       "node_modules",
+      "scripts",
       "AGENTS.md"
     ]
   },
   "tasks": {
-    "check": "deno fmt --check && deno lint && deno check mod.ts && deno check --config docs/deno.json docs/main.ts && deno task test",
-    "check:ts7": "deno check --unstable-tsgo mod.ts && deno check --unstable-tsgo --config docs/deno.json docs/main.ts && deno test --unstable-tsgo --allow-read --allow-write --allow-ffi --allow-env",
+    "check": "deno fmt --check && deno lint && deno check mod.ts scripts/test_npm.ts && deno check --config docs/deno.json docs/main.ts && deno task test",
+    "check:npm": "deno run -A scripts/test_npm.ts",
+    "check:ts7": "deno check --unstable-tsgo mod.ts scripts/test_npm.ts && deno check --unstable-tsgo --config docs/deno.json docs/main.ts && deno test --unstable-tsgo --allow-read --allow-write --allow-ffi --allow-env",
     "test": "deno test --allow-read --allow-write --allow-ffi --allow-env"
   },
   "imports": {
     "@std/assert": "jsr:@std/assert@^1.0.19",
-    "@std/path": "jsr:@std/path@^1.1.6",
     "sharp": "npm:sharp@0.35.3"
   }
 }

deno.lock

@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  compare,
+  dhash,
+  invertHash,
+  raw,
+  save,
+  toAscii,
+} from "@claudiu-ceia/dhash";
+
+const fixtures = process.env.DHASH_FIXTURES;
+assert.ok(fixtures, "DHASH_FIXTURES must point to the image fixtures");
+
+const expected = {
+  "dalle.png": "7735ac8c2da4746c",
+  "dalle-copyright.png": "7735ac0c2da4746c",
+  "dalle-bolder-copyright.jpeg": "7735ac852da4746c",
+  "dalle-crop.jpeg": "19e52b2908084d6c",
+  "dalle-edited.jpeg": "77352c0c2da4746c",
+  "dalle-stickers.jpeg": "77358c8c2da4746c",
+};
+
+const hashes = [];
+for (const [name, expectedHash] of Object.entries(expected)) {
+  const path = join(fixtures, name);
+  const pathHash = await dhash(path);
+  const bytesHash = await dhash(await readFile(path));
+  assert.equal(pathHash, expectedHash);
+  assert.equal(bytesHash, expectedHash);
+  hashes.push(pathHash);
+}
+
+assert.equal(compare(hashes[0], hashes[1]), 1);
+assert.equal(compare(hashes[0], hashes[2]), 2);
+assert.equal(compare(hashes[0], hashes[3]), 27);
+assert.equal(compare(hashes[0], hashes[4]), 2);
+assert.equal(compare(hashes[0], hashes[5]), 1);
+assert.equal(invertHash(invertHash(hashes[0])), hashes[0]);
+assert.equal(toAscii(hashes[0]).split("\n").length, 8);
+
+const png = await raw(hashes[0]);
+assert.deepEqual(
+  Array.from(png.slice(0, 8)),
+  [137, 80, 78, 71, 13, 10, 26, 10],
+);
+
+const output = join(process.cwd(), "fingerprint");
+await save(hashes[0], output);
+assert.deepEqual(
+  Array.from((await readFile(output + ".png")).slice(0, 8)),
+  [137, 80, 78, 71, 13, 10, 26, 10],
+);
+
+await assert.rejects(() => dhash(join(fixtures, "missing.png")));

scripts/npm_integration.mjs

@@ -0,0 +1,91 @@
+import { fileURLToPath } from "node:url";
+
+const packageName = "@claudiu-ceia/dhash";
+const npm = Deno.build.os === "windows" ? "npm.cmd" : "npm";
+const npx = Deno.build.os === "windows" ? "npx.cmd" : "npx";
+const fixtureDirectory = fileURLToPath(new URL("../tests", import.meta.url));
+
+async function run(
+  command: string,
+  args: string[],
+  cwd: string,
+  env?: Record<string, string>,
+) {
+  const child = new Deno.Command(command, {
+    args,
+    cwd,
+    env,
+    stdin: "null",
+    stdout: "inherit",
+    stderr: "inherit",
+  }).spawn();
+  const status = await child.status;
+
+  if (!status.success) {
+    throw new Error(`${command} exited with code ${status.code}`);
+  }
+}
+
+const directory = await Deno.makeTempDir({ prefix: "dhash-npm-" });
+const archive = `${directory}/dhash.tgz`;
+
+try {
+  await run(
+    Deno.execPath(),
+    ["pack", "--allow-dirty", "--ignore=deno.lock", "--output", archive],
+    Deno.cwd(),
+  );
+
+  await Deno.writeTextFile(
+    `${directory}/package.json`,
+    JSON.stringify({ private: true, type: "module" }),
+  );
+  await Deno.copyFile(
+    new URL("./npm_integration.mjs", import.meta.url),
+    `${directory}/integration.mjs`,
+  );
+  await Deno.writeTextFile(
+    `${directory}/consumer.ts`,
+    `import { type DHashOptions, dhash } from "${packageName}";
+const options: DHashOptions = { invert: true };
+const hash: Promise<string> = dhash(new Uint8Array(), options);
+void hash;
+`,
+  );
+  await Deno.writeTextFile(
+    `${directory}/tsconfig.json`,
+    JSON.stringify({
+      compilerOptions: {
+        module: "NodeNext",
+        moduleResolution: "NodeNext",
+        noEmit: true,
+        strict: true,
+        target: "ES2022",
+      },
+      include: ["consumer.ts"],
+    }),
+  );
+
+  await run(npm, ["install", "--no-audit", "--no-fund", archive], directory);
+  await run(npm, ["audit", "--omit=dev", "--audit-level=high"], directory);
+  await run(
+    npx,
+    ["--yes", "--package=typescript@7.0.2", "tsc", "--project", "."],
+    directory,
+  );
+
+  const versions = Deno.args.length > 0 ? Deno.args : [null];
+  for (const version of versions) {
+    const command = version === null ? "node" : npx;
+    const args = version === null
+      ? ["integration.mjs"]
+      : ["--yes", `--package=node@${version}`, "node", "integration.mjs"];
+    await run(command, args, directory, {
+      DHASH_FIXTURES: fixtureDirectory,
+    });
+  }
+
+  console.log(`Verified ${packageName} from a packed npm tarball.`);
+} finally {
+  await Deno.remove(directory, { recursive: true });
+}

scripts/test_npm.ts

@@ -1,5 +1,6 @@
 import sharp from "sharp";
-import { normalize, resolve } from "@std/path";
+import { readFile, writeFile } from "node:fs/promises";
+import { normalize, resolve } from "node:path";
 
 /**
  * Options for {@link dhash}.
@@ -36,7 +37,7 @@ export const invertHash = (hash: string): string => {
  * Bit convention: by default, bit `1` means the intensity increases left-to-right
  * (`left < right`). Use `options.invert` to flip this.
  *
- * @param pathOrSrc File path (relative to `Deno.cwd()`) or raw image bytes.
+ * @param pathOrSrc File path (relative to the current working directory) or raw image bytes.
  * @returns 16-character lowercase hex string.
  */
 export const dhash = async (
@@ -46,10 +47,10 @@ export const dhash = async (
   let file = pathOrSrc;
 
   if (typeof pathOrSrc === "string") {
-    const resolvedPath = resolve(Deno.cwd(), normalize(pathOrSrc));
+    const resolvedPath = resolve(normalize(pathOrSrc));
 
     try {
-      file = await Deno.readFile(resolvedPath);
+      file = await readFile(resolvedPath);
     } catch {
       throw new Error(`Failed to open "${resolvedPath}"`);
     }
@@ -136,5 +137,5 @@ export async function raw(hash: string): Promise<Uint8Array> {
  */
 export async function save(hash: string, filePath: string): Promise<void> {
   const buffer = await raw(hash);
-  await Deno.writeFile(`${filePath}.png`, buffer);
+  await writeFile(`${filePath}.png`, buffer);
 }