abstract-leveldown

An abstract prototype matching the leveldown API. Useful for extending levelup functionality by providing a replacement to leveldown.

abstract-leveldown provides a simple, operational noop base prototype that's ready for extending. By default, all operations have sensible "noops" (operations that essentially do nothing). For example, simple operations such as .open(callback) and .close(callback) will simply invoke the callback (on a next tick). More complex operations perform sensible actions, for example: .get(key, callback) will always return a 'NotFound' Error on the callback.

You add functionality by implementing the underscore versions of the operations. For example, to implement a put() operation you add a _put() method to your object. Each of these underscore methods override the default noop operations and are always provided with consistent arguments, regardless of what is passed in by the client.

Additionally, all methods provide argument checking and sensible defaults for optional arguments. All bad-argument errors are compatible with leveldown (they pass the leveldown method arguments tests). For example, if you call .open() without a callback argument you'll get an Error('open() requires a callback argument'). Where optional arguments are involved, your underscore methods will receive sensible defaults. A .get(key, callback) will pass through to a ._get(key, options, callback) where the options argument is an empty object.

If you are upgrading: please see UPGRADING.md.

Example

A simplistic in-memory leveldown replacement

var util = require('util')
var AbstractLevelDOWN = require('./').AbstractLevelDOWN

// constructor, passes through the 'location' argument to the AbstractLevelDOWN constructor
function FakeLevelDOWN (location) {
  AbstractLevelDOWN.call(this, location)
}

// our new prototype inherits from AbstractLevelDOWN
util.inherits(FakeLevelDOWN, AbstractLevelDOWN)

// implement some methods

FakeLevelDOWN.prototype._open = function (options, callback) {
  // initialise a memory storage object
  this._store = {}
  // optional use of nextTick to be a nice async citizen
  process.nextTick(function () { callback(null, this) }.bind(this))
}

FakeLevelDOWN.prototype._put = function (key, value, options, callback) {
  key = '_' + key // safety, to avoid key='__proto__'-type skullduggery
  this._store[key] = value
  process.nextTick(callback)
}

FakeLevelDOWN.prototype._get = function (key, options, callback) {
  var value = this._store['_' + key]
  if (value === undefined) {
    // 'NotFound' error, consistent with LevelDOWN API
    return process.nextTick(function () { callback(new Error('NotFound')) })
  }
  process.nextTick(function () {
    callback(null, value)
  })
}

FakeLevelDOWN.prototype._del = function (key, options, callback) {
  delete this._store['_' + key]
  process.nextTick(callback)
}

// Now use it with levelup

var levelup = require('levelup')

var db = levelup(new FakeLevelDOWN('/who/cares'))

db.put('foo', 'bar', function (err) {
  if (err) throw err
  db.get('foo', function (err, value) {
    if (err) throw err
    console.log('Got foo =', value)
  })
})

See memdown if you are looking for a complete in-memory replacement for leveldown.

Extensible API

Remember that each of these methods, if you implement them, will receive exactly the number and order of arguments described. Optional arguments will be converted to sensible defaults.

AbstractLevelDOWN(location)

AbstractLevelDOWN#status

An AbstractLevelDOWN based database can be in one of the following states:

'new' - newly created, not opened or closed
'opening' - waiting for the database to be opened
'open' - successfully opened the database, available for use
'closing' - waiting for the database to be closed
'closed' - database has been successfully closed, should not be used

AbstractLevelDOWN#_open(options, callback)

AbstractLevelDOWN#_close(callback)

AbstractLevelDOWN#_get(key, options, callback)

AbstractLevelDOWN#_put(key, value, options, callback)

AbstractLevelDOWN#_del(key, options, callback)

AbstractLevelDOWN#_batch(array, options, callback)

If batch() is called without arguments or with only an options object then it should return a Batch object with chainable methods. Otherwise it will invoke a classic batch operation.

AbstractLevelDOWN#_chainedBatch()

By default a batch() operation without arguments returns a blank AbstractChainedBatch object. The prototype is available on the main exports for you to extend. If you want to implement chainable batch operations then you should extend the AbstractChaindBatch and return your object in the _chainedBatch() method.

AbstractLevelDOWN#_serializeKey(key)

AbstractLevelDOWN#_serializeValue(value)

AbstractLevelDOWN#_iterator(options)

By default an iterator() operation returns a blank AbstractIterator object. The prototype is available on the main exports for you to extend. If you want to implement iterator operations then you should extend the AbstractIterator and return your object in the _iterator(options) method.

The iterator() operation accepts the following range options:

gt
gte
lt
lte
start (legacy)
end (legacy)

A range option that is either an empty buffer, an empty string or null will be ignored.

AbstractIterator implements the basic state management found in LevelDOWN. It keeps track of when a next() is in progress and when an end() has been called so it doesn't allow concurrent next() calls, it does allow end() while a next() is in progress and it doesn't allow either next() or end() after end() has been called.

AbstractIterator(db)

Provided with the current instance of AbstractLevelDOWN by default.

AbstractIterator#_next(callback)

AbstractIterator#_end(callback)

AbstractChainedBatch

Provided with the current instance of AbstractLevelDOWN by default.

AbstractChainedBatch#_put(key, value)

AbstractChainedBatch#_del(key)

AbstractChainedBatch#_clear()

AbstractChainedBatch#_write(options, callback)

AbstractChainedBatch#_serializeKey(key)

AbstractChainedBatch#_serializeValue(value)

TypeScript

Ships with TypeScript definitions that enable automatic inference of options and key-value types on a typed abstract-leveldown implementation.

Contributing

abstract-leveldown 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.

License & Copyright

abstract-leveldown is licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.

Tapppi / abstract-leveldown