Note that sync mode without buffering is slower than a Node Core WritableStream, however
this mode matches the expected behavior of console.log().
Note that if this is used to log to a windows terminal (cmd.exe or
powershell), it is needed to run chcp 65001 in the terminal to
correctly display utf-8 characters, see
chcp for more details.
Install
npm i sonic-boom
Example
'use strict'const SonicBoom = require('sonic-boom')const sonic = new SonicBoom({ fd: process.stdout.fd }) // or { dest: '/path/to/destination' }for (let i = 0; i < 10; i++) { sonic.write('hello sonic\n')}
API
SonicBoom(opts)
Creates a new instance of SonicBoom.
The options are:
fd: a file descriptor, something that is returned by fs.open or
fs.openSync.
dest: a string that is a path to a file to be written to (mode controlled by the append option).
minLength: the minimum length of the internal buffer that is
required to be full before flushing.
maxLength: the maximum length of the internal buffer. If a write operation would cause the buffer
to exceed maxLength, the data written is dropped and a drop event is emitted with the dropped data
maxWrite: the maximum number of bytes that can be written; default: 16384
periodicFlush: calls flush every xms.
sync: perform writes synchronously (similar to console.log).
fsync: perform a fsyncSync every time a write is completed.
append: appends writes to dest file instead of truncating it (default true).
mode: specify the creating file mode (see fs.open() from Node.js core).
contentMode: which type of data you can send to the write function, supported values are or . (default )
For sync:false a SonicBoom instance will emit the 'ready' event when a file descriptor is available.
For sync:true this is not relevant because the 'ready' event will be fired when the SonicBoom instance is created, before it can be subscribed to.
SonicBoom#write(string)
Writes the string to the file.
It will return false to signal the producer to slow down.
SonicBoom#flush([cb])
Writes the current buffer to the file. If a write is already in progress,
the buffered data is written after it completes.
The callback is called once all pending writes have completed and the file
has been fsynced (unless the fsync option is set). fsync errors meaning the
file descriptor cannot be synchronized, such as a pipe or TTY, are ignored.
If the flush fails, or the stream is destroyed before the data is flushed,
the callback is called with an error. end() waits for pending flushes
before closing the stream.
SonicBoom#reopen([file])
Reopen the file in place, useful for log rotation.
Example:
const stream = new SonicBoom({ dest: './my.log' })process.on('SIGUSR2', function () { stream.reopen()})
SonicBoom#flushSync()
Flushes the buffered data synchronously. This is a costly operation.
If an asynchronous write is in flight when flushSync() is called, only the
data queued after it is written, and it may reach the file before the data
of the in-flight write.
SonicBoom#end()
Closes the stream, the data will be flushed down asynchronously
SonicBoom#destroy()
Closes the stream immediately, the data is not flushed.
If the file is still being opened, the stream is marked as destroyed right
away (so write() and end() throw) and is closed once the file is open.
A pending flush() then fails with an 'error' event.
Events
SonicBoom#close
See Stream#close. The 'close' event when the instance has been closed.
SonicBoom#drain
See Stream#drain. The 'drain' event is emitted when source can resume sending data.
SonicBoom#drop
When destination file maximal length is reached, the 'drop' event is emitted with data that could not be written.
SonicBoom#error
The 'error' event is emitted when the destination file can not be opened, or written.
SonicBoom#finish
See Stream#finish. The 'finish' event after calling end() method and when all data was written.
SonicBoom#ready
The 'ready' event occurs when the created instance is ready to process input.
SonicBoom#write
The 'write' event occurs every time data is written to the underlying file. It emits the number of written bytes.
License
MIT
jsumners
james.sumners@gmail.com
utf8
buffer
utf8
mkdir: ensure directory for dest file exists when true (default false).
retryEAGAIN(err, writeBufferLen, remainingBufferLen): a function that will be called when sonic-boom
write/writeSync/flushSync encounters a EAGAIN or EBUSY error. If the return value is
true sonic-boom will retry the operation, otherwise it will bubble the
error. err is the error that caused this function to be called,
writeBufferLen is the length of the buffer sonic-boom tried to write, and
remainingBufferLen is the length of the remaining buffer sonic-boom didn't try to write.
maxWriteRetries: the maximum number of consecutive EAGAIN/EBUSY retries
(across write, writeSync and flushSync) sonic-boom will attempt
before giving up and emitting/throwing the error, instead of retrying
forever. The counter resets on every successful write. Default: 0
(no limit - preserves the previous unbounded-retry behavior). Set this if
the destination can become permanently unwritable (e.g. a reader that
stops draining a pipe), to avoid unbounded growth of the internal write
buffer while retries are silently attempted forever - see
#65.