refactor read streams using level-iterator-stream and level-codec

Author: juliangruber

CHANGELOG.md

@@ -1,9 +1,25 @@
-### 0.18.6 @ Aug 26 2014
+### 0.19.0 @ Aug 26 2014
+
+ * [[`7f14058440`](https://github.com/level/levelup/commit/7f14058440)] - minor whitespace changes (Rod Vagg)
+ * [[`9e6d335df2`](https://github.com/level/levelup/commit/9e6d335df2)] - fix license (Rod Vagg)
+ * [[`74caa18c09`](https://github.com/level/levelup/commit/74caa18c09)] - minor style fixes (Rod Vagg)
+ * [[`1c7bc43d01`](https://github.com/level/levelup/commit/1c7bc43d01)] - update nodeico badge (Rod Vagg)
+ * [[`b6357cc323`](https://github.com/level/levelup/commit/b6357cc323)] - Use highest/lowest instead of largest/smallest (Arnout Engelen)
+ * [[`e45ce4e9d5`](https://github.com/level/levelup/commit/e45ce4e9d5)] - Document what 'limit' does in 'reverse' mode (Arnout Engelen)
+ * [[`9004e9db69`](https://github.com/level/levelup/commit/9004e9db69)] - Discourage the use of start/end a bit (Arnout Engelen)
+ * [[`6178d69cdc`](https://github.com/level/levelup/commit/6178d69cdc)] - merge (Dominic Tarr)
+ * [[`e3ab0ebe03`](https://github.com/level/levelup/commit/e3ab0ebe03)] - document with comments (Dominic Tarr)
+ * [[`bb88572c15`](https://github.com/level/levelup/commit/bb88572c15)] - unmention bops (Dominic Tarr)
+ * [[`45df8e668e`](https://github.com/level/levelup/commit/45df8e668e)] - clarify ltgt (Dominic Tarr)
+ * [[`54eba03305`](https://github.com/level/levelup/commit/54eba03305)] - binary encoding in the browser (Calvin Metcalf)
+
+### 0.18.6 @ Jul 26 2014
+
  * (lots of stuff since 0.18.1 not recorded in changelog, ooops)
  * Extracted encoding / codec to separate modules (@dominictarr)
 
-
 ### 0.18.1 @ Nov 20 2013
+
  * Make chained-batch obey global LevelUP object options (@mcavage)
 
 ### 0.18.0 @ Nov 18 2013
@@ -54,7 +70,7 @@
 
 ### 0.9.0 @ 21 May 2013
 
-  * Use LevelDOWN@0.5.0, see https://github.com/rvagg/node-leveldown/blob/master/CHANGELOG.md for details
+  * Use LevelDOWN@0.5.0, see https://github.com/level/leveldown/blob/master/CHANGELOG.md for details
   * Race-condition(ish) fixed in ReadStream--createReadStream() does not start immediately and therefore allowed put()s to happen before the stream starts (@dominictarr)
   * ReadStream doesn't emit "ready" event (@dominictarr)
   * Allow separate encodings per operation in db.batch() (@juliangruber)
@@ -98,7 +114,7 @@
 ### 0.6.0 @ Feb 25 2013
 
   * complete transition to LevelDOWN for the LevelDB binding. No native code left in LevelUP @rvagg
-    - LevelDOWN now keeps its own ChangeLog at: https://github.com/rvagg/node-leveldown/blob/master/CHANGELOG.md
+    - LevelDOWN now keeps its own ChangeLog at: https://github.com/level/leveldown/blob/master/CHANGELOG.md
     - LevelDB@1.9.0 and Snappy@1.1.0 are included in LevelDOWN@0.1.2
   * simplify callback signature (remove extra, undocumented properties from some callbacks) @rvagg / @dominictarr
 

LICENSE.md

@@ -1,10 +1,10 @@
 The MIT License (MIT)
 =====================
 
-Copyright (c) 2014 LevelUP contributors
+Copyright (c) 2012-2015 LevelUP contributors
 ---------------------------------------
 
-*LevelUP contributors listed at <https://github.com/rvagg/node-levelup#contributors>*
+*LevelUP contributors listed at <https://github.com/level/levelup#contributors>*
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -5,7 +5,7 @@ LevelUP
 
 **Fast & simple storage - a Node.js-style LevelDB wrapper**
 
-[![Build Status](https://secure.travis-ci.org/rvagg/node-levelup.png)](http://travis-ci.org/rvagg/node-levelup)
+[![Build Status](https://secure.travis-ci.org/Level/levelup.png)](http://travis-ci.org/Level/levelup)
 
 [![NPM](https://nodei.co/npm/levelup.png?stars&downloads&downloadRank)](https://nodei.co/npm/levelup/) [![NPM](https://nodei.co/npm-dl/levelup.png?months=6&height=3)](https://nodei.co/npm/levelup/)
 
@@ -40,11 +40,11 @@ LevelDB stores entries **sorted lexicographically by keys**. This makes LevelUP'
 Relationship to LevelDOWN
 -------------------------
 
-LevelUP is designed to be backed by **[LevelDOWN](https://github.com/rvagg/node-leveldown/)** which provides a pure C++ binding to LevelDB and can be used as a stand-alone package if required.
+LevelUP is designed to be backed by **[LevelDOWN](https://github.com/level/leveldown/)** which provides a pure C++ binding to LevelDB and can be used as a stand-alone package if required.
 
 **As of version 0.9, LevelUP no longer requires LevelDOWN as a dependency so you must `npm install leveldown` when you install LevelUP.**
 
-LevelDOWN is now optional because LevelUP can be used with alternative backends, such as **[level.js](https://github.com/maxogden/level.js)** in the browser or [MemDOWN](https://github.com/rvagg/node-memdown) for a pure in-memory store.
+LevelDOWN is now optional because LevelUP can be used with alternative backends, such as **[level.js](https://github.com/maxogden/level.js)** in the browser or [MemDOWN](https://github.com/level/memdown) for a pure in-memory store.
 
 LevelUP will look for LevelDOWN and throw an error if it can't find it in its Node `require()` path. It will also tell you if the installed version of LevelDOWN is incompatible.
 
@@ -161,7 +161,7 @@ db.get('foo', function (err, value) {
 
 The `location` argument is available as a read-only property on the returned LevelUP instance.
 
-The `levelup(options, callback)` form (with optional `callback`) is only available where you provide a valid `'db'` property on the options object (see below). Only for back-ends that don't require a `location` argument, such as [MemDOWN](https://github.com/rvagg/memdown).
+The `levelup(options, callback)` form (with optional `callback`) is only available where you provide a valid `'db'` property on the options object (see below). Only for back-ends that don't require a `location` argument, such as [MemDOWN](https://github.com/level/memdown).
 
 For example:
 
@@ -171,7 +171,7 @@ var memdown = require('memdown')
 var db = levelup({ db: memdown })
 ```
 
-The `levelup(db, callback)` form (with optional `callback`) is only available where `db` is a factory function, as would be provided as a `'db'` property on an `options` object (see below). Only for back-ends that don't require a `location` argument, such as [MemDOWN](https://github.com/rvagg/memdown).
+The `levelup(db, callback)` form (with optional `callback`) is only available where `db` is a factory function, as would be provided as a `'db'` property on an `options` object (see below). Only for back-ends that don't require a `location` argument, such as [MemDOWN](https://github.com/level/memdown).
 
 For example:
 
@@ -198,7 +198,7 @@ var db = levelup(memdown)
   <p>Supported encodings are: hex, utf8, ascii, binary, base64, ucs2, utf16le.</p>
   <p><code>'json'</code> encoding is also supported, see below.</p>
 
-* `'db'` *(object, default: LevelDOWN)*: LevelUP is backed by [LevelDOWN](https://github.com/rvagg/node-leveldown/) to provide an interface to LevelDB. You can completely replace the use of LevelDOWN by providing a "factory" function that will return a LevelDOWN API compatible object given a `location` argument. For further information, see [MemDOWN](https://github.com/rvagg/node-memdown/), a fully LevelDOWN API compatible replacement that uses a memory store rather than LevelDB. Also see [Abstract LevelDOWN](http://github.com/rvagg/node-abstract-leveldown), a partial implementation of the LevelDOWN API that can be used as a base prototype for a LevelDOWN substitute.
+* `'db'` *(object, default: LevelDOWN)*: LevelUP is backed by [LevelDOWN](https://github.com/level/leveldown/) to provide an interface to LevelDB. You can completely replace the use of LevelDOWN by providing a "factory" function that will return a LevelDOWN API compatible object given a `location` argument. For further information, see [MemDOWN](https://github.com/level/memdown), a fully LevelDOWN API compatible replacement that uses a memory store rather than LevelDB. Also see [Abstract LevelDOWN](http://github.com/level/abstract-leveldown), a partial implementation of the LevelDOWN API that can be used as a base prototype for a LevelDOWN substitute.
 
 Additionally, each of the main interface methods accept an optional options object that can be used to override `'keyEncoding'` and `'valueEncoding'`.
 
@@ -460,11 +460,11 @@ db.createReadStream({ keys: false, values: true })
 <a name="writeStreams"></a>
 #### What happened to `db.createWriteStream`?
 
-`db.createWriteStream()` has been removed in order to provide a smaller and more maintainable core. It primarily existed to create symmetry with `db.createReadStream()` but through much [discussion](https://github.com/rvagg/node-levelup/issues/199), removing it was the best cause of action.
+`db.createWriteStream()` has been removed in order to provide a smaller and more maintainable core. It primarily existed to create symmetry with `db.createReadStream()` but through much [discussion](https://github.com/level/levelup/issues/199), removing it was the best cause of action.
 
 The main driver for this was performance. While `db.createReadStream()` performs well under most use cases, `db.createWriteStream()` was highly dependent on the application keys and values. Thus we can't provide a standard implementation and encourage more `write-stream` implementations to be created to solve the broad spectrum of use cases.
 
-Check out the implementations that the community has already produced [here](https://github.com/rvagg/node-levelup/wiki/Modules#write-streams).
+Check out the implementations that the community has already produced [here](https://github.com/level/levelup/wiki/Modules#write-streams).
 
 --------------------------------------------------------
 <a name='approximateSize'></a>
@@ -480,7 +480,7 @@ db.db.approximateSize('a', 'c', function (err, size) {
 })
 ```
 
-**Note:** `approximateSize()` is available via [LevelDOWN](https://github.com/rvagg/node-leveldown/), which by default is accessible as the `db` property of your LevelUP instance. This is a specific LevelDB operation and is not likely to be available where you replace LevelDOWN with an alternative back-end via the `'db'` option.
+**Note:** `approximateSize()` is available via [LevelDOWN](https://github.com/level/leveldown/), which by default is accessible as the `db` property of your LevelUP instance. This is a specific LevelDB operation and is not likely to be available where you replace LevelDOWN with an alternative back-end via the `'db'` option.
 
 
 --------------------------------------------------------
@@ -503,7 +503,7 @@ console.log(db.db.getProperty('leveldb.num-files-at-level3'))
 // → '243'
 ```
 
-**Note:** `getProperty()` is available via [LevelDOWN](https://github.com/rvagg/node-leveldown/), which by default is accessible as the `db` property of your LevelUP instance. This is a specific LevelDB operation and is not likely to be available where you replace LevelDOWN with an alternative back-end via the `'db'` option.
+**Note:** `getProperty()` is available via [LevelDOWN](https://github.com/level/leveldown/), which by default is accessible as the `db` property of your LevelUP instance. This is a specific LevelDB operation and is not likely to be available where you replace LevelDOWN with an alternative back-end via the `'db'` option.
 
 
 --------------------------------------------------------
@@ -513,7 +513,7 @@ console.log(db.db.getProperty('leveldb.num-files-at-level3'))
 
 The callback will be called when the destroy operation is complete, with a possible `error` argument.
 
-**Note:** `destroy()` is available via [LevelDOWN](https://github.com/rvagg/node-leveldown/) which you will have to install seperately, e.g.:
+**Note:** `destroy()` is available via [LevelDOWN](https://github.com/level/leveldown/) which you will have to install seperately, e.g.:
 
 ```js
 require('leveldown').destroy('./huge.db', function (err) { console.log('done!') })
@@ -532,7 +532,7 @@ A `repair()` can also be used to perform a compaction of the LevelDB log into ta
 
 The callback will be called when the repair operation is complete, with a possible `error` argument.
 
-**Note:** `repair()` is available via [LevelDOWN](https://github.com/rvagg/node-leveldown/) which you will have to install seperately, e.g.:
+**Note:** `repair()` is available via [LevelDOWN](https://github.com/level/leveldown/) which you will have to install seperately, e.g.:
 
 ```js
 require('leveldown').repair('./huge.db', function (err) { console.log('done!') })
@@ -581,7 +581,7 @@ A custom encoding may be provided by passing in an object as an value for `keyEn
 Extending LevelUP
 -----------------
 
-A list of <a href="https://github.com/rvagg/node-levelup/wiki/Modules"><b>Node.js LevelDB modules and projects</b></a> can be found in the wiki.
+A list of <a href="https://github.com/level/levelup/wiki/Modules"><b>Node.js LevelDB modules and projects</b></a> can be found in the wiki.
 
 When attempting to extend the functionality of LevelUP, it is recommended that you consider using [level-hooks](https://github.com/dominictarr/level-hooks) and/or [level-sublevel](https://github.com/dominictarr/level-sublevel). **level-sublevel** is particularly helpful for keeping additional, extension-specific, data in a LevelDB store. It allows you to partition a LevelUP instance into multiple sub-instances that each correspond to discrete namespaced key ranges.
 
@@ -591,7 +591,7 @@ Multi-process access
 
 LevelDB is thread-safe but is **not** suitable for accessing with multiple processes. You should only ever have a LevelDB database open from a single Node.js process. Node.js clusters are made up of multiple processes so a LevelUP instance cannot be shared between them either.
 
-See the <a href="https://github.com/rvagg/node-levelup/wiki/Modules"><b>wiki</b></a> for some LevelUP extensions, including [multilevel](https://github.com/juliangruber/multilevel), that may help if you require a single data store to be shared across processes.
+See the <a href="https://github.com/level/levelup/wiki/Modules"><b>wiki</b></a> for some LevelUP extensions, including [multilevel](https://github.com/juliangruber/multilevel), that may help if you require a single data store to be shared across processes.
 
 <a name="support"></a>
 Getting support
@@ -611,7 +611,7 @@ LevelUP 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 [CONTRIBUTING.md](https://github.com/rvagg/node-levelup/blob/master/CONTRIBUTING.md) file for more details.
+See the [CONTRIBUTING.md](https://github.com/level/levelup/blob/master/CONTRIBUTING.md) file for more details.
 
 ### Contributors
 

lib/batch.js

@@ -1,7 +1,7 @@
-/* Copyright (c) 2012-2014 LevelUP contributors
- * See list at <https://github.com/rvagg/node-levelup#contributing>
+/* Copyright (c) 2012-2015 LevelUP contributors
+ * See list at <https://github.com/level/levelup#contributing>
  * MIT License
- * <https://github.com/rvagg/node-levelup/blob/master/LICENSE.md>
+ * <https://github.com/level/levelup/blob/master/LICENSE.md>
  */
 
 var util          = require('./util')

lib/levelup.js

@@ -1,14 +1,15 @@
-/* Copyright (c) 2012-2014 LevelUP contributors
- * See list at <https://github.com/rvagg/node-levelup#contributing>
+/* Copyright (c) 2012-2015 LevelUP contributors
+ * See list at <https://github.com/level/levelup#contributing>
  * MIT License
- * <https://github.com/rvagg/node-levelup/blob/master/LICENSE.md>
+ * <https://github.com/level/levelup/blob/master/LICENSE.md>
  */
 
 var EventEmitter        = require('events').EventEmitter
   , inherits            = require('util').inherits
   , extend              = require('xtend')
   , prr                 = require('prr')
   , DeferredLevelDOWN   = require('deferred-leveldown')
+  , IteratorStream      = require('level-iterator-stream')
 
   , errors              = require('level-errors')
   , WriteError          = errors.WriteError
@@ -18,7 +19,6 @@ var EventEmitter        = require('events').EventEmitter
   , EncodingError       = errors.EncodingError
   , InitializationError = errors.InitializationError
 
-  , ReadStream          = require('./read-stream')
   , util                = require('./util')
   , Batch               = require('./batch')
   , Codec               = require('level-codec')
@@ -345,48 +345,21 @@ LevelUP.prototype.approximateSize = function (start_, end_, options, callback) {
 
 LevelUP.prototype.readStream =
 LevelUP.prototype.createReadStream = function (options) {
-  var self = this
   options = extend( {keys: true, values: true}, this.options, options)
 
   options.keyEncoding   = options.keyEncoding
   options.valueEncoding = options.valueEncoding
 
-  if (isDefined(options.start))
-    options.start = this._codec.encodeKey(options.start, [options])
-  if (isDefined(options.end))
-    options.end = this._codec.encodeKey(options.end, [options])
-  if (isDefined(options.gte))
-    options.gte = this._codec.encodeKey(options.gte, [options])
-  if (isDefined(options.gt))
-    options.gt = this._codec.encodeKey(options.gt, [options])
-  if (isDefined(options.lte))
-    options.lte = this._codec.encodeKey(options.lte, [options])
-  if (isDefined(options.lt))
-    options.lt = this._codec.encodeKey(options.lt, [options])
+  options = this._codec.encodeLtgt(options);
+  options.keyAsBuffer   = this._codec.keyAsBuffer(options)
+  options.valueAsBuffer = this._codec.valueAsBuffer(options)
+
   if ('number' !== typeof options.limit)
     options.limit = -1
 
-  options.keyAsBuffer   = this._codec.keyAsBuffer([options])
-  options.valueAsBuffer = this._codec.valueAsBuffer([options])
-
-  var makeData = options.keys && options.values
-    ? function (key, value) {
-        return {
-            key: self._codec.decodeKey(key, [options])
-          , value: self._codec.decodeValue(value, [options])
-        }
-      }
-    : options.keys
-    ? function (key) {
-        return self._codec.decodeKey(key, [options])
-      }
-    : options.values
-    ? function (_, value) {
-        return self._codec.decodeValue(value, [options])
-      }
-    : function () {}
-
-  return new ReadStream(this.db.iterator(options), options, makeData)
+  return new IteratorStream(this.db.iterator(options), extend(options, {
+    decoder: this._codec.createStreamDecoder(options)
+  }))
 }
 
 LevelUP.prototype.keyStream =