Awesome
bytespace
Efficient keypath subspaces prefixed with bytewise tuples.
This library is very much like level-sublevel
, and is API-compatible in several key way, but intents to be simpler in principle. A bytespace
is essentially just a collection of wrappers over levelup
methods to control key encoding behavior.
Prefixes are constructed as bytewise
-encoded arrays, which allows you to use arbirarily complex keys in your subspace prefixes (any encoding supported by bytewise
), and any keyEncoding
you prefer for your subspace suffix keyspace.
Usage
var bytespace = require('bytespace')
var levelup = require('levelup')
var db = levelup('./mydb')
// all the standard levelup options
var options = {
// keyEncoding defaults to "utf8" just like levelup
keyEncoding: require('bytewise'),
valueEncoding: 'json'
}
// same API as levelup
var appDb = bytespace(db, 'myapp', options)
// you can mount subspaces within subspaces
var nestedDb = bytespace(myapp, 'nested')
// namespace can be any bytewise-serializable value
var testDb = bytespace(appDb, new Date())
// subspaces may also be mounted sublevel-style
var subDb = testDb.sublevel('another')
Rooted keypaths
The subspace db instance itself is essentially a keyspace chroot
-- a jail you cannot escape with just a reference to the subspace. While a subspace must be provided a reference to a backing db to initialize, this capability should not be surfaced on any properties or methods of the subspace. The capabilities of a subspace are restricted to the subset of of keyspace allocated to it.
Nested subspaces
When instantiating a subspace, it will test the provided db
reference to determine if it's a bytespace
instance. If so, it will call the sublevel
method with the provided options to create the new subspace. Rather than running through the encode/decode process mulitple times, the responsibility of encoding and decoding keys is delegated to the root subspace. All keys will be correctly prefixed to the appropriate subspace.
The sublevel
method is API-compatible with level-sublevel, though we also take an extra options
argument to allow levelup
db options to be provided to configure subspaces separate from their ancestor spaces.
Remote subspaces
Since bytespace
is mostly just a set of levelup
method wrappers this allows you to use over a multilevel
-backed database, creating arbitrary subspaces on the client at runtime. If the multilevel
client database has access to a createLiveStream
method you can even create live streams observing ranges within your sublevel, all without the server having to know the sublevel layout ahead of time.
Hooks
Precommit and postcommit hooks are implemented using the pre
and post
methods from level-sublevel's API. The optional range
argument is not yet implemented but it is otherwise API-compatible, allowing a bytespace
instance with libraries expected a sublevel
instance.
Encoding
Subspace keys are encoded as bytewise-prefixed arrays. This allows subspace keys to be appended as the last element of a namespace without overhead. Encoded subspace keys can be appended to the precomputed namespace buffer with a single Buffer.concat
operation. Mounting a subspace adds another element to the prefix tuple. This serialization ensures that keys of different subspaces cannot interleave.
When encoding keys, the encoded namespace buffer can be efficiently concatenated with a subspace key. When decoding, the namespace portion can be sliced off and ignored. Testing for subspace inclusion is also just a single buffer slice.