Merge pull request #1093 from strongloop/docs-for-kvao

Add docs for KVAO

lib/kvao/expire.js

@@ -4,15 +4,17 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Set expiration (TTL) for the given key.
+ * Set the TTL (time to live) in ms (milliseconds) for a given key. TTL is the
+ * remaining time before a key-value pair is discarded from the database.
  *
- * @param {String} key
+ * @param {String} key Key to use when searching the database.
- * @param {Number} ttl
+ * @param {Number} ttl TTL in ms to set for the key.
- * @param {Object} options
+ * @options {Object} options
- * @callback cb
+ * @callback {Function} callback
- * @param {Error} error
+ * @param {Error} err Error object.
+ * @promise
  *
- * @header KVAO.get(key, cb)
+ * @header KVAO.expire(key, ttl, cb)
  */
 module.exports = function keyValueExpire(key, ttl, options, callback) {
   if (callback == undefined && typeof options === 'function') {
@@ -30,4 +32,3 @@ module.exports = function keyValueExpire(key, ttl, options, callback) {
   this.getConnector().expire(this.modelName, key, ttl, options, callback);
   return callback.promise;
 };
-

lib/kvao/get.js

@@ -4,12 +4,14 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Get the value stored for the given key.
+ * Return the value associated with a given key.
  *
- * @param {String} key
+ * @param {String} key Key to use when searching the database.
- * @callback cb
+ * @options {Object} options
- * @param {Error} error
+ * @callback {Function} callback
- * @param {*} value
+ * @param {Error} err Error object.
+ * @param {*} result Value associated with the given key.
+ * @promise
  *
  * @header KVAO.get(key, cb)
  */

lib/kvao/iterate-keys.js

@@ -4,19 +4,18 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Asynchronously iterate all keys.
+ * Asynchronously iterate all keys in the database. Similar to `.keys()` but
+ * instead allows for iteration over large data sets without having to load
+ * everything into memory at once.
  *
  * @param {Object} filter An optional filter object with the following
- * properties:
+ * @param {String} filter.match Glob string to use to filter returned
- *  - `match` - glob string to use to filter returned keys, e.g. 'userid.*'
+ *   keys (i.e. `userid.*`). All connectors are required to support `*` and
- *    All connectors are required to support `*` and `?`.
+ *   `?`. They may also support additional special characters that are
- *    They may also support additional special characters that are specific
+ *   specific to the backing database.
- *    to the backing store.
- *
  * @param {Object} options
- *
+ * @returns {AsyncIterator} An Object implementing `next(cb) -> Promise`
- * @returns {AsyncIterator} An object implementing "next(cb) -> Promise"
+ *   function that can be used to iterate all keys.
- * function that can be used to iterate all keys.
  *
  * @header KVAO.iterateKeys(filter)
  */

lib/kvao/keys.js

@@ -4,25 +4,22 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Get all keys.
+ * Return all keys in the database.
  *
- * **NOTE**
+ * **WARNING**: This method is not suitable for large data sets as all
- * Building an in-memory array of all keys may be expensive.
+ * key-values pairs are loaded into memory at once. For large data sets,
- * Consider using `iterateKeys` instead.
+ * use `iterateKeys()` instead.
  *
  * @param {Object} filter An optional filter object with the following
- * properties:
+ * @param {String} filter.match Glob string used to filter returned
- *  - `match` - glob string to use to filter returned keys, e.g. 'userid.*'
+ *   keys (i.e. `userid.*`). All connectors are required to support `*` and
- *    All connectors are required to support `*` and `?`.
+ *   `?`, but may also support additional special characters specific to the
- *    They may also support additional special characters that are specific
+ *   database.
- *    to the backing store.
  * @param {Object} options
- * @callback callback
+ * @callback {Function} callback
- * @param {Error=} err
- * @param {[String]} keys The list of keys.
- *
  * @promise
  *
+ *
  * @header KVAO.keys(filter, callback)
  */
 module.exports = function keyValueKeys(filter, options, callback) {
@@ -57,4 +54,3 @@ module.exports = function keyValueKeys(filter, options, callback) {
 
   return callback.promise;
 };
-

lib/kvao/set.js

@@ -4,12 +4,17 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Set the value for the given key.
+ * Persist a value and associate it with the given key.
  *
- * @param {String} key
+ * @param {String} key Key to associate with the given value.
- * @param {*} value
+ * @param {*} value Value to persist.
- * @callback cb
+ * @options {Number|Object} options Optional settings for the key-value
- * @param {Error} error
+ *   pair. If a Number is provided, it is set as the TTL (time to live) in ms
+ *   (milliseconds) for the key-value pair.
+ * @property {Number} ttl TTL for the key-value pair in ms.
+ * @callback {Function} callback
+ * @param {Error} err Error object.
+ * @promise
  *
  * @header KVAO.set(key, value, cb)
  */
@@ -37,4 +42,3 @@ module.exports = function keyValueSet(key, value, options, callback) {
   this.getConnector().set(this.modelName, key, value, options, callback);
   return callback.promise;
 };
-

lib/kvao/ttl.js

@@ -4,14 +4,16 @@ var assert = require('assert');
 var utils = require('../utils');
 
 /**
- * Get remaining expiration (TTL) for a given key.
+ * Return the TTL (time to live) for a given key. TTL is the remaining time
+ * before a key-value pair is discarded from the database.
  *
- * @param {String} key
+ * @param {String} key Key to use when searching the database.
- * @param {Object} options
+ * @options {Object} options
- * @callback cb
+ * @callback {Function} callback
  * @param {Error} error
- * @param {Number} ttl The remaining TTL for the given key. `undefined` if TTL
+ * @param {Number} ttl Expiration time for the key-value pair. `undefined` if
- *   was not initially set.
+ *   TTL was not initially set.
+ * @promise
  *
  * @header KVAO.ttl(key, cb)
  */