many-level

library2.0.0jsnpmunverified

many-level is a JavaScript library designed to share an abstract-level compatible database over network streams, acting as the spiritual successor to `multileveldown`. Currently at version 2.0.0, it allows a 'host' to expose a LevelDB-like database over any binary stream (e.g., TCP), while 'guests' can connect and interact with it as if it were a local `abstract-level` database instance. It leverages compact Protocol Buffers for efficient message encoding. The project follows a steady release cadence with significant updates marked by major version bumps addressing underlying stream mechanisms and protocol versions. A key differentiator is its optional seamless retry mechanism for guests, which helps maintain connectivity and resume operations, though it comes with a trade-off regarding snapshot guarantees. It ships with TypeScript types, providing a robust development experience.

database http-networking serialization

npm install many-level

github ↗package ↗

INSTALL

IMPORT

SIG · MANY-LEVEL

many-level

databasejavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

ManyLevelHost

✓ import { ManyLevelHost } from 'many-level'

✗ const { ManyLevelHost } = require('many-level')

While CommonJS `require` still works in Node.js, prefer ESM `import` for modern applications and consistent type inference. TypeScript users should always use `import`.

ManyLevelGuest

✓ import { ManyLevelGuest } from 'many-level'

✗ import ManyLevelGuest from 'many-level'

ManyLevelGuest is a named export, not a default export. Ensure correct destructuring.

Level

✓ import { Level } from 'level'

✗ import Level from 'level'

The `Level` class from the `level` package is commonly used with `many-level` for the host database. It's a named export.

This quickstart demonstrates setting up a `ManyLevelHost` server and connecting a `ManyLevelGuest` client, performing basic put/get/del operations, and ensuring proper shutdown.

import { ManyLevelHost, ManyLevelGuest } from 'many-level'; import { Level } from 'level'; import { pipeline } from 'readable-stream'; import { createServer, connect } from 'net'; import { rmSync } from 'fs'; // Clean up previous test database if it exists try { rmSync('./db', { recursive: true, force: true }); } catch (e) { // ignore } const dbPath = './db'; const hostDb = new Level(dbPath); const host = new ManyLevelHost(hostDb); const PORT = 9001; const server = createServer(function (socket) { pipeline(socket, host.createRpcStream(), socket, (err) => { if (err) console.error('Host pipeline error:', err.message); console.log('Host: Client disconnected.'); }); }); server.listen(PORT, async () => { console.log(`Host server listening on port ${PORT}`); const guestDb = new ManyLevelGuest(); const guestSocket = connect(PORT); pipeline(guestSocket, guestDb.createRpcStream(), guestSocket, (err) => { if (err) console.error('Guest pipeline error:', err.message); console.log('Guest: Disconnected from host.'); }); try { await guestDb.put('hello', 'world'); console.log(`Guest: Successfully put 'hello': 'world'`); const value = await guestDb.get('hello'); console.log(`Guest: Retrieved 'hello': '${value}'`); await guestDb.del('hello'); console.log(`Guest: Successfully deleted 'hello'.`); const hostValue = await hostDb.get('hello'); console.log(`Host: Value after guest operation: '${hostValue}'`); } catch (error) { console.error('Guest operation failed:', error.message); } finally { server.close(() => console.log('Host server closed.')); await hostDb.close(); console.log('Host database closed.'); try { rmSync(dbPath, { recursive: true, force: true }); console.log('Cleaned up database files.'); } catch (e) { console.warn('Failed to clean up database files:', e.message); } } });

Debug

Known issues

breakingVersion 2.0.0 replaced `duplexify` and related stream utilities with `readable-stream` v4. This is an internal change but could affect custom stream handling or integrations that relied on specific `duplexify` behaviors.

fix

Review custom stream pipelines and ensure compatibility with `readable-stream` v4 if directly interacting with `many-level`'s internal streams beyond `createRpcStream()`.

affects: >=2.0.0

breakingUpgrading from `multileveldown` to `many-level` (version 1.0.0+) requires significant changes as `many-level` is a complete successor, not a drop-in replacement. The API surface, particularly around stream creation and options, has changed.

fix

Consult the `UPGRADING.md` guide in the `many-level` repository for a detailed migration path from `multileveldown`.

affects: >=1.0.0

gotchaUsing the `retry: true` option for `ManyLevelGuest` enables seamless reconnection but disables snapshot guarantees for iterators. New iterators will be created upon reconnect, meaning `db.supports.snapshots` will be `false`.

fix

Understand the trade-off between seamless retry and snapshot consistency. If snapshot guarantees are critical for your application, avoid `retry: true` and implement manual reconnection logic or handle potential iterator failures.

affects: >=1.0.0

breakingThe internal `protocol-buffers` dependency was bumped from v4 to v5 in v2.0.0. While typically an internal concern, this could subtly affect wire compatibility or performance characteristics if you are interacting with the raw protocol buffer messages.

fix

Ensure all `many-level` instances (host and guest) are on compatible versions to avoid protocol mismatch issues. Upgrade clients and servers in tandem.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Not found

A `get` operation was attempted for a key that does not exist in the underlying LevelDB instance, or the connection to the host was interrupted.

fix

Ensure the key exists before attempting to retrieve it, or implement error handling for `NotFound` errors. Verify network connectivity between guest and host.

TypeError: db.createRpcStream is not a function

Attempting to call `createRpcStream()` on an object that is not a `ManyLevelHost` or `ManyLevelGuest` instance, or before the object is properly initialized.

fix

Ensure you are calling `createRpcStream()` on an instance created with `new ManyLevelHost(db)` or `new ManyLevelGuest()`. Double-check import paths and object instantiation.

Error: write after end

Attempting to write data to a stream that has already been closed or ended, typically due to a broken or closed network connection.

fix

Implement robust error handling for stream pipelines, ensuring that operations are only attempted on active connections. The quickstart example demonstrates basic pipeline error handling.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

readable-streamrequiredCore internal dependency for stream handling, particularly in v2.0.0+ where it replaced `duplexify`.

protocol-buffersrequiredUsed internally for efficient encoding and decoding of database operations over the network.

abstract-leveloptionalProvides the interface contract for both host and guest database instances, though not a direct npm dependency of `many-level` itself, it defines the expected API.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Level/many-level ↗

packagehttps://www.npmjs.com/package/many-level ↗