steno

What is steno?

The steno npm package is a simple, fast, and lightweight library for writing JSON files atomically. It ensures that data is written to disk safely and without corruption, making it ideal for applications that need to frequently update JSON files.

What are steno's main functionalities?

Atomic Write

This feature allows you to write JSON data to a file atomically. The `writeFile` method ensures that the data is written safely, preventing file corruption.

const steno = require('steno');
const fs = require('fs');

const data = { key: 'value' };

steno.writeFile('data.json', JSON.stringify(data), (err) => {
  if (err) throw err;
  console.log('Data written successfully');
});

Synchronous Write

This feature allows you to write JSON data to a file synchronously. The `writeFileSync` method ensures that the data is written safely and the operation is completed before moving on to the next line of code.

const steno = require('steno');
const fs = require('fs');

const data = { key: 'value' };

try {
  steno.writeFileSync('data.json', JSON.stringify(data));
  console.log('Data written successfully');
} catch (err) {
  console.error('Error writing data:', err);
}

Other packages similar to steno

write-file-atomic

The write-file-atomic package provides similar functionality to steno by ensuring that files are written atomically. It is designed to handle the same use cases, such as preventing file corruption during write operations. However, write-file-atomic offers more configuration options and is more widely used in the community.

fs-extra

The fs-extra package extends the native Node.js fs module with additional methods, including atomic write operations. While it offers a broader range of file system utilities compared to steno, it is also heavier and includes more features than just atomic writes.

README

steno

Super fast and safe non-blocking file writer for Node

var steno = require('steno')
steno('file.txt').write('data')

Example

If you need to write to file, you either use writeFileSync or writeFile. The first is blocking and the second doesn't prevent race condition.

For example:

// Very slow but file's content will always be 10000
for (var i = 0; i < 10000; i++) {
  fs.writeFileSync('file.txt', i)
}

// Very fast but file's content may be 5896, 2563, 9856, ...
for (var i = 0; i < 10000; i++) {
  fs.writeFile('file.txt', i, function() {})
}

With steno:

// Very fast and file's content will always be 10000
for (var i = 0; i < 10000; i++) {
  steno('file.txt').write(i)
}

Race condition is prevented and it runs in 2ms versus ~5500ms with fs.writeFileSync.

How it works

steno('file.txt').write('A') // starts writing A to file
steno('file.txt').write('B') // still writing A, B is buffered
steno('file.txt').write('C') // still writing A, B is replaced by C
                             // ...
                             // A has been written to file
                             // starts writting C (B has been skipped)

When file is being written, data is stored in memory and flushed to disk as soon as possible. Please note also that steno skips intermediate data (B in this example).

Methods

steno(filename)

Returns writer for filename.

writer.write(data, [cb])

Writes data to file. If file is already being written, data is buffered until it can be written. An optional callback can also be set to be notified when data has been written to disk.

writer.setCallback(cb)

Sets a writer level callback that is called only after file has been written. Useful for creating atomic writers, logging, delaying, ...

var atomicWriter = steno('tmp-file.txt').setCallback(function(err, data, next) {
  if (err) throw err
  fs.rename('tmp-file.txt', 'file.txt', function(err) {
    if (err) throw err
    next()
  })
})

atomicWriter.write('Hello world')

License

MIT - Typicode