fast-fs-hash

If you ever needed to check whether a set of files changed — to invalidate a cache, skip redundant builds, or trigger incremental CI — fast-fs-hash is for you.

It hashes hundreds of files in milliseconds using xxHash3-128 via a native C++ addon with SIMD acceleration.

xxHash3 is a non-cryptographic hash function — it is not suitable for security purposes, but it is more than enough for cache invalidation, deduplication, and change detection, which is what this library is designed for.

Zero external dependencies. Requires Node.js >= 22.

Installation

npm install fast-fs-hash

Requires Node.js >= 22.

The native addon is prebuilt for common platforms via platform-specific optional dependencies. When you run npm install, npm automatically installs only the package matching your current OS and architecture.

Supported platforms: macOS, Linux (glibc & musl), Windows, FreeBSD — both x64 and arm64.

On x64, optimized variants for AVX2 and AVX-512 are included and selected automatically at load time via native CPUID detection. Set FAST_FS_HASH_ISA=avx2|avx512|baseline to override.

CI note: Some CI configurations disable optional dependencies by default (e.g. npm install --no-optional or --omit=optional). To get the native addon in CI, either allow optional dependencies or install the platform package explicitly:

npm install @fast-fs-hash/fast-fs-hash-node-linux-x64-gnu

FileHashCache — Binary cache invalidation

FileHashCache reads, validates, and writes a compact binary cache file that tracks per-file stat metadata (inode, mtime, ctime, size) and content hashes (xxHash3-128).

On the next run it re-stats every tracked file and compares — files whose stat matches are skipped entirely (no re-read), giving near-instant validation for large file sets.

Why use FileHashCache?

Build systems, code generators, and CI pipelines often produce output that depends on many input files. Recomputing that output on every run is expensive — even when nothing changed.

FileHashCache solves this by persisting a fingerprint of all input files between runs. On the next invocation, it checks whether any input changed in sub-millisecond time (stat-only, no re-reading). If nothing changed, you skip the expensive step entirely.

Common use cases:

• Incremental builds: track source files → skip compilation when inputs are unchanged
• Generated output caching: store a compiled bundle, generated types, or processed assets alongside the cache — rebuild only when dependencies change
• CI artifact caching: validate whether a cached artifact is still fresh before uploading or downloading a new one
• Multi-step pipelines: each stage writes its own cache file, checked independently

The cache file also supports user data — opaque binary payloads stored alongside the file hashes. This lets you embed build output manifests, dependency graphs, or configuration snapshots directly in the cache, so a single open() tells you both "did anything change?" and "what was the previous result?" — no separate metadata files needed.

Why not just hash everything?

Hashing is fast, but reading thousands of files from disk is not. FileHashCache avoids re-reading files that haven't changed by comparing stat() metadata first. Only files with changed stat are re-hashed. This makes cache validation O(n × stat) instead of O(n × read + hash) — typically 10-100× faster for warm caches.

FileHashCache benchmarks (705 files, ~24 MiB)

Native (C++ addon):

| Scenario | Mean | Hz | Files/s | Throughput | | ------------------ | ------------------- | ---------- | ----------------- | ---------- | | no change | 0.6 ms (611.7 µs) | 1 635 op/s | 1 152 586 files/s | — | | 1 file changed | 0.9 ms (945.8 µs) | 1 057 op/s | 745 419 files/s | — | | many files changed | 2.6 ms (2 578.0 µs) | 388 op/s | 273 468 files/s | 9.6 GB/s | | no existing cache | 7.8 ms (7 785.3 µs) | 128 op/s | 90 555 files/s | 3.2 GB/s | | overwrite | 7.9 ms (7 877.9 µs) | 127 op/s | 89 491 files/s | 3.1 GB/s |

Node.js v22.22.2, Vitest 4.x — Apple M4 Max, macOS 25.4.0 (arm64), with anti-virus.

Results vary by hardware, file sizes, and OS cache state.

FileHashCache API

A long-lived cache that tracks file content hashes with exclusive OS-level locking. Create the instance once, then call open() on each build cycle. Configuration (files, version, fingerprint) is set via the constructor, setters, or configure().

Example: Build cache with dynamic file list

The typical usage: the file list is only known after a build step. Open without files (reuses the list from the previous cache on disk), then set the new file list before writing. Use compressedPayloads (LZ4-compressed inside the cache body) or uncompressedPayloads (stored raw, readable without decompression) to store arbitrary build metadata alongside the cache.

import { FileHashCache } from "fast-fs-hash";

const cache = new FileHashCache({
  cachePath: ".cache/build.fsh",
  rootPath: ".",
  version: 1,
});

export async function build() {
  using session = await cache.open();

  if (session.status === "upToDate" && session.compressedPayloads.length > 0) {
    return JSON.parse(session.compressedPayloads[0].toString()); // cached result
  }

  const result = await runBuild();

  cache.configure({ files: result.getSourceFiles().map((f) => f.fileName) });

  await session.write({
    compressedPayloads: [Buffer.from(JSON.stringify(result.output))],
  });

  return result.output;
}

Example: Simple build cache with known files

When the file list is known upfront, pass it to the constructor:

import { FileHashCache } from "fast-fs-hash";
import { globSync } from "node:fs";

const cache = new FileHashCache({
  cachePath: ".cache/build.fsh",
  rootPath: ".",
  files: globSync("src/**/*.ts"),
  version: 1,
});

using session = await cache.open();

if (session.status === "upToDate") {
  console.log("Build cache is fresh — skipping.");
} else {
  console.log("Files changed — rebuilding...");
  await runBuild();
  await session.write();
}

API Reference

Constructor: new FileHashCache({ cachePath, files?, rootPath?, version?, fingerprint?, lockTimeoutMs? })

Cache configuration (mutable between opens):

• configure(opts) — set multiple config fields at once: files, rootPath, version, fingerprint, lockTimeoutMs
• Setters: cache.files, cache.rootPath, cache.version, cache.fingerprint, cache.lockTimeoutMs
• needsOpen — true when config changed since last open, or cache was never opened

Cache methods:

• open(signal?) — acquires an exclusive lock, reads from disk, validates version/fingerprint, stat-matches entries. Returns a FileHashCacheSession.
• overwrite(options?) — writes a brand-new cache without reading the old one. Options: payloadValue0..3, compressedPayloads, uncompressedPayloads, signal, lockTimeoutMs.
• invalidate(paths) / invalidateAll() — mark files as dirty for the next open (watch mode).
• isLocked() / waitUnlocked(timeout?, signal?) — check or wait for lock.
• checkCacheFile() — sync stat check if the cache file on disk changed since last open.

Session properties (read-only, from disk):

• status — see Cache status below
• needsWrite — true if the session holds the lock and the status indicates changes
• configChanged — true if cache config was modified since this session was opened
• wouldNeedWrite — true if either files changed on disk or config changed
• busy / disposed — async operation state
• files, fileCount, version, rootPath
• diskVersion — the user version (u32) read from the on-disk header. Differs from version only when status === 'staleVersion'; lets migration code identify which old format to parse.
• payloadValue0..3 — four f64 numeric values read from disk
• compressedPayloads — array of LZ4-compressed binary Buffer payloads read from disk
• uncompressedPayloads — array of raw binary Buffer payloads readable without LZ4 decompression

Cache status

| Status | Disk readable? | Entries trustable? | Payloads readable? | Action | | ---------------- | ----------------- | ------------------------------ | ------------------ | ---------------------------------------------------------------------- | | 'upToDate' | Yes | Yes | Yes | None | | 'statsDirty' | Yes | Yes (content unchanged) | Yes | Rewrite cache (stats refreshed) | | 'changed' | Yes | Partially (some files changed) | Yes | Re-hash changed files, write | | 'stale' | Yes (well-formed) | No (fingerprint mismatch) | Yes | Discard entries, optionally migrate payloads, write | | 'staleVersion' | Yes (well-formed) | No (version differs) | Yes | As above, plus check session.diskVersion for version-aware migration | | 'missing' | No | — | No | Write fresh | | 'lockFailed' | — | — | — | Retry later |

'stale' and 'staleVersion' both keep the on-disk buffer readable so callers can migrate compressedPayloads / uncompressedPayloads / payloadValueN across config changes. 'missing' covers genuinely unreadable files (no file, truncated header, bad magic, corrupt body) — never thrown, always reported via this status so callers can recover by writing fresh.

Session methods:

• write(options?) — hashes unresolved entries, compresses, writes to disk, releases lock. Can only be called once. Options: payloadValue0..3, compressedPayloads, uncompressedPayloads, signal.
• resolve(signal?) — completes stat + hash for ALL files, returns FileHashCacheEntries. Can be called before write(). See below.
• close() — releases the lock. Also called automatically by using.

Static methods:

• FileHashCache.isLocked(cachePath) — check if locked by another process
• FileHashCache.waitUnlocked(cachePath, lockTimeoutMs?, signal?) — wait for unlock

Lock behavior:

• Cross-process exclusive lock via flock(2) (POSIX) / LockFileEx (Windows)
• Cross-thread safe: per-OFD semantics on POSIX and per-handle on Windows make worker_threads in the same process serialize correctly against each other
• Crash-safe: automatically released when the process dies
• lockTimeoutMs: -1 = block forever (default), 0 = non-blocking, >0 = timeout ms
• When lock fails: status === 'lockFailed'. Calling write() falls back to overwrite().
• Cancellable via AbortSignal on open(), overwrite(), and waitUnlocked()

Inspecting per-file changes with resolve()

After open(), the session knows the aggregate status but not which specific files changed. Call resolve() to complete stat + hash for every file and get per-file metadata.

Note: resolve() stats and hashes every unresolved file on the thread pool. This has a cost proportional to the number of changed files. Use it only when you need per-file information — for simple "changed → rebuild all" workflows, just check session.status.

using session = await cache.open();

if (session.status !== "upToDate") {
  const entries = await session.resolve();

  for (const entry of entries) {
    if (entry.changed) {
      console.log(
        `Changed: ${entry.path} (${entry.size} bytes, hash: ${entry.contentHashHex})`,
      );
    }
  }

  await session.write();
}

Each FileHashCacheEntry provides:

• path — absolute file path
• size — file size in bytes
• mtimeMs / ctimeMs — modification / change time in ms
• changed — true if content differs from the cached version (or is a new file)
• contentHash — 16-byte xxHash3-128 as a Buffer (zero-copy view)
• contentHashHex — 32-char hex string (lazy, computed on first access)

FileHashCacheEntries supports get(index), find(path), and iteration. The result is cached — subsequent calls to resolve() return the same snapshot.

xxHash128 — Direct hashing

When you don't need a persistent cache file — or you want raw xxHash3-128 digests to compare yourself — use the digest functions directly. FileHashCache uses them under the hood, but they are fully usable on their own.

File hashing benchmarks

large file (~197.3 KB):

| Scenario | Mean | Hz | Throughput | Relative | | -------------------- | ----------------- | ----------- | ---------- | --------------- | | native | 0.04 ms (43.5 µs) | 23 004 op/s | 4.5 GB/s | 6.6× faster | | Node.js crypto (md5) | 0.3 ms (285.8 µs) | 3 499 op/s | 690 MB/s | baseline |

medium file (~49.9 KB):

| Scenario | Mean | Hz | Throughput | Relative | | -------------------- | ----------------- | ----------- | ---------- | --------------- | | native | 0.03 ms (29.1 µs) | 34 413 op/s | 1.7 GB/s | 3.9× faster | | Node.js crypto (md5) | 0.1 ms (114.4 µs) | 8 740 op/s | 436 MB/s | baseline |

small file (~1.0 KB):

| Scenario | Mean | Hz | Relative | | -------------------- | ----------------- | ----------- | --------------- | | native | 0.02 ms (24.2 µs) | 41 358 op/s | 2.4× faster | | Node.js crypto (md5) | 0.06 ms (56.8 µs) | 17 591 op/s | baseline |

Parallel file hashing (705 files)

| Scenario | Mean | Hz | Throughput | Relative | | -------------------- | --------------------- | -------- | ---------- | --------------- | | native | 7.7 ms (7 728.3 µs) | 129 op/s | 3.2 GB/s | 4.6× faster | | Node.js crypto (md5) | 35.2 ms (35 241.8 µs) | 28 op/s | 701 MB/s | baseline |

In-memory buffer hashing

64 KB buffer:

| Scenario | Mean | Hz | Throughput | Relative | | ------------------ | ----------------- | ------------ | ---------- | ---------------- | | native XXH3-128 | 0.001 ms (1.4 µs) | 702 200 op/s | 46.0 GB/s | 48.3× faster | | Node.js crypto md5 | 0.07 ms (68.7 µs) | 14 547 op/s | 953 MB/s | baseline |

1 MB buffer:

| Scenario | Mean | Hz | Throughput | Relative | | ------------------ | ------------------- | ----------- | ---------- | ---------------- | | native XXH3-128 | 0.02 ms (22.0 µs) | 45 497 op/s | 47.7 GB/s | 49.7× faster | | Node.js crypto md5 | 1.1 ms (1 091.5 µs) | 916 op/s | 961 MB/s | baseline |

Hash files

import { digestFilesParallel, hashToHex } from "fast-fs-hash";

const digest = await digestFilesParallel([
  "package.json",
  "src/index.ts",
  "src/utils.ts",
]);
console.log("Aggregate:", hashToHex(digest));

Sequential variant (feeds files into a single running hash):

import { digestFilesSequential, hashToHex } from "fast-fs-hash";

const digest = await digestFilesSequential(["package.json", "src/index.ts"]);
console.log(hashToHex(digest));

Hash a single file

import { digestFile, hashToHex } from "fast-fs-hash";

const digest = await digestFile("package.json");
console.log(hashToHex(digest));

Hex string convenience

import { digestFileToHex, digestFilesToHexArray } from "fast-fs-hash";

// Single file → 32-char hex string
const hex = await digestFileToHex("package.json");

// Multiple files in parallel → per-file hex strings
const hexes = await digestFilesToHexArray(["src/a.ts", "src/b.ts"], 8);

| Function | Description | | ----------------------------------------------------------- | ----------------------------------------------------------------------- | | digestFileToHex(path, throwOnError?) | Hash a file → 32-char hex string. Wrapper around digestFile + hashToHex | | digestFilesToHexArray(paths, concurrency?, throwOnError?) | Hash files in parallel → per-file hex strings. Default concurrency 8 |

Hash buffers and strings

import { digestBuffer, digestString } from "fast-fs-hash";

const d1 = digestBuffer(myBuffer);
const d2 = digestString("hello world");
console.log(d2.toString("hex"));

Streaming class

For combining file hashes with extra data (config, environment, etc.):

import { XxHash128Stream } from "fast-fs-hash";

const h = new XxHash128Stream();
h.addString("my-config-v2");
await h.addFiles(["src/index.ts", "src/utils.ts"]);
console.log(h.digest().toString("hex"));

Busy guard: Async methods (addFile, addFiles, addFilesParallel) mark the instance as busy while the native worker thread is processing. During this time, calling any synchronous method or starting another async operation will throw an error. Always await each async call before invoking another method. Use the busy getter to check:

const h = new XxHash128Stream();
const promise = h.addFile("large.bin");
console.log(h.busy); // true — async operation in flight
// h.addString("oops"); // would throw!
await promise;
console.log(h.busy); // false — safe to use again

LZ4 Block Compression

fast-fs-hash exposes the LZ4 block compression API used internally for the cache file format. Both synchronous and asynchronous (pool-thread) variants are available.

LZ4 block format does not embed the uncompressed size — the caller must store it alongside the compressed data and pass it to the decompression function.

compress 64 KB:

| Scenario | Ratio | Mean | Hz | Throughput | Relative | | ----------------------- | ----- | ----------------- | ------------ | ---------- | --------------- | | native LZ4 | 0.7% | 0.003 ms (3.5 µs) | 287 745 op/s | 18.9 GB/s | 7.4× faster | | Node.js deflate level=1 | 1.0% | 0.03 ms (25.7 µs) | 38 932 op/s | 2.6 GB/s | baseline |

decompress 64 KB:

| Scenario | Mean | Hz | Throughput | Relative | | --------------- | ----------------- | ------------ | ---------- | --------------- | | native LZ4 | 0.002 ms (2.0 µs) | 489 721 op/s | 32.1 GB/s | 3.9× faster | | Node.js deflate | 0.008 ms (7.9 µs) | 127 080 op/s | 8.3 GB/s | baseline |

compress 1 MB:

| Scenario | Ratio | Mean | Hz | Throughput | Relative | | ----------------------- | ----- | ----------------- | ----------- | ---------- | --------------- | | native LZ4 | 0.4% | 0.04 ms (35.2 µs) | 28 435 op/s | 29.8 GB/s | 9.9× faster | | Node.js deflate level=1 | 0.7% | 0.3 ms (348.6 µs) | 2 869 op/s | 3.0 GB/s | baseline |

decompress 1 MB:

| Scenario | Mean | Hz | Throughput | Relative | | --------------- | ----------------- | ----------- | ---------- | --------------- | | native LZ4 | 0.03 ms (32.2 µs) | 31 055 op/s | 32.6 GB/s | 2.4× faster | | Node.js deflate | 0.08 ms (76.4 µs) | 13 086 op/s | 13.7 GB/s | baseline |

import {
  lz4CompressBlock,
  lz4DecompressBlock,
  lz4CompressBound,
} from "fast-fs-hash";

const input = Buffer.from("Hello, LZ4!");
const compressed = lz4CompressBlock(input);
const decompressed = lz4DecompressBlock(compressed, input.length);
console.log(decompressed.toString()); // "Hello, LZ4!"

LZ4 API

| Function | Description | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | lz4CompressBlock(input, offset?, length?) | Sync compress → new Buffer | | lz4CompressBlockTo(input, output, outputOffset?, inputOffset?, inputLength?) | Sync compress into pre-allocated buffer → bytes written | | lz4CompressBlockAsync(input, offset?, length?) | Async compress on pool thread → Promise<Buffer> | | lz4DecompressBlock(input, uncompressedSize, offset?, length?) | Sync decompress → new Buffer | | lz4DecompressBlockTo(input, uncompressedSize, output, outputOffset?, inputOffset?, inputLength?) | Sync decompress into pre-allocated buffer → bytes written | | lz4DecompressBlockAsync(input, uncompressedSize, offset?, length?) | Async decompress on pool thread → Promise<Buffer> | | lz4CompressBound(inputSize) | Max compressed size for pre-allocation | | lz4ReadAndCompress(path) | Read a file and LZ4-compress it on pool thread → Promise<{data, uncompressedSize}> | | lz4DecompressAndWrite(compressedData, uncompressedSize, path) | Decompress and write to file on pool thread (creates dirs) → Promise<boolean> |

Note: LZ4 block compression supports inputs up to ~1.9 GiB (LZ4_MAX_INPUT_SIZE = 0x7E000000). lz4ReadAndCompress and lz4DecompressAndWrite support files up to 512 MiB.

Read and compress a file

lz4ReadAndCompress reads a file and LZ4-block-compresses it in a single pool-thread operation — no JS-thread I/O, no intermediate Buffer allocation visible to the event loop.

import {
  lz4ReadAndCompress,
  lz4DecompressAndWrite,
  lz4DecompressBlock,
} from "fast-fs-hash";

const { data, uncompressedSize } = await lz4ReadAndCompress("large-file.bin");
console.log(`Compressed ${uncompressedSize} → ${data.length} bytes`);

// Decompress back to a file (creates parent directories if needed)
await lz4DecompressAndWrite(data, uncompressedSize, "restored-file.bin");

// Or decompress to a buffer in memory
const original = lz4DecompressBlock(data, uncompressedSize);

File Comparison

Compare two files for byte-equality asynchronously on a native pool thread. Opens both files, compares sizes via fstat, then reads in lockstep chunks with memcmp. Returns false if either file cannot be opened/read or if sizes differ — never throws.

equal files (~49.9 KB):

| Scenario | Mean | Hz | Throughput | Relative | | ---------------------------------- | ----------------- | ----------- | ---------- | --------------- | | native | 0.04 ms (43.2 µs) | 23 143 op/s | 1.2 GB/s | 2.5× faster | | Node.js (fs.open + read + compare) | 0.1 ms (106.3 µs) | 9 411 op/s | 470 MB/s | baseline |

equal files (~197.3 KB):

| Scenario | Mean | Hz | Throughput | Relative | | ---------------------------------- | ----------------- | ----------- | ---------- | --------------- | | native | 0.05 ms (49.4 µs) | 20 244 op/s | 4.0 GB/s | 3.0× faster | | Node.js (fs.open + read + compare) | 0.1 ms (148.9 µs) | 6 715 op/s | 1.3 GB/s | baseline |

different content, same size (~49.9 KB):

| Scenario | Mean | Hz | Throughput | Relative | | ---------------------------------- | ----------------- | ----------- | ---------- | --------------- | | native | 0.04 ms (39.5 µs) | 25 307 op/s | 1.3 GB/s | 2.6× faster | | Node.js (fs.open + read + compare) | 0.1 ms (102.2 µs) | 9 784 op/s | 488 MB/s | baseline |

different sizes (early exit):

| Scenario | Mean | Hz | Relative | | ---------------------------------- | ----------------- | ----------- | --------------- | | native | 0.04 ms (36.5 µs) | 27 397 op/s | 2.5× faster | | Node.js (fs.open + read + compare) | 0.09 ms (89.8 µs) | 11 136 op/s | baseline |

import { filesEqual } from "fast-fs-hash";

if (await filesEqual("output.bin", "expected.bin")) {
  console.log("Files are identical");
} else {
  console.log("Files differ (or one doesn't exist)");
}

| Function | Description | | -------------------------- | ------------------------------------------------------------- | | filesEqual(pathA, pathB) | Async byte-equality check on pool thread → Promise<boolean> |

Find Project Root

Walk the parent chain from a start path and locate project markers in a single pass: .git, package.json, tsconfig.json, and node_modules/. Reports nearest* (first hit walking up) and root* (last hit, bounded by the enclosing .git) for each marker, plus gitRoot and gitSuperRoot for submodule/worktree awareness.

The walk stops at the filesystem root, the user's home directory (or any ancestor of it), an optional stopPath, and a depth cap of 128 (symlink-loop defense). Tolerant of missing paths — if startPath doesn't exist, the walk begins from its longest existing ancestor and missing markers are returned as null rather than thrown.

shallow (3 levels deep):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.04 ms (45.0 µs) | 22 240 op/s | 6.2× faster | | native (async) | 0.06 ms (55.7 µs) | 17 968 op/s | 5.0× faster | | Node.js (sync, fs.statSync) | 0.1 ms (115.2 µs) | 8 682 op/s | 2.4× faster | | Node.js (async, fs.stat) | 0.3 ms (280.7 µs) | 3 562 op/s | baseline |

deep (12 levels deep):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.09 ms (92.6 µs) | 10 804 op/s | 7.9× faster | | native (async) | 0.1 ms (104.3 µs) | 9 586 op/s | 7.0× faster | | Node.js (sync, fs.statSync) | 0.3 ms (322.9 µs) | 3 096 op/s | 2.3× faster | | Node.js (async, fs.stat) | 0.7 ms (730.4 µs) | 1 369 op/s | baseline |

missing start path (tolerant fallback):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.06 ms (56.8 µs) | 17 614 op/s | 2.4× faster | | Node.js (sync, fs.statSync) | 0.1 ms (136.7 µs) | 7 315 op/s | baseline |

import { findProjectRoot, findProjectRootSync } from "fast-fs-hash";

// Sync (recommended for startup-time / build-tool use)
const info = findProjectRootSync(import.meta.dirname);
console.log(info.gitRoot, info.rootPackageJson, info.nearestTsconfigJson);

// Async — runs on the native thread pool, useful on cold or networked filesystems
const info2 = await findProjectRoot("/some/deep/file.ts");

// Optional stopPath: halt when the walker reaches this directory (or any ancestor of it)
const info3 = findProjectRootSync(start, "/workspace");

| Function | Description | | ------------------------------------------ | ------------------------------------------------------------ | | findProjectRootSync(startPath, stopPath) | Walk parent chain for project markers (sync) → ProjectRoot | | findProjectRoot(startPath, stopPath) | Walk parent chain on pool thread → Promise<ProjectRoot> |

The returned ProjectRoot object has these fields (each string | null):

| Field | Description | | --------------------- | ------------------------------------------------------------------------------ | | gitRoot | Innermost .git (dir or file). Matches git rev-parse --show-toplevel. | | gitSuperRoot | Outermost .git directory. Non-null only in submodules / nested worktrees. | | nearestPackageJson | First package.json walking up. | | rootPackageJson | Last package.json walking up, bounded by gitRoot. | | nearestTsconfigJson | First tsconfig.json walking up. | | rootTsconfigJson | Last tsconfig.json walking up, bounded by gitRoot. | | nearestNodeModules | First node_modules/ directory walking up (also detects when started inside). | | rootNodeModules | Last node_modules/ walking up, bounded by gitRoot. |

Find Nearest Project Files

A trimmed-down sibling of findProjectRoot that finds only the nearest package.json, tsconfig.json, and node_modules/ and exits the walk as soon as all three are populated. No .git probe, no gitRoot boundary, no root* fields — faster than findProjectRoot when callers don't need them.

The walk stops at the filesystem root, the user's home directory (or any ancestor of it), an optional stopPath, and a depth cap of 128. Tolerant of missing paths — missing fields are returned as null rather than throwing.

shallow (3 levels deep):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.03 ms (31.3 µs) | 31 911 op/s | 4.2× faster | | native (async) | 0.04 ms (42.8 µs) | 23 368 op/s | 3.1× faster | | Node.js (sync, fs.statSync) | 0.05 ms (54.9 µs) | 18 224 op/s | 2.4× faster | | Node.js (async, fs.stat) | 0.1 ms (132.4 µs) | 7 553 op/s | baseline |

deep (12 levels deep):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.07 ms (70.3 µs) | 14 216 op/s | 6.8× faster | | native (async) | 0.08 ms (80.1 µs) | 12 483 op/s | 5.9× faster | | Node.js (sync, fs.statSync) | 0.2 ms (217.5 µs) | 4 598 op/s | 2.2× faster | | Node.js (async, fs.stat) | 0.5 ms (476.3 µs) | 2 100 op/s | baseline |

missing start path (tolerant fallback):

| Scenario | Mean | Hz | Relative | | --------------------------- | ----------------- | ----------- | --------------- | | native (sync) | 0.03 ms (34.4 µs) | 29 045 op/s | 2.1× faster | | Node.js (sync, fs.statSync) | 0.07 ms (72.0 µs) | 13 894 op/s | baseline |

import {
  findNearestProjectFiles,
  findNearestProjectFilesSync,
} from "fast-fs-hash";

// Sync (recommended for startup-time / build-tool use)
const info = findNearestProjectFilesSync(import.meta.dirname);
console.log(info.packageJson, info.tsconfigJson, info.nodeModules);

// Async — runs on the native thread pool
const info2 = await findNearestProjectFiles("/some/deep/file.ts");

// Optional stopPath: halt when the walker reaches this directory (or any ancestor of it)
const info3 = findNearestProjectFilesSync(start, "/workspace");

| Function | Description | | -------------------------------------------------- | -------------------------------------------------------------------- | | findNearestProjectFilesSync(startPath, stopPath) | Walk parent chain for nearest markers (sync) → NearestProjectFiles | | findNearestProjectFiles(startPath, stopPath) | Walk parent chain on pool thread → Promise<NearestProjectFiles> |

The returned NearestProjectFiles object has these fields (each string | null):

| Field | Description | | -------------- | ------------------------------------------------------------------------------ | | packageJson | First package.json walking up. | | tsconfigJson | First tsconfig.json walking up. | | nodeModules | First node_modules/ directory walking up (also detects when started inside). |

Utility Functions

| Function | Description | | ---------------------------------------------------- | -------------------------------------------------------------------- | | hashToHex(digest) | Convert a 16-byte digest to a 32-char hex string | | hashesToHexArray(digests) | Convert an array of digests to hex strings | | findCommonRootPath(files, baseRoot?, allowedRoot?) | Longest common parent directory of file paths | | normalizeFilePaths(rootPath, files) | Resolve, sort, deduplicate paths relative to root | | toRelativePath(rootPath, filePath) | Single path → clean unix-style relative path (or null) | | threadPoolTrim() | Wake idle native pool threads so they self-terminate and free memory |

Environment Variables

| Variable | Default | Description | | ----------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | FAST_FS_HASH_ISA | auto-detect | Override SIMD variant: avx512, avx2, or baseline (x64 only) | | FAST_FS_HASH_POOL_IDLE_TIMEOUT_MS | 15000 | Idle timeout for native pool threads (1–3600000 ms). Threads self-terminate after this duration with no work. They respawn automatically when new work arrives. |

Acknowledgements

The native C++ backend uses:

• xxHash by Yann Collet — xxHash3-128 hashing (BSD 2-Clause License)
• LZ4 by Yann Collet — block compression (BSD 2-Clause License)

See NOTICES.md for full license texts.

Building from source

Prerequisites

| Tool | Version | Install | | -------------- | ------------------------------- | --------------------------------------------------------------------------- | | Node.js | >= 22 | nodejs.org | | npm | >= 9 | bundled with Node.js | | CMake | >= 3.15 | brew install cmake / apt install cmake / cmake.org | | C++20 compiler | Clang 14+ / GCC 12+ / MSVC 2022 | Xcode CLT / build-essential / Visual Studio |

Quick start

git clone --recurse-submodules https://github.com/SalvatorePreviti/fast-fs-hash.git
cd fast-fs-hash
npm install
npm run build:all   # compile C++ addon + TypeScript
npm test            # run tests
npm run bench       # run benchmarks

Note: git clone --recurse-submodules is required to pull deps/xxHash (the xxHash source used by the native addon).

Git submodule (xxHash)

The deps/xxHash/ directory is a git submodule pointing to xxHash v0.8.3.

If you cloned without --recurse-submodules, initialize the submodule manually:

git submodule update --init --recursive

See package.json for the full list of available build scripts.

Release process

• main — development branch. CI runs lint, typecheck, tests, and builds native binaries for all platforms on every push and PR.
• publish — release branch. Pushing to publish triggers the full CI pipeline. After all builds and tests pass, a dry-run publish verifies all packages. An admin must then manually approve the publish job (via the npm-publish GitHub environment) to publish to npm, create a git tag, and deploy docs.

npm packages are published with provenance attestations via GitHub Actions OIDC — no npm tokens are stored in CI.

Required GitHub repository settings

• Branch protection on publish: require PR reviews, require status checks to pass, restrict push access to admins only.
• Environment npm-publish: create under Settings → Environments with "Required reviewers" restricted to trusted maintainers.
• npm trusted publishing: configure each @fast-fs-hash/* package on npmjs.com to trust the npm-publish environment from this repository.

License

MIT — Copyright (c) 2025-present Salvatore Previti