DOCSEARCHbyAlgolia
Submit Docs

sonic-boom

repository·master·Indexed 43 days ago

https://github.com/pinojs/sonic-boom

An extremely fast, UTF-8 only stream implementation for high-performance writing to files and file descriptors, optimized to be significantly faster than Node.js core fs.createWriteStream(). Version 5.0.1 provides features such as synchronous writes, periodic flushing, and log rotation support via the reopen() method.

Tokens
2.5K
Snippets
10
Records
18
Agent score
6%

What's inside sonic-boom

  2. Handle SonicBoom events

    master

    SonicBoom is an EventEmitter and emits several useful events:

    • 'ready': Emitted when the file descriptor is open and ready for writing. (Note: In sync: true mode, this is emitted via process.nextTick).
    • 'error': Emitted when an error occurs during file opening or writing.
    • 'write': Emitted when a write operation completes, with the number of bytes written as the argument.
    • 'drain': Emitted when the internal buffer is cleared and it is safe to write more data.
    • 'drop': Emitted when data is dropped because maxLength was exceeded.
    • 'finish': Emitted after end() is called and all buffered data has been successfully written.
    • 'close': Emitted when the file descriptor is closed.

  3. Configure SonicBoom options

    master

    When creating a new SonicBoom instance, you can pass an options object to control buffering, synchronization, and file handling behavior.

    Available Options

    OptionDescription
    fdA file descriptor (e.g., from fs.open).
    destA string path to a file.
    minLengthMinimum internal buffer length required before flushing.
    maxLengthMaximum internal buffer length. If exceeded, data is dropped and a 'drop' event is emitted.
    maxWriteMaximum number of bytes that can be written (default: 16384).
    periodicFlushCalls flush every x ms.
    syncPerform writes synchronously (similar to console.log).
    fsyncPerform an fsyncSync every time a write is completed.
    appendAppends to dest instead of truncating (default: true).
    modeSpecify the creating file mode (Node.js fs.open style).
    contentModeType of data for write(): 'utf8' or 'buffer' (default: 'utf8').
    mkdirEnsure directory for dest exists (default: false).
    retryEAGAINFunction (err, writeBufferLen, remainingBufferLen) => boolean called on EAGAIN or EBUSY errors. Return true to retry.
    maxWriteRetriesMax consecutive EAGAIN/EBUSY retries before giving up (default: 0, which is unbounded).

  4. Basic usage of SonicBoom

    master

    To use SonicBoom, instantiate it with either a file descriptor (fd) or a destination path (dest). You can then use the .write() method to send strings to the stream.

    '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')
}

  5. SonicBoom Events

    master

    SonicBoom emits several events for lifecycle and error management:

    • 'close': Emitted when the instance has been closed.
    • 'drain': Emitted when the source can resume sending data.
    • 'drop' <any>: Emitted with the dropped data when the destination file reaches maxLength.
    • 'error' <Error>: Emitted when the destination file cannot be opened or written.
    • 'finish': Emitted after calling .end() and all data has been written.
    • 'ready': Occurs when the instance is ready to process input. (For sync: false, this is emitted when a file descriptor is available. For sync: true, it fires immediately upon creation).
    • 'write' <number>: Emitted every time data is written, emitting the number of bytes written.

  6. Initialize SonicBoom for high-performance writing

    master

    The SonicBoom class is used for high-performance UTF-8 stream writing to files or file descriptors. You can initialize it by passing a file path (string) or a file descriptor (number) in the options object.

    Key configuration options:

    • dest or fd: The file path (string) or file descriptor (number) to write to.
    • sync: Boolean. If true, uses synchronous file operations. Note that in sync mode, ready and error events are emitted via process.nextTick.
    • append: Boolean (default true). If true, opens the file in append mode (a); otherwise, write mode (w).
    • mkdir: Boolean (default false). If true, creates the directory for the file if it doesn't exist.
    • minLength: Number. The minimum amount of data to buffer before triggering a write.
    • maxLength: Number. The maximum amount of data to buffer before dropping new writes (emits drop event).
    • maxWrite: Number (default 16384). The maximum size of a single write operation.
    • periodicFlush: Number. Interval in milliseconds to automatically call flush().
    • contentMode: 'utf8' or 'buffer'. Use 'buffer' to write raw Buffers directly, avoiding string conversion overhead.
    • fsync: Boolean. If true, calls fsync after writes.
    const SonicBoom = require('sonic-boom');

// Writing to a file with directory creation and append mode
const sonic = new SonicBoom({ dest: './logs/app.log', mkdir: true, append: true });

// Writing to a file descriptor
const sonicFd = new SonicBoom({ fd: 1 });

  10. SonicBoom#flush([cb])

    master
    Writes the current buffer to the file if a write is not currently in progress. Does nothing if minLength is zero or if it is already writing. The callback cb is called when the flush operation completes or fails with an error.