iso-kv

library3.2.0jsnpmunverified

Isomorphic key-value storage library for JavaScript and TypeScript, supporting multiple backends including in-memory, localStorage, IndexedDB, and more. Current stable version is 3.2.0, with regular releases. It provides a unified API across Node.js, browsers, and other runtimes. Key differentiator: pluggable backend system and full TypeScript support out of the box, unlike simpler abstraction libraries.

storage

npm install iso-kv

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ISO-KV

iso-kv

storagejavascriptv3.2.0

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.

MemoryBlockstore

✓ import { MemoryBlockstore } from 'iso-kv'

✗ const MemoryBlockstore = require('iso-kv').MemoryBlockstore

ESM-only, no CommonJS support. Use named import.

createStore

✓ import { createStore } from 'iso-kv'

Default export is not available; use named import.

Store

✓ import type { Store } from 'iso-kv'

✗ import { Store } from 'iso-kv'

Store is a type-only export. Use 'import type' in TypeScript.

Demonstrates creating a store with MemoryBlockstore backend, putting a block, and getting it back by CID.

import { createStore, MemoryBlockstore } from 'iso-kv'; import { CID } from 'multiformats/cid'; async function main() { const store = createStore({ backend: new MemoryBlockstore() }); await store.put(new TextEncoder().encode('hello'), { cid: CID.parse('bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuyl1ab5ugxofdw') }); const block = await store.get(CID.parse('bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuyl1ab5ugxofdw')); console.log(new TextDecoder().decode(block.bytes)); } main().catch(console.error);

Debug

Known issues

breakingVersion 3.x drops support for Node.js < 16 and requires ESM.

fix

Use Node.js >=16 and ensure your project is configured for ESM (type: module in package.json or use .mjs files).

affects: >=3.0.0

deprecatedThe 'level' backend was removed in v3.

fix

Use 'fs' backend or a custom backend instead.

affects: >=3.0.0

gotchaBackend must be provided explicitly; no default backend.

fix

Always pass a backend instance to createStore().

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: store.put is not a function

Incorrect import of createStore, which returns an object with methods like put/get, but some users destructure incorrectly.

fix

Ensure you call createStore() and use the returned object. Example: const store = createStore({...}); await store.put(...);

ERR_REQUIRE_ESM from 'iso-kv'

Attempting to use CommonJS require() with ESM-only package.

fix

Convert to ESM imports. Use 'import' statements and ensure your package.json has 'type': 'module' or rename .js files to .mjs.

TypeError: Cannot read properties of undefined (reading 'bytes')

The get method returns a block with bytes, but if the CID is not found, it returns undefined. Not checking result.

fix

Check if get() returns a value before accessing .bytes. Example: const block = await store.get(cid); if (block) { console.log(block.bytes); }

Upgrade

Version history

3.2.0latest on npm

Audit

Dependencies

interface-storerequiredRequired for store interface compatibility

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/hugomrdias/iso-repo/tree/master/packages/iso-kv ↗

packageiso-kv ↗

homepagehttps://github.com/hugomrdias/iso-repo/tree/master/packages/iso-kv ↗