What does the cafsLocker variable do in the PNPM cafs code (internals)?

[lancejpollard]

How does the cafsLocker variable work in the PNPM cafs internal code? What is it used for, what features does it manage, and generally what is it solving?

ChatGPT gives a brief glimpse at what the cafsLocker does, but could you go into slightly more depth and breadth of an explanation on how it works?

The type is like this:

export type CafsLocker = Map<string, number>

What is the key and value? I am having a bit of difficulty tracing how it's being used in the codebase, could use some insight :)

I also see this:

export function writeBufferToCafs (
  locker: Map<string, number>,
  cafsDir: string,
  buffer: Buffer,
  fileDest: string,
  mode: number | undefined,
  integrity: ssri.IntegrityLike
): { checkedAt: number, filePath: string } {
  fileDest = path.join(cafsDir, fileDest)
  if (locker.has(fileDest)) {
    return {
      checkedAt: locker.get(fileDest)!,
      filePath: fileDest,
    }
  }
  // This part is a bit redundant.
  // When a file is already used by another package,
  // we probably have validated its content already.
  // However, there is no way to find which package index file references
  // the given file. So we should revalidate the content of the file again.
  if (existsSame(fileDest, integrity)) {
    return {
      checkedAt: Date.now(),
      filePath: fileDest,
    }
  }

  // This might be too cautious.
  // The write is atomic, so in case pnpm crashes, no broken file
  // will be added to the store.
  // It might be a redundant step though, as we verify the contents of the
  // files before linking
  //
  // If we don't allow --no-verify-store-integrity then we probably can write
  // to the final file directly.
  const temp = pathTemp(fileDest)
  writeFile(temp, buffer, mode)
  // Unfortunately, "birth time" (time of file creation) is available not on all filesystems.
  // We log the creation time ourselves and save it in the package index file.
  // Having this information allows us to skip content checks for files that were not modified since "birth time".
  const birthtimeMs = Date.now()
  optimisticRenameOverwrite(temp, fileDest)
  locker.set(fileDest, birthtimeMs)
  return {
    checkedAt: birthtimeMs,
    filePath: fileDest,
  }
}

That would suggest:

• key: file path
• value: checkedAt timestamp

But given that the "locker" has a last checked at timestamp, I still don't quite follow what that is being used for... Basically, what all is happening in that writeBufferToCafs function I guess?