add iterator.seek (#237)

README.md

@@ -138,6 +138,7 @@ A range option that is either an empty buffer, an empty string or `null` will be
 Provided with the current instance of `AbstractLevelDOWN` by default.
 
 ### `AbstractIterator#_next(callback)`
+### `AbstractIterator#_seek(target)`
 ### `AbstractIterator#_end(callback)`
 
 ### `AbstractChainedBatch`

abstract-iterator.js

@@ -36,6 +36,22 @@ AbstractIterator.prototype._next = function (callback) {
   process.nextTick(callback)
 }
 
+AbstractIterator.prototype.seek = function (target) {
+  if (this._ended) {
+    throw new Error('cannot call seek() after end()')
+  }
+  if (this._nexting) {
+    throw new Error('cannot call seek() before next() has completed')
+  }
+
+  target = this.db._serializeKey(target)
+  this._seek(target)
+}
+
+AbstractIterator.prototype._seek = function (callback) {
+  process.nextTick(callback)
+}
+
 AbstractIterator.prototype.end = function (callback) {
   if (typeof callback !== 'function') {
     throw new Error('end() requires a callback argument')

test.js

@@ -620,6 +620,31 @@ test('test serialization extensibility (batch array is not mutated)', function (
   t.equal(op.value, 'nope', 'did not mutate input value')
 })
 
+test('test serialization extensibility (iterator seek)', function (t) {
+  t.plan(3)
+
+  var spy = sinon.spy()
+  var TestIterator = implement(AbstractIterator, { _seek: spy })
+
+  var Test = implement(AbstractLevelDOWN, {
+    _iterator: function () {
+      return new TestIterator(this)
+    },
+    _serializeKey: function (key) {
+      t.equal(key, 'target')
+      return 'serialized'
+    }
+  })
+
+  var test = new Test('foobar')
+  var it = test.iterator()
+
+  it.seek('target')
+
+  t.equal(spy.callCount, 1, 'got _seek() call')
+  t.equal(spy.getCall(0).args[0], 'serialized', 'got expected target argument')
+})
+
 test('.status', function (t) {
   t.test('empty prototype', function (t) {
     var Test = implement(AbstractLevelDOWN)