Merge branch 'release/1.0.2' into production

docs.json

@@ -1,8 +1,7 @@
 {
   "content": [
     { "title": "LoopBack Storage Service", "depth": 2 },
-    "lib/storage-service.js",    
+    "lib/storage-service.js",
-    { "title": "Storage Handler API", "depth": 3 },
     "lib/storage-handler.js"
   ]
 }

lib/providers/filesystem/index.js

@@ -190,10 +190,10 @@ FileSystemProvider.prototype.download = function (options, cb) {
   }
 };
 
-FileSystemProvider.prototype.getFiles = function (container, download, cb) {
+FileSystemProvider.prototype.getFiles = function (container, options, cb) {
-  if (typeof download === 'function' && !(download instanceof RegExp)) {
+  if (typeof options === 'function' && !(options instanceof RegExp)) {
-    cb = download;
+    cb = options;
-    download = false;
+    options = false;
   }
   var self = this;
   if (!validateName(container, cb)) return;

lib/storage-connector.js

@@ -1,8 +1,10 @@
 var StorageService = require('./storage-service');
 /**
- * Export the initialize method to Loopback data
+ * Initialize the storage service as a connector for LoopBack data sources
- * @param dataSource
+ * @param {DataSource} dataSource DataSource instance
- * @param callback
+ * @prop {Object} settings Connector settings
+ * @callback {Function} callback Callback function
+ * @param {String|Object} err Error string or object
  */
 exports.initialize = function (dataSource, callback) {
   var settings = dataSource.settings || {};

lib/storage-handler.js

@@ -3,11 +3,12 @@ var StringDecoder = require('string_decoder').StringDecoder;
 
 /**
  * Handle multipart/form-data upload to the storage service
- * @param provider The storage service provider
+ * @param {Object} provider The storage service provider
  * @param {Request} req The HTTP request
  * @param {Response} res The HTTP response
  * @param {String} container The container name
- * @param {Function} cb The callback
+ * @callback {Function} cb Callback function
+ * @header storageService.upload(provider, req, res, container, cb) 
  */
 exports.upload = function (provider, req, res, container, cb) {
   var form = new IncomingForm(this.options);
@@ -103,13 +104,14 @@ exports.upload = function (provider, req, res, container, cb) {
 }
 
 /**
- * Handle download from a container/file
+ * Handle download from a container/file.
- * @param provider The storage service provider
+ * @param {Object} provider The storage service provider
  * @param {Request} req The HTTP request
  * @param {Response} res The HTTP response
  * @param {String} container The container name
  * @param {String} file The file name
- * @param {Function} cb The callback
+ * @callback {Function} cb Callback function.
+ * @header storageService.download(provider, req, res, container, file, cb) 
  */
 exports.download = function (provider, req, res, container, file, cb) {
   var reader = provider.download({

lib/storage-service.js

@@ -8,11 +8,17 @@ module.exports = StorageService;
 /**
  * Storage service constructor.  Properties of options object depend on the storage service provider.
  *
- * 
+ * @options {Object} options Options to create a provider; see below.
- * @options {Object} options The options to create a provider; see below;
+ * @prop {String} provider Storage service provider. Must be one of:
- * @prop {Object} connector <!-- What is this? -->
+ * <ul><li>'filesystem' - local file system.</li>
- * @prop {String} provider Use 'filesystem' for local file system.  Other supported values are: 'amazon', 'rackspace', 'azure', and 'openstack'. 
+ * <li>'amazon'</li>
- * @prop {String} root With 'filesystem' provider, the path to the root of storage directory.
+ * <li>'rackspace'</li>
+ * <li>'azure'</li>
+ * <li>'openstack'</li>
+ * </ul>
+ *
+ * Other supported values depend on the provider.
+ * See the [documentation](http://docs.strongloop.com/display/DOC/Storage+service) for more information.
  * @class
  */
 function StorageService(options) {
@@ -25,30 +31,14 @@ function StorageService(options) {
 
 function map(obj) {
   return obj;
-  /*
-   if (!obj || typeof obj !== 'object') {
-   return obj;
-   }
-   var data = {};
-   for (var i in obj) {
-   if (obj.hasOwnProperty(i) && typeof obj[i] !== 'function'
-   && typeof obj[i] !== 'object') {
-   if (i === 'newListener' || i === 'delimiter' || i === 'wildcard') {
-   // Skip properties from the base class
-   continue;
-   }
-   data[i] = obj[i];
-   }
-   }
-   return data;
-   */
 }
 
 /**
  * List all storage service containers.
- * @param {Function} callback Callback function; parameters: err - error message, containers - object holding all containers.
+ * @callback {Function} callback Callback function
+ * @param {Object|String} err Error string or object
+ * @param {Object[]} containers An array of container metadata objects
  */
-
 StorageService.prototype.getContainers = function (cb) {
   this.client.getContainers(function (err, containers) {
     if (err) {
@@ -62,14 +52,13 @@ StorageService.prototype.getContainers = function (cb) {
 };
 
 /**
- * Create a new storage service container.  Other option properties depend on the provider.
+ * Create a new storage service container.
- * 
+ *
- * @options {Object} options The options to create a provider; see below;
+ * @options {Object} options Options to create a container. Option properties depend on the provider.
- * @prop {Object} connector <!-- WHAT IS THIS? -->
+ * @prop {String} name Container name
- * @prop {String} provider Storage service provider. Use 'filesystem' for local file system.  Other supported values are: 'amazon', 'rackspace', 'azure', and 'openstack'. 
+ * @callback {Function} cb Callback function
- * @prop {String} root With 'filesystem' provider, the path to the root of storage directory.
+ * @param {Object|String} err Error string or object
- * @prop {String} 
+ * @param {Object} container Container metadata object
- * @param {Function} callback Callback function.
  */
 
 StorageService.prototype.createContainer = function (options, cb) {
@@ -85,17 +74,20 @@ StorageService.prototype.createContainer = function (options, cb) {
 
 /**
  * Destroy an existing storage service container.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {Function} callback Callback function.
+ * @callback {Function} callback Callback function.
+ * @param {Object|String} err Error string or object
  */
 StorageService.prototype.destroyContainer = function (container, cb) {
   return this.client.destroyContainer(container, cb);
 };
 
 /**
- * Look up a container by name.
+ * Look up a container metadata object by name.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {Function} callback Callback function.
+ * @callback {Function} callback Callback function.
+ * @param {Object|String} err Error string or object
+ * @param {Object} container Container metadata object
  */
 StorageService.prototype.getContainer = function (container, cb) {
   return this.client.getContainer(container, function (err, container) {
@@ -105,10 +97,12 @@ StorageService.prototype.getContainer = function (container, cb) {
 
 /**
  * Get the stream for uploading
- * @param {Object} container Container object.
+ * @param {String} container Container name
- * @param {String} file  IS THIS A FILE?
+ * @param {String} file  File name
- * @options options See below.
+ * @options {Object} [options] Options for uploading
- * @param callback Callback function
+ * @callback callback Callback function
+ * @param {String|Object} err Error string or object
+ * @returns {Stream} Stream for uploading
  */
 StorageService.prototype.uploadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
@@ -128,10 +122,12 @@ StorageService.prototype.uploadStream = function (container, file, options, cb)
 
 /**
  * Get the stream for downloading.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {String} file Path to file.
+ * @param {String} file File name.
- * @options {Object} options See below. <!-- What are the options -->
+ * @options {Object} options Options for downloading
- * @param {Function} callback Callback function
+ * @callback {Function} callback Callback function
+ * @param {String|Object} err Error string or object
+ * @returns {Stream} Stream for downloading
  */
 StorageService.prototype.downloadStream = function (container, file, options, cb) {
   if (!cb && typeof options === 'function') {
@@ -151,12 +147,14 @@ StorageService.prototype.downloadStream = function (container, file, options, cb
 
 /**
  * List all files within the given container.
- * @param {Object} container Container object.
+ * @param {String} container Container name.
- * @param {Function} download 
+ * @param {Object} [options] Options for download
- * @param {Function} callback Callback function
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ * @param {Object[]} files An array of file metadata objects
  */
-StorageService.prototype.getFiles = function (container, download, cb) {
+StorageService.prototype.getFiles = function (container, options, cb) {
-  return this.client.getFiles(container, download, function (err, files) {
+  return this.client.getFiles(container, options, function (err, files) {
     if (err) {
       cb(err, files);
     } else {
@@ -167,20 +165,48 @@ StorageService.prototype.getFiles = function (container, download, cb) {
   });
 };
 
+/**
+ * Look up the metadata object for a file by name
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ * @param {Object} file File metadata object
+ */
 StorageService.prototype.getFile = function (container, file, cb) {
   return this.client.getFile(container, file, function (err, f) {
     return cb(err, map(f));
   });
 };
 
+/**
+ * Remove an existing file
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @callback {Function} cb Callback function
+ * @param {Object|String} err Error string or object
+ */
 StorageService.prototype.removeFile = function (container, file, cb) {
   return this.client.removeFile(container, file, cb);
 };
 
+/**
+ * Upload middleware for the HTTP request/response  <!-- Should this be documented? -->
+ * @param {Request} req Request object
+ * @param {Response} res Response object
+ * @param {Function} cb Callback function
+ */
 StorageService.prototype.upload = function (req, res, cb) {
   return handler.upload(this.client, req, res, req.params.container, cb);
 };
 
+/**
+ * Download middleware <!-- Should this be documented? -->
+ * @param {String} container Container name
+ * @param {String} file File name
+ * @param {Response} res HTTP response
+ * @param {Function} cb Callback function
+ */
 StorageService.prototype.download = function (container, file, res, cb) {
   return handler.download(this.client, null, res, container, file, cb);
 };
@@ -259,4 +285,4 @@ StorageService.prototype.download.accepts = [
   {arg: 'res', type: 'object', 'http': {source: 'res'}}
 ];
 StorageService.prototype.download.http =
-{verb: 'get', path: '/:container/download/:file'};
+{verb: 'get', path: '/:container/download/:file'};

package.json

@@ -1,19 +1,19 @@
 {
   "name": "loopback-storage-service",
   "description": "Loopback Storage Service",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "index.js",
   "scripts": {
     "test": "./node_modules/.bin/mocha --timeout 30000 test/*test.js"
   },
   "dependencies": {
     "pkgcloud": "~0.9.4",
-    "async": "~0.2.10"
+    "async": "~0.2.10",
+    "formidable": "~1.0.14"
   },
   "devDependencies": {
     "express": "~3.4.0",
     "loopback": "1.x.x",
-    "formidable": "~1.0.14",
     "mocha": "~1.18.2",
     "supertest": "~0.10.0",
     "mkdirp": "~0.3.5"