Registry / storage / random-access-idb

random-access-idb

library1.2.2jsnpmunverified

random-access-idb is a browser-side storage library that implements the abstract-random-access interface using IndexedDB. Version 1.2.2 is the latest stable release. It provides a simple, file-like API for reading and writing binary data in the browser, with support for random access by offset. Unlike localStorage or other key-value stores, it is designed for use with libraries that expect a random-access storage backend, such as hypercore or dat. The library is lightweight and has no dependencies beyond the browser's IndexedDB API. It follows the random-access pattern where you open a database and then create named 'files' within it, each supporting read, write, and (optionally) del and stat operations. However, note that version 1.x does not support deletion or truncation, and changing the internal chunk size after writing data will corrupt existing data.

storage

npm install random-access-idb

package ↗

INSTALL

IMPORT

SIG · RANDOM-ACCESS-IDB

random-access-idb

storagejavascriptv1.2.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.

randomAccessIdb

✓ import randomAccessIdb from 'random-access-idb'

✗ const randomAccessIdb = require('random-access-idb')

The package is ESM-only. In Node.js, use dynamic import or a build tool. In the browser, use a bundler.

randomAccessIdb

✓ const randomAccessIdb = require('random-access-idb')

✗ import { randomAccessIdb } from 'random-access-idb'

CommonJS require works in Node.js or bundlers. The package exposes a default export, not a named one.

Type declarations

✓ import type { RandomAccessStorage } from 'random-access-idb'

TypeScript types are not bundled. Use @types/abstract-random-access or define your own.

Opens an IndexedDB database, creates a file, writes a buffer, then reads it back.

import randomAccessIdb from 'random-access-idb'; const db = randomAccessIdb('my-database'); const file = db('my-file.txt'); // Write data at offset 0 const data = new TextEncoder().encode('Hello, world!'); file.write(0, data, (err) => { if (err) console.error(err); // Read back 5 bytes from offset 0 file.read(0, 5, (err, buf) => { if (err) console.error(err); console.log(new TextDecoder().decode(buf)); // 'Hello' }); });

Debug

Known issues

breakingInternal chunk size (opts.size) must not be changed after writing data.

fix

Always use the same opts.size for a given file name across sessions, or delete the database if size changes.

affects: >=1.0.0

gotchaDoes not support deletion (file.del) or truncation (file.truncate) in version 1.x.

fix

Use a different storage backend that supports these operations, or manage deletions manually by overwriting with zeros.

affects: >=1.0.0 <2.0.0

gotchaWrites are only flushed to IndexedDB after the write callback is called. There is no additional durability guarantee beyond what IndexedDB provides.

fix

For critical data, ensure the callback has fired before proceeding.

affects: >=1.0.0

deprecatedThe package uses 'abstract-random-access' v1 interface; newer versions of random-access libraries use v2 with different callbacks.

fix

Check the version of abstract-random-access compatibility required by your consuming library (e.g., hypercore).

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: randomAccessIdb is not a function

Incorrect import: using named import instead of default import in ESM.

fix

Use: import randomAccessIdb from 'random-access-idb'

Error: First argument must be a string or an array of strings

Passing a non-string database name to randomAccessIdb().

fix

Ensure the first argument is a string: randomAccessIdb('my-database')

DOMException: The operation failed because the requested database name could not be found.

IndexedDB database was deleted or never created, but the code expects it to exist.

fix

The library creates the database on open; no action needed unless the browser blocks IndexedDB access.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

packagerandom-access-idb ↗