{"id":49045,"library":"random-access-storage","title":"random-access-storage","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/random-access-storage/random-access-storage","tags":["javascript"],"install":[{"cmd":"npm install random-access-storage","lang":"bash","label":"npm"},{"cmd":"yarn add random-access-storage","lang":"bash","label":"yarn"},{"cmd":"pnpm add random-access-storage","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Default export is the constructor. CJS require gives the default directly.","wrong":"const RandomAccessStorage = require('random-access-storage').RandomAccessStorage","symbol":"RandomAccessStorage","correct":"import RandomAccessStorage from 'random-access-storage'"},{"note":"CJS default export, not named.","wrong":"const { RandomAccessStorage } = require('random-access-storage')","symbol":"RandomAccessStorage","correct":"const RandomAccessStorage = require('random-access-storage')"},{"note":"TypeScript: use default import for type, or use namespace import for type-level access.","wrong":"import { RandomAccessStorage } from 'random-access-storage'","symbol":"RandomAccessStorage","correct":"type RandomAccessStorage = typeof import('random-access-storage')"}],"quickstart":{"code":"import RandomAccessStorage from 'random-access-storage'\nimport fs from 'fs'\n\nconst storage = new RandomAccessStorage({\n  open(req) {\n    fs.open('test.txt', 'r', (err, fd) => {\n      if (err) req.callback(err)\n      else { this._fd = fd; req.callback(null) }\n    })\n  },\n  read(req) {\n    const buf = Buffer.alloc(req.size)\n    fs.read(this._fd, buf, 0, req.size, req.offset, (err, bytes) => {\n      if (err) req.callback(err)\n      else if (bytes < req.size) req.callback(new Error('partial read'))\n      else req.callback(null, buf)\n    })\n  },\n  close(req) {\n    if (this._fd) fs.close(this._fd, () => req.callback(null))\n    else req.callback(null)\n  }\n})\n\nstorage.read(0, 10, (err, buf) => {\n  if (err) console.error(err)\n  else console.log(buf.toString())\n  storage.close()\n})","lang":"typescript","description":"Creates a file-backed RandomAccessStorage with open/read/close lifecycle, reads first 10 bytes, logs result, then closes."},"warnings":[{"fix":"Migrate listeners from storage.on('ready') to storage.on('open') or use storage.opened property.","message":"Version 3.0 removed the 'ready' event and replaced it with 'open'.","severity":"breaking","affected_versions":"2.x"},{"fix":"Update callback handlers to accept (err, result) only.","message":"Version 3.0 changed callback signatures: read/write/del now pass (err, result) instead of (err, result, ...additional args).","severity":"breaking","affected_versions":"2.x"},{"fix":"Ensure req.callback is called exactly once per operation.","message":"Do not call req.callback multiple times; it will cause unexpected behavior or crashes.","severity":"gotcha","affected_versions":">=3.0"},{"fix":"Use 'createAlways: true' in options instead of 'create: true'.","message":"The 'create' option in old versions is replaced by 'createAlways' in v3.","severity":"deprecated","affected_versions":"2.x"},{"fix":"Implement at least one of _read or _write before using the storage.","message":"If neither read nor write is implemented, the storage will throw on usage.","severity":"gotcha","affected_versions":">=3.0"},{"fix":"No fix needed, but be aware that automatic open may cause order-of-operations issues if you rely on synchronous setup.","message":"Storage.open() is automatically called on first read/write/del; calling it manually is optional but safe.","severity":"gotcha","affected_versions":">=3.0"}],"env_vars":null,"search_vec":"'3.0.2':20 'abstract':13,45 'access':3,11,54 'activ':79 'automat':58 'backend':27 'base':5 'build':65 'class':6 'cleanup':62 'common':23 'compli':73 'consist':49 'contract':50 'control':35 'current':16 'custom':66 'direct':40 'driver':68 'ecosystem':77 'enforc':47 'error':37 'file':69 'flow':34 'frequent':81 'fs':42 'handl':38,57 'hypercor':76 'implement':8 'interfac':24 'javascript':83 'lifecycl':33 'maintain':78 'manag':31 'memori':70 'network':71 'node.js':15 'open':59 'open/close':32 'oper':30 'pattern':55 'provid':21 'random':2,10,53 'random-access':52 'random-access-storag':1,9 'read/write/del':29 'releas':82 'stabl':17 'storag':4,12,26,67 'stream':44 'suspens':60 'unlik':39 'use':41,63 'version':18","created_at":"2026-06-07T16:59:46.109166+00:00","updated_at":"2026-06-07T16:59:46.109166+00:00","problems":[{"fix":"Use const RandomAccessStorage = require('random-access-storage') (no destructuring).","cause":"Importing a named export instead of default when using CJS require.","error":"TypeError: RandomAccessStorage is not a constructor"},{"fix":"Call req.callback(null, Buffer.alloc(req.size)) or ensure buffer length matches req.size.","cause":"In read implementation, req.callback() called with too few arguments or wrong buffer size.","error":"Error: Could not read at fileReader.read (test.js:xx)"},{"fix":"Use regular functions or bind correctly: open: function (req) { ... }","cause":"Using an arrow function for _open/_read/etc. that does not capture `this` correctly, or passing a wrong callback.","error":"TypeError: req.callback is not a function"},{"fix":"Check storage.closed before operations, or ensure close only after all operations.","cause":"Attempting to read/write after storage.close() has been called.","error":"Error: Storage is already closed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/random-access-storage/random-access-storage","github":"https://github.com/random-access-storage/random-access-storage","docs":null,"changelog":null,"pypi":null,"npm":"random-access-storage","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}