level-codec

level-codec

Encoding logic for level(up).

API

Codec([opts])

Create a new codec, with a global options object.

This could be something like

var codec = new Codec(db.options);

#encodeKey(key[, opts])

Encode key with given opts.

#encodeValue(value[, opts])

Encode value with given opts.

#encodeBatch(batch[, opts])

Encode batch ops with given opts.

#encodeLtgt(ltgt)

Encode the ltgt values of option object ltgt.

#decodeKey(key[, opts])

Decode key with given opts.

#decodeValue(value[, opts])

Decode value with given opts.

#createStreamDecoder([opts])

Create a function with signature (key, value), that for each key/value pair returned from a levelup read stream returns the decoded value to be emitted.

#keyAsBuffer([opts])

Check whether opts and the global opts call for a binary key encoding.

#valueAsBuffer([opts])

Check whether opts and the global opts call for a binary value encoding.

#encodings

The builtin encodings as object of form

{
  [type]: encoding
}

See below for a list and the format of encoding.

Builtin encodings

Type	Input	Stored as	Output
utf8	String or Buffer	String or Buffer	String
json	Any JSON type	JSON string	Input
binary	Buffer, string or byte array	Buffer	As stored
hex ascii base64 ucs2 utf16le utf-16le	String or Buffer	Buffer	String
none a.k.a. id	Any type (bypass encoding)	Input*	As stored

^* Stores may have their own type coercion. Whether type information is preserved depends on the abstract-leveldown implementation as well as the underlying storage (LevelDB, IndexedDB, etc).

Encoding format

An encoding is an object of the form:

{
  encode: function (data) {
    return data
  },
  decode: function (data) {
    return data
  },
  buffer: Boolean,
  type: 'example'
}

All of these properties are required.

The buffer boolean tells consumers whether to fetch data as a Buffer, before calling your decode() function on that data. If buffer is true, it is assumed that decode() takes a Buffer. If false, it is assumed that decode takes any other type (usually a string).

To explain this in the grand scheme of things, consider a store like leveldown which has the ability to return either a Buffer or string, both sourced from the same byte array. Wrap this store with encoding-down and it'll select the most optimal data type based on the buffer property of the active encoding. If your decode() function needs a string (and the data can legitimately become a UTF8 string), you should set buffer to false. This avoids the cost of having to convert a Buffer to a string.

The type string should be a unique name.

Publishers

• @juliangruber
• @ralphtheninja

License & copyright

Copyright (c) 2012-2017 levelup contributors.

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

Changelog

[8.0.0] - 2017-10-21

Changed

• Revert "fix utf-8 encoding returning buffers" (#23) (@ralphtheninja)

Added

• Add badges to README and stylize "levelup" (#22) (@vweevers)
• Document encodings and their format in greater detail (#22) (@vweevers)