# random-access-storage

> Easily make random-access-storage instances

Latest version **3.0.2** (published 2024-02-07) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 23/100 (F)** — status: abandoned.

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.2 |
| Published | 2024-02-07 |
| First published | 2018-02-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/random-access-storage) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 16 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 78 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

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

## Dependencies (2)

- [queue-tick](https://npm.io/package/queue-tick.md) ^1.0.0
- [bare-events](https://npm.io/package/bare-events.md) ^2.2.0

## Recent versions

- 3.0.2 (latest) — 2024-02-07
- 3.0.1 — 2023-06-27
- 3.0.0 — 2022-09-14
- 2.3.0 — 2022-09-12
- 2.2.1 — 2022-08-19
- 2.2.0 — 2022-08-17
- 2.1.0 — 2022-07-07
- 2.0.1 — 2022-06-27
- 2.0.0 — 2022-06-27
- 1.4.3 — 2022-02-10
- 1.4.2 — 2021-11-04
- 1.4.1 — 2020-02-28
- 1.4.0 — 2019-06-12
- 1.3.0 — 2018-06-21
- 1.2.0 — 2018-05-02
- … 4 more at https://npm.io/package/random-access-storage/versions

## README

# random-access-storage

Easily make random-access-storage instances

```
npm install random-access-storage
```

A random-access-storage instance is a common interface for a storage abstraction, that provides the following core api.

* `read(offset, size)` - Read a buffer at a custom offset.
* `write(offset, data)` - Write a buffer to a custom offset.
* `del(offset, size)` - Delete data at a custom offset.

This module exposes a base class that implements most of the plumbing and flow you'd usually want to implement when making one.

## Usage

``` js
const RandomAccessStorage = require('random-access-storage')
const fs = require('fs')

const file = fileReader('index.js')

file.read(0, 10, (err, buf) => console.log('0-10: ' + buf.toString()))
file.read(40, 15, (err, buf) => console.log('40-55: ' + buf.toString()))
file.close()

function fileReader (name) {
  let fd = 0
  return new RandomAccessStorage({
    open: function (req) {
      // called once automatically before the first read call
      fs.open(name, 'r', function (err, res) {
        if (err) return req.callback(err)
        fd = res
        req.callback(null)
      })
    },
    read: function (req) {
      const buf = Buffer.allocUnsafe(req.size)
      fs.read(fd, buf, 0, buf.length, req.offset, function (err, read) {
        if (err) return req.callback(err)
        if (read < buf.length) return req.callback(new Error('Could not read'))
        req.callback(null, buf)
      })
    },
    close: function (req) {
      if (!fd) return req.callback(null)
      fs.close(fd, err => req.callback(err))
    }
  })
}
```

## API

#### `const storage = new RandomAccessStorage([options])`

Make a new instance. Options include:

``` js
{
  createAlways: false, // always create storage on first open
  open: fn, // sets ._open
  read: fn, // sets ._read
  write: fn, // sets ._write
  del: fn, // sets ._del
  truncate: fn, // sets ._truncate
  stat: fn, // sets ._stat
  suspend: fn, // sets ._suspend
  close: fn, // sets ._close
  unlink: fn // sets ._unlink
}
```

#### `storage.readable`

True if the storage implements `._read`.

#### `storage.writable`

True if the storage implements `._write`.

#### `storage.deletable`

True if the storage implements `._del`.

#### `storage.truncatable`

True if the storage implements `._truncate`.

#### `storage.statable`

True if the storage implements `._stat`.

#### `storage.opened`

True if the storage has been fully opened.

#### `storage.closed`

True if the storage has been fully closed.

#### `storage.unlinked`

True if the storage has been fully unlinked.

#### `storage.writing`

True if the storage is currently being written to.

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

Emitted when the storage is fully open.

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

Emitted when the storage is fully closed.

#### `storage.on('unlink')`

Emitted when the storage is fully unlinked.

#### `storage.on('suspend')`

Emitted when the storage is fully suspended

#### `storage.on('unsuspend')`

Emitted when the storage comes out of suspension.

#### `storage.open(cb)`

Explicitly open the storage. If you do not call this yourself,
it will automatically called before any read/write/del/stat operation.

It is safe to call this more than once.

Triggers *one* call to `_open` if you implement that.

#### `storage._open(req)`

Implement storage open.

* `req.create` is `true` if the storage should be created.

Call `req.callback` when it is fully opened.

#### `storage.read(offset, size, callback)`

Read the specified bytes from the storage at the specified byte offset.
Calls the callback with a `(err, buffer)`.

#### `storage._read(req)`

Implement storage read.

* `req.offset` contains the byte offset you should read at.
* `req.size` contains the amount of bytes you should read.

Call `req.callback(err, buffer)` when the read is completed.

Note that this is guaranteed to run after the storage has been opened and not after it has been closed.

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

Write the specified buffer to the specified byte offset. Optionally pass a callback that is called with `(err)` when the write has completed.

#### `storage._write(req)`

Implement storage write.

* `req.offset` contains the byte offset you should write at.
* `req.data` contains the buffer you should write.

Call `req.callback(err)` when the write is completed.

Note that this is guaranteed to run after the storage has been opened and not after it has been closed.

#### `storage.del(offset, size, [callback])`

Delete the specified amount of bytes at the specified offset. Optionally pass a callback that is called with `(err)` when the delete has completed.

#### `storage._del(req)`

Implement storage delete.

* `req.offset` contains the byte offset to delete at.
* `req.size` contains the amount of bytes to delete.

Call `req.callback(err)` when the delete has completed.

Note that this is guaranteed to run after the storage has been opened and not after it has been closed.

#### `storage.truncate(offset, [callback])`

Truncate the storage at the specified offset. Optionally pass a callback that is called with `(err)` when the truncate has completed.

#### `storage._truncate(req)`

Implement storage truncate. Defaults to `storage._del(req)`.

* `req.offset` contains the byte offset to truncate at.

Call `req.callback(err)` when the truncate has completed.

Note that this is guaranteed to run after the storage has been opened and not after it has been closed.

#### `storage.stat(callback)`

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

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

#### `storage._stat(req)`

Implement storage stat.

Call `req.callback(err, statObject)` when the stat has completed.

Note that this is guaranteed to run after the storage has been opened and not after it has been closed.

#### `storage.suspend([callback])`

Suspend (temporarily close) the storage instance.

#### `storage._suspend(req)`

Implement storage suspend. Defaults to calling `_close`.

Optionally implement this to add a way for your storage instance to temporarily free resources.

Call `req.callback(err)` when the storage has been fully suspended.

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

Close the storage instance.

#### `storage._close(req)`

Implement storage close.

Call `req.callback(err)` when the storage is fully closed.

Note this is guaranteed to run after all pending read/write/stat/del operations has finished and no methods will run after.

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

Unlink the storage instance, removing all underlying data.

#### `storage._unlink(req)`

Implement storage unlink.

Call `req.callback(err)` when the storage has been fully unlinked.

Note this is guaranteed to run after `.close()` has been called and no methods will be run after.

## License

MIT

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