A bunch more jsdoc

- implements suggested fixes by @danroundhill

Author: beaucollins

src/simperium/bucket.js

@@ -2,21 +2,21 @@ import { EventEmitter } from 'events'
 import { inherits } from 'util'
 import { v4 as uuid } from 'uuid';
 
+/**
+ * @callback taskCallback
+ * @param {?Error} - if an error occurred it will be provided, otherwise null
+ * @param {Any} - the result of task
+ */
+
 /**
  * Convenience function to turn a function that uses a callback into a function
  * that returns a Promise.
  *
- * @param {Function} task - function that expects a single callback argument
+ * @param {taskCallback} task - function that expects a single callback argument
  * @returns {Promise} callback wrapped in a promise interface
  */
 const callbackAsPromise = ( task ) => new Promise( ( resolve, reject ) => {
-	task( ( error, result ) => {
-		if ( error ) {
-			reject( error );
-			return;
-		}
-		resolve( result );
-	} );
+	task( ( error, result ) => error ? reject( error ) : resolve( result ) );
 } );
 
 /**
@@ -44,23 +44,99 @@ const deprecateCallback = ( callback, promise ) => {
 	return promise;
 };
 
+/**
+ * A bucket object represents the data stored in Simperium for the given id
+ *
+ * @typedef {Object} BucketObject
+ * @param {String} id - bucket object id
+ * @param {Object} data - object literal of bucket object data stored at the id
+ * @param {?Boolean} isIndexing - used to indicate that the bucket is being indexed
+ */
+
+/**
+ * @callback bucketStoreGetCallback
+ * @param {?Error}
+ * @param {?BucketObject}
+ */
+
+/**
+ * @callback bucketStoreRemoveCallback
+ * @param {?Error}
+ */
+
+/**
+ * @callback bucketStoreFindCallback
+ * @param {?Error}
+ * @param {?BucketObject[]}
+ */
+
+/**
+ * Used by a bucket to store bucket object data.
+ *
+ * @interface BucketStore
+ */
+
+/**
+ * Retrieve a bucket object from the store
+ * @function
+ * @name BucketStore#get
+ * @param {String} id - the bucket object id to fetch
+ * @param {bucketStoreGetCallback} - callback once the object is fetched
+ */
+
+/**
+ * Updates the data for the given object id.
+ *
+ * @function
+ * @name BucketStore#update
+ * @param {String} id - to of object to update
+ * @param {Object} data - data to update the object to
+ * @param {Boolean} isIndexing - indicates the object is being downloaded during an index
+ * @param {bucketStoreGetCallback}
+ */
+
+/**
+ * Deletes the object at id from the datastore.
+ *
+ * @function
+ * @name BucketStore#remove
+ * @param {String} id - object to delete from the bucket
+ * @param {bucketStoreRemoveCallback} - called once the object is deleted
+ */
+
+/**
+ * Fetchs all bucket objects from the datastore.
+ *
+ * @function
+ * @name BucketStore#find
+ * @param {?Object} query - currently undefined
+ * @param {bucketStoreFindCallback} - called with results
+ */
+
 /**
  * Turns existing bucket storage provider callback api into a promise based API
  *
- * @param {Object} store - a bucket storage object
+ * @param {BucketStore} store - a bucket storage object
  * @returns {Object} store api methods that use Promises instead of callbacks
  */
 const promiseAPI = store => ( {
-	get: ( id ) =>
+	get: id =>
 		callbackAsPromise( store.get.bind( store, id ) ),
 	update: ( id, object, isIndexing ) =>
 		callbackAsPromise( store.update.bind( store, id, object, isIndexing ) ),
-	remove: ( id ) =>
+	remove: id =>
 		callbackAsPromise( store.remove.bind( store, id ) ),
-	find: ( query ) =>
+	find: query =>
 		callbackAsPromise( store.find.bind( store, query ) )
 } );
 
+/**
+ * A bucket that syncs data with Simperium.
+ *
+ * @param {String} name - Simperium bucket name
+ * @param {bucketStoreProvider} storeProvider - a factory function that provides a bucket store
+ * @param {Channel} channel - a channel instance used for syncing Simperium data
+ */
 export default function Bucket( name, storeProvider, channel ) {
 	EventEmitter.call( this );
 	this.name = name;
@@ -134,7 +210,7 @@ Bucket.prototype.reload = function() {
  * object ID to represent the object in simperium.
  *
  * @param {Object} object - plain js object literal to be saved/synced
- * @param {Function} callback - runs when object has been saved
+ * @param {?bucketStoreGetCallback} callback - runs when object has been saved
  * @return {Promise<Object>} data stored in the bucket
  */
 Bucket.prototype.add = function( object, callback ) {
@@ -146,7 +222,7 @@ Bucket.prototype.add = function( object, callback ) {
  * Requests the object data stored in the bucket for the given id.
  *
  * @param {String} id - bucket object id
- * @param {Function} callback - with the data stored in the bucket
+ * @param {?bucketStoreGetCallback} callback - with the data stored in the bucket
  * @return {Promise<Object>} the object id, data and indexing status
  */
 Bucket.prototype.get = function( id, callback ) {
@@ -160,7 +236,7 @@ Bucket.prototype.get = function( id, callback ) {
  * @param {Object} data - object literal to replace the object data with
  * @param {Object} [options] - optional settings
  * @param {Boolean} [options.sync=true] - false if object should not be synced with this update
- * @param {Function} callback - executed when object is updated localy
+ * @param {?bucketStoreGetCallback} callback - executed when object is updated localy
  * @returns {Promise<Object>} - update data
  */
 Bucket.prototype.update = function( id, data, options, callback ) {
@@ -182,23 +258,35 @@ Bucket.prototype.update = function( id, data, options, callback ) {
 	return deprecateCallback( callback, task );
 };
 
+/**
+ * @callback bucketHasLocalChanges
+ * @param {?Error}
+ * @param {?Boolean}
+ */
+
 /**
  * Check if the bucket has pending changes that have not yet been synced.
  *
- * @param {Function} [callback] - optional callback to receive response
+ * @param {?bucketHasLocalChanges} callback - optional callback to receive response
  * @returns {Promise<Boolean>} resolves to true if their are still changes to sync
  */
 Bucket.prototype.hasLocalChanges = function( callback ) {
 	return deprecateCallback( callback, this.channel.hasLocalChanges() );
 };
 
+/**
+ * @callback bucketGetVersion
+ * @param {?Error}
+ * @param {Number}
+ */
+
 /**
  * Gets the currently synced version number for the specified object id.
  *
  * A version of `0` indicates that an object has not been added to simperium yet.
  *
  * @param {String} id - object to get the version for
- * @param {Function} [callback] - optional callback
+ * @param {?bucketGetVersionCallback} callback - optional callback
  * @returns {Promise<number>} - resolves to the current synced version
  */
 Bucket.prototype.getVersion = function( id, callback ) {
@@ -210,7 +298,7 @@ Bucket.prototype.getVersion = function( id, callback ) {
  * is locally stored for the object
  *
  * @param {String} id - object to sync
- * @param {Function} [callback] - optional callback
+ * @param {?bucketStoreGetCallback} callback - optional callback
  * @returns {Promise<Object>} - object id, data
  */
 Bucket.prototype.touch = function( id, callback ) {
@@ -224,7 +312,7 @@ Bucket.prototype.touch = function( id, callback ) {
  * Deletes the object from the bucket
  *
  * @param {String} id - object to delete
- * @param {Function} [callback] - optional callback
+ * @param {?bucketStoreRemoveCallback} callback - optional callback
  * @returns {Promise<Void>} - resolves when object has been deleted
  */
 Bucket.prototype.remove = function( id, callback ) {

src/simperium/channel.js

@@ -28,6 +28,7 @@ const internal = {};
  */
 internal.updateChangeVersion = function( cv ) {
 	return this.store.setChangeVersion( cv ).then( () => {
+		// A unit test currently relies on this event, otherwise we can remove it
 		this.emit( 'change-version', cv );
 		return cv;
 	} );
@@ -93,7 +94,6 @@ internal.buildRemoveChange = function( id, ghost ) {
 	this.localQueue.queue( payload );
 };
 
-
 internal.diffAndSend = function( id, object ) {
 	var modify = internal.buildModifyChange.bind( this, id, object );
 	return this.store.get( id ).then( modify );
@@ -266,21 +266,106 @@ internal.indexingComplete = function() {
 }
 
 /**
- * Maintains syncing state for a simperium bucket.
+ * A ghost represents a version of a bucket object as known by Simperium
+ *
+ * Generally a client will keep the last known ghost stored locally for efficient
+ * diffing and patching of Simperium change operations.
+ *
+ * @typedef {Object} Ghost
+ * @property {Number} version - the ghost's version
+ * @property {String} key - the simperium bucket object id this ghost is for
+ * @property {Object} data - the data for the given ghost version
+ */
+
+/**
+ * Callback function used by the ghost store to iterate over existing ghosts
  *
- * A bucket uses a channel to lister for updates that come from simperium while
+ * @callback ghostIterator
+ * @param {Ghost} - the current ghost
+ */
+
+/**
+ * A GhostStore provides the store mechanism for ghost data that the Channel
+ * uses to maintain syncing state and producing change operations for
+ * Bucket objects.
+ *
+ * @interface GhostStore
+ */
+
+/**
+ * Retrieve a Ghost for the given bucket object id
+ *
+ * @function
+ * @name GhostStore#get
+ * @param {String} id - bucket object id
+ * @returns {Promise<Ghost>} - the ghost for this object
+ */
+
+/**
+ * Save a ghost in the store.
+ *
+ * @function
+ * @name GhostStore#put
+ * @param {String} id - bucket object id
+ * @param {Number} version - version of ghost data
+ * @param {Object} data - object literal to save as this ghost's data for this version
+ * @returns {Promise<Ghost>} - the ghost for this object
+ */
+
+/**
+ * Delete a Ghost from the store.
+ *
+ * @function
+ * @name GhostStore#remove
+ * @param {String} id - bucket object id
+ * @returns {Promise<Ghost>} - the ghost for this object
+ */
+
+/**
+ * Iterate over existing Ghost objects with the given callback.
+ *
+ * @function
+ * @name GhostStore#eachGhost
+ * @param {ghostIterator} - function to run against each ghost
+ */
+
+/**
+ * Get the current change version (cv) that this channel has synced.
+ *
+ * @function
+ * @name GhostStore#getChangeVersion
+ * @returns {Promise<String>} - the current change version for the bucket
+ */
+
+/**
+ * Set the current change version.
+ *
+ * @function
+ * @name GhostStore#setChangeVersion
+ * @returns {Promise<Void>} - resolves once the change version is saved
+ */
+
+
+/**
+ * Maintains syncing state for a Simperium bucket.
+ *
+ * A bucket uses a channel to listen for updates that come from simperium while
  * sending updates that are made on the client.
  *
  * The channel can handle incoming simperium commands via `handleMessage`. These
- * messages are stripped of their channel number that seperates bucket operations.
+ * messages are stripped of their channel number that separates bucket operations.
  * The `Client` maintains which commands should be routed to which channel.
  *
  * The channel is responsible for creating all change operations and downloading
  * bucket data.
  *
+ * @param {String} appid - Simperium app id, used for authenticating
+ * @param {String} access_token - Simperium user access token
+ * @param {GhostStore} store - data storage for ghost objects
+ * @param {String} name - the name of the bucket on Simperium.com
  */
 export default function Channel( appid, access_token, store, name ) {
-	const channel = this;
+	// Uses an event emitter to handle different Simperium  commands
 	const message = this.message = new EventEmitter();
 
 	this.name = name;
@@ -289,7 +374,7 @@ export default function Channel( appid, access_token, store, name ) {
 	this.store = store;
 	this.access_token = access_token;
 
-	this.session_id = 'node-' + uuid.v4();
+	this.session_id = 'node-' + uuid();
 
 	// These are the simperium bucket commands the channel knows how to handle
 	message.on( 'auth', this.onAuth.bind( this ) );
@@ -317,26 +402,6 @@ export default function Channel( appid, access_token, store, name ) {
 	this.localQueue.on( 'error', internal.handleChangeError.bind( this ) );
 }
 
-/**
- * A ghost represents a version of a bucket object as known by Simperium
- *
- * Generally a client will keep the last known ghost stored locally for efficient
- * diffing and patching of Simperium change operations.
- *
- * @typedef {Object} Ghost
- * @property {Number} version - the ghost's version
- * @property {String} key - the simperium bucket object id this ghost is for
- * @property {Object} data - the data for the given ghost version
- */
-
-/**
- * An object stored is Simperium.
- *
- * @typedef {Object} BucketObject
- * @property {String} id - simperium bucket object id
- * @property {Object} data - object literal data to be stored at the id
- */
-
 inherits( Channel, EventEmitter );
 
 /**
@@ -459,9 +524,8 @@ Channel.prototype.send = function( data ) {
  * Restores a buckets data to what is currently stored in the ghost data.
  */
 Channel.prototype.reload = function() {
-	var emit = this.emit.bind( this, 'update' );
-	this.store.eachGhost( function( ghost ) {
-		emit( ghost.key, ghost.data );
+	this.store.eachGhost( ghost => {
+		this.emit( 'update', ghost.key, ghost.data );
 	} );
 };