Binary File

Read and write to binary files in Node JS.

Important: This is an ESM NodeJS only package.

Contents

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

Installation

npm install @coderundebug/binary-file

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.

import { BinaryFileSync } from "@coderundebug/binary-file";

// Create binary file object
const binaryFile = new BinaryFileSync();

// Open the file for writing
binaryFile.openWrite('c:\\temp\\example.dat');

// Write some data to the file
binaryFile.writeUint8(0xFF);
binaryFile.writeInt32(0xABCD0123);
binaryFile.writeDouble(1234.56);

// Close the file
binaryFile.close();

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.

import { BinaryFilePromise } from "@coderundebug/binary-promise";

// Save data function
const saveData = async function () {
    // Create binary file object
    const binaryFile = new BinaryFilePromise();

    // Open the file for writing
    await binaryFile.openWrite('c:\\temp\\example.dat');

    // Write some data to the file
    await binaryFile.writeUint8(0xFF);
    await binaryFile.writeInt32(0xABCD0123);
    await binaryFile.writeDouble(1234.56);

    // Close the file
    await binaryFile.close();
};

// Save the data
await saveData();

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.

BinaryFileSyn([cacheSize=4096]);

BinaryFilePromise([cacheSize=4096]);

Arguments

• cacheSize - 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

// Create a binary file object (with default cache size)
const binaryFile = new BinaryFileSync();

// Create a binary file object (for use with promises)
const binaryFile = new BinaryFilePromise();

// Create a binary file object (with a large cache)
const binaryFile = new BinaryFileSync(248000);

// Create a binary file object (that does not use a cache buffer)
const binaryFile = new BinaryFileSync(0);

openRead

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

openRead(path);

Arguments

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

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file for reading (it must exist)
binaryFile.openRead('C:\\Temp\\example.dat');

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.

openAppend(path);

Arguments

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

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to append to
binaryFile.openAppend('C:\\Temp\\example.dat');

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.

openWrite(path);

Arguments

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

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

close

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

close();

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Write some data
binaryFile.writeDouble(101.42);

// Close the file
binaryFile.close();

path

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

path;

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Get the open file's path property
console.log('Path = ' + binaryFile.path);

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.

fd;

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Get the open file's fd value
console.log('FD = ' + binaryFile.fd);

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.

fileHandle;

Example

// Create a binary file object
const binaryFile = new BinaryFilePromise();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Get the open file's "fileHandle" object
console.log('fileHandle = ' + binaryFile.fileHandle.toString());

position

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

position;

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Write some data and get the current position
binaryFile.writeDouble(1234.56);
console.log('Position = ' + binaryFile.position);

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.

length;

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Write some data and get the current length
binaryFile.writeDouble(1234.56);
console.log('Length = ' + binaryFile.length);

writeXXX

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

writeBuffer(data); writeInt8(data); writeInt16(data, [bigEndian=false]); writeInt32(data, [bigEndian=false]); writeInt64(data, [bigEndian=false]); writeUint8(data); writeUint16(data, [bigEndian=false]); writeUint32(data, [bigEndian=false]); writeUint64(data, [bigEndian=false]); writeDouble(data, [bigEndian=false]); writeFloat(data, [bigEndian=false]);

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 The data can be written in either little endian (the default) or big endian.

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to write to
binaryFile.openWrite('C:\\Temp\\example.dat');

// Write some data
binaryFile.writeInt32(123456);
binaryFile.writeDouble(1234.56, true);

// Create buffer
let buffer = Buffer.alloc(16);
for (let count = 0; count < 16; count++) buffer.writeUInt8(count, count);

// Write buffer
binaryFile.writeBuffer(buffer);

// Close the file
binaryFile.close();

readXXX

Reads binary data from the file. The BinaryFilePromise version will return a Promise that resolves to the data value, or null if you have reached the end of the file.

readBuffer(); readInt8(); readInt16([bigEndian=false]); readInt32([bigEndian=false]); readInt64([bigEndian=false]); readUint8(); readUint16([bigEndian=false]); readUint32([bigEndian=false]); readUint64([bigEndian=false]); readDouble([bigEndian=false]); readFloat([bigEndian=false]);

Arguments

• bigEndian The data can be read in either as little endian (the default) or big endian.

Example

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to read from
binaryFile.openRead('C:\\Temp\\example.dat');

// Read some data
let value1 = binaryFile.readInt32();
let value2 = binaryFile.readDouble(true);

// Read buffer
let buffer = binaryFile.readBuffer();

// Close the file
binaryFile.close();

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.

seek(offset, [origin=0]);

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 - 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

// Create a binary file object
const binaryFile = new BinaryFileSync();

// Open a file to read from
binaryFile.openWrite('C:\\Temp\\example.dat');

// Move to the 100th byte within the file
binaryFile.seek(100);
let value1 = binaryFile.readUint16();

// Move back 8 bytes (position was 102, now 94)
binaryFile.seek(-8, 1);
let value2 = binaryFile.readUint16();

// Move to the last but 4th byte in the file
binaryFile.seek(-4, 2);
let value3 = binaryFile.readUint16();

// Close the file
binaryFile.close();