subleveldown

What is subleveldown?

The subleveldown package is a tool for creating sublevel partitions within a LevelDB database. It allows you to organize your data into separate namespaces, making it easier to manage and query specific subsets of your data.

What are subleveldown's main functionalities?

Creating Sublevels

This feature allows you to create a sublevel within a LevelDB database. By using subleveldown, you can partition your database into different namespaces, which helps in organizing and managing data more effectively. The code sample demonstrates how to create a sublevel and store a key-value pair in it.

const level = require('level');
const subleveldown = require('subleveldown');

const db = level('./mydb');
const subdb = subleveldown(db, 'sublevel1');

subdb.put('key', 'value', function (err) {
  if (err) return console.log('Ooops!', err);
  console.log('Value stored in sublevel1');
});

Accessing Sublevels

This feature allows you to access data stored in a specific sublevel. The code sample shows how to retrieve a value from a sublevel using the get method.

subdb.get('key', function (err, value) {
  if (err) return console.log('Ooops!', err);
  console.log('Value:', value);
});

Iterating Over Sublevels

This feature allows you to iterate over all key-value pairs in a sublevel. The code sample demonstrates how to use a read stream to access each entry in the sublevel.

subdb.createReadStream()
  .on('data', function (data) {
    console.log(data.key, '=', data.value);
  })
  .on('error', function (err) {
    console.log('Error:', err);
  })
  .on('end', function () {
    console.log('Stream ended');
  });

Other packages similar to subleveldown

level-sublevel

The level-sublevel package provides similar functionality by allowing you to create sublevels within a LevelDB database. It offers a more integrated approach with LevelDB, but subleveldown is often preferred for its simplicity and ease of use.

levelup

Levelup is a higher-level interface for LevelDB that provides a more user-friendly API. While it doesn't directly offer sublevel functionality, it can be used in conjunction with subleveldown to manage sublevels within a LevelDB database.

README

subleveldown

Split a levelup database into sublevels with their own keyspace, encoding and events.

Table of Contents

Click to expand

• Usage
• Background
• API
  • subdb = sub(db[, prefix][, options])
• Install
• Contributing
• Donate
• License

Usage

If you are upgrading: please see UPGRADING.md.

const sub = require('subleveldown')
const level = require('level')

const db = level('db')
const example = sub(db, 'example')
const nested = sub(example, 'nested')

The example and nested db's are just regular levelup instances:

example.put('hello', 'world', function () {
  nested.put('hi', 'welt', function () {
    // Prints { key: 'hi', value: 'welt' }
    nested.createReadStream().on('data', console.log)
  })
})

Or with promises and iterators:

await example.put('hello', 'world')
await nested.put('hi', 'welt')

for await (const [key, value] of nested.iterator()) {
  // Prints ['hi', 'welt']
  console.log([key, value])
}

Sublevels see their own keys as well as keys of any nested sublevels:

// Prints:
// { key: '!nested!hi', value: 'welt' }
// { key: 'hello', value: 'world' }
example.createReadStream().on('data', console.log)

They also support db.clear() which is very useful to empty a bucket of stuff:

example.clear(function (err) {})

// Or delete a range within `example`
example.clear({ gt: 'hello' }, function (err) {})

// With promises
await example.clear()

Background

subleveldown separates a levelup database into sections - or sublevels from here on out. Think SQL tables, but evented, ranged and realtime!

Each sublevel is a levelup of its own. This means it has the exact same interface as its parent database, but its own keyspace and events. In addition, sublevels are individually wrapped with encoding-down, giving us per-sublevel encodings. For example, it's possible to have one sublevel with Buffer keys and another with 'utf8' encoded keys. The same goes for values. Like so:

sub(db, 'one', { valueEncoding: 'json' })
sub(db, 'two', { keyEncoding: 'binary' })

There is one limitation, however: keys must encode to either strings or Buffers. This is not likely to affect you, unless you use custom encodings or the id encoding (which bypasses encodings and thus makes it your responsibility to ensure keys are either strings or Buffers). If in that case you do pass in a key that is not a string or Buffer, it will be irreversibly converted to a string.

Authored by @mafintosh and inspired by level-sublevel by @dominictarr, subleveldown has become an official part of Level. As level-sublevel is no longer under active development, we recommend switching to subleveldown to get the latest and greatest of the Level ecosystem. These two modules largely offer the same functionality, except for hooks and per-batch prefixes.

API

subdb = sub(db[, prefix][, options])

Returns a levelup instance that uses subleveldown to prefix the keys of the underlying store of db. The required db parameter must be a levelup instance. Any layers that this instance may have (like encoding-down or subleveldown itself) are peeled off to get to the innermost abstract-leveldown compliant store (like leveldown). This ensures there is no double encoding step.

The prefix must be a string. If omitted, the effective prefix is two separators, e.g. '!!'. If db is already a subleveldown-powered instance, the effective prefix is a combined prefix, e.g. '!one!!two!'.

The optional options parameter has the following subleveldown specific properties:

• separator (string, default: '!') Character for separating sublevel prefixes from user keys and each other. Must sort before characters used in prefixes. An error will be thrown if that's not the case.
• open (function) Optional open hook called when the underlying levelup instance has been opened. The hook receives a callback which must be called to finish opening.

Any other options are passed along to the underlying levelup and encoding-down constructors. See their documentation for further details.

Install

With npm do:

npm i subleveldown -S

Contributing

Level/subleveldown is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the Contribution Guide for more details.

Donate

Support us with a monthly donation on Open Collective and help us continue our work.

License

MIT

Changelog

[6.0.1] - 2021-10-02

Fixed

• Bump levelup to fix API parity with abstract-leveldown (bd73ace) (Vincent Weevers).