kyoto-client

<!DOCTYPE HTML> <html lang="en" class"no-js"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=640" /> <title>kyoto-client - Kyoto Tycoon client for node.js</title> <link rel="stylesheet" type="text/css" href="/screen.css" media="screen" /> <link rel="stylesheet" type="text/css" href="/highlight.css" media="screen" /> <meta name="generator" content="nanoc 3.1.6" /> <meta name="author" content="Wesley Moore" /> <script type="text/javascript"> var _gaq = _gaq || []; _gaq.push(['_setAccount', 'UA-199609-7']); _gaq.push(['_trackPageview']); (function() { var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); })(); </script> <script src="/modernizr-1.6.min.js" type="text/javascript" charset="utf-8"></script> <script src="/raphael-min.js" type="text/javascript" charset="utf-8"></script> <script src="/app.js" type="text/javascript" charset="utf-8"></script> </head> <body> <header> <h1><a href="/">kyoto-client</a> v0.4.0</h1> <nav> <li><a href="#intro">Introduction</a></li> <li><a href="#install">Installation</a></li> <li><a href="#developement">Development</a></li> <li><a href="#licence">Licence</a></li> <li><a href="https://github.com/wezm/kyoto-client" class="git">Source git</a></li> <li><a href="https://github.com/wezm/kyoto-client/issues">Bug Tracker</a></li> </nav> <h2><a href="#api">API</a></h2> <h3><a href="#db">DB</a></h3> <nav> <li><a href="#new">constructor</a></li> <li><a href="#open">open</a></li> <li><a href="#close">close</a></li> <li><a href="#defaultDatabase">defaultDatabase</a></li> <li><a href="#close">close</a></li> <li><a href="#echo">echo</a></li> <li><a href="#report">report</a></li> <li><a href="#play_script" class="not-implemented">playScript</a></li> <li><a href="#tune_replication" class="not-implemented">tuneReplication</a></li> <li><a href="#status">status</a></li> <li><a href="#clear">clear</a></li> <li><a href="#synchronize" class="not-implemented">synchronize</a></li> <li><a href="#set">set</a></li> <li><a href="#add">add</a></li> <li><a href="#replace">replace</a></li> <li><a href="#append">append</a></li> <li><a href="#increment">increment</a></li> <li><a href="#increment_double">incrementDouble</a></li> <li><a href="#cas">cas</a></li> <li><a href="#remove">remove</a></li> <li><a href="#get">get</a></li> <li><a href="#exists">exists</a></li> <li><a href="#set_bulk">setBulk</a></li> <li><a href="#remove_bulk">removeBulk</a></li> <li><a href="#get_bulk">getBulk</a></li> <li><a href="#vacuum" class="not-implemented">vacuum</a></li> <li><a href="#match_prefix">matchPrefix</a></li> <li><a href="#match_regex">matchRegex</a></li> <li><a href="#get_cursor">getCursor</a></li> </nav> <h3><a href="#cursor" class="class">Cursor</a></h3> <nav> <li><a href="#cur_jump">jump</a></li> <li><a href="#cur_jump_back">jumpBack</a></li> <li><a href="#cur_step">step</a></li> <li><a href="#cur_step_back">stepBack</a></li> <li><a href="#cur_set_value">setValue</a></li> <li><a href="#cur_remove">remove</a></li> <li><a href="#cur_get_key">getKey</a></li> <li><a href="#cur_get_value">getValue</a></li> <li><a href="#cur_get">get</a></li> <li><a href="#cur_delete">delete</a></li> <li><a href="#cur_each">each</a></li> </nav> <h2><a href="#related">Related Projects</a></h2> <nav> <li><a href="#connect-kyoto">connect-kyoto</a></li> </nav> <h2><a href="#changelog">Changelog</a></h2> <nav> <li><a href="#0.2.0">0.2.0</a></li> <li><a href="#0.1.1">0.1.1</a></li> <li><a href="#0.1.0">0.1.0</a></li> </nav> </header> <section id="main"> <h1> kyoto-client – Kyoto Tycoon client for node.js</h1> <a name="intro"></a> <h2>Introduction</h2> kyoto-client is a <a href="http://nodejs.org/">node.js</a> module that acts as a client to a <a href="http://fallabs.com/kyototycoon/">Kyoto Tycoon</a> server. Kyoto Tycoon is the server component of <a href="http://fallabs.com/kyotocabinet/">Kyoto Cabinet</a>, a fast, efficient key-value store developed by <a href="http://fallabs.com/">FAL labs</a>. Records can be stored on disk or in memory using a hash table or B+ tree. <a name="install"></a> <h2>Installation</h2> Installation via <a href="http://npmjs.org/">npm</a> is recommended: <pre><code>npm install kyoto-client </code></pre> <a name="development"></a> <h2>Development</h2> kyoto-client is implemented in <a href="http://jashkenas.github.com/coffee-script/">CoffeeScript</a> and uses <a href="https://github.com/caolan/nodeunit">nodeunit</a> for testing. Both are available via npm as <code>coffee-script</code> and <code>nodeunit</code> respectfully. It is developed against the current stable node.js version. The primary documentation for the project is its website, the source of which is also included here. The website is built with <a href="http://nanoc.stoneship.org/">nanoc</a>. To get setup for making documentation changes you’ll need to install nanoc and some other RubyGems: <ul> <li>From the <a href="https://github.com/wezm/kyoto-client/tree/master/doc">doc</a> directory run <code>bundle install</code> (assumes you have previously installed <a href="http://gembundler.com/">bundler</a>).</li> <li>Start the nanoc autocompiler with <code>bundle exec nanoc aco</code> and navigate to <a href="http://localhost:3000/">http://localhost:3000/</a>.</li> </ul>Contributions are welcome and should maintain the existing coding style and be accompanied by tests and documentation. Bugs and desired features are tracked in the <a href="https://github.com/wezm/kyoto-client/issues">issue tracker</a>. The tests can be run via <code>cake test</code>. <a name="licence"></a> <h2>Licence</h2> kyoto-client is licenced under the BSD licence. Refer to the <a href="https://github.com/wezm/kyoto-client/blob/master/LICENSE">LICENCE</a> in the repository for the full details. <a name="api"></a> <h2>API</h2> <a name="db"></a> <h3>DB</h3> The DB class is the primary interface to a Kyoto Tycoon database. <a name="new"></a> <h4>◆ constructor <code>new(defaultDatabase)</code> </h4> Constructs and returns a new DB object. <ul> <li> <code>defaultDatabase</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – The default Kyoto Tycoon database to operate upon when not expicitly specified in a procedure. See also <a href="#defaultDatabase">defaultDatabase</a>.</li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">var kt = require('kyoto-client'); var db = new kt.Db(); // With default database var db = new kt.Db('default.kct'); </code></pre> <a name="open"></a> <h4>◆ open <code>open(hostname='localhost', port=1978)</code> </h4> Open a connection to the database. Returns the Db object. <ul> <li> <code>hostname</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The hostname of the database.</li> <li> <code>port</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – The port to connect to on the host.</li> </ul><h5>Examples</h5> <pre class="highlight"><code class="language-js">db.open(); // on a different host db.open('kyoto.example.com'); </code></pre> <pre class="highlight"><code class="language-js">var kyoto = require('kyoto-client'); // Chained with new var db = new kyoto.Db().open('example.com', 1978); </code></pre> <a name="close"></a> <h4>◆ close <code>close(callback)</code> </h4> Close the connection to the database. Internally kyoto-client uses a persistent connection to the database to make requests faster. However to prevent your node application from hanging you must call <code>db.close</code> when you are done so that this persistent connection is closed. <ul> <li> <code>callback(error)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.close(function(error) { // Connection is now closed. The db can't be used anymore. }); </code></pre> <a name="defaultDatabase"></a> <h4>◆ defaultDatabase <code>defaultDatabase([database])</code> </h4> Set or get the default database. A Tokyo Tycoon server can host multiple databases. Requests can be directed at a particular database by name or number. E.g. <code>'users.kct'</code> or <code>1</code>. For procedures that accept a database option the value of defaultDatabase will be used if the option isn’t specified. <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – database to make default. If not specified the current value for the default database is returned.</li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">// Set the default database db.defaultDatabase('example.kct'); // Retrieve the current default database value db.defaultDatabase(); </code></pre> <a name="echo"></a> <h4>◆ echo <code>echo(input, callback)</code> </h4> Echo back the input data as the output data <ul> <li> <code>input</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Arbitrary key-value pairs</li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.echo({test: "Value"}, function(error, output) { // output -> {test: "Value"} }); </code></pre> <a name="report"></a> <h4>◆ report <code>report(callback)</code> </h4> Get a report on the server. <ul> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.report(function(error, output) { /* output -> { conf_kc_features: '(atomic)(zlib)' , conf_kc_version: '1.2.30 (7.1)' , conf_kt_features: '(kqueue)(lua)' , conf_kt_version: '0.9.19 (1.25)' , conf_os_name: 'Mac OS X' , db_0: 'count=2 size=400128 path=tests.kct' , db_total_count: '2' , db_total_size: '400128' , serv_conn: '1' , serv_task: '0' , sys_mem_peak: '2777088' , sys_mem_rss: '2777088' , sys_mem_size: '2777088' , sys_proc_id: '70687' , sys_ru_stime: '73.651796' , sys_ru_utime: '90.519024' , sys_time: '351491.752587' } */ }); </code></pre> <a name="play_script"></a> <h4>◆ playScript</h4> Call a procedure of the script language (<a href="http://www.lua.org/">Lua</a>) extension. Not yet implemented. <a name="tune_replication"></a> <h4>◆ tuneReplication</h4> Configure the replication configuration. Not yet implemented. <a name="status"></a> <h4>◆ status <code>status([options], callback)</code> </h4> Get miscellaneous status information about a database. <ul> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>test.kct</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.status(function(error, output) { /* output -> { apow: '8' , bnum: '65536' , chksum: '188' , count: '2' , cusage: '66' , dfunit: '0' , first: '1' , flags: '1' , fmtver: '5' , fpow: '10' , frgcnt: '0' , icnt: '0' , ktcapcnt: '-1' , ktcapsiz: '-1' , ktopts: '0' , last: '1' , lcnt: '1' , librev: '1' , libver: '7' , msiz: '67108864' , opts: '0' , path: 'tests.kct' , pccap: '67108864' , pnum: '2' , psiz: '8192' , rcomp: 'lexical' , realsize: '400128' , realtype: '49' , recovered: '0' , reorganized: '0' , root: '1' , size: '400128' , trimmed: '0' , type: '49' } */ }); // For a specific database db.status({database: "users.kct"}, function(error, output) { // output contains status info for the users database }); </code></pre> <a name="clear"></a> <h4>◆ clear <code>clear([options], callback)</code> </h4> Remove all records from the database. <ul> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.clear(function(error, output) { // output -> {} }); // Clear a specific database db.clear({database: "test.kct"}, function(error, output) { // output -> {} }); </code></pre> <a name="synchronize"></a> <h4>◆ synchronize</h4> Synchronize updated contents with the file and the device Not yet implemented. <a name="set"></a> <h4>◆ set <code>set(key, value, [options], callback)</code> </h4> Set value of a record. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>value</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The value of the record</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> <li> <code>expiry</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date">Date</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – Set the expiry time of the record. When a date, this value will be when the record expires. When a number the record will expire in the the value specified seconds from now.</li> </ul> </li> <li> <code>callback(error)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.set('test', "Value", function(error) { }); // Set a record in a specific database db.set('test', "Value", {database: "test.kct"}, function(error) { // error -> undefined }); // Set the record to expire in one minute db.set('test', "Value", {expiry: 60}, function(error) { }); // Set the record to expire on 1 Jan 2020 var expires = new Date("1 Jan 2020"); db.set('test', "Value", {expiry: expires}, function(error) { }); </code></pre> <a name="add"></a> <h4>◆ add <code>add(key, value, [options], callback)</code> </h4> Set value of a record. Returns an error if the record already exists. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>value</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The value of the record</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.add('test', "Value", function(error, output) { // error -> undefined }); // when value already exists db.add('test', "Value", function(error, output) { db.add('test', "Value", function(error, output) { // error -> Error("Record exists") // output -> { ERROR: 'DB: 6: record duplication: record duplication' } }); }); </code></pre> <a name="replace"></a> <h4>◆ replace <code>replace(key, value, [options], callback)</code> </h4> Replace the value of a record. Returns an error if the record does not exist. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>value</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The value of the record</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.set('test', "Test", function(error, output) { db.replace('test', "Value", function(error, output) { // error -> undefined // output -> {} }); }); // when the record doesn't exist db.replace('test', "Value", function(error, output) { // error -> Error("Record does not exist") // output -> { ERROR: 'DB: 7: no record: no record' } }); </code></pre> <a name="append"></a> <h4>◆ append <code>append(key, value, [options], callback)</code> </h4> Append to the value of a record. Sets the record if it does not exist. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>value</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The value to append to the record</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.set('test', "Test", function(error, output) { db.append('test', " Value", function(error, output) { // error -> undefined // output -> {} db.get('test', function(error, value) { // value -> 'Test Value' }) }); }); // when the record doesn't exist db.append('test', "Value", function(error, output) { // error -> Error("Record does not exist") // output -> {} db.get('test', function(error, value) { // value -> 'Value' }) }); </code></pre> <a name="increment"></a> <h4>◆ increment <code>increment(key, num, [options], callback)</code> </h4> Increment the integer value of a compatible record. Sets the record if it does not exist. Note: It appears that Kyoto Tycoon only allows records that were created with <code>increment</code> to be incremented. Attempts to use this procedure on records set by other means results in an error (Kyoto Tycoon 0.9.29 (2.1) on Mac OS X (Kyoto Cabinet 1.2.39)). <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>num</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – The amount to increment the record by. Should be a positive or negative integer.</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Result from the server <ul> <li> <code>num</code> – the new value of the record</li> </ul> </li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.increment('count', 1, function(error, output) { // error -> undefined // output -> { num: '1' } db.increment('count', 1, function(error, output) { // error -> undefined // output -> { num: '2' } }); }); // incrementing an incompatible record db.set('incompatible', "1", function(error, output) { db.increment('incompatible', 1, function(error, output) { // error -> Error("The existing record was not compatible") // output -> { ERROR: 'DB: 8: logical inconsistency: logical inconsistency' } }); }); </code></pre> <a name="increment_double"></a> <h4>◆ incrementDouble <code>incrementDouble(key, num, [options], callback)</code> </h4> Increment the double (floating point) value of a compatible record. Sets the record if it does not exist. See note about compatible values in <a href="#increment">increment</a>. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>num</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – The amount to increment the record by. Can be positive or negative.</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Result from the server <ul> <li> <code>num</code> – the new value of the record</li> </ul> </li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">db.incrementDouble('count', 1.5, function(error, output) { // error -> undefined // output -> { num: '1.500000' } db.incrementDouble('count', -0.25, function(error, output) { // error -> undefined // output -> { num: '1.250000' } }); }); // incrementing an incompatible record db.set('incompatible', "1", function(error, output) { db.incrementDouble('incompatible', 1, function(error, output) { // error -> Error("The existing record was not compatible") // output -> { ERROR: 'DB: 8: logical inconsistency: logical inconsistency' } }); }); </code></pre> <a name="cas"></a> <h4>◆ cas <code>cas(key, oval, nval, [options], callback)</code> </h4> Performs a compare-and-swap operation. The value is only updated if the assumed existing value matches. <ul> <li> <code>key</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> – The key of the record</li> <li> <code>oval</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The assumed old value. Set to <code>null</code> if the record does not currently have a value.</li> <li> <code>nval</code> – <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="http://nodejs.org/docs/v0.2.6/api.html#buffers-2">Buffer</a> – The new value. Set to <code>null</code> to remove the record.</li> <li> <code>options</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Options hash <ul> <li> <code>database</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String">String</a> or <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Number">Number</a> – A database name or index. For example: <code>'test.kct'</code> or <code>1</code>.</li> </ul> </li> <li> <code>callback(error, output)</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Function">Function</a> – Callback function <ul> <li> <code>error</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error">Error</a> – Set if an error occurs, otherwise <code>undefined</code> </li> <li> <code>output</code> <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object">Object</a> – Key-value pairs</li> </ul> </li> </ul><h5>Example</h5> <pre class="highlight"><code class="language-js">// sets the new value when the old value matches db.set('test', 'old', function() { db.cas('test', 'old', 'new', function(error, output) { db.get('test', function(error, value) { // value -> 'new' }); }); }); // doesn't set the new value when the old value differs db.set('test', 'old', function() { db.cas('test', 'not old', 'new', function(error, output) { db.get('test', function(error, value) { // value -> 'old' }); }); }); // removes the record when the new value is null db.set('test'<span clas