Class OPFSMetadataManager

constructor

• new OPFSMetadataManager(): OPFSMetadataManager

  Returns OPFSMetadataManager

parseFailures

orphansRemoved

load

• load(root: FileSystemDirectoryHandle): Promise<LoadOutcome | null>

  Read and parse _cache_meta.json. Returns null on cold start (file missing). On parse failure, returns a fresh snapshot with needsOrphanCleanup = true and increments parseFailures — caller should run cleanupOrphans to reclaim stray files.

  Parameters

  • root: FileSystemDirectoryHandle

  Returns Promise<LoadOutcome | null>

scheduleSave

• scheduleSave(
      params: {
          root: FileSystemDirectoryHandle;
          getSnapshot: () => MetadataSnapshot;
          delayMs: number;
          onError: (error: unknown) => void;
      },
  ): void

  Schedule a debounced metadata save. Replaces any previously- scheduled save (last writer wins on the timer). When the timer fires, getSnapshot is called to produce the latest state and the file is written; failures invoke onError.

  Parameters

  • params: {
        root: FileSystemDirectoryHandle;
        getSnapshot: () => MetadataSnapshot;
        delayMs: number;
        onError: (error: unknown) => void;
    }

  Returns void

hasPendingSave

• hasPendingSave(): boolean

  True if a debounced save is queued and has not yet fired.

  Returns boolean

cancelPendingSave

• cancelPendingSave(): void

  Cancel the debounced timer without running its action. Caller is responsible for any final synchronous save (typically only useful during dispose, paired with a direct save() call).

  Returns void

awaitInFlight

• awaitInFlight(): Promise<void>

  Await any save started by the timer; no-op if none.

  Returns Promise<void>

save

• save(root: FileSystemDirectoryHandle, snapshot: MetadataSnapshot): Promise<void>

  Synchronously write the snapshot to disk. Used by dispose for the final flush; swallows + logs errors so dispose never throws.

  Parameters

  • root: FileSystemDirectoryHandle
  • snapshot: MetadataSnapshot

  Returns Promise<void>

cleanupOrphans

• cleanupOrphans(
      root: FileSystemDirectoryHandle,
      expectedFileNames: Set<string>,
      shouldStop?: () => boolean,
  ): Promise<void>

  Reclaim OPFS files that exist on disk but have no entry in the provided expected set. Called from OPFSStore.init() after a metadata-parse failure; safe to skip otherwise (the cache rebuilds itself in seconds and orphans are bounded by quota).

  Increments orphansRemoved per file actually deleted.

  shouldStop is re-polled across the crawl's awaits; when it turns true (the owning store was disposed) the crawl halts before its next delete, so a stale expected-set can never keep reclaiming files a newer same-URL store is concurrently writing.

  Parameters

  • root: FileSystemDirectoryHandle
  • expectedFileNames: Set<string>
  • OptionalshouldStop: () => boolean

  Returns Promise<void>