What is the difference between fs.rename() and manually copying then deleting a file, particularly across different filesystems or drives?

fs.rename() performs an atomic move operation when the source and destination are on the same filesystem -- the file appears to move instantly with no window where it exists in neither location, which is important for operations that must never leave a file in a half-moved, inconsistent state. However, rename() fails with an EXDEV error when moving across different filesystems or drives (common in some cloud/container storage setups), in which case a manual copy-then-delete sequence is required instead, which is not atomic and can leave the operation partially complete if it's interrupted midway.

const fs = require('node:fs/promises');

try {
  await fs.rename('/tmp/upload.tmp', '/data/final.txt'); // atomic, if same filesystem
} catch (err) {
  if (err.code === 'EXDEV') {
    await fs.copyFile('/tmp/upload.tmp', '/data/final.txt'); // fallback: not atomic
    await fs.unlink('/tmp/upload.tmp');
  } else {
    throw err;
  }
}