diff --git a/README.md b/README.md
index 46ab31a3..1686cbd4 100644
--- a/README.md
+++ b/README.md
@@ -51,14 +51,23 @@ If you don't want to use the prebuilt binary for the platform you are installing
* [db.put()](#leveldown_put)
* [db.get()](#leveldown_get)
* [db.del()](#leveldown_del)
-* [db.batch()](#leveldown_batch)
+* [db.batch() _(array form)_](#leveldown_batch)
+* [db.batch() _(chained form)_](#leveldown_chainedbatch)
* [db.approximateSize()](#leveldown_approximateSize)
* [db.compactRange()](#leveldown_compactRange)
* [db.getProperty()](#leveldown_getProperty)
* [db.iterator()](#leveldown_iterator)
-* [iterator.next()](#iterator_next)
-* [iterator.seek()](#iterator_seek)
-* [iterator.end()](#iterator_end)
+* [chainedBatch](#chainedbatch)
+ * [chainedBatch.put()](#chainedbatch_put)
+ * [chainedBatch.del()](#chainedbatch_del)
+ * [chainedBatch.clear()](#chainedbatch_clear)
+ * [chainedBatch.write()](#chainedbatch_write)
+ * [chainedBatch.db](#chainedbatch_db)
+* [iterator](#iterator)
+ * [iterator.next()](#iterator_next)
+ * [iterator.seek()](#iterator_seek)
+ * [iterator.end()](#iterator_end)
+ * [iterator.db](#iterator_db)
* [leveldown.destroy()](#leveldown_destroy)
* [leveldown.repair()](#leveldown_repair)
@@ -152,18 +161,24 @@ The only property currently available on the `options` object is `sync` *(boolea
The `callback` function will be called with no arguments if the operation is successful or with a single `error` argument if the operation failed for any reason.
-### `db.batch(operations[, options], callback)`
-batch() is an instance method on an existing database object. Used for very fast bulk-write operations (both *put* and *delete*). The `operations` argument should be an `Array` containing a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside LevelDB.
+### `db.batch(operations[, options], callback)` _(array form)_
-Each operation is contained in an object having the following properties: `type`, `key`, `value`, where the *type* is either `'put'` or `'del'`. In the case of `'del'` the `'value'` property is ignored. Any entries with a `'key'` of `null` or `undefined` will cause an error to be returned on the `callback`. Any entries where the *type* is `'put'` that have a `'value'` of `undefined`, `null`, `[]`, `''` or `Buffer.alloc(0)` will be stored as a zero-length character array and therefore be fetched during reads as either `''` or `Buffer.alloc(0)` depending on how they are requested.
+Perform multiple _put_ and/or _del_ operations in bulk. The `operations` argument must be an `Array` containing a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation.
-See [`levelup`](https://github.com/level/levelup#batch) for full documentation on how this works in practice.
+Each operation is contained in an object having the following properties: `type`, `key`, `value`, where the `type` is either `'put'` or `'del'`. In the case of `'del'` the `value` property is ignored.
-#### `options`
+Any entries where the `key` or `value` (in the case of `'put'`) is `null` or `undefined` will cause an error to be returned on the `callback`. Any entries where the `type` is `'put'` that have a `value` of `[]`, `''` or `Buffer.alloc(0)` will be stored as a zero-length character array and therefore be fetched during reads as either `''` or `Buffer.alloc(0)` depending on how they are requested. See [`levelup`](https://github.com/level/levelup#batch) for full documentation on how this works in practice.
-The only property currently available on the `options` object is `sync` *(boolean, default: `false`)*. See leveldown#put() for details about this option.
+The optional `options` argument may contain:
-The `callback` function will be called with no arguments if the operation is successful or with a single `error` argument if the operation failed for any reason.
+- `sync` *(boolean, default: `false`)*. See [`db.put()`](#leveldown_put) for details about this option.
+
+The `callback` function will be called with no arguments if the batch is successful or with an `Error` if the batch failed for any reason.
+
+
+### `db.batch()` _(chained form)_
+
+Returns a new [`chainedBatch`](#chainedbatch) instance.
### `db.approximateSize(start, end, callback)`
@@ -194,12 +209,9 @@ Currently, the only valid properties are:
* 'leveldb.sstables': returns a multi-line string describing all of the *sstables* that make up contents of the current database.
-### `iterator = db.iterator([options])`
-iterator() is an instance method on an existing database object. It returns a new **Iterator** instance.
+### `db.iterator([options])`
-#### `options`
-
-The optional `options` object may contain:
+Returns a new [`iterator`](#iterator) instance. The optional `options` object may contain:
* `gt` (greater than), `gte` (greater than or equal) define the lower bound of the values to be fetched and will determine the starting point where `reverse` is *not* `true`. Only records where the key is greater than (or equal to) this option will be included in the range. When `reverse` is `true` the order will be reversed, but the records returned will be the same.
@@ -221,8 +233,44 @@ The optional `options` object may contain:
* `valueAsBuffer` *(boolean, default: `true`)*: Used to determine whether to return the `value` of each entry as a string or a Buffer.
+
+### `chainedBatch`
+
+
+#### `chainedBatch.put(key, value)`
+
+Queue a `put` operation on this batch. This may throw if `key` or `value` is invalid, following the same rules as the [array form of `db.batch()`](#leveldown_batch).
+
+
+#### `chainedBatch.del(key)`
+
+Queue a `del` operation on this batch. This may throw if `key` is invalid.
+
+
+#### `chainedBatch.clear()`
+
+Clear all queued operations on this batch.
+
+
+#### `chainedBatch.write([options, ]callback)`
+
+Commit the queued operations for this batch. All operations will be written atomically, that is, they will either all succeed or fail with no partial commits.
+
+The optional `options` argument may contain:
+
+- `sync` *(boolean, default: `false`)*. See [`db.put()`](#leveldown_put) for details about this option.
+
+The `callback` function will be called with no arguments if the batch is successful or with an `Error` if the batch failed for any reason. After `write` has been called, no further operations are allowed.
+
+
+#### `chainedBatch.db`
+
+A reference to the `db` that created this chained batch.
+
+### `iterator`
+
-### `iterator.next(callback)`
+#### `iterator.next(callback)`
next() is an instance method on an existing iterator object, used to increment the underlying LevelDB iterator and return the entry at that location.
the `callback` function will be called with no arguments in any of the following situations:
@@ -239,15 +287,20 @@ Otherwise, the `callback` function will be called with the following 3 arguments
* `value` - either a string or a Buffer depending on the `valueAsBuffer` argument when the `iterator()` was called.
-### `iterator.seek(key)`
+#### `iterator.seek(key)`
seek() is an instance method on an existing iterator object, used to seek the underlying LevelDB iterator to a given key.
By calling seek(key), subsequent calls to next(cb) will return key/values larger or smaller than `key`, based on your reverse setting in the iterator constructor.
-### `iterator.end(callback)`
+#### `iterator.end(callback)`
end() is an instance method on an existing iterator object. The underlying LevelDB iterator will be deleted and the `callback` function will be called with no arguments if the operation is successful or with a single `error` argument if the operation failed for any reason.
+
+#### `iterator.db`
+
+A reference to the `db` that created this iterator.
+
### `leveldown.destroy(location, callback)`
destroy() is used to completely remove an existing LevelDB database directory. You can use this function in place of a full directory *rm* if you want to be sure to only remove LevelDB-related files. If the directory only contains LevelDB files, the directory itself will be removed as well. If there are additional, non-LevelDB files in the directory, those files, and the directory, will be left alone.
diff --git a/chained-batch.js b/chained-batch.js
index c6195b64..0bd9a673 100644
--- a/chained-batch.js
+++ b/chained-batch.js
@@ -20,12 +20,6 @@ ChainedBatch.prototype._clear = function () {
}
ChainedBatch.prototype._write = function (options, callback) {
- // TODO (ensure docs covers the following)
- // Note that we're passing in options here, which we didn't do before. We
- // must do this so we can use the `sync` property, which we didn't handle before
- // since we never passed in an object at time of creation (bug) (the previous c++
- // used to assume we did this from the js side from the ChainedBatch()
- // constructor).
binding.batch_write(this.context, options, callback)
}