riak-dc

riak-dc
=======

So, Basho does not have an official javascript interface to Riak. However, there
is this riak-js thing. I found it to be poorly documented,
and the interface was not suitable for very small programs (I write command-line
tools, rather than web-front-end-ish type things). I wanted something
synchronous, something simple, that wouldn't take up too much space in my code.

Accordingly, I wrote a tiny little wrapper around http, and here is the product.

It is my hope that the code behind this never actually exceeds the length of the
documentation & test suite, and that anyone should be able to just
npm install riak-dc and be coding against a Riak quickly.

$3

* Riak.init( hostname, port, proxy )
- Takes two arguments: hostname, and port, which are what you would
expect them to be. Note that this call is optional, and defaults are localhost
and 8098, respectively. If you wish to use an http proxy, you may pass an
object that looks like { host: 'localhost', port: '3128' } and riak-dc
will attempt to use this proxy for all calls. You may also set the
environment variables HTTP_PROXY_HOST and HTTP_PROXY_PORT. Using init()
will override any environment variables you may have set.

* Riak.ping()
- Takes no arguments, returns a true value if the server gives a 200 response,
and something false otherwise.

* Riak.get_keys( bucket )
- Takes a single argument, the name of the bucket you'd like keys
for, and returns a promise to a list of the keys in that bucket.
Note that Riak does not care if this bucket does not exist. If you ask for
the keys from a non-existent bucket, Riak will dutifully tell you the list of
keys in that bucket is [], which is what get_keys will return to you here.

* Riak.get_tuple( bucket, key )
- Takes two arguments, the name of the bucket and key you wish to
have the value for. This is returned as a promised object, and will be whatever
Riak has stored. Typically this is JSON, but you will need to parse that
yourself (such as JSON.parse(tuple)), as it can be anything.
In the event that Riak has stored a 0-byte tuple: (that is, the bucket/key pair
are valid, the HTTP request returns 200, but the record is empty), you will
receive an Error. This is not strictly an error condition, but it is helpful to
know that the request itself was at least successful (whereas returning nothing
is not helpful).

* Riak.get_buckets( )
- Takes no arguments, and returns a promise of a list of the
buckets Riak knows about.

* Riak.put_tuple( bucket, tuple, key )
- Riak is very helpful in that it will provide you a key for the things you would
store. So while in order to store something you must provide a bucket and the
thing you would store (the tuple), the key argument is optional. If you supply
a key, that will be provided as Riak for the tuple you have asked to store.
User-supplied keys are useful for key filters,
if hierarchically-named keys is something you want.
If you have omitted a key for storing the tuple, you will be returned a promise
for the key that Riak has provided.

* Riak.del_tuple( bucket, key )
- Should you wish to remove a tuple from your Riak, you must specify a bucket and
a key. Returns what Riak returns; in the case you have tried to remove a tuple
Riak doesn't know about, Riak will return an Error.

author
====

@janearc, jane@cpan.org