level-codec

level-codec

Encode keys, values and range options, with built-in or custom encodings.

Usage

If you are upgrading: please see UPGRADING.md.

const Codec = require('level-codec')
const codec = Codec({ keyEncoding: 'json' })
const key = codec.encodeKey({ foo: 'bar' })
console.log(key) // -> '{"foo":"bar"}'
console.log(codec.decodeKey(key)) // -> { foo: 'bar' }

API

codec = Codec([opts])

Create a new codec, with a global options object.

codec.encodeKey(key[, opts])

Encode key with given opts.

codec.encodeValue(value[, opts])

Encode value with given opts.

codec.encodeBatch(batch[, opts])

Encode batch ops with given opts.

codec.encodeLtgt(ltgt)

Encode the ltgt values of option object ltgt.

codec.decodeKey(key[, opts])

Decode key with given opts.

codec.decodeValue(value[, opts])

Decode value with given opts.

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

codec.keyAsBuffer([opts])

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

codec.valueAsBuffer([opts])

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

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

Contributing

Level/codec 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

To sustain Level and its activities, become a backer or sponsor on Open Collective. Your logo or avatar will be displayed on our 28+ GitHub repositories and npm packages. 💖

Backers

Sponsors

License

MIT © 2012-present Contributors.

Changelog

[10.0.0] - 2021-04-09

Changed

• Breaking: remove legacy range options (Level/community#86) (73b19b4) (Vincent Weevers)
• Breaking: drop node 6 and 8 (38dc04c) (Level/community#98) (Vincent Weevers)
• Breaking: modernize syntax & bump standard to 16.x (874956f, e3ed6e4) (Level/community#98) (Vincent Weevers).
• Breaking: bump buffer from 15.x to 16.x (#62) (Level/community#98) (78d2ea0) (Alex Potsides).