Ranfile NPM | npm.io

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)

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.
  });