write-file-atomic

What is write-file-atomic?

The write-file-atomic npm package is designed to write files to disk atomically, meaning that it ensures that the file contents are either fully written or not written at all, preventing partial writes that can occur in crash scenarios. It also allows for setting file mode and ownership atomically with the file write.

What are write-file-atomic's main functionalities?

Atomic file writing

This feature ensures that the file is either completely written or not written at all, which is useful for preventing data corruption during write operations.

const writeFileAtomic = require('write-file-atomic');
writeFileAtomic('message.txt', 'Hello, World!', function (err) {
  if (err) throw err;
  console.log('The file has been saved!');
});

Setting file mode

This feature allows the user to set the file mode (permissions) at the time of writing the file atomically.

const writeFileAtomic = require('write-file-atomic');
writeFileAtomic('message.txt', 'Hello, World!', { mode: 0o755 }, function (err) {
  if (err) throw err;
  console.log('The file has been saved with the specified mode!');
});

Setting file ownership

This feature allows the user to set the file ownership (user ID and group ID) atomically with the file write operation.

const writeFileAtomic = require('write-file-atomic');
writeFileAtomic('message.txt', 'Hello, World!', { chown: { uid: 1000, gid: 50 } }, function (err) {
  if (err) throw err;
  console.log('The file has been saved with the specified ownership!');
});

Other packages similar to write-file-atomic

fs-extra

fs-extra is a package that builds on the native fs module, providing additional methods and ensuring compatibility across different platforms. It includes methods for atomic file writing, but also offers a wide range of other file system operations, making it more extensive than write-file-atomic.

graceful-fs

graceful-fs is a drop-in replacement for the fs module that makes file system operations more robust by queuing them and retrying on failure. It does not specifically focus on atomic writes, but it enhances the overall reliability of file system interactions.

atomic-write

atomic-write is a minimalistic module that provides atomic file writing capabilities. It is similar to write-file-atomic but with a smaller feature set and API surface area, focusing solely on the atomicity of the write operation.

README

write-file-atomic

This is an extension for node's fs.writeFile that makes its operation atomic allows you to include uid/gid for the final file as well. It does this by initially writing to a temporary file (your filename, followed by ".writeFile.atomic"), chowning it to the uid and gid you specified (if you specified any) and finally renames it to your filename.

var writeFileAtomic = require('write-file-atomic')
writeFileAtomic(filename, data, [options], callback)

• filename String
• data String | Buffer
• options Object
  • chown Object
    • uid Number
    • gid Number
  • encoding String | Null default = 'utf8'
  • mode Number default = 438 (aka 0666 in Octal) callback Function

Atomically and asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer.

If provided, the chown option requires both uid and gid properties or else you'll get an error.

The encoding option is ignored if data is a buffer. It defaults to 'utf8'.

Example:

writeFileAtomic('message.txt', 'Hello Node', {chown:{uid:100,gid:50}}, function (err) {
  if (err) throw err;
  console.log('It\'s saved!');
});

var writeFileAtomicSync = require('write-file-atomic').sync
writeFileAtomicSync(filename, data, [options])

The synchronous version of writeFileAtomic.