Merge pull request #261 from koopjs/files-jsdoc

lib/Files: catch `new` omission, add jsdoc

CHANGELOG.md

@@ -4,6 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 ### Fixed
+* catch omission of `new` keyword for `koop.Files`
 * Gracefully handle malformed esri geoms in geojson conversion
 * Revert Windows command line escaping, it was done improperly
 

lib/Files.js

@@ -3,16 +3,39 @@ var fs = require('fs')
 var child = require('child_process')
 var mkdirp = require('mkdirp')
 
+/**
+ * constructor for interacting with s3 or local disk storage
+ *
+ * @param {object} options - log (koop.Logger instance), config (koop config)
+ */
 var Files = function (options) {
+  // catch omission of `new` keyword
+  if (!(this instanceof Files)) {
+    return new Files(options)
+  }
+
+  /** @type {koop.Logger} logger instance */
   var log = options.log
+
+  /** @type {object} koop configuration */
   var config = options.config || {}
 
+  /** @type {string} local data directory */
   this.localDir = config.data_dir || false
+
+  /** @type {string} s3 bucket name */
   this.s3Bucket = (config.s3) ? config.s3.bucket : false
 
-  if (this.s3Bucket) this.s3 = new AWS.S3()
+  /** @type {AWS.S3} s3 connection instance */
+  this.s3 = this.s3bucket ? new AWS.S3() : false
 
-  // returns the path to the file locally or on s3
+  /**
+   * returns the path to the file locally or on s3
+   *
+   * @param  {string}   subdir - s3 bucket or local fs subdirectory
+   * @param  {string}   name - s3 file key or local file name
+   * @param  {function} callback - error, path string
+   */
   this.path = function (subdir, name, callback) {
     var self = this
     if (this.s3) {
@@ -43,7 +66,15 @@ var Files = function (options) {
     }
   }
 
-  // returns a boolean whether the file exists on s3 or local storage
+  /**
+   * returns a boolean if the file exists on s3 or local storage
+   * TODO: dedup identical logic from Files.path
+   * TODO: callback signature is very wrong on this one
+   *
+   * @param  {string}   subdir - s3 bucket or local fs subdirectory
+   * @param  {string}   name - s3 file key or local file name
+   * @param  {function} callback - A BOOLEAN?, path string
+   */
   this.exists = function (subdir, name, callback) {
     var self = this
     if (this.s3) {
@@ -80,7 +111,14 @@ var Files = function (options) {
     }
   }
 
-  // reads a file to either s3 or local fs
+  /**
+   * reads a file to either s3 or local fs
+   * TODO: clean up callback signature
+   *
+   * @param  {string}   subdir - s3 bucket or local fs subdirectory
+   * @param  {string}   name - s3 file key or local file name
+   * @param  {function} callback - error, data (string)
+   */
   this.read = function (subdir, name, callback) {
     if (this.s3) {
       var params = {
@@ -98,7 +136,14 @@ var Files = function (options) {
     }
   }
 
-  // writes a file to either s3 or local fs
+  /**
+   * writes a file to either s3 or local fs
+   *
+   * @param  {string}   subdir - s3 bucket or local fs subdirectory
+   * @param  {string}   name - s3 file key or local file name
+   * @param  {string}   data - file data
+   * @param  {function} callback - error
+   */
   this.write = function (subdir, name, data, callback) {
     var self = this
     if (this.s3) {
@@ -119,7 +164,13 @@ var Files = function (options) {
     }
   }
 
-  // removes a file to either s3 or local fs
+  /**
+   * removes a file from either s3 or local fs
+   *
+   * @param  {string}   subdir - s3 bucket or local fs subdirectory
+   * @param  {string}   name - s3 file key or local file name
+   * @param  {function} callback - error
+   */
   this.remove = function (subdir, name, callback) {
     var self = this
     if (this.s3) {
@@ -138,6 +189,12 @@ var Files = function (options) {
     }
   }
 
+  /**
+   * remove a directory from s3 or local fs
+   *
+   * @param  {string}   dir - any directory path
+   * @param  {Function} callback - error
+   */
   this.removeDir = function (dir, callback) {
     var self = this
     if (this.s3) {
@@ -171,10 +228,22 @@ var Files = function (options) {
     }
   }
 
+  /**
+   * remove a bucket from s3
+   *
+   * @param  {object}   params - options for s3.deleteBucket method
+   * @param  {Function} callback - error
+   */
   this.removeBucket = function (params, callback) {
     this.s3.deleteBucket(params, callback)
   }
 
+  /**
+   * remove a local directory
+   *
+   * @param  {string}   dir - any directory path
+   * @param  {Function} callback - error
+   */
   this.removeLocalDir = function (dir, callback) {
     var rootDir = [[this.localDir, dir].join('/')]
     var args = rootDir