Binary File
Source on GitHub

Read and write to binary files in Node JS.
IMPORTANT: This is an ESM NodeJS only package.

Installation

Introduction

Node JS has the means to read and write buffers to and from a file. You can also read and write different types of binary data to and from a buffer, like unsigned 16 bit integers.

This library combines both these into a single class that allows you to read and write binary data to and from a file in a simple way.

It comes in two classes, BinaryFilePromise for when you want to use async/await and BinaryFileSync if you prefer not to use promises. It also uses a data cache to improve performance.

This example uses the synchronous class version. It opens the file and writes an UINT8 (unsigned 8 bit integer), then an INT32 (signed 32 bit integer), and then writes a double (64 bit floating point number), and then finishes things off by closing the file.

This next example uses the asynchronous promise class version. It does the same things as before but it uses promises.

Binary File

Constructor

Creates a new instance of the BinaryFileSync or BinaryFilePromise object.

Arguments

  • [cacheSize=4069] - The size of the internal buffer cache. The cache is used to group data that is written into a buffer and only writes it to the file when it is full. It is also used when reading, putting a block of file data into the buffer so that it doesn't need to read the file for each read function called. The smallest this can be is 8 bytes, but you can set it to zero to turn off caching. The upper limit is 1MB. The default size is 4096 bytes.

Example


Open Read

Opens a file for reading. If the file does not exist then an exception is thrown. The BinaryFilePromise version will return a Promise.

Arguments

  • path - The full path of the file to open.

Example


Open Append

Opens a file for writing additional data to. If the file does not exist then the file is created. The file is not truncated if it already exists. The BinaryFilePromise version will return a Promise.

Arguments

  • path - The full path of the file to open.

Example


Open Write

Opens a file for writing data to. If the file does not exist then the file is created. If the file does already exist then it is truncated (emptied). The BinaryFilePromise version will return a Promise.

Arguments

  • path - The full path of the file to open.

Example


Close

Closes a file that is currently open. The BinaryFilePromise version will return a Promise.

Example


Path

After the file has been opened, you can get the full path of the file that was used to open it.

Example


File Descriptor

After the file has been opened, you can get file descriptor value, which you can use to perform any additional tasks with the node FS functions.

Example


File Handle

After a file has been opened, you can get the file handle class object, which you can use to call a number of additional functions. This is only used with the BinaryFilePromise class version.

Example


Position

This property is used to get the current read or write position within the file.

Example


Length

After the file has been opened, you can get the length of the file. If you are writing to the file then this value will be updated to give the current size of the file.

Example


Write

Writes binary data to the file. The BinaryFilePromise version will return a Promise.

Arguments

  • data - The data to write to the file. This is a Number type except for writeBuffer (which is a Buffer object), and the functions writeInt64 and writeUint64 (which require a BigInt).
  • [bigEndian=false] - The data can be written in either little endian (the default) or big endian.

Example


Read

Writes binary data to the file. The BinaryFilePromise version will return a Promise.

Arguments

  • [bigEndian=false] - The data can be read in either as little endian (the default) or big endian.

Example


Seek

Moves the current position to read or write from to a different location within the file. This allows you to move to different positions within the file whenever you want. However, please note, doing this will force the cache to be re-read or flushed, so do not use it too much as it will impact performance. The BinaryFilePromise version will return a Promise.

Arguments

  • offset - The offset from the origin location. By default this will be the offset from the start of the file. The value can be negative.
  • [origin=0] - The origin setting to control how the offset is used. This can be 0 = From Start of File, 1 = From Current Position or 2 = From End of File.

Example