# random-access-file

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

Latest version **4.1.2** (published 2024-12-20) · MIT license · 0 weekly downloads

## Install

```sh
npm install random-access-file
pnpm add random-access-file
yarn add random-access-file
bun add random-access-file
```

## Health

**Score 33/100 (F)** — status: maintenance-mode.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.1.2 |
| Published | 2024-12-20 |
| First published | 2013-02-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/random-access-file) |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 9.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 154 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/random-access-file
- Repository: https://github.com/random-access-storage/random-access-file
- Issues: https://github.com/random-access-storage/random-access-file/issues
- npm.io page: https://npm.io/package/random-access-file

## Dependencies (3)

- [bare-fs](https://npm.io/package/bare-fs.md) ^4.0.1
- [bare-path](https://npm.io/package/bare-path.md) ^3.0.0
- [random-access-storage](https://npm.io/package/random-access-storage.md) ^3.0.0

## Recent versions

- 4.1.2 (latest) — 2024-12-20
- 4.1.1 — 2024-11-12
- 4.1.0 — 2024-10-15
- 4.0.7 — 2024-02-09
- 4.0.6 — 2024-02-02
- 4.0.5 — 2024-02-02
- 4.0.4 — 2023-06-08
- 4.0.3 — 2023-05-30
- 4.0.2 — 2023-05-22
- 4.0.1 — 2023-05-22
- 4.0.0 — 2022-09-14
- 3.2.2 — 2022-08-19
- 3.2.1 — 2022-08-19
- 3.2.0 — 2022-08-19
- 3.1.0 — 2022-08-01
- … 38 more at https://npm.io/package/random-access-file/versions

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

---
_Source: https://npm.io/package/random-access-file · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._