diff --git a/lib/kvao/expire.js b/lib/kvao/expire.js index 6ac6b669..b7546f93 100644 --- a/lib/kvao/expire.js +++ b/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 {Number} ttl - * @param {Object} options - * @callback cb - * @param {Error} error + * @param {String} key Key to use when searching the database. + * @param {Number} ttl TTL in ms to set for the key. + * @options {Object} options + * @callback {Function} callback + * @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; }; - diff --git a/lib/kvao/get.js b/lib/kvao/get.js index 33908112..e844e1f4 100644 --- a/lib/kvao/get.js +++ b/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 - * @callback cb - * @param {Error} error - * @param {*} value + * @param {String} key Key to use when searching the database. + * @options {Object} options + * @callback {Function} callback + * @param {Error} err Error object. + * @param {*} result Value associated with the given key. + * @promise * * @header KVAO.get(key, cb) */ diff --git a/lib/kvao/iterate-keys.js b/lib/kvao/iterate-keys.js index 28c5e9da..224d28e4 100644 --- a/lib/kvao/iterate-keys.js +++ b/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: - * - `match` - glob string to use to filter returned keys, e.g. 'userid.*' - * All connectors are required to support `*` and `?`. - * They may also support additional special characters that are specific - * to the backing store. - * + * @param {String} filter.match Glob string to use to filter returned + * keys (i.e. `userid.*`). All connectors are required to support `*` and + * `?`. They may also support additional special characters that are + * specific to the backing database. * @param {Object} options - * - * @returns {AsyncIterator} An object implementing "next(cb) -> Promise" - * function that can be used to iterate all keys. + * @returns {AsyncIterator} An Object implementing `next(cb) -> Promise` + * function that can be used to iterate all keys. * * @header KVAO.iterateKeys(filter) */ diff --git a/lib/kvao/keys.js b/lib/kvao/keys.js index f287ede8..0d9df0ba 100644 --- a/lib/kvao/keys.js +++ b/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** - * Building an in-memory array of all keys may be expensive. - * Consider using `iterateKeys` instead. + * **WARNING**: This method is not suitable for large data sets as all + * key-values pairs are loaded into memory at once. For large data sets, + * use `iterateKeys()` instead. * * @param {Object} filter An optional filter object with the following - * properties: - * - `match` - glob string to use to filter returned keys, e.g. 'userid.*' - * All connectors are required to support `*` and `?`. - * They may also support additional special characters that are specific - * to the backing store. + * @param {String} filter.match Glob string used to filter returned + * keys (i.e. `userid.*`). All connectors are required to support `*` and + * `?`, but may also support additional special characters specific to the + * database. * @param {Object} options - * @callback callback - * @param {Error=} err - * @param {[String]} keys The list of keys. - * + * @callback {Function} callback * @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; }; - diff --git a/lib/kvao/set.js b/lib/kvao/set.js index c3118059..15bd224b 100644 --- a/lib/kvao/set.js +++ b/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 {*} value - * @callback cb - * @param {Error} error + * @param {String} key Key to associate with the given value. + * @param {*} value Value to persist. + * @options {Number|Object} options Optional settings for the key-value + * 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; }; - diff --git a/lib/kvao/ttl.js b/lib/kvao/ttl.js index 5c2d8abf..336ef7ae 100644 --- a/lib/kvao/ttl.js +++ b/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 {Object} options - * @callback cb + * @param {String} key Key to use when searching the database. + * @options {Object} options + * @callback {Function} callback * @param {Error} error - * @param {Number} ttl The remaining TTL for the given key. `undefined` if TTL - * was not initially set. + * @param {Number} ttl Expiration time for the key-value pair. `undefined` if + * TTL was not initially set. + * @promise * * @header KVAO.ttl(key, cb) */