strong-tie/inbound-calls
0
1# sonic-boom2 3[](https://www.npmjs.com/package/sonic-boom)4[](https://github.com/pinojs/sonic-boom/actions?query=workflow%3ACI)5[](https://standardjs.com/)6 7Extremely fast utf8-only stream implementation to write to files and8file descriptors.9 10This implementation is partial, but support backpressure and `.pipe()` in is here.11However, it is 2-3x faster than Node Core `fs.createWriteStream()`:12 13```14benchSonic*1000: 1916.904ms15benchSonicSync*1000: 8605.265ms16benchSonic4k*1000: 1965.231ms17benchSonicSync4k*1000: 1588.224ms18benchCore*1000: 5851.959ms19benchConsole*1000: 7605.713ms20```21 22Note that sync mode without buffering is _slower_ than a Node Core WritableStream, however23this mode matches the expected behavior of `console.log()`.24 25Note that if this is used to log to a windows terminal (`cmd.exe` or26powershell), it is needed to run `chcp 65001` in the terminal to27correctly display utf-8 characters, see28[chcp](https://ss64.com/nt/chcp.html) for more details.29 30## Install31 32```33npm i sonic-boom34```35 36## Example37 38```js39'use strict'40 41const SonicBoom = require('sonic-boom')42const sonic = new SonicBoom({ fd: process.stdout.fd }) // or { dest: '/path/to/destination' }43 44for (let i = 0; i < 10; i++) {45 sonic.write('hello sonic\n')46}47```48 49## API50 51### SonicBoom(opts)52 53Creates a new instance of SonicBoom.54 55The options are:56 57* `fd`: a file descriptor, something that is returned by `fs.open` or58 `fs.openSync`.59* `dest`: a string that is a path to a file to be written to (mode controlled by the `append` option).60* `minLength`: the minimum length of the internal buffer that is61 required to be full before flushing.62* `maxLength`: the maximum length of the internal buffer. If a write operation would cause the buffer63 to exceed `maxLength`, the data written is dropped and a `drop` event is emitted with the dropped data64* `maxWrite`: the maximum number of bytes that can be written; default: 1638465* `periodicFlush`: calls `flush` every x`ms`.66* `sync`: perform writes synchronously (similar to `console.log`).67* `fsync`: perform a [fsyncSync](https://nodejs.org/api/fs.html#fsfsyncsyncfd) every time a write is completed.68* `append`: appends writes to dest file instead of truncating it (default `true`).69* `mode`: specify the creating file `mode` (see [fs.open()](https://nodejs.org/api/fs.html#fsopenpath-flags-mode-callback) from Node.js core).70* `mkdir`: ensure directory for dest file exists when `true` (default `false`).71* `retryEAGAIN(err, writeBufferLen, remainingBufferLen)`: a function that will be called when sonic-boom72 write/writeSync/flushSync encounters a EAGAIN or EBUSY error. If the return value is73 true sonic-boom will retry the operation, otherwise it will bubble the74 error. `err` is the error that caused this function to be called,75 `writeBufferLen` is the length of the buffer sonic-boom tried to write, and76 `remainingBufferLen` is the length of the remaining buffer sonic-boom didn't try to write.77 78For `sync:false` a `SonicBoom` instance will emit the `'ready'` event when a file descriptor is available.79For `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.80 81 82### SonicBoom#write(string)83 84Writes the string to the file.85It will return false to signal the producer to slow down.86 87### SonicBoom#flush([cb])88 89Writes the current buffer to the file if a write was not in progress.90Do nothing if `minLength` is zero or if it is already writing.91 92call the callback when the flush operation is completed. when failed the callback is called with an error.93 94### SonicBoom#reopen([file])95 96Reopen the file in place, useful for log rotation.97 98Example:99 100```js101const stream = new SonicBoom('./my.log')102process.on('SIGUSR2', function () {103 stream.reopen()104})105```106 107### SonicBoom#flushSync()108 109Flushes the buffered data synchronously. This is a costly operation.110 111### SonicBoom#end()112 113Closes the stream, the data will be flushed down asynchronously114 115### SonicBoom#destroy()116 117Closes the stream immediately, the data is not flushed.118 119### Events120 121 122#### SonicBoom#close123 124See [Stream#close](https://nodejs.org/api/stream.html#event-close). The `'close'` event when the instance has been closed.125 126#### SonicBoom#drain127 128See [Stream#drain](https://nodejs.org/api/stream.html#event-drain). The `'drain'` event is emitted when source can resume sending data.129 130#### SonicBoom#drop <any>131 132When destination file maximal length is reached, the `'drop'` event is emitted with data that could not be written. 133 134#### SonicBoom#error <Error>135 136The `'error'` event is emitted when the destination file can not be opened, or written.137 138#### SonicBoom#finish139 140See [Stream#finish](https://nodejs.org/api/stream.html#event-finish). The `'finish'` event after calling `end()` method and when all data was written.141 142#### SonicBoom#ready143 144The `'ready'` event occurs when the created instance is ready to process input.145 146#### SonicBoom#write <number>147 148The `'write'` event occurs every time data is written to the underlying file. It emits the number of written bytes.149 150## License151 152MIT153