functions/partials/cacheFiles.mjsjavascript
import { createHash, randomUUID } from 'crypto'
import { mkdir, readFile, rename, writeFile } from 'fs/promises'
import path from 'path'
import { Transform } from 'stream'

// Marks a file sent to the plugin with its cache file and its path, so its result is cached even if the plugin renames it
const cacheFile = Symbol('cacheFile')

/**
 * The cache file for a file's contents: a hash of the cache name, the fingerprint and the contents, so the same file
 * with other plugin settings or plugin versions gets a result of its own.
 * @private
 * @param {string} directory
 * @param {string} name
 * @param {string} fingerprint
 * @param {Buffer} contents
 * @returns {string}
 */
const cachePath = (directory, name, fingerprint, contents) => path.join(
  directory,
  name,
  createHash('sha256').update(name).update('\0').update(fingerprint).update('\0').update(contents).digest('hex')
)

/**
 * Write through a temporary file and rename it, so a reader (another build or test worker) never sees a half-written
 * result.
 * @private
 * @param {string} file
 * @param {Buffer} contents
 * @returns {Promise<void>}
 */
const writeAtomic = async (file, contents) => {
  await mkdir(path.dirname(file), { recursive: true })
  const temporary = `${file}.${randomUUID()}.tmp`
  await writeFile(temporary, contents)
  await rename(temporary, file)
}

/**
 * Run a gulp plugin only on files it hasn't processed before. A file whose contents (with this cache name and
 * fingerprint) were processed by an earlier run gets that run's result from the cache instead, and skips the plugin.
 * Replaces gulp-cache, which kept one cache for every process in the system's temp folder.
 *
 * A result is cached when the plugin passes on the file object it was given (as gulp plugins usually do); a plugin
 * that makes new file objects still works, its results just aren't cached. When the plugin renames a file, the cache
 * keeps the new name too (next to the result, as `<entry>.path`), so a cached file is renamed the same way. Entries
 * are never pruned: delete the directory to start over.
 * @memberOf module:partials
 * @param {stream.Transform} plugin - The gulp plugin stream to run on uncached files (e.g. imagemin()).
 * @param {Object} options
 * @param {string} options.directory - Where cached results are kept (see images.cacheDir).
 * @param {string} [options.name='default'] - The cache's folder; keeps results of different plugin settings apart.
 * @param {string} [options.fingerprint=''] - Anything else that changes the plugin's output, such as its version and
 * options: when it changes, earlier results are no longer used.
 * @returns {stream.Transform}
 */
export const cacheFiles = (plugin, { directory, name = 'default', fingerprint = '' }) => {
  const writes = []
  const pluginDone = new Promise((resolve, reject) => {
    plugin.on('end', resolve)
    plugin.on('error', reject)
  })
  // The error also reaches the stream (below); this only stops it from being reported a second time as unhandled
  pluginDone.catch(() => {})

  const stream = new Transform({
    objectMode: true,
    transform (file, encoding, callback) {
      if (!file.isBuffer()) {
        callback(null, file)
        return
      }
      const cached = cachePath(directory, name, fingerprint, file.contents)
      readFile(cached).then(
        async contents => {
          file.contents = contents
          // Written before the result, so it's there whenever the result is
          const renamed = await readFile(`${cached}.path`, 'utf8').catch(() => undefined)
          if (renamed !== undefined) {
            file.path = path.join(path.dirname(file.path), renamed)
          }
          callback(null, file)
        },
        () => {
          file[cacheFile] = { cached, from: file.path }
          plugin.write(file)
          callback()
        }
      )
    },
    flush (callback) {
      plugin.end()
      pluginDone
        .then(() => Promise.all(writes))
        .then(() => callback(), callback)
    }
  })

  plugin.on('data', file => {
    const tag = file[cacheFile]
    delete file[cacheFile]
    if (tag && file.isBuffer()) {
      const { cached, from } = tag
      const renamed = file.path === from ? Promise.resolve() : writeAtomic(`${cached}.path`, path.relative(path.dirname(from), file.path))
      // The cache only saves time: a result that can't be written is processed again next run, not a failed build
      writes.push(renamed.then(() => writeAtomic(cached, file.contents)).catch(() => {}))
    }
    stream.push(file)
  })
  plugin.on('error', error => stream.destroy(error))

  return stream
}