Installation

Contents

• Introduction
• constructor
• openRead
• openAppend
• openWrite
• close
• path
• fd
• fileHandle
• position
• length
• writeXXX
• readXXX
• seek

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.

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

openRead

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

openAppend

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

openWrite

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

fd

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

fileHandle

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

writeXXX

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

readXXX

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