https://github.com/random-access-storage/random-access-file

Continuous reading or writing to a file using random offsets and lengths
https://github.com/random-access-storage/random-access-file

Last synced: 3 months ago
JSON representation

Continuous reading or writing to a file using random offsets and lengths

• Host: GitHub
• URL: https://github.com/random-access-storage/random-access-file
• Owner: random-access-storage
• Created: 2013-07-10T20:13:08.000Z (over 11 years ago)
• Default Branch: master
• Last Pushed: 2024-10-15T09:01:35.000Z (3 months ago)
• Last Synced: 2024-10-29T21:10:27.030Z (3 months ago)
• Language: JavaScript
• Size: 79.1 KB
• Stars: 153
• Watchers: 4
• Forks: 26
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome-dat - random-access-file - continuous reading / writing to files using random offset and lengths (Dat Core Modules / Storage)

README

        
# random-access-file

Continuous reading or writing to a file using random offsets and lengths

```

npm install random-access-file

```

## Why?

If you are receiving a file in multiple pieces in a distributed system it can be useful to write these pieces to disk one by one in various places throughout the file without having to open and close a file descriptor all the time.

random-access-file allows you to do just this.

## Usage

``` js

const RandomAccessFile = require('random-access-file')

const file = new RandomAccessFile('my-file.txt')

file.write(10, Buffer.from('hello'), function(err) {

  // write a buffer to offset 10

  file.read(10, 5, function(err, buffer) {

    console.log(buffer) // read 5 bytes from offset 10

    file.close(function() {

      console.log('file is closed')

    })

  })

})

```

file will use an open file descriptor. When you are done with the file you should call `file.close()`.

## API

#### `const file = new RandomAccessFile(filename, [options])`

Create a new file. Options include:

``` js

{

  truncate: false, // truncate the file before reading / writing

  size: someSize, // truncate the file to this size first

  readable: true, // should the file be opened as readable?

  writable: true,  // should the file be opened as writable?

  lock: false, // lock the file

  sparse: false // mark the file as sparse

}

```

#### `file.write(offset, buffer, [callback])`

Write a buffer at a specific offset.

#### `file.read(offset, length, callback)`

Read a buffer at a specific offset. Callback is called with the buffer read.

#### `file.del(offset, length, callback)`

Delete a portion of the file. Any partial file blocks in the deleted portion are zeroed and, if the file is sparse, the remaining file blocks unlinked in-place.

#### `file.truncate(offset, callback)`

Truncate the file length to this offset.

#### `file.stat(callback)`

Stat the storage. Should return an object with useful information about the underlying storage, including:

```js

{

  size: number // how many bytes of data is stored?

}

```

#### `file.close([callback])`

Close the underlying file descriptor.

#### `file.unlink([callback])`

Unlink the underlying file.

#### `file.on('open')`

Emitted when the file descriptor has been opened. You can access the fd using `file.fd`.

You do not need to wait for this event before doing any reads/writes.

#### `file.on('close')`

Emitted when the file has been closed.

## License

MIT