• Stars
    star
    119
  • Rank 297,930 (Top 6 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 10 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

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

subleveldown

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

level badge npm Node version Test Coverage Standard Common Changelog Donate

Table of Contents

Click to expand

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

More Repositories

1

levelup

A wrapper for abstract-leveldown compliant stores, for Node.js and browsers.
JavaScript
4,079
star
2

level

Universal abstract-level database for Node.js and browsers.
JavaScript
1,544
star
3

leveldown

Pure C++ Node.js LevelDB binding. An abstract-leveldown compliant store.
C++
773
star
4

level-js

An abstract-leveldown compliant store on top of IndexedDB.
JavaScript
542
star
5

awesome

An open list of awesome Level modules and resources.
JavaScript
287
star
6

memdown

In-memory abstract-leveldown store for Node.js and browsers.
JavaScript
285
star
7

rocksdb

Pure C++ Node.js RocksDB binding. An abstract-leveldown compliant store.
C++
229
star
8

abstract-leveldown

An abstract prototype matching the leveldown API.
JavaScript
146
star
9

party

Open a leveldb handle multiple times.
JavaScript
146
star
10

level-rocksdb

A convenience package bundling levelup and rocksdb.
JavaScript
146
star
11

abstract-level

Abstract class for a lexicographically sorted key-value database.
JavaScript
120
star
12

electron-demo

Demo app loading LevelDB into an Electron context.
JavaScript
79
star
13

level-ttl

Add a 'ttl' (time-to-live) option to levelup for put() and batch().
JavaScript
69
star
14

level-browserify

No longer maintained: superseded by level v5.0.0.
JavaScript
63
star
15

classic-level

An abstract-level database backed by LevelDB.
JavaScript
58
star
16

multileveldown

multilevel implemented using leveldowns with reconnect support.
JavaScript
58
star
17

browser-level

An abstract-level database for browsers, backed by IndexedDB.
JavaScript
45
star
18

leveljs.org

Source code of leveljs.org
Pug
43
star
19

community

Discussion, support and common information for projects in the community.
42
star
20

encoding-down

An abstract-leveldown implementation that wraps another store to encode keys and values.
JavaScript
41
star
21

level-hyper

A convenience package bundling levelup and leveldown-hyper.
JavaScript
30
star
22

leveldown-mobile

This project has been abandoned.
C++
27
star
23

codec

Encode keys, values and range options, with built-in or custom encodings.
JavaScript
27
star
24

memory-level

In-memory abstract-level database for Node.js and browsers.
JavaScript
25
star
25

mem

A convenience package bundling levelup and memdown.
JavaScript
24
star
26

level-ws

A basic writable stream for abstract-level databases.
JavaScript
22
star
27

packager

A levelup package helper for distributing with an abstract-leveldown compatible back-end.
JavaScript
20
star
28

level-test

Inject temporary and isolated level stores (leveldown, level-js, memdown or custom) into your tests.
JavaScript
20
star
29

deferred-leveldown

An abstract-leveldown implementation that queues operations while a real abstract-leveldown instance is being opened.
JavaScript
19
star
30

many-level

Share an abstract-level database over the network or other kind of stream.
JavaScript
17
star
31

leveldown-hyper

Pure C++ Node.js HyperLevelDB binding. An abstract-leveldown compliant store.
C++
15
star
32

errors

Error types for levelup.
JavaScript
13
star
33

web-stream

Read from an abstract-level database using Web Streams.
JavaScript
12
star
34

iterator-stream

Turn an abstract-leveldown iterator into a readable stream.
JavaScript
12
star
35

level-lmdb

This project has been abandoned.
JavaScript
11
star
36

bench

Benchmark abstract-level databases.
JavaScript
8
star
37

level-mobile

[Currently not actively maintained] Fast & simple storage - a Node.js-style LevelDB wrapper (a convenience package bundling levelup & leveldown-mobile) [requires JXcore 0.3.0.3+]
JavaScript
8
star
38

read-stream

Read from an abstract-level database using Node.js streams.
JavaScript
6
star
39

rave-level

Use a LevelDB database from multiple processes with seamless failover.
JavaScript
6
star
40

level-basho

This project has been abandoned.
JavaScript
5
star
41

webpack-starter

Demonstrates bundling level for browsers using webpack.
JavaScript
5
star
42

concat-iterator

Concatenate entries from an iterator into an array.
JavaScript
5
star
43

compose

Compose a database factory from abstract-leveldown and levelup layers.
JavaScript
4
star
44

transcoder

Encode data with built-in or custom encodings.
JavaScript
4
star
45

supports

Create a manifest describing the abilities of an abstract-level database.
JavaScript
4
star
46

level-fstream

This project has been abandoned.
JavaScript
3
star
47

lazy-open

This project has been abandoned.
JavaScript
3
star
48

typings

Experimental typing development for level repositories. Deprecated.
TypeScript
3
star
49

database

2
star
50

browserify-starter

Demonstrates bundling level for browsers using browserify.
JavaScript
2
star
51

.github

Default community health files.
1
star