From e6dfb9fe81310ccbc28425af1935c6bd918bc480 Mon Sep 17 00:00:00 2001
From: webdevelopersrinu <webdeveloper.srinu9@gmail.com>
Date: Thu, 3 Sep 2026 08:09:25 +0530
Subject: [PATCH] fs: add atomic option to writeFile

Writes go to a temp file next to the target and then get renamed
over it, so a reader never sees a half written file.

Refs: https://github.com/nodejs/node/issues/49886
Signed-off-by: webdevelopersrinu <webdeveloper.srinu9@gmail.com>
---
 doc/api/fs.md                              |  27 +++
 lib/fs.js                                  |  87 +++++++-
 lib/internal/fs/promises.js                |  37 ++++
 lib/internal/fs/utils.js                   |  29 +++
 test/parallel/test-fs-write-file-atomic.js | 243 +++++++++++++++++++++
 5 files changed, 422 insertions(+), 1 deletion(-)
 create mode 100644 test/parallel/test-fs-write-file-atomic.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 1ad902ad5fb6..bf6bd2845474 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -2287,6 +2287,9 @@ All the [caveats][] for `fs.watch()` also apply to `fsPromises.watch()`.
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65754
+    description: The `atomic` option is now supported.
   - version:
     - v21.0.0
     - v20.10.0
@@ -2318,6 +2321,12 @@ changes:
   * `flush` {boolean} If all data is successfully written to the file, and
     `flush` is `true`, `filehandle.sync()` is used to flush the data.
     **Default:** `false`.
+  * `atomic` {boolean} If `true`, the data is written to a temporary file next
+    to `file`, flushed, and then renamed over `file`. A reader sees either the
+    old data or the new data, never a half-written file. The permissions of an
+    existing `file` are kept instead of `mode`. Cannot be used with a file
+    descriptor, a {FileHandle}, or a `flag` other than `'w'`.
+    **Default:** `false`.
   * `signal` {AbortSignal} allows aborting an in-progress writeFile
 * Returns: {Promise} Fulfills with `undefined` upon success.
 
@@ -5681,6 +5690,9 @@ details.
 <!-- YAML
 added: v0.1.29
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65754
+    description: The `atomic` option is now supported.
   - version:
     - v21.0.0
     - v20.10.0
@@ -5746,6 +5758,12 @@ changes:
   * `flush` {boolean} If all data is successfully written to the file, and
     `flush` is `true`, `fs.fsync()` is used to flush the data.
     **Default:** `false`.
+  * `atomic` {boolean} If `true`, the data is written to a temporary file next
+    to `file`, flushed, and then renamed over `file`. A reader sees either the
+    old data or the new data, never a half-written file. The permissions of an
+    existing `file` are kept instead of `mode`. Cannot be used with a file
+    descriptor, a {FileHandle}, or a `flag` other than `'w'`.
+    **Default:** `false`.
   * `signal` {AbortSignal} allows aborting an in-progress writeFile
 * `callback` {Function}
   * `err` {Error|AggregateError}
@@ -7095,6 +7113,9 @@ this API: [`fs.utimes()`][].
 <!-- YAML
 added: v0.1.29
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65754
+    description: The `atomic` option is now supported.
   - version:
     - v21.0.0
     - v20.10.0
@@ -7186,6 +7207,12 @@ added:
 * `fd` {integer}
 * `buffer` {Buffer|TypedArray|DataView}
 * `options` {Object}
+  * `atomic` {boolean} If `true`, the data is written to a temporary file next
+    to `file`, flushed, and then renamed over `file`. A reader sees either the
+    old data or the new data, never a half-written file. The permissions of an
+    existing `file` are kept instead of `mode`. Cannot be used with a file
+    descriptor, a {FileHandle}, or a `flag` other than `'w'`.
+    **Default:** `false`.
   * `offset` {integer} **Default:** `0`
   * `length` {integer} **Default:** `buffer.byteLength - offset`
   * `position` {integer|null} **Default:** `null`
diff --git a/lib/fs.js b/lib/fs.js
index f974d808b826..13bf2b83fb41 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -102,6 +102,7 @@ const {
   collectRecursiveReaddirResult,
   copyObject,
   Dirent,
+  getAtomicTempPath,
   getDirents,
   getRecursiveDirents,
   getOptions,
@@ -118,6 +119,7 @@ const {
   stringToFlags,
   stringToSymlinkType,
   toUnixTimestamp,
+  validateAtomicWrite,
   validateBufferArray,
   validateCpOptions,
   validateOffsetLengthRead,
@@ -2878,6 +2880,73 @@ function writeAll(fd, isUserFd, buffer, offset, length, signal, flush, callback)
   });
 }
 
+// Drop the temp file and report the real error. If unlink also fails, ignore it.
+function abandonAtomicWrite(tmp, err, callback) {
+  fs.unlink(tmp, () => callback(err));
+}
+
+function writeFileAtomic(path, data, options, callback) {
+  const tmp = getAtomicTempPath(path);
+  // Keep the old permissions, or mode would widen them on every write.
+  fs.stat(path, (statErr, stats) => {
+    const mode = stats === undefined ? options.mode : stats.mode & 0o777;
+    // 'wx' so we never reuse a temp file someone left behind.
+    fs.open(tmp, 'wx', mode, (openErr, fd) => {
+      if (openErr) {
+        callback(openErr);
+        return;
+      }
+      // writeAll closes the fd. Always flush, or a crash can leave half a file.
+      writeAll(fd, false, data, 0, data.byteLength, options.signal, true, (writeErr) => {
+        if (writeErr) {
+          abandonAtomicWrite(tmp, writeErr, callback);
+          return;
+        }
+        fs.rename(tmp, path, (renameErr) => {
+          if (renameErr) {
+            abandonAtomicWrite(tmp, renameErr, callback);
+            return;
+          }
+          callback(null);
+        });
+      });
+    });
+  });
+}
+
+function writeFileAtomicSync(path, data, options) {
+  const tmp = getAtomicTempPath(path);
+  // Keep the old permissions, or mode would widen them on every write.
+  const stats = fs.statSync(path, { throwIfNoEntry: false });
+  const mode = stats === undefined ? options.mode : stats.mode & 0o777;
+  let fd;
+  try {
+    fd = fs.openSync(tmp, 'wx', mode);
+    try {
+      let offset = 0;
+      let length = data.byteLength;
+      while (length > 0) {
+        const written = fs.writeSync(fd, data, offset, length);
+        offset += written;
+        length -= written;
+      }
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, path);
+  } catch (err) {
+    if (fd !== undefined) {
+      try {
+        fs.unlinkSync(tmp);
+      } catch {
+        // Best effort. The real error matters more.
+      }
+    }
+    throw err;
+  }
+}
+
 /**
  * Asynchronously writes data to the file.
  * @param {string | Buffer | URL | number} path
@@ -2888,6 +2957,7 @@ function writeAll(fd, isUserFd, buffer, offset, length, signal, flush, callback)
  *   flag?: string;
  *   signal?: AbortSignal;
  *   flush?: boolean;
+ *   atomic?: boolean;
  *   } | string} [options]
  * @param {(err?: Error) => any} callback
  * @returns {void}
@@ -2913,12 +2983,19 @@ function writeFile(path, data, options, callback) {
   }
 
   const flag = options.flag || 'w';
+  const atomicPath = validateAtomicWrite(options.atomic ?? false, path, flag);
 
   if (!isArrayBufferView(data)) {
     validateStringAfterArrayBufferView(data, 'data');
     data = Buffer.from(data, options.encoding || 'utf8');
   }
 
+  if (atomicPath !== null) {
+    if (checkAborted(options.signal, callback)) return;
+    writeFileAtomic(atomicPath, data, options, callback);
+    return;
+  }
+
   if (isFd(path)) {
     const isUserFd = true;
     const signal = options.signal;
@@ -2949,6 +3026,7 @@ function writeFile(path, data, options, callback) {
  *   mode?: number;
  *   flag?: string;
  *   flush?: boolean;
+ *   atomic?: boolean;
  *   } | string} [options]
  * @returns {void}
  */
@@ -2970,9 +3048,11 @@ function writeFileSync(path, data, options) {
   }
 
   const flag = options.flag || 'w';
+  const atomicPath = validateAtomicWrite(options.atomic ?? false, path, flag);
 
   // C++ fast path for string data and UTF8 encoding
-  if (typeof data === 'string' && (options.encoding === 'utf8' || options.encoding === 'utf-8')) {
+  if (atomicPath === null && typeof data === 'string' &&
+      (options.encoding === 'utf8' || options.encoding === 'utf-8')) {
     if (!isInt32(path)) {
       path = getValidatedPath(path);
     }
@@ -2990,6 +3070,11 @@ function writeFileSync(path, data, options) {
     data = Buffer.from(data, options.encoding || 'utf8');
   }
 
+  if (atomicPath !== null) {
+    writeFileAtomicSync(atomicPath, data, options);
+    return;
+  }
+
   const isUserFd = isFd(path); // File descriptor ownership
   const fd = isUserFd ? path : fs.openSync(path, flag, options.mode);
 
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index bd9fc871ce75..895ac9c088e7 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -63,6 +63,7 @@ const {
   },
   collectRecursiveReaddirResult,
   copyObject,
+  getAtomicTempPath,
   getDirents,
   getRecursiveDirents,
   getOptions,
@@ -76,6 +77,7 @@ const {
   stringToSymlinkType,
   toUnixTimestamp,
   handleErrorFromBinding: handleSyncErrorFromBinding,
+  validateAtomicWrite,
   validateBufferArray,
   validateCpOptions,
   validateOffsetLengthRead,
@@ -2085,6 +2087,37 @@ async function mkdtempDisposable(prefix, options) {
   };
 }
 
+async function writeFileAtomic(path, data, options) {
+  const tmp = getAtomicTempPath(path);
+  let mode = options.mode;
+  try {
+    // Keep the old permissions, or mode would widen them on every write.
+    mode = (await stat(path)).mode & 0o777;
+  } catch {
+    // No file there yet, so mode is fine.
+  }
+
+  // 'wx' so we never reuse a temp file someone left behind.
+  const fd = await open(tmp, 'wx', mode);
+  try {
+    try {
+      await writeFileHandle(fd, data, options.signal, options.encoding);
+      // Always flush, or a crash can leave half a file.
+      await fd.sync();
+    } finally {
+      await fd.close();
+    }
+    await rename(tmp, path);
+  } catch (err) {
+    try {
+      await unlink(tmp);
+    } catch {
+      // Best effort. The real error matters more.
+    }
+    throw err;
+  }
+}
+
 async function writeFile(path, data, options) {
   options = getOptions(options, {
     encoding: 'utf8',
@@ -2104,6 +2137,7 @@ async function writeFile(path, data, options) {
   }
 
   const flag = options.flag || 'w';
+  const atomicPath = validateAtomicWrite(options.atomic ?? false, path, flag);
 
   if (!isArrayBufferView(data) && !isCustomIterable(data)) {
     validateStringAfterArrayBufferView(data, 'data');
@@ -2116,6 +2150,9 @@ async function writeFile(path, data, options) {
 
   checkAborted(options.signal);
 
+  if (atomicPath !== null)
+    return writeFileAtomic(atomicPath, data, options);
+
   const fd = await open(path, flag, options.mode);
   let writeOp = writeFileHandle(fd, data, options.signal, options.encoding);
 
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 3aadc19c4732..8abdf69f0e79 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -1186,6 +1186,33 @@ const validatePosition = hideStackFrames((position, name, length) => {
   }
 });
 
+// Keep the temp file next to the target. rename() is only atomic on the
+// same filesystem.
+let atomicWriteCounter = 0;
+function getAtomicTempPath(path) {
+  const suffix = `.${process.pid}.${atomicWriteCounter++}.tmp`;
+  if (typeof path === 'string') {
+    return path + suffix;
+  }
+  return Buffer.concat([path, Buffer.from(suffix)]);
+}
+
+// Returns the path to write to, or null when the write is not atomic.
+const validateAtomicWrite = hideStackFrames((atomic, path, flag) => {
+  validateBoolean.withoutStackTrace(atomic, 'options.atomic');
+  if (!atomic) return null;
+  if (flag !== 'w') {
+    throw new ERR_INCOMPATIBLE_OPTION_PAIR.HideStackFramesError(
+      'options.atomic', 'options.flag');
+  }
+  // A file descriptor has no name to rename over.
+  if (typeof path === 'number') {
+    throw new ERR_INVALID_ARG_TYPE.HideStackFramesError(
+      'path', ['string', 'Buffer', 'URL'], path);
+  }
+  return getValidatedPath(path);
+});
+
 // Shared VFS handler state for fs wrapping.
 // When handlers is null, no VFS is active (zero overhead).
 const vfsState = { __proto__: null, handlers: null };
@@ -1208,6 +1235,7 @@ module.exports = {
   Dirent,
   DirentFromStats,
   getDirent,
+  getAtomicTempPath,
   getDirents,
   getOptions,
   getRecursiveDirents,
@@ -1222,6 +1250,7 @@ module.exports = {
   stringToSymlinkType,
   Stats: deprecate(Stats, 'fs.Stats constructor is deprecated.', 'DEP0180'),
   toUnixTimestamp,
+  validateAtomicWrite,
   validateBufferArray,
   validateCpOptions,
   validateOffsetLengthRead,
diff --git a/test/parallel/test-fs-write-file-atomic.js b/test/parallel/test-fs-write-file-atomic.js
new file mode 100644
index 000000000000..9b1399df1dbd
--- /dev/null
+++ b/test/parallel/test-fs-write-file-atomic.js
@@ -0,0 +1,243 @@
+'use strict';
+const common = require('../common');
+const tmpdir = require('../common/tmpdir');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const test = require('node:test');
+const data = 'foo';
+let cnt = 0;
+
+function nextFile() {
+  return tmpdir.resolve(`${cnt++}.out`);
+}
+
+// No temp file should be left behind.
+function assertNoLeftovers() {
+  const leftovers = fs.readdirSync(tmpdir.path)
+    .filter((entry) => entry.endsWith('.tmp'));
+  assert.deepStrictEqual(leftovers, []);
+}
+
+tmpdir.refresh();
+
+test('synchronous version', async (t) => {
+  await t.test('validation', (t) => {
+    for (const v of ['true', '', 0, 1, [], {}, Symbol()]) {
+      assert.throws(() => {
+        fs.writeFileSync(nextFile(), data, { atomic: v });
+      }, { code: 'ERR_INVALID_ARG_TYPE' });
+    }
+  });
+
+  await t.test('rejects a file descriptor', (t) => {
+    const file = nextFile();
+    const fd = fs.openSync(file, 'w');
+    try {
+      assert.throws(() => {
+        fs.writeFileSync(fd, data, { atomic: true });
+      }, { code: 'ERR_INVALID_ARG_TYPE' });
+    } finally {
+      fs.closeSync(fd);
+    }
+  });
+
+  await t.test('rejects a non-default flag', (t) => {
+    assert.throws(() => {
+      fs.writeFileSync(nextFile(), data, { atomic: true, flag: 'a' });
+    }, { code: 'ERR_INCOMPATIBLE_OPTION_PAIR' });
+  });
+
+  await t.test('writes via a temporary file and renames', (t) => {
+    const renameSpy = t.mock.method(fs, 'renameSync');
+    const file = nextFile();
+    fs.writeFileSync(file, data, { atomic: true });
+
+    const calls = renameSpy.mock.calls;
+    assert.strictEqual(calls.length, 1);
+    const [from, to] = calls[0].arguments;
+    assert.strictEqual(to, file);
+    assert.strictEqual(path.dirname(from), path.dirname(file));
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('flushes before renaming', (t) => {
+    const spy = t.mock.method(fs, 'fsyncSync');
+    fs.writeFileSync(nextFile(), data, { atomic: true });
+    assert.strictEqual(spy.mock.calls.length, 1);
+  });
+
+  await t.test('does not stage a temporary file when not atomic', (t) => {
+    const spy = t.mock.method(fs, 'renameSync');
+    const file = nextFile();
+    fs.writeFileSync(file, data);
+    assert.strictEqual(spy.mock.calls.length, 0);
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), data);
+  });
+
+  await t.test('leaves the original intact when the write fails', (t) => {
+    const file = nextFile();
+    fs.writeFileSync(file, 'original');
+    t.mock.method(fs, 'writeSync', () => {
+      throw new Error('boom');
+    });
+
+    assert.throws(() => {
+      fs.writeFileSync(file, data, { atomic: true });
+    }, { message: 'boom' });
+    t.mock.restoreAll();
+
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), 'original');
+    assertNoLeftovers();
+  });
+
+  await t.test('leaves the original intact when the rename fails', (t) => {
+    const file = nextFile();
+    fs.writeFileSync(file, 'original');
+    t.mock.method(fs, 'renameSync', () => {
+      throw new Error('boom');
+    });
+
+    assert.throws(() => {
+      fs.writeFileSync(file, data, { atomic: true });
+    }, { message: 'boom' });
+    t.mock.restoreAll();
+
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), 'original');
+    assertNoLeftovers();
+  });
+
+  await t.test('accepts a file URL', (t) => {
+    const file = nextFile();
+    fs.writeFileSync(pathToFileURL(file), data, { atomic: true });
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('accepts a Buffer path', (t) => {
+    const file = nextFile();
+    fs.writeFileSync(Buffer.from(file), data, { atomic: true });
+    assert.strictEqual(fs.readFileSync(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('preserves the permissions of an existing file', (t) => {
+    if (common.isWindows) {
+      return;
+    }
+    const file = nextFile();
+    fs.writeFileSync(file, 'original', { mode: 0o600 });
+    fs.writeFileSync(file, data, { atomic: true });
+    assert.strictEqual(fs.statSync(file).mode & 0o777, 0o600);
+  });
+
+  await t.test('honors mode when the file does not exist', (t) => {
+    if (common.isWindows) {
+      return;
+    }
+    const file = nextFile();
+    fs.writeFileSync(file, data, { atomic: true, mode: 0o600 });
+    assert.strictEqual(fs.statSync(file).mode & 0o777, 0o600);
+  });
+});
+
+test('callback version', async (t) => {
+  await t.test('validation', (t) => {
+    for (const v of ['true', '', 0, 1, [], {}, Symbol()]) {
+      assert.throws(() => {
+        fs.writeFile(nextFile(), data, { atomic: v }, common.mustNotCall());
+      }, { code: 'ERR_INVALID_ARG_TYPE' });
+    }
+  });
+
+  await t.test('writes via a temporary file and renames', (t, done) => {
+    const spy = t.mock.method(fs, 'rename');
+    const file = nextFile();
+    fs.writeFile(file, data, { atomic: true }, common.mustSucceed(() => {
+      assert.strictEqual(spy.mock.calls.length, 1);
+      assert.strictEqual(spy.mock.calls[0].arguments[1], file);
+      assert.strictEqual(fs.readFileSync(file, 'utf8'), data);
+      assertNoLeftovers();
+      done();
+    }));
+  });
+
+  await t.test('leaves the original intact when the rename fails', (t, done) => {
+    const file = nextFile();
+    fs.writeFileSync(file, 'original');
+    t.mock.method(fs, 'rename', (from, to, cb) => {
+      cb(new Error('boom'));
+    });
+
+    fs.writeFile(file, data, { atomic: true }, common.mustCall((err) => {
+      assert.strictEqual(err.message, 'boom');
+      t.mock.restoreAll();
+      assert.strictEqual(fs.readFileSync(file, 'utf8'), 'original');
+      assertNoLeftovers();
+      done();
+    }));
+  });
+});
+
+test('promises version', async (t) => {
+  await t.test('validation', async (t) => {
+    for (const v of ['true', '', 0, 1, [], {}, Symbol()]) {
+      await assert.rejects(
+        fsp.writeFile(nextFile(), data, { atomic: v }),
+        { code: 'ERR_INVALID_ARG_TYPE' },
+      );
+    }
+  });
+
+  await t.test('rejects a FileHandle', async (t) => {
+    const handle = await fsp.open(nextFile(), 'w');
+    try {
+      await assert.rejects(
+        fsp.writeFile(handle, data, { atomic: true }),
+        { code: 'ERR_INVALID_ARG_TYPE' },
+      );
+    } finally {
+      await handle.close();
+    }
+  });
+
+  await t.test('writes via a temporary file and renames', async (t) => {
+    const file = nextFile();
+    await fsp.writeFile(file, data, { atomic: true });
+    assert.strictEqual(await fsp.readFile(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('overwrites an existing file', async (t) => {
+    const file = nextFile();
+    await fsp.writeFile(file, 'original');
+    await fsp.writeFile(file, data, { atomic: true });
+    assert.strictEqual(await fsp.readFile(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('accepts a file URL', async (t) => {
+    const file = nextFile();
+    await fsp.writeFile(pathToFileURL(file), data, { atomic: true });
+    assert.strictEqual(await fsp.readFile(file, 'utf8'), data);
+    assertNoLeftovers();
+  });
+
+  await t.test('a reader never observes a partial write', async (t) => {
+    const file = nextFile();
+    const big = 'x'.repeat(1024 * 1024);
+    await fsp.writeFile(file, big);
+
+    const writer = fsp.writeFile(file, 'y'.repeat(1024 * 1024), { atomic: true });
+    for (let i = 0; i < 20; i++) {
+      const seen = await fsp.readFile(file, 'utf8');
+      assert.strictEqual(seen.length, big.length);
+      assert.match(seen, /^(x+|y+)$/);
+    }
+    await writer;
+    assertNoLeftovers();
+  });
+});