fast-fs-hash - v0.0.0-rc4
    Preparing search index...

    Class FileHashCache

    A long-lived file hash cache configuration holder.

    Stores the cache file path, root path, version, fingerprint, file list, and lock timeout. These can be mutated between opens via setters.

    Call open to acquire an exclusive OS-level lock and get a FileHashCacheSession. Only one session can be active at a time.

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

    // Batch: open, check, write
    using session = await cache.open();
    if (session.status !== "upToDate") {
      await session.write();
    }

    // Watch mode: update files, re-open
    cache.files = newFileList;
    cache.invalidate(["src/foo.ts"]);
    using session2 = await cache.open();
    Index

    Constructors

    constructor

    Accessors

    activeSession busy cachePath fileCount files fingerprint lockTimeoutMs needsOpen rootPath version

    Methods

    checkCacheFile configure invalidate invalidateAll isLocked open overwrite waitUnlocked isLocked waitUnlocked

    Constructors

    Accessors

    • get activeSession(): FileHashCacheSession | null

      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().

      Returns FileHashCacheSession | null

    • get busy(): boolean

      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.

      Returns boolean

    • get cachePath(): string

      Resolved cache file path (immutable after construction).

      Returns string

    • get files(): readonly string[] | null

      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.

      Returns readonly string[] | null

    • set files(value: Iterable<string, any, any> | null): void

      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.

      Parameters

      • value: Iterable<string, any, any> | null

      Returns void

    • get fingerprint(): Uint8Array<ArrayBufferLike> | null

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

      Returns Uint8Array<ArrayBufferLike> | null

    • set fingerprint(value: Uint8Array<ArrayBufferLike> | null): void

      Parameters

      • value: Uint8Array<ArrayBufferLike> | null

      Returns void

    • get lockTimeoutMs(): number

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

      Returns number

    • set lockTimeoutMs(value: number): void

      Parameters

      • value: number

      Returns void

    • get needsOpen(): boolean

      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.

      Returns boolean

    • get rootPath(): string

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

      Returns string

    • set rootPath(value: string | null): void

      Parameters

      • value: string | null

      Returns void

    Methods

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

      Returns boolean

    • 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.

      Parameters

      Returns void

    • 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.

      Parameters

      • paths: Iterable<string>

      Returns void

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

      Returns void

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

      Returns boolean

    • 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++.

      Parameters

      • Optionalsignal: AbortSignal | null

        Optional AbortSignal to cancel the lock wait and/or stat phase.

      Returns Promise<FileHashCacheSession>

      A session holding the lock (or a lockFailed session).

    • 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.

      Parameters

      • Optionaloptions: FileHashCacheWriteOptions | null

        Optional write options (payload values, payload data, signal, lockTimeoutMs).

      Returns Promise<boolean>

    • Wait until the cache file is no longer exclusively locked.

      Parameters

      • OptionallockTimeoutMs: number

        Maximum time to wait in ms. Defaults to this instance's lockTimeoutMs.

      • Optionalsignal: AbortSignal | null

        Optional AbortSignal to cancel the wait.

      Returns Promise<boolean>

      true if unlocked, false on timeout or cancellation.

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

      Parameters

      • cachePath: string

      Returns boolean

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

      Parameters

      • cachePath: string

        Path to the cache file to wait on.

      • OptionallockTimeoutMs: number

        Maximum time to wait in ms. -1 = block until unlocked, 0 = check, >0 = timeout.

      • Optionalsignal: AbortSignal | null

        Optional AbortSignal to cancel the wait.

      Returns Promise<boolean>

      true if unlocked, false on timeout or cancellation.

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods