random-access-file

A simple abstraction for random access files using the promise style in nodejs.

ranfile exposes a fairly simple, low-level class, RandomAccessFile that is intended for binary data that is frequently accessed out of order.

Install

npm install ranfile

Use/Import

nodejs

const RandomAccessFile = require('ranfile')

Module API

Classes:

• RandomAccessFile : class – a convenience class for working with random access files.

Functions:

• .create(name)
• .open(name, writable)

.create(name)

Creates the specified file and opens it for random access.

Note that newly created files are opened in writable node.

arguments:

• name : string, required – the file's fully quailified name

returns:

• a Promise that is resolved with an instance of RandomAccessFile opened on the newly created file.

example:

const RandomAccessFile = require('ranfile')

RandomAccessFile.create('/home/me/temp/my-test-file')
  .then(file => {
    // file is open, do with it what you will.
  });

.open(name, writable)

Opens the specified, existing file.

arguments:

• name : string, required – the file's fully quailified name
• writable : boolean, optional – indicates whether the file is opened for writing. Default: false

returns:

• a Promise that is resolved with an instance of RandomAccessFile opened on the specified file.

example:

const RandomAccessFile = require('ranfile')

RandomAccessFile.open('/home/me/temp/my-test-file', true)
  .then(file => {
    // file is open, do with it what you will.
  });

RandomAccessFile Class

A convenience class for working with random access files.

properties:

• .descriptor : object – the file's opaque file descriptor.
• .name : string – the file's name.
• .size : number – the file's size in bytes.
• .writable : boolean – indicates whether the file was opened in a writable mode.

methods:

.read(offset, length)

Reads the specified number of bytes from the file, starting at the specified offset.

arguments:

• offset : number, required – the byte offset where reading will begin.
• length : number, required – then number of bytes to read.

result:

• A Promise that is resolved with a Buffer containing bytes read from the file.

example:

// ... assuming you've got a file...

file.read(100, 100)
  .then(data => {
    // data is a buffer with the second 100 bytes.
  });

.write(offset, data, first, length)

Writes the specified bytes to the file beginning at the specified offset.

arguments:

• offset : number, required – the byte offset where writing will begin.
• data : Buffer, required – a Buffer containing the bytes that will be written.
• first : number, optional – the first byte that will be written from the specified data.
• length : number, optional – then number of bytes to write from the specified data.

result:

• A Promise that is resolved with the offset of the byte following the last byte written

example:

// ... assuming you've got a file...

// overwrite the second 100 bytes...
const data = new Buffer(100, 'binary');
file.write(100, data)
  .then(next => {
    // next will equal 200, which is the offset to the byte that follows the
    // last byte written... if we're conducting successive writes at the end
    // of the file then this also equals the size of the file.
  });

.sync()

Synchronizes the underlying storage device by writing through the disk cache if such is present.

result:

• A Promise that is resolved when the file has been flushed.

.truncate(length)

Truncates the underlying file to precisely the length specified (bytes).

arguments:

• length : number, required – the length of the resulting file.

result:

• A Promise that is resolved when the file has been truncated.

.close()

Closes the file.

result:

• A Promise that is resolved when the file has been closed.

License

MIT