encoding-down - npm Package Compare versions

Comparing version 2.3.1 to 2.3.2

index.js

@@ -48,2 +48,3 @@ 'use strict'
   key = this.codec.encodeKey(key, opts)
+  opts.asBuffer = this.codec.valueAsBuffer(opts)
   this.db.get(key, opts, function (err, value) {
@@ -75,2 +76,4 @@ if (err) return cb(err)
 DB.prototype._iterator = function (opts) {
+  opts.keyAsBuffer = this.codec.keyAsBuffer(opts)
+  opts.valueAsBuffer = this.codec.valueAsBuffer(opts)
   return new Iterator(this, opts)
@@ -77,0 +80,0 @@ }

package.json

 {
   "name": "encoding-down",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "license": "MIT",
@@ -20,5 +20,5 @@ "repository": "level/encoding-down",
     "abstract-leveldown": "^2.7.1",
-    "level-codec": "^7.0.0",
+    "level-codec": "^8.0.0",
     "level-errors": "^1.0.4"
   }
 }

README.md

 # encoding-down
 
-<img alt="LevelDB Logo" height="100" src="http://leveldb.org/img/logo.svg">
+> An [`abstract-leveldown`] implementation that wraps another store to encode keys and values.
 
-[`abstract-leveldown`](https://github.com/level/abstract-leveldown) wrapper supporting levelup@1 encodings. For motivation, see [this issue](https://github.com/Level/levelup/pull/367).
+[![level badge][level-badge]](https://github.com/level/awesome)
+[![npm](https://img.shields.io/npm/v/encoding-down.svg)](https://www.npmjs.com/package/encoding-down)
+[![Travis](https://travis-ci.org/Level/encoding-down.svg?branch=master)](https://travis-ci.org/Level/encoding-down)
+[![david](https://david-dm.org/Level/encoding-down.svg)](https://david-dm.org/level/encoding-down)
+[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+[![npm](https://img.shields.io/npm/dm/encoding-down.svg)](https://www.npmjs.com/package/encoding-down)
 
-[![Build Status](https://travis-ci.org/Level/encoding-down.svg?branch=master)](https://travis-ci.org/Level/encoding-down) [![Greenkeeper badge](https://badges.greenkeeper.io/Level/encoding-down.svg)](https://greenkeeper.io/)
+## Introduction
 
+Stores like [`leveldown`] can only store strings and Buffers. 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][builtin-encodings] 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](#custom-encodings)!
+
 ## Usage
 
+Without any options, `encoding-down` defaults to the `utf8` encoding.
+
 ```js
@@ -15,6 +26,8 @@ const levelup = require('levelup')
 const encode = require('encoding-down')
-const db = levelup(encode(leveldown('./db')))
-db.put('name', 'encoding-down', function (err) {
-  db.get('name', function (err, value) {
-    if (!err) console.log('name=', value)
+
+const 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'
   })
@@ -24,2 +37,82 @@ })
 
+Can we store objects? Yes!
+
+```js
+const 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?
+
+```js
+const 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?
+
+```js
+const 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?
+
+```js
+const 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'
+  })
+})
+```
+
+```js
+const 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:
+
+```js
+const level = require('level')
+const 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
@@ -29,10 +122,48 @@
 
-* `db` `abstract-leveldown` compatible db such as `leveldown`, `memdown`, `level-js` etc
-* `options.keyEncoding` (string) defaults to `'utf8'`
-* `options.valueEncoding` (string) defaults to `'utf8'`
+* `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
 
-`options` are passed to [`level-codec`](https://github.com/level/codec), see [supported encodings](https://github.com/Level/codec#encodings) for more information.
+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][encoding-format] for a precise description of the format. Here's a quick example with `level` and `async/await` just for fun:
+
+```js
+const level = require('level')
+const lexint = require('lexicographic-integer')
+
+async function main () {
+  const db = level('./db8', {
+    keyEncoding: {
+      // Hey, someone should publish this!
+      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()
+```
+
 ## License
 
 MIT
+
+[level-badge]: http://leveldb.org/img/badge.svg
+[`abstract-leveldown`]: https://github.com/level/abstract-leveldown
+[`leveldown`]: https://github.com/level/leveldown
+[`level`]: https://github.com/level/level
+[`level-codec`]: https://github.com/level/level-codec
+[builtin-encodings]: https://github.com/level/level-codec#builtin-encodings
+[encoding-format]: https://github.com/level/level-codec#encoding-format

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

10362

increased by70.12%

Lines of code

131

increased by2.34%

Number of lines in readme file

167

increased by363.89%

Dependency changes

• + Addedlevel-codec@8.0.0(transitive)

• - Removedlevel-codec@7.1.0(transitive)

• Updatedlevel-codec@^8.0.0