[Pkg-javascript-commits] [node-leveldown] 76/492: beefed up README
Andrew Kelley
andrewrk-guest at moszumanska.debian.org
Sun Jul 6 17:13:46 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 93923547621a566b62f92c5d454bb8fa83e4668e
Author: Rod Vagg <rod at vagg.org>
Date: Sun Nov 18 13:44:39 2012 +1100
beefed up README
---
README.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 163 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
index 66d6def..6ef2070 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,31 @@ Fast & simple storage - a Node.js-style LevelDB wrapper
**[LevelDB](http://code.google.com/p/leveldb/)** is a simple key/value data store built by Google, inspired by BigTable. It's used in Google Chrome and many other products. LevelDB supports arbitrary byte arrays as both keys and values, singular *get*, *put* and *delete* operations, *batched put and delete*, forward and reverse iteration and simple compression using the [Snappy](http://code.google.com/p/snappy/) algorithm which is optimised for speed over compression.
-
**LevelUP** aims to expose the features of LevelDB in a Node.js-friendly way. Both keys and values are treated as `Buffer` objects and are automatically converted using a specified `'encoding'`. LevelDB's iterators are exposed as a Node.js style object-`ReadStream` and writing can be peformed via an object-`WriteStream`.
+**LevelUP** is an **OPEN Open Source Project**, see the <a href="#contributing">Contributing</a> section to find out what this means.
+
+ * <a href="#platforms">Tested & supported platforms</a>
+ * <a href="#basic">Basic usage</a>
+ * <a href="#api">API</a>
+ * <a href="#events">Events</a>
+ * <a href="#json">JSON data</a>
+ * <a href="#considerations">Important considerations</a>
+ * <a href="#contributing">Contributing</a>
+ * <a href="#licence">Licence & copyright</a>
+
+
+<a name="platforms"></a>
+Tested & supported platforms
+----------------------------
+
+ * **Linux** (tested on Ubuntu)
+ * **Mac OS**
+ * **Solaris** (tested on SmartOS & Nodejitsu)
+
+**Windows** support is coming soon; see [issue #5](https://github.com/rvagg/node-levelup/issues/5) if you would like to help on that front.
+
+<a name="basic"></a>
Basic usage
-----------
@@ -38,8 +60,52 @@ db.put('name', 'LevelUP', function (err) {
})
```
+<a name="api"></a>
+## API
-### Options
+ * <a href="#ctor"><code><b>levelup()</b></code></a>
+ * <a href="#open"><code>db.<b>open()</b></code></a>
+ * <a href="#close"><code>db.<b>close()</b></code></a>
+ * <a href="#put"><code>db.<b>put()</b></code></a>
+ * <a href="#get"><code>db.<b>get()</b></code></a>
+ * <a href="#del"><code>db.<b>del()</b></code></a>
+ * <a href="#batch"><code>db.<b>batch()</b></code></a>
+ * <a href="#isOpen"><code>db.<b>isOpen()</b></code></a>
+ * <a href="#isClosed"><code>db.<b>isClosed()</b></code></a>
+ * <a href="#readStream"><code>db.<b>readStream()</b></code></a>
+ * <a href="#keyStream"><code>db.<b>keyStream()</b></code></a>
+ * <a href="#valueStream"><code>db.<b>valueStream()</b></code></a>
+ * <a href="#writeStream"><code>db.<b>writeStream()</b></code></a>
+
+
+--------------------------------------------------------
+<a name="ctor"></a>
+### levelup(location[, options[, callback]])
+<code>levelup()</code> is the main entry point for creating a new LevelUP instance and opening the underlying store with LevelDB.
+
+This function returns a new instance of LevelUP and will also initiate an <a href="#open"><code>open()</code></a> operation. Opening the database is an asynchronous operation which will trigger your callback if you provide one. The callback should take the form: `function (err, db) {}` where the `db` is the LevelUP instance. If you don't provide a callback, any read & write operations are simply queued internally until the database is fully opened.
+
+This leads to two alternative ways of managing a new LevelUP instance:
+
+```js
+levelup(location, options, function (err, db) {
+ if (err) throw err
+ db.get('foo', function (err, value) {
+ if (err) return console.log('foo does not exist')
+ console.log('got foo =', value)
+ })
+})
+
+// vs the equivalent:
+
+var db = levelup(location, options) // will throw if an error occurs
+db.get('foo', function (err, value) {
+ if (err) return console.log('foo does not exist')
+ console.log('got foo =', value)
+})
+```
+
+#### `options`
`levelup()` takes an optional options object as its second argument; the following properties are accepted:
@@ -56,10 +122,57 @@ db.put('name', 'LevelUP', function (err) {
Additionally, each of the main interface methods accept an optional options object that can be used to override `encoding` (or `keyEncoding` & `valueEncoding`).
+--------------------------------------------------------
+<a name="open"></a>
+### db.open([callback])
+<code>open()</code> opens the underlying LevelDB store. In general **you should never need to call this method directly** as it's automatically called by <a href="#ctor"><code>levelup()</code></a>.
+
+However, it is possible to *reopen* a database after it has been closed with <a href="#close"><code>close()</code></a>; although this is not generally advised.
+
+--------------------------------------------------------
+<a name="close"></a>
+### db.close([callback])
+<code>close()</code> closes the underlying LevelDB store. The callback will receive any error encountered during closing as the first argument.
+
+You should always clean up your LevelUP instance by calling `close()` when you no longer need it to free up resources. A LevelDB store cannot be opened by multiple instances of LevelDB/LevelUP simultaneously.
+
+--------------------------------------------------------
+<a name="put"></a>
+### db.put(key, value[, options][, callback])
+<code>put()</code> is the primary method for inserting data into the store. Both the `key` and `value` can be arbitrary data objects.
+
+The callback argument is optional but if you don't provide one and an error occurs then expect the error to be thrown.
-### Batch operations
+#### `options`
-For faster write operations, the `batch()` method can be used to submit an array 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.
+Encoding of the `key` and `value` objects will adhere to `encoding` option(s) provided to <a href="#ctor"><code>levelup()</code></a>, although you can provide alternative encoding settings in the options for `put()` (it's recommended that stay consistent in your encoding of keys and values in a single store).
+
+If you provide a `'sync'` value of `true` in your `options` object, LevelDB will perform a synchronous write of the data; although the operation will be asynchronous as far as Node is concerned. Normally, LevelDB passes the data to the operating system for writing and returns immediately, however a synchronous write will use `fsync()` or equivalent so your callback won't be triggered until the data is actually on disk. Synchronous filesystem writes are **significantly** slower than async [...]
+
+--------------------------------------------------------
+<a name="get"></a>
+### db.get(key[, options][, callback])
+<code>get()</code> is the primary method for fetching data from the store. The `key` can be an arbitrary data object but if it doesn't exist in the store then the callback will receive an error as its first argument.
+
+#### `options`
+
+Encoding of the `key` objects will adhere to `encoding` option(s) provided to <a href="#ctor"><code>levelup()</code></a>, although you can provide alternative encoding settings in the options for `et()` (it's recommended that stay consistent in your encoding of keys and values in a single store).
+
+--------------------------------------------------------
+<a name="del"></a>
+### db.del(key[, options][, callback])
+<code>del()</code> is the primary method for removing data from the store. The `key` can be an arbitrary data object but if it doesn't exist in the store then the callback will receive an error as its first argument.
+
+#### `options`
+
+Encoding of the `key` objects will adhere to `encoding` option(s) provided to <a href="#ctor"><code>levelup()</code></a>, although you can provide alternative encoding settings in the options for `et()` (it's recommended that stay consistent in your encoding of keys and values in a single store).
+
+A `'sync'` option can also be passed, see <a href="#put"><code>put()</code></a> for details on how this works.
+
+--------------------------------------------------------
+<a name="batch"></a>
+### db.batch(array[, options][, callback])
+<code>batch()</code> can be used for very fast bulk-write operations (both *put* and *delete*). The `array` 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.
```js
var ops = [
@@ -76,11 +189,39 @@ db.batch(ops, function (err) {
})
```
+
+#### `options`
+
+See <a href="#put"><code>put()</code></a> for a discussion on the `options` object. You can overwrite default `key` and `value` encodings and also specify the use of `sync` filesystem operations.
+
Streams
-------
+--------------------------------------------------------
+<a name="isOpen"></a>
+### db.isOpen()
-### ReadStream
+A LevelUP object can be in one of the following states:
+
+ * *"new"* - newly created, not opened or closed
+ * *"opening"* - waiting for the database to be opened
+ * *"open"* - successfully opened the database, available for use
+ * *"closing"* - waiting for the database to be closed
+ * *"closed"* - database has been successfully closed, should not be used
+
+`isOpen()` will return `true` only when the state is "open".
+
+--------------------------------------------------------
+<a name="isClosed"></a>
+### db.isClosed()
+
+*See <a href="#put"><code>isOpen()</code></a>*
+
+`isClosed()` will return `true` only when the state is "closing" *or* "closed", it can be useful for determining if read and write operations are permissible.
+
+--------------------------------------------------------
+<a name="readStream"></a>
+### db.readStream()
You can obtain a **ReadStream** of the full database by calling the `readStream()` method. The resulting stream is a complete Node.js-style [Readable Stream](http://nodejs.org/docs/latest/api/stream.html#stream_readable_stream) where `'data'` events emit objects with `'key'` and `'value'` pairs.
@@ -114,8 +255,9 @@ Additionally, you can supply an options object as the first parameter to `readSt
* `'values'`: a boolean (defaults to `true`) to indicate 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.
-
-### KeyStream
+--------------------------------------------------------
+<a name="keyStream"></a>
+### db.keyStream()
A **KeyStream** is a **ReadStream** where the `'data'` events are simply the keys from the database so it can be used like a traditional stream rather than an object stream.
@@ -134,8 +276,9 @@ db.readStream({ keys: true, values: false })
})
```
-
-### ValueStream
+--------------------------------------------------------
+<a name="valyeStream"></a>
+### db.valueStream()
A **ValueStream** is a **ReadStream** where the `'data'` events are simply the values from the database so it can be used like a traditional stream rather than an object stream.
@@ -154,8 +297,9 @@ db.readStream({ keys: false, values: true })
})
```
-
-### WriteStream
+--------------------------------------------------------
+<a name="writeStream"></a>
+### db.writeStream()
A **WriteStream** can be obtained by calling the `writeStream()` method. The resulting stream is a complete Node.js-style [Writable Stream](http://nodejs.org/docs/latest/api/stream.html#stream_writable_stream) which accepts objects with `'key'` and `'value'` pairs on its `write()` method. Tce WriteStream will buffer writes and submit them as a `batch()` operation where the writes occur on the same event loop tick, otherwise they are treated as simple `put()` operations.
@@ -177,7 +321,7 @@ db.writeStream()
The standard `write()`, `end()`, `destroy()` and `destroySoon()` methods are implemented on the WriteStream. `'drain'`, `'error'`, `'close'` and `'pipe'` events are emitted.
-### Pipes and Node Stream compatibility
+#### Pipes and Node Stream compatibility
A ReadStream can be piped directly to a WriteStream, allowing for easy copying of an entire database. A simple `copy()` operation is included in LevelUP that performs exactly this on two open databases:
@@ -191,7 +335,7 @@ The ReadStream is also [fstream](https://github.com/isaacs/fstream)-compatible w
KeyStreams and ValueStreams can be treated like standard streams of raw data. If `'encoding'` is set to `'binary'` the `'data'` events will simply be standard Node `Buffer` objects straight out of the data store.
-
+<a name="events"></a>
Events
------
@@ -205,22 +349,19 @@ LevelUP emits events when the callbacks to the corresponding methods are called.
If you do not pass a callback to an async function, and there is an error, LevelUP will `emit('error', err)` instead.
-JSON
-----
+<a name="json"></a>
+JSON data
+---------
You specify `'json'` encoding for both keys and/or values, you can then supply JavaScript objects to LevelUP and receive them from all fetch operations, including ReadStreams. LevelUP will automatically *stringify* your objects and store them as *utf8* and parse the strings back into objects before passing them back to you.
+<a name="considerations"></a>
Important considerations
------------------------
* 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.
-TODO
-----
-
-* Windows support (see [issue #5](https://github.com/rvagg/node-levelup/issues/5) if you would like to help)
-* Benchmarks
-
+<a name="contributing"></a>
Contributing
------------
@@ -237,6 +378,7 @@ See the [CONTRIBUTING.md](https://github.com/rvagg/node-levelup/blob/master/CONT
* Jake Verbaten - [GitHub/raynos](https://github.com/raynos) - [Twitter/@raynos2](https://twitter.com/Raynos2)
* Dominic Tarr - [GitHub/dominictarr](https://github.com/dominictarr) - [Twitter/@dominictarr](https://twitter.com/dominictarr)
+<a name="licence"></a>
Licence & copyright
-------------------
--
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