Registry / storage / random-access-storage

random-access-storage

library3.0.2jsnpmunverified

Base class for implementing random-access-storage abstractions in Node.js. Current stable version is 3.0.2. Provides a common interface for storage backends with read/write/del operations, managing open/close lifecycle, flow control, and error handling. Unlike directly using fs or streaming abstractions, it enforces a consistent contract for random-access patterns and handles automatic opening, suspension, and cleanup. Useful for building custom storage drivers (file, memory, network) that comply with the Hypercore ecosystem. Maintained actively with frequent releases.

storage

npm install random-access-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RANDOM-ACCESS-STOR

random-access-storage

storagejavascriptv3.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RandomAccessStorage

✓ import RandomAccessStorage from 'random-access-storage'

✗ const RandomAccessStorage = require('random-access-storage').RandomAccessStorage

Default export is the constructor. CJS require gives the default directly.

RandomAccessStorage

✓ const RandomAccessStorage = require('random-access-storage')

✗ const { RandomAccessStorage } = require('random-access-storage')

CJS default export, not named.

RandomAccessStorage

✓ type RandomAccessStorage = typeof import('random-access-storage')

✗ import { RandomAccessStorage } from 'random-access-storage'

TypeScript: use default import for type, or use namespace import for type-level access.

Creates a file-backed RandomAccessStorage with open/read/close lifecycle, reads first 10 bytes, logs result, then closes.

import RandomAccessStorage from 'random-access-storage' import fs from 'fs' const storage = new RandomAccessStorage({ open(req) { fs.open('test.txt', 'r', (err, fd) => { if (err) req.callback(err) else { this._fd = fd; req.callback(null) } }) }, read(req) { const buf = Buffer.alloc(req.size) fs.read(this._fd, buf, 0, req.size, req.offset, (err, bytes) => { if (err) req.callback(err) else if (bytes < req.size) req.callback(new Error('partial read')) else req.callback(null, buf) }) }, close(req) { if (this._fd) fs.close(this._fd, () => req.callback(null)) else req.callback(null) } }) storage.read(0, 10, (err, buf) => { if (err) console.error(err) else console.log(buf.toString()) storage.close() })

Debug

Known issues

breakingVersion 3.0 removed the 'ready' event and replaced it with 'open'.

fix

Migrate listeners from storage.on('ready') to storage.on('open') or use storage.opened property.

affects: 2.x

breakingVersion 3.0 changed callback signatures: read/write/del now pass (err, result) instead of (err, result, ...additional args).

fix

Update callback handlers to accept (err, result) only.

affects: 2.x

gotchaDo not call req.callback multiple times; it will cause unexpected behavior or crashes.

fix

Ensure req.callback is called exactly once per operation.

affects: >=3.0

deprecatedThe 'create' option in old versions is replaced by 'createAlways' in v3.

fix

Use 'createAlways: true' in options instead of 'create: true'.

affects: 2.x

gotchaIf neither read nor write is implemented, the storage will throw on usage.

fix

Implement at least one of _read or _write before using the storage.

affects: >=3.0

gotchaStorage.open() is automatically called on first read/write/del; calling it manually is optional but safe.

fix

No fix needed, but be aware that automatic open may cause order-of-operations issues if you rely on synchronous setup.

affects: >=3.0

Errors

Common errors & fixes

TypeError: RandomAccessStorage is not a constructor

Importing a named export instead of default when using CJS require.

fix

Use const RandomAccessStorage = require('random-access-storage') (no destructuring).

Error: Could not read at fileReader.read (test.js:xx)

In read implementation, req.callback() called with too few arguments or wrong buffer size.

fix

Call req.callback(null, Buffer.alloc(req.size)) or ensure buffer length matches req.size.

TypeError: req.callback is not a function

Using an arrow function for _open/_read/etc. that does not capture `this` correctly, or passing a wrong callback.

fix

Use regular functions or bind correctly: open: function (req) { ... }

Error: Storage is already closed

Attempting to read/write after storage.close() has been called.

fix

Check storage.closed before operations, or ensure close only after all operations.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/random-access-storage/random-access-storage ↗

packagerandom-access-storage ↗

homepagehttps://github.com/random-access-storage/random-access-storage ↗