Class FileHashCache

Create a new FileHashCache configuration.

Normalizes and encodes file paths immediately (no I/O).

The session currently returned by the most recent open (or synthesized on lock failure), or null when no session is live.

Cleared when the session is closed or when a new open()/overwrite() supersedes it. A lockFailed session stays referenced here until closed — useful for inspecting status without re-calling open().

true while THIS instance holds the path mutex — i.e. while a session is active (from open() until session.close()), or while overwrite() is in progress. Does NOT reflect other instances holding the same path; use isLocked for that.

Resolved cache file path (immutable after construction).

Number of tracked files.

Current file list as absolute resolved paths (sorted). null before the first open when constructed without files (reuse-from-disk mode). Lazily decoded from encoded paths — no allocation until first access.

Set the file list. Accepts absolute or relative paths — they are resolved against rootPath, normalized, sorted, and deduplicated. Paths outside rootPath are silently dropped. Marks all entries as dirty.

16-byte fingerprint for fast cache rejection. Must be exactly 16 bytes or null.

Lock acquisition timeout in ms. -1 = block forever, 0 = non-blocking, >0 = timeout.

Whether the cache should be opened (or re-opened).

Returns true when the cache has never been opened, files/version/fingerprint changed, or invalidateAll/invalidate was called.

Root path used for file path resolution. Set to null or "" to auto-detect from files on next open.

User-defined cache version (u32).

Check whether the cache file on disk may have changed since the last open.

Set multiple configuration options at once.

Equivalent to setting individual properties (version, fingerprint, files, rootPath, lockTimeoutMs). Can be called between open() and write() to change what gets written.

Mark specific files as dirty. On the next open, the C++ stat-match will only stat these files (plus any previously invalidated files), skipping stat for all other entries.

Mark all files as dirty. Next open will stat-match every entry.

Check whether the cache file is exclusively locked (by this instance or another process).

Acquire the OS lock without reading or parsing the cache file.

Use this when you only need cross-process mutual exclusion on the cache path — no entries, no payloads, no stat loop. The returned session has status 'missing' and lockOnly === true; its data accessors return empty defaults. The cache file is created (0 bytes) if it doesn't exist; its contents are not read.

Callers may still call FileHashCacheSession.write on the returned session to write a fresh cache (equivalent to overwrite, but reusing the already-held lock — no release / re-acquire dance).

Open the cache with an exclusive OS-level lock.

The JS-side path mutex is acquired first (so worker threads are not tied up waiting on an in-isolate contender). The wait honors signal and the configured lockTimeoutMs. If the JS wait is cancelled or times out, a lockFailed session is returned without ever calling C++. Any time spent waiting on the JS mutex is deducted from the timeout passed to C++.

Write a brand-new cache file without reading the old one.

Uses the current cache configuration (files, version, fingerprint, rootPath). Call configure or set properties before calling this method.

Returns false if the lock could not be acquired (timeout/cancel) or the C++ write failed. Throws if no files are configured — that's a programmer error, not a runtime condition.

Wait until the cache file is no longer exclusively locked.

Check whether another process currently holds an exclusive lock on cachePath.

Wait until the cache file is no longer exclusively locked by another process.