subleveldown

subleveldown

Sublevels on top of levelup with different encodings for each sublevel.

Table of Contents

Click to expand

• Usage
• Background
• API
• Install
• License

Usage

If you are upgrading: please see UPGRADING.md.

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

var db = level('db')

var test = sub(db, 'test') // test is just a regular levelup
var test2 = sub(db, 'test2')
var nested = sub(test, 'nested')

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

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).

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. Should be outside the character (or byte) range of user keys.
• 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

License

MIT © 2014-present Mathias Buus and contributors. See the included LICENSE file for more details.

Changelog

[3.0.0-rc1] - 2018-06-03

Changed

• Upgrade levelup from ^1.2.1 to ^3.0.1 (@ralphtheninja)
• Upgrade abstract-leveldown from ^2.4.1 to ^5.0.0 (@ralphtheninja)
• Upgrade memdown devDependency from ^1.1.0 to ^3.0.0 (@ralphtheninja)
• Upgrade tape devDependency from ^4.2.2 to ^4.9.0 (@ralphtheninja)
• Upgrade standard devDependency from ^5.3.1 to ^11.0.1 (@ralphtheninja)
• Update links in package.json (@ralphtheninja)
• Replace util.inherits with inherits module (@ralphtheninja)
• SubIterator should inherit from AbstractIterator (@ralphtheninja)
• Use underscore methods to properly override (@ralphtheninja)
• Change SubDown#type from subdown to subleveldown (@ralphtheninja)
• Rewrite SubDown#_open to handle any inner *downs (@ralphtheninja)
• Update sublevel specific tests to handle levelup + encoding-down (@ralphtheninja)
• Update README (@ralphtheninja, @vweevers)

Added

• Depend on encoding-down for encoding logic (@ralphtheninja)
• Add node 6, 8, 9 and 10 to Travis (@ralphtheninja)
• Test SubDown constructor (@ralphtheninja)
• Test main subdb (@ralphtheninja)
• Test encodings (@ralphtheninja)
• Test wrapping a closed levelup and re-opening it (@ralphtheninja)
• Test nested sublevels (@ralphtheninja)
• Add temporary down() and isAbstract() functions (@ralphtheninja)
• Add UPGRADING.md (@ralphtheninja)

Removed

• Remove node 0.12 from Travis (@ralphtheninja)
• Remove SubDown#destroy (@ralphtheninja)
• Remove SubDown#repair (@ralphtheninja)
• Remove SubDown#setDb (@ralphtheninja)
• Remove SubDown#approximateSize (@ralphtheninja)
• Remove SubDown#getProperty (@ralphtheninja)

Fixed

• Fix deprecated new Buffer() (@ralphtheninja)