Package Exports

encoding-down

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (encoding-down) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

encoding-down

An abstract-leveldown implementation that wraps another store to encode keys and values.

Node version

Introduction

Stores like leveldown can only store strings and Buffers. Other types, though accepted, are serialized before storage, which is an irreversible type conversion. For a richer set of data types you can wrap such a store with encoding-down. It allows you to specify an encoding to use for keys and values independently. This not only widens the range of input types, but also limits the range of output types. The encoding is applied to all read and write operations: it encodes writes and decodes reads.

Many encodings are builtin courtesy of level-codec. The default encoding is utf8 which ensures you'll always get back a string. You can also provide a custom encoding like bytewise - or your own!

Usage

Without any options, encoding-down defaults to the utf8 encoding.

var levelup = require('levelup')
var leveldown = require('leveldown')
var encode = require('encoding-down')

var db = levelup(encode(leveldown('./db1')))

db.put('example', Buffer.from('encoding-down'), function (err) {
  db.get('example', function (err, value) {
    console.log(typeof value, value) // 'string encoding-down'
  })
})

Can we store objects? Yes!

var db = levelup(encode(leveldown('./db2'), { valueEncoding: 'json' }))

db.put('example', { awesome: true }, function (err) {
  db.get('example', function (err, value) {
    console.log(value) // { awesome: true }
    console.log(typeof value) // 'object'
  })
})

How about storing Buffers, but getting back a hex-encoded string?

var db = levelup(encode(leveldown('./db3'), { valueEncoding: 'hex' }))

db.put('example', Buffer.from([0, 255]), function (err) {
  db.get('example', function (err, value) {
    console.log(typeof value, value) // 'string 00ff'
  })
})

What if we previously stored binary data?

var db = levelup(encode(leveldown('./db4'), { valueEncoding: 'binary' }))

db.put('example', Buffer.from([0, 255]), function (err) {
  db.get('example', function (err, value) {
    console.log(typeof value, value) // 'object <Buffer 00 ff>'
  })

  // Override the encoding for this operation
  db.get('example', { valueEncoding: 'base64' }, function (err, value) {
    console.log(typeof value, value) // 'string AP8='
  })
})

And what about keys?

var db = levelup(encode(leveldown('./db5'), { keyEncoding: 'json' }))

db.put({ awesome: true }, 'example', function (err) {
  db.get({ awesome: true }, function (err, value) {
    console.log(value) // 'example'
  })
})

var db = levelup(encode(leveldown('./db6'), { keyEncoding: 'binary' }))

db.put(Buffer.from([0, 255]), 'example', function (err) {
  db.get('00ff', { keyEncoding: 'hex' }, function (err, value) {
    console.log(value) // 'example'
  })
})

Usage with `level`

The level module conveniently bundles encoding-down and passes its options to encoding-down. This means you can simply do:

var level = require('level')
var db = level('./db7', { valueEncoding: 'json' })

db.put('example', 42, function (err) {
  db.get('example', function (err, value) {
    console.log(value) // 42
    console.log(typeof value) // 'number'
  })
})

API

`db = require('encoding-down')(db[, options])`

db must be an abstract-leveldown compliant store
options are passed to level-codec:
- keyEncoding: encoding to use for keys
- valueEncoding: encoding to use for values

Both encodings default to 'utf8'. They can be a string (builtin level-codec encoding) or an object (custom encoding).

Custom encodings

Please refer to level-codec documentation for a precise description of the format. Here's a quick example with level and async/await just for fun:

var level = require('level')
var lexint = require('lexicographic-integer')

async function main () {
  var db = level('./db8', {
    keyEncoding: {
      type: 'lexicographic-integer',
      encode: (n) => lexint.pack(n, 'hex'),
      decode: lexint.unpack,
      buffer: false
    }
  })

  await db.put(2, 'example')
  await db.put(10, 'example')

  // Without our encoding, the keys would sort as 10, 2.
  db.createKeyStream().on('data', console.log) // 2, 10
}

main()

With an npm-installed encoding (modularity ftw!) we can reduce the above to:

var level = require('level')
var lexint = require('lexicographic-integer-encoding')('hex')

var db = level('./db8', {
  keyEncoding: lexint
})

encoding-down

Package Exports

Readme

encoding-down

Introduction

Usage

Usage with level

API

db = require('encoding-down')(db[, options])

Custom encodings

License

Usage with `level`

`db = require('encoding-down')(db[, options])`