Function writeFileAtomic

src/utils/atomic-write.ts:37–75

(
  filePath: string,
  data: string | Uint8Array,
  opts: AtomicWriteOptions = {},
)

 * the temp file is cleaned up and the original target is left untouched.
 */
export async function writeFileAtomic(
  filePath: string,
  data: string | Uint8Array,
  opts: AtomicWriteOptions = {},
): Promise<void> {
  const dir = path.dirname(filePath);
  const tmp = path.join(dir, `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${seq++}`);
  const mode = opts.mode ?? 0o644;

  let fh: fs.FileHandle | undefined;
  try {
    // 'wx' → O_CREAT|O_EXCL: the temp name is unique, so this never clobbers.
    fh = await fs.open(tmp, 'wx', mode);
    await fh.writeFile(data, { encoding: opts.encoding ?? 'utf-8' });
    await fh.sync(); // flush contents to disk before the rename
    await fh.close();
    fh = undefined;

    await fs.rename(tmp, filePath); // atomic replace

    if (opts.fsyncDir !== false) {
      // Make the directory entry (the rename) durable. Not supported on every
      // platform/fs — best-effort, never fatal.
      let dh: fs.FileHandle | undefined;
      try {
        dh = await fs.open(dir, 'r');
        await dh.sync();
      } catch {
        /* directory fsync unsupported here — acceptable */
      } finally {
        await dh?.close().catch(() => {});
      }
    }
  } catch (err) {
    if (fh) await fh.close().catch(() => {});
    await fs.unlink(tmp).catch(() => {}); // don't leave a turd behind
    throw err;
  }
}