buffered-file-reader

A promise-based buffered reader for sequential byte-wise binary file input.

NPM package: buffered-file-reader Examples of how to use it: github.com/chdh/buffered-file-reader/tree/main/examples

Concept

"Locate mode" is used to access data within the internal data buffer.

Locate mode is a very old concept which was was common in IBM mainframes with PL/I. It's used to avoid copying file data and to allow fast byte-wise inspection of the data stream.

With the "view" functionality of the Node.js Buffer and JavaScript TypedArray classes, it's now possible to use this concept in a modern programming environment.

API

Reader.open()

static Reader.open(fileName: string, options?: OpenOptions) : Promise<Reader>

Opens a file and returns a Reader object.

• fileName: The name of a file to read from.
• options: Optional options (see below).
• Return value: A new Reader object.

interface OpenOptions {
  bufferSize?:         number; // size of the internal data buffer, default is to use 256 KB
  preallocatedBuffer?: Buffer; // a pre-allocated buffer to be re-used instead of using bufferSize to allocate a new buffer
}

reader.close()

reader.close() : Promise<void>

Closes the Reader object and the underlying file handle.

reader.get()

reader.get(length: number) : Promise<Buffer|undefined>

Returns a view into the internal data buffer at the current file position.

• length: Specifies the number of bytes requested. If the end of the file is encountered or if there is not enough space in the internal buffer, a shorter view is returned. If more data is available in the internal data buffer, which is normally the case, a longer view is returned. For optimal performance, length should be much smaller than the size of the internal data buffer.
• Return value: A Buffer object whis is a view into the internal data buffer at the current position. If the current file position is at the end of the file and no more data is available, undefined is returned.

The current file position is not advanced.

reader.advance()

reader.advance(length: number)

Advances the current file position.

reader.filePosition

reader.filePosition : number

Returns the current file position.

Example

import {Reader} from "buffered-file-reader";

const reader = await Reader.open("test.txt");

let buf = await reader.get(4);
console.log("First 4 bytes: ", buf.subarray(0, 4));
console.log("Available bytes in the buffer view: ", buf.length);

reader.advance(100);

buf = await reader.get(1);
console.log("Byte at position 100: ", buf[0]);

await reader.close();