Interface FileHashCacheSession

ReadonlypayloadValue0

ReadonlypayloadValue1

ReadonlypayloadValue2

ReadonlypayloadValue3

ReadonlyrootPath

Readonlystatus

Readonlyversion

busy

• get busy(): boolean

  true while resolve or write is in progress.

  Returns boolean

cache

• get cache(): FileHashCache

  The parent FileHashCache that created this session.

  Returns FileHashCache

compressedPayloads

• get compressedPayloads(): readonly Buffer<ArrayBufferLike>[]

  LZ4-compressed opaque binary payloads read from disk. Empty array if none. Lazily decoded, zero-copy.

  Returns readonly Buffer<ArrayBufferLike>[]

configChanged

• get configChanged(): boolean

  true if the cache configuration (files, version, fingerprint) was modified since this session was opened (via setters or FileHashCache.configure).

  Returns boolean

disposed

• get disposed(): boolean

  true once close or write has released the lock.

  Returns boolean

fileCount

• get fileCount(): number

  Number of tracked files (from disk, or from the constructor when status is 'missing').

  Returns number

files

• get files(): readonly string[]

  File list as absolute paths. When status is 'missing', reflects the files passed to the constructor. Lazily decoded from the on-disk representation.

  Returns readonly string[]

needsWrite

• get needsWrite(): boolean

  true if the session holds the lock and the status indicates a write is needed.

  Returns boolean

uncompressedPayloads

• get uncompressedPayloads(): readonly Buffer<ArrayBufferLike>[]

  Uncompressed opaque binary payloads read from disk — stored raw directly after the header and readable without decompressing the body. Empty array if none. Lazily decoded, zero-copy.

  Returns readonly Buffer<ArrayBufferLike>[]

wouldNeedWrite

• get wouldNeedWrite(): boolean

  Check if a write is needed — either because the cache status indicates changes on disk, or because the cache configuration was modified since this session was opened.

  Equivalent to session.status !== 'upToDate' || session.configChanged.

  Returns boolean

[dispose]

• "[dispose]"(): void

  Disposable — using session = await cache.open() calls close.

  Returns void

close

• close(): void

  Release the exclusive lock and mark this session as disposed. Safe to call multiple times. If called while resolve or write is in progress, cancels the operation via the cancel flag and closes immediately.

  Returns void

resolve

• resolve(signal?: AbortSignal | null): Promise<FileHashCacheEntries>

  Resolve all file entries — complete stat + hash for every tracked file.

  After open(), some entries may be only partially resolved (CacheOpen exits early on the first change). This method completes stat + hash for ALL files, then returns a FileHashCacheEntries snapshot with per-file metadata.

  Can be called before write(). The resolved data is reused by write. Cannot be called after write() or close(). Returns cached result on subsequent calls.

  Parameters

  • Optionalsignal: AbortSignal | null

    Optional AbortSignal to cancel the resolve phase.

  Returns Promise<FileHashCacheEntries>

  Readonly snapshot of all file entries.

write

• write(options?: FileHashCacheWriteOptions | null): Promise<boolean>

  Write the cache file and release the lock.

  Can only be called once per session. After write completes (success or failure), the session is disposed and the lock is released.

  Omitted user-value fields preserve the values read from disk. Config overrides (version, fingerprint, rootPath, files) are applied to the parent FileHashCache before writing.

  Parameters

  • Optionaloptions: FileHashCacheWriteOptions | null

    Optional write options.

  Returns Promise<boolean>

  true if the write succeeded, false on lock failure.