[Pkg-javascript-commits] [node-leveldown] 233/492: readme update to reflect current code
Andrew Kelley
andrewrk-guest at moszumanska.debian.org
Sun Jul 6 17:14:02 UTC 2014
This is an automated email from the git hooks/post-receive script.
andrewrk-guest pushed a commit to annotated tag rocksdb-0.10.1
in repository node-leveldown.
commit 76e93e9513d7f364560d0cddbcee73794cd2f403
Author: Rod Vagg <rod at vagg.org>
Date: Sun Feb 24 14:20:06 2013 +1100
readme update to reflect current code
---
README.md | 133 +++++++++++++++++++++++++++++---------------------------------
1 file changed, 63 insertions(+), 70 deletions(-)
diff --git a/README.md b/README.md
index ef8d4cf..5f439ac 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,21 @@
LevelDOWN
=========
-A Node.js LevelDB binding (currently being extracted from LevelUP)
+A Low-level Node.js LevelDB binding
-------------------------
[](http://travis-ci.org/rvagg/node-leveldown)
-## READ THIS FIRST
+LevelDOWN was extracted from [LevelUP](https://github.com/rvagg/node-levelup) and now serves as a stand-alone binding for LevelDB.
-LevelDOWN is currently undergoing API development to prepare it for general use. Version 0.0.0 represents the API as it has been used internally within [LevelUP](https://github.com/rvagg/node-levelup) but this API is not ideal for public consumption.
+It is **strongly recommended** that you use LevelUP in preference to LevelDOWN unless you have measurable performance reasons to do so. LevelUP is optimised for usability and safety. Although we are working to improve the safety of the LevelDOWN interface it is still easy to crash your Node process if you don't do things in just the right way.
-If you wish to contribute towards improving this API, please submit your suggestions in the form of a pull request against *this* README.md file, highlighting changes you believe ought to be made; discussion will then ensue!
-
-LevelDOWN is stable for general use as long as you are careful what arguments you provide (LevelUP sanitises most inputs prior to feeing them to the binding). You also need to be aware of the ongoing work on the API. Each time a breaking change is made to the API, the *Major* version will be incremented (i.e. where [semver](http://semver.org) specifies Major.Minor.Patch), so be careful with your npm dependencies!
-
-In general, the current API is fairly brittle and each method must be fed the right number and type of arguments; failing to adhere to the requirements of each method call may result in process death. Making the API more resilient will be a top priority.
-
-The other major priority for API-change will be to make it as easy and natural to use without unnecessary fluff (the fluff can go in LevelUP if it's really needed). The API will be as minimal as possible while still providing enough async access to LevelDB for efficient use.
+See the section on <a href="#safety">safety</a> below for details of known unsafe operations with LevelDOWN.
<a name="api"></a>
## API
* <a href="#ctor"><code><b>leveldown()</b></code></a>
- * <a href="#createIterator"><code><b>createIterator()</b></code></a>
* <a href="#leveldown_open"><code><b>leveldown#open()</b></code></a>
* <a href="#leveldown_close"><code><b>leveldown#close()</b></code></a>
* <a href="#leveldown_put"><code><b>leveldown#put()</b></code></a>
@@ -30,6 +23,7 @@ The other major priority for API-change will be to make it as easy and natural t
* <a href="#leveldown_del"><code><b>leveldown#del()</b></code></a>
* <a href="#leveldown_batch"><code><b>leveldown#batch()</b></code></a>
* <a href="#leveldown_approximateSize"><code><b>leveldown#approximateSize()</b></code></a>
+ * <a href="#leveldown_iterator"><code><b>leveldown#iterator()</b></code></a>
* <a href="#iterator_next"><code><b>iterator#next()</b></code></a>
* <a href="#iterator_end"><code><b>iterator#end()</b></code></a>
@@ -39,44 +33,15 @@ The other major priority for API-change will be to make it as easy and natural t
### leveldown(location)
<code>leveldown()</code> returns a new **LevelDOWN** instance. `location` is a String pointing to the LevelDB location to be opened.
-The `location` argument is available as a read-only property on the returned LevelUP instance.
-
---------------------------------------------------------
-<a name="createIterator"></a>
-### leveldown.createIterator(database, options)
-<code>createIterator()</code> returns a new **Iterator** instance for the given `database` instance. Both arguments are required.
-
-#### `options`
-
-The `options` object may contain:
-
-* `'start'`: the key you wish to start the read at. By default it will start at the beginning of the store. Note that the *start* doesn't have to be an actual key that exists, LevelDB will simply find the *next* key, greater than the key you provide.
-
-* `'end'`: the key you wish to end the read on. By default it will continue until the end of the store. Again, the *end* doesn't have to be an actual key as an (inclusive) `<=`-type operation is performed to detect the end. You can also use the `destroy()` method instead of supplying an `'end'` parameter to achieve the same effect.
-
-* `'reverse'` *(boolean, default: `false`)*: a boolean, set to true if you want the stream to go in reverse order. Beware that due to the way LevelDB works, a reverse seek will be slower than a forward seek.
-
-* `'keys'` *(boolean, default: `true`)*: whether the `'data'` event should contain keys. If set to `true` and `'values'` set to `false` then `'data'` events will simply be keys, rather than objects with a `'key'` property. Used internally by the `keyStream()` method.
-
-* `'values'` *(boolean, default: `true`)*: whether the `'data'` event should contain values. If set to `true` and `'keys'` set to `false` then `'data'` events will simply be values, rather than objects with a `'value'` property. Used internally by the `valueStream()` method.
-
-* `'limit'` *(number, default: `-1`)*: limit the number of results collected by this stream. This number represents a *maximum* number of results and may not be reached if you get to the end of the store or your `'end'` value first. A value of `-1` means there is no limit.
-
-* `'fillCache'` *(boolean, default: `false`)*: wheather LevelDB's LRU-cache should be filled with data read.
-
-* `'keyAsBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `key` of each entry as a `String` or a Node.js `Buffer` object. Note that converting from a `Buffer` to a `String` incurs a cost so if you need a `String` (and the `value` can legitimately become a UFT8 string) then you should fetch it as one.
-
-* `'valueAsBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `value` of each entry as a `String` or a Node.js `Buffer` object.
-
--------------------------------------------------------
<a name="leveldown_open"></a>
-### leveldown#open(options, callback)
+### leveldown#open([options, ]callback)
<code>open()</code> is an instance method on an existing database object.
#### `options`
-The `options` object may contain:
+The optional `options` argument may contain:
* `'createIfMissing'` *(boolean, default: `true`)*: If `true`, will initialise an empty database at the specified location if one doesn't already exist. If `false` and a database doesn't exist you will receive an error in your `open()` callback and your database won't open.
@@ -88,21 +53,19 @@ The `options` object may contain:
The `callback` function will be called with no arguments when the database has been successfully opened, or with a single `error` argument if the open operation failed for any reason.
-All 3 arguments are required.
--------------------------------------------------------
<a name="leveldown_close"></a>
### leveldown#close(callback)
<code>close()</code> is an instance method on an existing database object. The underlying LevelDB database will be closed 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.
-The `callback` argument is required.
--------------------------------------------------------
<a name="leveldown_put"></a>
-### leveldown#put(key, value, options, callback)
+### leveldown#put(key, value[, options], callback)
<code>put()</code> is an instance method on an existing database object, used to store new entries, or overwrite existing entries in the LevelDB store.
-The `key` and `value` objects may either be `String`s or Node.js `Buffer` objects and cannot be `undefined` or `null`.
+The `key` and `value` objects may either be `String`s or Node.js `Buffer` objects and cannot be `undefined` or `null`. Other object types are converted to JavaScript `String`s with the `toString()` method and the resulting `String` *may not* be a zero-length. A richer set of data-types are catered for in LevelUP.
#### `options`
@@ -110,35 +73,31 @@ The only property currently available on the `options` object is `'sync'` *(bool
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.
-All 4 arguments are required.
-
--------------------------------------------------------
<a name="leveldown_get"></a>
-### leveldown#get(key, options, callback)
+### leveldown#get(key[, options], callback)
<code>get()</code> is an instance method on an existing database object, used to fetch individual entries from the LevelDB store.
-The `key` object may either be a `String` or a Node.js `Buffer` object and cannot be `undefined` or `null`.
+The `key` object may either be a `String` or a Node.js `Buffer` object and cannot be `undefined` or `null`. Other object types are converted to JavaScript `String`s with the `toString()` method and the resulting `String` *may not* be a zero-length. A richer set of data-types are catered for in LevelUP.
#### `options`
-The `options` object may contain:
+The optional `options` object may contain:
* `'fillCache'` *(boolean, default: `true`)*: LevelDB will by default fill the in-memory LRU Cache with data from a call to get. Disabling this is done by setting `fillCache` to `false`.
-* `'asBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `value` of the entry as a `String` or a Node.js `Buffer` object. Note that converting from a `Buffer` to a `String` incurs a cost so if you need a `String` (and the `value` can legitimately become a UFT8 string) then you should fetch it as one.
+* `'asBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `value` of the entry as a `String` or a Node.js `Buffer` object. Note that converting from a `Buffer` to a `String` incurs a cost so if you need a `String` (and the `value` can legitimately become a UFT8 string) then you should fetch it as one with `asBuffer: true` and you'll avoid this conversion cost.
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.
-All 3 arguments are required.
-
--------------------------------------------------------
<a name="leveldown_del"></a>
-### leveldown#del(key, options, callback)
+### leveldown#del(key[, options], callback)
<code>del()</code> is an instance method on an existing database object, used to delete entries from the LevelDB store.
-The `key` object may either be a `String` or a Node.js `Buffer` object and cannot be `undefined` or `null`.
+The `key` object may either be a `String` or a Node.js `Buffer` object and cannot be `undefined` or `null`. Other object types are converted to JavaScript `String`s with the `toString()` method and the resulting `String` *may not* be a zero-length. A richer set of data-types are catered for in LevelUP.
#### `options`
@@ -146,13 +105,11 @@ The only property currently available on the `options` object is `'sync'` *(bool
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.
-All 3 arguments are required.
-
--------------------------------------------------------
<a name="leveldown_batch"></a>
-### leveldown#batch(operations, options, callback)
-<code>batch()</code> is an instance method on an existing database object. Used for very fast bulk-write operations (both *put* and *delete*). The `operations` argument should contain a list of operations to be executed sequentially. 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. See [LevelUP](https://github.com/rvagg/node-levelup#bat [...]
+### leveldown#batch(operations[, options], callback)
+<code>batch()</code> 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. 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. See [LevelUP](https://github.com/rvagg [...]
#### `options`
@@ -160,9 +117,7 @@ The only property currently available on the `options` object is `'sync'` *(bool
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.
-All 3 arguments are required.
-Callback
--------------------------------------------------------
<a name="leveldown_approximateSize"></a>
### leveldown#approximateSize(start, end, callback)
@@ -172,34 +127,72 @@ The `start` and `end` parameters may be either `String` or Node.js `Buffer` obje
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.
-All 3 arguments are required.
+
+--------------------------------------------------------
+<a name="createIterator"></a>
+### leveldown#iterator([options])
+<code>iterator()</code> is an instance method on an existing database object. It returns a new **Iterator** instance.
+
+#### `options`
+
+The optional `options` object may contain:
+
+* `'start'`: the key you wish to start the read at. By default it will start at the beginning of the store. Note that the *start* doesn't have to be an actual key that exists, LevelDB will simply find the *next* key, greater than the key you provide.
+
+* `'end'`: the key you wish to end the read on. By default it will continue until the end of the store. Again, the *end* doesn't have to be an actual key as an (inclusive) `<=`-type operation is performed to detect the end. You can also use the `destroy()` method instead of supplying an `'end'` parameter to achieve the same effect.
+
+* `'reverse'` *(boolean, default: `false`)*: a boolean, set to true if you want the stream to go in reverse order. Beware that due to the way LevelDB works, a reverse seek will be slower than a forward seek.
+
+* `'keys'` *(boolean, default: `true`)*: whether the callback to the `next()` method should receive a non-null `key`. There is a small efficiency gain if you ultimately don't care what the keys are as they don't need to be converted and copied into JavaScript.
+
+* `'values'` *(boolean, default: `true`)*: whether the callback to the `next()` method should receive a non-null `value`. There is a small efficiency gain if you ultimately don't care what the values are as they don't need to be converted and copied into JavaScript.
+
+* `'limit'` *(number, default: `-1`)*: limit the number of results collected by this iterator. This number represents a *maximum* number of results and may not be reached if you get to the end of the store or your `'end'` value first. A value of `-1` means there is no limit.
+
+* `'fillCache'` *(boolean, default: `false`)*: wheather LevelDB's LRU-cache should be filled with data read.
+
+* `'keyAsBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `key` of each entry as a `String` or a Node.js `Buffer` object. Note that converting from a `Buffer` to a `String` incurs a cost so if you need a `String` (and the `value` can legitimately become a UFT8 string) then you should fetch it as one.
+
+* `'valueAsBuffer'` *(boolean, default: `true`)*: Used to determine whether to return the `value` of each entry as a `String` or a Node.js `Buffer` object.
--------------------------------------------------------
<a name="iterator_next"></a>
-### iterator#next(endCallback, nextCallback)
+### iterator#next(callback)
<code>next()</code> is an instance method on an existing iterator object, used to increment the underlying LevelDB iterator and return the entry at that location.
-The `endCallback` function will be called with no arguments in any of the following situations:
+the `callback` function will be called with no arguments in any of the following situations:
* the iterator comes to the end of the store
* the `end` key has been reached; or
* the `limit` has been reached
-Otherwise, `nextCallback` will be called with the following 3 arguments:
+Otherwise, the `callback` function will be called with the following 3 arguments:
-* `null`
+* `error` - any error that occurs while incrementing the iterator.
* `key` - either a `String` or a Node.js `Buffer` object depending on the `keyAsBuffer` argument when the `createIterator()` was called.
* `value` - either a `String` or a Node.js `Buffer` object depending on the `valueAsBuffer` argument when the `createIterator()` was called.
-Both `endCallback` and `nextCallback` arguments are required.
--------------------------------------------------------
<a name="iterator_end"></a>
### iterator#end(callback)
<code>end()</code> 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.
-The `callback` argument is required.
+
+<a name="safety"></a>
+Safety
+------
+
+### Database state
+
+Currently LevelDOWN does not track the state of the underlying LevelDB instance. This means that calling `open()` on an already open database may result in an error. Likewise, calling any other operation on a non-open database may result in an error.
+
+LevelUP currently tracks and manages state and will prevent out-of-state operations from being send to LevelDOWN. If you use LevelDOWN directly then you must track and manage state.
+
+### Iterators
+
+You should make sure to **always** `end()` your LevelDOWN Iterators, it will not be done for you, even on a `close()` of the database your Iterator belongs to. If you don't `end()` then the underlying resources aren't cleaned up and this will result in a Node process death.
<a name="contributing"></a>
@@ -236,4 +229,4 @@ Copyright (c) 2012-2013 LevelDOWN contributors (listed above).
LevelDOWN is licensed under an MIT +no-false-attribs license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.
-*LevelDOWN builds on the excellent work of the LevelDB and Snappy teams from Google and additional contributors. LevelDB and Snappy are both issued under the [New BSD Licence](http://opensource.org/licenses/BSD-3-Clause).*
+*LevelDOWN builds on the excellent work of the LevelDB and Snappy teams from Google and additional contributors. LevelDB and Snappy are both issued under the [New BSD Licence](http://opensource.org/licenses/BSD-3-Clause).*
\ No newline at end of file
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-leveldown.git
More information about the Pkg-javascript-commits
mailing list